embeddedci 2.13.2__tar.gz → 2.13.4__tar.gz

{embeddedci-2.13.2 → embeddedci-2.13.4}/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog — `embeddedci`
 
+## 2.13.4
+
+- The ADC input range (pod firmware 3.9.5+, analog module v3r4, `Capabilities.adc_low_range`):
+  `BenchPod.adc_range(range=None)` reads or switches it (`"normal"` ±32.8 V, `"low"` ±5.46 V at
+  about 6x the resolution), `adc_range_test()` self-tests it through the cal1 loopback, and
+  `analog_path`, `adc_read`, `capture_adc` take `range=`. `calibrate_adc_gain("cal1", range="low")`
+  measures the low range's gain (`Calibration.adc_low_gain_ppm`). Captures scale with the fit of
+  the range in use: the SDK re-reads it whenever a reply says the pod changed range.
+  `AdcReading` gains `range`, `fullscale`, `overrange`; `Capture` gains `range`, `overrange`,
+  `clipped_samples`; `AnalogPathState.range`; `Capabilities.adc_range`, `adc_range_fullscale`.
+  New types `AdcRange`, `AdcRangeState`, `AdcRangeTest`, `AdcRangeTestPoint`.
+- `capture_adc(source="current_in")` reads the pod's `current_in` fit after routing, so it is the
+  fit of the range in use.
+
+## 2.13.3
+
+- The DMM-guided calibration (pod firmware 3.9.4+, `Capabilities.cal_dmm`):
+  `BenchPod.calibrate_dac(path, points)` stores this pod's own line for a DAC output from two
+  `(code16, volts)` DMM readings, `calibrate_adc_gain(source)` measures an ADC gain (`cal1`,
+  `cal2`, `ext`) through a loopback, and `clear_calibration(part)` clears one part (`offset`,
+  `dac`, `adc`). `Calibration` gains `dac` (`DacLine`), `adc_gain_ppm`, `dmm` and `measured`;
+  `BenchPod.DMM_SET_POINTS` has the set points. New types `DacCalPath`, `AdcGainSource`,
+  `CalibrationPart`. `Calibration.zero_count` is the raw J8-open zero the pod derives its offset from.
+
 ## 2.13.2
 
 - Docs: `calibrate()` corrects every ADC source from firmware 3.9.3 (they share the front end) and

