jlctl is a command line tool for controlling @Architeuthis-Flux's awesome Jumperless breadboard.
Check the Releases page for binary releases, and follow instructions from there.
Prerequisite:
- a working Rust toolchain. If you don't have one, visit https://rustup.rs/ to get one.
Building:
cargo build --releaseYou'll find the binary in ./target/release/jlctl. Copy it wherever you like!
jlctl needs access to the serial port of the jumperless. By default it will try to find the port itself.
If that fails, or if you want to restrict jlctl to a specific serial port, use the --port <port> option.
List serial ports to see if the board is detected:
$ jlctl list-ports
╭──────────────┬───────────┬───────────────────╮
│ Port Name ┆ USB ID ┆ Role │
╞══════════════╪═══════════╪═══════════════════╡
│ /dev/ttyACM0 ┆ acab:1312 ┆ JumperlessPrimary │
├╌╌╌╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌┼╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤
│ /dev/ttyACM1 ┆ acab:1312 ┆ JumperlessArduino │
╰──────────────┴───────────┴───────────────────╯
If you see a port with role "JumperlessPrimary", you're good to go.
Connect some rows together:
$ jlctl bridge set 3-7,14-2
Rows 3, 7, 14 and 2 should be lit up on your board now.
Retrieve the current list of bridges:
$ jlctl bridge list
3-7,14-2
Retrieve the list of nets:
$ jlctl net list
Use the help command to get a list of commands and options:
$ jlctl help
CLI for the jumperless breadboard
Usage: jlctl [OPTIONS] <COMMAND>
Commands:
list-ports List serial ports
identify-port Identify primary Jumperless port
raw Send a raw command to the Jumperless
net Interact with nets
bridge Interact with bridges
supply-switch-pos Inform Jumperless about it's switch position
lightnet Set color for given light
server Start HTTP server
help Print this message or the help of the given subcommand(s)
Options:
-p, --port <PORT> Serial port where the Jumperless is connected. If omitted, the port is detected dynamically
-l, --log-path <LOG_PATH> Capture device log in this file [default: log.txt]
-h, --help Print help
-V, --version Print version
To get help for a specific command, run jlctl help <command>, e.g.
$ jlctl help bridge
Interact with bridges
Usage: jlctl bridge <COMMAND>
Commands:
list Download list of bridges from the Jumperless
set Upload new list of bridges to the Jumperless
clear Upload empty list of bridges to the jumperless
help Print this message or the help of the given subcommand(s)
Options:
-h, --help Print help
This works for subcommands as well:
$ jctl help bridge list
Download list of bridges from the Jumperless
Usage: jlctl bridge list [OPTIONS]
Options:
-f, --file <FILE> Write to file instead of stdout
-h, --help Print help
etc.
jlctl uses the env_logger package to facilitate logging.
Check out it's documentation to find out about all the options.
The log level defaults to info. A good place to start is setting it to debug:
RUST_LOG=debug jlctl ...
Many of the commands support JSON input and output. Check help for details.
If you are missing some feature, please open an issue or a PR.
Some examples (using jq for JSON processing):
- Identify the Arduino Port (e.g. to pass it to avrdude):
$ jlctl list-ports -o json | jq -r '.[] | select(.role == "JumperlessArduino") | .info.port_name' /dev/ttyACM1 - Print color of the
GNDnode:$ jlctl net list -ojson | jq -r '.[] | select(.name == "GND") | .color' #001c04
jlctl includes an HTTP server, used by the jumperlab UI.
To start it, run
jlctl server
By default the server listens on localhost:8080. To change that, pass --listen:
jlctl server --listen 0.0.0.0:12345
Pass 0 as the port, to let the operating system choose a random one (e.g. --listen localhost:0).
When run as a server, jlctl will try to open the device once the first request comes in. It then keeps that device open and uses it for subsequent requests. If any request fails to communicate with the device, that request will fail (with status 502), but subsequent requests will try to open the device again.
jlctl can be built with the jumperlab UI included.
The UI will be pre-built, and included within the jlctl binary as a ZIP. This way both projects can be distributed as a single binary.
To build jlctl with jumperlab, take these steps:
- Check out / update the jumperlab submodule, with:
git submodule update --init - Build jlctl with the
jumperlabfeaturecargo build --features jumperlab
The resulting build will server jumperlab on the /jumperlab path, when running in server mode.
A link to open jumperlab is also printed during server startup:
$ target/release/jlctl server
[2024-01-28T20:36:25Z INFO jlctl::server] Starting HTTP server, listening on localhost:8080
[2024-01-28T20:36:25Z INFO actix_server::builder] starting 1 workers
[2024-01-28T20:36:25Z INFO actix_server::server] Actix runtime found; starting in Actix runtime
To open Jumperlab, visit: http://localhost:8080/jumperlab
