BQ28Z610 Driver
BQ28Z610 Battery fuel gauge device driver for Arduino
Data Structures | Functions
data_flash_access.h File Reference

12.2.45 Data Flash Access() 0x4000–0x5FFF headers More...

#include <Arduino.h>
#include "globals.h"
#include "utils.h"
#include "alt_manufacturer_access.h"
#include "service.h"

Go to the source code of this file.

Data Structures

class  DF_ADDR
 Data Flash addresses. More...
 

Functions

void dfReadBytes (word addr, byte *retval, int len)
 Read array of bytes from the Data Flash by address. More...
 
void dfWriteBytes (word addr, byte *data, int len)
 Write array of data to the Data Flash. More...
 
byte dfReadByte (word addr)
 
byte dfReadU1 (word addr)
 
void dfWriteByte (word addr, byte value)
 
word dfReadWord (word addr)
 Read a word value (two bytes) from the Data Flash by address. More...
 
void dfWriteWord (word addr, word value)
 Write a word value (two bytes) to the Data Flash by address. More...
 
int dfReadI2 (word addr)
 Read Two-byte Integer value from the Data Flash by address. More...
 
void dfWriteI2 (word addr, int value)
 Write int value to the Data Flash by address. More...
 
word dfReadU2 (word addr)
 Read Two-byte unsigned integer value from the Data Flash by address. More...
 
void dfWriteU2 (word addr, word value)
 Write unsigned int value to the Data Flash by address. More...
 
String dfReadString (word addr)
 Read String value from the Data Flash by address. More...
 
String dfDeviceName ()
 Read the Device Name from the Data Flash. More...
 
int dfReadDesignCapacityMah ()
 Read the Design Capacity in mAh from the Data Flash. More...
 
void dfWriteDesignCapacityMah (int designCapacityMah)
 Write Design Capacity in mAh to the Data Flash. More...
 
int dfReadDesignCapacityCwh ()
 Read the Design Energy in cWh from the Data Flash. More...
 
void dfWriteDesignCapacityCwh (int designCapacityCwh)
 Write Design Energy in cWh to the Data Flash. More...
 
byte dfReadFetOptions ()
 Settings; Configuration; 0x4600; FET Options; H1. More...
 
void dfWriteFetOptionsCHGFET (bool chgFetBitValue)
 Settings; Configuration; FET Options; H1. More...
 
byte dfReadDaConfiguration ()
 Settings; Configuration; 0x469B; DA Configuration; H1. More...
 
byte dfReadGasGaugingUpdateStatus ()
 Gas Gauging; Update Status; 0x420E; H1. More...
 
void dfWriteGasGaugingUpdateStatus (byte updateStatus)
 Gas Gauging; Update Status; 0x420E; H1. More...
 
void dfReadAllData ()
 Read and print all data from the Data Flash. More...
 
void dfPrintRaTable ()
 Print data from R_a table. More...
 
int dfReadTaperCurrent ()
 Advanced Charge Algorithm; Termination Config; 0x4693; Charge Term Taper Current; I2. More...
 
void dfWriteTaperCurrent (int taperCurrent)
 Advanced Charge Algorithm; Termination Config; 0x4693; Charge Term Taper Current; I2. More...
 
void dfResetRaTableFlags ()
 Reset "R_a flags" in the Data Flash to the Default values: More...
 
word dfReadSocFlagConfigA ()
 Settings; Configuration; 0x4632; SOC Flag Config A; H2. More...
 
void dfWriteSocFlagConfigA (word socFlagConfigA)
 Settings; Configuration; 0x4632; SOC Flag Config A; H2. More...
 
byte dfReadTcSetRsocThreshold ()
 Gas Gauging; TC; 0x464B; Set % RSOC Threshold. More...
 
void dfWriteTcSetRsocThreshold (byte setThreshold)
 Gas Gauging; TC; 0x464B; Set % RSOC Threshold. More...
 
