Preparing the Keypad for Operation

This topic lays out the steps required to set up the kp. object. All preparations should be made with the keypad disabled (kp.enabled = 0 — NO) or this setup won't work.

Selecting the Operating Mode

Start by selecting the type of the keypad you are using — matrix or binary. This is done through the kp.mode property.

If your keypad is of the binary type, additionally set the kp.idlecode property.

Mapping Scan and Return Lines

Next, define the list of scan and return lines. Scan lines are only necessary for matrix keypads. Return lines are required both for matrix and binary keypads.

One great feature of the kp. object is that you can assign ("map") any I/O line of your device to be a scan or return line. I/O lines serving as scan or return lines don't even have to be "together" (have consecutive numbers). Scan lines are assigned through the kp.scanlinesmapping property, return lines — through the kp.returnlinesmapping property.

On platforms with explicit output buffer control, each scan line must be configured as an output and each return line as an input.

Limitations:

You can't have more than eight scan lines and eight return lines
You must have at least one return line
Any given I/O line can only serve as a scan or return line, not both

For example, here is how you select lines 24, 20, and 27 to serve as scan lines and 28, 21, and 25 to serve as return lines:

Tibbo BASIC

							kp.scanlinesmapping="24,20,27"
kp.returnlinesmapping="28,21,25"

'this is only necessary on devices with explicit output buffer control
io.num=PL_IO_NUM_24
io.enabled=YES
io.num=PL_IO_NUM_20_INT4
io.enabled=YES
io.num=PL_IO_NUM_27
io.enabled=YES
						

Line numbers are platform-dependent. They come from pl_io_num enum — see its declaration in the "Platform-Dependent Constants" section of your device's platform documentation (for example, the EM1000's is here). The pl_io_num enum is a list of constants like "PL_IO_NUM_24" — you cannot just drop "PL_IO_NUM_24" into kp.scanlinesmapping (or kp.returnlinesmapping). The correct way is to write "24" or use str(PL_IO_NUM_24). So, another way to do the above setup would look like this:

Tibbo BASIC

							kp.scanlinesmapping=str(PL_IO_NUM_24)+","+str(PL_IO_NUM_20_INT4)+","+str(PL_IO_NUM_27)
kp.returnlinesmapping=str(PL_IO_NUM_28)+","+str(PL_IO_NUM_21_INT5)+","+str(PL_IO_NUM_25)
...
s=kp.returnlinesmapping 's will be equal to '28,21,25'
						

Defining State Transition Delays

Your third step is to set proper delay times for key state transitions. Five different properties are responsible for that: kp.pressdelay, kp.longpressdelay, kp.repeatdelay, kp.releasedelay, and kp.longreleasedelay. Each property sets the transition delay time in 10ms increments. Setting a property to 0 means that the corresponding transition will never happen. Note that the maximum value for each property is 254. All five properties already have sensible default values, so you only need to change them if you don't like what we have chosen for you:

Tibbo BASIC

							kp.pressdelay=4 '40ms (4 successive keypad scans) to confirm that the key is pressed
							kp.longpressdelay=150 '1.5 seconds
							kp.repeatdelay=0 'we do not want auto-repeat to work
							kp.releasedelay=4 '40ms
							kp.longreleasedelay=200 '2 seconds
						

Final Steps

If you want the keypad to be disabled when certain keys transition into certain states, use the kp.autodisablecodes property. In the example below, the kp. object is set to be disabled when a key with key code 49 is _LONGPRESSED or the key with key code 20 is _PRESSED.

Also, you can choose whether you want to receive your keypad events through the on_kp event handler (default) or through the kp.getkey method.

Finally, enable the keypad, and you are all set.

Tibbo BASIC

							kp.autodisablecodes=str(PL_KP_EVENT_LONGPRESSED)+",49,"+str(PL_KP_EVENT_PRESSED)+",20" 'see the next topic for the explanation of key codes
kp.genkpevent=NO 'polling mode selected
kp.enabled=YES
						