embeddedci 2.2.0__tar.gz → 2.4.0__tar.gz

{embeddedci-2.2.0 → embeddedci-2.4.0}/CHANGELOG.md

@@ -1,6 +1,55 @@
 # Changelog — `embeddedci`
 
-## Unreleased
+## 2.4.0
+
+- **Breaking:** the 4-20 mA measurement terminal (J8) is now `"current_in"` as an ADC source
+  and analog path, and `lowlevel.cal_switch(current_in=...)` for its relay. The old name read as
+  "amplifier". Firmware 3.4.0 no longer accepts the old name, so `AdcSource` and
+  `AnalogPath` drop it without a major version. `adc_read("current_in")` also returns the loop
+  current in amps as `AdcReading.current`.
+- Calibration: `BenchPod.calibrate()` makes the pod measure the offset of its 4-20 mA input
+  (`current_in`, J8 disconnected) and store it in flash; `calibration()` reads it back and
+  `clear_calibration()` removes it. All three return a `Calibration` (`calibrated`, `offset` in
+  volts, the fit `a` / `b`). `adc_read("current_in")` has the offset taken out and reports it as
+  `AdcReading.offset`. New `CalibrateSource` and `Capabilities.calibrate`. Needs firmware 3.4.0.
+- 4-20 mA output: `BenchPod.current_out(amps)` holds a current on terminal J9 and returns a
+  `CurrentOutput` with the current actually held, the 16-bit DAC code and the range the output
+  can do; `current_out_range()` reads the range only. The pod converts and refuses a current
+  outside its range. The output is loop powered (it needs an external floating supply) and shares the DAC with the voltage outputs,
+  which `current_out` switches off. New analog path `"current_out"` and
+  `Capabilities.current_out`. Needs firmware 3.4.0.
+- Waveforms on the 4-20 mA output: `generate`, `replay` and `replay_waveform` take
+  `dac_path="current_out"` (`DacPath` gains it), with levels in amps and the range the pod
+  reports. Stopping the returned handle returns the loop to 4 mA.
+- Captures of the 4-20 mA input in amps: `capture_adc(source="current_in")` scales with the pod's
+  own fit and fills the new `Capture.currents`. `capture_correlated` takes `source` too, so the
+  loop current is captured next to the logic channels off one trigger. Such a capture replays as the same current on
+  `current_out`, and `save_capture_as_recording` stores it as a current. `Waveform.unit` says
+  whether a library entry is in `"V"` or `"mA"`; `WaveformLibrary.save_recording` takes `unit`,
+  and `save_segments` takes amps on the `current_out` path. Needs server support for the unit.
+- Motor & battery emulator: `BenchPod.open_motor_emulator()` returns a `MotorEmulator` for the
+  ECP5 emulator boards on the SPI link. It configures every board at once (`configure`, slave
+  SPI with PROGRAMN and DONE), reads and writes the link registers by name (`read`, `write`,
+  `broadcast=True`), and converts the common ones to units with an `EmulatorCalibration`: bridge
+  PWM and duties, sinc samples, protection and trips, the battery model (`BatteryModel`, OCV curve,
+  R0 / RC branch, state of charge), the back-EMF shape, the logging stream (`read_log` returns
+  whole sample sets) and the board EEPROM. Needs emulator gateware 0x0007+.
+- `SpiSession.stream(data, head=...)` sends data of any size in one CS frame through the pod's
+  PSRAM (`load_bin` staging, then the `spi_stream` command). New `SpiStreamResult` and
+  `Capabilities.spi_stream`.
+
+## 2.3.0
+
+- SPI master on the LA pins: `BenchPod.open_spi()` returns an `SpiSession` for raw full-duplex
+  transfers (`transfer`, CS held across calls with `hold_cs`) and SPI NOR flash work
+  (`flash_id`, `flash_read`, `flash_erase`, `flash_write`, `flash_program`).
+  `BenchPod.spi_flash(image, addr)` erases, writes and verifies a whole image in one call, and can
+  hold the DUT in reset while it runs (`hold_reset=True`). Pins come from the wiring profile
+  (`spi_sclk`, `spi_mosi`, `spi_miso`, `spi_cs`) or as arguments; up to 6 MHz, modes 0 and 3.
+  Needs firmware 3.3+ with gateware v45 (capability `spi_master`, new `Capabilities.spi_master`).
+  Works over the LAN, USB and the cloud.
+- pytest plugin: with `BENCHPOD_LIFT_DAC_LIMITS=1` a session fixture clears the pod's DAC output
+  limits for the run and writes the same limits back at the end, even when tests fail.
 
 ## 2.2.0
 

