mpy-devices

Query and monitor MicroPython devices - discover connected devices and check firmware versions.

Features

• TUI Interface - Interactive terminal UI for monitoring devices
• Device Discovery - Automatic detection of connected MicroPython devices
• Version Checking - Query firmware version and device information
• Multiple Output Formats - Text, JSON for scripting
• Stable Device Paths - Resolves /dev/serial/by-id/ paths
• Shortcuts - Use a0 instead of /dev/ttyACM0

Installation

Using uv (Recommended)

uv tool install mpy-devices

Using pipx

pipx install mpy-devices

From Source

git clone https://github.com/andrewleech/mpy-devices
cd mpy-devices
uv pip install -e .

Usage

TUI Mode (Default)

Launch the interactive terminal UI:

mpy-devices

Features:

• Auto-discover all connected devices
• Live device information
• Keyboard navigation (↑↓ to navigate, r to refresh, q to quit)
• Device details panel

Check Specific Device

# Check by device path
mpy-devices /dev/ttyACM0

# Check using shortcut
mpy-devices a0

# Check by stable path
mpy-devices /dev/serial/by-id/usb-MicroPython_Board_ABC123-if00

Output:

Querying: /dev/ttyACM0
  TTY Path:    /dev/ttyACM0
  By-ID Path:  /dev/serial/by-id/usb-Raspberry_Pi_Pico_ABC123-if00
  VID:PID:     2e8a:000c
  Device ID:   ABC123
  Machine:     RPI_PICO with RP2040
  System:      rp2
  Release:     1.22.0
  Version:     v1.22.0 on 2024-01-01

List All Devices

mpy-devices --list

Output:

/dev/ttyACM0 ABC123 2e8a:000c Raspberry Pi Pico
/dev/ttyACM1 DEF456 f055:9802 MicroPython pyboard

JSON Output

For scripting and automation:

# List all devices as JSON
mpy-devices --json

# Check specific device as JSON
mpy-devices --json /dev/ttyACM0

Example output:

{
  "device": {
    "path": "/dev/ttyACM0",
    "by_id_path": "/dev/serial/by-id/usb-Raspberry_Pi_Pico_ABC123-if00",
    "serial_number": "ABC123",
    "vid": 11914,
    "pid": 12,
    "vid_pid": "2e8a:000c",
    "manufacturer": "Raspberry Pi",
    "product": "Pico"
  },
  "version": {
    "sysname": "rp2",
    "release": "1.22.0",
    "version": "v1.22.0 on 2024-01-01",
    "machine": "RPI_PICO with RP2040",
    "nodename": "rp2"
  },
  "error": null
}

Device Shortcuts

For convenience, mpy-devices supports mpremote-style shortcuts:

• a0-a9 → /dev/ttyACM0-9 (Linux)
• u0-u9 → /dev/ttyUSB0-9 (Linux)
• c0-c99 → COM0-99 (Windows)

Examples:

mpy-devices a0       # Same as /dev/ttyACM0
mpy-devices u1       # Same as /dev/ttyUSB1
mpy-devices c3       # Same as COM3

Options

-v, --verbose           Show detailed error messages
-t, --timeout SECONDS   Query timeout in seconds (default: 5)
--list                  List all devices (text output)
--json                  Output in JSON format
--version               Show version and exit
--help                  Show help message

Examples

Check All Connected Devices

mpy-devices

Launches TUI showing all devices with their status.

Check Device Before Flashing

mpy-devices /dev/ttyACM0 && flash-firmware.sh /dev/ttyACM0

Monitor Devices in Script

#!/bin/bash
devices=$(mpy-devices --json | jq -r '.[].path')
for dev in $devices; do
    echo "Found device: $dev"
done

Check Device with Custom Timeout

mpy-devices --timeout 10 /dev/ttyACM0

Integration with MicroPython Workflow

Before Running Tests

# Check device and get stable path
mpy-devices a0

# Use the by-id path in test scripts
cd tests
./run-tests.py -t /dev/serial/by-id/usb-Board-ABC123-if00

In CI/CD

# Verify device is connected and running MicroPython
if mpy-devices --json /dev/ttyACM0 | jq -e '.version != null'; then
    echo "Device ready"
    run-tests.sh
else
    echo "Device not ready"
    exit 1
fi

Troubleshooting

No Devices Found

• Check USB cable connection
• Verify device is powered on
• Check permissions (see below)

Permission Denied

On Linux, add your user to the dialout group:

sudo usermod -a -G dialout $USER

Then logout and login again.

Device Not Responding

• Try with longer timeout: mpy-devices --timeout 10 /dev/ttyACM0
• Check if another program is using the device
• Try soft reset: mpremote connect /dev/ttyACM0 soft-reset

mpremote Not Found

Install mpremote:

pip install mpremote

Or if running from MicroPython repository:

cd micropython/tools/mpremote
pip install -e .

Requirements

• Python 3.8+
• pyserial
• mpremote (for device querying)
• click, rich, textual (for UI)

Development

See CLAUDE.md for development documentation.

# Clone repository
git clone https://github.com/andrewleech/mpy-devices
cd mpy-devices

# Install in development mode
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black src/
ruff check src/

License

MIT License - See LICENSE file for details.

Related Projects

• mpremote - MicroPython remote control and filesystem access
• MicroPython - Python for microcontrollers

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Author

Andrew Leech

Changelog

0.1.0 (2024-10-22)

• Initial release
• TUI interface with live device list
• Text and JSON output modes
• Device discovery and version checking
• Shortcut support (a0, u0, c0, etc.)
• Stable /dev/serial/by-id/ path resolution