ez.keyboard - ezOS Lua API

audio bus crypto display ez global gps keyboard mesh net radio sprite storage synth system wifi

Physical keyboard and trackball input handling

Reads input from the T-Deck's QWERTY keyboard and trackball. Supports key events with modifiers (shift, ctrl, alt, fn), special keys (arrows, enter, escape), and trackball movement/click. The keyboard is polled during the main loop; use read() to get pending key events.

Functions

available() → boolean Check if a key is waiting

ez.keyboard.available() -> boolean

Non-blocking check if a key event is ready to be read. Use in your main loop to poll for input before calling read(). Returns true if at least one key event is queued.

Returns: true if a key is available to read

if ez.keyboard.available() then
local key = ez.keyboard.read()
if key.character then
print("Pressed:", key.character)
elseif key.special then
print("Special key:", key.special)
end
end

get_backlight() → integer Get current keyboard backlight level

ez.keyboard.get_backlight() -> integer

Returns the current keyboard backlight brightness. The T-Deck has illuminated keys for use in low-light conditions.

Returns: Backlight level (0-255, 0 = off, 255 = maximum brightness)

local level = ez.keyboard.get_backlight()
print("Backlight:", level)

get_mode() → string Get current keyboard input mode

ez.keyboard.get_mode() -> string

Returns the keyboard processing mode. "normal" provides translated key events with character values. "raw" gives direct matrix access for custom key handling or chording.

Returns: "normal" or "raw"

print("Keyboard mode:", ez.keyboard.get_mode())

get_pin_states() → string Debug function to get raw GPIO pin states for wake detection

ez.keyboard.get_pin_states() -> string

Returns a string showing the current state of all keyboard and trackball GPIO pins. Useful for debugging hardware issues or wake-from-sleep detection. Values are 1 (pressed/active low) or 0 (released).

Returns: String: "KB_INT=X TB_UP=X TB_DOWN=X TB_LEFT=X TB_RIGHT=X TB_CLICK=X"

print(ez.keyboard.get_pin_states())
-- Output: "KB_INT=0 TB_UP=0 TB_DOWN=0 TB_LEFT=0 TB_RIGHT=0 TB_CLICK=0"

get_raw_matrix_bits() → integer Get full matrix state as 64-bit integer (raw mode)

ez.keyboard.get_raw_matrix_bits() -> integer

Returns the entire keyboard matrix state as a single 64-bit integer. Each column occupies 7 bits. Efficient for comparing entire keyboard state or implementing chord detection.

Returns: 49-bit value (7 cols × 7 rows), bits 0-6 = col 0, bits 7-13 = col 1, etc.

local bits = ez.keyboard.get_raw_matrix_bits()
if bits ~= 0 then
print("Some keys are pressed")
end

get_repeat_delay() → integer Get initial delay before key repeat starts

ez.keyboard.get_repeat_delay() -> integer

Returns how long a key must be held before repeat begins. Default is 400ms. Shorter delays make repeat start faster.

Returns: Delay in milliseconds

print("Repeat delay:", ez.keyboard.get_repeat_delay(), "ms")

get_repeat_enabled() → boolean Check if key repeat is enabled

ez.keyboard.get_repeat_enabled() -> boolean

Returns whether holding a key generates repeated key events. When enabled, holding a key generates events after an initial delay.

Returns: true if key repeat is enabled

if ez.keyboard.get_repeat_enabled() then
print("Key repeat is on")
end

get_repeat_rate() → integer Get key repeat rate (interval between repeats)

ez.keyboard.get_repeat_rate() -> integer

Returns the interval between repeated key events while holding a key. Default is 50ms (20 repeats/second).

Returns: Interval in milliseconds between repeat events

print("Repeat rate:", ez.keyboard.get_repeat_rate(), "ms")

get_trackball_mode() → string Get current trackball input mode

ez.keyboard.get_trackball_mode() -> string

Returns how the trackball is read. "polling" reads on-demand in the main loop. "interrupt" uses hardware interrupts for lower latency.

Returns: "polling" or "interrupt"

print("Trackball mode:", ez.keyboard.get_trackball_mode())

get_trackball_sensitivity() → integer Get trackball sensitivity level

ez.keyboard.get_trackball_sensitivity() -> integer