{embeddedci-2.2.0 → embeddedci-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: embeddedci
-Version: 2.2.0
+Version: 2.4.0
 Summary: BenchPod SDK and pytest plugin for EmbeddedCI hardware-in-the-loop testing
 Project-URL: Homepage, https://embeddedci.com
 Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
@@ -243,7 +243,7 @@ automatically.)
 * **Invalid arguments raise `ValueError`**. A `BenchPodError` subclass always means a device,
   transport or server failure — see [Errors](#errors).
 * **Device state is typed.** Methods return frozen dataclasses (`LaVoltage`, `TargetStatus`,
-  `PowerStatus`, `PullState`, `DacOutput`, `AdcReading`, …) from `embeddedci.benchpod.state`; each
+  `PowerStatus`, `PullState`, `DacOutput`, `CurrentOutput`, `AdcReading`, …) from `embeddedci.benchpod.state`; each
   keeps the untouched firmware reply in `.raw`.
 * **String options are `Literal` types** and are validated: `DacPath`, `DacOutputPath`,
   `AnalogPath`, `AdcSource`, `LoopSource`, `Waveshape`, `ReplayMapping`, `DecodeProtocol`,
@@ -504,7 +504,7 @@ how finely a transient was resolved. Measured on a v2 pod:
 | eFuse 2 (external) | 5-20 V on the external terminal | ≈ 3.0 A | ≈ 21.8 V | 167 µA |
 
 An overload is held at the limit for about 2.8 ms, then the eFuse trips (`TargetStatus` `fault`) and
-retries after ≈ 110 ms. A trip shorter than one sample does not show in a profile. The ADC's `amp`
+retries after ≈ 110 ms. A trip shorter than one sample does not show in a profile. The ADC's `current_in`
 input is a 4-20 mA loop terminal (249 Ω), not a way to measure the target's supply.
 
 ## Flashing
@@ -541,6 +541,65 @@ assert result.ok, result.stderr     # also: returncode, stdout, target_unreachab
   empties the target config's clock-boost reset events, which otherwise race the SWD link.
 * OpenOCD runs on the machine running the test, on every transport including the cloud.
 
