ltc681x

Module monitor

Source
Expand description

Generic client for LTX681X device family

This module contains a generic client which supports communication with any LTC681X device.

§Initialization

The client is based on a SPI bus, which implements the embedded-hal SPI Transfer trait and contains the following two generic parameters:

use ltc681x::example::ExampleSPIDevice;
use ltc681x::ltc6812::LTC6812;
use ltc681x::ltc6813::LTC6813;
use ltc681x::monitor::LTC681X;

// Single LTC6813 device
let spi_bus = ExampleSPIDevice::default();
let client: LTC681X<_, _, LTC6813, 1> = LTC681X::ltc6813(spi_bus);

// Three LTC6812 devices in daisy chain
let spi_bus = ExampleSPIDevice::default();
let client: LTC681X<_, _, LTC6812, 3> = LTC681X::ltc6812(spi_bus);

§Conversion

The following section describes starting conversion and polling mechanisms.

§Cell conversion

A cell conversion is started using the LTC681XClient::start_conv_cells method. The method takes three arguments:

  • mode: ADC frequency and filter settings, s. ADCMode
  • cells: Group of cells to be converted, e.g. LTC6813::CellSelection
  • dcp: Allow discharging during conversion?
// Converting first cell group using normal ADC mode
client.start_conv_cells(ADCMode::Normal, CellSelection::Group1, true);

// Converting all cells using fast ADC mode
client.start_conv_cells(ADCMode::Fast, CellSelection::All, true);

§Conversion time

Execution time of cell conversions is deterministic. The expected timing is returned as CommandTime.

// Converting first cell group using normal ADC mode
let timing = client.start_conv_cells(ADCMode::Normal, CellSelection::Group1, true).unwrap();

// 407 us in 7kHz mode (CFGAR0=0)
assert_eq!(407, timing.regular);

// 523 us in 3kHz mode (CFGAR0=1)
assert_eq!(523, timing.alternative);

§GPIO conversion

A GPIO conversion is started using the LTC681XClient::start_conv_gpio method. The method takes three arguments:

// Converting second GPIO group using normal ADC mode
client.start_conv_gpio(ADCMode::Normal, GPIOSelection::Group2);

// Converting all GPIOs using fast ADC mode
client.start_conv_gpio(ADCMode::Fast, GPIOSelection::All);

§Conversion time

Execution time of GPIO conversions is deterministic. The expected timing is returned as CommandTime.

// Converting second GPIO group using normal ADC mode
let timing = client.start_conv_gpio(ADCMode::Normal, GPIOSelection::Group2).unwrap();

// 788 us in 7kHz mode (CFGAR0=0)
assert_eq!(788, timing.regular);

// 1000 us in 3kHz mode (CFGAR0=1)
assert_eq!(1000, timing.alternative);

§Polling

ADC status may be be polled using the PollClient::adc_ready method. The following poll methods are currently supported:

§SDO line polling

After entering a conversion command, the SDO line is driven low when the device is busy performing conversions. SDO is pulled high when the device completes conversions.

This involves controlling the CS pin, as CS needs to stay low until the ADC conversion is finished. LatchingSpiDevice is implementing this behaviour and is used internally.

Please note that if this poll method is used, the SPI bus cannot be used by any other device until the conversion is complete.

let mut  client: LTC681X<_, _, LTC6813, 1> = LTC681X::enable_sdo_polling(spi_bus, cs_pin);

while !client.adc_ready().unwrap() {
    // ADC conversion is not finished yet
}

§Reading registers

The content of registers may be directly read. The client returns an array containing three u16, one value for each register slot.

// Single LTC613 device
let mut client: LTC681X<_, _, LTC6813, 1> = LTC681X::ltc6813(spi_bus);

// Reading cell voltage register B (CVBR)
let cell_voltages = client.read_register(Register::CellVoltageB).unwrap();
// Voltage of cell 5 (CVBR2/CVBR3)
assert_eq!(7538, cell_voltages[0][1]);

// Reading auxiliary voltage register A (AVAR)
let aux_voltages = client.read_register(Register::AuxiliaryA).unwrap();
// Voltage of GPIO1 (AVAR0/AVAR1)
assert_eq!(24979, aux_voltages[0][0]);

§Multiple devices in daisy chain

The read_register() method returns one array for each device in daisy chain. So the first array index addresses the device index. The second index addresses the slot within the register (0, 1, 2).

