Key States and Transitions

Each key on your keypad can be in one of the five states, as defined by the pl_kp_event_codes constant:

The following diagram shows all key states and possible state transitions:

The red arrows show transitions for when the key is pressed (or remains pressed), while blue arrows show when the key is released (or remains released). Each time a key transitions to the next state, this change is recorded into the keypad event FIFO, which has a depth of eight states.

Enabling the kp. object (setting kp.enabled = 1 — YES) clears the keypad event FIFO and sets each key's state to "longreleased." Press the key long enough and it will go into the "pressed" state. From there, the key can go to "released" and, later, "longreleased" if you let go of that key, or into "longpressed" and then "repeatpressed" if you keep the key pressed.

On matrix keypads, the kp. object will track the state of all keys on the keypad simultaneously, and it is possible to press several keys at once — state transitions will be recorded independently for each key. Binary keypads only allow tracking a single key at a time. This is because a binary keypad is only capable of sending a single key code at any given moment.

The time it takes for a key to transition from one state to another is quantified in 10ms intervals. This is the time period at which the kp. object "pings" the keypad. Each transition's delay, expressed in 10ms intervals, is defined by a dedicated property, so you can decide for yourself what "just now" and "a while ago" mean. The properties are: kp.longpressdelay, kp.longreleasedelay, kp.pressdelay, kp.releasedelay, and kp.repeatdelay. Five available key states, along with adjustable state transition times, allow you to create sophisticated keypad input and get away with having fewer keys.

In addition, the kp.autodisablecodes property allows you to define a list of keys and their state transitions that will cause the keypad to be disabled (kp.enabled = 0 — NO). Keypad auto-disabling may be very useful. For example, if your keypad has keys <0> ~ <9>, <ENTER>, and <CANCEL>, then you can set kp.autodisablecodes to the key code of the <ENTER> key and select _PRESSED as the auto-disabling state. Meaning, as soon as the <ENTER> key is pressed, the keypad will be disabled for further input until you re-enable it by setting kp.enabled = 1 — YES.  

If kp.genkpevent = 1 — YES, then your app gets one on_kp event for each state transition (for each keypad event in the FIFO). If kp.genkpevent = 0 — NO, then you will need to poll for state transitions using the kp.getkey method. More on this in Receiving Keypad Events Through on_kp Events and Receiving Keypad Events Using the kp.getkey Method.

Note that there is an additional state in the diagram. It is called "lockup" and it happens when a key stays pressed for the kp.lockupdelay number of 10ms intervals. Lockups (stuck keys) can happen on a keypad of any type. Capacitive sensor keypads are especially prone to lockups caused by electrostatic discharge (ESD) and moisture (a droplet of water is often indistinguishable from a finger touching on a key). Note that "lockup" is not a key state. Rather, it is a condition of the keypad as a whole. Once the lockup condition is detected, the keypad is disabled (kp.enabled = 0 — NO).