byte dfReadTcClearRsocThreshold ()
 Gas Gauging; TC; 0x464C; Clear % RSOC Threshold. More...
 
void dfWriteTcClearRsocThreshold (byte clearThreshold)
 Gas Gauging; TC; 0x464C; Clear % RSOC Threshold. More...
 
int dfReadQmaxCell1 ()
 Gas Gauging; State; 0x4206; Qmax Cell 1; I2. More...
 
int dfReadQmaxCell2 ()
 Gas Gauging; State; 0x4208; Qmax Cell 2; I2. More...
 
int dfReadQmaxPack ()
 Gas Gauging; State; 0x420A; Qmax Pack; I2. More...
 
void dfWriteQmax (word qMaxCell0, word qMaxCell1)
 Qmax Pack = min(Qmax Cell 1, Qmax Cell 2) More...
 
word dfReadCycleCount ()
 Gas Gauging; State; 0x4240; Cycle Count; U2. More...
 
void dfWriteCycleCount (word cycleCount)
 Gas Gauging; State; 0x4240; Cycle Count; U2. More...
 

Detailed Description

12.2.45 Data Flash Access() 0x4000–0x5FFF headers

Accessing data flash (DF) is only supported by the AltManufacturerAccess() by addressing the physical address.

Warning
[!] Not Available in SEALED Mode. UNSEALED Mode is enough for both: reading and writing. If you try to read the DF in SEALED mode, you'll just get an array of zeros.
BQ28Z610
Technical Reference Manual
(c) Texas Instruments
Literature Number: SLUUA65E
See also
https://www.ti.com/lit/ug/sluua65e/sluua65e.pdf
13 Data Flash Values
14 Data Flash Summary

MIT License

Copyright (c) 2024 Oleksii Sylichenko

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Function Documentation

◆ dfDeviceName()

String dfDeviceName ( )

Read the Device Name from the Data Flash.

I2C Configuration; Data; 0x4080; Device Name; S21

See also
DF_ADDR::DEVICE_NAME

◆ dfPrintRaTable()

void dfPrintRaTable ( )

Print data from R_a table.

Cell 0, Cell 1, xCell 0, xCell 1:

  • R_a flag
  • 15 rows
See also
DF_ADDR::CELL0_RA_FLAG
DF_ADDR::CELL1_RA_FLAG
DF_ADDR::X_CELL0_RA_FLAG
DF_ADDR::X_CELL1_RA_FLAG

◆ dfReadAllData()

void dfReadAllData ( )

Read and print all data from the Data Flash.

See also
DF_ADDR::MIN
DF_ADDR::MAX
BlockProtocol::PAYLOAD_MAX_SIZE

◆ dfReadByte()

byte dfReadByte ( word  addr)
See also
dfReadBytes()

◆ dfReadBytes()

void dfReadBytes ( word  addr,
byte *  retval,
int  len 
)

Read array of bytes from the Data Flash by address.

Address should be fit into Data Flash addresses region, otherwise error message will be printed.

Requested length should be in the range [1; 32]

See also
AltManufacturerAccess()
DF_ADDR::MIN
DF_ADDR::MAX
BlockProtocol

◆ dfReadCycleCount()

word dfReadCycleCount ( )

Gas Gauging; State; 0x4240; Cycle Count; U2.

See also
DF_ADDR::GAS_GAUGING_CYCLE_COUNT

◆ dfReadDaConfiguration()

byte dfReadDaConfiguration ( )

Settings; Configuration; 0x469B; DA Configuration; H1.

Bit 0: CC0—Cell Count
  0 = 1 cell
  1 = 2 cell
Bit 1: Reserved
Bit 2: Reserved
Bit 3: IN_SYSTEM_SLEEP—In-system SLEEP mode
  0 = Disables (default)
  1 = Enables
Bit 4: SLEEP—SLEEP Mode
  0 = Disables SLEEP mode
  1 = Enables SLEEP mode (default)
