DC2100A  1.2.0
Bi-Directional Cell Balancer Using the LTC3300-1 and the LTC6804-2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Balancer.h
Go to the documentation of this file.
1 /*
2  Linear Technology DC2100A Demonstration Board.
3  Reference Application File for Controlling the LTC3300-1 Battery Balancers through the LTC6804-2 Battery Monitor on the DC2100A PCB.
4 
5  @verbatim
6  This file contains a task to control the balancers in the DC2100A System with a resolution set by BALANCER_TASK_RATE, as well as functions
7  to control and monitor the balancer task.
8  @endverbatim
9 
10  http://www.linear.com/solutions/5126
11 
12  REVISION HISTORY
13  $Revision: 687 $
14  $Date: 2014-09-05 14:51:22 -0400 (Fri, 05 Sep 2014) $
15 
16  Copyright (c) 2013, Linear Technology Corp.(LTC)
17  All rights reserved.
18 
19  Redistribution and use in source and binary forms, with or without
20  modification, are permitted provided that the following conditions are met:
21 
22  1. Redistributions of source code must retain the above copyright notice, this
23  list of conditions and the following disclaimer.
24  2. Redistributions in binary form must reproduce the above copyright notice,
25  this list of conditions and the following disclaimer in the documentation
26  and/or other materials provided with the distribution.
27 
28  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
29  ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
30  WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
31  DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
32  ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
33  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
34  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
35  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
36  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
37  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
38 
39  The views and conclusions contained in the software and documentation are those
40  of the authors and should not be interpreted as representing official policies,
41  either expressed or implied, of Linear Technology Corp.
42 
43 */
44 
45 /*! @file
46  @ingroup Balancer
47  Reference Application File for Controlling the LTC3300-1 Battery Balancers through the LTC6804-2 Battery Monitor on the DC2100A PCB.
48 */
49 
50 #ifndef __BALANCER_H__
51 #define __BALANCER_H__
52 
53 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
54 // Includes
55 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
56 #include "Typedefs.h"
57 
58 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
59 // Definitions
60 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
61 
62 //! @name Balancer Control Module Constants
63 //! @{
64 #define BALANCER_TASK_RATE 250 //!< in ms, the rate at which the balancer control task is executed.
65 //! @}
66 
67 //! @name Balancer Control States
68 //! @{
69 //! The Balancer Control Task can operate in one of the following states.
70 typedef enum
71 {
72  BALANCER_CONTROL_OFF, //!< Balancing is not active. ICs are allowed to go to sleep.
73  BALANCER_CONTROL_GUI, //!< Watchdog is being activated to prevent LTC3300s from going to sleep, but raw commands are being sent to ICs from the GUI.
74  BALANCER_CONTROL_SETUP, //!< Balancing commands are being loaded. ICs are prevented from going to sleep.
75  BALANCER_CONTROL_ON, //!< Balancing commands are being executed for a timed value for each cell. ICs are prevented from going to sleep. State automatically transitions to OFF when balancing is complete.
76  BALANCER_CONTROL_SUSPEND //!< Balancing commands are suspended. ICs are prevented from going to sleep.
78 //! @}
79 
80 //! @name Balancer Active State Structures
81 //! @{
82 //! This C structure contains the active balance command to be executed by the Balancer task in the BALANCER_CONTROL_ON state.
83 //! Note that CCS gives the error "Number of bits is out of range" with the structure defined, so definitions are used to define
84 //! the BALANCER_ACTIVE_STATE_TYPE packed structure manually.
85 //! @verbatim
86 //! typedef struct{
87 //! int16 time : 15; // time to balance with BALANCER_TASK_RATE resolution.
88 //! int16 command : 1; // 0 for charge, 1 for discharge
89 //! } BALANCER_ACTIVE_STATE_TYPE;
90 //! @endverbatim
91 typedef int16 BALANCER_ACTIVE_STATE_TYPE; //!< Size of structure used for balancer active state.
92 #define BALANCER_ACTIVE_STATE_COMMAND_BITS 1 //!< Size of bit field used to indicate charge and discharge
93 #define BALANCER_ACTIVE_STATE_COMMAND_SHIFT 15 //!< Position of bit field used to indicate charge and discharge
94 #define BALANCER_ACTIVE_STATE_COMMAND_MASK MASK(BALANCER_ACTIVE_STATE_COMMAND_BITS, BALANCER_ACTIVE_STATE_COMMAND_SHIFT) //!< Mask for bit field used to indicate charge and discharge
95 #define BALANCER_ACTIVE_STATE_TIME_BITS 15 //!< Size of bit field used to hold time to balance
96 #define BALANCER_ACTIVE_STATE_TIME_SHIFT 0 //!< Position of bit field used to hold time to balance
97 #define BALANCER_ACTIVE_STATE_TIME_MASK MASK(BALANCER_ACTIVE_STATE_TIME_BITS, BALANCER_ACTIVE_STATE_TIME_SHIFT) //!< Mask for bit field used to hold time to balance
98 #define BALANCER_ACTIVE_STATE_CHARGE 0 //!< 0 for charge
99 #define BALANCER_ACTIVE_STATE_DISCHARGE 1 //!< 1 for discharge
100 #define BALANCER_ACTIVE_STATE_COMMAND_SET(command, time) ((command << BALANCER_ACTIVE_STATE_COMMAND_SHIFT) + (time << BALANCER_ACTIVE_STATE_TIME_SHIFT)) //!< Macro to set active balancer command.
101 //! @}
102 
103 //! @name Balancer Passive State Structure
104 //! @{
105 typedef int16 BALANCER_PASSIVE_STATE_TYPE; //!< Bitmap for LTC6804_NUM_CELLV_ADC passive balancers on one DC2100A, 1 = ON and 0 = Off, bit 0 = cell 0
106 //! @}
107 
108 //! @name Balancer Passive State Structure
109 //! @{
110 typedef signed int32 BALANCER_DELTA_Q_TYPE; //!< Data Type for amount of charge to move from a cell in mAs.
111 //! @}
112 
113 //! @name Balancer Current Constants
114 //! @{
115 //! Nominal balance currents for DC2100A models, which can be A, B, C, or D.
116 //! Note that calibrated balance currents use a scaled version of nominal to reduce RAM usage.
117 #define BALANCER_AB_CURRENT_CHARGE_12CELL 2600 //!< in mA, nominal charge balance current for cells with 12 cell secondary connections on a DC2100A-A or DC2100A-B
118 #define BALANCER_AB_CURRENT_DISCHARGE_12CELL 2400 //!< in mA, nominal discharge balance current for cells with 12 cell secondary connections on a DC2100A-A or DC2100A-B
119 #define BALANCER_AB_CURRENT_CHARGE_6CELL 2200 //!< in mA, nominal charge balance current for cells with 6 cell secondary connections on a DC2100A-A or DC2100A-B
120 #define BALANCER_AB_CURRENT_DISCHARGE_6CELL 2400 //!< in mA, nominal discharge balance current for cells with 6 cell secondary connections on a DC2100A-A or DC2100A-B
121 #define BALANCER_CD_CURRENT_CHARGE_12CELL 4000 //!< in mA, nominal charge balance current for cells with 12 cell secondary connections on a DC2100A-C or DC2100A-D
122 #define BALANCER_CD_CURRENT_DISCHARGE_12CELL 4300 //!< in mA, nominal discharge balance current for cells with 12 cell secondary connections on a DC2100A-C or DC2100A-D
123 #define BALANCER_CD_CURRENT_CHARGE_6CELL 3400 //!< in mA, nominal charge balance current for cells with 6 cell secondary connections on a DC2100A-C or DC2100A-D
124 #define BALANCER_CD_CURRENT_DISCHARGE_6CELL 4000 //!< in mA, nominal discharge balance current for cells with 6 cell secondary connections on a DC2100A-C or DC2100A-D
125 #define BALANCER_CURRENT_SCALE_FACTOR (1L << BALANCER_CURRENT_SCALE_FACTOR_SHIFT) //!< scale that calibration values are divided by to get a % of the nominal current value.
126 #define BALANCER_CURRENT_SCALE_FACTOR_SHIFT 8 //!< number of bits to shift for equivalant of division by BALANCER_CURRENT_SCALE_FACTOR
127 #define BALANCER_CURRENT_SCALE_CALC(desired_current, base_current) ((BALANCER_CURRENT_SCALE_FACTOR*(desired_current - base_current) + base_current/2) / base_current) //!< calculation of calibration current values
128 //! @}
129 
130 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
131 // Global Data
132 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
133 //! @name Active Cell Balancer State Variables
134 //! @{
135 extern BALANCER_ACTIVE_STATE_TYPE Balancer_Active_State[DC2100A_MAX_BOARDS][DC2100A_NUM_CELLS]; //!< The state of each active cell balancer on each DC2100A in the system.
136 extern BALANCER_ACTIVE_STATE_TYPE Balancer_Active_Time_Max; //!< The longest active balance time in the DC2100A system.
137 extern BALANCER_ACTIVE_STATE_TYPE Balancer_Active_Time_Next_Stop; //!< The shortest, yet non-zero, active balance time in the DC2100A system.
138 extern int8 Balancer_Active_Board_Max; //!< The board with the longest remaining balance time
139 extern int8 Balancer_Active_Board_Next_Stop; //!< The cell with the shortest, yet non-zero, remaining balance time
140 //! @}
141 
142 //! @name Passive Cell Balancer States
143 //! @{
144 extern BALANCER_PASSIVE_STATE_TYPE Balancer_Passive_State[DC2100A_MAX_BOARDS]; //!< Bitmap for LTC6804_NUM_CELLV_ADC passive balancers on one DC2100A, 1 = ON and 0 = Off, bit 0 = cell 0
145 //! @}
146 
147 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
148 // Global Prototypes
149 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
150 
151 //! Initializes the parts of the Balancer Module, that need to be initialized upon power-up of the PIC.
152 //! @return void
153 void Balancer_Init(void);
154 
155 //! Initializes the parts of the Balancer Module, that need to be initialized upon wakeup of the LTC3300-1.
156 //! @return TRUE if initialization was successful.
157 BOOLEAN Balancer_Wakeup_Init(void);
158 
159 //! Executes the Balancer Control task.
160 //! - Sends watchdog commands to the LTC3300-1 ICs to keep them awake, unless in a state which allows the LTC3300-1 ICs to sleep.
161 //! - If in the BALANCER_CONTROL_ON state, each active cell balancer command has its timer decremented while sending the appropriate commands
162 //! to the LTC3300-1 ICs. The max and min (yet non-zero) balance times are tracked in this state.
163 //! - Turns on/off the passive balancers.
164 //! @return void
165 void Balancer_Control_Task(void);
166 
167 //! Places Balancer Control Task in the BALANCER_CONTROL_SETUP state.
168 //! Does not change the active cell balancer states.
169 //! @return void
170 void Balancer_Set(void);
171 
172 // Places Balancer Control Task in the BALANCER_CONTROL_SETUP state.
173 // Loads the desired active cell balancer states for DC2100A_NUM_CELLS cells on one board.
174 // return void
175 void Balancer_Set(
176  int8 board_num, // The logical address for the PCB containing this Balancer.
177  BALANCER_ACTIVE_STATE_TYPE* cell_state_ptr // Pointer to the desired active cell balancer states for DC2100A_NUM_CELLS cells.
178 );
179 
180 //! Places Balancer Control Task in the BALANCER_CONTROL_SETUP state.
181 // Calculates and loads the optimal active cell balancer states to achieve the desired amount of charge to move for each cell.
182 // See "CapDemo Balancing Algorithm" worksheet in DC2100A_Design.xlsm for a model of this function.
183 // Note - this function is currently only implemented for a single DC2100A board.
184 // return void
185 void Balancer_Set(
186  BALANCER_DELTA_Q_TYPE* charge_target_ptr // Pointer to the desired charge to move in for DC2100A_NUM_CELLS cells in mAs.
187 );
188 
189 //! Places Balancer Control Task in the BALANCER_CONTROL_ON state. Note that balancing is not started until the next state execution,
190 //! to ensure that the balance times are accurately controlled to the BALANCER_TASK_RATE resolution.
191 //! @return void
192 void Balancer_Start(void);
193 
194 //! Places Balancer Control Task in the BALANCER_CONTROL_OFF state immediately, as it's possible there's a catastrophic reason why we
195 //! need to suspend,and resets the Balancer Control Task.
196 //! @return void
197 void Balancer_Stop(void);
198 
199 //! Places Balancer Control Task in the BALANCER_CONTROL_SUSPEND state immediately as it's possible there's a catastrophic reason why we
200 //! need to suspend.
201 //! @return void
202 void Balancer_Suspend(void);
203 
204 //! Places Balancer Control Task in the BALANCER_CONTROL_GUI state, stopping all control of balancers by Balancer Control Task,
205 //! and allows full control of LTC3300 ICs through direct commands from GUI.
206 //! @return void
207 void Balancer_GUI(void);
208 
209 //! Returns if any balancer is actively balancing.
210 //! @return TRUE if any balancer is actively balancing.
211 BOOLEAN Balancer_Is_Balancing(void);
212 
213 //! Sets Balancer Control Task for synchronous or asynchronous mode.
214 //! @return void
215 void Balancer_Synchronous_Mode_Set(BOOLEAN synchronous_mode //!< TRUE for synchronous mode, FALSE for asynchronous mode.
216  );
217 
218 //! Returns if Balancer Control Task is configured for synchronous mode.
219 //! @return TRUE if Balancer Control Task is configured for synchronous mode.
220 BOOLEAN Balancer_Synchronous_Mode_Get(void);
221 
222 //! Forces recalculation of the longest and shortest (yet non-zero) active balance times in the DC2100A system.
223 //! @return void
225 
226 #endif
int16 BALANCER_PASSIVE_STATE_TYPE
Bitmap for LTC6804_NUM_CELLV_ADC passive balancers on one DC2100A, 1 = ON and 0 = Off...
Definition: Balancer.h:105
void Balancer_Start(void)
Places Balancer Control Task in the BALANCER_CONTROL_ON state.
Definition: Balancer.c:539
void Balancer_Max_and_Nextstop_Find(void)
Forces recalculation of the longest and shortest (yet non-zero) active balance times in the DC2100A s...
Definition: Balancer.c:604
BALANCER_ACTIVE_STATE_TYPE Balancer_Active_Time_Next_Stop
The shortest, yet non-zero, active balance time in the DC2100A system.
Definition: Balancer.c:91
BALANCER_ACTIVE_STATE_TYPE Balancer_Active_State[DC2100A_MAX_BOARDS][DC2100A_NUM_CELLS]
The state of each active cell balancer on each DC2100A in the system.
Definition: Balancer.c:89
BALANCER_ACTIVE_STATE_TYPE Balancer_Active_Time_Max
The longest active balance time in the DC2100A system.
Definition: Balancer.c:90
Balancing is not active.
Definition: Balancer.h:72
Balancing commands are suspended.
Definition: Balancer.h:76
void Balancer_Control_Task(void)
Executes the Balancer Control task.
Definition: Balancer.c:168
BOOLEAN Balancer_Synchronous_Mode_Get(void)
Returns if Balancer Control Task is configured for synchronous mode.
Definition: Balancer.c:598
int16 BALANCER_ACTIVE_STATE_TYPE
Size of structure used for balancer active state.
Definition: Balancer.h:91
Balancing commands are being executed for a timed value for each cell.
Definition: Balancer.h:75
BALANCER_PASSIVE_STATE_TYPE Balancer_Passive_State[DC2100A_MAX_BOARDS]
Bitmap for LTC6804_NUM_CELLV_ADC passive balancers on one DC2100A, 1 = ON and 0 = Off...
Definition: Balancer.c:94
void Balancer_Synchronous_Mode_Set(BOOLEAN synchronous_mode)
Sets Balancer Control Task for synchronous or asynchronous mode.
Definition: Balancer.c:592
BOOLEAN Balancer_Wakeup_Init(void)
Initializes the parts of the Balancer Module, that need to be initialized upon wakeup of the LTC3300-...
Definition: Balancer.c:143
int8 Balancer_Active_Board_Max
The board with the longest remaining balance time.
Definition: Balancer.c:92
Watchdog is being activated to prevent LTC3300s from going to sleep, but raw commands are being sent ...
Definition: Balancer.h:73
BALANCER_CONTROL_STATE_TYPE
Definition: Balancer.h:70
int8 Balancer_Active_Board_Next_Stop
The cell with the shortest, yet non-zero, remaining balance time.
Definition: Balancer.c:93
void Balancer_Stop(void)
Places Balancer Control Task in the BALANCER_CONTROL_OFF state immediately, as it's possible there's ...
Definition: Balancer.c:547
void Balancer_Set(void)
Places Balancer Control Task in the BALANCER_CONTROL_SETUP state.
Definition: Balancer.c:303
Balancing commands are being loaded.
Definition: Balancer.h:74
signed int32 BALANCER_DELTA_Q_TYPE
Data Type for amount of charge to move from a cell in mAs.
Definition: Balancer.h:110
void Balancer_Suspend(void)
Places Balancer Control Task in the BALANCER_CONTROL_SUSPEND state immediately as it's possible there...
Definition: Balancer.c:562
void Balancer_GUI(void)
Places Balancer Control Task in the BALANCER_CONTROL_GUI state, stopping all control of balancers by ...
Definition: Balancer.c:570
BOOLEAN Balancer_Is_Balancing(void)
Returns if any balancer is actively balancing.
Definition: Balancer.c:576
void Balancer_Init(void)
Initializes the parts of the Balancer Module, that need to be initialized upon power-up of the PIC...
Definition: Balancer.c:120