# circuitpython-tool
[](https://badge.fury.io/py/circuitpython-tool)
Links:
- Github: https://github.com/dhrosa/circuitpython-tool
- PyPI: https://pypi.org/project/circuitpython-tool
Installation:
```sh
pip install circuitpython-tool
```
## Overview
`circuitpython-tool` is a command-line utility for conveniently using
CircuitPython devices from the terminal. Especially useful
when multiple devices are connected to the same computer.
Benefits:
- No need to manually mount `CIRCUITPY` drives, or even keep track of where its mounted. You can refer to the device by name instead.
- No need to figure out the name of the serial terminal (e.g. /dev/ttyACM1). You can refer to the device by name instead.
- No need to find the correct CircuitPython version, reset your device while holding BOOTSEL, or drag-and-drop the `.uf2` file into `RPI-RP2`. You can enter the UF2 bootloader with one command, and automatically download and install CircuitPython with another command.
This tool is designed for a workflow where instead of editing files directly on
the CircuitPython device, you edit files on your computer and sync the code over
to the device.
## Usage
## Terminology
- **Query**: `vendor:model:serial` string that specifies one or more connected CircuitPython devices. Each component string is searched for in the respective attribute. Empty strings are allowed in each component of the query. Example queries:
- `::` matches ANY device.
- `Adafruit::` matches any device whose vendor contains the string "Adafruit"
- `:Feather:` matches any device whose model contains the string "Feather"
- `Adafruit:Feather:` matches any device whose vendor contains the string "Adafruit" AND whose model contains the string "Feather"
- **Device**: A CircuitPython device connected over USB. The device shows up as
a removeable drive labeled `CIRCUITPY`. When the term "device" is referred to
in a command-line argument, the device is specified as a query strong as
above. An error is thrown if the given query matches multiple connected
devices.
- **UF2 Device**: A device connected over USB that is in its UF2 bootloader. For
RP2040-based devices, the device shows up as a removable drive labeled
`RPI-RP2`. This is the default state for brand-new RP2040 devices. This is
also the state entered when a device is reset with the BOOTSEL butten held
down. This state can also be entered via the `uf2 enter` command.
## Example Commands
### List devices
List connected CircuitPython devices and their properties:
### Connect to serial terminal
Open serial terminal to connected Raspberry Pi Pico (without needing to find the correct /dev/ttyACM path!):
```sh
circuitpython-tool connect :Pico:
```
### Upload code
Upload code to connected Raspberry Pi Pico everytime the contents of `~/mycode` changes (without needing to manually mount the device!):
```sh
circuitpython-tool upload --dir ~/mycode :Pico:
```
Or to only upload code once and exit:
```sh
circuitpython-tool watch --dir ~/mycode :Pico: --mode=single-shot
```
### Mount device
Mount Raspberry Pi Pico (if needed) and print the path to the mountpoint:
```sh
circuitpython-tool mount :Pico:
```
### Install CircuitPython
Automatically download and install the correct version of CircuitPython onto a connected Raspberry Pi Pico.
If the device isn't already in the UF2 bootloader:
```sh
circuitpython-tool uf2 enter :Pico:
```
Then download and install CircuitPython:
```sh
circuitpython-tool install --board raspberry_pi_pico
```
### Wipe out flash memory
Wipe out flash memory to bring the device to a factory default state:
```sh
circuitpython-tool uf2 nuke
```
## Shell completion
The tool supports shell completion of all parameters, including device queries and board names!
Setup completion for your shell:
```sh
eval "$(circuitpython-tool completion)"
```
Device queries:
<!-- RICH-CODEX hide_command: true -->
Adafruit board names:
<!-- RICH-CODEX hide_command: true -->
CircuitPython locales:
<!-- RICH-CODEX hide_command: true -->
Raw data
{
"_id": null,
"home_page": null,
"name": "circuitpython-tool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "adafruit,circuitpython,microcontroller,rp2040",
"author": null,
"author_email": "Diony Rosa <dhrosa+dev@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/d6/1a/4205c4105858f85b2a553f5016a8f987f32e48082fb4c5aae446e9f219e0/circuitpython_tool-0.10.0.tar.gz",
"platform": null,
"description": "# circuitpython-tool\n\n[](https://badge.fury.io/py/circuitpython-tool)\n\nLinks:\n- Github: https://github.com/dhrosa/circuitpython-tool\n- PyPI: https://pypi.org/project/circuitpython-tool\n\nInstallation:\n\n```sh\npip install circuitpython-tool\n```\n\n## Overview\n\n`circuitpython-tool` is a command-line utility for conveniently using\nCircuitPython devices from the terminal. Especially useful\nwhen multiple devices are connected to the same computer.\n\nBenefits:\n- No need to manually mount `CIRCUITPY` drives, or even keep track of where its mounted. You can refer to the device by name instead.\n- No need to figure out the name of the serial terminal (e.g. /dev/ttyACM1). You can refer to the device by name instead.\n- No need to find the correct CircuitPython version, reset your device while holding BOOTSEL, or drag-and-drop the `.uf2` file into `RPI-RP2`. You can enter the UF2 bootloader with one command, and automatically download and install CircuitPython with another command.\n\nThis tool is designed for a workflow where instead of editing files directly on\nthe CircuitPython device, you edit files on your computer and sync the code over\nto the device.\n\n## Usage\n\n\n\n## Terminology\n\n- **Query**: `vendor:model:serial` string that specifies one or more connected CircuitPython devices. Each component string is searched for in the respective attribute. Empty strings are allowed in each component of the query. Example queries:\n - `::` matches ANY device.\n - `Adafruit::` matches any device whose vendor contains the string \"Adafruit\"\n - `:Feather:` matches any device whose model contains the string \"Feather\"\n - `Adafruit:Feather:` matches any device whose vendor contains the string \"Adafruit\" AND whose model contains the string \"Feather\"\n \n- **Device**: A CircuitPython device connected over USB. The device shows up as\n a removeable drive labeled `CIRCUITPY`. When the term \"device\" is referred to\n in a command-line argument, the device is specified as a query strong as\n above. An error is thrown if the given query matches multiple connected\n devices.\n \n- **UF2 Device**: A device connected over USB that is in its UF2 bootloader. For\n RP2040-based devices, the device shows up as a removable drive labeled\n `RPI-RP2`. This is the default state for brand-new RP2040 devices. This is\n also the state entered when a device is reset with the BOOTSEL butten held\n down. This state can also be entered via the `uf2 enter` command.\n\n## Example Commands\n\n### List devices\nList connected CircuitPython devices and their properties:\n\n\n\n\n### Connect to serial terminal\n\nOpen serial terminal to connected Raspberry Pi Pico (without needing to find the correct /dev/ttyACM path!):\n\n```sh\ncircuitpython-tool connect :Pico:\n```\n\n### Upload code\n\nUpload code to connected Raspberry Pi Pico everytime the contents of `~/mycode` changes (without needing to manually mount the device!):\n\n```sh\ncircuitpython-tool upload --dir ~/mycode :Pico:\n```\n\nOr to only upload code once and exit:\n\n```sh\ncircuitpython-tool watch --dir ~/mycode :Pico: --mode=single-shot\n```\n\n### Mount device\nMount Raspberry Pi Pico (if needed) and print the path to the mountpoint:\n```sh\ncircuitpython-tool mount :Pico:\n```\n\n### Install CircuitPython\n\nAutomatically download and install the correct version of CircuitPython onto a connected Raspberry Pi Pico.\n\nIf the device isn't already in the UF2 bootloader:\n\n```sh\ncircuitpython-tool uf2 enter :Pico:\n```\n\nThen download and install CircuitPython:\n```sh\ncircuitpython-tool install --board raspberry_pi_pico\n```\n\n### Wipe out flash memory\n\nWipe out flash memory to bring the device to a factory default state:\n```sh\ncircuitpython-tool uf2 nuke\n```\n\n## Shell completion\n\nThe tool supports shell completion of all parameters, including device queries and board names!\n\nSetup completion for your shell:\n\n```sh\neval \"$(circuitpython-tool completion)\"\n```\n\nDevice queries:\n<!-- RICH-CODEX hide_command: true -->\n\n\nAdafruit board names:\n<!-- RICH-CODEX hide_command: true -->\n\n\nCircuitPython locales:\n<!-- RICH-CODEX hide_command: true -->\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Command-line tool for interfacing with CircuitPython devices.",
"version": "0.10.0",
"project_urls": {
"Source code": "https://github.com/dhrosa/circuitpython_tool"
},
"split_keywords": [
"adafruit",
"circuitpython",
"microcontroller",
"rp2040"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9daa11a292ecb9993bafbef00697700343654ee2113549e818d0f17ed549926b",
"md5": "43704298264667a207ec4a9eb526db4f",
"sha256": "4151108b50e352cb51d28bdee7eafe210f73755f1d556544005ff0054e4c072b"
},
"downloads": -1,
"filename": "circuitpython_tool-0.10.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "43704298264667a207ec4a9eb526db4f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 62288,
"upload_time": "2024-03-06T00:19:25",
"upload_time_iso_8601": "2024-03-06T00:19:25.731941Z",
"url": "https://files.pythonhosted.org/packages/9d/aa/11a292ecb9993bafbef00697700343654ee2113549e818d0f17ed549926b/circuitpython_tool-0.10.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d61a4205c4105858f85b2a553f5016a8f987f32e48082fb4c5aae446e9f219e0",
"md5": "0be4b1497c889a0b410fa9d1ecf5f1fe",
"sha256": "1bb0dfd894a947b6d3db70110e0e9ec25e85bfe777ab92713eec0c005e9a948d"
},
"downloads": -1,
"filename": "circuitpython_tool-0.10.0.tar.gz",
"has_sig": false,
"md5_digest": "0be4b1497c889a0b410fa9d1ecf5f1fe",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 66382,
"upload_time": "2024-03-06T00:19:27",
"upload_time_iso_8601": "2024-03-06T00:19:27.518158Z",
"url": "https://files.pythonhosted.org/packages/d6/1a/4205c4105858f85b2a553f5016a8f987f32e48082fb4c5aae446e9f219e0/circuitpython_tool-0.10.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-06 00:19:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dhrosa",
"github_project": "circuitpython_tool",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "circuitpython-tool"
}
JSON
