SIMComSIM7080 class

The loggerModem subclass for modules based on the SIMCOMSIM7080".

Base classes

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

Constructors, destructors, conversion operators

SIMComSIM7080(Stream* modemStream, int8_t powerPin, int8_t statusPin, int8_t modemSleepRqPin, const char* apn): Construct a new SIMComSIM7080 object The constructor initializes all of the provided member variables, constructs a loggerModem parent class with the appropriate timing for the module, calls the constructor for a TinyGSM modem on the provided modemStream, and creates a TinyGSM Client linked to the modem.
~SIMComSIM7080(): Destroy the SIMComSIM7080 object - no action needed.

Public functions

bool modemWake(void) -> bool override: Wake up the modem.
bool connectInternet(uint32_t maxConnectionTime = 50000L) -> bool override: 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) override: Detach from EPS or GPRS data connection and then deregister from the cellular network.
Client* createClient() -> Client* override: Create a new client object using the default socket number.
void deleteClient(Client* client) virtual: Attempts to delete a created TinyGsmClient object. We need to do this to close memory leaks from the create client because we can't delete the created client from a pointer to the parent because the Arduino core's client class doesn't have a virtual destructor.
Client* createSecureClient() -> Client* override: Create a new secure client object using the default socket number.
void deleteSecureClient(Client* client) virtual: Attempts to delete a created TinyGsmSecureClient object. We need to do this to close memory leaks from the create client because we can't delete the created client from a pointer to the parent because the Arduino core's client class doesn't have a virtual destructor.
Client* createSecureClient(SSLAuthMode sslAuthMode, SSLVersion sslVersion = SSLVersion::TLS1_2, const char* CAcertName = nullptr, const char* clientCertName = nullptr, const char* clientKeyName = nullptr) -> Client* override: Create a new secure client object using the default socket number.
Client* createSecureClient(const char* pskIdent, const char* psKey, SSLVersion sslVersion = SSLVersion::TLS1_2) -> Client* override: Create a new secure client object using the default socket number.
Client* createSecureClient(const char* pskTableName, SSLVersion sslVersion = SSLVersion::TLS1_2) -> Client* override: Create a new secure client object using the default socket number.
uint32_t getNISTTime(void) -> uint32_t override: Get the time from NIST via TIME protocol (rfc868).
bool getModemSignalQuality(int16_t& rssi, int16_t& percent) -> bool override: Query the modem for the current signal quality and write the results to the supplied non-constant references.
bool getModemBatteryStats(int8_t& chargeState, int8_t& percent, int16_t& milliVolts) -> bool override: Query the modem for battery information and write the values to the supplied non-constant references.
float getModemChipTemperature(void) -> float override: Get the current temperature provided by the modem module.

Public variables

TinyGsm gsmModem: Public reference to the TinyGSM modem.

Protected functions

bool isInternetAvailable(void) -> bool override: Check whether there is an active internet connection available.
bool modemSleepFxn(void) -> bool override: 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) -> bool override: 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) -> bool override: 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) -> bool override: Check if the modem was awake using all possible means.

Function documentation

SIMComSIM7080::SIMComSIM7080(Stream* modemStream, int8_t powerPin, int8_t statusPin, int8_t modemSleepRqPin, const char* apn)

Construct a new SIMComSIM7080 object The constructor initializes all of the provided member variables, constructs a loggerModem parent class with the appropriate timing for the module, calls the constructor for a TinyGSM modem on the provided modemStream, and creates a TinyGSM Client linked to the modem.

Parameters
modemStream	The Arduino stream instance for serial communication.
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.
modemSleepRqPin	The digital pin number of a pin on the mcu used to request the modem enter its lowest possible power state.
apn	The Access Point Name (APN) for the SIM card.

Should be set to a negative number if the modem should be continuously powered or the power cannot be controlled by the MCU. Should be set to a negative number if the modem status pin cannot be read. This is the pin labeled STATUS in SIMCom's integration guide. 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. This is the pin labeled PWRKEY in SIMCom's integration guide.

bool SIMComSIM7080::modemWake(void) override

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.

Set-up pin modes. Because the modem calls wake BEFORE the first setup, we must set the pin modes in the wake function.

Run the specific modemWakeFxn().

Check that the modem is responding to AT commands.

