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.
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.
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;
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.
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.
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.
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 
int8_t LTC3335_Get_Counter_Test_Current(uint16_t *microamps)
Gets the battery current in uA.
Definition: LTC3335.cpp:431
LTC3335_OUTPUT_VOLTAGE_TYPE
Definition: LTC3335.h:120
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
Definition: LTC3335.h:139
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
static uint32_t discharged_capacity
in mAs, the discharged capacity calculated from the LTC3335 accumulator and
Definition: DC2343A.ino:110
LTC3335: Nanopower Buck-Boost DC/DC with Integrated Coulomb Counter.
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
static uint16_t vbat
battery voltage, optimally measured with an adc, set to a constant in this sketch ...
Definition: DC2343A.ino:117
int8_t LTC3335_Set_Counter_Test(boolean enabled)
Enables/Disables the LTC3335 Counter Test feature.
Definition: LTC3335.cpp:360
unsigned coulomb_counter_overflow
Coulomb counter operating fault due to an improperly chosen prescalar causing the ripple counter to o...
Definition: LTC3335.h:155
LTC3335_ALARM_TYPE alarms
active alarms read from the LTC3335.
Definition: DC2343A.ino:112
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
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.
int8_t LTC3335_Get_Alarms(LTC3335_ALARM_TYPE *alarms)
Gets the alarms active from the LTC3335.
Definition: LTC3335.cpp:225
unsigned unused
Definition: LTC3335.h:157
unsigned alarm_trip
Accumulator value has met or exceeded the alarm threshold value.
Definition: LTC3335.h:156
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
int8_t LTC3335_Clear_Int(LTC3335_ALARM_TYPE *alarms)
Sends the command to clear the INT condition.
Definition: LTC3335.cpp:268
static float voltage
Definition: DC2289AA.ino:71
The alarm conditions which cause the LTC3335 to activate the /INT pin.
Definition: LTC3335.h:152
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