loggerModem class

The loggerModem class provides an internet connection for the logger and supplies an Arduino Client instance to use to publish data.

A modem is a device that can be controlled by a logger to send out data directly to the world wide web.

The loggerModem class wraps the TinyGSM library and adds in the power functions to turn the modem on and off and some error checking.

TinyGSM is available here: https://github.com/vshymanskyy/TinyGSM

Derived classes

class DigiXBee: The parent class for all Digi XBee and XBee3 wifi and cellular modules.
class EspressifESP8266: The loggerModem subclass for any breakout of the Espressif ESP8266 wifi chip or ESP32 wifi/bluetooth chip that has been flashed with Espressif's AT command firmware.
class QuectelBG96: The loggerModem subclass for Dragino, Nimbelink, or any other module based on the Quectel BG96.
class SIMComSIM7000: The loggerModem subclass for Botletics, And1, and other modules based on the SIMCOM SIM7000.
class SIMComSIM7080: The loggerModem subclass for modules based on the SIMCOMSIM7080".
class SIMComSIM800: The loggerModem subclass for the Adafruit Fona 2G, the Sodaq GPRSBeeR4 and almost any other module based on the SIMCOM SIM800 or SIM900 modules andthier variants".
class SequansMonarch: The loggerModem subclass for Nimbelink or other modules based on the Sequans Monarch VZM20Q.
class SodaqUBeeR410M: The loggerModem subclass for the LTE-M Sodaq UBee based on the u-blox SARA R410M LTE-M cellular module. This can be also used for any other breakout of the the u-blox R4 or N4 series modules.
class SodaqUBeeU201: The loggerModem subclass for the 2G/3G Sodaq UBee based on the u-blox SARA U201 2G/3G cellular module.

Constructors, destructors, conversion operators

loggerModem(int8_t powerPin, int8_t statusPin, bool statusLevel, int8_t modemResetPin, bool resetLevel, uint32_t resetPulse_ms, int8_t modemSleepRqPin, bool wakeLevel, uint32_t wakePulse_ms, uint32_t max_status_time_ms, uint32_t max_disconnetTime_ms, uint32_t wakeDelayTime_ms, uint32_t max_atresponse_time_ms): Construct a new loggerModem object.
~loggerModem() virtual: Destroy the logger Modem object - no action taken.

Public functions

void setModemLED(int8_t modemLEDPin): Set an LED to turn on (pin will be HIGH) when the modem is on.
String getModemName(void ): Get the modem name.
bool modemSetup(void ) virtual: Set up the modem before first use.
bool setup(void ) deprecated in v0.24.1: Retained for backwards compatibility; use modemSetup() in new code.
bool modemHardReset(void ) virtual: Use the modem reset pin specified in the constructor to perform a "hard" or "panic" reset.

Protected static functions

static uint32_t parseNISTBytes(byte[4] nistBytes): Convert the 4 bytes returned on the NIST daytime protocol to the number of seconds since January 1, 1970 in UTC.

Protected variables

String _modemName: The modem name.

Member variables set in the constructor

These are all related to expected modem response times and the pin connections between the modem module and the logger MCU.

int8_t _powerPin protected: The digital pin number of the mcu pin controlling power to the modem (active HIGH).
int8_t _statusPin protected: The digital pin number of the mcu pin connected to the modem status output pin.
bool _statusLevel protected: The level (LOW or HIGH) of the _statusPin when the modem is active.
int8_t _modemResetPin protected: The digital pin number of the pin on the mcu attached the the hard or panic reset pin of the modem.
bool _resetLevel protected: The level (LOW or HIGH) of the _modemResetPin which will cause the modem to reset.
uint32_t _resetPulse_ms protected: The length of time in milliseconds at _resetLevel needed on _modemResetPin to reset the modem.
int8_t _modemSleepRqPin protected: The digital pin number of a pin on the mcu used to request the modem enter its lowest possible power state.
bool _wakeLevel protected: The level (LOW or HIGH) on the _modemSleepRqPin used to wake the modem.
uint32_t _wakePulse_ms protected: The length of pulse in milliseconds at _wakeLevel needed on the _modemSleepRqPin to wake the modem.
uint32_t _statusTime_ms protected: The time in milliseconds between when modemWake() is run and when the _statusPin is expected to be at _statusLevel.
uint32_t _disconnetTime_ms protected: The maximum length of time in milliseconds between when the modem is requested to enter lowest power state (modemSleep()) and when it should have completed necessary steps to shut down.
uint32_t _wakeDelayTime_ms protected: The time in milliseconds between when the modem is powered and when it is able to receive a wake command.
uint32_t _max_atresponse_time_ms protected: The time in milliseconds between when the modem is awake and when its serial ports reach full functionality and are ready to accept AT commands.

