EmbeddedCI BenchPod

Open a BenchPod connection (closing any previous one and its sessions) and report status. Over the cloud the device is shared: this takes an exclusive lease, released by `disconnect` or after the server's idle timeout (the next tool call then reconnects).

Close UART/CAN sessions and the connection, releasing a cloud lease. Safe when not connected.

Takes no parameters.

Connection, firmware, capabilities, selected LA voltage and open sessions — with warnings for anything that will block the next steps (e.g. no LA voltage). Works when not connected.

Takes no parameters.

Select the LA I/O-bank voltage to match the DUT's I/O (1.8 V needs a rev3 pod). Required before flash, UART, LA capture, pull resistors or I2C-sensor emulation.

Which DUT signal is on which LA channel — call this first, before any channel argument. Returns the bench's effective profile: a 14-row pin table (what is wired to each channel and its bias resistor), the named signals, the target-power rail, the UART baud and the SWD target, plus warnings about risky wiring. Every tool whose channel, baud, rail or SWD arguments are omitted takes them from this profile, and channel arguments accept these names.

Takes no parameters.

Replace the wiring profile this connection uses (and optionally store it on embeddedci.com). The profile is validated first: two roles or signals on one LA channel, an out-of-range pin or an unknown key are rejected with a message naming every problem.

Switch the target's power rail on. The result says which rail was used.

Switch the target's power rail off. The result says which rail was used.

Measure the DUT's supply current and voltage for a window: average, minimum and peak current, voltage, energy and charge (gap-free sampling, so energy is integrated, not estimated). Use this for a self-contained window (a boot, a sleep interval). To profile across other tool calls, bracket them with power_profile_start / power_profile_stop.

Start sampling the target-power rail in the background, then run the steps you want to profile and call power_profile_stop. Replaces any profile already running.

Stop the running power profile and return its statistics (and, with points, a trace).

Both target-power rails, internal 5 V (efuse 1) and external (efuse 2): on/off and tripped state, bus voltage and current draw.

Takes no parameters.

Drive the DUT's reset line from the pod's reset pin (rev3 pods, DUT header J1 pin 22).

Read the JEDEC ID of the SPI NOR flash on the SPI pins (gateware v45+, capability spi_master). present=false means the ID read all 00 or all FF: nothing is answering (wiring, power, or /WP and /HOLD not tied high). The pins are released again afterwards.

Erase, write and verify an image into the SPI NOR flash wired to the SPI pins. 25-series parts, first 16 MB. Throughput is roughly 30 KB/s over the LAN (erase is extra) and slower over the cloud. Fails with the pod's message when nothing answers, the part is write-protected, or a chunk does not verify.

Read bytes back from the SPI NOR flash, to a file or (up to 4096 bytes) as hex.

One full-duplex SPI transaction (CS asserted for all of tx) with any SPI device on the SPI pins. Returns what came back on MISO. The SPI master is armed for the call and released after it.

Program the DUT over SWD through the pod's CMSIS-DAP probe. Give either `file` (a path on this server's host) or an uploaded build (`build`, or `repo`/`ref` for the newest build of a branch). OpenOCD runs on this server's host, except for an uploaded build on a cloud connection, which embeddedci.com flashes itself. The SWD pins, the reset flag and the target config come from the wiring profile when omitted. A failed flash is a normal result (ok=false): read target_unreachable (unpowered, mis-wired or held in reset), stalled, and the log tails to decide what to change; `artifact` says which build was flashed.

Record the DUT's UART output for a fixed window (or until until_regex matches). The channels and baud come from the wiring profile when omitted.

Power the target off, then capture UART while it powers back on — the boot banner lands in the window. The channels, baud and power rail come from the wiring profile when omitted.

Start buffering the DUT's UART in the background (replacing any open session). Open it BEFORE an action whose output matters (power_on, reset_target), then uart_read; use uart_write to type into the DUT's console. The channels and baud come from the wiring profile when omitted; the result says which were used. A channel used as GPIO must be released first (gpio_release).

Send text to the DUT's RX through the open UART session.

Return the UART output received since the previous uart_read, optionally waiting for a match.

Stop the background UART session (safe when none is open).

Takes no parameters.

Make the pod act as an I2C sensor on sda/scl for the DUT to read. Engage pull-ups on both lines first (set_pull). The channels come from the wiring profile when omitted. Readings start at the model's defaults; seed them with temperature_c/pressure_pa or values.

Change what the emulated sensor reports (at least one value); the reply lists every reading.

The sensor models the pod can emulate, with their addresses and settable readings (key, unit, range, default).

Takes no parameters.

Disarm the emulated sensor (safe when none is active).

Takes no parameters.

Emulated sensor state plus bus activity counters — did the DUT talk to it at all?

Takes no parameters.

Read the emulated sensor's register image.