Bit 5: Reserved
Bit 6: CTEMP—Cell Temperature protection source
  0 = MAX (default)
  1 = Average
Bit 7: Reserved
See also
DF_ADDR::DA_CONFIGURATION
DaConfigurationFlags

◆ dfReadDesignCapacityCwh()

int dfReadDesignCapacityCwh ( )

Read the Design Energy in cWh from the Data Flash.

Gas Gauging; Design; 0x462C; Design Capacity cWh; I2

Is used for LOAD mode = Constant Power.

See also
DF_ADDR::DESIGN_CAPACITY_CWH

◆ dfReadDesignCapacityMah()

int dfReadDesignCapacityMah ( )

Read the Design Capacity in mAh from the Data Flash.

Gas Gauging; Design; 0x462A; Design Capacity mAh; I2

Is used for LOAD mode = Constant Current.

See also
DF_ADDR::DESIGN_CAPACITY_MAH

◆ dfReadFetOptions()

byte dfReadFetOptions ( )

Settings; Configuration; 0x4600; FET Options; H1.

Bit 0: Reserved
Bit 1: Reserved
Bit 2: OTFET—FET action in OVERTEMPERATURE mode
  0 = No FET action for overtemperature condition
  1 = CHG and DSG FETs will be turned off for overtemperature conditions.
Bit 3: CHGSU—FET action in CHARGE SUSPEND mode
  0 = FET active
  1 = Charging or precharging disabled, FET off
Bit 4: CHGIN—FET action in CHARGE INHIBIT mode
  0 = FET active
  1 = Charging or precharging disabled, FET off
Bit 5: CHGFET—FET action on valid charge termination
  0 = FET active
  1 = Charging or precharging disabled, FET off
Bit 6: SLEEPCHG—CHG FET enabled during sleep
  0 = CHG FET off during sleep
  1 = CHG FET remains on during sleep.
Bit 7: Reserved
See also
DF_ADDR::FET_OPTIONS
FetOptionsFlags

◆ dfReadGasGaugingUpdateStatus()

byte dfReadGasGaugingUpdateStatus ( )

Gas Gauging; Update Status; 0x420E; H1.

Bit 1:0: Update1, Update0 - Update Status:
  0,0 = Impedance Track gauging and lifetime updating is disabled.
  0,1 = QMax updated
  1,0 = QMax and Ra table have been updated
Bit 2: Impedance Track gauging and lifetime updating:
  0 = Disabled
  1 = Enabled
Bit 3: QMax update:
  0 = Not updated
  1 = Updated
Bit 7:4: Reserved
Warning
[!] If any Reserved bit is set then check whether security mode is Unsealed, otherwise Unseal the Device.
  • 0x00 = 0000 - Impedance Track gauging and lifetime updating is disabled.
  • 0x01 = 0001
  • 0x02 = 0010
  • 0x04 = 0100 - Neither QMax nor Ra table are updated. Learning is in progress.
  • 0x05 = 0101 - QMax is updated.
  • 0x06 = 0110 - QMax and Ra table are updated.
  • 0x0E = 1110 - QMax is updated in field (in real conditions).
See also
DF_ADDR::GAS_GAUGING_UPDATE_STATUS
GasGaugingUpdateStatusFlags

◆ dfReadI2()

int dfReadI2 ( word  addr)

Read Two-byte Integer value from the Data Flash by address.

See also
dfReadWord()

◆ dfReadQmaxCell1()

int dfReadQmaxCell1 ( )

Gas Gauging; State; 0x4206; Qmax Cell 1; I2.

See also
DF_ADDR::Q_MAX_CELL_1

◆ dfReadQmaxCell2()

int dfReadQmaxCell2 ( )

Gas Gauging; State; 0x4208; Qmax Cell 2; I2.

See also
DF_ADDR::Q_MAX_CELL_2

