Skip to content

SDK + MCP 4.0: code-only errors, client API 2, TLS by default, firmware 4.0 names, removals - #130

Merged
wardviaene merged 10 commits into
mainfrom
sdk-4.0
Nov 20, 2026
Merged

wardviaene merged 10 commits into
mainfrom
sdk-4.0

Conversation

@wardviaene

Copy link
Copy Markdown
Member

Breaking SDK + MCP 4.0 for BenchPod firmware 4.0.0. Pairs with embeddedci-com/benchpod-firmware#192 (branch fw-3.11-cutover, built against c5107d3: features table revision 11, error catalog BP0001 to BP0080). No version bumps and nothing published: the release PR does that; the CHANGELOG text is ready under 4.0.0.

Breaking changes (CHANGELOG 4.0.0)

Firmware 4.0 only

  • CLIENT_API = 2 (a test ties it to the bundled table's api). A pod below client API 2 (firmware 3.x) raises the new FirmwareTooOldError on connect, saying to update the pod with benchpod flash-self or the web app, or to stay on embeddedci 3.x. The USB console decides by firmware version. The SDK has no firmware-update commands of its own.
  • Features come from the features table only: no caps list, no status with "caps":false, no version fallbacks. Capabilities.sensors_format, the signal alias and Transport.status_without_caps() are gone. diag() sends diag only.
  • The USB console path does status and ping only (firmware 4.0's console); LA voltage, power, SWD and the UART proxy point at usb or a network address.

Refusals by code only

  • Every catalog code BP0001 to BP0080 maps to an exception class with fields from its args; the message is the catalog's message plus fix.sdk (MCP: fix.mcp). A coded reply without message renders fully. Text patterns, raw-command rewrites, status_too_large, la_pins_too_large and STATUS_FITS_FIRMWARE are gone. A refusal without a code keeps its text.
  • New ReplyTooLargeError (BP0053, BP0054), DacPinoutMismatchError (BP0080, digital, module); PinConflictError gains owner, instance. Cloud retry keys on BP0052.
  • ModuleInfo.dac_pinout_ok; MCP status warns when it is false.

TLS by default

  • A LAN address without a port means 8443 over TLS (pinned on first use); no plaintext fallback. Plaintext 8080 only on the USB network adapter (10.237.x) or an explicit :8080. mDNS reads api, tls, https_only from TXT, connects to the TLS port and refuses firmware 3.x. trust_lan_tls and the pin helpers default to 8443.

Firmware 4.0 wire names (public SDK names unchanged)

  • sample_rate_hz / adc_sample_rate_hz / la_sample_rate_hz in hertz, freq_hz, clock_hz, dac_out v and code16, loop code16, can_start/can_stop, ts_ms, booleans for target_power, target_status, usb_network and status.usb, la_step/la_pull, power profile sample_rate_hz. generate sends volts only (path + amplitude_v/offset_v, or _ua). Captures take the default base64 (enc:"dec" only for a transport without chunks).

Removed (approved)

  • set_pull boolean form and enabled= (the four pull shortcuts stay), REFERENCE_BENCH, PRESET_ALIASES, "embeddedci-reference", Wiring.defaults(), PULL_OHMS/PULLUP_CHANNELS/PULLDOWN_CHANNELS (use PULL_TABLE), RP_VID, the serial connection keyword, bench_pod_addr, a numeric upload reset input, CanBus.expect/read_until(can_id=).

MCP

  • Seconds parameters end in _s (delay_s, duration_s, timeout_s, trigger_timeout_s, stop_dac_after_s, width_s, pulse_s, off_settle_s, max_duration_s, lease_wait_s); the I/O voltage is la_voltage; set_pull(la, pull); replay takes waveform_id (no replay_waveform tool); usb_network(enabled=false) returns enabled; generate returns no bits. Instructions updated. Tool surface snapshot refreshed.

What must change elsewhere

  • examples (process-node-stm32/tests/test_alarms.py, test_can_hil.py): expect(can_id=X) / read_until(can_id=X) become expect(X) / read_until(X); the embeddedci>=2.0 notes in scenario-sensors-stm32/tests/conftest.py and selftest-stm32/e2e_local.py become 4.0. Any host:8080 connection string: drop the port.
  • openhtf: now embeddedci>=4.0.0,<5 (done here; no release). The MCP package pins the same.
  • plugin: the MCP instructions changed (FirmwareTooOldError, set_pull(la=...), replay with waveform_id, _s parameters); refresh any copied tool docs.
  • firmware catalog: fix.mcp texts still name set_pull(las=[...]); the tool now takes la. Needs a catalog edit in benchpod-firmware.
  • CI: the mcp-min-sdk job installs the minimum SDK from PyPI, so it fails until embeddedci 4.0.0 is published.

How tested

  • make test (fakes only, no hardware): SDK 1212 passed, MCP 210, openhtf 74, scripts 12, with BENCHPOD_FIRMWARE_DIR pointing at the firmware worktree (bundled table and catalog match byte for byte).
  • New tests: api<2 refusal (LAN, console, mDNS, MCP), TLS default port choice and no fallback, one coded reply without a message per catalog code (test_error_codes.py), the JSON sent for every renamed command (test_wire_names_4.py), the removals. Test fakes written for 3.x statuses are read as 4.0 by tests/conftest.py.
  • Not run on hardware.

🤖 Generated with Claude Code

wardviaene and others added 10 commits November 19, 2026 22:08
CLIENT_API is 2. A pod below client API 2 (firmware 3.x) raises the new
FirmwareTooOldError on connect, with the firmware update to run (the USB
console decides by firmware version). Every legacy path for firmware
without the features table is gone: the caps list, status caps:false,
version fallbacks (la_dir, bus master, diag), the pullup form of pulls,
the 8-bit generate, the la_pins subset fallback and the console's
la-voltage/power/dap/uart text commands. Firmware 4.0 split la into
la_pull and la_step, sends captures as base64 by default and takes
generate in volts with freq_hz/sample_rate_hz; the SDK follows.

Features table synced to revision 11. Test fakes written for 3.x statuses
are read as 4.0 by tests/conftest.py; tests of removed paths are gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Firmware 4.0 sends a code and its args with no message (BP0030 alone
keeps one). The SDK and the MCP server never read a refusal's text
any more: the text patterns, the raw-command rewrites, the la voltage
text, status_too_large and la_pins_too_large are gone, and the client's
i2c busy, reply too large, no module link and unknown sensor instance
checks, and the cloud's device busy retry, use the codes. Every code
BP0001 to BP0080 maps to an exception class with fields from its args
(new ReplyTooLargeError, DacPinoutMismatchError; PinConflictError gets
owner and instance); messages come from the catalog (fix.sdk, MCP
fix.mcp). A refusal without a code keeps its text as it is.

Error catalog synced (BP0080 dac_pinout_mismatch). ModuleInfo has
dac_pinout_ok; the MCP status warns when it is false.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Firmware 4.0 serves the JSON API on Ethernet and Wi-Fi over TLS only.
A network address without a port now means 8443 over TLS (pinned on
first use); plaintext 8080 only on the USB network adapter (10.237.x)
or when the address names :8080, with a hint when that fails. The
TLS-then-plaintext probe is gone. The usb LAN fallback uses TLS. mDNS
discovery reads api, tls and https_only from the TXT record, connects
to the TLS port and refuses a pod with firmware 3.x.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rates in hertz (sample_rate_hz, adc_sample_rate_hz, la_sample_rate_hz,
freq_hz), clock_hz for the I2C and SPI masters, dac_out v with code16
replies, code16 in the loop replies, can_start/can_stop and ts_ms,
booleans for target_power, target_status and usb_network, and
power_profile sample_rate_hz. test_wire_names_4.py asserts the JSON
sent for each renamed command and the renamed reply fields read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SDK: set_pull takes a direction only (no True/False, no enabled=);
REFERENCE_BENCH, PRESET_ALIASES, the embeddedci-reference preset and
Wiring.defaults() are gone, as are PULL_OHMS, PULLUP_CHANNELS,
PULLDOWN_CHANNELS (PULL_TABLE stays), RP_VID, the serial connection
keyword, the bench_pod_addr config key, a channel number as the
upload reset input, and CanBus.expect/read_until can_id=.

MCP: every seconds parameter ends in _s, the I/O voltage is la_voltage,
set_pull takes la and pull, replay takes waveform_id (replay_waveform
is gone), usb_network takes and returns enabled. Tool surface
snapshot refreshed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The hardware run of #130 against the 4.0 candidate failed only in e2e
tests written for 3.x: set_pull booleans, a refusal text assert (now
BP0031 code and fields), the raw measure command (freq_hz, enc dec),
the BP0039 trigger edge (the SDK names it start, documented), and the
console tier (status and ping only). The USB console now runs the
firmware version check on connect like the other transports, and its
network-only refusals all say it is a network command.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…pt it

The MCP and OpenHTF need SDK 4.0, and CI installs them next to the SDK from
this tree: a dev version lets that install work before 4.0.0 is published.
The release PR sets 4.0.0 and the pins to >=4.0.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@wardviaene
wardviaene merged commit 2712fe5 into main Nov 20, 2026
16 of 20 checks passed
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