| Name | mpy-devices JSON |
| Version |
1.1.0
JSON |
| download |
| home_page | None |
| Summary | Query and monitor MicroPython devices - discover connected devices and check firmware versions |
| upload_time | 2025-10-22 09:15:09 |
| maintainer | None |
| docs_url | None |
| author | Andrew Leech |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
devices
firmware
micropython
serial
usb
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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)
```bash
uv tool install mpy-devices
```
### Using pipx
```bash
pipx install mpy-devices
```
### From Source
```bash
git clone https://github.com/andrewleech/mpy-devices
cd mpy-devices
uv pip install -e .
```
## Usage
### TUI Mode (Default)
Launch the interactive terminal UI:
```bash
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
```bash
# 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
```bash
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:
```bash
# List all devices as JSON
mpy-devices --json
# Check specific device as JSON
mpy-devices --json /dev/ttyACM0
```
Example output:
```json
{
"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:
```bash
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
```bash
mpy-devices
```
Launches TUI showing all devices with their status.
### Check Device Before Flashing
```bash
mpy-devices /dev/ttyACM0 && flash-firmware.sh /dev/ttyACM0
```
### Monitor Devices in Script
```bash
#!/bin/bash
devices=$(mpy-devices --json | jq -r '.[].path')
for dev in $devices; do
echo "Found device: $dev"
done
```
### Check Device with Custom Timeout
```bash
mpy-devices --timeout 10 /dev/ttyACM0
```
## Integration with MicroPython Workflow
### Before Running Tests
```bash
# 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
```bash
# 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:
```bash
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:
```bash
pip install mpremote
```
Or if running from MicroPython repository:
```bash
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](CLAUDE.md) for development documentation.
```bash
# 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](https://docs.micropython.org/en/latest/reference/mpremote.html) - MicroPython remote control and filesystem access
- [MicroPython](https://micropython.org/) - 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
Raw data
{
"_id": null,
"home_page": null,
"name": "mpy-devices",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "devices, firmware, micropython, serial, usb",
"author": "Andrew Leech",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ef/2a/ca66047babc9504bd387d953b57e7c11eece99ba1a6d7048651dc8c52013/mpy_devices-1.1.0.tar.gz",
"platform": null,
"description": "# mpy-devices\n\nQuery and monitor MicroPython devices - discover connected devices and check firmware versions.\n\n## Features\n\n- **TUI Interface** - Interactive terminal UI for monitoring devices\n- **Device Discovery** - Automatic detection of connected MicroPython devices\n- **Version Checking** - Query firmware version and device information\n- **Multiple Output Formats** - Text, JSON for scripting\n- **Stable Device Paths** - Resolves `/dev/serial/by-id/` paths\n- **Shortcuts** - Use `a0` instead of `/dev/ttyACM0`\n\n## Installation\n\n### Using uv (Recommended)\n\n```bash\nuv tool install mpy-devices\n```\n\n### Using pipx\n\n```bash\npipx install mpy-devices\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/andrewleech/mpy-devices\ncd mpy-devices\nuv pip install -e .\n```\n\n## Usage\n\n### TUI Mode (Default)\n\nLaunch the interactive terminal UI:\n\n```bash\nmpy-devices\n```\n\nFeatures:\n- Auto-discover all connected devices\n- Live device information\n- Keyboard navigation (`\u2191\u2193` to navigate, `r` to refresh, `q` to quit)\n- Device details panel\n\n### Check Specific Device\n\n```bash\n# Check by device path\nmpy-devices /dev/ttyACM0\n\n# Check using shortcut\nmpy-devices a0\n\n# Check by stable path\nmpy-devices /dev/serial/by-id/usb-MicroPython_Board_ABC123-if00\n```\n\nOutput:\n```\nQuerying: /dev/ttyACM0\n TTY Path: /dev/ttyACM0\n By-ID Path: /dev/serial/by-id/usb-Raspberry_Pi_Pico_ABC123-if00\n VID:PID: 2e8a:000c\n Device ID: ABC123\n Machine: RPI_PICO with RP2040\n System: rp2\n Release: 1.22.0\n Version: v1.22.0 on 2024-01-01\n```\n\n### List All Devices\n\n```bash\nmpy-devices --list\n```\n\nOutput:\n```\n/dev/ttyACM0 ABC123 2e8a:000c Raspberry Pi Pico\n/dev/ttyACM1 DEF456 f055:9802 MicroPython pyboard\n```\n\n### JSON Output\n\nFor scripting and automation:\n\n```bash\n# List all devices as JSON\nmpy-devices --json\n\n# Check specific device as JSON\nmpy-devices --json /dev/ttyACM0\n```\n\nExample output:\n```json\n{\n \"device\": {\n \"path\": \"/dev/ttyACM0\",\n \"by_id_path\": \"/dev/serial/by-id/usb-Raspberry_Pi_Pico_ABC123-if00\",\n \"serial_number\": \"ABC123\",\n \"vid\": 11914,\n \"pid\": 12,\n \"vid_pid\": \"2e8a:000c\",\n \"manufacturer\": \"Raspberry Pi\",\n \"product\": \"Pico\"\n },\n \"version\": {\n \"sysname\": \"rp2\",\n \"release\": \"1.22.0\",\n \"version\": \"v1.22.0 on 2024-01-01\",\n \"machine\": \"RPI_PICO with RP2040\",\n \"nodename\": \"rp2\"\n },\n \"error\": null\n}\n```\n\n## Device Shortcuts\n\nFor convenience, mpy-devices supports mpremote-style shortcuts:\n\n- `a0-a9` \u2192 `/dev/ttyACM0-9` (Linux)\n- `u0-u9` \u2192 `/dev/ttyUSB0-9` (Linux)\n- `c0-c99` \u2192 `COM0-99` (Windows)\n\nExamples:\n```bash\nmpy-devices a0 # Same as /dev/ttyACM0\nmpy-devices u1 # Same as /dev/ttyUSB1\nmpy-devices c3 # Same as COM3\n```\n\n## Options\n\n```\n-v, --verbose Show detailed error messages\n-t, --timeout SECONDS Query timeout in seconds (default: 5)\n--list List all devices (text output)\n--json Output in JSON format\n--version Show version and exit\n--help Show help message\n```\n\n## Examples\n\n### Check All Connected Devices\n\n```bash\nmpy-devices\n```\n\nLaunches TUI showing all devices with their status.\n\n### Check Device Before Flashing\n\n```bash\nmpy-devices /dev/ttyACM0 && flash-firmware.sh /dev/ttyACM0\n```\n\n### Monitor Devices in Script\n\n```bash\n#!/bin/bash\ndevices=$(mpy-devices --json | jq -r '.[].path')\nfor dev in $devices; do\n echo \"Found device: $dev\"\ndone\n```\n\n### Check Device with Custom Timeout\n\n```bash\nmpy-devices --timeout 10 /dev/ttyACM0\n```\n\n## Integration with MicroPython Workflow\n\n### Before Running Tests\n\n```bash\n# Check device and get stable path\nmpy-devices a0\n\n# Use the by-id path in test scripts\ncd tests\n./run-tests.py -t /dev/serial/by-id/usb-Board-ABC123-if00\n```\n\n### In CI/CD\n\n```bash\n# Verify device is connected and running MicroPython\nif mpy-devices --json /dev/ttyACM0 | jq -e '.version != null'; then\n echo \"Device ready\"\n run-tests.sh\nelse\n echo \"Device not ready\"\n exit 1\nfi\n```\n\n## Troubleshooting\n\n### No Devices Found\n\n- Check USB cable connection\n- Verify device is powered on\n- Check permissions (see below)\n\n### Permission Denied\n\nOn Linux, add your user to the `dialout` group:\n\n```bash\nsudo usermod -a -G dialout $USER\n```\n\nThen logout and login again.\n\n### Device Not Responding\n\n- Try with longer timeout: `mpy-devices --timeout 10 /dev/ttyACM0`\n- Check if another program is using the device\n- Try soft reset: `mpremote connect /dev/ttyACM0 soft-reset`\n\n### mpremote Not Found\n\nInstall mpremote:\n\n```bash\npip install mpremote\n```\n\nOr if running from MicroPython repository:\n\n```bash\ncd micropython/tools/mpremote\npip install -e .\n```\n\n## Requirements\n\n- Python 3.8+\n- pyserial\n- mpremote (for device querying)\n- click, rich, textual (for UI)\n\n## Development\n\nSee [CLAUDE.md](CLAUDE.md) for development documentation.\n\n```bash\n# Clone repository\ngit clone https://github.com/andrewleech/mpy-devices\ncd mpy-devices\n\n# Install in development mode\nuv venv\nsource .venv/bin/activate\nuv pip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Format code\nblack src/\nruff check src/\n```\n\n## License\n\nMIT License - See LICENSE file for details.\n\n## Related Projects\n\n- [mpremote](https://docs.micropython.org/en/latest/reference/mpremote.html) - MicroPython remote control and filesystem access\n- [MicroPython](https://micropython.org/) - Python for microcontrollers\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Author\n\nAndrew Leech\n\n## Changelog\n\n### 0.1.0 (2024-10-22)\n\n- Initial release\n- TUI interface with live device list\n- Text and JSON output modes\n- Device discovery and version checking\n- Shortcut support (a0, u0, c0, etc.)\n- Stable /dev/serial/by-id/ path resolution\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Query and monitor MicroPython devices - discover connected devices and check firmware versions",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/andrewleech/mpy-devices",
"Issues": "https://github.com/andrewleech/mpy-devices/issues",
"Repository": "https://github.com/andrewleech/mpy-devices"
},
"split_keywords": [
"devices",
" firmware",
" micropython",
" serial",
" usb"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "42e2f0b047dcc6236d20dc502caf23fdae108e460c08e6c3335b23bdb871cf1a",
"md5": "014823920e852d00af46d291ec9ce1e9",
"sha256": "eb1340cf51996677312868b744540363294fd10aba954f425adde9e3c462855c"
},
"downloads": -1,
"filename": "mpy_devices-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "014823920e852d00af46d291ec9ce1e9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14725,
"upload_time": "2025-10-22T09:15:07",
"upload_time_iso_8601": "2025-10-22T09:15:07.987022Z",
"url": "https://files.pythonhosted.org/packages/42/e2/f0b047dcc6236d20dc502caf23fdae108e460c08e6c3335b23bdb871cf1a/mpy_devices-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ef2aca66047babc9504bd387d953b57e7c11eece99ba1a6d7048651dc8c52013",
"md5": "f6ddf86fe1fa786c075f40429e92e8f6",
"sha256": "05cfc5e061db9b3c668ff6ed71c3f9202ee2fd27270daa53944f4511b73b81dc"
},
"downloads": -1,
"filename": "mpy_devices-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f6ddf86fe1fa786c075f40429e92e8f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 20890,
"upload_time": "2025-10-22T09:15:09",
"upload_time_iso_8601": "2025-10-22T09:15:09.082029Z",
"url": "https://files.pythonhosted.org/packages/ef/2a/ca66047babc9504bd387d953b57e7c11eece99ba1a6d7048651dc8c52013/mpy_devices-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 09:15:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andrewleech",
"github_project": "mpy-devices",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mpy-devices"
}
