Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
77d285e
Firmware 4.0 protocol: client API 2, code-only refusals, exit code 7
wardviaene Nov 20, 2026
84007d8
discover: read the API level from mDNS and say what a pod needs
wardviaene Nov 20, 2026
7280137
lan-tls: scpi switch, firmware 4.0 TLS defaults
wardviaene Nov 20, 2026
7f00929
install-blobs, flash-self: drop the console blob upload (firmware bef…
wardviaene Nov 20, 2026
ecf94aa
cloud ca, cloud proxy: JSON over the USB network adapter, no console
wardviaene Nov 20, 2026
b3ef4c3
set-wifi, show-network, scan-wifi, clear-wifi: JSON over USB; net-reset
wardviaene Nov 20, 2026
d3bdf8f
identity wipe: JSON identity_wipe over the USB network adapter
wardviaene Nov 20, 2026
76bbbb0
sig-policy: show only, over the USB network adapter
wardviaene Nov 20, 2026
3b641b5
usb-reattach, la voltage, flash over USB: JSON only, no console
wardviaene Nov 20, 2026
d5777e2
serialconsole: keep only the console commands firmware 4.0 has
wardviaene Nov 20, 2026
0323b63
Follow the firmware 4.0 renames
wardviaene Nov 20, 2026
e02acdb
gofmt
wardviaene Nov 20, 2026
0f5e895
Sync the features table (rev 11) and the error catalog (BP0080)
wardviaene Nov 20, 2026
9abe492
benchpod ci: exit codes that do not clash with the CLI's table
wardviaene Nov 20, 2026
a9c7763
README: word the ci exit codes so the docs check passes
wardviaene Nov 20, 2026
570fdb2
Usage mistakes exit with 2
wardviaene Nov 20, 2026
067c39a
One flag name each: --out, --format, --addr
wardviaene Nov 20, 2026
6a8f92d
Drop the set-bench-pod alias, the serial connection keyword and bare mV
wardviaene Nov 20, 2026
cd40bae
README: la voltage takes no bare millivolts
wardviaene Nov 20, 2026
2238d85
Drop the fallbacks for firmware before 4.0
wardviaene Nov 20, 2026
338959f
README: breaking changes in 0.10
wardviaene Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
494 changes: 277 additions & 217 deletions README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion cmd/benchpod-cli/adcrange.go
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ func adcRange(ctx context.Context, c podCommander, via, action, what string, out
return errors.New(adcRangeMissing)
}
if pe, ok := tcpclient.AsPodError(err); ok {
return refusedError(what, pe, false)
return refusedError(what, pe)
}
return fmt.Errorf("%s: %w", what, err)
}
Expand Down
24 changes: 6 additions & 18 deletions cmd/benchpod-cli/blobs.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ import (

const blobsManifestName = "blobs-manifest.json"

// blobsInstallTimeout bounds a whole install: ~1.3 MB over the USB console plus the slot writes.
// blobsInstallTimeout bounds a whole install: ~1.3 MB over USB plus the slot writes.
const blobsInstallTimeout = 10 * time.Minute

type blobEntry struct {
Expand Down Expand Up @@ -267,19 +267,6 @@ func espLast(todo []blobEntry) []blobEntry {
return append(out, esp...)
}

// podFirmwareRelease is the release tag of the firmware a pod runs ("v3.4.0"), "" if unknown.
func podFirmwareRelease(ctx context.Context, console *serialconsole.Console) string {
raw, err := console.Status(ctx)
if err != nil {
return ""
}
v := serialconsole.FirmwareVersion(raw)
if v != "" && !strings.HasPrefix(v, "v") {
v = "v" + v
}
return v
}

func newInstallBlobsCmd(g *globalFlags) *cobra.Command {
var dir, release, only string
var force bool
Expand All @@ -288,8 +275,9 @@ func newInstallBlobsCmd(g *globalFlags) *cobra.Command {
Short: "Install the gateware and ESP32-C3 images the pod's firmware goes with (over USB)",
Long: "The pod keeps its iCE40 gateware images and its ESP32-C3 Wi-Fi image in the\n" +
"W25Q flash next to the FPGA, not in its firmware. This sends the ones it lacks\n" +
"over USB: the pod's USB network adapter when it is up (firmware 3.9.0+), else its\n" +
"USB console. By default they come from the GitHub release that matches\n" +
"over the pod's USB network adapter (firmware 3.9.0+), else its network address.\n" +
"USB networking off: `benchpod usb-network on --connection usb` (the console's\n" +
"`usb-network on`). By default they come from the GitHub release that matches\n" +
"the firmware the pod runs; --dir takes them from a local build (stm32h563/build/blobs).\n\n" +
"Each blob's signature (blob-*.bin.sig) is checked and reported, and handed to\n" +
"firmware that checks it too; for now a missing or failing one never stops an install.",
Expand All @@ -301,8 +289,8 @@ func newInstallBlobsCmd(g *globalFlags) *cobra.Command {
}
ctx, cancel := context.WithTimeout(context.Background(), g.effectiveTimeout(blobsInstallTimeout))
defer cancel()
// This computer's end of the pod's USB network link (firmware 3.9.0+) needs no console;
// else the console names the way in: the USB network when it is up, else the console.
// This computer's end of the pod's USB network link needs no console; else the console
// names the way in: the USB network when it is up, else the pod's network address.
target, closeTarget := g.localBlobTarget(ctx)
path := "the USB network"
if target == nil {
Expand Down
29 changes: 6 additions & 23 deletions cmd/benchpod-cli/blobs_target.go
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,8 @@ import (
)

// blobTarget is where install-blobs reads the pod's W25Q slots and sends blobs: the pod's network
// API (over its USB network adapter, firmware 3.9.0+: blob_status and ota_* with a target) or its
// USB console (blobs and upload-*, older firmware).
// API (blob_status and ota_* with a target), over its USB network adapter or its network address
// (firmware 3.9.0 and later; older firmware had a console upload this CLI no longer sends).
type blobTarget interface {
Blobs(ctx context.Context) ([]serialconsole.BlobSlot, error)
UploadSigned(ctx context.Context, target string, data []byte, version int, manifest []byte,
Expand All @@ -33,24 +33,6 @@ type blobTarget interface {
Method() string
}

// consoleBlobs is the USB console.
type consoleBlobs struct {
*serialconsole.Console
path string
}

func (c consoleBlobs) Release(ctx context.Context) string { return podFirmwareRelease(ctx, c.Console) }
func (c consoleBlobs) Via() string { return c.path }
func (c consoleBlobs) Method() string { return "usb_console" }

func (c consoleBlobs) Identity(ctx context.Context) (string, string) {
id, err := c.Console.Identity(ctx)
if err != nil {
return "", ""
}
return id.PublicKey, id.ShortID
}

// lanBlobChunk is the raw bytes per ota_data line (as the LAN OTA in hwe2e sends).
const lanBlobChunk = 768

Expand Down Expand Up @@ -244,7 +226,8 @@ func (l lanBlobs) waitApplied(ctx context.Context, target string) error {
func blobTargetFor(ctx context.Context, console *serialconsole.Console, path string) (blobTarget, func(), error) {
u, err := console.USBNetwork(ctx)
if errors.Is(err, serialconsole.ErrNoUSBNet) {
return consoleBlobs{Console: console, path: path}, func() {}, nil // firmware before 3.9.0
return nil, func() {}, errors.New("this pod's firmware is older than 3.9.0 and takes blobs only over its USB console, " +
"which this CLI no longer uses: update the pod with `benchpod flash-self` (USB DFU), which installs its blobs")
}
if err != nil {
return nil, func() {}, fmt.Errorf("read the pod's status: %w", err)
Expand Down Expand Up @@ -272,8 +255,8 @@ func blobTargetFor(ctx context.Context, console *serialconsole.Console, path str
return t, c, nil
}
}
return nil, func() {}, errors.New("this pod's firmware (3.9.0 or later) takes blobs over the network, and neither its USB " +
"network adapter (Wi-Fi configured on the pod turns it off: `benchpod clear-wifi`) nor its network address answers")
return nil, func() {}, errors.New("the pod takes blobs over the network, and neither its USB network adapter " +
"nor its network address answers. " + usbNetworkOffHint)
}

// localBlobTarget is the pod's network API on this computer's end of its USB network link
Expand Down
27 changes: 9 additions & 18 deletions cmd/benchpod-cli/blobs_target_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -42,23 +42,14 @@ func (c *textConsole) Close() error { return nil }

var _ io.ReadWriteCloser = (*textConsole)(nil)

// New CLI + firmware without a usable USB network: install-blobs keeps today's console path.
func TestBlobTargetFallsBackToTheConsole(t *testing.T) {
cases := map[string]string{
"firmware before 3.9.0": " device : benchpod\r\n ip : 192.168.1.220\r\n",
}
for name, status := range cases {
c := serialconsole.NewConsole(&textConsole{status: status})
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
target, closeT, err := blobTargetFor(ctx, c, "/dev/cu.usbmodem1")
cancel()
if err != nil {
t.Fatalf("%s: %v", name, err)
}
closeT()
if _, ok := target.(consoleBlobs); !ok || target.Via() != "/dev/cu.usbmodem1" {
t.Fatalf("%s: target %T via %s, want the console", name, target, target.Via())
}
// Firmware before 3.9.0 has no USB network adapter: its console upload is gone, so a clear error
// that names flash-self.
func TestBlobTargetBefore39IsAnError(t *testing.T) {
c := serialconsole.NewConsole(&textConsole{status: " device : benchpod\r\n ip : 192.168.1.220\r\n"})
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
if _, _, err := blobTargetFor(ctx, c, "/dev/cu.usbmodem1"); err == nil || !strings.Contains(err.Error(), "benchpod flash-self") {
t.Fatalf("err = %v", err)
}
}

Expand All @@ -72,7 +63,7 @@ func TestBlobTargetOn39WithoutANetworkIsAnError(t *testing.T) {
" usb : net off (Wi-Fi configured) pod 10.237.8.85 host 10.237.8.86 link down rx 0 (drop 0) tx 0 (full 0)\r\n"})
ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
defer cancel()
if _, _, err := blobTargetFor(ctx, c, "/dev/cu.usbmodem1"); err == nil || !strings.Contains(err.Error(), "clear-wifi") {
if _, _, err := blobTargetFor(ctx, c, "/dev/cu.usbmodem1"); err == nil || !strings.Contains(err.Error(), "usb-network on") {
t.Fatalf("err = %v", err)
}
}
95 changes: 26 additions & 69 deletions cmd/benchpod-cli/busmaster.go
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ func busCommand(ctx context.Context, t *podTarget, what, feature string, req map
if isUnknownCommand(err) {
return &shownRefusal{msg: what + ": " + tooOldForBusMaster(feature), pe: pe}
}
return refusedError(what, pe, !t.spec.IsCloud())
return refusedError(what, pe)
}
return fmt.Errorf("%s: %w", what, err)
}
Expand Down Expand Up @@ -206,7 +206,7 @@ type i2cSession struct {
Active *bool `json:"active"`
SDA int `json:"sda"`
SCL int `json:"scl"`
Hz int `json:"hz"`
Hz int `json:"clock_hz"`
Pullups string `json:"pullups"`
}

Expand Down Expand Up @@ -272,7 +272,7 @@ func newI2CStartCmd(g *globalFlags) *cobra.Command {
}
defer cancel()
var s i2cSession
req := map[string]any{"cmd": "i2c_start", "sda": sdaPin, "scl": sclPin, "hz": hz, "pullups": pullups}
req := map[string]any{"cmd": "i2c_start", "sda": sdaPin, "scl": sclPin, "clock_hz": hz, "pullups": pullups}
if err := busCommand(ctx, t, "i2c start", "I2C master", req, &s); err != nil {
return err
}
Expand Down Expand Up @@ -463,7 +463,7 @@ func newI2CStopCmd(g *globalFlags) *cobra.Command {
}
}

// writeLine prints one line to the command output (--output-filename or stdout).
// writeLine prints one line to the command output (--out or stdout).
func writeLine(g *globalFlags, line string) error {
out, closeOut, err := resolveOutput(g.outputFilename)
if err != nil {
Expand Down Expand Up @@ -567,74 +567,31 @@ type laPinsCommander interface {
Command(ctx context.Context, req map[string]any) (json.RawMessage, error)
}

// laPinsFetch reads la_pins: every pin (pins nil) or only those pins. Firmware after 3.10.12 sends
// only the pins asked for; older firmware sends all 14 and they are filtered here. A full listing
// the pod answers with "reply too large" (a long sensor instance name on every pin) is read in two
// parts, LA1-7 and LA8-14, and joined.
// laPinsFetch reads la_pins: every pin (pins nil) or only those pins (the pod sends only the pins
// asked for). A full listing the pod answers with BP0053 (reply_too_large: a long sensor instance
// name on every pin) is read in two parts, LA1-7 and LA8-14, and joined.
func laPinsFetch(ctx context.Context, c laPinsCommander, pins []int) (json.RawMessage, error) {
if pins == nil {
raw, err := c.Command(ctx, map[string]any{"cmd": "la_pins"})
if err == nil || !strings.Contains(err.Error(), "reply too large") { // no code yet
return raw, err
if pins != nil {
return c.Command(ctx, map[string]any{"cmd": "la_pins", "la": pins})
}
raw, err := c.Command(ctx, map[string]any{"cmd": "la_pins"})
if err == nil || !tcpclient.HasCode(err, "BP0053") {
return raw, err
}
var parts [2]map[string]any
for i, half := range [][]int{{1, 2, 3, 4, 5, 6, 7}, {8, 9, 10, 11, 12, 13, 14}} {
raw, err := c.Command(ctx, map[string]any{"cmd": "la_pins", "la": half})
if err != nil {
return nil, err
}
first, err1 := laPinsQuery(ctx, c, []int{1, 2, 3, 4, 5, 6, 7})
if err1 != nil {
return nil, laPinsUpdateHint(err)
if err := json.Unmarshal(raw, &parts[i]); err != nil {
return nil, fmt.Errorf("unexpected reply %s", strings.TrimSpace(string(raw)))
}
if n, _ := first["pins"].([]any); len(n) > 7 {
return nil, laPinsUpdateHint(err) // firmware without the pin subset: it sent everything again
}
second, err2 := laPinsQuery(ctx, c, []int{8, 9, 10, 11, 12, 13, 14})
if err2 != nil {
return nil, err2
}
a, _ := first["pins"].([]any)
b, _ := second["pins"].([]any)
first["pins"] = append(a, b...)
return json.Marshal(first)
}
m, err := laPinsQuery(ctx, c, pins)
if err != nil {
return nil, err
}
return json.Marshal(m)
}

// laPinsUpdateHint says what to do when older firmware (no pin subset) cannot send the whole list.
func laPinsUpdateHint(err error) error {
return fmt.Errorf("%w; firmware after 3.10.12 reads this list in parts: update the pod "+
"(benchpod flash-self, or the firmware update in the web app), or ask for fewer pins "+
"(benchpod la pins 1-7)", err)
}

// laPinsQuery sends la_pins with "la" and keeps only the entries of those pins.
func laPinsQuery(ctx context.Context, c laPinsCommander, pins []int) (map[string]any, error) {
raw, err := c.Command(ctx, map[string]any{"cmd": "la_pins", "la": pins})
if err != nil {
return nil, err
}
var m map[string]any
if err := json.Unmarshal(raw, &m); err != nil {
return nil, fmt.Errorf("unexpected reply %s", strings.TrimSpace(string(raw)))
}
want := map[int]bool{}
for _, p := range pins {
want[p] = true
}
var keep []any
entries, _ := m["pins"].([]any)
for _, e := range entries {
if em, ok := e.(map[string]any); ok {
if la, ok := em["la"].(float64); ok && want[int(la)] {
keep = append(keep, e)
}
}
}
if keep == nil {
keep = []any{}
}
m["pins"] = keep
return m, nil
a, _ := parts[0]["pins"].([]any)
b, _ := parts[1]["pins"].([]any)
parts[0]["pins"] = append(a, b...)
return json.Marshal(parts[0])
}

func newLAPinsCmd(g *globalFlags) *cobra.Command {
Expand All @@ -644,7 +601,7 @@ func newLAPinsCmd(g *globalFlags) *cobra.Command {
Short: "List every LA pin: function, GPIO state, live level, pull-up, direction and warnings",
Long: "List every LA pin, or only PINS (a pin, a list or a range: 9, 9,10, 9-12, la9, or a\n" +
"name from the pod's wiring profile). A list too large for one cloud reply is read\n" +
"in two parts by itself (firmware after 3.10.12).",
"in two parts by itself.",
Example: " benchpod la pins\n benchpod la pins 1-4\n benchpod la pins uart_rx --json",
Args: cobra.MaximumNArgs(1),
RunE: func(_ *cobra.Command, args []string) error {
Expand Down
Loading