Returns the current trackball sensitivity. Higher values mean more movement events per physical rotation. Default is 2.

Returns: Sensitivity value (1-10, higher = more sensitive)

local sens = ez.keyboard.get_trackball_sensitivity()
print("Trackball sensitivity:", sens)

has_key_activity() → boolean Check if keyboard interrupt pin indicates key activity

ez.keyboard.has_key_activity() -> boolean

Checks the hardware interrupt pin to detect if any key is pressed. More efficient than reading the full matrix - useful for wake detection or quick polling before more expensive operations.

Returns: true if a key press is detected via hardware interrupt pin

-- Quick check before reading keys
if ez.keyboard.has_key_activity() then
local key = ez.keyboard.read()
end

has_trackball() → boolean Check if device has trackball

ez.keyboard.has_trackball() -> boolean

Checks if the T-Deck has a working trackball. The T-Deck Plus includes a trackball for navigation. Returns false if trackball is not detected or not available on this hardware variant.

Returns: true if trackball is available

if ez.keyboard.has_trackball() then
print("Use trackball to navigate")
else
print("Use arrow keys to navigate")
end

is_alt_held() → boolean Check if Alt is currently held

ez.keyboard.is_alt_held() -> boolean

Returns the current state of the Alt key. Use for alternate character input or keyboard shortcuts.

Returns: true if Alt is currently held down

if ez.keyboard.is_alt_held() then
print("Alt is held")
end

is_ctrl_held() → boolean Check if Ctrl is currently held

ez.keyboard.is_ctrl_held() -> boolean

Returns the current state of the Control key. Use for keyboard shortcuts like Ctrl+C, Ctrl+V.

Returns: true if Ctrl is currently held down

if ez.keyboard.is_ctrl_held() then
print("Ctrl is held")
end

is_fn_held() → boolean Check if Fn is currently held

ez.keyboard.is_fn_held() -> boolean

Returns the current state of the Function key. The Fn key provides access to special characters and function key combinations.

Returns: true if Fn is currently held down

if ez.keyboard.is_fn_held() then
print("Fn is held - function layer active")
end

is_held() → boolean Check whether a character key is currently held down

ez.keyboard.is_held(char) -> boolean

The T-Deck I2C keyboard does not emit release events for character keys, so hold state cannot be inferred from the event stream. is_held() bridges the gap by briefly switching to raw matrix mode. The key's (col,row) position is learned automatically on its first press in the session. Until then, is_held() returns false. Case-insensitive: is_held("w") and is_held("W") both query the same matrix bit.

Parameter	Description
char	Single-character string

Returns: true if the character's key is currently held

if ez.keyboard.is_held("w") then move_forward() end

is_key_pressed() → boolean Check if a specific matrix key is pressed (raw mode)

ez.keyboard.is_key_pressed(col, row) -> boolean

Checks if a specific key at the given matrix position is pressed. Works in raw mode. The T-Deck keyboard is a 5x7 matrix (columns 0-4, rows 0-6).

Parameter	Description
col	Column index (0-4)
row	Row index (0-6)

Returns: true if key at position is pressed

-- Check if specific matrix position is pressed
if ez.keyboard.is_key_pressed(2, 3) then
print("Key at col 2, row 3 is pressed")
end

is_shift_held() → boolean Check if Shift is currently held

ez.keyboard.is_shift_held() -> boolean

Returns the current state of the Shift key. Use for modifier combinations or to check if text should be uppercase.

Returns: true if Shift is currently held down

if ez.keyboard.is_shift_held() then
print("Shift is held")
end

read() → table Read next key event (non-blocking)

ez.keyboard.read() -> table

Returns the next key event from the queue. The returned table contains: character (string or nil), special (special key name or nil), and modifier flags (shift, ctrl, alt, fn, valid). Returns nil if no key waiting.

Returns: Key event table with character, special, shift, ctrl, alt, fn, valid fields, or nil

local key = ez.keyboard.read()
if key then
if key.special == "ENTER" then
submit_form()
elseif key.character and key.ctrl then
-- Ctrl+key shortcut
handle_shortcut(key.character)
end
end

read_blocking() → table Read key with optional timeout (blocking)

ez.keyboard.read_blocking(timeout_ms) -> table

Waits for a key press, blocking until a key is pressed or the timeout expires. Use for simple input prompts or games that need to wait for user input. A timeout of 0 means wait forever.

