Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions packages/embeddedci-mcp/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
4 changes: 2 additions & 2 deletions packages/embeddedci-mcp/src/embeddedci_mcp/guide.py
Original file line number Diff line number Diff line change
Expand Up @@ -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=<name or YAML>, 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: <LA wired to the DUT RX>}.
- 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).
Expand Down Expand Up @@ -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).
"""
4 changes: 4 additions & 0 deletions packages/embeddedci-mcp/src/embeddedci_mcp/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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 (±).")
Expand Down
5 changes: 3 additions & 2 deletions packages/embeddedci-mcp/src/embeddedci_mcp/server.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)


Expand Down
1 change: 1 addition & 0 deletions packages/embeddedci-mcp/tests/conftest.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Expand Down
7 changes: 7 additions & 0 deletions packages/embeddedci-mcp/tests/test_tools.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 8 additions & 0 deletions packages/embeddedci/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
23 changes: 21 additions & 2 deletions packages/embeddedci/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down
40 changes: 37 additions & 3 deletions packages/embeddedci/src/embeddedci/benchpod/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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":
Expand All @@ -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) ------------------------------------------------
Expand Down Expand Up @@ -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
Expand All @@ -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+) -------------------------------
Expand All @@ -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

Expand All @@ -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)."""
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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)

Expand Down
Loading