Flags and other member variables only used internally

int8_t _modemLEDPin protected: The digital pin number of a pin on the mcu used to indicate the modem's current activity state.
uint32_t _millisPowerOn protected: The processor elapsed time when the power was turned on for the modem.
uint32_t _lastNISTrequest protected: The processor elapsed time when the a connection to the NIST time server was last attempted.
bool _hasBeenSetup protected: Flag. True indicates that the modem has already successfully completed setup.
bool _pinModesSet protected: Flag. True indicates that the pins on the mcu attached to the modem are set to the correct mode (ie, input vs output).

Static member variables used to hold modem metadata

static int16_t _priorRSSI protected: The last stored RSSI value.
static int16_t _priorSignalPercent protected: The last stored signal strength percent value.
static float _priorModemTemp protected: The last stored modem chip temperature value.
static float _priorBatteryState protected: The last stored modem battery state value.
static float _priorBatteryPercent protected: The last stored modem battery percent value.
static float _priorBatteryVoltage protected: The last stored modem battery voltage value.

Pin setting functions

Functions to set or re-set the the pin numbers for the connection between the modem module and the logger MCU.

void setModemStatusLevel(bool level): Set the pin level to be expected when the on the modem status pin when the modem is active.
void setModemWakeLevel(bool level): Set the pin level to be used to wake the modem.
void setModemResetLevel(bool level): Set the pin level to be used to reset the modem.

Functions for internet connectivity

bool connectInternet(uint32_t maxConnectionTime = 50000L) pure virtual: Wait for the modem to successfully register on the cellular network and then request that it establish either EPS or GPRS data connection.
void disconnectInternet(void ) pure virtual: Detatch from EPS or GPRS data connection and then deregister from the cellular network.
uint32_t getNISTTime(void ) pure virtual: Get the time from NIST via TIME protocol (rfc868).

Modem metadata functions

Functions to get metadata about modem functionality - using the modem like a sensor.

These functions will query the modem to get new values.

bool getModemSignalQuality(int16_t& rssi, int16_t& percent) pure virtual: Query the modem for the current signal quality and write the results to the supplied non-constant references.
bool getModemBatteryStats(uint8_t& chargeState, int8_t& percent, uint16_t& milliVolts) pure virtual: Query the modem for battery information and write the values to the supplied non-constant references.
float getModemChipTemperature(void ) pure virtual: Get the current temperature provided by the modem module.
bool updateModemMetadata(void ) virtual: Query the modem for signal quality, battery, and temperature information and store the values to the static internal variables.

Functions to return the current value of static member variables

These functions do NOT query the modem for new values, they return the stored value.

static float getModemRSSI(): Get the stored Modem RSSI value.
static float getModemSignalPercent(): Get the stored modem signal strength as a percent.
static float getModemBatteryChargeState(): Get the stored modem battery charge state.
static float getModemBatteryChargePercent(): Get the stored modem battery charge percent object.
static float getModemBatteryVoltage(): Get the stored modem battery voltage.
static float getModemTemperature(): Get the stored modem temperature.

Functions to convert between signal strength measurement types

static int16_t getRSSIFromCSQ(int16_t csq) protected: Get approximate RSSI from CSQ (assuming no noise).
static int16_t getPctFromCSQ(int16_t csq) protected: Get signal percent from CSQ.
static int16_t getPctFromRSSI(int16_t rssi) protected: Get signal percent from CSQ.

Helper functions

void modemLEDOn(void ) protected: Turn on the modem LED/alert pin - sets it HIGH
void modemLEDOff(void ) protected: Turn off the modem LED/alert pin - sets it LOW
void setModemPinModes(void ) protected virtual: Set the processor pin modes (input vs output, with and without pull-up) for all pins connected between the modem module and the mcu.

Pure virtual functions for each modem to implement

bool isInternetAvailable(void ) protected pure virtual: Check whether there is an active internet connection available.
bool modemSleepFxn(void ) protected pure virtual: Perform the parts of the modem sleep process that are unique to a specific module, as opposed to the parts of setup that are common to all modem modules.
bool modemWakeFxn(void ) protected pure virtual: Perform the parts of the modem wake up process that are unique to a specific module, as opposed to the parts of setup that are common to all modem modules.
bool extraModemSetup(void ) protected pure virtual: Perform the parts of the modem set up process that are unique to a specific module, as opposed to the parts of setup that are common to all modem modules.
bool isModemAwake(void ) protected pure virtual: Check if the modem was awake using all possible means.

Function documentation