Capture and decode the emulated sensor's I2C bus into a transaction trace (S/Sr/P, addr, data, ACK).

Make the pod play a GPS module: NMEA sentences (u-blox style, 9600 baud, 1 Hz by default) on tx for the DUT's UART. It runs on a second UART, so uart_open keeps working for the DUT's console. The position moves along course_deg at speed_kmh between fixes. Needs gateware v48 ("gps" in status caps).

Change the fix the emulated GPS prints (any subset); the next sentences carry it.

Stop the GPS receiver and release its pin (safe when none runs).

Takes no parameters.

The GPS receiver's session (tx, baud, rate, epochs, overruns) and the fix it prints.

Takes no parameters.

Engage or release the fixed bias resistors: LA1-LA6 pull UP (I2C lines), LA7/LA8 pull DOWN. The resistors are 3V3-referenced, so the pod refuses to engage them with the LA bank at 1.8 V.

Read the pod's USB network setting (firmware 3.9.0+), or turn the adapter off. Only the device changes it: Ethernet, Wi-Fi and the cloud may only read it.

The pod's LAN API over TLS (firmware 3.9.3+): port 8443, HTTPS-only, and the certificate clients pin (sha256). Connections to a network address use TLS by default when the pod has it. Installing your own certificate: `benchpod lan-tls set-cert` or the SDK's set_lan_tls_cert.

State, direction and value of the bias resistor on LA1-LA8.

Takes no parameters.

What owns each of the 14 LA channels — none (free), gpio, uart_rx/uart_tx, swd_clk/swd_dio, i2c_sda/i2c_scl or step — plus each channel's GPIO mode, commanded level and bias resistor. Read this when a tool is refused with a pin conflict: it names the owner to stop. Live pin levels come along when the gateware can read them. Captures observe every channel whatever owns it.

Takes no parameters.

Claim LA channels as GPIO so the pod can drive or read them. A channel stays GPIO — across disconnects — until gpio_release, and while it is GPIO nothing else can use it: release it before uart_open, flash or enable_i2c_sensor on that channel. A channel already owned by another function is refused with a PinConflictError naming the owner and the tool that frees it, and an engaged bias resistor that would fight the mode with a PullConflictError.

Set the level of GPIO output / open-drain channels (all of them in one pod command). The channels must already be in an output or open_drain mode (gpio_mode).

The live level (0/1) of LA channels — omit `la` for all 14. Works whatever owns a channel; a GPIO input is the usual way to watch a DUT output.

Wait until an LA channel reads `level` (reached=false when the timeout passes first). Polled from this host, so it resolves to a few milliseconds plus the round trip — for precise timing use a triggered capture (capture_la trigger_la) and la_timing instead.

Emit FPGA-timed pulses on an LA channel — a trigger for the DUT, or a step/dir motor train. The channel must be free or a GPIO output at level 0 (it returns to its GPIO level afterwards). The FPGA runs the train by itself, so this returns as soon as it starts.

Stop using channels as GPIO — they go back to high-Z, watched by captures. Omit `la` to release every GPIO channel (channels owned by other functions are left alone). Do this before starting a UART session, flashing or emulating a sensor on those channels.

Set every analog mux and relay for a named path in one step. dac_3v3/dac_5v/dac_12v route the DAC to an output; adc_ext connects the ADC to the front SMA; cal1/cal2 loop the 5 V/12 V DAC output back into the ADC; current_in reads the 4-20 mA input (J8); current_out switches the DAC voltage outputs off for the 4-20 mA output (J9); off parks everything. range also sets the ADC input range (see adc_range); off and cal2 put it back to normal.

Read or switch the ADC input range (analog module v3r4 and later, firmware 3.9.5+). normal is the ÷12 divider: ±32.8 V, about 1 mV per count. low is ÷2: ±5.46 V, about 167 µV per count, 6x the resolution for signals up to ±5 V. The low range's input is 1.82 MΩ: tell the user to use 1x leads, not a 10x scope probe. It applies to ext, cal1 and current_in (not cal2), and stays until changed, analog_path off or cal2, or a pod restart. capture_adc and adc_read scale with the range in use. A board without the low range refuses low. Use low for small signals; switch back to normal when a reading or capture reports overrange.

Route a DAC output (3v3, 5v, 12v = ±12 V, or off) and drive a calibrated DC voltage on it.

Hold a current on the 4-20 mA output (terminal J9), in amps, or read the range it can do. The output is loop powered: it needs an external floating supply on J9 (pin 1 plus to the supply plus, pin 2 through the receiver to the supply minus; 8 V plus 20 mA times the loop resistance, 30 V at most). Nothing in the loop may touch pod ground, also not through a target that shares a ground with the pod. Ask the user how J9 is wired before driving it. Never wire J9 straight into J8. The pod cannot see the loop: the call succeeds with the supply off. It cannot go below its live zero (a little above 0.004 A) or above about 0.0201 A: there is no 0 mA or 21 mA level. 0.004 gives the lowest current; anything else outside the range fails with the pod's message. The DAC is shared: this switches the 3v3/5v/12v outputs off, and dac_output, generate and replay also move the loop current. dac_stop leaves the loop where it was: set 0.004 to go back to 4 mA.

