Skip to content
worxbendPublic

About

Scala CLI client for echo LED matrix proxy

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

12 Commits

Folders and files

Repository files navigation

echoctl

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

Features implemented

  • 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, and queue. SpecCoverageSpecTests asserts there is no device matrix route in the server's spec the CLI cannot reach.
  • Additional helper endpoints: /openapi.json and /metrics.
  • Config resolution precedence: flags > env > config file > defaults.
  • Firmware effect id/name table for effect, checked against the firmware's own table by PresetSpecTests — including which effects are retired and which ignore --color. echoctl effects lists the ones worth choosing from.
  • Duration/interval and color input validation.
  • --json and --verbose output modes.
  • com.lihaoyi-backed CLI ergonomics (picocli, fansi, pprint, os-lib, requests, upickle).
  • Mill build with NativeImageModule support.
  • Unit tests cover colour/duration parsing, preset resolution, config precedence, frame-palette resolution, and the pixel-grid → palette conversion used by upload.

Contracts with the other repos

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.

Things that are not what they look like

A few behaviours are counter-intuitive enough to be worth stating, all verified against the firmware:

  • stop does not clear the panel. The firmware halts the effect engine without touching the frame buffer, so the last effect frame stays lit. Use matrix clear.
  • matrix clear may not stick. With an idle background configured, the server repaints it almost immediately. matrix panel off is 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/meteor are comet with a shorter tail; rain does not fall). echoctl effects hides them; using one warns.
  • matrix frame uploads to the device's animation slot (opcode 0x09), it is not a raw full-frame write. There is no route for the latter.

Frame files

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.

Configuration

Config path: ~/.config/echoctl/config.json.

{
  "default_profile": "home",
  "profiles": {
    "home": {
      "server": "http://pi4.lan:8080",
      "device": "living-room",
      "token": ""
    }
  }
}

Environment variables:

  • ECHOCTL_SERVER
  • ECHOCTL_TOKEN
  • ECHOCTL_DEVICE
  • MATRIX_PROXY_ADMIN_TOKEN (token fallback)

Global flags:

  • --server
  • --token
  • --device
  • --profile
  • --config
  • --json
  • --verbose
  • --help

About

Scala CLI client for echo LED matrix proxy

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages