Skip to main content
Version: Matrix OS 4.0 🚧

Code Your Application (Python)

Python apps are the fastest way to build a shareable Matrix OS app. Start with a small standalone app, then keep the API reference open while you add storage, MIDI, HID, or UI.

Ways To Run Python​

Matrix OS Developer Toolkit​

Use Matrix OS Developer Toolkit for the fastest edit-test loop. You can try it at dev.203.io, or run it locally from the Matrix OS repository.

The Python panel is best for short snippets, staged .py files, and quick checks before copying an app to device storage.

Python REPL​

Open the Python app from the application launcher and connect over USB serial. The REPL is best for quick experiments, API exploration, and testing short snippets.

Use a serial terminal on the Matrix OS USB serial port; set the speed to 115200 if the terminal asks. If output, tracebacks, or the prompt are missing, start from Debug Your Application (Python).

Standalone Python App​

A standalone app lives on Matrix OS device storage:

/MatrixOS/Applications/HelloPython/
  AppInfo.json
  main.py
Storage Required

Standalone Python applications require Matrix OS device storage. On Mystrix hardware, insert a microSD card and use USB Storage Mode from Matrix OS settings before copying the app folder.

Create AppInfo.json​

Create /MatrixOS/Applications/HelloPython/AppInfo.json:

{
  "name": "Hello Python",
  "author": "Your Name",
  "color": [0, 255, 255],
  "version": 1,
  "osMinimalVer": [4, 0, 0],
  "appMainFile": "main.py"
}

appMainFile must match the Python file Matrix OS should run when the app launches.

Required fields:

  • name: display name in Matrix OS.
  • author: author or organization.
  • color: app icon color as [R, G, B].
  • version: app version number.
  • osMinimalVer: minimum Matrix OS version.
  • appMainFile: Python file to run.

If Matrix OS cannot parse AppInfo.json, or if appMainFile does not point to an existing file, the app will not appear or will fail to launch.

Create main.py​

Create /MatrixOS/Applications/HelloPython/main.py:

import MatrixOS

LED = MatrixOS.LED
Input = MatrixOS.Input
SYS = MatrixOS.SYS

FUNCTION_KEY = Input.function_key()
COLOR = (0, 255, 255)
cursor = (0, 0)


def draw():
    LED.clear()
    LED.set_xy(cursor[0], cursor[1], COLOR)
    LED.update()


def handle_event(event):
    global cursor

    keypad = event.get("keypad")
    if not keypad:
        return

    if event.get("id") == FUNCTION_KEY and keypad.get("hold"):
        LED.clear()
        LED.update()
        SYS.exit_app()
        return

    point = event.get("point")
    if point and keypad.get("pressed"):
        cursor = point
        draw()


def loop():
    event = Input.get_event()
    while event is not None:
        handle_event(event)
        event = Input.get_event()


draw()
Input.clear()

Expected result:

  • The top-left LED turns cyan when the app launches.
  • Pressing a grid key moves the cyan LED to that key.
  • Holding the function key clears the LEDs and exits the app.

Standalone apps that should keep running define loop(). Matrix OS calls loop() repeatedly after the file has loaded. Let loop() return after it handles the current batch of work; a script with no loop() runs once and then exits.

Try It First​

The quickest path is the hosted toolkit:

  1. Open dev.203.io.
  2. Switch to the Python panel.
  3. Stage main.py, then run it.
  4. Use the input panel to press keys and check the LED panel.
  5. Check the Python output panel for print() output or tracebacks.

To run the same toolkit locally, use the local setup flow first, then start it from the Matrix OS repository:

make DEVICE=MystrixSim setup
make DEVICE=MystrixSim build-dev
make DEVICE=MystrixSim run

Then open the WebUI URL printed by the dev server, usually http://localhost:3000, and use the same Python panel flow.

For automation, the local toolkit JSON-RPC bridge can run snippets with python.runText; see Matrix OS Developer Toolkit.

Deploy To A Device​

  1. Open Matrix OS settings and enable USB Storage Mode.
  2. Create /MatrixOS/Applications/HelloPython/ on device storage.
  3. Copy AppInfo.json and main.py into that folder.
  4. Leave USB Storage Mode.
  5. Restart Matrix OS or reopen the application launcher so the app list refreshes.
  6. Launch Hello Python from the application launcher.

Troubleshooting​

  • App is not visible: check the folder path, AppInfo.json JSON syntax, and appMainFile.
  • App opens then exits: make sure main.py defines loop() for long-running behavior.
  • LEDs do not change: call MatrixOS.LED.update() after drawing.
  • Input feels stuck after leaving a modal UI: call MatrixOS.Input.clear().
  • Storage is not visible: confirm the microSD card is installed and USB Storage Mode is active.
  • Script has an exception: use print() while testing and see Debug Your Application (Python).

Example Apps​

Matrix OS includes Python example apps in the Matrix OS source tree:

These are useful references once you have the minimal app running.

API Reference​

Comments