+## SPI flash and SPI devices
+
+Pods with gateware v45+ (`bp.capabilities.spi_master`) run an SPI master on any four LA pins, up
+to 6 MHz, modes 0 and 3. Wire a 25-series SPI NOR flash (W25Q, MX25, GD25, ...) with its SCK, DI,
+DO and CS on LA channels (power it at the LA voltage, tie /WP and /HOLD high) and program it:
+
+```python
+res = bp.spi_flash("fw.bin", 0x0, sck=13, mosi=14, miso=6, cs=5, hold_reset=True)
+print(res.jedec_id, res.length, res.seconds)       # erased, written and verified
+```
+
+Or work with a session (pins from the wiring profile's `spi_sclk`, `spi_mosi`, `spi_miso`,
+`spi_cs` when omitted):
+
+```python
+with bp.open_spi(hz=6_000_000) as spi:
+    print(spi.flash_id())                          # SpiFlashInfo(jedec_id='ef4017', present=True, ...)
+    data = spi.flash_read(0x0, 4096)
+    spi.flash_erase(0x10000, 65536)
+    spi.flash_write(0x10000, payload)              # 768 B per command, each verified
+    rx = spi.transfer(b"\x9f\x00\x00\x00")        # raw full-duplex, for any SPI device
+```
+
+`hold_reset=True` holds the DUT in reset for the job (rev3 pods), so its own controller does not
+drive the same bus. The SPI master shares the SWD engine: an SWD flash cannot run while a session
+is open. Expect about 30 KB/s written (verified) over the LAN, less over the cloud.
+
+`spi.stream(data, head=b"...")` sends data of any size in one CS frame, write-only: it is uploaded
+into the pod's PSRAM first, then clocked out 512 bytes at a time (an FPGA bitstream into a
+slave-SPI configuration port). It needs a LAN or cloud connection and firmware with the
+`spi_stream` command (`bp.capabilities.spi_stream`).
+
+## Motor & battery emulator
+
+The BenchPod motor emulator boards (ECP5, up to four on one SPI link) are driven with
+`bp.open_motor_emulator()`. The SPI pins come from the wiring profile, as do `PROGRAMN` (open
+drain) and `DONE` (input) when it names them:
+
+```python
+from embeddedci.benchpod import BatteryModel
+
+with bp.open_motor_emulator() as emu:
+    emu.configure("emu.bit")                       # every board at once; waits for DONE
+    print(emu.probe(0))                            # BoardInfo(version=7, ...)
+    emu.set_protection(0, overcurrent_a=8, overvoltage_on_v=30, overvoltage_off_v=29)
+    emu.set_battery(BatteryModel(capacity_ah=2.0, ocv=[25.2, 23.4, 22.2, 18.0], r0_ohm=0.02))
+    emu.set_pwm(200_000)
+    emu.arm(0)
+    emu.set_control(0, pwm=True)
+    print(emu.sample(0).phase_currents, emu.battery_state(0).soc)
+    emu.start_log(["a", "bus"])
+    log = emu.read_log()                           # whole sample sets, sequence-checked
+```
+
+Every register of the link protocol is reachable by name with `emu.read("SPEED")` and
+`emu.write("KE", 1200, board=1)` (`motor_emulator.REGISTERS`); `broadcast=True` writes every
+board. Units use `EmulatorCalibration` (the design values unless you pass a bench calibration).
+Needs emulator gateware 0x0007 or later.
+
 ## UART
 
 `rx` is the LA channel the pod **samples** (wire the DUT's TX here); `tx` is the channel the pod
@@ -713,7 +772,8 @@ one step:
 | `"dac_3v3"`, `"dac_5v"`, `"dac_12v"` | route the DAC to that output (`dac_12v` is the bipolar ±12 V output) |
 | `"adc_ext"` | connect the ADC to the front SMA |
 | `"cal1"`, `"cal2"` | loop the 5 V / 12 V DAC output back into the ADC |
-| `"amp"` | read the amps terminal |
+| `"current_in"` | read the 4-20 mA measurement terminal |
+| `"current_out"` | the 4-20 mA output: switch the DAC voltage outputs off |
 | `"off"` | park everything |
 
 ```python
@@ -727,9 +787,94 @@ print(bp.adc_read("ext").voltage)          # the true front-SMA voltage (the ÷1
 ```
 
 `dac_output` takes calibrated volts (`"3v3"`, `"5v"`, `"12v"`, or `"off"`); without `volts` it only
-routes. `adc_read` routes the source (`"ext"`, `"cal1"`, `"cal2"`, `"amp"`) and returns one averaged,
+routes. `adc_read` routes the source (`"ext"`, `"cal1"`, `"cal2"`, `"current_in"`) and returns one averaged,
 calibrated reading; the pod refuses it while the input is still moving (e.g. a DAC left running).
 
+### Calibrating the 4-20 mA input
+
+`"current_in"` reads the 4-20 mA terminal (J8) across a 249 Ω resistor, so 4 mA is 0.996 V and 20 mA is
+4.98 V. Each pod is off by a few mV there. The pod can measure that offset itself and keep it in
+its flash:
+
+```python
+cal = bp.calibrate()                       # disconnect J8 first. Calibration(source, calibrated, offset, a, b, ...)
+print(cal.offset)                          # 0.004356: what the open input read, now taken out
+print(bp.adc_read("current_in").voltage)   # 0.0 with J8 still open
+print(bp.adc_read("current_in").current)   # loop current in amps: 0.004 to 0.020 for a live loop
+
+bp.calibration()                           # what the pod has stored
+bp.clear_calibration()                     # back to the built-in fit
+```
+
+Calibrate once per pod: it survives a reboot and a firmware update. The pod refuses
+(`BenchPodError`) when something is driving J8 (more than 50 mV) and keeps what it had. `a` and `b`
+are the fit the pod now uses for `current_in` (`volts = a + b * count`). Only the offset of `current_in` is
+calibrated; the other sources use the built-in fits. Needs firmware 3.4.0 (capability
+`calibrate`, `Capabilities.calibrate`).
+
+### The 4-20 mA output
+
+Terminal J9 is a two-wire 4-20 mA transmitter. `current_out` holds a current on it, in amps:
+
+```python
+out = bp.current_out(0.012)                # CurrentOutput(current, code, min_current, max_current)
+print(out.current)                         # 0.012: the current actually held (16-bit, 0.25 µA steps)
+print(out.min_current, out.max_current)    # 0.004056 0.020094 on a rev3 pod: what the output can do
+
+bp.current_out(0.004)                      # back to the live zero
+print(bp.current_out_range().max_current)  # the range only, nothing moves
+```
+
+- **It is loop powered.** J9 pin 1 (plus) goes to the plus of an external floating loop supply, pin 2
+  (minus) through your receiver to the supply minus. Use 8 V plus 20 mA times the loop
+  resistance, 30 V at most (24 V drives up to 800 Ω).
+- **The loop must float.** Pin 2 is not pod ground, and nothing in the loop may touch pod
+  ground: not the supply minus, and not a receiver that shares a ground with the pod (through
+  SWD or UART wiring to the same target). If it does, the current is no longer regulated.
+- **Do not wire J9 straight into J8.** The output cannot regulate that way.
+- The pod cannot see the loop. `current_out` succeeds with the supply off or the loop open.
+- The output cannot go below its live zero (a little above 4 mA) or above about 20.1 mA: there is no
+  0 mA and no 21 mA level. `0.004` gives the live zero. Anything else outside the range raises
+  `BenchPodError` with the pod's message. A value of 1 or more raises `ValueError` (amps, not mA).
+- **The DAC is shared** with the 3.3 V / 5 V / ±12 V outputs. `current_out` switches those off
+  first. `dac_output`, `generate` and `replay` also move the loop current. `dac_stop` leaves the
+  loop where it was: call `current_out(0.004)` to go back to 4 mA.
+- While DAC limits are set (an output stage), the pod refuses `current_out`.
+
+Waveforms work on it too. `generate`, `replay` and `replay_waveform` take
+`dac_path="current_out"`, and their levels are then amps:
+
+```python
+with bp.generate("sine", freq_hz=2, amplitude=0.006, offset=0.012, dac_path="current_out"):
+    ...                                    # 6 to 18 mA; leaving the block returns the loop to 4 mA
+
+ramp = [0.004 + 0.016 * i / 999 for i in range(1000)]
+bp.replay(ramp, dac_path="current_out", sample_rate_hz=1000)   # 4 to 20 mA in 1 s, looping
+
+loop = bp.capture_adc(4096, sample_rate_hz=100_000, source="current_in")
+print(max(loop.currents))                  # a capture of J8 carries the loop current in amps
+bp.replay(loop, dac_path="current_out")    # play the captured loop back on J9
+```
+
+- `generate` builds 8-bit levels: steps of about 63 µA. `replay` is 16-bit.
+- Stopping the returned handle returns the loop to 4 mA. A bare `dac_stop()` does not.
+- A capture or recording of a voltage has no current to reproduce: on `current_out` it needs
+  `mapping="fit"`, which stretches its shape over the output's range. The same holds for a
+  current recording (`Waveform.unit == "mA"`) on a voltage output.
+- In the cloud library, `save_capture_as_recording` stores a capture of `current_in` as a current
+  (`unit="mA"`), and `waveforms.save_segments(..., dac_path="current_out")` takes amps.
+- Below 400 kS/s a capture of `current_in` reads about 10 to 20 µA higher than `adc_read`.
+- The FPGA timing features work on the 4-20 mA terminals exactly as on the voltage ones, because
+  they are the same DAC and ADC: `capture_correlated(..., source="current_in")` captures the loop
+  current and the logic channels off one trigger, `on_capture=True` starts a current waveform at
+  the capture's t0, `stop_dac_after` freezes it (the loop then holds that current), and
+  `trigger=` starts a capture on an LA edge. There is one ADC and one DAC: a capture is the SMA
+  voltage or the J8 current, and the output is a voltage or a current, never both at once.
+
+The pod converts with a fit for its board revision (measured on one rev3 pod; the nominal part
+values on v2), the same on every pod of that revision: the output has no per-pod calibration.
+Expect a few tens of µA between pods. Needs firmware 3.4.0 or later (capability `current_out`, `Capabilities.current_out`).
+
 ## Captures
 
 Captures return data with the scaling applied: an ADC `Capture` holds **calibrated volts** (the
@@ -1192,7 +1337,7 @@ These sit below the stable API and are **not** covered by the stability promise:
   (raises `FirmwareError` when the pod refuses). Works over TCP, USB and the cloud.
 * `bp.transport` — the underlying transport object.
 * `bp.lowlevel` — individual analog switches and raw DAC codes for bring-up and diagnostics:
-  `dac_mux(ctrl1=, ctrl2=)`, `dac_mux_status()`, `cal_switch(cal1=, cal2=, amp_measure=, cal_path=)`,
+  `dac_mux(ctrl1=, ctrl2=)`, `dac_mux_status()`, `cal_switch(cal1=, cal2=, current_in=, cal_path=)`,
   `cal_switch_status()`, `dac_set(code, divider=)`. Prefer the named paths — these can leave the
   front end in a state no named path describes.
 

{embeddedci-2.2.0 → embeddedci-2.4.0}/README.md

@@ -205,7 +205,7 @@ automatically.)
 * **Invalid arguments raise `ValueError`**. A `BenchPodError` subclass always means a device,
   transport or server failure — see [Errors](#errors).
 * **Device state is typed.** Methods return frozen dataclasses (`LaVoltage`, `TargetStatus`,
-  `PowerStatus`, `PullState`, `DacOutput`, `AdcReading`, …) from `embeddedci.benchpod.state`; each
+  `PowerStatus`, `PullState`, `DacOutput`, `CurrentOutput`, `AdcReading`, …) from `embeddedci.benchpod.state`; each
   keeps the untouched firmware reply in `.raw`.
 * **String options are `Literal` types** and are validated: `DacPath`, `DacOutputPath`,
   `AnalogPath`, `AdcSource`, `LoopSource`, `Waveshape`, `ReplayMapping`, `DecodeProtocol`,
@@ -466,7 +466,7 @@ how finely a transient was resolved. Measured on a v2 pod:
 | eFuse 2 (external) | 5-20 V on the external terminal | ≈ 3.0 A | ≈ 21.8 V | 167 µA |
 
 An overload is held at the limit for about 2.8 ms, then the eFuse trips (`TargetStatus` `fault`) and
-retries after ≈ 110 ms. A trip shorter than one sample does not show in a profile. The ADC's `amp`
+retries after ≈ 110 ms. A trip shorter than one sample does not show in a profile. The ADC's `current_in`
 input is a 4-20 mA loop terminal (249 Ω), not a way to measure the target's supply.
 
 ## Flashing
@@ -503,6 +503,65 @@ assert result.ok, result.stderr     # also: returncode, stdout, target_unreachab
   empties the target config's clock-boost reset events, which otherwise race the SWD link.
 * OpenOCD runs on the machine running the test, on every transport including the cloud.
 
+## SPI flash and SPI devices
+
+Pods with gateware v45+ (`bp.capabilities.spi_master`) run an SPI master on any four LA pins, up
+to 6 MHz, modes 0 and 3. Wire a 25-series SPI NOR flash (W25Q, MX25, GD25, ...) with its SCK, DI,
+DO and CS on LA channels (power it at the LA voltage, tie /WP and /HOLD high) and program it:
+
+```python
+res = bp.spi_flash("fw.bin", 0x0, sck=13, mosi=14, miso=6, cs=5, hold_reset=True)
+print(res.jedec_id, res.length, res.seconds)       # erased, written and verified
+```
+
+Or work with a session (pins from the wiring profile's `spi_sclk`, `spi_mosi`, `spi_miso`,
+`spi_cs` when omitted):
+
+```python
+with bp.open_spi(hz=6_000_000) as spi:
+    print(spi.flash_id())                          # SpiFlashInfo(jedec_id='ef4017', present=True, ...)
+    data = spi.flash_read(0x0, 4096)
+    spi.flash_erase(0x10000, 65536)
+    spi.flash_write(0x10000, payload)              # 768 B per command, each verified
+    rx = spi.transfer(b"\x9f\x00\x00\x00")        # raw full-duplex, for any SPI device
+```
+
+`hold_reset=True` holds the DUT in reset for the job (rev3 pods), so its own controller does not
+drive the same bus. The SPI master shares the SWD engine: an SWD flash cannot run while a session
+is open. Expect about 30 KB/s written (verified) over the LAN, less over the cloud.
+
+`spi.stream(data, head=b"...")` sends data of any size in one CS frame, write-only: it is uploaded
+into the pod's PSRAM first, then clocked out 512 bytes at a time (an FPGA bitstream into a
+slave-SPI configuration port). It needs a LAN or cloud connection and firmware with the
+`spi_stream` command (`bp.capabilities.spi_stream`).
+
+## Motor & battery emulator
+
+The BenchPod motor emulator boards (ECP5, up to four on one SPI link) are driven with
+`bp.open_motor_emulator()`. The SPI pins come from the wiring profile, as do `PROGRAMN` (open
+drain) and `DONE` (input) when it names them:
+
+```python
+from embeddedci.benchpod import BatteryModel
+
+with bp.open_motor_emulator() as emu:
+    emu.configure("emu.bit")                       # every board at once; waits for DONE
+    print(emu.probe(0))                            # BoardInfo(version=7, ...)
+    emu.set_protection(0, overcurrent_a=8, overvoltage_on_v=30, overvoltage_off_v=29)
+    emu.set_battery(BatteryModel(capacity_ah=2.0, ocv=[25.2, 23.4, 22.2, 18.0], r0_ohm=0.02))
+    emu.set_pwm(200_000)
+    emu.arm(0)
+    emu.set_control(0, pwm=True)
+    print(emu.sample(0).phase_currents, emu.battery_state(0).soc)
+    emu.start_log(["a", "bus"])
+    log = emu.read_log()                           # whole sample sets, sequence-checked
+```
+
+Every register of the link protocol is reachable by name with `emu.read("SPEED")` and
+`emu.write("KE", 1200, board=1)` (`motor_emulator.REGISTERS`); `broadcast=True` writes every
+board. Units use `EmulatorCalibration` (the design values unless you pass a bench calibration).
+Needs emulator gateware 0x0007 or later.
+
 ## UART
 
 `rx` is the LA channel the pod **samples** (wire the DUT's TX here); `tx` is the channel the pod
@@ -675,7 +734,8 @@ one step:
 | `"dac_3v3"`, `"dac_5v"`, `"dac_12v"` | route the DAC to that output (`dac_12v` is the bipolar ±12 V output) |
 | `"adc_ext"` | connect the ADC to the front SMA |
 | `"cal1"`, `"cal2"` | loop the 5 V / 12 V DAC output back into the ADC |
-| `"amp"` | read the amps terminal |
+| `"current_in"` | read the 4-20 mA measurement terminal |
+| `"current_out"` | the 4-20 mA output: switch the DAC voltage outputs off |
 | `"off"` | park everything |
 
 ```python
@@ -689,9 +749,94 @@ print(bp.adc_read("ext").voltage)          # the true front-SMA voltage (the ÷1
 ```
 
 `dac_output` takes calibrated volts (`"3v3"`, `"5v"`, `"12v"`, or `"off"`); without `volts` it only
-routes. `adc_read` routes the source (`"ext"`, `"cal1"`, `"cal2"`, `"amp"`) and returns one averaged,
+routes. `adc_read` routes the source (`"ext"`, `"cal1"`, `"cal2"`, `"current_in"`) and returns one averaged,
 calibrated reading; the pod refuses it while the input is still moving (e.g. a DAC left running).
 
+### Calibrating the 4-20 mA input
+
+`"current_in"` reads the 4-20 mA terminal (J8) across a 249 Ω resistor, so 4 mA is 0.996 V and 20 mA is
+4.98 V. Each pod is off by a few mV there. The pod can measure that offset itself and keep it in
+its flash:
+
+```python
+cal = bp.calibrate()                       # disconnect J8 first. Calibration(source, calibrated, offset, a, b, ...)
+print(cal.offset)                          # 0.004356: what the open input read, now taken out
+print(bp.adc_read("current_in").voltage)   # 0.0 with J8 still open
+print(bp.adc_read("current_in").current)   # loop current in amps: 0.004 to 0.020 for a live loop
+
+bp.calibration()                           # what the pod has stored
+bp.clear_calibration()                     # back to the built-in fit
+```
+
+Calibrate once per pod: it survives a reboot and a firmware update. The pod refuses
+(`BenchPodError`) when something is driving J8 (more than 50 mV) and keeps what it had. `a` and `b`
+are the fit the pod now uses for `current_in` (`volts = a + b * count`). Only the offset of `current_in` is
+calibrated; the other sources use the built-in fits. Needs firmware 3.4.0 (capability
+`calibrate`, `Capabilities.calibrate`).
+
+### The 4-20 mA output
+
+Terminal J9 is a two-wire 4-20 mA transmitter. `current_out` holds a current on it, in amps:
+
+```python
+out = bp.current_out(0.012)                # CurrentOutput(current, code, min_current, max_current)
+print(out.current)                         # 0.012: the current actually held (16-bit, 0.25 µA steps)
+print(out.min_current, out.max_current)    # 0.004056 0.020094 on a rev3 pod: what the output can do
+
+bp.current_out(0.004)                      # back to the live zero
+print(bp.current_out_range().max_current)  # the range only, nothing moves
+```
+
+- **It is loop powered.** J9 pin 1 (plus) goes to the plus of an external floating loop supply, pin 2
+  (minus) through your receiver to the supply minus. Use 8 V plus 20 mA times the loop
+  resistance, 30 V at most (24 V drives up to 800 Ω).
+- **The loop must float.** Pin 2 is not pod ground, and nothing in the loop may touch pod
+  ground: not the supply minus, and not a receiver that shares a ground with the pod (through
+  SWD or UART wiring to the same target). If it does, the current is no longer regulated.
+- **Do not wire J9 straight into J8.** The output cannot regulate that way.
+- The pod cannot see the loop. `current_out` succeeds with the supply off or the loop open.
+- The output cannot go below its live zero (a little above 4 mA) or above about 20.1 mA: there is no
+  0 mA and no 21 mA level. `0.004` gives the live zero. Anything else outside the range raises
+  `BenchPodError` with the pod's message. A value of 1 or more raises `ValueError` (amps, not mA).
+- **The DAC is shared** with the 3.3 V / 5 V / ±12 V outputs. `current_out` switches those off
+  first. `dac_output`, `generate` and `replay` also move the loop current. `dac_stop` leaves the
+  loop where it was: call `current_out(0.004)` to go back to 4 mA.
+- While DAC limits are set (an output stage), the pod refuses `current_out`.
+
+Waveforms work on it too. `generate`, `replay` and `replay_waveform` take
+`dac_path="current_out"`, and their levels are then amps:
+
+```python
+with bp.generate("sine", freq_hz=2, amplitude=0.006, offset=0.012, dac_path="current_out"):
+    ...                                    # 6 to 18 mA; leaving the block returns the loop to 4 mA
+
+ramp = [0.004 + 0.016 * i / 999 for i in range(1000)]
+bp.replay(ramp, dac_path="current_out", sample_rate_hz=1000)   # 4 to 20 mA in 1 s, looping
+
+loop = bp.capture_adc(4096, sample_rate_hz=100_000, source="current_in")
+print(max(loop.currents))                  # a capture of J8 carries the loop current in amps
+bp.replay(loop, dac_path="current_out")    # play the captured loop back on J9
+```
+
+- `generate` builds 8-bit levels: steps of about 63 µA. `replay` is 16-bit.
+- Stopping the returned handle returns the loop to 4 mA. A bare `dac_stop()` does not.
+- A capture or recording of a voltage has no current to reproduce: on `current_out` it needs
+  `mapping="fit"`, which stretches its shape over the output's range. The same holds for a
+  current recording (`Waveform.unit == "mA"`) on a voltage output.
+- In the cloud library, `save_capture_as_recording` stores a capture of `current_in` as a current
+  (`unit="mA"`), and `waveforms.save_segments(..., dac_path="current_out")` takes amps.
+- Below 400 kS/s a capture of `current_in` reads about 10 to 20 µA higher than `adc_read`.
+- The FPGA timing features work on the 4-20 mA terminals exactly as on the voltage ones, because
+  they are the same DAC and ADC: `capture_correlated(..., source="current_in")` captures the loop
+  current and the logic channels off one trigger, `on_capture=True` starts a current waveform at
+  the capture's t0, `stop_dac_after` freezes it (the loop then holds that current), and
+  `trigger=` starts a capture on an LA edge. There is one ADC and one DAC: a capture is the SMA
+  voltage or the J8 current, and the output is a voltage or a current, never both at once.
+
+The pod converts with a fit for its board revision (measured on one rev3 pod; the nominal part
+values on v2), the same on every pod of that revision: the output has no per-pod calibration.
+Expect a few tens of µA between pods. Needs firmware 3.4.0 or later (capability `current_out`, `Capabilities.current_out`).
+
 ## Captures
 
 Captures return data with the scaling applied: an ADC `Capture` holds **calibrated volts** (the
@@ -1154,7 +1299,7 @@ These sit below the stable API and are **not** covered by the stability promise:
   (raises `FirmwareError` when the pod refuses). Works over TCP, USB and the cloud.
 * `bp.transport` — the underlying transport object.
 * `bp.lowlevel` — individual analog switches and raw DAC codes for bring-up and diagnostics:
-  `dac_mux(ctrl1=, ctrl2=)`, `dac_mux_status()`, `cal_switch(cal1=, cal2=, amp_measure=, cal_path=)`,
+  `dac_mux(ctrl1=, ctrl2=)`, `dac_mux_status()`, `cal_switch(cal1=, cal2=, current_in=, cal_path=)`,
   `cal_switch_status()`, `dac_set(code, divider=)`. Prefer the named paths — these can leave the
   front end in a state no named path describes.
 

{embeddedci-2.2.0 → embeddedci-2.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "embeddedci"
-version = "2.2.0"
+version = "2.4.0"
 description = "BenchPod SDK and pytest plugin for EmbeddedCI hardware-in-the-loop testing"
 readme = "README.md"
 requires-python = ">=3.10"

{embeddedci-2.2.0 → embeddedci-2.4.0}/src/embeddedci/benchpod/__init__.py

@@ -49,6 +49,7 @@ from .constants import (
     PIN13,
     PIN14,
     AdcSource,
+    CalibrateSource,
     AnalogPath,
     CanMode,
     DacOutputPath,
@@ -105,6 +106,8 @@ from .server_api import ServerApi, ServerApiError
 from .state import (
     AdcReading,
     AnalogPathState,
+    Calibration,
+    CurrentOutput,
     DacOutput,
     EfuseState,
     FpgaImageInfo,
@@ -118,6 +121,9 @@ from .state import (
     UsbCcStatus,
 )
 from .uart import UartCapture, UartSession
+from .spi import SpiFlashInfo, SpiFlashResult, SpiSession, SpiStreamResult
+from . import motor_emulator
+from .motor_emulator import BatteryModel, EmulatorCalibration, MotorEmulator
 from .waveforms import Waveform, WaveformLibrary
 from .wiring import Signal, Wiring
 
@@ -144,12 +150,23 @@ __all__ = [
     "AnalogPathState",
     "DacOutput",
     "AdcReading",
+    "Calibration",
+    "CurrentOutput",
     "FpgaImageInfo",
     "LoopState",
     # flash + UART
     "FlashResult",
     "UartCapture",
     "UartSession",
+    "SpiSession",
+    "SpiFlashInfo",
+    "SpiFlashResult",
+    "SpiStreamResult",
+    # motor & battery emulator
+    "motor_emulator",
+    "MotorEmulator",
+    "EmulatorCalibration",
+    "BatteryModel",
     # CAN
     "can",
     "CanBus",
@@ -222,6 +239,7 @@ __all__ = [
     "DacOutputPath",
     "AnalogPath",
     "AdcSource",
+    "CalibrateSource",
     "Waveshape",
     "ReplayMapping",
     "LoopSource",

{embeddedci-2.2.0 → embeddedci-2.4.0}/src/embeddedci/benchpod/capabilities.py

@@ -158,6 +158,16 @@ class Capabilities:
     nrst_pin: bool = False
     #: USB-C CC-line monitoring (rev3 pods): :meth:`BenchPod.usb_cc`.
     usb_cc: bool = False
+    #: SPI master on four LA pins and SPI NOR flash programming (gateware >= v45):
+    #: :meth:`BenchPod.open_spi`, :meth:`BenchPod.spi_flash`.
+    spi_master: bool = False
+    #: ``spi_stream``: send an upload staged in PSRAM through the SPI master in one CS frame
+    #: (an FPGA bitstream): :meth:`SpiSession.stream <embeddedci.benchpod.spi.SpiSession.stream>`.
+    spi_stream: bool = False
+    #: The pod can calibrate its own ADC and keeps the result: :meth:`BenchPod.calibrate`.
+    calibrate: bool = False
+    #: The pod can hold a current on its 4-20 mA output (J9): :meth:`BenchPod.current_out`.
+    current_out: bool = False
 
     #: LA I/O-bank voltage the pod currently reports (mV), if known.
     la_vccio_mv: int = 0
@@ -233,6 +243,10 @@ class Capabilities:
                 ("capture_b64", "capture_b64"),
                 ("nrst_pin", "nrst_pin"),
                 ("usb_cc", "usb_cc"),
+                ("spi_master", "spi_master"),
+                ("spi_stream", "spi_stream"),
+                ("calibrate", "calibrate"),
+                ("current_out", "current_out"),
             ):
                 if name in names and hasattr(c, attr):
                     setattr(c, attr, True)
@@ -282,6 +296,8 @@ class Capabilities:
             ("capture_trigger", "cap.capture_trigger"), ("power_profile", "cap.power_profile"),
             ("capture_b64", "cap.capture_b64"),
             ("nrst_pin", "cap.nrst_pin"), ("usb_cc", "cap.usb_cc"),
+            ("spi_master", "cap.spi_master"), ("spi_stream", "cap.spi_stream"),
+            ("calibrate", "cap.calibrate"), ("current_out", "cap.current_out"),
         ):
             b = _as_bool(params, key)
             if b is not None: