Photon Battery Shield Hookup Guide

Contributors: jimblom

Using the MAX17043 LiPo Fuel Gauge

One of the most unique features of the Photon Battery Shield is the integrated MAX17043 LiPo fuel gauge. The MAX17043 sits between the battery and your Photon -- it uses a calibrated ADC to measure the battery voltage. Comparing that measured voltage against their "ModelGauge" algorithm, the IC can produce a state-of-charge (SOC) estimate, to give you an idea of what percentage remains of the battery charge.

Loading the SparkFunMAX17043 Library

The MAX17043 communicates over I²C, so coding an interface between the Photon and the fuel gauge can be a little tricky. Luckily, we've done the hard work for you! We've written a Particle library for the MAX17043. You can load it up in the Particle IDE by going to the "Libraries" tab, and searching for SparkFunMAX17043.

If you're using the desktop version of the IDE, Particle Dev, and still want to use the library, you can grab the latest version from our GitHub repository.

Running the MAX17043_Simple Example

After finding the library, navigate to "MAX17043_Simple.cpp" and click Use This Example -- the Build IDE will create a clone of this sketch in your "Code" tab.

You shouldn't have to change anything, just make sure your Photon is selected in the "Devices" tab, and click "Flash".

Once your Photon is running the code, there are two ways to view its data. One is to open a serial terminal (see our Serial Terminal Basics tutorial if you need help with this). Find your Photon's serial port number ("COM#" on Windows "/dev/tty.usbmodemXXXX" on Mac) and set the baud rate to 9600. The battery's voltage, state-of-charge, and alert status will stream by.

Since USB is plugged in, the voltage and percentage should steadily increase as the battery charges.

Alternatively, if you want to monitor the battery discharge, you can use the Photon's Internet-connectivity to view the battery voltage and charge status. First, though, you'll need to identify your Photon's device ID as well as your account's access token. The device ID can be found in Particle Build by clicking the '>' next to your device name.

Your access token can be found under the "Settings" tab.

Armed with those long strings of hex characters, open a new browser tab and navigate to:

https://api.particle.io/v1/devices/DEVICE_ID/voltage?access_token=ACCESS_TOKEN

Make sure to sub in the proper values for DEVICE_ID and ACCESS_TOKEN. If everything was entered correctly, you should see something like this:

Among the data in that JSON response is a "result" key, which shows the current voltage reading. You can also view the state-of-charge, and alert status by navigating to:

https://api.particle.io/v1/devices/DEVICE_ID/soc?access_token=ACCESS_TOKEN

and

https://api.particle.io/v1/devices/DEVICE_ID/alert?access_token=ACCESS_TOKEN

Yay Spark Variables!

Using the SparkFunMAX17043 Library

The SparkFunMAX17043 library is simple. There's some initialization required. Make sure to include the library, and in your setup() call lipo.begin().

language:c
#include "SparkFunMAX17043/SparkFunMAX17043.h" // Include the SparkFun MAX17043 library

void setup()
{
    // Set up the MAX17043 LiPo fuel gauge:
    lipo.begin(); // Initialize the MAX17043 LiPo fuel gauge

    // Quick start restarts the MAX17043 in hopes of getting a more accurate
    // guess for the SOC.
    lipo.quickStart();
}

Calling lipo.quickStart() will re-calibrate the MAX17043's ADC, and usually results in more accurate readings.

If you're using the library in Particle Build, make sure you go to the SPARKFUNMAX17043 library in the "Libraries" tab, select INCLUDE IN APP, and add it to your desired code file.

Reading Voltage and SoC

Two functions are used to read the MAX17043's voltage and state-of-charge values:

language:c
// lipo.getVoltage() returns a voltage value (e.g. 3.93)
voltage = lipo.getVoltage();
// lipo.getSOC() returns the estimated state of charge (e.g. 79%)
soc = lipo.getSOC();

Both functions return a float variable. lipo.getVoltage() should usually be between 0.0 and about 4.2. lipo.getSOC() should be somewhere between 0.0 and 100.0.

Using the Alert Interrupt

One of the MAX17043's nifty features is a programmable alert interrupt. You can tell it to trigger a flag whenever the state-of-charge falls below a certain threshold.

To set up the alert, use lipo.setThreshold([percentage]). For example:

language:c
lipo.setThreshold(15); // Set Alert threshold to 15%

...will set the alert threshold to 15%.

The alert status can be read in both software and hardware. To get the alert status in software, call lipo.getAlert(). This function will return 0 if the alert is not triggered, and 1 if it is.

As mentioned in the Battery Shield Overview section, a jumper on the bottom of the board can optionally be closed to connect the MAX17043's alert pin to Photon pin D6. This alert is active-low -- meaning it'll be HIGH when it's not triggered and LOW when the SoC has fallen below threshold.

Once an alert has been triggered, you'll need to clear it before it can fire again. That's what lipo.clearAlert() will do for you. Even if the SoC rises above the threshold, you'll still need to manually clear the alert.