Input API

Overview

Python apps use MatrixOS.Input for keypad, touchbar, and future input types.

Data Model

• InputId: a tuple (cluster_id, member_id).
• Point: a tuple (x, y).
• Event and snapshot values are dictionaries.
• Keypad data is stored under the keypad field when the input class is keypad.

Event Dictionary

Event dictionaries returned by get_event() include:

• id: (cluster_id, member_id)
• input_class: numeric input class
• point: (x, y) or None
• keypad: keypad data for keypad inputs

Representative keypad event:

{
    "id": (1, 0),
    "input_class": 1,
    "point": (0, 0),
    "keypad": {
        "state": 2,  # MatrixOS.Input.STATE_PRESSED
        "pressed": True,
        "released": False,
        "hold": False,
        "aftertouch": False,
        "pressure": 65535,
        "velocity": 65535,
    },
}

Keypad dictionaries include:

• state: numeric keypad state.
• pressed: True while the input is in a press event.
• released: True while the input is in a release event.
• hold: True while the input is in a hold event.
• aftertouch: True while the input is in an aftertouch event.
• pressure: current pressure value.
• velocity: press or release velocity value.

pressure and velocity are 16-bit values in the range 0..65535 when the device reports those capabilities.

State Constants

Constant	Meaning
STATE_IDLE	Input is inactive.
STATE_ACTIVATED	Input is active between event edges.
STATE_PRESSED	Press event.
STATE_HOLD	Hold threshold reached.
STATE_AFTERTOUCH	Pressure changed while active.
STATE_RELEASED	Release event.

MatrixOS.Input.get_event

get_event(timeout_ms: int = 0) -> dict | None

Reads the next input event.

Parameters:

• timeout_ms: Maximum time to wait in milliseconds. 0 is non-blocking.

Returns:

• dict | None: Event dictionary, or None when no event is available before the timeout.

---

MatrixOS.Input.clear

clear() -> None

Clears pending input events and suppresses active inputs until the next press.

Use it after leaving a modal UI or after intentionally consuming a key combo.

---

MatrixOS.Input.function_key

function_key() -> InputId

Returns the Matrix OS function key input ID.

Returns:

• InputId: Tuple (cluster_id, member_id).

---

MatrixOS.Input.try_get_point

try_get_point(input_id: InputId) -> tuple[int, int] | None

Maps an input ID to a point when the input has coordinates.

Parameters:

• input_id: Tuple (cluster_id, member_id).

Returns:

• tuple[int, int] | None: Point, or None when the input has no coordinates.

---

MatrixOS.Input.clusters

clusters() -> list[dict]

Returns all input cluster descriptors.

Returns:

• list[dict]: Cluster dictionaries.

Cluster dictionaries include:

• id
• name
• input_class
• input_class_name
• shape
• shape_name
• root_point
• dimension
• input_count
• has_coordinates

---

MatrixOS.Input.get_cluster

get_cluster(cluster: int | str) -> dict | None

Looks up one input cluster by ID or name.

Parameters:

• cluster: Cluster ID or cluster name, such as "Grid" when the device exposes that name.

Returns:

• dict | None: Cluster dictionary, or None when not found.

---

MatrixOS.Input.primary_grid_cluster

primary_grid_cluster() -> dict | None

Returns the primary grid input cluster.

Returns:

• dict | None: Cluster dictionary, or None when no primary grid exists.

---

MatrixOS.Input.get_state

get_state(input_id: InputId) -> dict | None

Reads the current state snapshot for one input.

Parameters:

• input_id: Tuple (cluster_id, member_id).

Returns:

• dict | None: Snapshot dictionary with the same shape as an event dictionary, or None when unavailable.

---

MatrixOS.Input.get_inputs_at

get_inputs_at(point: tuple[int, int]) -> list[InputId]

Returns all input IDs located at a point.

Parameters:

• point: Tuple (x, y).

Returns:

• list[InputId]: Input IDs at that point.

---

MatrixOS.Input.get_input_at

get_input_at(cluster: int | str, point: tuple[int, int]) -> InputId | None

Returns the input ID at a point in a specific cluster.

Parameters:

• cluster: Cluster ID or name.
• point: Tuple (x, y).

Returns:

• InputId | None: Input ID, or None when no input exists at that point.

---

MatrixOS.Input.get_keypad_capabilities

get_keypad_capabilities(cluster: int | str) -> dict | None

Returns keypad capability flags for a cluster.

Parameters:

• cluster: Cluster ID or name.

Returns:

• dict | None: Capability dictionary, or None when the cluster is not found or is not a keypad cluster.

The returned dict includes:

• has_pressure
• has_aftertouch
• has_velocity
• has_position

Event Loop Example

import MatrixOS

def loop():
    # Drain all pending events every loop call so input stays responsive.
    event = MatrixOS.Input.get_event()
    while event is not None:
        keypad = event.get("keypad")
        point = event.get("point")
        if keypad and point and keypad.get("pressed"):
            # Light the LED at the pressed key's coordinate.
            MatrixOS.LED.set_xy(point[0], point[1], (255, 255, 255))
            MatrixOS.LED.update()

        # Keep reading until the event queue is empty.
        event = MatrixOS.Input.get_event()

Common Operations

Task	API
Read the next event	MatrixOS.Input.get_event()
Read state at a point	get_input_at(...) then get_state(...)
Convert a point to an input ID	MatrixOS.Input.get_input_at(cluster, point)
Convert an input ID to a point	MatrixOS.Input.try_get_point(input_id)
Clear pending input	MatrixOS.Input.clear()
Event data	event dict
Keypad data	event["keypad"] or snapshot["keypad"] dict