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"

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

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:

https://e2e.ti.com/support/power-management-group/power-management/f/power-management-forum/738029/bq28z610-data-flash-access-issues/2726302#2726302

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 )