Hard reset is there's no AT response.

Exit if we can't hard reset.

Clean any junk out of the modem buffer.

Re-run the modem init, or setup if necessary. This will turn off echo, which often turns itself back on after a reset/power loss. This also checks the SIM card state.

If we run setup, take success value entirely from that.

bool SIMComSIM7080::connectInternet(uint32_t maxConnectionTime = 50000L) override

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 was unresponsive, unable to register with the cellular network, or unable to establish a EPS or GPRS connection.

Power up, if necessary

Check if the modem was awake, wake it if not

wait

Client* SIMComSIM7080::createClient() override

Create a new client object using the default socket number.

Returns	Client* A new client object

void SIMComSIM7080::deleteClient(Client* client) virtual

Attempts to delete a created TinyGsmClient object. We need to do this to close memory leaks from the create client because we can't delete the created client from a pointer to the parent because the Arduino core's client class doesn't have a virtual destructor.

Parameters
client	The client to delete

Client* SIMComSIM7080::createSecureClient() override

Create a new secure client object using the default socket number.

Returns	Client* A new secure client object

void SIMComSIM7080::deleteSecureClient(Client* client) virtual

Attempts to delete a created TinyGsmSecureClient object. We need to do this to close memory leaks from the create client because we can't delete the created client from a pointer to the parent because the Arduino core's client class doesn't have a virtual destructor.

Parameters
client	The client to delete

Client* SIMComSIM7080::createSecureClient(SSLAuthMode sslAuthMode, SSLVersion sslVersion = SSLVersion::TLS1_2, const char* CAcertName = nullptr, const char* clientCertName = nullptr, const char* clientKeyName = nullptr) override

Create a new secure client object using the default socket number.

Parameters
sslAuthMode	The SSL authentication mode to use
sslVersion	The SSL version to use
CAcertName	The name of the CA certificate to use
clientCertName	The name of the client certificate to use
clientKeyName	The name of the client key to use
Returns	Client* A new secure client object

Client* SIMComSIM7080::createSecureClient(const char* pskIdent, const char* psKey, SSLVersion sslVersion = SSLVersion::TLS1_2) override

Create a new secure client object using the default socket number.

Parameters
pskIdent	The pre-shared key identity
psKey	The pre-shared key
sslVersion	The SSL version to use
Returns	Client* A new secure client object

Client* SIMComSIM7080::createSecureClient(const char* pskTableName, SSLVersion sslVersion = SSLVersion::TLS1_2) override

Create a new secure client object using the default socket number.

Parameters
pskTableName	The pre-shared key table name - for modems that require PSK's in a "table" format
sslVersion	The SSL version to use
Returns	Client* A new secure client object

uint32_t SIMComSIM7080::getNISTTime(void) override

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.

Check for and bail if not connected to the internet.

Try up to 12 times to get a timestamp from NIST.

Make TCP connection.

Wait up to 5 seconds for a response.

bool SIMComSIM7080::getModemSignalQuality(int16_t& rssi, int16_t& percent) override

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 SIMComSIM7080::getModemBatteryStats(int8_t& chargeState, int8_t& percent, int16_t& milliVolts) override

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 SIMComSIM7080::getModemChipTemperature(void) override

Get the current temperature provided by the modem module.

Returns	float The temperature in degrees Celsius

bool SIMComSIM7080::isInternetAvailable(void) override protected

Check whether there is an active internet connection available.

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

bool SIMComSIM7080::modemSleepFxn(void) override 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 successfully.

bool SIMComSIM7080::modemWakeFxn(void) override 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 successfully - does NOT indicate that the modem is now responsive.

bool SIMComSIM7080::extraModemSetup(void) override 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.

TODO: Settings applied via CACFG are meant for transparent transmission mode, not the "normal" transmission mode used by TinyGSM. This may not be necessary (or even functional).

bool SIMComSIM7080::isModemAwake(void) override 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 accidentally pulse an already on modem to off.

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

If the wake up is one where a pin is held (0 wake time) and * that pin is defined, then we're going to check the level of the * held pin as the indication of whether attempts were made to * wake the modem before entering the setup function.

If there's a status pin, use that to determine if the modem is * awake.

If we can't determine status by pin level, try checking if the * modem responds to AT commands.