A Scala 3 CLI client for echo, the LED matrix HTTP proxy.
It intentionally talks only to the HTTP API (/api/v1/...) and never uses the raw TCP firmware protocol.
# Basic health checks
echoctl health
echoctl ready
echoctl devices
# Play animations
echoctl animations list
echoctl animations catalog
echoctl play alert --priority 80
echoctl preset matrix_rain_background
echoctl effects # list the effects worth choosing from
echoctl effect comet --interval 80ms --color '#00FF55'
echoctl stop # stops the effect; does NOT clear the panel
# Repeat an animation. "forever" needs a duration, or it never finishes.
echoctl play spinner --loop forever --duration 10s
echoctl play spinner --loop until_deadline --duration 5s
# Direct matrix controls
echoctl matrix fill '#00FF55'
echoctl matrix clear
echoctl matrix brightness 20
echoctl matrix pixel 3 4 '#FF0044' # one pixel, display-space coordinates
echoctl matrix panel off # blank output, keep the image
echoctl matrix panel on
# Device-side animation: the firmware loops these locally, with no
# network round-trip per frame. Up to 8 frames.
echoctl matrix animation --delay 120ms heart1.txt heart2.txt
echoctl matrix frame heart1.txt # upload a single frame
echoctl matrix frame --preview-only heart1.txt
# Discovery
echoctl openapi
echoctl metrics
# Notify and generic event
echoctl notify "deploy done" --duration 3s
echoctl event --source cli --type deploy --attr animation=notify --attr duration=2s
# Background and queue
echoctl background get
echoctl background set matrix_rain_background
echoctl queue
echoctl queue --clear- Complete coverage of the server's HTTP surface:
health,ready,devices,animations,play,preset,effect,stop,notify,event,matrix(fill, clear, brightness, static, pixel, panel, frame, animation),background, andqueue.SpecCoverageSpecTestsasserts there is no device matrix route in the server's spec the CLI cannot reach. - Additional helper endpoints:
/openapi.jsonand/metrics. - Config resolution precedence: flags > env > config file > defaults.
- Firmware effect id/name table for
effect, checked against the firmware's own table byPresetSpecTests— including which effects are retired and which ignore--color.echoctl effectslists the ones worth choosing from. - Duration/interval and color input validation.
--jsonand--verboseoutput modes.com.lihaoyi-backed CLI ergonomics (picocli,fansi,pprint,os-lib,requests,upickle).- Mill build with
NativeImageModulesupport. - Unit tests cover colour/duration parsing, preset resolution, config precedence, frame-palette resolution, and the pixel-grid → palette conversion used by upload.
Two files in spec/ are vendored copies of contracts this CLI does not own. Both
are asserted by tests, so a change upstream surfaces as a failing test here rather
than as a wrong animation on the panel:
| File | Owner | Asserted by |
|---|---|---|
spec/firmware-effects.tsv |
led-matrix-controller — TcpMatrixServer::applyCommand |
PresetSpecTests |
spec/openapi.json |
echo — generated by go generate ./cmd/matrix-proxy |
SpecCoverageSpecTests |
To refresh them, copy the upstream artifact in and run ./mill echoctl.test.
A few behaviours are counter-intuitive enough to be worth stating, all verified against the firmware:
stopdoes not clear the panel. The firmware halts the effect engine without touching the frame buffer, so the last effect frame stays lit. Usematrix clear.matrix clearmay not stick. With an idle background configured, the server repaints it almost immediately.matrix panel offis the only dark state that survives, because it is the one the server's convergence leaves alone.- Four effects ignore
--color— rainbow, fire, plasma and confetti compute their own colours. The device still answers OK, so the CLI warns instead. - Six effect ids are retired — they still work and still resolve, but each is a
parameter variant of another effect (
chase/meteorarecometwith a shorter tail;raindoes not fall).echoctl effectshides them; using one warns. matrix frameuploads to the device's animation slot (opcode0x09), it is not a raw full-frame write. There is no route for the latter.
matrix frame and matrix animation read 8×8 frame files. Name your colours in a
palette: section and reference them from rows::
palette:
off: "#000000"
lit: "#FF0044"
rows:
- [off,lit,lit,off,off,lit,lit,off]
- [lit,lit,lit,lit,lit,lit,lit,lit]
- [lit,lit,lit,lit,lit,lit,lit,lit]
- [off,lit,lit,lit,lit,lit,lit,off]
- [off,off,lit,lit,lit,lit,off,off]
- [off,off,off,lit,lit,off,off,off]
- [off,off,off,off,off,off,off,off]
- [off,off,off,off,off,off,off,off]
Colours may be hex (#RRGGBB), rgb(r,g,b), or one of red, green, blue,
white, off. Rows are display-space — the proxy handles the panel's serpentine
wiring. A symbol that is not in the palette is an error, not a skipped pixel.
Config path: ~/.config/echoctl/config.json.
{
"default_profile": "home",
"profiles": {
"home": {
"server": "http://pi4.lan:8080",
"device": "living-room",
"token": ""
}
}
}Environment variables:
ECHOCTL_SERVERECHOCTL_TOKENECHOCTL_DEVICEMATRIX_PROXY_ADMIN_TOKEN(token fallback)
Global flags:
--server--token--device--profile--config--json--verbose--help