diff --git a/packages/embeddedci-mcp/CHANGELOG.md b/packages/embeddedci-mcp/CHANGELOG.md index c055f4d..1177cc6 100644 --- a/packages/embeddedci-mcp/CHANGELOG.md +++ b/packages/embeddedci-mcp/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog — `embeddedci-mcp` +## 3.0.5 + +- `adc_read` on `current_in` returns `sense_ohms`, the resistance the loop current was computed + with: 249 ohm up to analog module v3r4, about 100 ohm from v3r5 (firmware 3.10.13+), which also + reads `current_in` in the low range by default. The guide explains the 30 mA limiter. + ## 3.0.4 - Needs embeddedci 3.0.4. diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py b/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py index 0930b97..de5aa64 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/guide.py @@ -27,7 +27,7 @@ - Interactive console: uart_open, power_on, uart_read(until_regex), uart_write, uart_close. - Emulate sensors (I2C, SPI, UART, analog; firmware with the 'sensors' capability): the pod plays a sensor from a definition. sensor_library lists ready ones (bme280, bmp280, sht4x, mpu6050, gps_nmea, ...) and sensor_show gives one's YAML and params. For I2C, set_pull([sda, scl], pull="up") on LA1-LA6 (LA7/LA8 pull down only) first. sensor_start(definition=, pins={sda, scl} | {tx} | ...), then sensor_set(instance, values) changes readings, sensor_stimulus_load + sensor_stimulus_start play values over time, sensor_fault injects a fault, sensor_status shows bus activity, sensor_capture waits for the DUT's next transaction on an I2C sensor's bus and decodes it, sensor_stop ends it. A part the library lacks: read sensor_format, write a definition from the datasheet, check it with sensor_validate, then sensor_start it. A GPS module is gps_nmea on pins={tx: }. - Analog: dac_output (DC), generate (sine/square/sawtooth) and replay drive the DAC and route its path; adc_read gives one calibrated value, capture_adc a waveform summary; dac_stop ends any DAC output. -- 4-20 mA input: adc_read(source='current_in') reads terminal J8 and returns current in amps (0.004 to 0.020 for a live loop) next to the voltage across the 249 ohm sense resistor. calibration shows whether the pod has calibrated its ADC offset there. If not, analog readings can be off by up to about 50 mV: ask the user to disconnect J8, then calibrate (once per pod, stored on the pod; on firmware 3.9.3+ it corrects every ADC source). +- 4-20 mA input: adc_read(source='current_in') reads terminal J8 and returns current in amps (0.004 to 0.020 for a live loop) next to the voltage across the sense resistor (249 ohm; from analog module v3r5 100 ohm behind a 30 mA limiter, read in the low range by default, so a reading stuck near 28.5 to 31.5 mA is the limiter). calibration shows whether the pod has calibrated its ADC offset there. If not, analog readings can be off by up to about 50 mV: ask the user to disconnect J8, then calibrate (once per pod, stored on the pod; on firmware 3.9.3+ it corrects every ADC source). - 4-20 mA output: current_out(current) holds a loop current on terminal J9, in amps (0.012 is 12 mA), and returns the current actually held and the range. It needs an external floating loop supply on J9 and cannot go below about 4 mA or above about 20 mA. It shares the DAC with the voltage outputs and switches them off; dac_stop does not return the loop to 4 mA, current_out(0.004) does. The loop must float: nothing in it may touch pod ground, also not through a target that shares a ground with the pod (SWD, UART). Ask the user how J9 is wired first, and never suggest wiring J9 straight into J8. generate, replay and replay_waveform take dac_path='current_out' to play a waveform as a current (levels in amps); capture_adc(source='current_in') summarises the loop current in amps. - Gateware images: the FPGA runs either the 'loop' image (control_loop) or the 'deep_replay' image (replays longer than 2048 samples). control_loop, replay and replay_waveform switch automatically (~3 s; switched_image in the result says so). A switch resets the FPGA and stops any DAC output, UART session or sensor emulation, so start those after it. fpga_image switches explicitly. I2C/SPI/UART sensors run on a third, emulation image that sensor_start loads by itself (control_loop and deep replays are unavailable while it runs). - Logic: capture_la, then decode_la (i2c/uart/spi) re-decodes that capture without re-capturing, and la_timing measures edge times, pulse widths, frequency and the delay between two channels (e.g. trigger pin to result pin). @@ -80,7 +80,7 @@ 4-20 mA output J9 (current_out): loop powered, pin 1 plus to an external floating supply (8 V plus 20 mA times the loop resistance, 30 V at most), pin 2 the loop return (not pod ground). Nothing in that loop may touch pod ground. Input J8 (current_in): pin 1 plus, 249 ohm to - ground, pin 2 ground. Do not wire J9 straight into J8. + ground (100 ohm behind a 30 mA limiter from module v3r5), pin 2 ground. Do not wire J9 straight into J8. CAN: CAN+/CAN- through a TCAN1044 transceiver; the 120 ohm termination is switchable (can_open term). """ diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py index b5286bd..5e9c29d 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/models.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/models.py @@ -609,6 +609,10 @@ class AdcReadResult(BaseModel): "The pod's own calibration offset in volts, already taken out of voltage (current_in only).")) current: Optional[float] = Field(None, description=( "Loop current in amps on the 4-20 mA input (current_in only): 0.004 to 0.020 for a live loop.")) + sense_ohms: Optional[float] = Field(None, description=( + "The resistance current was computed with, ohms (current_in only, firmware 3.10.13+): 249 up to " + "analog module v3r4, about 100 from v3r5 (100 ohm behind a 30 mA limiter, so a loop reads at most " + "28.5 to 31.5 mA). Null on older firmware (249).")) range: Optional[str] = Field(None, description=( "The ADC input range the reading was taken in: normal or low (firmware 3.9.5+).")) fullscale: Optional[float] = Field(None, description="That range's full scale, volts (±).") diff --git a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py index 19306ab..3dba1b9 100644 --- a/packages/embeddedci-mcp/src/embeddedci_mcp/server.py +++ b/packages/embeddedci-mcp/src/embeddedci_mcp/server.py @@ -2122,13 +2122,14 @@ async def adc_read(source: AdcSource = "ext", range: AdcRangeArg = None) -> m.Ad """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. + at 6x the resolution on analog module v3r4+; overrange says the input clipped. From analog module v3r5 + current_in reads in the low range unless range is given (the next other route gives normal back). Refused while the input is still moving (e.g. a DAC output left running). """ r = await _call(lambda: SESSION.require().adc_read(source, range=range)) return m.AdcReadResult(source=r.source, voltage=r.voltage, count=r.count, span=r.span, - offset=r.offset, current=r.current, range=r.range or None, + offset=r.offset, current=r.current, sense_ohms=getattr(r, "sense_ohms", None), range=r.range or None, fullscale=r.fullscale, overrange=r.overrange) diff --git a/packages/embeddedci-mcp/tests/conftest.py b/packages/embeddedci-mcp/tests/conftest.py index 310fa31..cfb7b98 100644 --- a/packages/embeddedci-mcp/tests/conftest.py +++ b/packages/embeddedci-mcp/tests/conftest.py @@ -481,6 +481,7 @@ def _cmd_adc_read(self, req): if reply["source"] == "current_in": reply["offset_mv"] = round(self.current_in_offset_uv / 1000) reply["ua"] = round(reply["mv"] * 1000 / 249) + reply["sense_mohm"] = 249000 return reply def _cmd_calibrate(self, req): diff --git a/packages/embeddedci-mcp/tests/test_tools.py b/packages/embeddedci-mcp/tests/test_tools.py index 7845bba..182f94c 100644 --- a/packages/embeddedci-mcp/tests/test_tools.py +++ b/packages/embeddedci-mcp/tests/test_tools.py @@ -705,7 +705,14 @@ def test_calibrate_tools(connected): reading = call("adc_read", source="current_in") assert reading["offset"] == pytest.approx(0.004) assert reading["current"] == pytest.approx(3.301 / 249, abs=1e-6) + # The SDK reports the pod's sense resistor from 3.0.4 on; the minimum pinned SDK may not. + from embeddedci.benchpod.state import AdcReading + if "sense_ohms" in AdcReading.__dataclass_fields__: + assert reading["sense_ohms"] == pytest.approx(249.0) + else: + assert reading["sense_ohms"] is None assert call("adc_read", source="ext")["current"] is None + assert call("adc_read", source="ext")["sense_ohms"] is None stored = call("calibration") assert stored["calibrated"] is True and stored["count"] is None cleared = call("calibrate", clear=True) diff --git a/packages/embeddedci-openhtf/src/embeddedci_openhtf/analog.py b/packages/embeddedci-openhtf/src/embeddedci_openhtf/analog.py index 1c768a4..6c3e92a 100644 --- a/packages/embeddedci-openhtf/src/embeddedci_openhtf/analog.py +++ b/packages/embeddedci-openhtf/src/embeddedci_openhtf/analog.py @@ -301,7 +301,8 @@ def _rd(test, bench): raise RuntimeError("this pod's firmware does not report the loop current on current_in; " "update the firmware") test.measurements["current_in_a"] = r.current - test.logger.info("4-20 mA input = %.3f mA (%.4f V across 249 ohm)", r.current * 1000.0, r.voltage) + ohms = r.sense_ohms or 249.0 # 100 ohm from analog module v3r5 + test.logger.info("4-20 mA input = %.3f mA (%.4f V across %.0f ohm)", r.current * 1000.0, r.voltage, ohms) return _rd diff --git a/packages/embeddedci/CHANGELOG.md b/packages/embeddedci/CHANGELOG.md index 2631b06..c1cc17b 100644 --- a/packages/embeddedci/CHANGELOG.md +++ b/packages/embeddedci/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog — `embeddedci` +## 3.0.5 + +- **4-20 mA input on analog module v3r5** (firmware 3.10.13+): the sense resistor is 100 Ω (249 Ω up + to v3r4). `AdcReading.sense_ohms` and `Calibration.sense_ohms` give the resistance the pod + converts with, and `capture_adc(source="current_in")` uses it for `currents` (249 Ω when the + firmware does not say). On v3r5 the pod reads `current_in` in the low range unless `range` is + given; the SDK follows that range, and gives it back when a DAC output is routed after it. + ## 3.0.4 - **Read test runs back:** `embeddedci.benchpod.runs.api` lists the runs on embeddedci.com diff --git a/packages/embeddedci/README.md b/packages/embeddedci/README.md index 6825b94..8a3e519 100644 --- a/packages/embeddedci/README.md +++ b/packages/embeddedci/README.md @@ -874,7 +874,7 @@ how finely a transient was resolved. Measured on a v2 pod: 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 `current_in` -input is a 4-20 mA loop terminal (249 Ω), not a way to measure the target's supply. +input is a 4-20 mA loop terminal (249 Ω, 100 Ω from analog module v3r5), not a way to measure the target's supply. ## Flashing @@ -1647,7 +1647,26 @@ the 5 V DMM line, see below); it serves every source in the low range and shows ### 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 -4.98 V. Each pod's analog input has its own offset, from part tolerances: anywhere from a few mV +4.98 V. From analog module v3r5 (firmware 3.10.13+) the resistor is 100 Ω behind a series diode and +a 30 mA current limiter, which lowers what the pod takes from the loop to about 4.3 V at 20 mA: + +| | Module up to v3r4 | Module v3r5 and later | +|---|---|---| +| 4 mA / 20 mA | 0.996 V / 4.98 V | 0.4 V / 2.0 V | +| Voltage taken from the loop at 20 mA | about 5 V | about 4.3 V | +| Range `current_in` reads in by default | the range in use | `low` | +| Resolution | about 4 µA per count | about 1.7 µA per count (low), 10 µA (normal) | +| Measurable current | 0 to about 21 mA in the low range, more in normal | 0 to the limiter, 28.5 to 31.5 mA | + +On v3r5, `adc_read("current_in")`, `analog_path("current_in")` and `capture_adc(source="current_in")` +without `range` switch the ADC to the low range; the next route of another source or a DAC output +gives the normal range back. A reading that sits near 30 mA whatever the loop does is the limiter. +A reversed loop reads 0 (the diode blocks it). `AdcReading.sense_ohms` and +`Calibration.sense_ohms` give the resistance the pod converts with (249, or 100 Ω in parallel with +the ADC input divider: 99.990 normal, 99.995 low); captures of `current_in` use it for `currents`. +Calibration is the same on both: J8 open is 0 V. + +Each pod's analog input has its own offset, from part tolerances: anywhere from a few mV to about 50 mV. With J8 open the terminal is at 0 V, so the pod can measure that offset itself and keep it in its flash: diff --git a/packages/embeddedci/src/embeddedci/benchpod/client.py b/packages/embeddedci/src/embeddedci/benchpod/client.py index c619b3a..4a51601 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/client.py +++ b/packages/embeddedci/src/embeddedci/benchpod/client.py @@ -162,7 +162,9 @@ # The DAC output each named analog path drives (cal1/cal2 loop the 5 V / 12 V DAC back to the ADC). _ANALOG_PATH_DAC = {"dac_3v3": "3v3", "dac_5v": "5v", "dac_12v": "12v", "cal1": "5v", "cal2": "12v", "current_out": _CURRENT_OUT} -#: The sense resistor on the 4-20 mA input (J8): ``current_in`` reads the voltage across it. +#: The sense resistor on the 4-20 mA input (J8): ``current_in`` reads the voltage across it. 249 Ω +#: on analog modules up to v3r4 and the default for firmware that does not say; from v3r5 the pod +#: reports its own value (``Calibration.sense_ohms``, 100 Ω with the ADC divider in parallel). _CURRENT_IN_SENSE_OHMS = 249.0 #: The live zero a stopped current waveform returns to (microamps). _CURRENT_OUT_ZERO_UA = 4000 @@ -364,6 +366,9 @@ def __init__( # The DAC output this connection last routed (dac_output, analog_path, a routed waveform), # so a waveform played with route=False and no dac_path scales for it. None = unknown. self._routed_dac_path: Optional[str] = None + #: The pod put the ADC in the low range by itself, routing ``current_in`` on analog module + #: v3r5 (firmware 3.10.13+); the next DAC route puts it back, without saying so. + self._adc_low_auto = False self._api_base = api_base or os.environ.get(API_BASE_ENV) self._api_key = api_key or os.environ.get(API_KEY_ENV) self._cloud_user_token = cloud_user_token @@ -1744,8 +1749,10 @@ def analog_path(self, path: AnalogPath, *, range: Optional[AdcRange] = None) -> if range is not None: check_choice(range, ADC_RANGES, "range") req["range"] = range + before = self.capabilities.adc_range state = AnalogPathState.from_reply(self.command(req)) self._follow_adc_range(state.range) + self._note_auto_range(path == "current_in", range, before, state.range) if path in _ANALOG_PATH_DAC: self._routed_dac_path = _ANALOG_PATH_DAC[path] elif path == "off": @@ -1766,6 +1773,7 @@ def dac_output(self, path: DacOutputPath, *, volts: Optional[float] = None) -> D req["volts"] = float(volts) out = DacOutput.from_reply(self.command(req)) self._routed_dac_path = None if path == "off" else path + self._dac_routed() return out # -- the 4-20 mA output (J9) ------------------------------------------------ @@ -1817,7 +1825,11 @@ def adc_read(self, source: AdcSource = "ext", *, range: Optional[AdcRange] = Non On ``current_in`` the reading also carries ``current``, the loop current in amps, and already has this pod's calibration offset taken out (:meth:`calibrate`); ``offset`` says - how much that was. + how much that was. From analog module v3r5 (100 Ω sense resistor, 30 mA limiter, firmware + 3.10.13+) ``current_in`` reads in the low range unless ``range`` says otherwise: about + 1.7 µA per count, up to the limiter's 28.5 to 31.5 mA. The next route of another source or + output gives the normal range back. ``sense_ohms`` is the resistance ``current`` was + computed with. ``range`` switches the ADC input range first (:meth:`adc_range`): ``"low"`` reads up to ±5.46 V at about 6x the resolution on analog module v3r4+ (not on ``cal2``). The reading @@ -1828,8 +1840,10 @@ def adc_read(self, source: AdcSource = "ext", *, range: Optional[AdcRange] = Non if range is not None: check_choice(range, ADC_RANGES, "range") req["range"] = range + before = self.capabilities.adc_range reading = AdcReading.from_reply(self.command(req)) self._follow_adc_range(reading.range) + self._note_auto_range(source == "current_in", range, before, reading.range) return reading # -- the ADC input range (analog module v3r4+) ------------------------------- @@ -1853,6 +1867,8 @@ def adc_range(self, range: Optional[AdcRange] = None) -> AdcRangeState: check_choice(range, ADC_RANGES, "range") req["range"] = range state = AdcRangeState.from_reply(self.command(req)) + if range is not None: + self._adc_low_auto = False self._set_adc_range_fit(state) return state @@ -1875,6 +1891,20 @@ def _set_adc_range_fit(self, state: AdcRangeState) -> None: unwrap = caps.adc_affine.unwrap if caps.adc_affine is not None else True caps.adc_affine = AffineCal(a=state.a or 0.0, b=state.b, unwrap=unwrap) + def _note_auto_range(self, current_in: bool, asked: Optional[str], before: str, after: str) -> None: + """After a route: on analog module v3r5 ``current_in`` without a ``range`` takes the low + range by itself, and the next route of another path gives it back.""" + if asked is not None or not current_in: + self._adc_low_auto = False + elif after == "low" and before != "low": + self._adc_low_auto = True + + def _dac_routed(self) -> None: + """A DAC output was routed: a low range ``current_in`` picked by itself is normal again.""" + if self._adc_low_auto: + self._adc_low_auto = False + self._follow_adc_range("normal") + def _follow_adc_range(self, rng: str) -> None: """A reply said the pod is in range ``rng``: re-read the fit when the cached one is for another range (``off`` and ``cal2`` put the range back to normal).""" @@ -2645,7 +2675,8 @@ def _scale_current_in(cap: Capture, fit: Optional[Calibration]) -> Capture: else: unwrapped = (c + ADC_WRAP_SPAN if c < ADC_WRAP_THRESHOLD else c for c in cap.counts) cap.volts = [fit.a + fit.b * c for c in unwrapped] - cap.currents = [v / _CURRENT_IN_SENSE_OHMS for v in cap.volts] + ohms = fit.sense_ohms or _CURRENT_IN_SENSE_OHMS + cap.currents = [v / ohms for v in cap.volts] return cap def capture_la(self, samples: int = 4096, *, sample_rate_hz: Optional[float] = None, @@ -2795,6 +2826,7 @@ def _route_output(self, dac_path: str) -> None: self.command({"cmd": "analog_path", "path": _CURRENT_OUT}) else: self.command({"cmd": "dac_out", "path": dac_path}) + self._dac_routed() self._routed_dac_path = dac_path def _default_dac_path(self, route: bool) -> str: @@ -2933,6 +2965,8 @@ def _generate16(self, waveform: str, *, freq_hz: float, amplitude: float, offset d = _dict(self.command(req)) if route: self._routed_dac_path = dac_path # the pod routed it + if dac_path != _CURRENT_OUT: + self._dac_routed() return DacHandle(stop=self._stop_for(dac_path), dac_path=dac_path, cotrig=bool(d.get("cotrig", False)), data=d) diff --git a/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json b/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json index 64dd5b1..80fe3a0 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json +++ b/packages/embeddedci/src/embeddedci/benchpod/error_catalog.json @@ -1,7 +1,7 @@ { "_generated": "GENERATED by tools/gen_errors.py from errors/catalog.toml. DO NOT EDIT: edit the catalog.", "version": 1, - "catalog_sha256": "5d8cec0705e0316ea5a49c15f9ae0459f0da8c258e55dd35f5bd39d392aa2ac5", + "catalog_sha256": "ef614af22c086dc10994ecb05d7148b8f27cf1483a34bc3309a39e5ef9768550", "docs_url": "https://embeddedci.com/docs/errors#{code}", "codes": { "BP0001": { @@ -430,6 +430,38 @@ "mcp": "take the lease again with lease_acquire, then renew it before its ttl_s runs out", "web": "The session's lease ran out. Start it again." } + }, + "BP0028": { + "name": "vref_5v_missing", + "area": "io", + "since": "next", + "message": "5 V did not come up on pin 21 ({mv} mV)", + "cause": "In 5 V mode the pod switches pin 21, the rail every pull-up pulls to, to its USB supply. The pod measures pin 21 and found it below 4.3 V, so it went back to the previous I/O voltage. A weak USB supply, a hub without power, or a load on pin 21 causes it.", + "args": { + "mv": "int" + }, + "fix": { + "sdk": "power the pod from a USB port or supply that gives 5 V, check what is wired to pin 21, then set 5 V again", + "cli": "power the pod from a USB port or supply that gives 5 V, check what is wired to pin 21, then run `benchpod la voltage 5.0` again", + "mcp": "ask the user to power the pod from a USB port or supply that gives 5 V and to check pin 21, then call set_la_voltage(5.0) again", + "web": "Pin 21 did not reach 5 V. Power the pod from a USB port that gives 5 V and check what is wired to pin 21." + } + }, + "BP0029": { + "name": "pull_rail_down", + "area": "io", + "since": "next", + "message": "pin 21 is down ({mv} mV): the pull resistors are off until it is back", + "cause": "The pull resistors pull up to J1 pin 21. The pod measures pin 21 and found it down, so it holds both pull expanders off (with pin 21 down they would answer on the same address). Pin 21 is shorted, overloaded, or a DUT holds it down.", + "args": { + "mv": "int" + }, + "fix": { + "sdk": "check what is wired to J1 pin 21 (bp.la_voltage() shows its state), remove the short or load, then set the pull again", + "cli": "check what is wired to J1 pin 21 (`benchpod la voltage` shows its state), remove the short or load, then set the pull again", + "mcp": "ask the user to check what is wired to J1 pin 21 (set_la_voltage with no voltage shows its state), then set the pull again", + "web": "Pin 21 is down, so the pull resistors are off. Check what is wired to pin 21." + } } } } diff --git a/packages/embeddedci/src/embeddedci/benchpod/feature_map.json b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json index 87a35c3..7d42158 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/feature_map.json +++ b/packages/embeddedci/src/embeddedci/benchpod/feature_map.json @@ -1,8 +1,8 @@ { "_generated": "GENERATED by tools/gen_features.py from features/features.toml. DO NOT EDIT: edit the table.", "schema": 1, - "revision": 5, - "table_sha256": "b6cc066b3aa988a94742bde342db983672f8d710be32ed21486242d693523468", + "revision": 7, + "table_sha256": "a6a88ef88c0925212fcfa41f87409572bc0210a9fd02f2f418fc2a50b86eba64", "floor": "3.9.2", "docs_base": "https://github.com/embeddedci-com/benchpod-firmware/blob/main/docs/", "facts": { @@ -42,6 +42,9 @@ "hw": "adc_low_range", "frame": "adc_low_range", "legacy_caps": "adc_low_range" + }, + "vref_out": { + "hw": "vref_out" } }, "releases": [ @@ -124,6 +127,11 @@ "firmware": "3.10.12", "gateware": 58, "date": "2026-11-18" + }, + { + "firmware": "3.10.13", + "gateware": 59, + "date": "2026-11-19" } ], "features": { @@ -655,21 +663,39 @@ }, "la_pull_1v8": { "rev": 4, - "firmware": "next", + "firmware": "3.10.13", "board": "any", "docs": "API.md#switch-or-query-an-la-pin-pull-resistor" }, "log_level": { "rev": 4, - "firmware": "next", + "firmware": "3.10.13", "board": "any", "docs": "usb-serial-interface.md#log-levels" }, "lease": { "rev": 5, - "firmware": "next", + "firmware": "3.10.13", "board": "any", "docs": "API.md#pod-lease" + }, + "la_5v": { + "rev": 6, + "firmware": "3.10.13", + "board": "any", + "requires": [ + "vref_out" + ], + "docs": "API.md#la_voltage--select-the-la-io-bank-voltage" + }, + "la_pull_strength": { + "rev": 7, + "firmware": "3.10.13", + "board": "any", + "requires": [ + "vref_out" + ], + "docs": "API.md#pull-resistors-on-digital-v3r4" } } } diff --git a/packages/embeddedci/src/embeddedci/benchpod/results.py b/packages/embeddedci/src/embeddedci/benchpod/results.py index fb5307a..6edbcd8 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/results.py +++ b/packages/embeddedci/src/embeddedci/benchpod/results.py @@ -93,7 +93,8 @@ class Capture: sample_rate_hz: float = 0.0 source: str = "" #: Loop current per sample in amps, for a capture of ``current_in`` (the 4-20 mA input, J8): - #: ``volts`` across the pod's 249 Ω sense resistor. Empty for every other source. + #: ``volts`` across the pod's sense resistor (249 Ω; 100 Ω from analog module v3r5, as the pod + #: reports it in ``Calibration.sense_ohms``). Empty for every other source. currents: List[float] = field(default_factory=list) #: The trigger that started the capture (t = 0 is its moment), or ``None``. trigger: Optional[Trigger] = None diff --git a/packages/embeddedci/src/embeddedci/benchpod/state.py b/packages/embeddedci/src/embeddedci/benchpod/state.py index e846a32..db54853 100644 --- a/packages/embeddedci/src/embeddedci/benchpod/state.py +++ b/packages/embeddedci/src/embeddedci/benchpod/state.py @@ -26,6 +26,12 @@ def _opt_int(d: Mapping[str, Any], key: str) -> Optional[int]: return None +def _opt_ohms(d: Mapping[str, Any]) -> Optional[float]: + """``sense_mohm`` (the 4-20 mA input's sense resistance, milliohms) in ohms, or ``None``.""" + mohm = _opt_int(d, "sense_mohm") + return None if mohm is None or mohm <= 0 else mohm / 1000.0 + + def _raw() -> Any: return field(default_factory=dict, repr=False, compare=False) @@ -394,7 +400,8 @@ class AdcReading: #: ``current_in``, and older firmware. offset: Optional[float] = None #: Loop current in amps on ``current_in``, the 4-20 mA input: ``voltage`` across the pod's - #: 249 Ω sense resistor. ``None`` on every other source and on older firmware. + #: sense resistor (249 Ω, or 100 Ω from analog module v3r5). ``None`` on every other source and + #: on older firmware. current: Optional[float] = None #: The ADC input range the reading was taken in (``"normal"`` / ``"low"``) and its full scale #: in volts (±). ``""`` / ``None`` on firmware before 3.9.5. @@ -403,6 +410,11 @@ class AdcReading: #: A sample sat on an ADC rail: the input is past ``fullscale`` and ``voltage`` is only a #: bound. Use the normal range. ``False`` on firmware before 3.9.5. overrange: bool = False + #: On ``current_in``: the resistance ``current`` was computed with, in ohms (firmware 3.10.13+). + #: 249.0 on analog modules up to v3r4; from v3r5 the 100 Ω sense resistor in parallel with the + #: ADC input divider, 99.990 in the normal range and 99.995 in the low range. ``None`` on other + #: sources and older firmware (which is always 249 Ω). + sense_ohms: Optional[float] = None raw: Dict[str, Any] = _raw() @classmethod @@ -418,7 +430,7 @@ def from_reply(cls, reply: Any) -> "AdcReading": offset=None if offset_mv is None else offset_mv / 1000.0, current=None if ua is None else ua / 1e6, range=str(d.get("range", "") or ""), fullscale=None if fs is None else fs / 1000.0, overrange=d.get("overrange") is True, - raw=d) + sense_ohms=_opt_ohms(d), raw=d) @dataclass(frozen=True) @@ -508,6 +520,10 @@ class Calibration: #: module's EEPROM, digital v3r3: it moves with the module), ``"pod"`` (only the pod's flash) or #: ``"none"``. ``None`` on older firmware. stored: Optional[str] = None + #: The resistance a ``current_in`` voltage is turned into the loop current with, in ohms, for + #: the range in use (firmware 3.10.13+): 249.0 on analog modules up to v3r4, from v3r5 99.990 + #: (normal range) or 99.995 (low range). ``None`` on older firmware, which is always 249 Ω. + sense_ohms: Optional[float] = None raw: Dict[str, Any] = _raw() @classmethod @@ -529,7 +545,7 @@ def from_reply(cls, reply: Any) -> "Calibration": measured=None if meas is None else { k[:-3]: (_opt_int(meas, k) or 0) / 1e6 for k in meas if k.endswith("_uv")}, stored=d.get("stored") if isinstance(d.get("stored"), str) else None, - raw=d) + sense_ohms=_opt_ohms(d), raw=d) @dataclass(frozen=True) diff --git a/packages/embeddedci/tests/api_surface.json b/packages/embeddedci/tests/api_surface.json index 4a4e04f..a75463a 100644 --- a/packages/embeddedci/tests/api_surface.json +++ b/packages/embeddedci/tests/api_surface.json @@ -48,6 +48,7 @@ "range", "fullscale", "overrange", + "sense_ohms", "raw" ], "from_reply": "(cls, reply: 'Any') -> \"'AdcReading'\"" @@ -233,6 +234,7 @@ "zero_count", "measured", "stored", + "sense_ohms", "raw" ], "from_reply": "(cls, reply: 'Any') -> \"'Calibration'\"" diff --git a/packages/embeddedci/tests/e2e/test_e2e_pod.py b/packages/embeddedci/tests/e2e/test_e2e_pod.py index 080a8f3..d6bf437 100644 --- a/packages/embeddedci/tests/e2e/test_e2e_pod.py +++ b/packages/embeddedci/tests/e2e/test_e2e_pod.py @@ -435,7 +435,9 @@ def test_current_in_reads_zero_with_j8_open(pod): pod.analog_path("off") if reading.current is None: pytest.skip("this pod's firmware does not report the loop current") - assert reading.current == pytest.approx(reading.voltage / 249, abs=4e-6) + # 249 ohm up to analog module v3r4; from v3r5 the pod reports about 100 ohm (firmware 3.10.13+). + ohms = reading.sense_ohms or 249.0 + assert reading.current == pytest.approx(reading.voltage / ohms, abs=4e-6) limit = 30e-6 if pod.capabilities.calibrate and pod.calibration().calibrated else 100e-6 assert abs(reading.current) < limit, f"J8 open reads {reading.current * 1e6:.0f} uA: is something connected?" diff --git a/packages/embeddedci/tests/test_current_in_shunt.py b/packages/embeddedci/tests/test_current_in_shunt.py new file mode 100644 index 0000000..1174866 --- /dev/null +++ b/packages/embeddedci/tests/test_current_in_shunt.py @@ -0,0 +1,138 @@ +"""The 4-20 mA input (J8) on both analog module revisions: 249 ohm up to v3r4, 100 ohm from v3r5 +(firmware 3.10.13+), where ``current_in`` takes the low range by itself and the pod reports the +resistance it converts with (``sense_mohm``).""" + +from __future__ import annotations + +from typing import Any, Dict + +import pytest + +from embeddedci.benchpod import BenchPod +from embeddedci.benchpod.state import AdcReading, Calibration + +from test_adc_range import RangePod + + +class V3r5Pod(RangePod): + """A v3r5 module: routing current_in without a range picks the low range, the next relay path + (or a DAC route) gives it back, as the firmware does (analog_path_auto_range).""" + + def __init__(self, shunt_100r: bool = True) -> None: + super().__init__(supported=True) + self.shunt_100r = shunt_100r + self.auto = False + + def _sense_mohm(self) -> int: + if not self.shunt_100r: + return 249000 + return 99995 if self.range == "low" else 99990 + + def _route(self, path: str, rng: Any) -> None: + if rng is not None: + self.auto = False + if path in ("off", "cal2"): + self.range = "normal" + self._set(rng) + return + if path in ("off", "cal2"): + self.range, self.auto = "normal", False + elif path == "current_in": + if self.range == "normal" and self.shunt_100r: + self.range, self.auto = "low", True + elif path != "current_out" and self.auto: + self.range, self.auto = "normal", False + + def command(self, req: dict) -> Any: + cmd = req["cmd"] + if cmd == "analog_path": + self.commands.append(req) + self._route(req["path"], req.get("range")) + return {"path": req["path"], "u55": 0, "u58": 0, "range": self.range} + if cmd == "adc_read": + self.commands.append(req) + self._route(req["source"], req.get("range")) + d: Dict[str, Any] = {"source": req["source"], "mv": 1600, "uv": 1600212, "count": 55938, "span": 5, + "range": self.range, "fullscale_mv": 5462 if self.range == "low" else 32856, + "overrange": False} + if req["source"] == "current_in": + mohm = self._sense_mohm() + d.update({"offset_mv": 0, "ua": round(1600212 * 1000 / mohm), "sense_mohm": mohm}) + return d + if cmd == "dac_out": + self.commands.append(req) + self._route("dac_" + req["path"] if req["path"] != "off" else "off", None) + return {"path": req["path"], "mv": 0, "code": 0} + d = super().command(req) + if cmd == "calibrate": + d["sense_mohm"] = self._sense_mohm() + return d + + +def _pod(shunt_100r: bool = True) -> "tuple[BenchPod, V3r5Pod]": + t = V3r5Pod(shunt_100r) + return BenchPod(transport=t, lease=False), t + + +def test_models_carry_the_sense_resistance(): + r = AdcReading.from_reply({"source": "current_in", "mv": 1600, "uv": 1600212, "count": 1, "ua": 16003, + "sense_mohm": 99995, "range": "low"}) + assert r.sense_ohms == pytest.approx(99.995) and r.current == pytest.approx(0.016003) + c = Calibration.from_reply({"source": "current_in", "calibrated": True, "a_uv": 1, "b_nv": 1, + "sense_mohm": 249000}) + assert c.sense_ohms == pytest.approx(249.0) + # Older firmware does not say: None, and the SDK takes 249 ohm. + assert AdcReading.from_reply({"source": "current_in", "mv": 996, "ua": 4000}).sense_ohms is None + assert Calibration.from_reply({"source": "current_in", "calibrated": False}).sense_ohms is None + assert Calibration.from_reply({"source": "current_in", "sense_mohm": 0}).sense_ohms is None + + +def test_v3r4_reads_as_before(): + bp, t = _pod(shunt_100r=False) + r = bp.adc_read("current_in") + assert r.range == "normal" and r.sense_ohms == pytest.approx(249.0) + assert r.current == pytest.approx(1.600212 / 249, abs=1e-6) + cap = bp.capture_adc(2, source="current_in") + assert cap.currents == pytest.approx([v / 249.0 for v in cap.volts]) + + +def test_v3r5_reads_current_in_in_the_low_range(): + bp, t = _pod() + bp.capabilities + r = bp.adc_read("current_in") + assert t.commands[0] == {"cmd": "adc_read", "source": "current_in"} # no range sent: the pod picks it + assert r.range == "low" and r.fullscale == pytest.approx(5.462) + assert r.sense_ohms == pytest.approx(99.995) and r.current == pytest.approx(0.016003, abs=1e-6) + assert bp.capabilities.adc_range == "low" # captures now scale with the low fit + # Another source gets the normal range back, and the SDK follows. + assert bp.adc_read("ext").range == "normal" and bp.capabilities.adc_range == "normal" + # Asked for, the normal range stays on current_in: 100 ohm || 992.5k. + r = bp.adc_read("current_in", range="normal") + assert r.range == "normal" and r.sense_ohms == pytest.approx(99.990) + + +def test_v3r5_capture_is_in_amps_through_100_ohm(): + bp, t = _pod() + cap = bp.capture_adc(2, source="current_in") + assert t.commands[0] == {"cmd": "analog_path", "path": "current_in"} + assert cap.range == "low" + assert cap.currents and cap.currents == pytest.approx([v / 99.995 for v in cap.volts]) + # 59538 in the low fit is about 1 V: 10 mA through 100 ohm (it was 4 mA through 249 ohm). + assert cap.currents[1] == pytest.approx(0.010, abs=2e-4) + + +def test_a_dac_route_after_current_in_brings_the_normal_range_back(): + bp, t = _pod() + bp.analog_path("current_in") + assert bp.capabilities.adc_range == "low" + bp.dac_output("12v", volts=10.0) # the pod put K5 back without saying so + assert t.range == "normal" and bp.capabilities.adc_range == "normal" + assert t.commands[-1] == {"cmd": "adc_range"} # the normal fit was re-read + + +def test_a_low_range_the_user_chose_is_not_given_back(): + bp, t = _pod() + bp.analog_path("current_in", range="low") + n = len(t.commands) + bp.dac_output("5v", volts=1.0) + assert t.range == "low" and bp.capabilities.adc_range == "low" and len(t.commands) == n + 1