One calibrated voltage: ext = front SMA (true volts), cal1/cal2 = DAC loopbacks, current_in = 4-20 mA input (J8). current_in also returns current, the loop current in amps. range low reads small signals (up to ±5.46 V) at 6x the resolution on analog module v3r4+; overrange says the input clipped. Refused while the input is still moving (e.g. a DAC output left running).

The calibration the pod has stored: the ADC offset (measured on current_in, terminal J8) and the fit it uses, and on firmware 3.9.4+ the DMM-guided parts (dac: a line per DAC output, adc_gain_ppm: a gain per ADC source). calibrated=false means the pod has no ADC offset: analog readings can be off by up to about 50 mV.

Takes no parameters.

Calibrate the pod's ADC offset on its 4-20 mA input (current_in, terminal J8) and store it on the pod. Nothing may be connected to J8: ask the user to disconnect it and confirm before calling. The pod reads its open input (0 V) and keeps that offset in flash. Every later adc_read on current_in has it taken out, and on firmware 3.9.3+ every other ADC source and capture too (they share the front end). Once per pod is enough: it survives reboots and firmware updates. The pod refuses, and keeps what it had, when something is driving J8 (more than 150 mV; 50 mV before 3.9.3). clear=true removes the stored calibration (all of it, or clear_part only).

Store this pod's own line for a DAC output from two DMM readings (firmware 3.9.4+, cap cal_dmm). The flow, with the user holding a bench DMM: ask them to disconnect the DUT from the output and put the DMM (DC volts) on that output's SMA. Drive each set point with dac_output(path, volts) and keep its code16 (3v3: 0.5 and 3.0 V, 5v: 1.0 and 4.0 V, 12v: -5 and +5 V), ask the user what the DMM reads, then call this with both points and switch the output off (dac_output path off). From then on dac_output, generate and the DAC output limits use this line. The pod refuses, and keeps what it had, when the codes are too close, a reading is far from what the output should give (DMM on the wrong SMA) or the gain is more than 2 % off.

Measure and store an ADC source's gain against a DMM-calibrated DAC output (firmware 3.9.4+). Needs the ADC offset (calibrate) and the driving output's DMM line (calibrate_dac on 5v for cal1, 12v for cal2 and ext). For ext, ask the user to connect the SMA cable first. The pod drives two set points itself and switches the outputs off afterwards; measured says what it saw. Nothing to read on a DMM.

Capture the ADC and summarise it: calibrated stats, dominant frequency and a min/max envelope. source current_in captures the 4-20 mA input (J8): the stats are then the loop current in amps (unit "A"), and replay(from_last_capture=true, dac_path="current_out") plays it back as a current. Above 32768 samples the capture streams from PSRAM (multi-second captures work). With trigger_la the capture waits for that edge or level, so t = 0 is the trigger moment. The capture is kept for replay and save_capture_as_recording. range low captures small signals (up to ±5.46 V) at 6x the resolution (see adc_range); clipped_samples > 0 means it clipped. oversample suits measuring small or near-0 V signals at low rates; the result's oversample says how many conversions each sample averages, and it fails if they do not fit in the pod's memory.

Capture all 14 LA channels and summarise each: levels, edge count, first edge, estimated frequency. With trigger_la the capture starts on that edge or level instead of immediately, so a short event can be caught at a high sample rate. The capture is kept for decode_la and la_timing. sample_rate_hz goes up to 12 MS/s, or 48 MS/s on gateware v50+ (48, 24 or 16 MS/s); above 12 MS/s a signal changing over ~6 million times per second for long stops early (truncated); retry at 12 MS/s.

ADC and LA captured from one hardware trigger, so their timebases align. Both are kept. With trigger_la both streams start on that edge or level. There is one ADC: the analog half is the SMA voltage or, with source current_in, the loop current on J8 (unit "A"), never both.

Decode I2C (sda, scl), UART (rx, baud) or SPI (sclk + mosi/miso/cs, mode) from LA data. Sample at least ~10x the bit rate. Decoding the last capture again with other channels is free.

Timing of one channel of the last capture_la / capture_correlated: edge timestamps, pulse widths, frequency and duty cycle; with to_la, the delay from its first edge to the next edge on to_la (e.g. a trigger pin to a "result ready" pin). Resolution is one sample; no new capture is taken.

