energyShield 2 Pro Arduino Library Reference

Created On
Last Updated On
byAaron Liebold
Print
< All Topics

energyShield 2 Pro Arduino Library Reference

The energyShield 2 library provides software functions that allow the user to easily access all of the energyShield 2 Pro’s advanced functionality. This functionality comes from the integrated battery fuel gauge, real-time clock, solar input regulation, and voltage measurement ability (these features are not present on the energyShield 2 Basic). This library communicates with these peripherals using the Arduino Wire library (TWI) and one of the Arduino’s analog inputs (A0 by default). The TWI is, by default, connected to the SDA and SCL pins which are available on all Arduino’s with the R3 layout. For backward compatibility, the SDA and SCL lines can be connected to A4 and A5 by bridging the corresponding solder jumpers on the bottom of the energyShield.

NS_energyShield2 Library Links

Changelog

  • 03/29/18 – Fixed custom battery capacity. Added readVMPP() to examples
  • 02/08/18 – Updated README.md
  • 04/07/17 – Updated sleepSeconds() function
  • 03/02/17 – Updated default battery capacity
  • 03/01/17 – Initial Commit

Classes

NS_energyShield2()

Class

NS_energyShield2()
NS_energyShield2(uint16_t batteryCapacity_mAh)

Description

Creates an instance of the NS_energyShield2 class.

Parameters

Battery Capacity: The battery capacity in mAh of the 3.7V Li-Po cell connected to the energyShield 2. (Optional) Assumed to be the default 1800mAh, if not specified.

NS_energyShield2 es2; // Creates NS_energyShield2 object called es2 with the default capacity of 1800mAh
NS_energyShield2 es2(1500); // Creates NS_energyShield2 object called es2 with a custom capacity of 1500mAh

Methods

begin()

Method

NS_energyShield2.begin()

Description

Initializes energyShield 2. The initialization starts the Wire library, sets up the RTC and fuel gauge, and disables input voltage regulation (to allow charging at any voltage from 7V – 23 V) on the barrel jack.

The initialization starts the Wire library, sets up the RTC and fuel gauge, and disables input voltage regulation (to allow charging at any voltage from 7V – 23 V) on the barrel jack. If you are using setVMPP() to regulate the input voltage, place the setVMPP() command immediately after the begin() command.

Parameters

None.

Returns

FALSE – if initialization was successful.
TRUE – if failed to initialize. (int)

es2.begin(); // Initialize energyShield 2

batteryVoltage()

Method

NS_energyShield2.batteryVoltage()

Description

Measures the voltage of the battery on the energyShield 2.

Parameters

None.

Returns

Battery voltage in mV. (uint16_t)

unsigned int Voltage; 
Voltage = es2.batteryVoltage();

batteryCurrent()

Method

NS_energyShield2.batteryCurrent()

Description

Measures the current into the battery on the energyShield 2. (Positive = Charging | Negative = Discharging)

Parameters

None.

Returns

Battery current in mA. (int16_t)

int Current; 
Current = es2.batteryCurrent();

SOC()

Method

NS_energyShield2.SOC()

Description

Measures state of charge (%) of the battery.

Parameters

None.

Returns

State of charge in 1% increments. (uint16_t)

unsigned int StateOfCharge; 
StateOfCharge = es2.SOC();

fullChargeCapacity()

Method

NS_energyShield2.fullChargeCapacity()

Description

Returns the fully-charged capacity of the battery learned by the fuel gauge.

Parameters

None.

Returns

Full charge capacity in mAh. (uint16_t)

unsigned int FullChargeCapacity; 
FullChargeCapacity = es2.fullChargeCapacity();

remainingCapacity()

Method

NS_energyShield2.remainingCapacity()

Description

Returns the remaining capacity of the battery.

Parameters

None.

Returns

Remaining capacity in mAh. (uint16_t)

unsigned int RemainingCapacity; 
RemainingCapacity= es2.remainingCapacity();

batteryAlert()

Method

NS_energyShield2.batteryAlert(uint8_t alarmSOC)

Description

Programs the state of charge at which the fuel gauge will turn on the low battery LED. By default, batteryAlert() is programmed to 10%.

Run this command after NS_energyShield2.begin().

Parameters

alarmSOC – the state of charge at which the LOW battery LED turns on. (uint8_t)

