# circremote
A command-line tool for remotely executing CircuitPython code on devices over serial or Web Workflow connections.
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.
## Features
- **Cross-platform support**: Works on Windows, macOS, and Linux
- **Multiple connection types**: Serial ports and CircuitPython Web Workflow
- **Built-in commands**: 100+ sensor and utility commands included
- **Remote commands**: Execute commands from URLs and GitHub repositories
- **Dependency management**: Automatic installation of CircuitPython libraries via circup
- **Configuration**: Device aliases and search paths for easy management
- **Quiet mode**: Suppress output for scripting and automation
## Installation
```bash
pip install circremote
```
## Quick Start
### Serial Connection (macOS/Linux)
```bash
# List files on device
circremote /dev/ttyUSB0 ls /
# Run a sensor command
circremote /dev/ttyUSB0 BME280
```
### Serial Connection (Windows)
```bash
# List files on device
circremote COM3 ls /
# Run a sensor command
circremote COM3 BME280
```
### Web Workflow Connection
```bash
# Connect to device over network
circremote 192.168.1.100 BME280
# With password
circremote -p mypassword 192.168.1.100 BME280
```
### Remote Commands
```bash
# Run command from GitHub
circremote /dev/ttyUSB0 https://github.com/user/repo/tree/main/commands/BME280
# Run Python file from web
circremote /dev/ttyUSB0 https://example.com/my_sensor.py
```
## Configuration
Create `~/.circremote/config.json` (cross-platform):
```json
{
"devices": [
{
"name": "my-device",
"device": "/dev/ttyUSB0",
"friendly_name": "My CircuitPython Board",
"defaults": {
"sda": "board.IO1",
"scl": "board.IO2",
"address": "0x76"
}
}
],
"command_aliases": [
{
"name": "temp",
"command": "BME280"
}
],
"search_paths": [
"/path/to/my/commands"
],
"circup": "/usr/local/bin/circup",
"variable_defaults": {
"sda": "board.SDA",
"scl": "board.SCL",
"address": "0x76"
}
}
```
### Device Defaults
You can set default values for command variables on a per-device basis using the `defaults` field in your device configuration. This is especially useful for I2C pin assignments that are specific to your board layout.
**Variable Resolution Priority:**
1. **Command line values** (highest priority)
2. **Device defaults** (from config.json)
3. **Global variable defaults** (from config.json)
4. **Command defaults** (from info.json)
**Example:**
```bash
# With device defaults, you can run:
circremote my-device BME280
# Instead of having to specify pins every time:
circremote my-device BME280 sda=board.IO1 scl=board.IO2 address=0x76
```
### Global Variable Defaults
You can also set global default values for command variables that apply to all devices and commands using the `variable_defaults` field in your configuration. This is useful for setting common defaults like I2C pins that are consistent across your setup.
**Example:**
```bash
# With global defaults, you can run:
circremote /dev/ttyUSB0 BME280 # Uses global sda/scl defaults
# Device-specific defaults still override global defaults:
circremote my-device BME280 # Uses device defaults, then global defaults
```
Then use device aliases:
```bash
circremote my-device temp
```
## Options
- `-v, --verbose`: Verbose output
- `-q, --quiet`: Quiet mode (suppress output except device output)
- `-y, --yes`: Auto-confirm all prompts
- `-c, --skip-circup`: Skip dependency installation
- `-p, --password`: Web Workflow password
- `-C, --config`: Custom config file path
- `-u, --circup`: Custom circup path
- `-t, --timeout`: Connection timeout (seconds)
## Documentation
- [Usage Guide](doc/usage.md)
- [Command Reference](doc/commands.md)
- [FAQ](doc/faq.md)
## License
MIT License - see [LICENSE](LICENSE) file for details.
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/c7/67/4c92e22593e479fd93452fd099333594c81a17ed761963db55196f6ae520/circremote-0.12.0.tar.gz",
"platform": null,
"description": "# circremote\n\nA command-line tool for remotely executing CircuitPython code on devices over serial or Web Workflow connections.\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\n## Features\n\n- **Cross-platform support**: Works on Windows, macOS, and Linux\n- **Multiple connection types**: Serial ports and CircuitPython Web Workflow\n- **Built-in commands**: 100+ sensor and utility commands included\n- **Remote commands**: Execute commands from URLs and GitHub repositories\n- **Dependency management**: Automatic installation of CircuitPython libraries via circup\n- **Configuration**: Device aliases and search paths for easy management\n- **Quiet mode**: Suppress output for scripting and automation\n\n## Installation\n\n```bash\npip install circremote\n```\n\n## Quick Start\n\n### Serial Connection (macOS/Linux)\n```bash\n# List files on device\ncircremote /dev/ttyUSB0 ls /\n\n# Run a sensor command\ncircremote /dev/ttyUSB0 BME280\n```\n\n### Serial Connection (Windows)\n```bash\n# List files on device\ncircremote COM3 ls /\n\n# Run a sensor command\ncircremote COM3 BME280\n```\n\n### Web Workflow Connection\n```bash\n# Connect to device over network\ncircremote 192.168.1.100 BME280\n\n# With password\ncircremote -p mypassword 192.168.1.100 BME280\n```\n\n### Remote Commands\n```bash\n# Run command from GitHub\ncircremote /dev/ttyUSB0 https://github.com/user/repo/tree/main/commands/BME280\n\n# Run Python file from web\ncircremote /dev/ttyUSB0 https://example.com/my_sensor.py\n```\n\n## Configuration\n\nCreate `~/.circremote/config.json` (cross-platform):\n\n```json\n{\n \"devices\": [\n {\n \"name\": \"my-device\",\n \"device\": \"/dev/ttyUSB0\",\n \"friendly_name\": \"My CircuitPython Board\",\n \"defaults\": {\n \"sda\": \"board.IO1\",\n \"scl\": \"board.IO2\",\n \"address\": \"0x76\"\n }\n }\n ],\n \"command_aliases\": [\n {\n \"name\": \"temp\",\n \"command\": \"BME280\"\n }\n ],\n \"search_paths\": [\n \"/path/to/my/commands\"\n ],\n \"circup\": \"/usr/local/bin/circup\",\n \"variable_defaults\": {\n \"sda\": \"board.SDA\",\n \"scl\": \"board.SCL\",\n \"address\": \"0x76\"\n }\n}\n```\n\n### Device Defaults\n\nYou can set default values for command variables on a per-device basis using the `defaults` field in your device configuration. This is especially useful for I2C pin assignments that are specific to your board layout.\n\n**Variable Resolution Priority:**\n1. **Command line values** (highest priority)\n2. **Device defaults** (from config.json)\n3. **Global variable defaults** (from config.json)\n4. **Command defaults** (from info.json)\n\n**Example:**\n```bash\n# With device defaults, you can run:\ncircremote my-device BME280\n\n# Instead of having to specify pins every time:\ncircremote my-device BME280 sda=board.IO1 scl=board.IO2 address=0x76\n```\n\n### Global Variable Defaults\n\nYou can also set global default values for command variables that apply to all devices and commands using the `variable_defaults` field in your configuration. This is useful for setting common defaults like I2C pins that are consistent across your setup.\n\n**Example:**\n```bash\n# With global defaults, you can run:\ncircremote /dev/ttyUSB0 BME280 # Uses global sda/scl defaults\n\n# Device-specific defaults still override global defaults:\ncircremote my-device BME280 # Uses device defaults, then global defaults\n```\n\nThen use device aliases:\n```bash\ncircremote my-device temp\n```\n\n## Options\n\n- `-v, --verbose`: Verbose output\n- `-q, --quiet`: Quiet mode (suppress output except device output)\n- `-y, --yes`: Auto-confirm all prompts\n- `-c, --skip-circup`: Skip dependency installation\n- `-p, --password`: Web Workflow password\n- `-C, --config`: Custom config file path\n- `-u, --circup`: Custom circup path\n- `-t, --timeout`: Connection timeout (seconds)\n\n## Documentation\n\n- [Usage Guide](doc/usage.md)\n- [Command Reference](doc/commands.md)\n- [FAQ](doc/faq.md)\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "A command-line tool for uploading and running code on CircuitPython devices",
"version": "0.12.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": "e4c3dcde3289304d45055b425ae9a2012d5705febb4087eb443cca5a387ac09c",
"md5": "44656af3f084a86039a260d6cb2e22f9",
"sha256": "c6199125664b1754871737204f97dc43cc68e1e32de3afa18525d7dede073f8c"
},
"downloads": -1,
"filename": "circremote-0.12.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "44656af3f084a86039a260d6cb2e22f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 181513,
"upload_time": "2025-09-03T17:50:15",
"upload_time_iso_8601": "2025-09-03T17:50:15.789041Z",
"url": "https://files.pythonhosted.org/packages/e4/c3/dcde3289304d45055b425ae9a2012d5705febb4087eb443cca5a387ac09c/circremote-0.12.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c7674c92e22593e479fd93452fd099333594c81a17ed761963db55196f6ae520",
"md5": "af690b284a29ce952ff5ab93364609d3",
"sha256": "c22b3eac78ad0f2ff82fef053d50da810eabe268a0a73736b36b17b70695e970"
},
"downloads": -1,
"filename": "circremote-0.12.0.tar.gz",
"has_sig": false,
"md5_digest": "af690b284a29ce952ff5ab93364609d3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 87928,
"upload_time": "2025-09-03T17:50:16",
"upload_time_iso_8601": "2025-09-03T17:50:16.847085Z",
"url": "https://files.pythonhosted.org/packages/c7/67/4c92e22593e479fd93452fd099333594c81a17ed761963db55196f6ae520/circremote-0.12.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 17:50:16",
"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