loggerModem(int8_t powerPin, int8_t statusPin, bool statusLevel, int8_t modemResetPin, bool resetLevel, uint32_t resetPulse_ms, int8_t modemSleepRqPin, bool wakeLevel, uint32_t wakePulse_ms, uint32_t max_status_time_ms, uint32_t max_disconnetTime_ms, uint32_t wakeDelayTime_ms, uint32_t max_atresponse_time_ms)

Construct a new loggerModem object.

Parameters
powerPin	The digital pin number of the mcu pin controlling power to the modem (active `HIGH`).
statusPin	The digital pin number of the mcu pin connected to the modem status output pin.
statusLevel	The level (`LOW` or `HIGH`) of the _statusPin when the modem is active.
modemResetPin	The digital pin number of the pin on the mcu attached the the hard or panic reset pin of the modem.
resetLevel	The level (`LOW` or `HIGH`) of the _modemResetPin which will cause the modem to reset.
resetPulse_ms	The length of time in milliseconds at _resetLevel needed on _modemResetPin to reset the modem.
modemSleepRqPin	The digital pin number of a pin on the mcu used to request the modem enter its lowest possible power state.
wakeLevel	The level (`LOW` or `HIGH`) on the _modemSleepRqPin used to wake the modem.
wakePulse_ms	The length of pulse in milliseconds at _wakeLevel needed on the _modemSleepRqPin to wake the modem.
max_status_time_ms	The time in milliseconds between when modemWake() is run and when the _statusPin is expected to be at _statusLevel.
max_disconnetTime_ms	The maximum length of time in milliseconds between when the modem is requested to enter lowest power state (modemSleep()) and when it should have completed necessary steps to shut down.
wakeDelayTime_ms	The time in milliseconds between when the modem is powered and when it is able to receive a wake command.
max_atresponse_time_ms	The time in milliseconds between when the modem is awake and when its serial ports reach full functionality and are ready to accept AT commands.

void setModemLED(int8_t modemLEDPin)

Set an LED to turn on (pin will be HIGH) when the modem is on.

Parameters
modemLEDPin	The digital pin number for the LED

String getModemName(void )

Get the modem name.

Returns	String The modem name

bool modemSetup(void ) virtual

Set up the modem before first use.

Returns	bool True if setup was successful

This is used for operations that cannot happen in the modem constructor - they must happen at run time, not at compile time.

bool setup(void ) deprecated in v0.24.1

Retained for backwards compatibility; use modemSetup() in new code.

Returns	bool True if setup was successful

bool modemHardReset(void ) virtual

Use the modem reset pin specified in the constructor to perform a "hard" or "panic" reset.

Returns	bool True if the reset succeeded and the modem should now be responsive. False if the modem remains non-responsive either because the reset failed to fix the communication issue or because a reset is not possible with the current pin/modem configuration.

This should only be used if the modem is clearly non-responsive.

static uint32_t parseNISTBytes(byte[4] nistBytes)

Convert the 4 bytes returned on the NIST daytime protocol to the number of seconds since January 1, 1970 in UTC.

Parameters
nistBytes	4 bytes from NIST
Returns	uint32_t the number of seconds since January 1, 1970 00:00:00 UTC

NIST supplies a 4 byte response to any TCP connection made on port 37. This is the 32-bit number of seconds since January 1, 1970 00:00:00 UTC. The server closes the TCP connection immediately after sending the data, so there is no need to close it

bool modemWake(void ) pure virtual

Wake up the modem.

Returns	bool True if the modem is responsive and ready for action.

This sets pin modes, powers up the modem if necessary, sets time stamps, runs the specific modem's wake function, tests for responsiveness to AT commands, and then re-runs the TinyGSM init() if necessary. If the modem fails to respond, this attempts a "hard" pin reset if possible.

For most modules, this function is created by the MS_MODEM_WAKE macro.

bool wake(void ) deprecated in v0.24.1

Retained for backwards compatibility; use modemWake() in new code.

Returns	bool True if wake was sucessful, modem should be ready to communicate

void modemPowerDown(void ) virtual

Cut power to the modem by setting the modem power pin low.

bool modemSleep(void ) virtual

Request that the modem enter its lowest possible power state.

Returns	bool True if the modem has sucessfully entered low power state

bool modemSleepPowerDown(void ) virtual

Request that the modem enter its lowest possible power state and then set the power pin low after the modem has indicated it has successfully gone to low power.

Returns	bool True if the modem has sucessfully entered low power state and then powered off

This allows the modem to shut down all connections cleanly and do any necessary internal housekeeping before stopping power.

void setModemStatusLevel(bool level)

