keypad – Support for scanning keys and key matrices¶
The keypad module provides native support to scan sets of keys or buttons,
connected independently to individual pins,
connected to a shift register,
or connected in a row-and-column matrix.
Available on these boards
- class keypad.Event(key_number: int = 0, pressed: bool = True, timestamp: Optional[int] = None)¶
A key transition event.
Create a key transition event, which reports a key-pressed or key-released transition.
- Parameters
key_number (int) – The key number.
pressed (bool) –
Trueif the key was pressed;Falseif it was released.timestamp (int) – The time in milliseconds that the keypress occurred in the
supervisor.ticks_mstime system. If specified as None, the current value ofsupervisor.ticks_msis used.
- key_number :int¶
The key number.
- pressed :bool¶
Trueif the event represents a key down (pressed) transition. The opposite ofreleased.
- released :bool¶
Trueif the event represents a key up (released) transition. The opposite ofpressed.
- timestamp :int¶
The timestamp.
- class keypad.EventQueue¶
A queue of
Eventobjects, filled by akeypadscanner such asKeysorKeyMatrix.You cannot create an instance of
EventQueuedirectly. Each scanner creates an instance when it is created.- overflowed :bool¶
Trueif an event could not be added to the event queue because it was full. (read-only) Set toFalsebyclear().
- get() Optional[Event]¶
Return the next key transition event. Return
Noneif no events are pending.Note that the queue size is limited; see
max_eventsin the constructor of a scanner such asKeysorKeyMatrix. If a new event arrives when the queue is full, the event is discarded, andoverflowedis set toTrue.
- get_into(event: Event) bool¶
Store the next key transition event in the supplied event, if available, and return
True. If there are no queued events, do not toucheventand returnFalse.The advantage of this method over
get()is that it does not allocate storage. Instead you can reuse an existingEventobject.Note that the queue size is limited; see
max_eventsin the constructor of a scanner such asKeysorKeyMatrix.- Returns
Trueif an event was available and stored,Falseif not.- Return type
- clear() None¶
Clear any queued key transition events. Also sets
overflowedtoFalse.
- class keypad.KeyMatrix(row_pins: Sequence[microcontroller.Pin], column_pins: Sequence[microcontroller.Pin], columns_to_anodes: bool = True, interval: float = 0.02, max_events: int = 64)¶
Manage a 2D matrix of keys with row and column pins.
Create a
Keysobject that will scan the key matrix attached to the given row and column pins. There should not be any external pull-ups or pull-downs on the matrix:KeyMatrixenables internal pull-ups or pull-downs on the pins as necessary.The keys are numbered sequentially from zero. A key number can be computed by
row * len(column_pins) + column.An
EventQueueis created when this object is created and is available in theeventsattribute.- Parameters
row_pins (Sequence[microcontroller.Pin]) – The pins attached to the rows.
column_pins (Sequence[microcontroller.Pin]) – The pins attached to the colums.
columns_to_anodes (bool) – Default
True. If the matrix uses diodes, the diode anodes are typically connected to the column pins, and the cathodes should be connected to the row pins. If your diodes are reversed, setcolumns_to_anodestoFalse.interval (float) – Scan keys no more often than
intervalto allow for debouncing.intervalis in float seconds. The default is 0.020 (20 msecs).max_events (int) – maximum size of
eventsEventQueue: maximum number of key transition events that are saved. Must be >= 1. If a new event arrives when the queue is full, the oldest event is discarded.
- key_count :int¶
The number of keys that are being scanned. (read-only)
- events :EventQueue¶
The
EventQueueassociated with thisKeysobject. (read-only)
- __exit__() None¶
Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.
- reset() None¶
Reset the internal state of the scanner to assume that all keys are now released. Any key that is already pressed at the time of this call will therefore immediately cause a new key-pressed event to occur.
- class keypad.Keys(pins: Sequence[microcontroller.Pin], *, value_when_pressed: bool, pull: bool = True, interval: float = 0.02, max_events: int = 64)¶
Manage a set of independent keys.
Create a
Keysobject that will scan keys attached to the given sequence of pins. Each key is independent and attached to its own pin.An
EventQueueis created when this object is created and is available in theeventsattribute.- Parameters
pins (Sequence[microcontroller.Pin]) – The pins attached to the keys. The key numbers correspond to indices into this sequence.
value_when_pressed (bool) –
Trueif the pin reads high when the key is pressed.Falseif the pin reads low (is grounded) when the key is pressed. All the pins must be connected in the same way.pull (bool) –
Trueif an internal pull-up or pull-down should be enabled on each pin. A pull-up will be used ifvalue_when_pressedisFalse; a pull-down will be used if it isTrue. If an external pull is already provided for all the pins, you can setpulltoFalse. However, enabling an internal pull when an external one is already present is not a problem; it simply uses slightly more current.interval (float) – Scan keys no more often than
intervalto allow for debouncing.intervalis in float seconds. The default is 0.020 (20 msecs).max_events (int) – maximum size of
eventsEventQueue: maximum number of key transition events that are saved. Must be >= 1. If a new event arrives when the queue is full, the oldest event is discarded.
- key_count :int¶
The number of keys that are being scanned. (read-only)
- events :EventQueue¶
The
EventQueueassociated with thisKeysobject. (read-only)
- __exit__() None¶
Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.
- class keypad.ShiftRegisterKeys(*, clock: microcontroller.Pin, data: microcontroller.Pin, latch: microcontroller.Pin, value_to_latch: bool = True, key_count: int, value_when_pressed: bool, interval: float = 0.02, max_events: int = 64)¶
Manage a set of keys attached to an incoming shift register.
Create a
Keysobject that will scan keys attached to a parallel-in serial-out shift register like the 74HC165 or CD4021. Note that you may chain shift registers to load in as many values as you need.Key number 0 is the first (or more properly, the zero-th) bit read. In the 74HC165, this bit is labeled
Q7. Key number 1 will be the value ofQ6, etc.An
EventQueueis created when this object is created and is available in theeventsattribute.- Parameters
clock (microcontroller.Pin) – The shift register clock pin. The shift register should clock on a low-to-high transition.
data (microcontroller.Pin) – the incoming shift register data pin
latch (microcontroller.Pin) – Pin used to latch parallel data going into the shift register.
value_to_latch (bool) – Pin state to latch data being read.
Trueif the data is latched whenlatchgoes highFalseif the data is latched whenlatchgoes low. The default isTrue, which is how the 74HC165 operates. The CD4021 latch is the opposite. Once the data is latched, it will be shifted out by toggling the clock pin.key_count (int) – number of data lines to clock in
value_when_pressed (bool) –
Trueif the pin reads high when the key is pressed.Falseif the pin reads low (is grounded) when the key is pressed.interval (float) – Scan keys no more often than
intervalto allow for debouncing.intervalis in float seconds. The default is 0.020 (20 msecs).max_events (int) – maximum size of
eventsEventQueue: maximum number of key transition events that are saved. Must be >= 1. If a new event arrives when the queue is full, the oldest event is discarded.
- key_count :int¶
The number of keys that are being scanned. (read-only)
- events :EventQueue¶
The
EventQueueassociated with thisKeysobject. (read-only)
- __exit__() None¶
Automatically deinitializes when exiting a context. See Lifetime and ContextManagers for more info.