Skip to main content

MicroPython and embedded devices

MAGPIE lets any MicroPython device participate directly in the same system as Python services and C++ robot processes. The default ZMQ transport communicates over TCP without a broker. Install the optional MQTT package when the deployment needs brokered routing, browser access, or easier communication across NAT.

:::info Board-independent

MAGPIE does not identify, whitelist, or depend on any board family. It runs on all MicroPython devices; individual features use only the runtime capabilities and peripherals required by that feature.

:::

Prepare the board​

Install the default package, replacing COM13 with the board's serial port:

python -m pip install mpremote
mpremote connect COM13 mip install github:luxai-qtrobot/magpie-upy

Clone the repository to get the examples, then replace WIFI_SSID and WIFI_PASSWORD in the script you want to run:

git clone https://github.com/luxai-qtrobot/magpie-upy.git
cd magpie-upy
python -m pip install luxai-magpie

The ZMQ examples connect the board to Wi-Fi, bind a direct TCP endpoint, and print the board's IP address. Run the board script and its matching desktop command in separate terminals. Keep these plain ZMQ endpoints on a trusted local network.

Stream sensor data to a desktop​

The sensor example publishes a DictFrame containing a counter and the board's free heap every two seconds:

mpremote connect COM13 run examples/zmq_sensor_stream.py

Read the stream from the desktop, replacing BOARD_IP with the address printed by the board:

magpie-read tcp://DEVICE_IP:5555 magpie-upy/esp32-001/sensor --pretty

This is direct cross-language interoperability: MicroPython and desktop MAGPIE share the ZMQ multipart format, MessagePack representation, frame envelope, and stream API.

Stream JPEG camera frames​

On a MicroPython device whose runtime exposes a camera module, the camera example captures VGA JPEG frames and publishes them without re-encoding. Adapt the camera import and configuration to that runtime.

mpremote connect COM13 run examples/zmq_camera_stream.py

Install the desktop video tools and connect the viewer to the IP address printed by the board:

python -m pip install "luxai-magpie[video]"
magpie-video-viewer tcp://DEVICE_IP:5559 magpie-upy/esp32-001/camera

Each sample is an ImageFrameJpeg carrying the camera's JPEG bytes plus width, height, channel, pixel-format, and normal MAGPIE frame metadata. JPEG size varies with the scene and camera quality, so the example raises the ZMQ max_message_size limit accordingly.

Send a stream to the board​

The reverse example lets the board receive commands or state from a desktop publisher:

mpremote connect COM13 run examples/zmq_stream_reader.py

Publish values to the endpoint printed by the board:

magpie-write tcp://DEVICE_IP:5557 magpie-upy/esp32-001/command "{'action':'ping'}" --rate 1 --loop

The reader uses delivery="latest", so a slow application favors the newest buffered value.

Control a physical output with RPC​

Start the ZMQ service that controls the example board's user LED:

mpremote connect COM13 run examples/zmq_rpc_switch.py

Call it from the desktop:

magpie-request tcp://BOARD_IP:5558 "{'action':'on'}" --pretty
magpie-request tcp://BOARD_IP:5558 "{'action':'off'}" --pretty

The device acknowledges each request before returning its result. Adjust the GPIO and active-high or active-low behavior to match the connected hardware.

Expose an MCP tool from the device​

Run the on-device MCP tool server:

mpremote connect COM13 run examples/zmq_mcp_tool.py

Discover and call its free_memory tool through ordinary MAGPIE RPC:

magpie-request tcp://BOARD_IP:5556 "{'jsonrpc':'2.0','id':1,'method':'tools/list'}" --pretty
magpie-request tcp://BOARD_IP:5556 "{'jsonrpc':'2.0','id':2,'method':'tools/call','params':{'name':'free_memory','arguments':{}}}" --pretty

An agent can call the same tool through a desktop FastMCP client and MAGPIE's McpTransport. The board itself needs no FastMCP runtime, HTTP server, or operating system—it implements the MCP tool contract through McpSchema and ZMQ RPC.

Optional MQTT examples​

Install the MQTT manifest in addition to the default package when the board needs MQTT:

mpremote connect COM13 mip install github:luxai-qtrobot/magpie-upy/package-mqtt.json
python -m pip install "luxai-magpie[mqtt]"

The repository includes equivalent MQTT examples:

ExampleBoard scriptDesktop command
Sensor streammqtt_sensor_stream.pymagpie-read-mqtt
User LED RPCmqtt_rpc_switch.pymagpie-request-mqtt
MCP toolmqtt_mcp_tool.pymagpie-request-mqtt or a FastMCP client

Edit each script's MQTT_CONFIG before running it. A public broker is suitable only for demonstrations; use an authenticated broker and topic ACLs for deployed devices.

Where to go next​