Set the pin level to be expected when the on the modem status pin when the modem is active.

Parameters
level	The active level of the pin (`LOW` or `HIGH`)

If this function is not called, the modem status pin is assumed to exactly follow the hardware specifications for that modems raw cellular component.

void setModemWakeLevel(bool level)

Set the pin level to be used to wake the modem.

Parameters
level	The pin level (`LOW` or `HIGH`) of the pin while waking the modem.

If this function is not called, the modem status pin is assumed to exactly follow the hardware specifications for that modems raw cellular component.

void setModemResetLevel(bool level)

Set the pin level to be used to reset the modem.

Parameters
level	The pin level (`LOW` or `HIGH`) of the pin while resetting the modem.

If this function is not called, the modem status pin is assumed to exactly follow the hardware specifications for that modems raw cellular component - nearly always low.

bool connectInternet(uint32_t maxConnectionTime = 50000L) pure virtual

Wait for the modem to successfully register on the cellular network and then request that it establish either EPS or GPRS data connection.

Parameters
maxConnectionTime	The maximum length of time in milliseconds to wait for network registration and data sconnection. Defaults to 50,000ms (50s).
Returns	bool True if EPS or GPRS data connection has been established. False if the modem wasunresponsive, unable to register with the cellular network, or unable to establish a EPS or GPRS connection.

uint32_t getNISTTime(void ) pure virtual

Get the time from NIST via TIME protocol (rfc868).

Returns	uint32_t The number of seconds since Jan 1, 1970 IN UTC

This would be much more efficient if done over UDP, but I'm doing it over TCP because I don't have a UDP library for all the modems.

bool getModemSignalQuality(int16_t& rssi, int16_t& percent) pure virtual

Query the modem for the current signal quality and write the results to the supplied non-constant references.

Parameters
rssi	A reference to an int16_t which will be set with the received signal strength indicator
percent	A reference to an int16_t which will be set with the "percent" signal strength
Returns	bool True indicates that the communication with the modem was successful and the values referenced by the pointers should be valid.

bool getModemBatteryStats(uint8_t& chargeState, int8_t& percent, uint16_t& milliVolts) pure virtual

Query the modem for battery information and write the values to the supplied non-constant references.

Parameters
chargeState	A reference to an uint8_t which will be set with the current charge state (significance of value varies)
percent	A reference to an int8_t which will be set with the current charge percent - this may or may not be a valid value depending on the module and breakout.
milliVolts	A reference to an uint16_t which will be set with the current battery voltage in mV - this may or may not be a valid value depending on the module and breakout.
Returns	bool True indicates that the communication with the modem was successful and the values referenced by the pointers should be valid.

float getModemChipTemperature(void ) pure virtual

Get the current temperature provided by the modem module.

Returns	float The temperature in degrees Celsius

bool updateModemMetadata(void ) virtual

Query the modem for signal quality, battery, and temperature information and store the values to the static internal variables.

Returns	bool True indicates that the communication with the modem was successful and the values of the internal static variables should be valid.

static float getModemRSSI()

Get the stored Modem RSSI value.

Returns	float The stored RSSI

static float getModemSignalPercent()

Get the stored modem signal strength as a percent.

Returns	float The stored signal strength

static float getModemBatteryChargeState()

Get the stored modem battery charge state.

Returns	float The stored signal percent

static float getModemBatteryChargePercent()

Get the stored modem battery charge percent object.

Returns	float The stored battery charge percent

static float getModemBatteryVoltage()

Get the stored modem battery voltage.

Returns	float The stored battery voltage in mV

static float getModemTemperature()

Get the stored modem temperature.

Returns	float The stored temperature in degrees Celsius

static int16_t getRSSIFromCSQ(int16_t csq)

Get approximate RSSI from CSQ (assuming no noise).

Parameters
csq	A "CSQ" (0-31) signal qualilty
Returns	int16_t An RSSI in dBm, making assumptions about the conversion

The RSSI is estimated from a look-up assuming no noise.

static int16_t getPctFromCSQ(int16_t csq)

Get signal percent from CSQ.

Parameters
csq	A "CSQ" (0-31) signal qualilty
Returns	int16_t The percent of maximum signal strength.

The percent is grabbed from a look-up.

static int16_t getPctFromRSSI(int16_t rssi)

Get signal percent from CSQ.

Parameters
rssi	The RSSI in dBm.
Returns	int16_t The estimated percent of maximum signal strength.

bool isInternetAvailable(void ) pure virtual

Check whether there is an active internet connection available.

Returns	bool True if there is an active data connection to the internet.

bool modemSleepFxn(void ) pure virtual

