Matrix OS Developer Toolkit

Matrix OS Developer Toolkit is the Matrix OS 4.0 software-in-the-loop runtime for development and testing. It builds Matrix OS to WebAssembly, runs it in a browser-hosted Mystrix-like device, and exposes developer tools for input, LED, MIDI, HID, serial, storage, Python, and system inspection.

Matrix OS 4.0 beta

Matrix OS Developer Toolkit is a beta developer tool. It is useful for API work, UI iteration, Python testing, and automation, but it is not a full replacement for testing on hardware.

Try It Online

You can try Matrix OS Developer Toolkit at dev.203.io.

The online toolkit is the fastest way to inspect the UI and try the simulator. Use a local run when you need the WebSocket JSON-RPC bridge, local builds, or automation scripts.

Local Requirements

• Emscripten toolchain with emcmake and emcc
• Node.js and npm
• CMake
• A shell that can run the MatrixOS Makefile

On Windows, the toolkit helper can discover common Emscripten install locations such as C:\emsdk, C:\Program Files\emsdk, %USERPROFILE%\emsdk, and %USERPROFILE%\Documents\emsdk.

Setup

Clone the Matrix OS repository, then run:

make DEVICE=MystrixSim setup

This configures the WebAssembly build and installs the WebUI dependencies.

Build

make DEVICE=MystrixSim build-dev

The build produces the toolkit runtime JavaScript and WebAssembly files, validates the runtime package, and writes a local firmware package for the WebUI.

Release automation publishes Matrix OS Developer Toolkit runtime bundles as .msfw files.

Run

make DEVICE=MystrixSim run

This starts the Matrix OS Developer Toolkit WebUI development server.

WebUI Tools

The Matrix OS Developer Toolkit WebUI includes panels for:

• firmware source and runtime package loading
• live input injection and state monitoring
• LED framebuffer inspection
• MIDI monitor and test send
• HID and RawHID inspection
• serial I/O
• storage, NVS, and virtual filesystem inspection
• Python REPL and uploaded .py script execution
• system build metadata and runtime status
• runtime logs

Firmware Packages

Matrix OS Developer Toolkit uses .msfw runtime packages. A package contains the built MatrixOSHost.js and MatrixOSHost.wasm runtime assets plus metadata used by the WebUI.

The WebUI can load local builds, packaged release assets, or proxied release assets depending on how it is served.

JSON-RPC Bridge

When the WebUI runs in the node-backed dev server, it exposes a local WebSocket JSON-RPC bridge for automation. Use it for repeatable tests and scripted checks against the browser-hosted runtime.

Static hosted builds do not expose this bridge. Keep the WebUI tab open while an external RPC client is connected, because the browser-hosted runtime is the active bridge target. If the tab is closed, external RPC clients receive a runtime-unavailable error.

Endpoint

The default WebSocket endpoint is:

ws://localhost:4002

You can override the port with MATRIXOS_RPC_PORT.

Message Shape

Request:

{
  "jsonrpc": "2.0",
  "id": "example-1",
  "method": "python.status",
  "params": {}
}

Success response:

{
  "jsonrpc": "2.0",
  "id": "example-1",
  "result": {
    "available": true,
    "active": false,
    "mode": "idle"
  }
}

Error response:

{
  "jsonrpc": "2.0",
  "id": "example-1",
  "error": {
    "code": 4001,
    "message": "Invalid params"
  }
}

Common bridge error codes:

Code	Meaning
4001	Invalid params
4002	Unknown target
4003	Unsupported capability
4004	Timeout
5001	Internal error

Common Methods

Example RPC calls exposed by the WebUI include:

• bridge.status
• session.status
• session.ping
• session.reset
• runtime.getState
• input.list
• input.execute
• input.releaseAll
• led.getFrame
• midi.listPorts
• midi.send
• log.get
• python.status
• python.runText
• python.stageFiles
• python.runStaged
• python.getOutput
• python.stop

Python Methods

Method	Params	Result
python.status	{}	{ available, active, mode, debug }
python.runText	{ name, text, timeoutMs?, idleTimeoutMs? }	{ ok, name, size, mode, completed }
python.stageFiles	{ files: [{ name, text }], entry? }	{ ok, count, entry }
python.runStaged	{ timeoutMs?, idleTimeoutMs? }	{ ok, mode, completed }
python.getOutput	{ last?, mode? }	{ entries: [{ timestamp, mode, text }] }
python.stop	{ timeoutMs? }	{ ok, mode }

python.runText is best for short smoke tests. Use python.stageFiles and python.runStaged for a complete app folder with helper modules.

Check Bridge Status

From the Matrix OS repository:

node Devices/MystrixSim/WebUI/tools/rpc-test.mjs --ws ws://localhost:4002 --method bridge.status

Run A Python Snippet

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\")"}'

Read the output:

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

Run Python Smoke Tests

The WebUI includes smoke scripts for Python runtime checks:

npm --prefix Devices/MystrixSim/WebUI run smoke:python -- --ws ws://localhost:4002 --suite core

Use the full example suite when you are validating local Matrix OS changes. The example suite can fail because of an example app or simulator issue even when your own snippet runs correctly.

Python Testing

The Python panel can enter the built-in Python REPL or stage a .py file and run it as a Python app. This is useful for checking Matrix OS Python APIs before copying an app to device storage.

Limitations

• Hardware timing is simulated.
• USB, HID, MIDI, serial, storage, and input behavior are routed through host-side shims.
• Some panels expose planned or partial beta functionality.
• Always verify hardware-dependent behavior on a real Mystrix device before release.