Drive a sine, square or sawtooth on a DAC output. On firmware 3.9.1+ the pod takes the volts, calibrates them for dac_path and plays the waveform at the DAC's full 16 bits (bits=16 in the result); both peaks must then be on the path. Older firmware builds it from 8-bit levels (bits=8): 256 steps over the path. dac_path current_out plays it as a current on the 4-20 mA output (J9), with amplitude and offset in amps and steps of about 0.25 uA (63 uA on older firmware). See current_out for the wiring it needs. The DAC voltage outputs are switched off for it. dac_stop then leaves the loop where the waveform stopped: call current_out(0.004) to go back to 4 mA.

Stop any DAC output: generator, replay or control loop. The 4-20 mA output follows the DAC, so after a waveform on current_out the loop stays where it stopped: call current_out(0.004) to return it to 4 mA.

Takes no parameters.

Loop a waveform out of the DAC until dac_stop — agent-provided volts or the last ADC capture. More than 2048 samples need the deep_replay gateware image, switched to automatically. dac_path current_out replays on the 4-20 mA output (J9) in amps. A last capture of current_in replays as the same current; a capture of a voltage source there needs mapping fit. See current_out for the wiring. After dac_stop, call current_out(0.004) to go back to 4 mA.

The organisation's cloud waveform library (needs a cloud connection or BENCHPOD_API_KEY).

Takes no parameters.

The BenchPods registered to your embeddedci.com organisation, and whether each is online. Drive one with connect(connection) using the returned `connection` ('embeddedci:<name>'). Needs no pod connection. Authenticates with BENCHPOD_API_KEY, else the session saved by `benchpod login` (~/.config/benchpod-cli/token.json), refreshing it when it has expired.

Takes no parameters.

Loop a cloud-library waveform out of the DAC until dac_stop (needs server access). A recording too long for a shallow replay switches the pod to the deep_replay gateware image (unless target_samples asks for a downsampled replay). dac_path current_out replays on the 4-20 mA output (J9). A recording with unit mA replays there as the same current; a recording in V there, or a mA recording on a voltage output, needs mapping fit. After dac_stop, call current_out(0.004) to go back to 4 mA.

Save the last capture_adc to the cloud waveform library as a replayable recording. A capture of current_in (the 4-20 mA input) is stored as a current, unit mA; full_scale_v is then in mA too.

Run a tabulated transfer function in the FPGA: each tick out = curve[input], damped and clamped. Needs the loop gateware image, switched to automatically. Poll with loop_probe, move the input with loop_input, stop with dac_stop.

Re-target the running loop's input without re-arming (hold a point, meter, move on).

The running loop's live operating point; assert against loop_input, not i, in open-loop runs.

Takes no parameters.

Reprogram the pod's FPGA with another stored gateware image (~2-3 s). Rarely needed: control_loop, replay and replay_waveform switch automatically. The switch resets the FPGA (any DAC output, UART session or I2C sensor emulation stops).

Bring up the pod's CAN interface (replacing any open CAN session).

Queue one classic CAN frame.

Read received CAN frames (id, data, timestamps in pod milliseconds).

Make the pod firmware answer a CAN id instantly (ECU simulation), or clear all rules.

CAN link state: mode, bitrate, error counters, bus-off.

Takes no parameters.

Clear responder rules and stop CAN (safe when not open).

Takes no parameters.

Emit step pulses on an LA channel (step/dir motor drivers); with dir_la, set direction first. The step rate is 1 / (2 x delay). The FPGA runs the train by itself; this returns as soon as it starts. More than 65535 steps: send several trains (wait for the pod between them).

Escape hatch for firmware commands no tool covers. Prefer the dedicated tools.

Open the AI Vision connection (closing a previous one) and report the board's status.

The AI Vision boards registered to your embeddedci.com organisation, and whether each is online. Connect to one with vision_connect(connection) using its `connection` ('embeddedci:<name>'). Authenticates with BENCHPOD_API_KEY, else the `benchpod login` session.

Takes no parameters.

Close the AI Vision connection and release its lease. Safe when not connected.

Takes no parameters.

Version, calibration, camera lock, actuators, lease and capabilities, with warnings for what will block the next steps.

Takes no parameters.

The screen as an image, so you can read it yourself. With a region: that part at full sensor resolution (small text, icons).

All text on the screen (or a region) in reading order, with boxes.

Elements matching text, a kind or a template, best first. Text inside a button returns the button (its center is where a press taps).

Wait until text appears (or, with gone, disappears). Returns met=false on timeout.

How close the screen is to a stored reference screen.

Black, dim, frozen, flickering or stuck pixels over a window of frames.

Map camera pixels to screen pixels; every later box and tap is in screen pixels.

Store the current screen (or a region of it, e.g. an icon as a template) as a reference.

Find the element, tap its center with the actuator, and optionally verify the result. Fails with the visible text when the element is not on the screen.

Tap a point in screen pixels (hold_ms > 0 for a long press).