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:
| Example | Board script | Desktop command |
|---|---|---|
| Sensor stream | mqtt_sensor_stream.py | magpie-read-mqtt |
| User LED RPC | mqtt_rpc_switch.py | magpie-request-mqtt |
| MCP tool | mqtt_mcp_tool.py | magpie-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
- Browse the complete MicroPython examples.
- Use the MicroPython API reference for public constructors, lifecycle, limits, and errors.
- Read the ZeroMQ transport guide or MQTT transport guide.
- Read MCP and AI agents before exposing actions that affect physical systems.