# `circremote`
A command-line tool for uploading and running Python code on CircuitPython devices via serial or Web Workflow websocket connections, with support for dependency management and sensor libraries.
A few examples:
```
# simple I2C scanner on locally connected device
circremote /dev/ttyUSB0 scan-i2c
# show the contents of settings.toml on a Web Workflow device
circremote 192.168.1.23:8080 -p PASSWORD cat settings.toml
# run Adafruit's I2C scanner on a device with the nickname feather-s3
circremote feather-s3 https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/I2C_Scanners/circuitpython/code.py
# help
circremote -h
```
## Overview
`circremote` is a utility program that allows you to easily upload and run code on a CircuitPython device without disturbing code.py.
It works with devices connected over USB and over a network connection to devices that support and are configured for the Web Workflow.
It includes a library of small programs ("commands") which perform utility functions like scanning the I2C bus or cleaning up undesired files from the internal flash filesystem, as well as example programs that work with a variety of sensors and other devices.
It can run the commands included with it, your own commands from anywhere in the filesystem, and commands that it loads over HTTP/HTTPS. It can easily execute example programs from Github.
Commands can include a `requirements.txt` file and `circup` will automatically be run to install them. Commands can also take arguments, so you can (for instance) pass the I2C SDA and SCL pins to a command, or specify the address of a sensor.
For your convenience you can also configure aliases for devices and commands.
It can also pull code from a web server, so you can run Adafruit example code directly from Github if you want.
It does not currently support Microsoft Windows. I do not have a Windows machine and have no way to test it with Windows. I understand that a lot of people use Windows and that the lack of support means that a lot of people who might benefit from `circremote` won't be able to use it. While I'm happy to spend some time and resources on continuing to develop `circremote` and support users, I don't have the time, energy or desire to bring up a new platform and get it working on it. If a motivated co-maintainer comes along who'd like to get `circremote` working properly with Windows and then support it, I'd be happy to bring someone like that onto the project.
- [About `circremote`](doc/about.md)
- [Install](doc/install.md)
- [Usage](doc/usage.md)
- [Commands](doc/commands.md)
- [Configuration](doc/configuration.md)
- [Contributing](doc/contributing.md)
- [Development](doc/development.md)
- [Testing](doc/testing.md)
- [Release](doc/release.md)
- [FAQ](doc/faq.md)
## Rough Edges
There are still some rough edges in dealing with program termination and resuming `code.py` (the "double exit" mode). Programs can continue running indefinitely, which may or may not be desired. Many commands are untested because I either don't have the hardware or haven't had the time to get to them.
## Getting Help
If you run into problems, first - if you're using Microsoft Windows, this is currently unsupported and we cannot help you.
Please review the [FAQ](doc/faq.md).
If you're unable to resolve the problem with `circremote` file an issue here on Github.
General CircuitPython help is available at [#help-with-circuitpython on Adafruit's Discord server[(https://discord.com/channels/327254708534116352/537365702651150357) and at [r/circuitpython](https://www.reddit.com/r/circuitpython/) on Reddit.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- CircuitPython community for the excellent ecosystem
- Adafruit for the sensor libraries
- Python community for, well... Python
Raw data
{
"_id": null,
"home_page": null,
"name": "circremote",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "John Romkey <58883+romkey@users.noreply.github.com>",
"keywords": "circuitpython, microcontroller, serial, websocket, webworkflow, esp32, sensors",
"author": null,
"author_email": "John Romkey <58883+romkey@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/9c/14/513ce4f06996c9fa0179fed30426a846950e1a94f9f480efb0218375632f/circremote-0.11.0.tar.gz",
"platform": null,
"description": "# `circremote`\n\nA command-line tool for uploading and running Python code on CircuitPython devices via serial or Web Workflow websocket connections, with support for dependency management and sensor libraries.\n\nA few examples:\n```\n# simple I2C scanner on locally connected device\ncircremote /dev/ttyUSB0 scan-i2c\n\n# show the contents of settings.toml on a Web Workflow device\ncircremote 192.168.1.23:8080 -p PASSWORD cat settings.toml\n\n# run Adafruit's I2C scanner on a device with the nickname feather-s3\ncircremote feather-s3 https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/I2C_Scanners/circuitpython/code.py\n\n# help\ncircremote -h\n```\n\n## Overview\n\n`circremote` is a utility program that allows you to easily upload and run code on a CircuitPython device without disturbing code.py.\n\nIt works with devices connected over USB and over a network connection to devices that support and are configured for the Web Workflow.\n\nIt includes a library of small programs (\"commands\") which perform utility functions like scanning the I2C bus or cleaning up undesired files from the internal flash filesystem, as well as example programs that work with a variety of sensors and other devices.\n\nIt can run the commands included with it, your own commands from anywhere in the filesystem, and commands that it loads over HTTP/HTTPS. It can easily execute example programs from Github.\n\nCommands can include a `requirements.txt` file and `circup` will automatically be run to install them. Commands can also take arguments, so you can (for instance) pass the I2C SDA and SCL pins to a command, or specify the address of a sensor.\n\nFor your convenience you can also configure aliases for devices and commands.\nIt can also pull code from a web server, so you can run Adafruit example code directly from Github if you want.\n\nIt does not currently support Microsoft Windows. I do not have a Windows machine and have no way to test it with Windows. I understand that a lot of people use Windows and that the lack of support means that a lot of people who might benefit from `circremote` won't be able to use it. While I'm happy to spend some time and resources on continuing to develop `circremote` and support users, I don't have the time, energy or desire to bring up a new platform and get it working on it. If a motivated co-maintainer comes along who'd like to get `circremote` working properly with Windows and then support it, I'd be happy to bring someone like that onto the project.\n\n- [About `circremote`](doc/about.md)\n- [Install](doc/install.md)\n- [Usage](doc/usage.md)\n- [Commands](doc/commands.md)\n- [Configuration](doc/configuration.md)\n- [Contributing](doc/contributing.md)\n- [Development](doc/development.md)\n- [Testing](doc/testing.md)\n- [Release](doc/release.md)\n- [FAQ](doc/faq.md)\n\n## Rough Edges\n\nThere are still some rough edges in dealing with program termination and resuming `code.py` (the \"double exit\" mode). Programs can continue running indefinitely, which may or may not be desired. Many commands are untested because I either don't have the hardware or haven't had the time to get to them.\n\n## Getting Help\n\nIf you run into problems, first - if you're using Microsoft Windows, this is currently unsupported and we cannot help you.\n\nPlease review the [FAQ](doc/faq.md).\n\nIf you're unable to resolve the problem with `circremote` file an issue here on Github.\n\nGeneral CircuitPython help is available at [#help-with-circuitpython on Adafruit's Discord server[(https://discord.com/channels/327254708534116352/537365702651150357) and at [r/circuitpython](https://www.reddit.com/r/circuitpython/) on Reddit.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- CircuitPython community for the excellent ecosystem\n- Adafruit for the sensor libraries\n- Python community for, well... Python\n",
"bugtrack_url": null,
"license": null,
"summary": "A command-line tool for uploading and running code on CircuitPython devices",
"version": "0.11.0",
"project_urls": {
"Bug Tracker": "https://github.com/romkey/circremote/issues",
"Changelog": "https://github.com/romkey/circremote/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/romkey/circremote#readme",
"Homepage": "https://github.com/romkey/circremote",
"Repository": "https://github.com/romkey/circremote"
},
"split_keywords": [
"circuitpython",
" microcontroller",
" serial",
" websocket",
" webworkflow",
" esp32",
" sensors"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "43449ba4894488090ff7ec7fa93285bd435e0d3d402e40d567160142cc6074b0",
"md5": "60a281f5f8949d2b235401df77813ddb",
"sha256": "f788afa736365dea97dba7056c6cb12e6ff4576c4f71787a766f0406c1912073"
},
"downloads": -1,
"filename": "circremote-0.11.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "60a281f5f8949d2b235401df77813ddb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 156509,
"upload_time": "2025-08-12T04:59:34",
"upload_time_iso_8601": "2025-08-12T04:59:34.627710Z",
"url": "https://files.pythonhosted.org/packages/43/44/9ba4894488090ff7ec7fa93285bd435e0d3d402e40d567160142cc6074b0/circremote-0.11.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9c14513ce4f06996c9fa0179fed30426a846950e1a94f9f480efb0218375632f",
"md5": "7480574acdc3887515adfc3aa12ae851",
"sha256": "cac4d376f23a9791deae3f571b47a9cb0546b0276877ecb6b490a114ca5e06d9"
},
"downloads": -1,
"filename": "circremote-0.11.0.tar.gz",
"has_sig": false,
"md5_digest": "7480574acdc3887515adfc3aa12ae851",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 73273,
"upload_time": "2025-08-12T04:59:35",
"upload_time_iso_8601": "2025-08-12T04:59:35.938495Z",
"url": "https://files.pythonhosted.org/packages/9c/14/513ce4f06996c9fa0179fed30426a846950e1a94f9f480efb0218375632f/circremote-0.11.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 04:59:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "romkey",
"github_project": "circremote",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "pyserial",
"specs": [
[
">=",
"3.5"
]
]
},
{
"name": "websocket-client",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.25.0"
]
]
},
{
"name": "circup",
"specs": [
[
">=",
"2.2.2"
]
]
}
],
"tox": true,
"lcname": "circremote"
}
JSON
