Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/johnwargo/circuitpython-sync
Synchronize files from a CircuitPython device to a local project folder
https://github.com/johnwargo/circuitpython-sync
circuitpython nodejs
Last synced: about 1 month ago
JSON representation
Synchronize files from a CircuitPython device to a local project folder
- Host: GitHub
- URL: https://github.com/johnwargo/circuitpython-sync
- Owner: johnwargo
- License: mit
- Created: 2023-02-08T12:41:28.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2024-03-09T16:33:49.000Z (10 months ago)
- Last Synced: 2024-03-09T17:37:10.255Z (10 months ago)
- Topics: circuitpython, nodejs
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/cpsync
- Size: 213 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# CircuitPython Sync
Node module that synchronizes the files on a connected CircuitPython device to a local project folder. It provides a one-way sync from the CircuitPython device to the local project folder. Technically it does a copy rather than a sync, but if I included copy in the name, it would be `cpcopy` or `cp-copy` which looks like a merger of the Linux copy command `cp` plus the DOS copy command `copy` and that would be confusing.
When you work with a CircuitPython device, you generally read and write executable Python files directly from/to the device; there's even a Python editor called [Mu](https://codewith.mu/) built just for this use case.
Many more experienced developers work with a local project folder then transfer the source code to a connected device, as you do when working with Arduino and other platforms. This module allows you to do both:
1. Read/write source code from/to a connected Circuit Python device using Mu or other editors (even Visual Studio Code plugins).
2. Automatically copy source files from the device to a local project folder whenever the change on the device.
Here's how it works:
1. Create a local Python project with all the other files you need (like a `readme.md` file, or a `.gitignore`).
2. Connect a CircuitPython device to your computer.
3. Open a terminal window or command prompt and execute the module specifying the CircuitPython drive path and local project path as command line arguments.
4. The module copies all of the files from the connected CircuitPython device to the specified project folder.
5. Open any editor you want and edit the Python source code files (and any other file) on the connected device.
6. When you save any modified files on the connected CircuitPython device, the module automatically copies the modified file(s) to the project folder.
[See the module in action on YouTube](https://www.youtube.com/watch?v=QkF4pEy4YIY)
## Installation
To install globally, open a command prompt or terminal window and execute the following command:
``` shell
npm install -g cpsync
```
You'll want to install globally since CircuitPython projects don't generally use Node modules (like this one) so a `package.json` file and `node_modules` folder will look weird in your project folder.
## Usage
To start the sync process, in a terminal window execute the following command:
``` shell
cpsync [-d | --debug] [-i | --ignore]
```
Arguments:
* `` is the drive path for a connected CircuitPython device
* `` is the local project folder where you want the module to copy the files from the connected CircuitPython device
Both command arguments are required (indicated by angle brackets `<` and `>`). Square brackets (`[` and `]`)indicate optional parameters.
Options:
* `-d` or `--debug` enables debug mode which writes additional information to the console as the module executes
* `-i` or `--ignore` instructs the module to ignore the internal files typically found on a CircuitPython device.
A CircuitPython device hosts several internal use or housekeeping files that you don't need copied into your local project. When you enable ignore mode (by passing the `-i` option on the command line), the module ignores the following when synchronizing files from the CircuitPython device to your local project folder:
``` typescript
const ignoreFiles = [
'boot_out.txt',
'BOOTEX.LOG',
'.DS_Store',
'.metadata_never_index',
'System Volume Information',
'test_results.txt',
'.Trashes'
] as const;
const ignoreFolders = [
'.fseventsd',
'System Volume Information',
'.Trashes'
] as const;
```
If you find other device-side housekeeping files, let me know and I'll update the ignore arrays in the module.
## Examples
If you don't want to install the module globally, you can execute the module on the fly instead using:
``` shell
npx cpsync
```
On Windows, the device appears as a drive with a drive letter assignment. So, assuming it's drive H (your experience may vary but that's how it shows up on my Windows system) start the module with the following command:
``` shell
cpsync h: c:\dev\mycoolproject
```
Assuming you'll launch the module from your project folder, use a `.` for the current folder as shown in the following example:
``` shell
cpsync h: .
```
On macOS, it mounts as a drive and you can access it via `/Volumes` folder. On my system, the device mounts as `CIRCUITPY`, so start the sync process using:
``` shell
cpsync /Volumes/CIRCUITPY .
```
On Windows I like to execute the module from the terminal prompt in Visual Studio Code, but keep the terminal available to execute other commands, so I start the module using the following:
``` shell
start cpsync
```
This starts the module in a new/separate terminal window, leaving the Visual Studio terminal available to me to execute additional commands.
For example, if I execute the following command:
``` shell
start cpsync h: . -i
```
A new window opens as shown in the following figure
The CircuitPython device shows up as drive `H:` and the `.` tells the module to copy the files to the current folder.
Every time you change the file contents on the device, the module copies the modified files to the local project folder.
### Getting Help Or Making Changes
Use [GitHub Issues](https://github.com/johnwargo/circuitpython-sync/issues) to get help with this module.
Pull Requests gladly accepted, but only with complete documentation of what the change is, why you made it, and why you think its important to have in the module.
If this code helps you: 