1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
//! # Driver for the [LTC2949](<https://www.analog.com/en/products/ltc2949.html>) current, voltage, charge and energy monitor.
//!
//! The LTC2949 is **not** a member of the LTC681X cell-monitor family - its register map (paginated, 256+
//! bytes) and command framing (`DCMD` 0xFE with an ID byte and configurable PEC stride) are
//! distinct from the cell-monitor ADCV/RDCV model. It does however share isoSPI signalling
//! and the PEC15 checksum with the LTC681X family and is intended to live on the same bus.
//!
//! ## Bus topology
//!
//! This driver targets the **addressable, parallel-to-daisy-chain** arrangement of
//! datasheet Figure 12(B): the LTC2949 hangs off the isoSPI bus *in parallel* with a
//! daisy chain of LTC68xx cell monitors (typically via an LTC6820), rather than being
//! chained inside it. Because the LTC2949 is reached directly:
//!
//! * **Register reads and writes both use `DCMD`** (command 0xFE). The cell monitors do
//! not understand `DCMD`, so it implicitly addresses the LTC2949 and its response
//! comes straight back with no shift-register prefix to discard (datasheet Table 10,
//! "Parallel to Daisy Chain or LTC2949 Sole").
//! * **`BCREN` is kept cleared** (the default) so the LTC2949 ignores broadcast RDCV
//! reads and never collides on the bus with the cell monitors.
//! * Synchronous fast conversions are triggered with a **broadcast `ADCV`** (reaching the
//! LTC2949 and every cell monitor at once); the LTC2949's own fast results, if needed,
//! are read back with an **addressed RDCV** (`RDCVCONF = 1`, `BCREN = 0`).
//!
//! The same framing also covers the "LTC2949 sole" case (no cell monitors on the bus at
//! all), so no separate construction is needed for that.
//!
//! ## Scope
//!
//! Initial coverage matches the user-confirmed scope:
//!
//! * Wake-up, mode control (OPCTRL), ADC configuration (ADCCONF). Timed operations are
//! split into non-blocking halves that return the required wait in microseconds —
//! mirroring `CommandTime` on the cell-monitor client —
//! so hosts with cooperative schedulers own the waiting themselves (no `DelayNs` seam).
//! * Slow-mode result registers (`I1`, `I2`, `P1`, `P2`, `BAT`, `TEMP`, `VCC`, `SLOT1/2`).
//! * Accumulators (charge `C1..C3`, energy `E1/E2/E4`, time `TB1..TB4`), plus the
//! memory-lock handshake for coherent multi-register snapshots.
//! * Decoded status/fault registers (`STATUS`, `FAULTS`, `EXTFAULTS`).
//! * Fast mode trigger (`FACTRL`, broadcast `ADCV`) and FIFO drain.
//! * Steinhart–Hart linearisation coefficients for the two NTC channels
//! ([`client::Client::write_ntc_coefficients`]), including the `f32 → Float24` encoding.
//!
//! The overcurrent-comparator threshold registers (used to arm the hardware
//! `LTC_OVERCURRENT` one-shot) and EEPROM are deliberately out of scope for this cut;
//! `read_faults`/`read_extfaults` expose the fault bytes but no typed bitfields yet.
//!
//! ## Example
//!
//! End-to-end initialisation for a 3 × LTC6813 stack with an LTC2949 sitting on
//! top. The example follows the datasheet-prescribed procedure for shunt
//! temperature compensation (Table 77, "Procedure to Enable Temperature
//! Compensation of Sense Resistor") so every register touched is something the
//! datasheet asks you to write before leaving STANDBY.
//!
//! ```
//! use ltc2949::client::{
//! AdcConfiguration, Channel, Client, FastControlRegister, FifoTag, MuxInput, NtcConfig, OpsControlRegister, ShuntTcConfig,
//! LTC2949, T_BOOT_US,
//! };
//! use embedded_hal::delay::DelayNs;
//! # use ltc2949::example::{ExampleDelay, ExampleSPIDevice};
//! # (|| -> Result<(), ltc2949::client::Error<ExampleSPIDevice>> {
//!
//! // Mock Hardware peripherals for example
//! let spi = ExampleSPIDevice::default();
//! let mut delay = ExampleDelay::default();
//!
//! // The LTC2949 hangs off the isoSPI bus in parallel with the cell-monitor chain.
//! let mut client = LTC2949::new(spi);
//!
//! // ---- Step 0 – wake the device ---------------------------------------
//! // Two dummy bytes provide the isoSPI wake edge; the device then needs tBOOT
//! // (≤100 ms, the returned value) to reach STANDBY. The driver never blocks:
//! // the host waits the returned microseconds its own way (timer poll, delay, RTOS),
//! // then confirms the wake-up so the core doesn't auto-sleep again after 1 s.
//! let boot_us = client.start_wake_up()?;
//! assert_eq!(T_BOOT_US, boot_us);
//! delay.delay_us(boot_us);
//! client.confirm_wake_up()?;
//!
//! // ---- Step 1 – stay in STANDBY (CONT=0) ------------------------------
//! // The wake-up sequence leaves the core in STANDBY; if it was already in
//! // MEASURE you'd need: client.write_opctrl(OpCtrl::default())?;
//! //
//! // It is also recommended to check STATUS / FAULTS / EXTFAULTS here and
//! // clear any UVLO/POR flags. All three registers have typed accessors.
//! let _power_on_status = client.read_status()?;
//!
//! // ---- Step 2a – program NTC1 coefficients ----------------------------
//! // Example values from datasheet Table 75 (Vishay NTCLE203E3103SB0, 10 kΩ
//! // reference divider).
//! client.write_ntc_coefficients(
//! Channel::One,
//! &NtcConfig {
//! r_ref: 10_000.0,
//! a: 1.1382e-3,
//! b: 2.3267e-4,
//! c: 0.93243e-7,
//! },
//! )?;
//!
//! // ---- Step 2b – program shunt-1 temperature compensation -------------
//! // Copper sense resistor with TC = 3900 ppm/K, R_nominal characterised at
//! // 25 °C. Set both terms to 0.0 if you use a low-TC alloy and don't need
//! // compensation.
//! client.write_shunt_tc(
//! Channel::One,
//! &ShuntTcConfig { tc: 0.0039, t_ref: 25.0, tc2: 0.0 },
//! )?;
//!
//! // ---- Step 3 – tell the AUX ADC to report SLOT1 as a temperature -----
//! // NTC1 on, both power ADCs left in power-mode (P1ASV/P2ASV = 0).
//! client.write_adcconf(AdcConfiguration::default().with_ntc1(true))?;
//!
//! // ---- Step 4 – route the NTC's V-pin into SLOT1 ----------------------
//! // Typical wiring: VREF -- R_ref -- V1 -- NTC -- AGND. We read the V1 pin
//! // single-ended (MUXP = V1, MUXN = AGND); the device's NTC1 lineariser
//! // combines the reading with R_ref to compute R_NTC and then the
//! // temperature via Steinhart-Hart.
//! client.write_slot_mux(Channel::One, MuxInput::Agnd, MuxInput::V1)?;
//!
//! // ---- Step 5 – commit page-1 configuration (ADJUPD) ------------------
//! // OPCTRL.ADJUPD is a set-only bit; the device clears it after ≤100 ms.
//! // Poll OPCTRL.adjupd() == false to know when the update has landed.
//! client.write_opctrl(OpsControlRegister::default().with_adjupd(true))?;
//! delay.delay_ms(100);
//!
//! // ---- Step 6 – enter continuous slow-mode measurement ----------------
//! // ≈100 ms per cycle, 18-bit results. First update lands ~50 ms later.
//! client.write_opctrl(OpsControlRegister::default().with_cont(true))?;
//! delay.delay_ms(100);
//!
//! // ---- Slow-mode reads ------------------------------------------------
//! // After ≥100 ms of CONT, the result registers are populated. LSB sizes
//! // are documented on each method; here are the conversions you'll
//! // typically pair with each value.
//! let i1 = client.read_current1()?; // CurrentSenseVoltage
//! let v_shunt_uv = (i1.decode() * 1_000_000.0) as i32;
//! // For a 100 µΩ shunt: current_uA = v_shunt_uv * 10
//!
//! let bat = client.read_bat()?; // BatteryVoltage
//! let bat_uv = (bat.decode() * 1_000_000.0) as i32;
//! assert_eq!(4_629_375, bat_uv);
//!
//! let slot1 = client.read_slot1()?; // SlotValue
//! let temp_decic = (slot1.decode_temperature() * 10.0) as i32;
//! assert_eq!(250, temp_decic);
//!
//! // ---- Charge accumulation (state-of-charge) --------------------------
//! // C1 keeps integrating current as long as CONT is set; coulombs are
//! // C1 · 377.887 ps · V / R_shunt (internal clock or 4 MHz crystal).
//! let charge1 = client.read_charge1()?; // AccumulatedCharge
//! let coulombs = charge1.decode_coulombs(100e-6); // 100 µΩ shunt
//! assert!((coulombs - 37.7887).abs() < 0.0001);
//!
//! // ---- Fast measurements synchronised with the cell monitors ----------
//! // Configure channels 1 and 2 for fast single-shot, then broadcast ADCV
//! // so the LTC2949 and every LTC6813 trigger at the same instant.
//! client.write_factrl(FastControlRegister::default().with_fach1(true).with_fach2(true))?;
//! client.trigger_adcv_broadcast()?;
//! delay.delay_us(800);
//!
//! // Fast continuous: set FACONV=1 and drain the FIFO periodically.
//! client.write_factrl(
//! FastControlRegister::default().with_faconv(true).with_fach1(true).with_fach2(true),
//! )?;
//! delay.delay_us(1_260);
//! assert_eq!(302_060, delay.elapsed_us());
//!
//! // Then read up to 32 samples at a time:
//! let samples = client.read_fifo_i1::<32>()?;
//! for s in &samples {
//! // 16-bit signed, LSB = 7.60371 µV across the shunt.
//! let uv = (s.raw as i32 * 760_371) / 100_000;
//! if s.tag == FifoTag::Ok {
//! assert_eq!(1_946, uv);
//! }
//! }
//! # Ok(())
//! # })().unwrap();
//! ```
//!
//! ## Alongside LTC6813 / LTC6812 cell monitors on one isoSPI bus
//!
//! In the Figure 12(B) topology the LTC2949 and a daisy chain of LTC68xx cell monitors
//! share a single isoSPI link (usually one LTC6820). At the `embedded-hal` level that one
//! physical [`SpiBus`](embedded_hal::spi::SpiBus) is shared between two
//! [`embedded_hal::spi::SpiDevice`] handles — one driving the
//! [`client::Client`], the other driving the [LTC681X client](https://docs.rs/ltc681x/0.6.2/ltc681x/monitor/trait.LTC681XClient.html) cell
//! monitor client — typically via `embedded-hal-bus` (e.g. `RefCellDevice`,
//! `AtomicDevice` or `CriticalSectionDevice`).
//!
//! Because both devices sit on the same wire, a single **broadcast `ADCV`** triggers a
//! synchronous conversion on every device at once: the cell monitors convert their cells
//! and the LTC2949 converts whichever fast channels its `FACTRL` selects. Issuing the
//! broadcast through the cell-monitor client puts exactly one `ADCV` on the bus, which the
//! parallel LTC2949 also hears.
//!
//! ```
//! use ltc2949::client::{FastControlRegister, Client, LTC2949, OpsControlRegister};
//! use ltc681x::ltc6813::{CellSelection, LTC6813};
//! use ltc681x::monitor::{ADCMode, LTC681X, LTC681XClient};
//!
//! // `meter_spi` and `chain_spi` are two SpiDevice handles to the *same* isoSPI bus
//! // (build them from one shared SpiBus with embedded-hal-bus). All waits below are
//! // host-owned — poll a timer, sleep, or delay as the platform allows. For an LTC6812
//! // stack, swap the type and the chain length — the flow is identical.
//! # fn demo<M, C>(meter_spi: M, chain_spi: C) -> Result<(), ()>
//! # where
//! # M: embedded_hal::spi::SpiDevice<u8>,
//! # C: embedded_hal::spi::SpiDevice<u8>,
//! # {
//! // The LTC2949 hangs off the bus in parallel and is addressed directly via DCMD.
//! let mut meter = LTC2949::new(meter_spi);
//! // Three LTC6813 cell monitors form the daisy chain.
//! let mut chain: LTC681X<_, _, LTC6813, 3> = LTC681X::ltc6813(chain_spi);
//!
//! // ---- Configure the meter (datasheet "Single Shunt Configuration") -----------
//! // CH1 stays in slow high-precision mode for charge/energy integration; CH2 is set
//! // to fast mode so a broadcast ADCV makes it snapshot synchronously with the cells.
//! let boot_us = meter.start_wake_up().map_err(|_| ())?;
//! // ... host waits `boot_us` microseconds ...
//! meter.confirm_wake_up().map_err(|_| ())?;
//! meter.write_opctrl(OpsControlRegister::default().with_cont(true)).map_err(|_| ())?; // CONT prereq
//! meter.write_factrl(FastControlRegister::default().with_fach2(true)).map_err(|_| ())?; // CH2 fast
//!
//! // ---- One broadcast ADCV → both devices convert at the same instant ----------
//! // start_conv_cells emits a *broadcast* ADCV (A/B address bits = 0), so it reaches
//! // the daisy chain and the parallel LTC2949 alike. Its CommandTime reports the cell
//! // conversion duration (all groups, normal mode ≈ 2.3 ms); the LTC2949 fast channel
//! // finishes in well under 1 ms, so waiting out the CommandTime covers both.
//! let timing = chain
//! .start_conv_cells(ADCMode::Normal, CellSelection::All, false)
//! .map_err(|_| ())?;
//! // ... host waits `timing.regular` microseconds ...
//!
//! // ---- Read each device back over its own handle ------------------------------
//! let cell_voltages = chain.read_voltages(CellSelection::All).map_err(|_| ())?;
//!
//! // CH1 high-precision current (continuously updated while CONT is set).
//! let i1 = meter.read_current1().map_err(|_| ())?; // CurrentSenseVoltage
//!
//! // The CH2 fast snapshot triggered above is read from the LTC2949's fast path; the
//! // FIFO drain (see the previous example, `read_fifo_i2`) is the supported route when
//! // running fast-continuous (FACONV = 1).
//! let _ = (cell_voltages, i1);
//! # Ok(())
//! # }
//! ```
extern crate alloc;
pub use heapless;
pub