ModularSensors > Classes > loggerModem
ModularSensors > Modules > Primary Object Classes > loggerModem


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
Retained for backwards compatibility.
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 pullup) 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.

voidsetModemLED(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

StringgetModemName(void )

Get the modem name.

Returns String The modem name

boolmodemSetup(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.


boolsetup(void )

Retained for backwards compatibility.

Returns bool True if setup was successful

boolmodemHardReset(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_tparseNISTBytes(byte[4] nistBytes) protected

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


boolmodemWake(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.


boolwake(void )

Retained for backwards compatibility.

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

voidmodemPowerDown(void ) virtual

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


boolmodemSleep(void ) virtual

Request that the modem enter its lowest possible power state.

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

boolmodemSleepPowerDown(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.


voidsetModemStatusLevel(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.


voidsetModemWakeLevel(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.


voidsetModemResetLevel(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.


boolconnectInternet(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_tgetNISTTime(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.


boolgetModemSignalQuality(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.

boolgetModemBatteryStats(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.

floatgetModemChipTemperature(void ) pure virtual

Get the current temperature provided by the modem module.

Returns float The temperature in degrees Celsius

boolupdateModemMetadata(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 floatgetModemRSSI()

Get the stored Modem RSSI value.

Returns float The stored RSSI

static floatgetModemSignalPercent()

Get the stored modem signal strength as a percent.

Returns float The stored signal strength

static floatgetModemBatteryChargeState()

Get the stored modem battery charge state.

Returns float The stored signal percent

static floatgetModemBatteryChargePercent()

Get the stored modem battery charge percent object.

Returns float The stored battery charge percent

static floatgetModemBatteryVoltage()

Get the stored modem battery voltage.

Returns float The stored battery voltage in mV

static floatgetModemTemperature()

Get the stored modem temperature.

Returns float The stored temperature in degrees Celsius

static int16_tgetRSSIFromCSQ(int16_t csq) protected

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_tgetPctFromCSQ(int16_t csq) protected

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_tgetPctFromRSSI(int16_t rssi) protected

Get signal percent from CSQ.

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

boolisInternetAvailable(void ) pure virtual protected

Check whether there is an active internet connection available.

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

boolmodemSleepFxn(void ) pure virtual protected

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.

boolmodemWakeFxn(void ) pure virtual protected

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.

boolextraModemSetup(void ) pure virtual protected

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.


boolisModemAwake(void ) pure virtual protected

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().