Skip to content

CLI: classify pod errors by code, client API level (client_api, update-required error) - #79

Merged
wardviaene merged 5 commits into
mainfrom
error-codes-client-api
Nov 20, 2026
Merged

wardviaene merged 5 commits into
mainfrom
error-codes-client-api

Conversation

@wardviaene

Copy link
Copy Markdown
Member

Two changes, in three commits:

  1. Classify pod refusals by their error code. Before, PodError carried Code and Args, but ClassifyRefusal, explainRefusal and translateRefusal only looked at the text. Now tcpclient has one table from every catalog code (BP0001-BP0030) to its refusal kind, and the exit code follows the kind. A coded refusal shows the catalog's message and fix.cli as the hint (refusalHint / codedRefusal). Text matching is kept only as the fallback for replies without a code. Each fallback has a comment naming the code that replaces it, or "no code yet".
  2. Client API level. tcpclient.ClientAPI = 1, and a test checks it equals the embedded features.json api. Every JSON command carries "client_api":1 and "client":"cli <version>", on all four builders: Client.Command/Samples/Chunks, Session.Command, StartRaw (dap/uart raw starts), and cloudpod.Client.Command (embeddedci.com command channel, without the LAN lease). The USB console and SCPI send nothing. When a status reply announces api (or min_client_api) above 1, the CLI stops with:
    this pod's firmware <version> needs a newer benchpod CLI (pod API n, this CLI handles 1): brew upgrade --cask benchpod, or download the latest release from https://github.com/embeddedci-com/benchpod-cli/releases/latest
    A pod without api counts as 1. A BP0030 reply gives the same error (an *UpdateRequiredError, not a *PodError). Commands that only talk to the server or work locally are not affected.

New exit code 6: update the CLI. It is in the root help and in the README exit-code table. The README also has a new "Firmware newer than the CLI" section and explains coded refusals.

Needs benchpod-firmware#191 for the api / min_client_api fields and BP0030. Older firmware works as before: it ignores the request fields, announces no api (level 1) and never sends BP0030. The catalog and features.json are synced from that branch.

Code to handling

Code Kind (exit) Extra CLI handling
BP0001 la_voltage_not_set refused (3) catalog fix
BP0002 unknown_command refused (3) isUnknownCommand(err): each command's "this firmware lacks X, update it" message
BP0003 i2c_session_open, BP0004 spi_session_open, BP0005 bus_engine_busy busy (4)
BP0006-BP0015 (missing_argument, wiring_*) refused (3)
BP0016 storage_busy busy (4)
BP0017-BP0024 (gateware_too_old, uart_*, la_no_pull, la_pull_direction) refused (3)
BP0025 lease_busy busy (4) benchpod ci: holder/purpose/left_s from args
BP0026 lease_lost, BP0027 lease_not_held refused (3) benchpod ci: run invalid (its own exit 4)
BP0028 vref_5v_missing, BP0029 pull_rail_down refused (3)
BP0030 client_too_old update the CLI (6) *UpdateRequiredError

Every coded refusal's hint is the catalog's fix.cli with the args filled in. A code the CLI's catalog does not know (newer firmware) falls back to the text.

Text matches left, and why

  • locked:, forbidden: (gates), bare busy, swd busy / uart busy / spi busy / PSRAM busy: (ClassifyRefusal, explainRefusal): no code yet.
  • busy: a cloud job holds and ci_lease.go TrimPrefix("busy: "): fallback, BP0025 replaces them. Firmware 3.10.13 and older sends the cloud lease gate as text only.
  • la voltage not set -> BP0001; need(s) gateware v55+ -> BP0017; unknown cmd / unknown command -> BP0002; lease lost -> BP0026/BP0027: fallbacks for firmware without codes.
  • I2C needs pull-ups, pin conflict:, the emulation-image hint, image switch refused:, reply too large (busmaster), loosen (policy, a server-relayed text), unknown target (cloudcfg): no code yet.

The pinned lease_busy text in internal/fwrefusals is marked removed: 3.10.14. Firmware main (f7196d1) now builds that text from macros and sends BP0025 with it, so the literal check failed against firmware main.

Tests

  • Table-driven tests over every catalog code: the kind table covers the catalog exactly; the exit code, refusalHint, refusedError and withRefusalHint show the catalog message and fix.cli; BP0030 gives exit 6.
  • Uncoded firmware texts keep their exit codes, and IsUnknownCommand works with the code and with the text.
  • ClientAPI equals the embedded api.
  • The request fields on each builder, plus an end-to-end run on a LAN fake and a cloud fake. SetClientName keeps 32 printable characters.
  • The status check: api 2 stops with the error, api 1 or no api works, ping is not checked. Tested on a connection, a session and through the cloud, and BP0030 on both the LAN and the cloud.
  • The old-firmware tests (adcrange, loglevel, usbnetwork, policy, lavoltage, cloudcfg) now run against both the unknown cmd text and a BP0002 reply with no text. The cloud keeps code/args.
  • go vet ./... and go test ./... pass, with BENCHPOD_FIRMWARE_DIR pointed at the firmware branch. No hardware was used.

The cmd tests turn the client fields off in TestMain, so the existing tests that compare whole requests stay as they are. TestEveryRequestCarriesTheClientFields turns them back on.

🤖 Generated with Claude Code

wardviaene and others added 5 commits November 19, 2026 16:48
The catalog gains BP0030 client_too_old; features.json gains api and
min_client_api.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One table in tcpclient maps every catalog code (BP0001-BP0030) to its
refusal kind, so the exit code follows the code; a coded refusal's hint
is the catalog's fix.cli. Text matching stays as the fallback for
replies without a code, each match marked with the code that replaces it
or "no code yet". The six "unknown cmd" checks (and four more) use
one helper, isUnknownCommand (BP0002, else the text).

The pinned lease_busy text is marked removed: firmware after 3.10.13
builds it from macros and sends BP0025 with it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every JSON command (LAN, USB networking, a session, a raw-mode start and
embeddedci.com's command channel) carries "client_api":1 and
"client":"cli <version>". A status reply announcing an api above the
CLI's (1, the embedded features.json api; none counts as 1) stops with
"this pod's firmware <v> needs a newer benchpod CLI (...)" and exit
code 6; a BP0030 refusal gives the same error. README: exit code 6 and
how the update check works.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…the format out again in #191)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e commands still run

status prints the update line as a warning instead of stopping, and
flash-self, install-blobs, dfu, bootsel, discover and identity skip the
check, so an old CLI can still show such a pod and update or roll back its
firmware. The toggle is set before each command (SetAllowNewerPod).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@wardviaene
wardviaene merged commit 3a56807 into main Nov 20, 2026
3 of 4 checks passed
@wardviaene
wardviaene deleted the error-codes-client-api branch November 20, 2026 02:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant