Repository navigation
SDK + MCP: classify pod errors by code, client API level (client_api, ClientTooOldError) - #129
Merged
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:FirmwareError(message stays the SDK's_LA_VOLTAGE_SDK; MCP keeps its own text)UnsupportedFeatureErrorfeature=cmdPodBusyErrorPodBusyErrorFirmwareErrorWiringError(FirmwareError)namePodBusyError(its text, "busy: ...", already gave this class)UnsupportedFeatureErrorfeature=featureFirmwareError(no ValueError-likeFirmwareErrorsubclass exists)PullDirectionErrorla,want,havePodLeasedErrorholder,purpose,left_sPodLeaseLostErrorbyFirmwareError(pod_lease checks the code)FirmwareErrorClientTooOldError(FirmwareError)client_api,min_client_api,apiClientTooOldErroris deliberately not anUnsupportedFeatureError: 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'sapi.protocol.encode_request(TCP, USB network, cloud byte tunnel, pod lease, the discovery probes) and the cloud command channel add"client_api": 1and"client": "sdk <version>"(MCP:"mcp <version>") to every JSON command. The USB console text protocol and SCPI get nothing.Capabilitiesreadsapi/min_client_api(status,cap.*frame);client_api_levelcounts a pod withoutapias 1. A pod aboveCLIENT_APIfails the connect withClientTooOldError(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 turnsClientTooOldErrorinto 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
errors.pynames its replacement (BP0001, BP0002, BP0017, BP0025, BP0016).busy:,forbidden:, the digital board without analog, "reply too large" (client.pyla_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"..codeand 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_textstill rewritesfirmware_messagefor refusals without a code; coded ones use the catalog'smcpfix.Needs
benchpod-firmware#191 (
client-api-level) for theapi/min_client_apifields and BP0030. Bundledfeatures.jsonanderrors.jsonare synced from that branch. This works with older firmware: it ignores the new request fields, and a pod withoutapicounts 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 withBENCHPOD_FIRMWARE_DIRpointing at the firmware branch, becausetest_bundled_copy_matches_the_firmwarecompares against the sibling checkout.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.test_client_api.py(15):CLIENT_APIequals the bundledapi;client_api/clientare 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.test_refusals.py): the server name in requests, connect to an api-2 pod, BP0030 on a tool, coded BP0001..code/ the class (i2c busy BP0003, wiring BP0009/BP0013). Request-shape tests strip the two new fields viatests/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