Returns

Remaining capacity in mAh. (uint16_t)

es2.batteryAlert(20); // Programs fuel gauge to turn on low battery LED at 20% or below

temperature()

Method

NS_energyShield2.temperature()

Description

Returns the temperature read by the fuel gauge.

Parameters

None.

Returns

Temperature in 0.1 °C. (int16_t)

int Temperature; 
Temperature = es2.temperature();

setVMPP()

Method

NS_energyShield2.setVMPP(int MPP_Voltage_mV, bool writeEEPROM)

Description

Sets the regulated maximum power point voltage of the solar charging. When charging from the barrel jack, the charger will reduce the charging current to keep the input voltage ≥ VMPP. A VMPP value ≤0 will disable the maximum power-point regulation and allow charging at any voltage from 7V – 23V. If written to EEPROM, the regulated VMPP value will be recalled after sleeping or after a lapse in solar power. The EEPROM has a limited number of write cycles (~1,000,000), so if you are changing the VMPP value frequently (e.g. MPPT) you should only write the EEPROM when the value needs to be remembered. The function readVMPP() can be used to check if the EEPROM needs to be rewritten to avoid unnecessary writes.

Parameters

MPP_Voltage_mV: Maximum power point voltage in mV. (int)

writeEEPROM – writes VMPP value to EEPROM, if true. (boolean)

Returns

Nothing.

es2.setVMPP(17500, 1); // Set MPP regulation at 17.5V and write to EEPROM, so setting can be recalled
es2.setVMPP(-1, 0); // Disable MPP regulation to allow charging from any voltage from 7V - 23V and do not write to EEPROM

readVMPP()

Method

NS_energyShield2.readVMPP()

Description

Reads the current VMPP regulation voltage.

Parameters

None

Returns

VMPP regulation voltage in mV. (int)

int VoltageMPP = es2.readVMPP(); // Read the current VMPP in mV

unsigned int MPPVoltage = 18000;
if (eS2.readVMPP() != MPPVoltage) {
     es2.setVMPP(MPPVoltage, 1); // If VMPP is not set correctly, write the correct VMPP to EEPROM
}

inputVoltage()

Method

NS_energyShield2.inputVoltage()
NS_energyShield2.inputVoltage(uint8_t pin)

Description

Measures the voltage input to the barrel jack from a solar panel or power adapter.

Parameters

pin: Analog pin connected to input voltage read circuit. (optional) Will default to analog pin 0 if not specified.

Returns

Voltage input in mV. (uint16_t)

Default (ADP:A0):

unsigned int SolarVoltage; 
SolarVoltage = es2.inputVoltage();

When VADP:A3 is used instead of VADP:A0

unsigned int SolarVoltage; 
SolarVoltage = es2.inputVoltage(3);

setTimeAndDate()

Method

NS_energyShield2.setTimeAndDate(uint8_t second, uint8_t minute, uint8_t hour, uint8_t dayOfMonth, uint8_t dayOfWeek, uint8_t month, uint8_t year)

Description

Sets the time and date in the energyShield’s RTC.

Parameters

second: seconds value of the time to be programmed in the RTC. (0-59)

minutes: minutes value of the time to be programmed in the RTC. (0-59)

hour: hour value of the time to be programmed in the RTC. (0-23)

dayOfMonth: day of the month to be programmed in the RTC. (1-31)

dayOfWeek: day of the week to be programmed in the RTC. (0-6 [Sun – Sat])

month: month of the year to be programmed in the RTC. (1-12)

year: year to be programmed in the RTC (0-99)

Returns

Nothing.

es2.setDateAndTime(00, 29, 16, 21, 3, 10, 15); // Set time and date to 4:29:00 P.M. Wednesday, October 21 2015

readClock()

Method

NS_energyShield2.readClock()

Description

Reads all time and date values from RTC into a local buffer.

Parameters

None.

Returns

Nothing.

es2.readClock();

second()

Method

NS_energyShield2.second()

Description

Returns seconds value from the local buffer.

Parameters

None.

Returns

Seconds values of time. (uint8_t)

char Seconds; 
es2.readClock(); 
Seconds = es2.seconds();

minute()

Method

NS_energyShield2.minute()

Description

Returns minutes value from the local buffer.

Parameters

None.

Returns

Minutes values of time. (uint8_t)

