| Linduino 1.3.0 Linear Technology Arduino-Compatible Demonstration Board

LTC3335.h
Go to the documentation of this file.
1 /*!
2 LTC3335: Nanopower Buck-Boost DC/DC with Integrated Coulomb Counter
3
4 This header file contains the API to the LTC3335 driver. A minimal
5 set of functions were declared to allow access to the features of the
6 part while abstracting away from the register transactions.
7
8 @verbatim
9 The LTC®3335 is a high efficiency, low quiescent current
10 (680nA) buck-boost DC/DC converter with an integrated
11 precision coulomb counter which monitors accumulated
12 battery discharge in long life battery powered applications.
13 The buck-boost can operate down to 1.8V on its input and
14 provides eight pin-selectable output voltages with up to
15 50mA of output current.
16
17 The coulomb counter stores the accumulated battery discharge
18 in an internal register accessible via an I2C interface.
19 The LTC3335 features a programmable discharge alarm
20 threshold. When the threshold is reached, an interrupt is
21 generated at the IRQ pin.
22
23 To accommodate a wide range of battery types and sizes,
24 the peak input current can be selected from as low as 5mA
25 to as high as 250mA and the full-scale coulomb counter
26 has a programmable range of 32,768:1.
27
28 @endverbatim
29
30 http://www.linear.com/product/LTC3335
31
32 http://www.linear.com/product/LTC3335#demoboards
33
34
35 Copyright 2018(c) Analog Devices, Inc.
36
37 All rights reserved.
38
39 Redistribution and use in source and binary forms, with or without
40 modification, are permitted provided that the following conditions are met:
41 - Redistributions of source code must retain the above copyright
42 notice, this list of conditions and the following disclaimer.
43 - Redistributions in binary form must reproduce the above copyright
44 notice, this list of conditions and the following disclaimer in
45 the documentation and/or other materials provided with the
46 distribution.
47 - Neither the name of Analog Devices, Inc. nor the names of its
48 contributors may be used to endorse or promote products derived
49 from this software without specific prior written permission.
50 - The use of this software may or may not infringe the patent rights
51 of one or more patent holders. This license does not release you
52 from the requirement that you obtain separate licenses from these
53 patent holders to use this software.
54 - Use of the software either in source or binary form, must be run
55 on or directly connected to an Analog Devices Inc. component.
56
57 THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR
58 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
59 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
60 IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT,
61 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
62 LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, PROCUREMENT OF SUBSTITUTE GOODS OR
63 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
64 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
65 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
66 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
67 */
68
69 /*! @file
70 @ingroup LTC3335
71 API Header File for LTC3335: Nanopower Buck-Boost DC/DC with Integrated Coulomb Counter
72 */
73
74 #ifndef LTC3335_H
75 #define LTC3335_H
76
77 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
78 // Includes
79 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
80 #include "LTC3335_Config.h"
81
82 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
83 // Definitions
84 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
85
86 // \cond
87 //! @name General Purpose Macros
88 //! @{
89 //! Macros to return the number of bits needed to store a number
90 #define NBITS2(n) ((n&2)?1:0)
91 #define NBITS4(n) ((n&(0xC))?(2+NBITS2(n>>2)):(NBITS2(n)))
92 #define NBITS8(n) ((n&0xF0)?(4+NBITS4(n>>4)):(NBITS4(n)))
93 #define NBITS16(n) ((n&0xFF00)?(8+NBITS8(n>>8)):(NBITS8(n)))
94 #define NBITS32(n) ((n&0xFFFF0000)?(16+NBITS16(n>>16)):(NBITS16(n)))
95 #define NBITS(n) (n==0?0:NBITS32(1L*n)+1)
96
97 //! macro for bitmask.
98 #define MASK(size, shift) (((1LL << (size)) - 1) << (shift))
99
100 //! Constants defined so that other constants don't include unexplained numbers in them.
101 #define MV_PER_V 1000
102 #define MA_PER_A 1000
103 #define UA_PER_MA 1000
104 #define SEC_PER_HR 3600
105 #define MS_PER_SEC 1000
106 //! @}
107 // \endcond
108
109 //! @name LTC3335 Driver Properties
110 //! @{
111 #define LTC3335_BAUD_RATE 400 //!< in kHz, Max Clock Operating Frequency (fSCL from datasheet page 5)
112 #define LTC3335_PRESCALER_MAX 15 //!< the maximum prescaler that be selected for the LTC3335.
113 #define LTC3335_TFS (11.74e-6) //!< in s, full scale ON time from page 15 of datasheet.
114 #define LTC3335_IQ (680e-9) //!< in A, Input Quiescent Current from page 1 of datasheet.
115 //! @}
116
117 //! @name Voltage Settings
118 //! @{
119 //! Options available for setting output voltage via I2C.
120 typedef enum { } LTC3335_OUTPUT_VOLTAGE_TYPE;
121 #define LTC3335_OUTPUT_VOLTAGE_1_8V 0
122 #define LTC3335_OUTPUT_VOLTAGE_2_5V 1
123 #define LTC3335_OUTPUT_VOLTAGE_2_8V 2
124 #define LTC3335_OUTPUT_VOLTAGE_3_0V 3
125 #define LTC3335_OUTPUT_VOLTAGE_3_3V 4
126 #define LTC3335_OUTPUT_VOLTAGE_3_6V 5
127 #define LTC3335_OUTPUT_VOLTAGE_4_5V 6
128 #define LTC3335_OUTPUT_VOLTAGE_5_0V 7
129 #define LTC3335_NUM_OUTPUT_VOLTAGES 8
130 //! @}
131
132 //! @name IPeak Settings
133 //! @{
134 //! Options available for IPeak setting.
135 //! NOTE! This can not be set via I2C. It can only be set with resistors on pins 13-15
136 //! of the LTC3335, along with the an appropriately sized inductor. In order to
137 //! translate accumulator values to coulombs, and Counter Test results to amps,
138 //! this setting must be known.
139 typedef enum { } LTC3335_IPEAK_CONFIGURATION_TYPE;
140 #define LTC3335_IPEAK_CONFIGURATION_5MA 0
141 #define LTC3335_IPEAK_CONFIGURATION_10MA 1
142 #define LTC3335_IPEAK_CONFIGURATION_15MA 2
143 #define LTC3335_IPEAK_CONFIGURATION_25MA 3
144 #define LTC3335_IPEAK_CONFIGURATION_50MA 4
145 #define LTC3335_IPEAK_CONFIGURATION_100MA 5
146 #define LTC3335_IPEAK_CONFIGURATION_150MA 6
147 #define LTC3335_IPEAK_CONFIGURATION_250MA 7
148 #define LTC3335_NUM_IPEAK 8
149 //! @}
150
151 //! The alarm conditions which cause the LTC3335 to activate the /INT pin.
152 typedef struct
153 {
154 unsigned ac_on_time_overflow :1; //!< AC(ON) time operating fault (tAC > tFS) due to improperly chosen inductor value timing out the AC(ON) measurement.
155 unsigned coulomb_counter_overflow :1; //!< Coulomb counter operating fault due to an improperly chosen prescalar causing the ripple counter to overflow.
156 unsigned alarm_trip :1; //!< Accumulator value has met or exceeded the alarm threshold value.
157 unsigned unused :5;
158 } LTC3335_ALARM_TYPE;
159
160 //! counts for iq current to accumulate to 1 mAs
161 #define LTC3335_TIMER_COUNTS_PER_IQ_MAS ((uint32_t)(LTC3335_TIMER_COUNTS_PER_SEC/(LTC3335_IQ * MA_PER_A)))
162
163 //! LTC3335_Counter_Test_Current_Task() must be called often more often than this rate for hardware counter to not overflow
164 #define LTC3335_MIN_CURRENT_TASK_RATE ((1LL << LTC3335_COUNTER_SIZE) * 2 * LTC3335_TFS)
165
166 // Value of IPEAK in mA, used in calculations of coulomb count and current.
167 #if LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_5MA
168 #define LTC3335_IPEAK_MA 5 //!< mA = 5mA, used in calculations of coulomb count and current.
169 #elif LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_10MA
170 #define LTC3335_IPEAK_MA 10 //!< mA = 10mA, used in calculations of coulomb count and current.
171 #elif LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_15MA
172 #define LTC3335_IPEAK_MA 15 //!< mA = 15mA, used in calculations of coulomb count and current.
173 #elif LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_25MA
174 #define LTC3335_IPEAK_MA 25 //!< mA = 25mA, used in calculations of coulomb count and current.
175 #elif LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_50MA
176 #define LTC3335_IPEAK_MA 50 //!< mA = 50mA, used in calculations of coulomb count and current.
177 #elif LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_100MA
178 #define LTC3335_IPEAK_MA 100 //!< mA = 100mA, used in calculations of coulomb count and current.
179 #elif LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_150MA
180 #define LTC3335_IPEAK_MA 150 //!< mA = 150mA, used in calculations of coulomb count and current.
181 #elif LTC3335_IPEAK_CONFIGURATION == LTC3335_IPEAK_CONFIGURATION_250MA
182 #define LTC3335_IPEAK_MA 250 //!< mA = 250mA, used in calculations of coulomb count and current.
183 #else
184 #error Must configure firmware for IPEAK value.
185 #endif
186
187 //! Macro to select the optimal prescaler for the specified battery capacity at compile time.
188 #define LTC3335_PRESCALER (LTC3335_PRESCALER_MAX - NBITS( (uint32_t)(1L*LTC3335_CAPACITY*SEC_PER_HR/LTC3335_RANGE(LTC3335_PRESCALER_MAX)) ) )
189
190 //! Macro to retrieve the LTC3335 coulomb count range with a given prescaler.
191 #if LTC3335_USE_SOFTWARE_CORRECTION == true
192 #define LTC3335_RANGE(p) ((uint32_t)(255LL * LTC3335_RESOLUTION(p) * ((1LL << 16) + LTC3335_CORRECTION_FACTOR_TYP) / (1L << 16)))
193 #else
194 #define LTC3335_RANGE(p) ((uint32_t)(255LL * LTC3335_RESOLUTION(p)))
195 #endif
196
197 //! Macro to retrieve the LTC3335 coulomb count resolution with a given prescaler.
198 #define LTC3335_RESOLUTION(p) ((uint32_t)(LTC3335_IPEAK_MA * LTC3335_TFS * (1LL << (42 - 1 - p)) / 255 + 0.5))
199
200 //! Verify that battery capacity isn't so gigantic that it would overflow a 32 bit number.
201 #if LTC3335_CAPACITY*SEC_PER_HR > ((1LL << 32) - 1)
202 #error Battery Capacity is larger than 32 bit number. Change 32bit capacity variables into 64bit.
203 #endif
204
205 //! Verify that capacity resolution isn't so tiny that half bits in units of mAs result in 1% discretization error.
206 #if LTC3335_CAPACITY*SEC_PER_HR < ((1L << 8) * 100 / 2)
207 #error Battery Capacity is so small that units of mAs result in more than 1% discretization error. Change code units to uAs.
208 #endif
209
210 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
211 // Global Data
212 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
213
214 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
215 // Global Functions
216 //-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
217
218 //! Initializes the LTC3335 driver, setting the prescaler, output voltage, and alarm threshold selected in LTC3335_Confg.h
219 //! @return 0 if the init was successful.
220 int8_t LTC3335_Init(void);
221
222 //! Enables/Disables software control of the LTC3335 output voltage.
223 //! If software control is enabled, the voltage is set to the specified setting.
224 //! @return 0 if the LTC3335 communication was successful.
225 int8_t LTC3335_Set_Voltage(boolean enabled, //!< TRUE to enable software control of output voltage, FALSE to disable software control (output voltage set by pins 3-5).
226 LTC3335_OUTPUT_VOLTAGE_TYPE voltage //!< The output voltage setting if software control is enabled.
227 );
228
229 //! Gets the alarms active from the LTC3335.
230 //! @return 0 if the LTC3335 communication was successful.
231 int8_t LTC3335_Get_Alarms(LTC3335_ALARM_TYPE *alarms //!< Bitmap containing the LTC3335 active alarms.
232 );
233
234 //! Sends the command to clear the INT condition.
235 //! NOTE! Additional registers are rewritten in order for the INT condition to be reset.
236 //! @return 0 if the LTC3335 communication was successful.
237 int8_t LTC3335_Clear_Int(LTC3335_ALARM_TYPE *alarms
238 );
239
240 //! Enables/Disables the LTC3335 Counter Test feature.
241 //! @return 0 if the LTC3335 communication was successful.
242 int8_t LTC3335_Set_Counter_Test(boolean enabled //!< TRUE to enable Counter Test feature, FALSE to disable Counter Test feature.
243 );
244
245 #if LTC3335_USE_SOFTWARE_CORRECTION == false
246 //! Gets the discharged capacity from the battery in mAs.
247 //! @return 0 if the LTC3335 communication was successful.
248 int8_t LTC3335_Get_Discharged_Capacity(uint32_t *discharged_capacity //!< Pointer to where discharged capacity will be returned.
249 );
250 #else
251 //! Gets the discharged capacity from the battery in mAs.
252 //! @return 0 if the LTC3335 communication was successful.
253 int8_t LTC3335_Get_Discharged_Capacity(uint32_t *discharged_capacity, //!< Pointer to where discharged capacity will be returned.
254 uint16_t vbat //!< Battery voltage used to select software correction factor.
255 );
256 #endif // LTC3335_USE_SOFTWARE_CORRECTION == false
257
258 #if LTC3335_USE_CURRENT_MEASUREMENT == true
259 #if LTC3335_USE_SOFTWARE_CORRECTION == false
260 //! Gets the battery current in uA.
261 //! @return 0 if the LTC3335 communication was successful.
262 int8_t LTC3335_Get_Counter_Test_Current(uint16_t *microamps //!< Pointer to where current will be returned.
263 );
264 #else
265 //! Gets the battery current in uA.
266 //! @return 0 if the LTC3335 communication was successful.
267 int8_t LTC3335_Get_Counter_Test_Current(uint16_t *microamps, //!< Pointer to where current will be returned.
268 uint16_t vbat //!< Battery voltage used to select software correction factor.
269 );
270 #endif // LTC3335_USE_SOFTWARE_CORRECTION == false
271
272 //! Resets the number of edges and the amount of time stored for the Counter Test feature.
273 //! @return TRUE if the LTC3335 communication was successful.
274 int8_t LTC3335_Reset_Counter_Test_Current(void);
275
276 //! Task that must be run periodically, for the edges and time to be stored for the
277 //! LTC3335 Counter Test feature.
278 //! @return TRUE if the LTC3335 communication was successful.
279 void LTC3335_Counter_Test_Current_Task(void);
280 #endif // LTC3335_USE_CURRENT_MEASUREMENT == true
281
282 #if LTC3335_USE_SOFTWARE_CORRECTION == true
283 //! Returns the software correction factor for a specified LTC3335_IPEAK_CONFIGURATION, LTC3335_OUTPUT_VOLTAGE, and battery voltage.
284 //! Note! - These corrections factors are only valid at room temperature and for the recommended Coilcraft LPS5030-xxxMRB inductor.
285 //! @return TRUE if the LTC3335 communication was successful.
286 int16_t LTC3335_Get_Software_Correction_Factor(uint16_t vbat //!< Battery voltage used to select software correction factor.
287 );
288 #endif // LTC3335_USE_SOFTWARE_CORRECTION == true
289
290 #endif // LTC3335_H
291
LTC3335_Get_Counter_Test_Current
int8_t LTC3335_Get_Counter_Test_Current(uint16_t *microamps)
Gets the battery current in uA.
Definition: LTC3335.cpp:431
LTC3335_OUTPUT_VOLTAGE_TYPE
LTC3335_OUTPUT_VOLTAGE_TYPE
Definition: LTC3335.h:120
LTC3335_Get_Discharged_Capacity
int8_t LTC3335_Get_Discharged_Capacity(uint32_t *discharged_capacity)
Gets the discharged capacity from the battery in mAs.
Definition: LTC3335.cpp:306
LTC3335_IPEAK_CONFIGURATION_TYPE
LTC3335_IPEAK_CONFIGURATION_TYPE
Definition: LTC3335.h:139
LTC3335_ALARM_TYPE::ac_on_time_overflow
unsigned ac_on_time_overflow
AC(ON) time operating fault (tAC > tFS) due to improperly chosen inductor value timing out the AC(ON)...
Definition: LTC3335.h:154
discharged_capacity
static uint32_t discharged_capacity
in mAs, the discharged capacity calculated from the LTC3335 accumulator and
Definition: DC2343A.ino:110
LTC3335_Config.h
LTC3335: Nanopower Buck-Boost DC/DC with Integrated Coulomb Counter.
LTC3335_Init
int8_t LTC3335_Init(void)
Verify that battery capacity isn&#39;t so gigantic that it would overflow a 32 bit number.
Definition: LTC3335.cpp:162
vbat
static uint16_t vbat
battery voltage, optimally measured with an adc, set to a constant in this sketch ...
Definition: DC2343A.ino:117
LTC3335_Set_Counter_Test
int8_t LTC3335_Set_Counter_Test(boolean enabled)
Enables/Disables the LTC3335 Counter Test feature.
Definition: LTC3335.cpp:360
LTC3335_ALARM_TYPE::coulomb_counter_overflow
unsigned coulomb_counter_overflow
Coulomb counter operating fault due to an improperly chosen prescalar causing the ripple counter to o...
Definition: LTC3335.h:155
alarms
LTC3335_ALARM_TYPE alarms
active alarms read from the LTC3335.
Definition: DC2343A.ino:112
LTC3335_Reset_Counter_Test_Current
int8_t LTC3335_Reset_Counter_Test_Current(void)
Resets the number of edges and the amount of time stored for the Counter Test feature.
Definition: LTC3335.cpp:396
LTC3335_Get_Software_Correction_Factor
int16_t LTC3335_Get_Software_Correction_Factor(uint16_t vbat)
Returns the software correction factor for a specified LTC3335_IPEAK_CONFIGURATION, LTC3335_OUTPUT_VOLTAGE, and battery voltage.
Definition: LTC3335_Correction_Tables.cpp:354
LTC3335_Get_Alarms
int8_t LTC3335_Get_Alarms(LTC3335_ALARM_TYPE *alarms)
Gets the alarms active from the LTC3335.
Definition: LTC3335.cpp:225
LTC3335_ALARM_TYPE::unused
unsigned unused
Definition: LTC3335.h:157
LTC3335_ALARM_TYPE::alarm_trip
unsigned alarm_trip
Accumulator value has met or exceeded the alarm threshold value.
Definition: LTC3335.h:156
LTC3335_Set_Voltage
int8_t LTC3335_Set_Voltage(boolean enabled, LTC3335_OUTPUT_VOLTAGE_TYPE voltage)
Enables/Disables software control of the LTC3335 output voltage.
Definition: LTC3335.cpp:206
LTC3335_Clear_Int
int8_t LTC3335_Clear_Int(LTC3335_ALARM_TYPE *alarms)
Sends the command to clear the INT condition.
Definition: LTC3335.cpp:268
voltage
static float voltage
Definition: DC2289AA.ino:71
LTC3335_ALARM_TYPE
The alarm conditions which cause the LTC3335 to activate the /INT pin.
Definition: LTC3335.h:152
LTC3335_Counter_Test_Current_Task
void LTC3335_Counter_Test_Current_Task(void)
Task that must be run periodically, for the edges and time to be stored for the LTC3335 Counter Test ...
Definition: LTC3335.cpp:409