Debug Your Application (Python)

Python app debugging in Matrix OS usually starts with print() output, then moves to the Matrix OS Developer Toolkit when you need repeatable input, LED, storage, or RPC-driven tests.

Where Output Appears

• In Matrix OS Developer Toolkit, use the Python panel output and runtime logs.
• On hardware, use the Python REPL or app serial output.
• For automation, use the toolkit JSON-RPC bridge and read output with python.getOutput.

Hardware Serial And REPL

1. Open the Python app from the Matrix OS application launcher.
2. Connect the device to the host over USB.
3. Open the Matrix OS USB serial port in a serial terminal.
4. Use 115200 baud if the terminal asks for a speed.
5. Run short statements in the REPL, or launch a standalone Python app and watch the same serial output for print() messages and tracebacks.

The port appears as a normal serial device, such as a COM port on Windows. If several serial ports are present, unplug and reconnect the device to see which port appears.

If the serial port is visible but no Python prompt appears, make sure the Python app is active. If a standalone app exits immediately, check AppInfo.json, top-level exceptions, and whether the app needs a loop() function.

Minimal Debug Pattern

import MatrixOS

print("app start")

MatrixOS.LED.clear()
MatrixOS.LED.set_xy(0, 0, (255, 0, 0))
MatrixOS.LED.update()

print("lit 0,0 red")

Expected result: the app prints both messages and lights the first LED red.

Debug Input

import MatrixOS

print("waiting for one input event")

event = MatrixOS.Input.get_event(5000)
if event is None:
    print("no input event")
else:
    point = event.get("point")
    keypad = event.get("keypad", {})
    print("event id=", event.get("id"))
    print("point=", point)
    print("keypad=", keypad)

Expected result: pressing a key prints the event ID, point, and keypad data. If no event arrives within the timeout, the script prints no input event.

Debug A Short Loop

Keep debug loops bounded while testing from the toolkit so the script can finish and RPC output can be collected.

import MatrixOS

for i in range(20):
    event = MatrixOS.Input.get_event(50)
    if event:
        point = event.get("point")
        keypad = event.get("keypad", {})
        print("input", i, point, keypad)

        if point and keypad.get("pressed"):
            MatrixOS.LED.set_xy(point[0], point[1], (255, 255, 255))
            MatrixOS.LED.update()

print("loop done")

Expected result: the script polls input briefly, prints any events it receives, and exits cleanly.

Debug Storage

import MatrixOS

if MatrixOS.FileSystem.available():
    with open("debug.txt", "w") as f:
        f.write("hello from Matrix OS\n")
    print("wrote debug.txt")
else:
    print("filesystem unavailable")

Expected result: the app either writes debug.txt in the app sandbox or reports that filesystem storage is unavailable.

Common Problems

Symptom	Likely Cause	Check
NameError: MatrixOS	Missing import	Add import MatrixOS at the top.
No LED change	Missing update()	Call MatrixOS.LED.update() after drawing.
No input events	Wrong app/view or no injected input	Use the toolkit input panel or press hardware keys while the Python app is active.
Script never finishes in RPC tests	Infinite loop	Use a bounded loop for smoke tests, then switch to long-running app logic later.
File writes fail	Storage unavailable	Check MatrixOS.FileSystem.available() first.

Toolkit RPC Smoke Test

With Matrix OS Developer Toolkit running and the WebUI tab open, use the JSON-RPC bridge to run a short script:

node Devices/MystrixSim/WebUI/tools/rpc-test.mjs --ws ws://localhost:4002 --method python.runText --params '{"name":"docs_smoke.py","text":"import MatrixOS\nMatrixOS.LED.clear()\nMatrixOS.LED.set_xy(0,0,(255,0,0))\nMatrixOS.LED.update()\nprint(\"ok\")"}'

Then read output:

node Devices/MystrixSim/WebUI/tools/rpc-test.mjs --ws ws://localhost:4002 --method python.getOutput --params '{"last":20}'

If the script starts but prints a traceback, treat it as a docs/example bug first. If the bridge reports that the runtime is unavailable, open or reload the toolkit WebUI tab.