Expand description
§Driver for the LTC2949 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 understandDCMD, 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”). BCRENis 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
CommandTimeon the cell-monitor client — so hosts with cooperative schedulers own the waiting themselves (noDelayNsseam). - Slow-mode result registers (
I1,I2,P1,P2,BAT,TEMP,VCC,SLOT1/2). - Accumulators (charge
C1..C3, energyE1/E2/E4, timeTB1..TB4), plus the memory-lock handshake for coherent multi-register snapshots. - Decoded status/fault registers (
STATUS,FAULTS,EXTFAULTS). - Fast mode trigger (
FACTRL, broadcastADCV) and FIFO drain. - Steinhart–Hart linearisation coefficients for the two NTC channels
(
client::Client::write_ntc_coefficients), including thef32 → Float24encoding.
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;
// 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);
}
}§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 is shared between two
embedded_hal::spi::SpiDevice handles — one driving the
client::Client, the other driving the LTC681X client 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.
// 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);Re-exports§
pub use heapless;