◆ dfReadQmaxPack()

int dfReadQmaxPack ( )

Gas Gauging; State; 0x420A; Qmax Pack; I2.

See also
DF_ADDR::Q_MAX_PACK

◆ dfReadSocFlagConfigA()

word dfReadSocFlagConfigA ( )

Settings; Configuration; 0x4632; SOC Flag Config A; H2.

Bit 0: TDSETV—Enables the TD flag set by the cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 1: TDCLEARV—Enables the TD flag clear by cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 2: TDSETRSOC—Enables the TD flag set by RSOC threshold
  0 = Disabled
  1 = Enabled (default)
Bit 3: TDCLEARRSOC—Enables the TD flag cleared by the RSOC threshold
  0 = Disabled
  1 = Enabled (default)
Bit 4: TCSETV—Enables the TC flag set by cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 5: TCCLEARV—Enables the TC flag clear by cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 6: TCSETRSOC—Enables the TC flag set by the RSOC threshold
  0 = Disabled (default)
  1 = Enabled
Bit 7: TCCLEARRSOC—Enables the TC flag cleared by the RSOC threshold
  0 = Disabled
  1 = Enabled (default)
Bit 8: Reserved
Bit 9: Reserved
Bit 10: FCSETVCT—Enables the FC flag set by primary charge termination
  0 = Disabled
  1 = Enabled (default)
Bit 11: TCSETVCT—Enables the TC flag set by primary charge termination
  0 = Disabled
  1 = Enabled (default)
Bit 15: 12: Reserved
Returns
  • Default: 0x0C8C;
  • JBL: 0001 0011 1000 0011;
See also
DF_ADDR::SOC_FLAG_CONFIG_A
SOCFlagConfigAFlags

◆ dfReadString()

String dfReadString ( word  addr)

Read String value from the Data Flash by address.

See also
AltManufacturerAccess()

◆ dfReadTaperCurrent()

int dfReadTaperCurrent ( )

Advanced Charge Algorithm; Termination Config; 0x4693; Charge Term Taper Current; I2.

See also
DF_ADDR::CHARGE_TERM_TAPER_CURRENT

◆ dfReadTcClearRsocThreshold()

byte dfReadTcClearRsocThreshold ( )

Gas Gauging; TC; 0x464C; Clear % RSOC Threshold.

See also
DF_ADDR::TC_CLEAR_RSOC_THRESHOLD

◆ dfReadTcSetRsocThreshold()

byte dfReadTcSetRsocThreshold ( )

Gas Gauging; TC; 0x464B; Set % RSOC Threshold.

See also
DF_ADDR::TC_SET_RSOC_THRESHOLD

◆ dfReadU1()

byte dfReadU1 ( word  addr)
See also
dfReadByte()

◆ dfReadU2()

word dfReadU2 ( word  addr)

Read Two-byte unsigned integer value from the Data Flash by address.

See also
dfReadWord()

◆ dfReadWord()

word dfReadWord ( word  addr)

Read a word value (two bytes) from the Data Flash by address.

Result is in the Normal Order.

Parameters
addr- two-byte address
Returns
two byte in normal order: 0x4321
See also
dfReadBytes()
composeWord()

◆ dfResetRaTableFlags()

void dfResetRaTableFlags ( )

Reset "R_a flags" in the Data Flash to the Default values:

  • Cell0 R_a flag: addr = 0x4100, data = 0xFF55 - Cell impedance never updated; Table being used;
  • Cell1 R_a flag: addr = 0x4140, data = 0xFF55 - Cell impedance never updated; Table being used;
  • xCell0 R_a flag: addr = 0x4180, data = 0xFFFF - Cell impedance never updated; Table never used;
  • xCell0 R_a flag: addr = 0x41C0, data = 0xFFFF - Cell impedance never updated; Table never used;
