1. Home
  2. Knowledge Base
  3. energyShield 2 Pro
  4. energyShield 2 Pro Arduino Library Reference

energyShield 2 Pro Arduino Library Reference

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.

 

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)

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)

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)

SOC()

Method

NS_energyShield2.SOC()

Description

Measures state of charge (%) of the battery.

Parameters

None.

Returns

State of charge in 1% increments. (uint16_t)

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)

remainingCapacity()

Method

NS_energyShield2.remainingCapacity()

Description

Returns the remaining capacity of the battery.

Parameters

None.

Returns

Remaining capacity in mAh. (uint16_t)

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)

temperature()

Method

NS_energyShield2.temperature()

Description

Returns the temperature read by the fuel gauge.

Parameters

None.

Returns

Temperature in 0.1 °C. (int16_t)

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.

readVMPP()

Method

NS_energyShield2.readVMPP()

Description

Reads the current VMPP regulation voltage.

Parameters

None

Returns

VMPP regulation voltage in mV. (int)

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):

When VADP:A3 is used instead of VADP:A0

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.

readClock()

Method

NS_energyShield2.readClock()

Description

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

Parameters

None.

Returns

Nothing.

second()

Method

NS_energyShield2.second()

Description

Returns seconds value from the local buffer.

Parameters

None.

Returns

Seconds values of time. (uint8_t)

minute()

Method

NS_energyShield2.minute()

Description

Returns minutes value from the local buffer.

Parameters

None.

Returns

Minutes values of time. (uint8_t)

hour()

Method

NS_energyShield2.hour()

Description

Returns hour value from the local buffer.

Parameters

None.

Returns

Hour value of time. (uint8_t)

dayOfMonth()

Method

NS_energyShield2.dayOfMonth()

Description

Returns day of the month from the local buffer.

Parameters

None.

Returns

Day of the month. (uint8_t)

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.

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.

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.

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.

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.

Was this article helpful?

Related Articles