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 the explicit output buffer control, each scan line must be configured as output, each return line — as input.


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

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 **


'this is only necessary on devices with explicit output buffer control

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, EM1000's is here). The pl_io_num 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 **

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 (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