Skip to content

SDK + MCP: classify pod errors by code, client API level (client_api, ClientTooOldError) - #129

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

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

Conversation

@wardviaene

Copy link
Copy Markdown
Member

What

1. Pod refusals are classified by their error code. One table, errors._BY_CODE, maps every code in the synced catalog to an exception class and fills that class's fields from the code's args:

Codes Class Fields from args
BP0001 la voltage not set FirmwareError (message stays the SDK's _LA_VOLTAGE_SDK; MCP keeps its own text)
BP0002 unknown command UnsupportedFeatureError feature = cmd
BP0003 / BP0004 I2C / SPI session open PodBusyError
BP0005 SWD/SPI/I2C engine busy PodBusyError
BP0006 missing argument FirmwareError
BP0007 to BP0015 wiring profiles new WiringError(FirmwareError) name
BP0016 storage busy PodBusyError (its text, "busy: ...", already gave this class)
BP0017 gateware too old UnsupportedFeatureError feature = feature
BP0018 to BP0022 UART options FirmwareError (no ValueError-like FirmwareError subclass exists)
BP0023 / BP0024 pulls PullDirectionError la, want, have
BP0025 lease busy PodLeasedError holder, purpose, left_s
BP0026 lease lost PodLeaseLostError by
BP0027 lease not held FirmwareError (pod_lease checks the code)
BP0028 / BP0029 pin 21 FirmwareError
BP0030 client too old new ClientTooOldError(FirmwareError) client_api, min_client_api, api

ClientTooOldError is deliberately not an UnsupportedFeatureError: several SDK paths catch that one to fall back quietly, and the MCP hint for it says to update the pod.

2. Client API level. feature_map.CLIENT_API = 1; a test ties it to the bundled table's api. protocol.encode_request (TCP, USB network, cloud byte tunnel, pod lease, the discovery probes) and the cloud command channel add "client_api": 1 and "client": "sdk <version>" (MCP: "mcp <version>") to every JSON command. The USB console text protocol and SCPI get nothing. Capabilities reads api / min_client_api (status, cap.* frame); client_api_level counts a pod without api as 1. A pod above CLIENT_API fails the connect with ClientTooOldError (firmware version, both levels, pip install -U embeddedci). The check runs on the status read connect already makes for the pin directions, so there is no extra request. BP0030 raises the same error. The features_rev warning is unchanged. MCP turns ClientTooOldError into a tool error that says to update embeddedci-mcp (uvx embeddedci-mcp@latest, pip install -U embeddedci-mcp, or the benchpod plugin). This works with embeddedci 3.0.5 too (getattr-guarded), so the MCP pin stays at 3.0.5.

Still matched on text, and why

  • Firmware without codes (before 3.10.8). These refusals still classify from their text into the same classes as before. Each pattern in errors.py names its replacement (BP0001, BP0002, BP0017, BP0025, BP0016).
  • Refusals with no code yet. Pin, pull and direction conflicts, "needs gateware" outside the UART, trigger timeout, locked/LAN policy, generic busy:, forbidden:, the digital board without analog, "reply too large" (client.py la_pins split, status too large), "no module link" (client.py), "unknown sensor instance" (sensors/emulation.py). These are marked "no code yet: firmware PR 2 of the codes plan".
  • A code newer than this SDK. The code stays on .code and the class comes from the text, so an older SDK keeps working when a later firmware adds codes to refusals it already classifies by text.
  • open_i2c's busy rewrite keys on BP0003 (text only without a code). MCP _error_text still rewrites firmware_message for refusals without a code; coded ones use the catalog's mcp fix.

Needs

benchpod-firmware#191 (client-api-level) for the api / min_client_api fields and BP0030. Bundled features.json and errors.json are synced from that branch. This works with older firmware: it ignores the new request fields, and a pod without api counts as 1.

Tests

Unit tests with fakes only; nothing touched the hardware.

  • make test: embeddedci 1195 passed, embeddedci-mcp 221 passed, embeddedci-openhtf 74 passed, scripts 12 passed. Run with BENCHPOD_FIRMWARE_DIR pointing at the firmware branch, because test_bundled_copy_matches_the_firmware compares against the sibling checkout.
  • New test_error_codes.py (48): one coded reply per code gives the class and fields, a guard that every catalog code is in the table, one text-only reply per pattern gives the old class, and an unknown code falls back to the text.
  • New test_client_api.py (15): CLIENT_API equals the bundled api; client_api/client are present on TCP, the cloud command channel and the cloud tunnel, and absent from the USB console; pod api 2 fails the connect while api 1 or none connects; refresh re-checks; BP0030; the cloud frame.
  • MCP (test_refusals.py): the server name in requests, connect to an api-2 pod, BP0030 on a tool, coded BP0001.
  • Coded fakes in the existing tests now assert .code / the class (i2c busy BP0003, wiring BP0009/BP0013). Request-shape tests strip the two new fields via tests/wire.py.

Docs: SDK README (error codes table, client API level, error classes), MCP README and guide, both CHANGELOGs under 3.0.6. No version bumps.

🤖 Generated with Claude Code

wardviaene and others added 4 commits November 19, 2026 16:50
From benchpod-firmware#191 (client-api-level): features.json gets api 1 and
min_client_api 0, the catalog gets BP0030 client_too_old.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
One table (errors._BY_CODE) maps every catalog code, BP0001 to BP0030, to its
exception class and fills the class's fields from the code's args. The text
patterns stay as the fallback for a reply without a code the SDK knows (older
firmware, a code newer than this SDK), each marked with what replaces it.
New WiringError (BP0007-BP0015) and ClientTooOldError (BP0030); BP0003-BP0005
and BP0016 are PodBusyError, BP0017 UnsupportedFeatureError with the feature
from its args. BP0001 keeps the SDK's own la voltage text. open_i2c's busy
rewrite keys on BP0003.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feature_map.CLIENT_API = 1 is the highest pod api the SDK handles; a test
ties it to the bundled table's api. protocol.encode_request (TCP, USB
network, the cloud tunnel, the pod lease, discovery probes) and the cloud
command channel add "client_api" and "client": "sdk <version>" to every
JSON command; the USB console's text protocol gets nothing. Capabilities
reads api and min_client_api (status, cloud frame). A pod above CLIENT_API
fails the connect with ClientTooOldError (the pin-direction read on connect
does the check, so no extra request), and so does BP0030. README and
CHANGELOG (3.0.6) describe the error codes and the client API level.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Requests carry "client": "mcp <version>" (embeddedci after 3.0.5). A pod
above this server's client API level (on connect) or its BP0030 refusal
reaches the agent as ClientTooOldError telling the user to update
embeddedci-mcp (uvx embeddedci-mcp@latest, pip install -U embeddedci-mcp, or
the benchpod plugin). A coded BP0001 keeps this server's la voltage text.
README, guide and CHANGELOG (3.0.6).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@wardviaene
wardviaene merged commit 6d70e62 into main Nov 20, 2026
20 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