See also
DF_ADDR::CELL0_RA_FLAG
DF_ADDR::CELL1_RA_FLAG
DF_ADDR::X_CELL0_RA_FLAG
DF_ADDR::X_CELL1_RA_FLAG

◆ dfWriteByte()

void dfWriteByte ( word  addr,
byte  value 
)
See also
dfWriteBytes()

◆ dfWriteBytes()

void dfWriteBytes ( word  addr,
byte *  data,
int  len 
)

Write array of data to the Data Flash.

The byte order should be as it should be written in the data flash.

The Data length should be in the range [1; 32]

Some addresses within the standard region are prohibited from writing, I am not sure about the exact ranges of such addresses.

For example, around the address 0x5A5A, there are data 0xFF and they cannot be overwritten.

Special thanks for providing the accurate definition of the DF writing algorithm to the user "silomilo" from the Texas Intruments forum:

Write to 0x3E ( AltManufacturingAccess) the MAC address (little endian) followed by the data to write ( Note: Minimum data is 1 and maximum is 32 )

Write to 0x60 ( MacDataChecksum ) the checksum calculated as per below

Write to 0x61 ( MacDataLength ) the total number of bytes written including the MAC address, data bytes, checksum, and MACDataLength itself

Read back from MAC address to verify (Write address to read to 0x3E and read back desired number of bytes)

Parameters
addr- Address of the Data Flash to write data.
data- Array of data bytes.
len- Length of the data.
See also
StdCommands::ALT_MANUFACTURER_ACCESS
StdCommands::MAC_DATA_CHECKSUM

◆ dfWriteCycleCount()

void dfWriteCycleCount ( word  cycleCount)

Gas Gauging; State; 0x4240; Cycle Count; U2.

See also
DF_ADDR::GAS_GAUGING_CYCLE_COUNT

◆ dfWriteDesignCapacityCwh()

void dfWriteDesignCapacityCwh ( int  designCapacityCwh)

Write Design Energy in cWh to the Data Flash.

Gas Gauging; Design; 0x462C; Design Capacity cWh; I2

  • JBL: 3672

Design Energy = Nominal Voltage * Capacity 7.2 V * 5100 mAh = 36'720 mWh = 3672 cWh

See also
DF_ADDR::DESIGN_CAPACITY_CWH

◆ dfWriteDesignCapacityMah()

void dfWriteDesignCapacityMah ( int  designCapacityMah)

Write Design Capacity in mAh to the Data Flash.

Gas Gauging; Design; 0x462A; Design Capacity mAh; I2

  • JBL: 5100
See also
DF_ADDR::DESIGN_CAPACITY_MAH

◆ dfWriteFetOptionsCHGFET()

void dfWriteFetOptionsCHGFET ( bool  chgFetBitValue)

Settings; Configuration; FET Options; H1.

Bit 5: CHGFET - FET action on valid charge termination

  • 0 = FET active
  • 1 = Charging or precharging disabled, FET off
See also
DF_ADDR::FET_OPTIONS
FetOptionsFlags::CHGFET()

◆ dfWriteGasGaugingUpdateStatus()

void dfWriteGasGaugingUpdateStatus ( byte  updateStatus)

Gas Gauging; Update Status; 0x420E; H1.

Bit 1:0: Update1, Update0 - Update Status:
  0,0 = Impedance Track gauging and lifetime updating is disabled.
  0,1 = QMax updated
  1,0 = QMax and Ra table have been updated
Bit 2: Impedance Track gauging and lifetime updating:
  0 = Disabled
  1 = Enabled
Bit 3: QMax update:
  0 = Not updated
  1 = Updated
Bit 7:4: Reserved
Warning
[!] If any Reserved bit is set then check whether security mode is Unsealed, otherwise Unseal the Device.
  • 0x00 = 0000 - Impedance Track gauging and lifetime updating is disabled.
  • 0x01 = 0001
  • 0x02 = 0010
  • 0x04 = 0100 - Neither QMax nor Ra table are updated. Learning is in progress.
  • 0x05 = 0101 - QMax is updated.
  • 0x06 = 0110 - QMax and Ra table are updated.
  • 0x0E = 1110 - QMax is updated in field (in real conditions).