char Minutes; 
es2.readClock(); 
Minutes = es2.minute();

hour()

Method

NS_energyShield2.hour()

Description

Returns hour value from the local buffer.

Parameters

None.

Returns

Hour value of time. (uint8_t)

char Hour; 
es2.readClock(); 
Hour = es2.hour();

dayOfMonth()

Method

NS_energyShield2.dayOfMonth()

Description

Returns day of the month from the local buffer.

Parameters

None.

Returns

Day of the month. (uint8_t)

char DayOfTheMonth; 
es2.readClock(); 
DayOfTheMonth = es2.dayOfMonth();

dayOfWeek()

Method

NS_energyShield2.dayOfWeek()

Description

Returns day of the week from the local buffer.

Parameters

None.

Returns

Day of the week. (uint8_t) Returns a value of 0 – 6 corresponding to Sunday – Saturday.

char DayOfTheWeek; 
es2.readClock(); 
DayOfTheWeek = es2.dayOfWeek();

month()

Method

NS_energyShield2.month()

Description

Returns month of the year from the local buffer.

Parameters

None.

Returns

Month of the year. (uint8_t) Returns a value of 1 – 12 corresponding to January – December.

char Month; 
es2.readClock(); 
Month = es2.month();

year()

Method

NS_energyShield2.year()

Description

Returns the year from the local buffer.

Parameters

None.

Returns

The year. (uint8_t) Returns a value of 0 – 99.

char Year; 
es2.readClock(); 
Year = es2.year();

sleepSeconds()

Method

NS_energyShield2.sleepSeconds(int timeInSeconds)

Description

This function turns off the power from the energyShield 2 for timeInSeconds seconds and then turns the power back on. This allows the user to write code in a one time through format and call sleepSeconds() at the end of the code execution to turn off the power to the Arduino. When power is turned back on, the Arduino will execute all of the code again. This is very useful for intermittent tasks such as data logging or blinking an LED.

You must take the boot time of an Arduino into account when considering the efficiency/duty cycle of operation. An Arduino Uno with the Optiboot bootloader wakes up in a fraction of a second, while an Arduino Leonardo takes several seconds to begin executing the user’s program. This makes a big difference when using small sleep times.

Note: Due to the intricacies of the system, it will take about 1.5 seconds to enter sleep the first time after power cycling the switch on the energyShield 2.

Parameters

timeInSeconds: the amount of time, in seconds, that the energyShield 2 will turn off the power. timeInSeconds must be ≥3 seconds and up to a maximum of 604799 seconds (1 week – 1 second).

Returns

Nothing.

/* In this example, the Arduino turns on, blinks the LED, and then turns off for 4 seconds. This results in a power duty cycle of approximately 1000/(1000 + 4000), or 20% (assuming negligeble boot time). This means that the battery will last about 5 times as long as if the Arduino had run constantly. */ 
#include &amp;amp;amp;amp;lt;Utilities.h&amp;amp;amp;amp;gt; 
#include &amp;amp;amp;amp;lt;NS_energyShield2.h&amp;amp;amp;amp;gt; 

NS_energyShield2 es2; 

void setup() { 
es2.begin(); // Initialize energyShield 2 

pinMode(13, OUTPUT); // Set pin 13 as OUTPUT 

// Blink LED 
digitalWrite(13, HIGH); 
delay(1000); 
digitalWrite(13, LOW); 

es2.sleepSeconds(4); // Power turns off here
} 

void loop() { 
}

Legacy Methods

Methods

NS_energyShield2.voltage()

NS_energyShield2.current()

NS_energyShield.percent()

NS_energyShield.Vadp(int pin)

Description

These methods were added to provide backward compatibility with any code written for the energyShield 1.

Parameters

voltage()

None.

current()

None.

percent()

None.

Vadp():

pin: ADC channel connected to input voltage feedback.

Returns

voltage()

Battery voltage in mV.

current()

Battery current in mA.

percent()

State of battery charge in increments of 1%.

Vadp():

Adapter (barrel jack) voltage in mV.

Previous Hardware Reference – eS2 Pro
Next How to Set Up Solar Charging – eS2 Pro
Table of Contents
Pay with PayPal, PayPal Credit or any major credit card Powered by Stripe
Copyright 2013 - 2021 NightShade Electronics | All Rights Reserved