Parameter	Description
timeout_ms	Timeout in milliseconds (0 = wait forever)

Returns: Key event table, or nil on timeout

print("Press any key to continue...")
local key = ez.keyboard.read_blocking(5000)  -- Wait up to 5 seconds
if key then
print("You pressed a key!")
else
print("Timeout - no key pressed")
end

read_raw_code() → integer|nil Read raw key code byte directly from I2C (no translation)

ez.keyboard.read_raw_code() -> integer|nil

Reads the raw byte from the keyboard I2C controller without any translation. Useful for debugging or implementing custom keyboard handling. Returns nil if no key data is available.

Returns: Raw byte (0x00-0xFF) or nil if no key available

local code = ez.keyboard.read_raw_code()
if code then
print("Raw key code:", string.format("0x%02X", code))
end

read_raw_matrix() → table|nil Read raw key matrix state (only works in raw mode)

ez.keyboard.read_raw_matrix() -> table|nil

Reads the complete keyboard matrix state. Returns 7 bytes, one per column, with each bit representing a row (1 = pressed). Only works when keyboard is in "raw" mode. Use for detecting multiple simultaneous key presses (chording).

Returns: Table of 7 bytes (one per column, 7 bits = rows), or nil on error

ez.keyboard.set_mode("raw")
local matrix = ez.keyboard.read_raw_matrix()
if matrix then
for col, val in ipairs(matrix) do
print("Column", col, "=", string.format("0x%02X", val))
end
end

set_backlight() Set keyboard backlight brightness

ez.keyboard.set_backlight(level)

Sets the keyboard backlight brightness. Higher values use more power. Set to 0 to turn off completely for battery saving.

Parameter	Description
level	Brightness level (0-255, 0 = off, 255 = max)

ez.keyboard.set_backlight(128)  -- Half brightness
ez.keyboard.set_backlight(0)    -- Turn off to save battery

set_mode() → boolean Set keyboard input mode

ez.keyboard.set_mode(mode) -> boolean

Switches between normal and raw keyboard modes. Raw mode provides direct access to the key matrix for custom input handling, chording, or implementing custom keyboard layouts.

Parameter	Description
mode	"normal" for translated keys, "raw" for matrix access

Returns: true if mode was set successfully

ez.keyboard.set_mode("raw")
local matrix = ez.keyboard.read_raw_matrix()
ez.keyboard.set_mode("normal")

set_repeat_delay() Set initial delay before key repeat starts

ez.keyboard.set_repeat_delay(delay_ms)

Sets how long a key must be held before repeat begins. Clamped to 50-2000ms range.

Parameter	Description
delay_ms	Delay in milliseconds (50-2000, default 400)

ez.keyboard.set_repeat_delay(300)  -- Faster repeat start

set_repeat_enabled() Enable or disable key repeat

ez.keyboard.set_repeat_enabled(enabled)

Controls whether holding a key generates repeated key events. Useful for text editing and games. Disable for applications where only single presses should register.

Parameter	Description
enabled	true to enable, false to disable

ez.keyboard.set_repeat_enabled(false)  -- Single press only

set_repeat_rate() Set key repeat rate (interval between repeats)

ez.keyboard.set_repeat_rate(rate_ms)

Sets how fast keys repeat while held. Lower values = faster repeat. Clamped to 10-500ms range.

Parameter	Description
rate_ms	Interval in milliseconds (10-500, default 50)

ez.keyboard.set_repeat_rate(30)  -- Faster repeat

set_trackball_mode() Set trackball input mode

ez.keyboard.set_trackball_mode(mode)

Sets how the trackball is read. "interrupt" mode provides lower latency but uses more CPU. "polling" mode is more power efficient.

Parameter	Description
mode	"polling" or "interrupt"

ez.keyboard.set_trackball_mode("interrupt")  -- Lower latency

set_trackball_sensitivity() Set trackball sensitivity level

ez.keyboard.set_trackball_sensitivity(value)

Adjusts how responsive the trackball is. Higher values generate more movement events for the same physical rotation. Use lower values for precision, higher for faster cursor movement.

Parameter	Description
value	Sensitivity value (1-10, higher = more sensitive)

ez.keyboard.set_trackball_sensitivity(3)  -- Slightly faster