{embeddedci-2.13.2 → embeddedci-2.13.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: embeddedci
-Version: 2.13.2
+Version: 2.13.4
 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
@@ -1021,6 +1021,40 @@ microvolt resolution (about 76 µV a step on `"5v"`) and `code16` is the 16-bit
 stays the nearest 8-bit level. On older firmware `code16` is `None` and the steps are 8-bit. `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).
 
+### The ADC input range (analog module v3r4)
+
+Analog module v3r4 (firmware 3.9.5+, `Capabilities.adc_low_range`) adds a ÷2 low range to the
+ADC input next to the normal ÷12 one:
+
+| Range | Full scale | Resolution | Input impedance |
+|---|---|---|---|
+| `"normal"` (default) | ±32.8 V | ~1 mV per count | ~1 MΩ |
+| `"low"` | ±5.46 V | ~167 µV per count | 1.82 MΩ: use 1x leads, not 10x probes |
+
+```python
+st = bp.adc_range("low")                   # AdcRangeState(range, supported, fullscale, ...)
+r = bp.adc_read("ext")                      # read in the low range: r.range == "low"
+r = bp.adc_read("current_in", range="low")  # or switch it with the reading
+cap = bp.capture_adc(4096, source="ext", range="low")
+print(cap.range, cap.overrange)             # a clipped sample: capture again in the normal range
+bp.adc_range("normal")
+print(bp.adc_range_test().passed)           # self-test through the cal1 loopback (5 V output)
+```
+
+The range applies to `ext`, `cal1` and `current_in` (4-20 mA fits inside it); `cal2` has none.
+It stays until it is changed, `analog_path("off")` or `analog_path("cal2")`, or the pod restarts.
+`analog_path`, `adc_read` and `capture_adc` take `range=` too. Captures are raw counts: the SDK
+keeps the fit it scales them with on the range in use (`Capabilities.adc_range`), and re-reads it
+whenever a reply says the pod moved to the other range. `AdcReading.overrange` and
+`Capture.overrange` (with `clipped_samples`) flag samples on the ADC's rails. A board without the
+low range raises `BenchPodError` for `"low"`.
+
+`adc_range_test()` drives the 5 V output into `cal1` at 1 V and 3.5 V, reads each point in both
+ranges, and fails (`passed` is `False`) when they disagree by more than 5 % + 30 mV. The low range's
+gain is calibrated through `cal1` with `calibrate_adc_gain("cal1", range="low")` (after the offset and
+the 5 V DMM line, see below); it serves every source in the low range and shows as
+`Calibration.adc_low_gain_ppm`.
+
 ### Calibrating the ADC offset
 
 `"current_in"` reads the 4-20 mA terminal (J8) across a 249 Ω resistor, so 4 mA is 0.996 V and 20 mA is
@@ -1046,8 +1080,45 @@ and keeps what it had. `a` and `b` are the fit the pod now uses for `current_in`
 Every ADC source shares the same front end after its input switch, so from firmware 3.9.3 the pod
 takes the offset out of all of them: `adc_read` on `ext`, `cal1` and `cal2`, and `capture_adc`,
 whose `volts` use the fit the pod reports (on the LAN in `status`, through embeddedci.com in its
-capabilities). Older firmware corrects `current_in` only. Only the offset is calibrated; the gain
-uses the built-in fits. Needs firmware 3.4.0 (capability `calibrate`, `Capabilities.calibrate`).
+capabilities). Older firmware corrects `current_in` only. Needs firmware 3.4.0 (capability
+`calibrate`, `Capabilities.calibrate`). The web app has it in the pod's Settings tab, under
+Calibration.
+
+#### Calibrating with a DMM
+
+With a bench DMM the pod can also take out what the offset leaves (firmware 3.9.4+, capability
+`cal_dmm`, `Capabilities.cal_dmm`): its own DAC line per output, then the ADC gain per source.
+Every step is optional and stored on its own; an output or source without one keeps the built-in
+fit. Disconnect the DUT from the DAC outputs first: this drives up to ±5 V on them.
+
+```python
+points = []
+for volts in bp.DMM_SET_POINTS["5v"]:            # 1.0 and 4.0 V; 3v3: 0.5 / 3.0, 12v: -5 / +5
+    out = bp.dac_output("5v", volts=volts)
+    points.append((out.code16, read_dmm()))      # the DMM on the 5 V output SMA, DC volts
+cal = bp.calibrate_dac("5v", points)             # this pod's line for the 5 V output
+bp.dac_output("off")
+print(cal.dac["5v"])                             # DacLine(a, b, offset=-0.0031, gain_ppm=-996)
+
+bp.calibrate_adc_gain("cal1")                    # 5 V loopback, against the line just stored
+bp.calibrate_adc_gain("ext")                     # needs the 12v line and an SMA cable ±12 V -> ADC in
+bp.clear_calibration("dac")                      # one part: "offset", "dac" or "adc"; no part = all
+```
+
+`calibrate_dac(path, points)` takes two `(code16, volts)` pairs: the 16-bit code `dac_output`
+drove and the DMM reading. From then on `dac_output`, the calibrated `generate` and the DAC output
+limits convert with this pod's line (`DacLine`: `a`, `b` per 16-bit code, `offset`, `gain_ppm`
+against the built-in line). `calibrate_adc_gain(source)` measures `cal1` through the 5 V output,
+`cal2` through the ±12 V output and `ext` (the front SMA, which `capture_adc` and the control loop
+use) through an SMA cable from the ±12 V output to the ADC input; `current_in` follows `cal1`. It
+needs the ADC offset and the driving output's DMM line, and `Calibration.measured` says what it
+saw. The pod refuses (`BenchPodError`) and keeps what it had when a reading cannot be right: two
+codes too close, a reading far from what the output should give (the DMM on another SMA), a gain
+more than 2 % off. It also refuses while DAC output limits are set. `Calibration.dac`,
+`Calibration.adc_gain_ppm` and `Calibration.dmm` show what is stored. The pod stores raw
+measurements (the J8-open zero as `Calibration.zero_count`, the DMM points) and derives every fit
+from them, so a later firmware with re-measured built-in fits keeps them right. Going back to
+firmware 3.4.0 to 3.9.3 keeps the offset; the DMM parts are not used there.
 
 ### The 4-20 mA output
 
@@ -1140,9 +1211,9 @@ both = bp.capture_correlated(adc_samples=4096, adc_sample_rate_hz=400_000,
 print(both.adc.duration, both.la.duration)              # one hardware trigger: timebases align
 ```
 
-* `capture_adc(samples=4096, *, sample_rate_hz=None, source=None, trigger=None, trigger_timeout=10.0)` — omitted rate = the device
+* `capture_adc(samples=4096, *, sample_rate_hz=None, source=None, trigger=None, trigger_timeout=10.0, range=None)` — omitted rate = the device
   maximum; the **achieved** rate is on the result. `source` routes the ADC first (omitted, the
-  current routing is left alone). `volts` use the front-SMA calibration; for the other sources
+  current routing is left alone); `range` sets the [ADC input range](#the-adc-input-range-analog-module-v3r4). `volts` use the front-SMA calibration; for the other sources
   compare `counts` or use `adc_read`.
 * `capture_la(samples=4096, *, sample_rate_hz=None, stop_dac_after=None, trigger=None, trigger_timeout=10.0)` — 12-bit words; bit *n* is
   channel LA*n+1*. The **achieved** rate is on the result and can be below the request: the pod
@@ -1631,7 +1702,7 @@ lease_wait=600.0, lease_ttl=120, wiring=None)`. A context manager; `close()` is
 | GPIO and pins | `gpio(la, mode="output", *, level=None)`, `gpio_pins(las, mode="output", *, level=None)`, `configure_gpio(las, mode="output", *, level=None)`, `set_gpio(la, level)`, `read_gpio(la)`, `wait_for_level(la, level, *, timeout, poll=0.005)` (`False` when `timeout` passes first), `pin_levels()`, `la_pins()`, `release_gpio(*las)`, `la_step(la, *, steps, delay, dir_la=None, direction=0)` |
 | I2C sensor | `enable_i2c_sensor(sensor=Sensor.BMP280, *, sda=None, scl=None, address=None, **values)`, `set_i2c_sensor(**values)`, `disable_i2c_sensor()`, `i2c_sensor_status()`, `i2c_sensor_types()`, `i2c_sensor_regs()`, `i2c_sensor_capture(...)` |
 | GPS receiver | `enable_gps(tx, *, baud=9600, rate_hz=1, sentences=None, utc=None, **fix)`, `set_gps(*, utc=None, **fix)`, `disable_gps()`, `gps_status()` |
-| Analog | `analog_path(path)`, `adc_read(source="ext")`, `dac_output(path, *, volts=None)`, `current_out(current)`, `current_out_range()`, `calibrate(source="current_in")`, `calibration()`, `clear_calibration()` |
+| Analog | `analog_path(path, *, range=None)`, `adc_read(source="ext", *, range=None)`, `adc_range(range=None)`, `adc_range_test()`, `dac_output(path, *, volts=None)`, `current_out(current)`, `current_out_range()`, `calibrate(source="current_in")`, `calibration()`, `clear_calibration(part=None)`, `calibrate_dac(path, points)`, `calibrate_adc_gain(source, *, range="normal")`, `DMM_SET_POINTS` |
 | Captures | `capture_adc(...)`, `capture_la(...)`, `capture_correlated(...)`, `decode(source, protocol="i2c", ...)` |
 | DAC | `generate(...)`, `replay(...)`, `replay_waveform(...)`, `dac_stop()`, `control_loop(...)`, `loop_input(...)`, `loop_probe()` |
 | CAN | `open_can(*, bitrate=500000, mode="normal", term=False, fd=False)`, `can_config(...)`, `can_disable()`, `can_status()`, `can_term(on)`, `can_write(...)`, `can_read(...)`, `can_respond(...)`, `can_respond_clear()` |
@@ -1672,12 +1743,16 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen
 | `I2CByte` | `I2CMessage.data` | `value`, `ack` |
 | `UartFrame` | `decode("uart")` | `index`, `start_us`, `end_us`, `value`, `hex`, `text`, `ok`, `error` |
 | `SpiFrame` | `decode("spi")` | `index`, `start_us`, `end_us`, `mosi`, `miso`, `mosi_hex`, `miso_hex` |
-| `AnalogPathState` | `analog_path` | `path`, `dac_mux_register`, `cal_relay_register` |
-| `AdcReading` | `adc_read` | `source`, `voltage`, `count`, `span`, `offset`, `current` |
+| `AnalogPathState` | `analog_path` | `path`, `dac_mux_register`, `cal_relay_register`, `range` |
+| `AdcReading` | `adc_read` | `source`, `voltage`, `count`, `span`, `offset`, `current`, `range`, `fullscale`, `overrange` |
+| `AdcRangeState` | `adc_range` | `range`, `supported`, `fullscale`, `normal_fullscale`, `low_fullscale`, `a`, `b` (volts, the `ext` fit of the range) |
+| `AdcRangeTest` | `adc_range_test` | `passed`, `points` (each an `AdcRangeTestPoint`: `set_voltage`, `normal`, `low`, `ok`) |
+| `AdcRange` (literal) | `adc_range`, `range=` | `"normal"`, `"low"` |
 | `DacOutput` | `dac_output` | `path`, `voltage`, `code` |
 | `CurrentOutput` | `current_out`, `current_out_range` | `current`, `code`, `min_current`, `max_current` |
-| `Calibration` | `calibrate`, `calibration`, `clear_calibration` | `source`, `calibrated`, `offset`, `a`, `b`, `count`, `span`, `samples` |
-| `Capture` | `capture_adc` | `counts`, `volts`, `currents`, `sample_rate_hz`, `source`, `trigger`, `duration`, `times()`, `mean()`, `min()`, `max()`, `rms()`, `rms_ac()`, `peak_to_peak()`, `first_crossing()`, `crossing_times()`, `fft()`, `dominant_frequency()` |
+| `Calibration` | `calibrate`, `calibration`, `clear_calibration`, `calibrate_dac`, `calibrate_adc_gain` | `source`, `calibrated`, `offset`, `a`, `b`, `count`, `span`, `samples`, `dac`, `adc_gain_ppm`, `adc_low_gain_ppm`, `dmm`, `measured`, `zero_count` |
+| `DacLine` | `Calibration.dac` | `a`, `b`, `offset`, `gain_ppm` |
+| `Capture` | `capture_adc` | `counts`, `volts`, `currents`, `sample_rate_hz`, `source`, `trigger`, `range`, `overrange`, `clipped_samples`, `duration`, `times()`, `mean()`, `min()`, `max()`, `rms()`, `rms_ac()`, `peak_to_peak()`, `first_crossing()`, `crossing_times()`, `fft()`, `dominant_frequency()` |
 | `LaCapture` | `capture_la` | `words`, `channels`, `sample_rate_hz`, `trigger`, `duration`, `channel(la)`, `level_at()`, `edges()`, `edge_times()`, `first_edge()`, `delay()`, `frequency()`, `duty_cycle()`, `pulse_widths()`, `decode()` |
 | `CorrelatedCapture` | `capture_correlated` | `adc` (a `Capture`), `la` (a `LaCapture`), sharing one hardware trigger |
 | `Trigger` | `capture_adc`, `capture_la`, `capture_correlated` | `la`, `edge` |
@@ -1718,9 +1793,9 @@ reported keeps its default (`False`, `0` or `""`), so a feature check is just
 | Group | Fields |
 |---|---|
 | Identity | `board`, `firmware_version`, `board_rev` (`"v2"`, `"v3"`, `"unknown"`, or `""`), `la_vccio_mv` (the LA bank voltage the pod reports) |
-| ADC | `adc_bits`, `adc_fullscale_mv`, `adc_channels`, `adc_offset_counts`, `adc_affine` (the front-end fit), `adc_max_count`, `counts_to_volts(count)` |
+| ADC | `adc_bits`, `adc_fullscale_mv`, `adc_channels`, `adc_offset_counts`, `adc_affine` (the front-end fit, of the range in use), `adc_low_range` (analog module v3r4+: the low range), `adc_range` (`"normal"`, `"low"`, or `""` before firmware 3.9.5), `adc_range_fullscale` (volts, ±), `adc_max_count`, `counts_to_volts(count)` |
 | DAC and replay | `dac`, `dac_dc`, `dac_replay`, `dac_deep_replay`, `dac_control_loop`, `dac_loop_sources` (gateware v29+), `dac_loop_input_map` (v30+), `dac_cotrig` (v27+), `generate16` (firmware 3.9.1+: `generate` in calibrated 16-bit volts), `dac_bits`, `dac_replay_bits`, `dac_replay_max_samples`, `dac_fullscale_mv`, `dac_channels`, `dac_limits` (output limits on the DAC paths) |
-| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `spi_master` (v45+), `spi_stream`, `calibrate`, `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensor_types` (the BME280/SHT4x/MPU-6050 models), `gps` (the GPS receiver, gateware v48+), `analog` (`False` on the digital-only board, `None` when not announced) |
+| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `spi_master` (v45+), `spi_stream`, `calibrate`, `cal_dmm` (firmware 3.9.4+: `calibrate_dac`, `calibrate_adc_gain`), `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensor_types` (the BME280/SHT4x/MPU-6050 models), `gps` (the GPS receiver, gateware v48+), `analog` (`False` on the digital-only board, `None` when not announced) |
 | Firmware updates and policies | `flash_kb` (MCU flash in KiB, 0 when not reported), `blob_slots`, `ota_sig`, `sig_policy` (`"audit"`, `"required"`, ...), `sig_keys`, `sig_policy_cmd`, `lan_policy` (`"open"`, `"locked"`, `"off"`), `lan_policy_cmd`, `tunnel_max_tier`, `lease_state` (the pod refuses LAN writes while a cloud job holds it), `cloud_ca`, `cloud_proxy`, `ws_auth_v2` (server only) |
 | Boot health | `safe_mode`, `safe_reason`, `last_crash`, `reset_cause`, `boot_warning()` (a one-line warning after safe mode or a crash, else `None`) |
 | Source | `raw` (the map it was parsed from) |
@@ -1761,7 +1836,7 @@ timeout=60.0, lease_id=None)`. Errors raise `ServerApiError` (`status`), and an
 | `curve_output_at(curve, input_code)`, `input_percent_to_code(percent)` | evaluate a curve the way the gateware does; an input percentage as a code |
 | `encode_curve_b64url(codes)` | 16-bit DAC codes as little-endian base64url, the wire form of a curve |
 | `INTERNAL`, `EXTERNAL`, `PIN1` … `PIN14`, `BMP280_ADDR_PRIMARY`, `BMP280_ADDR_SECONDARY` | named constants (see [API conventions](#api-conventions-and-stability)) |
-| `DacPath`, `DacOutputPath`, `AnalogPath`, `AdcSource`, `CalibrateSource` (`"current_in"`), `LoopSource`, `Waveshape`, `ReplayMapping`, `DecodeProtocol`, `CanMode`, `FaultType`, `GpioMode`, `Edge`, `TriggerEdge` | the `Literal` string types |
+| `DacPath`, `DacOutputPath`, `AnalogPath`, `AdcSource`, `CalibrateSource` (`"current_in"`), `DacCalPath` (`"3v3"`, `"5v"`, `"12v"`), `AdcGainSource` (`"cal1"`, `"cal2"`, `"ext"`), `CalibrationPart` (`"offset"`, `"dac"`, `"adc"`), `LoopSource`, `Waveshape`, `ReplayMapping`, `DecodeProtocol`, `CanMode`, `FaultType`, `GpioMode`, `Edge`, `TriggerEdge` | the `Literal` string types |
 | `decode`, `i2c`, `can`, `control_loop`, `motor_emulator`, `dsp` | submodules: off-device decoders, I2C helpers, CAN types, curve helpers, the emulator's registers, and `dsp`, a pure-Python mirror of the server's record-to-replay processing |
 
 ## Examples

{embeddedci-2.13.2 → embeddedci-2.13.4}/README.md

@@ -983,6 +983,40 @@ microvolt resolution (about 76 µV a step on `"5v"`) and `code16` is the 16-bit
 stays the nearest 8-bit level. On older firmware `code16` is `None` and the steps are 8-bit. `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).
 
+### The ADC input range (analog module v3r4)
+
+Analog module v3r4 (firmware 3.9.5+, `Capabilities.adc_low_range`) adds a ÷2 low range to the
+ADC input next to the normal ÷12 one:
+
+| Range | Full scale | Resolution | Input impedance |
+|---|---|---|---|
+| `"normal"` (default) | ±32.8 V | ~1 mV per count | ~1 MΩ |
+| `"low"` | ±5.46 V | ~167 µV per count | 1.82 MΩ: use 1x leads, not 10x probes |
+
+```python
+st = bp.adc_range("low")                   # AdcRangeState(range, supported, fullscale, ...)
+r = bp.adc_read("ext")                      # read in the low range: r.range == "low"
+r = bp.adc_read("current_in", range="low")  # or switch it with the reading
+cap = bp.capture_adc(4096, source="ext", range="low")
+print(cap.range, cap.overrange)             # a clipped sample: capture again in the normal range
+bp.adc_range("normal")
+print(bp.adc_range_test().passed)           # self-test through the cal1 loopback (5 V output)
+```
+
+The range applies to `ext`, `cal1` and `current_in` (4-20 mA fits inside it); `cal2` has none.
+It stays until it is changed, `analog_path("off")` or `analog_path("cal2")`, or the pod restarts.
+`analog_path`, `adc_read` and `capture_adc` take `range=` too. Captures are raw counts: the SDK
+keeps the fit it scales them with on the range in use (`Capabilities.adc_range`), and re-reads it
+whenever a reply says the pod moved to the other range. `AdcReading.overrange` and
+`Capture.overrange` (with `clipped_samples`) flag samples on the ADC's rails. A board without the
+low range raises `BenchPodError` for `"low"`.
+
+`adc_range_test()` drives the 5 V output into `cal1` at 1 V and 3.5 V, reads each point in both
+ranges, and fails (`passed` is `False`) when they disagree by more than 5 % + 30 mV. The low range's
+gain is calibrated through `cal1` with `calibrate_adc_gain("cal1", range="low")` (after the offset and
+the 5 V DMM line, see below); it serves every source in the low range and shows as
+`Calibration.adc_low_gain_ppm`.
+
 ### Calibrating the ADC offset
 
 `"current_in"` reads the 4-20 mA terminal (J8) across a 249 Ω resistor, so 4 mA is 0.996 V and 20 mA is
@@ -1008,8 +1042,45 @@ and keeps what it had. `a` and `b` are the fit the pod now uses for `current_in`
 Every ADC source shares the same front end after its input switch, so from firmware 3.9.3 the pod
 takes the offset out of all of them: `adc_read` on `ext`, `cal1` and `cal2`, and `capture_adc`,
 whose `volts` use the fit the pod reports (on the LAN in `status`, through embeddedci.com in its
-capabilities). Older firmware corrects `current_in` only. Only the offset is calibrated; the gain
-uses the built-in fits. Needs firmware 3.4.0 (capability `calibrate`, `Capabilities.calibrate`).
+capabilities). Older firmware corrects `current_in` only. Needs firmware 3.4.0 (capability
+`calibrate`, `Capabilities.calibrate`). The web app has it in the pod's Settings tab, under
+Calibration.
+
+#### Calibrating with a DMM
+
+With a bench DMM the pod can also take out what the offset leaves (firmware 3.9.4+, capability
+`cal_dmm`, `Capabilities.cal_dmm`): its own DAC line per output, then the ADC gain per source.
+Every step is optional and stored on its own; an output or source without one keeps the built-in
+fit. Disconnect the DUT from the DAC outputs first: this drives up to ±5 V on them.
+
+```python
+points = []
+for volts in bp.DMM_SET_POINTS["5v"]:            # 1.0 and 4.0 V; 3v3: 0.5 / 3.0, 12v: -5 / +5
+    out = bp.dac_output("5v", volts=volts)
+    points.append((out.code16, read_dmm()))      # the DMM on the 5 V output SMA, DC volts
+cal = bp.calibrate_dac("5v", points)             # this pod's line for the 5 V output
+bp.dac_output("off")
+print(cal.dac["5v"])                             # DacLine(a, b, offset=-0.0031, gain_ppm=-996)
+
+bp.calibrate_adc_gain("cal1")                    # 5 V loopback, against the line just stored
+bp.calibrate_adc_gain("ext")                     # needs the 12v line and an SMA cable ±12 V -> ADC in
+bp.clear_calibration("dac")                      # one part: "offset", "dac" or "adc"; no part = all
+```
+
+`calibrate_dac(path, points)` takes two `(code16, volts)` pairs: the 16-bit code `dac_output`
+drove and the DMM reading. From then on `dac_output`, the calibrated `generate` and the DAC output
+limits convert with this pod's line (`DacLine`: `a`, `b` per 16-bit code, `offset`, `gain_ppm`
+against the built-in line). `calibrate_adc_gain(source)` measures `cal1` through the 5 V output,
+`cal2` through the ±12 V output and `ext` (the front SMA, which `capture_adc` and the control loop
+use) through an SMA cable from the ±12 V output to the ADC input; `current_in` follows `cal1`. It
+needs the ADC offset and the driving output's DMM line, and `Calibration.measured` says what it
+saw. The pod refuses (`BenchPodError`) and keeps what it had when a reading cannot be right: two
+codes too close, a reading far from what the output should give (the DMM on another SMA), a gain
+more than 2 % off. It also refuses while DAC output limits are set. `Calibration.dac`,
+`Calibration.adc_gain_ppm` and `Calibration.dmm` show what is stored. The pod stores raw
+measurements (the J8-open zero as `Calibration.zero_count`, the DMM points) and derives every fit
+from them, so a later firmware with re-measured built-in fits keeps them right. Going back to
+firmware 3.4.0 to 3.9.3 keeps the offset; the DMM parts are not used there.
 
 ### The 4-20 mA output
 
@@ -1102,9 +1173,9 @@ both = bp.capture_correlated(adc_samples=4096, adc_sample_rate_hz=400_000,
 print(both.adc.duration, both.la.duration)              # one hardware trigger: timebases align
 ```
 
-* `capture_adc(samples=4096, *, sample_rate_hz=None, source=None, trigger=None, trigger_timeout=10.0)` — omitted rate = the device
+* `capture_adc(samples=4096, *, sample_rate_hz=None, source=None, trigger=None, trigger_timeout=10.0, range=None)` — omitted rate = the device
   maximum; the **achieved** rate is on the result. `source` routes the ADC first (omitted, the
-  current routing is left alone). `volts` use the front-SMA calibration; for the other sources
+  current routing is left alone); `range` sets the [ADC input range](#the-adc-input-range-analog-module-v3r4). `volts` use the front-SMA calibration; for the other sources
   compare `counts` or use `adc_read`.
 * `capture_la(samples=4096, *, sample_rate_hz=None, stop_dac_after=None, trigger=None, trigger_timeout=10.0)` — 12-bit words; bit *n* is
   channel LA*n+1*. The **achieved** rate is on the result and can be below the request: the pod
@@ -1593,7 +1664,7 @@ lease_wait=600.0, lease_ttl=120, wiring=None)`. A context manager; `close()` is
 | GPIO and pins | `gpio(la, mode="output", *, level=None)`, `gpio_pins(las, mode="output", *, level=None)`, `configure_gpio(las, mode="output", *, level=None)`, `set_gpio(la, level)`, `read_gpio(la)`, `wait_for_level(la, level, *, timeout, poll=0.005)` (`False` when `timeout` passes first), `pin_levels()`, `la_pins()`, `release_gpio(*las)`, `la_step(la, *, steps, delay, dir_la=None, direction=0)` |
 | I2C sensor | `enable_i2c_sensor(sensor=Sensor.BMP280, *, sda=None, scl=None, address=None, **values)`, `set_i2c_sensor(**values)`, `disable_i2c_sensor()`, `i2c_sensor_status()`, `i2c_sensor_types()`, `i2c_sensor_regs()`, `i2c_sensor_capture(...)` |
 | GPS receiver | `enable_gps(tx, *, baud=9600, rate_hz=1, sentences=None, utc=None, **fix)`, `set_gps(*, utc=None, **fix)`, `disable_gps()`, `gps_status()` |
-| Analog | `analog_path(path)`, `adc_read(source="ext")`, `dac_output(path, *, volts=None)`, `current_out(current)`, `current_out_range()`, `calibrate(source="current_in")`, `calibration()`, `clear_calibration()` |
+| Analog | `analog_path(path, *, range=None)`, `adc_read(source="ext", *, range=None)`, `adc_range(range=None)`, `adc_range_test()`, `dac_output(path, *, volts=None)`, `current_out(current)`, `current_out_range()`, `calibrate(source="current_in")`, `calibration()`, `clear_calibration(part=None)`, `calibrate_dac(path, points)`, `calibrate_adc_gain(source, *, range="normal")`, `DMM_SET_POINTS` |
 | Captures | `capture_adc(...)`, `capture_la(...)`, `capture_correlated(...)`, `decode(source, protocol="i2c", ...)` |
 | DAC | `generate(...)`, `replay(...)`, `replay_waveform(...)`, `dac_stop()`, `control_loop(...)`, `loop_input(...)`, `loop_probe()` |
 | CAN | `open_can(*, bitrate=500000, mode="normal", term=False, fd=False)`, `can_config(...)`, `can_disable()`, `can_status()`, `can_term(on)`, `can_write(...)`, `can_read(...)`, `can_respond(...)`, `can_respond_clear()` |
@@ -1634,12 +1705,16 @@ few built from other shapes); `to_dict()` goes the other way where a type is sen
 | `I2CByte` | `I2CMessage.data` | `value`, `ack` |
 | `UartFrame` | `decode("uart")` | `index`, `start_us`, `end_us`, `value`, `hex`, `text`, `ok`, `error` |
 | `SpiFrame` | `decode("spi")` | `index`, `start_us`, `end_us`, `mosi`, `miso`, `mosi_hex`, `miso_hex` |
-| `AnalogPathState` | `analog_path` | `path`, `dac_mux_register`, `cal_relay_register` |
-| `AdcReading` | `adc_read` | `source`, `voltage`, `count`, `span`, `offset`, `current` |
+| `AnalogPathState` | `analog_path` | `path`, `dac_mux_register`, `cal_relay_register`, `range` |
+| `AdcReading` | `adc_read` | `source`, `voltage`, `count`, `span`, `offset`, `current`, `range`, `fullscale`, `overrange` |
+| `AdcRangeState` | `adc_range` | `range`, `supported`, `fullscale`, `normal_fullscale`, `low_fullscale`, `a`, `b` (volts, the `ext` fit of the range) |
+| `AdcRangeTest` | `adc_range_test` | `passed`, `points` (each an `AdcRangeTestPoint`: `set_voltage`, `normal`, `low`, `ok`) |
+| `AdcRange` (literal) | `adc_range`, `range=` | `"normal"`, `"low"` |
 | `DacOutput` | `dac_output` | `path`, `voltage`, `code` |
 | `CurrentOutput` | `current_out`, `current_out_range` | `current`, `code`, `min_current`, `max_current` |
-| `Calibration` | `calibrate`, `calibration`, `clear_calibration` | `source`, `calibrated`, `offset`, `a`, `b`, `count`, `span`, `samples` |
-| `Capture` | `capture_adc` | `counts`, `volts`, `currents`, `sample_rate_hz`, `source`, `trigger`, `duration`, `times()`, `mean()`, `min()`, `max()`, `rms()`, `rms_ac()`, `peak_to_peak()`, `first_crossing()`, `crossing_times()`, `fft()`, `dominant_frequency()` |
+| `Calibration` | `calibrate`, `calibration`, `clear_calibration`, `calibrate_dac`, `calibrate_adc_gain` | `source`, `calibrated`, `offset`, `a`, `b`, `count`, `span`, `samples`, `dac`, `adc_gain_ppm`, `adc_low_gain_ppm`, `dmm`, `measured`, `zero_count` |
+| `DacLine` | `Calibration.dac` | `a`, `b`, `offset`, `gain_ppm` |
+| `Capture` | `capture_adc` | `counts`, `volts`, `currents`, `sample_rate_hz`, `source`, `trigger`, `range`, `overrange`, `clipped_samples`, `duration`, `times()`, `mean()`, `min()`, `max()`, `rms()`, `rms_ac()`, `peak_to_peak()`, `first_crossing()`, `crossing_times()`, `fft()`, `dominant_frequency()` |
 | `LaCapture` | `capture_la` | `words`, `channels`, `sample_rate_hz`, `trigger`, `duration`, `channel(la)`, `level_at()`, `edges()`, `edge_times()`, `first_edge()`, `delay()`, `frequency()`, `duty_cycle()`, `pulse_widths()`, `decode()` |
 | `CorrelatedCapture` | `capture_correlated` | `adc` (a `Capture`), `la` (a `LaCapture`), sharing one hardware trigger |
 | `Trigger` | `capture_adc`, `capture_la`, `capture_correlated` | `la`, `edge` |
@@ -1680,9 +1755,9 @@ reported keeps its default (`False`, `0` or `""`), so a feature check is just
 | Group | Fields |
 |---|---|
 | Identity | `board`, `firmware_version`, `board_rev` (`"v2"`, `"v3"`, `"unknown"`, or `""`), `la_vccio_mv` (the LA bank voltage the pod reports) |
-| ADC | `adc_bits`, `adc_fullscale_mv`, `adc_channels`, `adc_offset_counts`, `adc_affine` (the front-end fit), `adc_max_count`, `counts_to_volts(count)` |
+| ADC | `adc_bits`, `adc_fullscale_mv`, `adc_channels`, `adc_offset_counts`, `adc_affine` (the front-end fit, of the range in use), `adc_low_range` (analog module v3r4+: the low range), `adc_range` (`"normal"`, `"low"`, or `""` before firmware 3.9.5), `adc_range_fullscale` (volts, ±), `adc_max_count`, `counts_to_volts(count)` |
 | DAC and replay | `dac`, `dac_dc`, `dac_replay`, `dac_deep_replay`, `dac_control_loop`, `dac_loop_sources` (gateware v29+), `dac_loop_input_map` (v30+), `dac_cotrig` (v27+), `generate16` (firmware 3.9.1+: `generate` in calibrated 16-bit volts), `dac_bits`, `dac_replay_bits`, `dac_replay_max_samples`, `dac_fullscale_mv`, `dac_channels`, `dac_limits` (output limits on the DAC paths) |
-| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `spi_master` (v45+), `spi_stream`, `calibrate`, `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensor_types` (the BME280/SHT4x/MPU-6050 models), `gps` (the GPS receiver, gateware v48+), `analog` (`False` on the digital-only board, `None` when not announced) |
+| Features | `scope`, `analyzer`, `serial`, `tunnel`, `command`, `ota`, `la_pins`, `gpio_read` (direct pin reads, v35+), `capture_trigger` (v35+), `power_profile`, `capture_b64` (faster ADC read-back, used automatically), `nrst_pin` (the dedicated reset pin, rev3), `usb_cc` (rev3), `spi_master` (v45+), `spi_stream`, `calibrate`, `cal_dmm` (firmware 3.9.4+: `calibrate_dac`, `calibrate_adc_gain`), `current_out`, `can`, `pod_current` (`PowerStatus.pod`), `sensor_types` (the BME280/SHT4x/MPU-6050 models), `gps` (the GPS receiver, gateware v48+), `analog` (`False` on the digital-only board, `None` when not announced) |
 | Firmware updates and policies | `flash_kb` (MCU flash in KiB, 0 when not reported), `blob_slots`, `ota_sig`, `sig_policy` (`"audit"`, `"required"`, ...), `sig_keys`, `sig_policy_cmd`, `lan_policy` (`"open"`, `"locked"`, `"off"`), `lan_policy_cmd`, `tunnel_max_tier`, `lease_state` (the pod refuses LAN writes while a cloud job holds it), `cloud_ca`, `cloud_proxy`, `ws_auth_v2` (server only) |
 | Boot health | `safe_mode`, `safe_reason`, `last_crash`, `reset_cause`, `boot_warning()` (a one-line warning after safe mode or a crash, else `None`) |
 | Source | `raw` (the map it was parsed from) |
@@ -1723,7 +1798,7 @@ timeout=60.0, lease_id=None)`. Errors raise `ServerApiError` (`status`), and an
 | `curve_output_at(curve, input_code)`, `input_percent_to_code(percent)` | evaluate a curve the way the gateware does; an input percentage as a code |
 | `encode_curve_b64url(codes)` | 16-bit DAC codes as little-endian base64url, the wire form of a curve |
 | `INTERNAL`, `EXTERNAL`, `PIN1` … `PIN14`, `BMP280_ADDR_PRIMARY`, `BMP280_ADDR_SECONDARY` | named constants (see [API conventions](#api-conventions-and-stability)) |
-| `DacPath`, `DacOutputPath`, `AnalogPath`, `AdcSource`, `CalibrateSource` (`"current_in"`), `LoopSource`, `Waveshape`, `ReplayMapping`, `DecodeProtocol`, `CanMode`, `FaultType`, `GpioMode`, `Edge`, `TriggerEdge` | the `Literal` string types |
+| `DacPath`, `DacOutputPath`, `AnalogPath`, `AdcSource`, `CalibrateSource` (`"current_in"`), `DacCalPath` (`"3v3"`, `"5v"`, `"12v"`), `AdcGainSource` (`"cal1"`, `"cal2"`, `"ext"`), `CalibrationPart` (`"offset"`, `"dac"`, `"adc"`), `LoopSource`, `Waveshape`, `ReplayMapping`, `DecodeProtocol`, `CanMode`, `FaultType`, `GpioMode`, `Edge`, `TriggerEdge` | the `Literal` string types |
 | `decode`, `i2c`, `can`, `control_loop`, `motor_emulator`, `dsp` | submodules: off-device decoders, I2C helpers, CAN types, curve helpers, the emulator's registers, and `dsp`, a pure-Python mirror of the server's record-to-replay processing |
 
 ## Examples

{embeddedci-2.13.2 → embeddedci-2.13.4}/pyproject.toml

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

{embeddedci-2.13.2 → embeddedci-2.13.4}/src/embeddedci/benchpod/__init__.py

@@ -48,8 +48,12 @@ from .constants import (
     PIN12,
     PIN13,
     PIN14,
+    AdcRange,
     AdcSource,
     CalibrateSource,
+    CalibrationPart,
+    DacCalPath,
+    AdcGainSource,
     AnalogPath,
     CanMode,
     DacOutputPath,
@@ -114,9 +118,13 @@ from .results import Capture, CorrelatedCapture, LaCapture, LanTls, Trigger
 from .transport.tls import delete_pin as forget_lan_tls, trust_lan_tls
 from .server_api import ServerApi, ServerApiError, ServerPermissionDeniedError
 from .state import (
+    AdcRangeState,
+    AdcRangeTest,
+    AdcRangeTestPoint,
     AdcReading,
     AnalogPathState,
     Calibration,
+    DacLine,
     CurrentOutput,
     DacOutput,
     EfuseState,
@@ -159,8 +167,12 @@ __all__ = [
     "PullState",
     "AnalogPathState",
     "DacOutput",
+    "AdcRangeState",
+    "AdcRangeTest",
+    "AdcRangeTestPoint",
     "AdcReading",
     "Calibration",
+    "DacLine",
     "CurrentOutput",
     "FpgaImageInfo",
     "LoopState",
@@ -252,8 +264,12 @@ __all__ = [
     "DacPath",
     "DacOutputPath",
     "AnalogPath",
+    "AdcRange",
     "AdcSource",
     "CalibrateSource",
+    "CalibrationPart",
+    "DacCalPath",
+    "AdcGainSource",
     "Waveshape",
     "ReplayMapping",
     "LoopSource",

{embeddedci-2.13.2 → embeddedci-2.13.4}/src/embeddedci/benchpod/capabilities.py

@@ -115,6 +115,13 @@ class Capabilities:
     adc_offset_counts: float = 0.0
     #: affine front-end fit; None => use the naive linear model.
     adc_affine: Optional[AffineCal] = None
+    #: The board has the ADC low range (analog module v3r4+): :meth:`BenchPod.adc_range`.
+    adc_low_range: bool = False
+    #: The ADC input range :attr:`adc_affine` is for: ``"normal"`` or ``"low"``; ``""`` when the
+    #: firmware does not say (before 3.9.5: always normal).
+    adc_range: str = ""
+    #: That range's input full scale in volts (±), or 0.0 when not reported.
+    adc_range_fullscale: float = 0.0
 
     # DAC / replay
     dac: bool = False
@@ -176,6 +183,10 @@ class Capabilities:
     spi_stream: bool = False
     #: The pod can calibrate its own ADC and keeps the result: :meth:`BenchPod.calibrate`.
     calibrate: bool = False
+    #: ``calibrate`` also takes the DMM-guided forms (firmware 3.9.4+): this pod's own DAC line
+    #: per output and ADC gain per source, :meth:`BenchPod.calibrate_dac`,
+    #: :meth:`BenchPod.calibrate_adc_gain`.
+    cal_dmm: bool = False
     #: The pod can hold a current on its 4-20 mA output (J9): :meth:`BenchPod.current_out`.
     current_out: bool = False
     #: Classic CAN on the pod's CAN+/CAN- terminals: :meth:`BenchPod.open_can`. Firmware older
@@ -319,9 +330,11 @@ class Capabilities:
                 ("spi_master", "spi_master"),
                 ("spi_stream", "spi_stream"),
                 ("calibrate", "calibrate"),
+                ("cal_dmm", "cal_dmm"),
                 ("current_out", "current_out"),
                 ("can", "can"),
                 ("pod_current", "pod_current"),
+                ("adc_low_range", "adc_low_range"),
                 ("dac_limits", "dac_limits"),
                 ("sensor_types", "sensor_types"),
                 ("gps", "gps"),
@@ -336,8 +349,19 @@ class Capabilities:
         c.last_crash = _crash_text(status.get("last_crash", status.get("crash")))
         c.reset_cause = str(status.get("reset", status.get("reset_cause", "")) or "")
         c._apply_affine(status)
+        c._apply_range(status)
         return c
 
+    def _apply_range(self, src: Mapping[str, Any], prefix: str = "") -> None:
+        """The ADC input range the fit is for (firmware 3.9.5+)."""
+        rng = src.get(prefix + "adc_range")
+        if isinstance(rng, str) and rng:
+            self.adc_range = rng
+        if (v := _as_float(src, prefix + "adc_range_fs_mv")) is not None and v > 0:
+            self.adc_range_fullscale = v / 1000.0
+        if _as_bool(src, prefix + "adc_low_range") is True:
+            self.adc_low_range = True
+
     @classmethod
     def from_parameters(cls, params: Mapping[str, Any]) -> "Capabilities":
         """Parse a server ``cap.*`` device-parameter map (complete capability set)."""
@@ -379,8 +403,9 @@ class Capabilities:
             ("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"),
+            ("calibrate", "cap.calibrate"), ("cal_dmm", "cap.cal_dmm"), ("current_out", "cap.current_out"),
             ("can", "cap.can"), ("pod_current", "cap.pod_current"),
+            ("adc_low_range", "cap.adc_low_range"),
             ("sensor_types", "cap.sensor_types"), ("gps", "cap.gps"),
             ("dac_limits", "cap.dac_limits"),
             ("ws_auth_v2", "cap.ws_auth_v2"),
@@ -408,6 +433,7 @@ class Capabilities:
             c.adc_affine = AffineCal(a=cal_a, b=cal_b, unwrap=bool(_as_bool(params, "cap.adc_cal_unwrap")))
         else:
             c._apply_affine(params, board=c.board)
+        c._apply_range(params, "cap.")
         return c
 
     def _apply_affine(self, src: Mapping[str, Any], board: Optional[str] = None) -> None:

{embeddedci-2.13.2 → embeddedci-2.13.4}/src/embeddedci/benchpod/capture.py

@@ -147,7 +147,7 @@ def capture_adc(transport: Any, caps: Capabilities, *, samples: int = 4096,
         counts.extend(_dense(chunk))
     volts = [caps.counts_to_volts(c) for c in counts]
     return Capture(counts=counts, volts=volts, sample_rate_hz=_rate_hz(rate, sample_rate_hz),
-                   source=source)
+                   source=source, range=caps.adc_range)
 
 
 def capture_la(transport: Any, *, samples: int = 4096, sample_rate_hz: Optional[float] = None,
@@ -279,7 +279,8 @@ def capture_correlated(transport: Any, caps: Capabilities, *, adc_samples: int =
         la_words = la_dense[:la_samples] if la_samples else la_dense
 
     adc = Capture(counts=adc_counts, volts=[caps.counts_to_volts(c) for c in adc_counts],
-                  sample_rate_hz=_rate_hz(adc_rate, adc_sample_rate_hz), trigger=trigger)
+                  sample_rate_hz=_rate_hz(adc_rate, adc_sample_rate_hz), trigger=trigger,
+                  range=caps.adc_range)
     la = LaCapture(words=la_words, sample_rate_hz=_rate_hz(la_rate, la_sample_rate_hz),
                    trigger=trigger)
     return CorrelatedCapture(adc=adc, la=la)