Perform the parts of the modem sleep process that are unique to a specific module, as opposed to the parts of setup that are common to all modem modules.

Returns	bool True if the unique part of the sleep function ran sucessfully.

bool modemWakeFxn(void ) pure virtual

Perform the parts of the modem wake up process that are unique to a specific module, as opposed to the parts of setup that are common to all modem modules.

Returns	bool True if the unique part of the wake function ran sucessfully - does NOT indicate that the modem is now responsive.

bool extraModemSetup(void ) pure virtual

Perform the parts of the modem set up process that are unique to a specific module, as opposed to the parts of setup that are common to all modem modules.

Returns	bool True if the extra setup succeeded.

For most modules, this function is created by the MS_MODEM_EXTRA_SETUP macro which runs the TinyGSM modem init() and client init() functions.

bool isModemAwake(void ) pure virtual

Check if the modem was awake using all possible means.

Returns	bool True if the modem is already awake.

If possible, we always want to check if the modem was awake before attempting to wake it up. Most cellular modules are woken and put to sleep by identical pulses on a sleep or "power" pin. We don't want to accidently pulse an already on modem to off.

For most modules, this function is created by the MS_IS_MODEM_AWAKE macro.

Variable documentation

String loggerModem::_modemName protected

The modem name.

Set in the init() portion of the modemSetup(). Returned by getModemName().

int8_t loggerModem::_powerPin protected

The digital pin number of the mcu pin controlling power to the modem (active HIGH).

Should be set to a negative number if the modem should be continuously powered or the power cannot be controlled by the MCU.

int8_t loggerModem::_statusPin protected

The digital pin number of the mcu pin connected to the modem status output pin.

Should be set to a negative number if the modem status pin cannot be read.

int8_t loggerModem::_modemResetPin protected

The digital pin number of the pin on the mcu attached the the hard or panic reset pin of the modem.

Should be set to a negative number if the modem reset pin is not connected to the MCU.

int8_t loggerModem::_modemSleepRqPin protected

The digital pin number of a pin on the mcu used to request the modem enter its lowest possible power state.

Should be set to a negative number if there is no pin usable for deep sleep modes or it is not accessible to the MCU.

uint32_t loggerModem::_wakePulse_ms protected

The length of pulse in milliseconds at _wakeLevel needed on the _modemSleepRqPin to wake the modem.

Set to 0 if the pin must be continuously held at _wakeLevel to keep the modem active.

uint32_t loggerModem::_wakeDelayTime_ms protected

The time in milliseconds between when the modem is powered and when it is able to receive a wake command.

That is, the time that should be allowed between modemPowerUp() and modemWake().

uint32_t loggerModem::_max_atresponse_time_ms protected

The time in milliseconds between when the modem is awake and when its serial ports reach full functionality and are ready to accept AT commands.

That is, the time that should be allowed between modemWake() and init(). If the modem does not respond within this time frame (plus a 500ms buffer) a modemHardReset() will be attempted.

int8_t loggerModem::_modemLEDPin protected

The digital pin number of a pin on the mcu used to indicate the modem's current activity state.

Intended to be a pin attached to a LED.

Should be set to a negative number if no LED is available.

uint32_t loggerModem::_millisPowerOn protected

The processor elapsed time when the power was turned on for the modem.

The _millisPowerOn value is set in the modemPowerUp() function. It is un-set in the modemSleepPowerDown() function.

uint32_t loggerModem::_lastNISTrequest protected

The processor elapsed time when the a connection to the NIST time server was last attempted.

NIST documentation is very clear that it must not be contacted more than once every 4 seconds.

static int16_t loggerModem::_priorRSSI protected

The last stored RSSI value.

Set by getModemSignalQuality() or updateModemMetadata(). Returned by getModemRSSI().

static int16_t loggerModem::_priorSignalPercent protected

The last stored signal strength percent value.

Set by getModemSignalQuality() or updateModemMetadata(). Returned by getModemSignalPercent().

static float loggerModem::_priorModemTemp protected

The last stored modem chip temperature value.

Set by getModemChipTemperature() or updateModemMetadata(). Returned by getModemTemperature().

static float loggerModem::_priorBatteryState protected

The last stored modem battery state value.

Set by getModemBatteryStats() or updateModemMetadata(). Returned by getModemBatteryChargeState().

static float loggerModem::_priorBatteryPercent protected

The last stored modem battery percent value.

Set by getModemBatteryStats() or updateModemMetadata(). Returned by getModemBatteryChargePercent().

static float loggerModem::_priorBatteryVoltage protected

The last stored modem battery voltage value.

Set by getModemBatteryStats() or updateModemMetadata(). Returned by getModemBatteryVoltage().