// Three LTC613 devices in daisy chain
let mut client: LTC681X<_, _, LTC6813, 3> = LTC681X::ltc6813(spi_bus);

// Reading cell voltage register A (CVAR)
let cell_voltages = client.read_register(Register::CellVoltageA).unwrap();
// Voltage of cell 1 of third device
assert_eq!(24979, cell_voltages[2][0]);

// Voltage of cell 3 of second device
assert_eq!(8878, cell_voltages[1][2]);

§Mapping voltages

Instead of manually reading voltage registers, the client offers a convenient method for mapping voltages to cell or GPIO groups.

// LTC6813 device
let mut client: LTC681X<_, _, LTC6813, 1> = LTC681X::ltc6813(spi_bus);

// Returns the value of cell group A. In case of LTC613: cell 1, 7 and 13
let voltages = client.read_voltages(CellSelection::Group1).unwrap();

assert_eq!(Channel::Cell1, voltages[0][0].channel);
assert_eq!(24979, voltages[0][0].voltage);

assert_eq!(Channel::Cell7, voltages[0][1].channel);
assert_eq!(25441, voltages[0][1].voltage);

assert_eq!(Channel::Cell13, voltages[0][2].channel);
assert_eq!(25822, voltages[0][2].voltage);

// Returns the value of GPIO group 2. In case of LTC613: GPIO2 and GPIO7
let voltages = client.read_voltages(GPIOSelection::Group2).unwrap();

assert_eq!(Channel::GPIO2, voltages[0][0].channel);
assert_eq!(7867, voltages[0][0].voltage);

assert_eq!(Channel::GPIO7, voltages[0][1].channel);
assert_eq!(7869, voltages[0][1].voltage);

§Self-tests

The LTC681X family supports a number of verification and fault-tests.

§Overlap measurement (ADOL command)

Starting the ADC overlapping measurement and reading the results:

client.start_overlap_measurement(ADCMode::Normal, true);
// [...] waiting until conversion finished
let data = client.read_overlap_result().unwrap();

// Voltage of cell 7 measured by ADC2
assert_eq!(25441, data[0][0]);
// Voltage of cell 7 measured by ADC1
assert_eq!(7869, data[0][1]);
// Voltage of cell 13 measured by ADC3
assert_eq!(25822, data[0][2]);
// Voltage of cell 13 measured by ADC2
assert_eq!(8591, data[0][3]);

§Internal device parameters (ADSTAT command)

Measuring internal device parameters and reading the results.

The expected execution time is returned as CommandTime, see command timing of cell conversion as example.

client.measure_internal_parameters(ADCMode::Normal, StatusGroup::All);
// [...] waiting until conversion finished
let data = client.read_internal_device_parameters().unwrap();

// Sum of all voltages in uV => 75.318 V
assert_eq!(75_318_000, data[0].total_voltage);
// Die temperature in °C
assert_eq!("56.31578", data[0].temperature.to_string());
// Analog power supply voltage in uV => 3.2 V
assert_eq!(3_200_000, data[0].analog_power);
// Digital power supply voltage in uV => 5.12 V
assert_eq!(5_120_000, data[0].digital_power);

Structs§

CommandTime
Expected execution time of the issued command
InternalDeviceParameters
Collection of internal device parameters, measured by ADSTAT command
LTC681X
Client for LTC681X IC
NoPolling
No ADC polling is used
NoWriteCommandError
Error in case writing to this register ist not supported and therefore no command exists.
RegisterAddress
Location of a conversion voltage
SDOLinePolling
Leaves CS Low and waits until SDO goes high
Voltage
Conversion result of a single channel

Enums§

ADCMode
ADC frequency and filtering settings
ChannelType
ADC channel type
Error
Error enum of LTC681X
StatusGroup
Selection of status group

Traits§

ChannelIndex
Converts channels (cells or GPIOs) to indexes
DeviceTypes
Device specific types
GroupedRegisterIndex
Converts registers to indexes
LTC681XClient
Public LTC681X client interface
PollClient
Public LTC681X interface for polling ADC status
PollMethod
Poll Strategy
RegisterLocator
Maps register locations to cell or GPIO groups
ToCommandBitmap
Trait for casting command options to command bitmaps
ToCommandTiming
Trait for determining the estimated execution time
ToFullCommand
Trait for casting to constant (precomputed) commands