See also
DF_ADDR::GAS_GAUGING_UPDATE_STATUS

◆ dfWriteI2()

void dfWriteI2 ( word  addr,
int  value 
)

Write int value to the Data Flash by address.

See also
dfWriteWord()

◆ dfWriteQmax()

void dfWriteQmax ( word  qMaxCell1,
word  qMaxCell2 
)

Qmax Pack = min(Qmax Cell 1, Qmax Cell 2)

  • Gas Gauging; State; 0x4206; Qmax Cell 1; I2
  • Gas Gauging; State; 0x4208; Qmax Cell 2; I2
  • Gas Gauging; State; 0x420A; Qmax Pack; I2
See also
DF_ADDR::Q_MAX_CELL_1
DF_ADDR::Q_MAX_CELL_2
DF_ADDR::Q_MAX_PACK

◆ dfWriteSocFlagConfigA()

void dfWriteSocFlagConfigA ( word  socFlagConfigA)

Settings; Configuration; 0x4632; SOC Flag Config A; H2.

Bit 0: TDSETV—Enables the TD flag set by the cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 1: TDCLEARV—Enables the TD flag clear by cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 2: TDSETRSOC—Enables the TD flag set by RSOC threshold
  0 = Disabled
  1 = Enabled (default)
Bit 3: TDCLEARRSOC—Enables the TD flag cleared by the RSOC threshold
  0 = Disabled
  1 = Enabled (default)
Bit 4: TCSETV—Enables the TC flag set by cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 5: TCCLEARV—Enables the TC flag clear by cell voltage threshold
  0 = Disabled (default)
  1 = Enabled
Bit 6: TCSETRSOC—Enables the TC flag set by the RSOC threshold
  0 = Disabled (default)
  1 = Enabled
Bit 7: TCCLEARRSOC—Enables the TC flag cleared by the RSOC threshold
  0 = Disabled
  1 = Enabled (default)
Bit 8: Reserved
Bit 9: Reserved
Bit 10: FCSETVCT—Enables the FC flag set by primary charge termination
  0 = Disabled
  1 = Enabled (default)
Bit 11: TCSETVCT—Enables the TC flag set by primary charge termination
  0 = Disabled
  1 = Enabled (default)
Bit 15: 12: Reserved
Returns
  • Default: 0x0C8C;
  • JBL: 0001 0011 1000 0011;
See also
DF_ADDR::SOC_FLAG_CONFIG_A

◆ dfWriteTaperCurrent()

void dfWriteTaperCurrent ( int  taperCurrent)

Advanced Charge Algorithm; Termination Config; 0x4693; Charge Term Taper Current; I2.

See also
DF_ADDR::CHARGE_TERM_TAPER_CURRENT

◆ dfWriteTcClearRsocThreshold()

void dfWriteTcClearRsocThreshold ( byte  clearThreshold)

Gas Gauging; TC; 0x464C; Clear % RSOC Threshold.

See also
DF_ADDR::TC_CLEAR_RSOC_THRESHOLD

◆ dfWriteTcSetRsocThreshold()

void dfWriteTcSetRsocThreshold ( byte  setThreshold)

Gas Gauging; TC; 0x464B; Set % RSOC Threshold.

See also
DF_ADDR::TC_SET_RSOC_THRESHOLD

◆ dfWriteU2()

void dfWriteU2 ( word  addr,
word  value 
)

Write unsigned int value to the Data Flash by address.

See also
dfWriteWord()

◆ dfWriteWord()

void dfWriteWord ( word  addr,
word  value 
)

Write a word value (two bytes) to the Data Flash by address.

Order of bytes should be Normal.

See also
dfWriteBytes()