├── LICENSE ├── README.md ├── doc └── MAX17043-MAX17044.pdf ├── firmware ├── SparkFunMAX17043.cpp ├── SparkFunMAX17043.h └── examples │ └── MAX17043_Simple.cpp └── spark.json /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 SparkFun Electronics 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## SparkFun MAX17043 Particle Library 2 | 3 | Firmware library SparkFun's Photon Battery Shield and the MAX17043 Breakout. 4 | 5 | About 6 | ------------------- 7 | 8 | This is a firmware library for [SparkFun's Photon Battery Shield](https://www.sparkfun.com/products/13626). 9 | 10 | [![Photon Battery Shield](https://cdn.sparkfun.com//assets/parts/1/1/0/0/9/13626-01a.jpg)](https://www.sparkfun.com/products/13626). 11 | 12 | The MAX17043 interfaces between a LiPo battery and a microcontroller. The MAX17043 can read a battery's voltage and, using a sophisticated battery-modelling algorithm, estimate the state of charge (SOC). 13 | 14 | Repository Contents 15 | ------------------- 16 | 17 | * **/doc** - Additional documentation for the user. These files are ignored by the IDE. 18 | * **/firmware** - Source files for the library (.cpp, .h). 19 | * **/firmware/examples** - Example sketches for the library (.cpp). Run these from the Particle IDE. 20 | * **spark.json** - General library properties for the Particel library manager. 21 | 22 | Example Usage 23 | ------------------- 24 | 25 | Include the MAX17043 library: 26 | 27 | #include "SparkFunMAX17043.h" // Include the SparkFun MAX17043 library 28 | 29 | Then use the `lipo` object to interact with it. Begin by initializing the IC: 30 | 31 | void setup() 32 | { 33 | // Set up the MAX17043 LiPo fuel gauge: 34 | lipo.begin(); // Initialize the MAX17043 LiPo fuel gauge 35 | 36 | // Quick start restarts the MAX17043 in hopes of getting a more accurate 37 | // guess for the SOC. 38 | lipo.quickStart(); 39 | 40 | // We can set an interrupt to alert when the battery SoC gets too low. 41 | // We can alert at anywhere between 1% - 32%: 42 | lipo.setThreshold(10); // Set alert threshold to 10%. 43 | } 44 | 45 | Then you can read the voltage and state-of-charge (SOC) values like this: 46 | 47 | // lipo.getVoltage() returns a voltage value (e.g. 3.93) 48 | voltage = lipo.getVoltage(); 49 | // lipo.getSOC() returns the estimated state of charge (e.g. 79%) 50 | soc = lipo.getSOC(); 51 | 52 | Check out the example files in the [examples directory](https://github.com/sparkfun/SparkFun_MAX17043_Particle_Library/tree/master/firmware/examples) for more guidance. 53 | 54 | Recommended Components 55 | ------------------- 56 | 57 | * [Particle Photon](https://www.sparkfun.com/products/13345) 58 | * [SparkFun Photon Battery Shield](https://www.sparkfun.com/products/13626) 59 | 60 | License Information 61 | ------------------- 62 | 63 | This product is _**open source**_! 64 | 65 | Please review the LICENSE.md file for license information. 66 | 67 | If you have any questions or concerns on licensing, please contact techsupport@sparkfun.com. 68 | 69 | Distributed as-is; no warranty is given. 70 | 71 | - Your friends at SparkFun. 72 | -------------------------------------------------------------------------------- /doc/MAX17043-MAX17044.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sparkfun/SparkFun_MAX17043_Particle_Library/f96f47139f538053e5d9341ca1b85079c2063340/doc/MAX17043-MAX17044.pdf -------------------------------------------------------------------------------- /firmware/SparkFunMAX17043.cpp: -------------------------------------------------------------------------------- 1 | /****************************************************************************** 2 | SparkFunMAX17043.cpp 3 | SparkFun MAX17043 Library Source File 4 | Jim Lindblom @ SparkFun Electronics 5 | Original Creation Date: June 22, 2015 6 | https://github.com/sparkfun/SparkFun_MAX17043_Particle_Library 7 | 8 | This file implements all functions of the MAX17043 class. Functions here range 9 | from higher level stuff, like reading/writing MAX17043 registers to low-level, 10 | hardware reads and writes. 11 | 12 | Development environment specifics: 13 | IDE: Particle Build 14 | Hardware Platform: Particle Photon 15 | SparkFun Photon Battery Shield 16 | 17 | This code is released under the MIT license. 18 | 19 | Distributed as-is; no warranty is given. 20 | ******************************************************************************/ 21 | #include "SparkFunMAX17043.h" 22 | 23 | /////////////////////////////////// 24 | // MAX17043 Register Definitions // 25 | /////////////////////////////////// 26 | // All registers contain two bytes of data and span two addresses. 27 | #define MAX17043_VCELL 0x02 // R - 12-bit A/D measurement of battery voltage 28 | #define MAX17043_SOC 0x04 // R - 16-bit state of charge (SOC) 29 | #define MAX17043_MODE 0x06 // W - Sends special commands to IC 30 | #define MAX17043_VERSION 0x08 // R - Returns IC version 31 | #define MAX17043_CONFIG 0x0C // R/W - Battery compensation (default 0x971C) 32 | #define MAX17043_COMMAND 0xFE // W - Sends special comands to IC 33 | 34 | /////////////////////////////////// 35 | // MAX17043 Config Register Bits // 36 | /////////////////////////////////// 37 | #define MAX17043_CONFIG_SLEEP 7 38 | #define MAX17043_CONFIG_ALERT 5 39 | #define MAX17043_CONFIG_THRESHOLD 0 40 | 41 | ///////////////////////////////////// 42 | // MAX17043 Mode Register Commands // 43 | ///////////////////////////////////// 44 | #define MAX17043_MODE_QUICKSTART 0x4000 45 | 46 | //////////////////////////////////////// 47 | // MAX17043 Command Register Commands // 48 | //////////////////////////////////////// 49 | #define MAX17043_COMMAND_POR 0x5400 50 | 51 | //////////////////////////////// 52 | // MAX17043 7-Bit I2C Address // 53 | //////////////////////////////// 54 | #define MAX17043_ADDRESS 0x36 55 | 56 | MAX17043::MAX17043() 57 | { 58 | 59 | } 60 | 61 | uint8_t MAX17043::begin() 62 | { 63 | Wire.begin(); 64 | return 1; 65 | } 66 | 67 | uint8_t MAX17043::quickStart() 68 | { 69 | // A quick-start allows the MAX17043 to restart fuel-gauge calculations in the 70 | // same manner as initial power-up of the IC. If an application’s power-up 71 | // sequence is exceedingly noisy such that excess error is introduced into the 72 | // IC’s “first guess” of SOC, the host can issue a quick-start to reduce the 73 | // error. A quick-start is initiated by a rising edge on the QSTRT pin, or 74 | // through software by writing 4000h to MODE register. 75 | return write16(MAX17043_MODE_QUICKSTART, MAX17043_MODE); 76 | } 77 | 78 | float MAX17043::getVoltage() 79 | { 80 | uint16_t vCell; 81 | vCell = read16(MAX17043_VCELL); 82 | // vCell is a 12-bit register where each bit represents 1.25mV 83 | vCell = (vCell) >> 4; 84 | 85 | return ((float) vCell / 800.0); 86 | } 87 | 88 | float MAX17043::getSOC() 89 | { 90 | uint16_t soc; 91 | float percent; 92 | soc = read16(MAX17043_SOC); 93 | percent = (soc & 0xFF00) >> 8; 94 | percent += (float) (((uint8_t) soc) / 256.0); 95 | 96 | return percent; 97 | } 98 | 99 | uint16_t MAX17043::getVersion() 100 | { 101 | return read16(MAX17043_VERSION); 102 | } 103 | 104 | uint8_t MAX17043::getThreshold() 105 | { 106 | uint16_t configReg = read16(MAX17043_CONFIG); 107 | uint8_t threshold = (configReg & 0x001F); 108 | 109 | // It has an LSb weight of 1%, and can be programmed from 1% to 32%. 110 | // Values are in 2's complement, e.g.: 00000=32%, 00001=31%, 11111=1%. 111 | // Let's convert our percent to that first: 112 | threshold = 32 - threshold; 113 | return threshold; 114 | } 115 | 116 | uint8_t MAX17043::setThreshold(uint8_t percent) 117 | { 118 | // The alert threshold is a 5-bit value that sets the state of charge level 119 | // where an interrupt is generated on the ALRT pin. 120 | 121 | // It has an LSb weight of 1%, and can be programmed from 1% to 32%. 122 | // Values are in 2's complement, e.g.: 00000=32%, 00001=31%, 11111=1%. 123 | // Let's convert our percent to that first: 124 | percent = constrain(percent, 0, 32); 125 | percent = 32 - percent; 126 | 127 | // Read config reg, so we don't modify any other values: 128 | uint16_t configReg = read16(MAX17043_CONFIG); 129 | configReg &= 0xFFE0; // Mask out threshold bits 130 | configReg |= percent; // Add new threshold 131 | 132 | return write16(configReg, MAX17043_CONFIG); 133 | } 134 | 135 | uint8_t MAX17043::clearAlert() 136 | { 137 | // Read config reg, so we don't modify any other values: 138 | uint16_t configReg = read16(MAX17043_CONFIG); 139 | configReg &= ~(1<> 8; 192 | return compensation; 193 | } 194 | 195 | uint16_t MAX17043::getConfigRegister() 196 | { 197 | return read16(MAX17043_CONFIG); 198 | } 199 | 200 | uint8_t MAX17043::setCompensation(uint8_t newCompensation) 201 | { 202 | // The CONFIG register compensates the ModelGauge algorith. The upper 8 bits 203 | // of the 16-bit register control the compensation. 204 | // Read the original configReg, so we can leave the lower 8 bits alone: 205 | uint16_t configReg = read16(MAX17043_CONFIG); 206 | configReg &= 0x00FF; // Mask out compensation bits 207 | configReg |= ((uint16_t)newCompensation << 8) | configReg; 208 | return write16(configReg, MAX17043_CONFIG); 209 | } 210 | 211 | uint8_t MAX17043::write16(uint16_t data, uint8_t address) 212 | { 213 | uint8_t msb, lsb; 214 | msb = (data & 0xFF00) >> 8; 215 | lsb = (data & 0x00FF); 216 | Wire.beginTransmission(MAX17043_ADDRESS); 217 | Wire.write(address); 218 | Wire.write(msb); 219 | Wire.write(lsb); 220 | return (Wire.endTransmission()); 221 | } 222 | 223 | uint16_t MAX17043::read16(uint8_t address) 224 | { 225 | uint8_t msb, lsb; 226 | int16_t timeout = 1000; 227 | 228 | Wire.beginTransmission(MAX17043_ADDRESS); 229 | Wire.write(address); 230 | Wire.endTransmission(false); 231 | 232 | Wire.requestFrom(MAX17043_ADDRESS, 2); 233 | while ((Wire.available() < 2) && (timeout-- > 0)) 234 | delay(1); 235 | msb = Wire.read(); 236 | lsb = Wire.read(); 237 | 238 | return ((uint16_t) msb << 8) | lsb; 239 | } 240 | 241 | // Define a static MAX17043 object called lipo, which we'll use in the sketches. 242 | MAX17043 lipo; 243 | -------------------------------------------------------------------------------- /firmware/SparkFunMAX17043.h: -------------------------------------------------------------------------------- 1 | /****************************************************************************** 2 | SparkFunMAX17043.h 3 | SparkFun MAX17043 Library Header File 4 | Jim Lindblom @ SparkFun Electronics 5 | Original Creation Date: June 22, 2015 6 | https://github.com/sparkfun/SparkFun_MAX17043_Particle_Library 7 | 8 | This file implements all functions of the MAX17043 class. Functions here range 9 | from higher level stuff, like reading/writing MAX17043 registers to low-level, 10 | hardware reads and writes. 11 | 12 | Development environment specifics: 13 | IDE: Particle Build 14 | Hardware Platform: Particle Photon 15 | SparkFun Photon Battery Shield 16 | 17 | This code is released under the MIT license. 18 | 19 | Distributed as-is; no warranty is given. 20 | ******************************************************************************/ 21 | #ifndef __SparkFunMAX17043_H__ 22 | #define __SparkFunMAX17043_H__ 23 | 24 | #include "application.h" 25 | 26 | class MAX17043 27 | { 28 | public: 29 | MAX17043(); 30 | 31 | // begin() - Initializes I2C and the MAX17043. 32 | uint8_t begin(); 33 | 34 | // quickStart() - Restarts the MAX17043 to allow it to re-"guess" the 35 | // parameters that go into its SoC algorithms. Calling this in your setup() 36 | // usually results in more accurate SoC readings. 37 | // Output: 0 on success, positive integer on fail. 38 | uint8_t quickStart(); 39 | 40 | // getVoltage() - Get the MAX17043's voltage reading. 41 | // Output: floating point value between 0-5V in 1.25mV increments. 42 | float getVoltage(); 43 | 44 | // getSOC() - Get the MAX17043's state-of-charge (SOC) reading, as calculated 45 | // by the IC's "ModelGauge" algorithm. 46 | // Output: floating point value between 0-100, representing a percentage of 47 | // full charge. 48 | float getSOC(); 49 | 50 | // getVersion() - Get the MAX17043's production version number. 51 | // Output: 3 on success 52 | uint16_t getVersion(); 53 | 54 | // getThreshold() - Get the MAX17043's current percentage threshold that will 55 | // trigger an alert. 56 | // Output: An integer value between 1 and 32, representing a % that will 57 | // trigger an alert interrupt. 58 | uint8_t getThreshold(); 59 | 60 | // setThreshold([percent]) - Set the MAX17043's percentage threshold that will 61 | // trigger an alert. 62 | // Input: [percent] - Percentage value that will trigger an alert interrupt. 63 | // Any value between 1 and 32 is valid. 64 | // Output: 0 on success, positive integer on fail. 65 | uint8_t setThreshold(uint8_t percent); 66 | 67 | // getAlert([clear]) - Check if the MAX17043's alert interrupt has been 68 | // triggered. 69 | // INPUT: [clear] - If [clear] is true, the alert flag will be cleared if it 70 | // was set. 71 | // OUTPUT: Returns 1 if interrupt is/was triggered, 0 if not. 72 | uint8_t getAlert(bool clear = false); 73 | 74 | // clearAlert() - Clear the MAX17043's alert flag. 75 | // Output: 0 on success, positive integer on fail. 76 | uint8_t clearAlert(); 77 | 78 | // sleep() - Set the MAX17043 into sleep mode. 79 | // Output: 0 on success, positive integer on fail. 80 | uint8_t sleep(); 81 | 82 | // wake() - Wake the MAX17043 up from sleep. 83 | // Output: 0 on success, positive integer on fail. 84 | uint8_t wake(); 85 | 86 | // reset() - Issue a Power-on-reset command to the MAX17043. This function 87 | // will reset every register in the MAX17043 to its default value. 88 | // Output: 0 on success, positive integer on fail. 89 | uint8_t reset(); 90 | 91 | // getConfigRegister() - Read the 16-bit value of the CONFIG Register. 92 | // Output: 16-bit integer value representing the msb and lsb bytes of the 93 | // CONFIG register. 94 | uint16_t getConfigRegister(); 95 | 96 | // getCompensation() - Get the ModelGauge compensation value - an obscure 97 | // 8-bit value set to 0x97 by default. 98 | // Output: 8-bit value read from the CONFIG register's MSB. 99 | uint8_t getCompensation(); 100 | 101 | // setCompensation([newCompensation]) - Set the 8-bit compensation value. This 102 | // is an obscure 8-bit value that has some effect on Maxim's ModelGauge 103 | // algorithm. 104 | // From the datasheet: "Contact Maxim for instructions for optimization." 105 | // Input: [newCompensation] - Should be a value between 0-255. 106 | // Output: 0 on success, positive integer on fail. 107 | uint8_t setCompensation(uint8_t newCompensation); 108 | 109 | private: 110 | // write16([data], [address]) - Write 16 bits to the requested address. After 111 | // writing the address to be written, two sequential 8-bit writes will occur. 112 | // the msb is written first, then lsb. 113 | // Input: [data] - A 16-bit integer to be written to the device. 114 | // [address] - An 8-bit address to be written to. 115 | // Output: 0 on success, positive integer on fail. 116 | uint8_t write16(uint16_t data, uint8_t address); 117 | 118 | // read16([address]) - Read 16-bits from the requested address of a device. 119 | // Input: [address] - An 8-bit address to be read from. 120 | // Output: A 16-bit value read from the device's address will be returned. 121 | uint16_t read16(uint8_t address); 122 | }; 123 | 124 | // Define a static MAX17043 object called lipo, which we'll use in the sketches. 125 | extern MAX17043 lipo; 126 | 127 | #endif 128 | -------------------------------------------------------------------------------- /firmware/examples/MAX17043_Simple.cpp: -------------------------------------------------------------------------------- 1 | /****************************************************************************** 2 | MAX17043_Simple_Serial.cpp 3 | SparkFun MAX17043 Example Code 4 | Jim Lindblom @ SparkFun Electronics 5 | Original Creation Date: June 22, 2015 6 | https://github.com/sparkfun/SparkFun_MAX17043_Particle_Library 7 | 8 | This file demonstrates the simple API of the SparkFun MAX17043 Particle library. 9 | Pair the Photon up to a SparkFun Photon Battery Shield 10 | (https://www.sparkfun.com/products/13626), and away you go! 11 | 12 | This example will print the gauge's voltage and state-of-charge (SOC) readings 13 | to both serial (9600 baud) and out to the Particle cloud. Navigate to 14 | https://api.particle.io/v1/devices/{DEVICE_ID}/voltage?access_token={ACCESS_TOKEN} 15 | https://api.particle.io/v1/devices/{DEVICE_ID}/soc?access_token={ACCESS_TOKEN} 16 | https://api.particle.io/v1/devices/{DEVICE_ID}/alert?access_token={ACCESS_TOKEN} 17 | 18 | And read your Photon's battery charge from the Cloud! 19 | 20 | Development environment specifics: 21 | IDE: Particle Build 22 | Hardware Platform: Particle Photon 23 | SparkFun Photon Battery Shield 24 | 25 | This code is released under the MIT license. 26 | 27 | Distributed as-is; no warranty is given. 28 | ******************************************************************************/ 29 | 30 | #include "SparkFunMAX17043/SparkFunMAX17043.h" // Include the SparkFun MAX17043 library 31 | 32 | double voltage = 0; // Variable to keep track of LiPo voltage 33 | double soc = 0; // Variable to keep track of LiPo state-of-charge (SOC) 34 | bool alert; // Variable to keep track of whether alert has been triggered 35 | 36 | void setup() 37 | { 38 | Serial.begin(9600); // Start serial, to output debug data 39 | 40 | // Set up Spark variables (voltage, soc, and alert): 41 | Particle.variable("voltage", voltage); 42 | Particle.variable("soc", soc); 43 | Particle.variable("alert", alert); 44 | // To read the values from a browser, go to: 45 | // http://api.particle.io/v1/devices/{DEVICE_ID}/{VARIABLE}?access_token={ACCESS_TOKEN} 46 | 47 | // Set up the MAX17043 LiPo fuel gauge: 48 | lipo.begin(); // Initialize the MAX17043 LiPo fuel gauge 49 | 50 | // Quick start restarts the MAX17043 in hopes of getting a more accurate 51 | // guess for the SOC. 52 | lipo.quickStart(); 53 | 54 | // We can set an interrupt to alert when the battery SoC gets too low. 55 | // We can alert at anywhere between 1% - 32%: 56 | lipo.setThreshold(20); // Set alert threshold to 20%. 57 | } 58 | 59 | void loop() 60 | { 61 | // lipo.getVoltage() returns a voltage value (e.g. 3.93) 62 | voltage = lipo.getVoltage(); 63 | // lipo.getSOC() returns the estimated state of charge (e.g. 79%) 64 | soc = lipo.getSOC(); 65 | // lipo.getAlert() returns a 0 or 1 (0=alert not triggered) 66 | alert = lipo.getAlert(); 67 | 68 | // Those variables will update to the Spark Cloud, but we'll also print them 69 | // locally over serial for debugging: 70 | Serial.print("Voltage: "); 71 | Serial.print(voltage); // Print the battery voltage 72 | Serial.println(" V"); 73 | 74 | Serial.print("Alert: "); 75 | Serial.println(alert); 76 | 77 | Serial.print("Percentage: "); 78 | Serial.print(soc); // Print the battery state of charge 79 | Serial.println(" %"); 80 | Serial.println(); 81 | 82 | delay(500); 83 | } 84 | -------------------------------------------------------------------------------- /spark.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "SparkFunMAX17043", 3 | "author": "Jim Lindblom ", 4 | "license": "MIT", 5 | "version": "1.1.3", 6 | "description": "A library to drive the MAX17043 LiPo fuel gauge." 7 | } 8 | --------------------------------------------------------------------------------