SparkFun_Swarm_Satellite_Arduino_Library
|
#include <SparkFun_Swarm_Satellite_Arduino_Library.h>
Public Member Functions | |
SWARM_M138 (void) | |
Class to communicate with the Swarm M138 satellite modem. | |
bool | begin (HardwareSerial &hardSerial) |
Begin communication with the Swarm M138 modem. More... | |
bool | begin (byte deviceAddress=SFE_QWIIC_SWARM_DEFAULT_I2C_ADDRESS, TwoWire &wirePort=Wire) |
Begin communication with the Swarm M138 modem. More... | |
void | enableDebugging (Stream &debugPort=Serial) |
Enable debug messages on the chosen serial port Calling this function with nothing sets the debug port to Serial You can also call it with other streams like Serial1, SerialUSB, etc. More... | |
void | disableDebugging (void) |
Disable debug messages. | |
Swarm_M138_Error_e | getConfigurationSettings (char *settings) |
Read the modem device ID and name using the $CS message. More... | |
Swarm_M138_Error_e | getDeviceID (uint32_t *id) |
Read the modem device ID using the $CS message. More... | |
bool | isConnected (void) |
Check if the modem is connected and responding by getting the configuration settings. More... | |
Swarm_M138_Error_e | getDateTime (Swarm_M138_DateTimeData_t *dateTime) |
Get the most recent $DT message. More... | |
Swarm_M138_Error_e | getDateTimeRate (uint32_t *rate) |
Query the current $DT rate. More... | |
Swarm_M138_Error_e | setDateTimeRate (uint32_t rate) |
Set the rate of $DT Date/Time messages. More... | |
Swarm_M138_Error_e | getFirmwareVersion (char *version) |
Read the modem firmware version using the $FV message. More... | |
Swarm_M138_Error_e | getGpsJammingIndication (Swarm_M138_GPS_Jamming_Indication_t *jamming) |
Get the most recent $GJ message. More... | |
Swarm_M138_Error_e | getGpsJammingIndicationRate (uint32_t *rate) |
Query the current $GJ rate. More... | |
Swarm_M138_Error_e | setGpsJammingIndicationRate (uint32_t rate) |
Set the rate of $GJ jamming indication messages. More... | |
Swarm_M138_Error_e | getGeospatialInfo (Swarm_M138_GeospatialData_t *info) |
Get the most recent $GN message. More... | |
Swarm_M138_Error_e | getGeospatialInfoRate (uint32_t *rate) |
Query the current $GN rate. More... | |
Swarm_M138_Error_e | setGeospatialInfoRate (uint32_t rate) |
Set the rate of $GN geospatial information messages. More... | |
Swarm_M138_Error_e | getGPIO1Mode (Swarm_M138_GPIO1_Mode_e *mode) |
Get the current GPIO1 pin mode using the $GP message. More... | |
Swarm_M138_Error_e | setGPIO1Mode (Swarm_M138_GPIO1_Mode_e mode) |
Get the current GPIO1 pin mode using the $GP message. More... | |
Swarm_M138_Error_e | readGPIO1voltage (float *voltage) |
Read the voltage on GPIO1 (Modes 1 and 2 only) More... | |
Swarm_M138_Error_e | getGpsFixQuality (Swarm_M138_GPS_Fix_Quality_t *fixQuality) |
Get the most recent $GS message. More... | |
Swarm_M138_Error_e | getGpsFixQualityRate (uint32_t *rate) |
Query the current $GS rate. More... | |
Swarm_M138_Error_e | setGpsFixQualityRate (uint32_t rate) |
Set the rate of $GS GPS fix quality messages. More... | |
Swarm_M138_Error_e | powerOff (void) |
The Modem enters a low power mode until power is completely removed and restored. More... | |
Swarm_M138_Error_e | getPowerStatus (Swarm_M138_Power_Status_t *powerStatus) |
Get the most recent $PW message. More... | |
Swarm_M138_Error_e | getPowerStatusRate (uint32_t *rate) |
Query the current $PW rate. More... | |
Swarm_M138_Error_e | setPowerStatusRate (uint32_t rate) |
Set the rate of $PW power status messages. More... | |
Swarm_M138_Error_e | getTemperature (float *temperature) |
Get the modem temperature. More... | |
Swarm_M138_Error_e | getCPUvoltage (float *voltage) |
Get the modem CPU voltage. More... | |
Swarm_M138_Error_e | restartDevice (bool deletedb=false) |
Restart the modem. More... | |
Swarm_M138_Error_e | getReceiveTest (Swarm_M138_Receive_Test_t *rxTest) |
Get the most recent $RT message. More... | |
Swarm_M138_Error_e | getReceiveTestRate (uint32_t *rate) |
Query the current $RT rate. More... | |
Swarm_M138_Error_e | setReceiveTestRate (uint32_t rate) |
Set the rate of $RT receive test messages. More... | |
Swarm_M138_Error_e | sleepMode (uint32_t seconds) |
Instruct the modem to sleep for this many seconds. More... | |
Swarm_M138_Error_e | sleepMode (Swarm_M138_DateTimeData_t sleepUntil, bool dateAndTime=true) |
Instruct the modem to sleep until this date and time. More... | |
Swarm_M138_Error_e | getRxMessageCount (uint16_t *count, bool unread=false) |
Return the count of all messages (default) or unread messages (unread = true) More... | |
Swarm_M138_Error_e | deleteRxMessage (uint64_t msg_id) |
Delete the RX message with the specified ID. More... | |
Swarm_M138_Error_e | deleteAllRxMessages (bool read=true) |
Delete all read RX messages (default) or all messages (read = false) More... | |
Swarm_M138_Error_e | markRxMessage (uint64_t msg_id) |
Mark the RX message with the specified ID as read. More... | |
Swarm_M138_Error_e | markAllRxMessages (void) |
Mark all RX messages as read. More... | |
Swarm_M138_Error_e | getMessageNotifications (bool *enabled) |
Query if message notifications are enabled. More... | |
Swarm_M138_Error_e | setMessageNotifications (bool enable) |
Enable / disable receive message notifications. More... | |
Swarm_M138_Error_e | listMessage (uint64_t msg_id, char *asciiHex, size_t len, uint32_t *epoch=NULL, uint16_t *appID=NULL) |
List the message with the specified ID. Does not change message state. More... | |
Swarm_M138_Error_e | readMessage (uint64_t msg_id, char *asciiHex, size_t len, uint32_t *epoch=NULL, uint16_t *appID=NULL) |
Read the message with the specified ID. More... | |
Swarm_M138_Error_e | readOldestMessage (char *asciiHex, size_t len, uint64_t *msg_id, uint32_t *epoch=NULL, uint16_t *appID=NULL) |
Read the oldest unread message. More... | |
Swarm_M138_Error_e | readNewestMessage (char *asciiHex, size_t len, uint64_t *msg_id, uint32_t *epoch=NULL, uint16_t *appID=NULL) |
Read the newest unread message. More... | |
Swarm_M138_Error_e | getUnsentMessageCount (uint16_t *count) |
Return the count of all unsent messages. More... | |
Swarm_M138_Error_e | deleteTxMessage (uint64_t msg_id) |
Delete the TX message with the specified ID. More... | |
Swarm_M138_Error_e | deleteAllTxMessages (void) |
Delete all unsent messages. More... | |
Swarm_M138_Error_e | listTxMessage (uint64_t msg_id, char *asciiHex, size_t len, uint32_t *epoch=NULL, uint16_t *appID=NULL) |
List the unsent message with the specified ID. More... | |
Swarm_M138_Error_e | transmitText (const char *data, uint64_t *msg_id) |
List the IDs of all the unsent messages. More... | |
Swarm_M138_Error_e | transmitText (const char *data, uint64_t *msg_id, uint16_t appID) |
Queue a printable text message for transmission with an appID. More... | |
Swarm_M138_Error_e | transmitTextHold (const char *data, uint64_t *msg_id, uint32_t hold) |
Queue a printable text message for transmission with a hold duration. More... | |
Swarm_M138_Error_e | transmitTextHold (const char *data, uint64_t *msg_id, uint32_t hold, uint16_t appID) |
Queue a printable text message for transmission with a hold duration and an appID. More... | |
Swarm_M138_Error_e | transmitTextExpire (const char *data, uint64_t *msg_id, uint32_t epoch) |
Queue a printable text message for transmission with an expiry time (epoch) More... | |
Swarm_M138_Error_e | transmitTextExpire (const char *data, uint64_t *msg_id, uint32_t epoch, uint16_t appID) |
Queue a printable text message for transmission with an expiry time (epoch) and an appID. More... | |
Swarm_M138_Error_e | transmitBinary (const uint8_t *data, size_t len, uint64_t *msg_id) |
Queue a binary message for transmission. More... | |
Swarm_M138_Error_e | transmitBinary (const uint8_t *data, size_t len, uint64_t *msg_id, uint16_t appID) |
Queue a binary message for transmission with an appID. More... | |
Swarm_M138_Error_e | transmitBinaryHold (const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t hold) |
Queue a binary message for transmission with a hold duration. More... | |
Swarm_M138_Error_e | transmitBinaryHold (const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t hold, uint16_t appID) |
Queue a binary message for transmission with a hold duration and an appID. More... | |
Swarm_M138_Error_e | transmitBinaryExpire (const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t epoch) |
Queue a binary message for transmission with an expiry time (epoch) More... | |
Swarm_M138_Error_e | transmitBinaryExpire (const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t epoch, uint16_t appID) |
Queue a binary message for transmission with an expiry time (epoch) and an appID. More... | |
bool | checkUnsolicitedMsg (void) |
Check for the arrival of new serial data. Parse it. Process any unsolicited messages. Call the callback(s) - if enabled. More... | |
void | setDateTimeCallback (void(*swarmDateTimeCallback)(const Swarm_M138_DateTimeData_t *dateTime)) |
Set up the callback for the $DT Date Time message. More... | |
void | setGpsJammingCallback (void(*swarmGpsJammingCallback)(const Swarm_M138_GPS_Jamming_Indication_t *jamming)) |
Set up the callback for the $GJ jamming indication message. More... | |
void | setGeospatialInfoCallback (void(*swarmGeospatialCallback)(const Swarm_M138_GeospatialData_t *info)) |
Set up the callback for the $GN geospatial information message. More... | |
void | setGpsFixQualityCallback (void(*swarmGpsFixQualityCallback)(const Swarm_M138_GPS_Fix_Quality_t *fixQuality)) |
Set up the callback for the $GS GPS fix quality message. More... | |
void | setPowerStatusCallback (void(*swarmPowerStatusCallback)(const Swarm_M138_Power_Status_t *status)) |
Set up the callback for the $PW power status message. More... | |
void | setReceiveMessageCallback (void(*swarmReceiveMessageCallback)(const uint16_t *appID, const int16_t *rssi, const int16_t *snr, const int16_t *fdev, const char *asciiHex)) |
Set up the callback for the $RD receive data message. More... | |
void | setReceiveTestCallback (void(*swarmReceiveTestCallback)(const Swarm_M138_Receive_Test_t *rxTest)) |
Set up the callback for the $RT receive test message. More... | |
void | setSleepWakeCallback (void(*swarmSleepWakeCallback)(Swarm_M138_Wake_Cause_e cause)) |
Set up the callback for the $SL WAKE sleep mode messages. More... | |
void | setModemStatusCallback (void(*swarmModemStatusCallback)(Swarm_M138_Modem_Status_e status, const char *data)) |
Set up the callback for the $M138 modem status messages. More... | |
void | setTransmitDataCallback (void(*swarmTransmitDataCallback)(const int16_t *rssi_sat, const int16_t *snr, const int16_t *fdev, const uint64_t *msg_id)) |
Set up the callback for $TD SENT messages. More... | |
const char * | modemStatusString (Swarm_M138_Modem_Status_e status) |
Convert modem status enum into printable text. More... | |
const char * | modemErrorString (Swarm_M138_Error_e error) |
Convert modem error enum into printable text. More... | |
const char * | commandErrorString (const char *ERR) |
Convert command error into a printable description. More... | |
Public Attributes | |
char * | commandError |
Communication interface for the Swarm M138 satellite modem.
bool SWARM_M138::begin | ( | byte | deviceAddress = SFE_QWIIC_SWARM_DEFAULT_I2C_ADDRESS , |
TwoWire & | wirePort = Wire |
||
) |
Begin communication with the Swarm M138 modem.
deviceAddress | The I2C address of the Qwiic Swarm. Default is SFE_QWIIC_SWARM_DEFAULT_I2C_ADDRESS 0x52. |
wirePort | The TwoWire (I2C) port used to communicate with the Power Board. Default is Wire. |
bool SWARM_M138::begin | ( | HardwareSerial & | hardSerial | ) |
Begin communication with the Swarm M138 modem.
Begin – initialize module and ensure it's connected
hardSerial | The hardware serial port to be used to communicate with the modem |
bool SWARM_M138::checkUnsolicitedMsg | ( | void | ) |
Check for the arrival of new serial data. Parse it. Process any unsolicited messages. Call the callback(s) - if enabled.
Process unsolicited messages from the modem. Call the callbacks if required
const char * SWARM_M138::commandErrorString | ( | const char * | ERR | ) |
Convert command error into a printable description.
ERR | The command error as const char * |
Swarm_M138_Error_e SWARM_M138::deleteAllRxMessages | ( | bool | read = true | ) |
Delete all read RX messages (default) or all messages (read = false)
read | If true (default): deletes the read messages If false: deletes all messages |
Swarm_M138_Error_e SWARM_M138::deleteAllTxMessages | ( | void | ) |
Delete all unsent messages.
Swarm_M138_Error_e SWARM_M138::deleteRxMessage | ( | uint64_t | msg_id | ) |
Delete the RX message with the specified ID.
msg_id | The ID of the message to be deleted |
Swarm_M138_Error_e SWARM_M138::deleteTxMessage | ( | uint64_t | msg_id | ) |
Delete the TX message with the specified ID.
msg_id | The ID of the message to be deleted |
void SWARM_M138::enableDebugging | ( | Stream & | debugPort = Serial | ) |
Enable debug messages on the chosen serial port Calling this function with nothing sets the debug port to Serial You can also call it with other streams like Serial1, SerialUSB, etc.
Debug prints
debugPort | The serial port to be used for the debug messages |
Swarm_M138_Error_e SWARM_M138::getConfigurationSettings | ( | char * | settings | ) |
Read the modem device ID and name using the $CS message.
Commands Configuration Settings
settings | A pointer to where the settings will be stored It is recommended that the user allocates at least SWARM_M138_MEM_ALLOC_CS bytes to store the settings |
Swarm_M138_Error_e SWARM_M138::getCPUvoltage | ( | float * | voltage | ) |
Get the modem CPU voltage.
voltage | A pointer to a float which will hold the result |
Swarm_M138_Error_e SWARM_M138::getDateTime | ( | Swarm_M138_DateTimeData_t * | dateTime | ) |
Get the most recent $DT message.
Date/Time
dateTime | A pointer to a Swarm_M138_DateTimeData_t struct which will hold the result |
Swarm_M138_Error_e SWARM_M138::getDateTimeRate | ( | uint32_t * | rate | ) |
Query the current $DT rate.
rate | A pointer to a uint32_t which will hold the result |
Swarm_M138_Error_e SWARM_M138::getDeviceID | ( | uint32_t * | id | ) |
Read the modem device ID using the $CS message.
id | The address of the uint32_t where the ID will be stored |
Swarm_M138_Error_e SWARM_M138::getFirmwareVersion | ( | char * | version | ) |
Read the modem firmware version using the $FV message.
Firmware Version
settings | A pointer to where the settings will be stored It is recommended that the user allocates at least SWARM_M138_MEM_ALLOC_FV bytes to store the settings |
Swarm_M138_Error_e SWARM_M138::getGeospatialInfo | ( | Swarm_M138_GeospatialData_t * | info | ) |
Get the most recent $GN message.
Geospatial information
info | A pointer to a Swarm_M138_GeospatialData_t struct which will hold the result |
Swarm_M138_Error_e SWARM_M138::getGeospatialInfoRate | ( | uint32_t * | rate | ) |
Query the current $GN rate.
rate | A pointer to a uint32_t which will hold the result |
Swarm_M138_Error_e SWARM_M138::getGPIO1Mode | ( | Swarm_M138_GPIO1_Mode_e * | mode | ) |
Get the current GPIO1 pin mode using the $GP message.
GPIO1 Control
mode | A pointer to a Swarm_M138_GPIO1_Mode_e enum where the mode will be stored |
Swarm_M138_Error_e SWARM_M138::getGpsFixQuality | ( | Swarm_M138_GPS_Fix_Quality_t * | fixQuality | ) |
Get the most recent $GS message.
GPS fix quality
fixQuality | A pointer to a Swarm_M138_GPS_Fix_Quality_t struct which will hold the result |
Swarm_M138_Error_e SWARM_M138::getGpsFixQualityRate | ( | uint32_t * | rate | ) |
Query the current $GS rate.
rate | A pointer to a uint32_t which will hold the result |
Swarm_M138_Error_e SWARM_M138::getGpsJammingIndication | ( | Swarm_M138_GPS_Jamming_Indication_t * | jamming | ) |
Get the most recent $GJ message.
GPS Jamming/Spoofing Indication
dateTime | A pointer to a Swarm_M138_DateTimeData_t struct which will hold the result |
Swarm_M138_Error_e SWARM_M138::getGpsJammingIndicationRate | ( | uint32_t * | rate | ) |
Query the current $GJ rate.
rate | A pointer to a uint32_t which will hold the result |
Swarm_M138_Error_e SWARM_M138::getMessageNotifications | ( | bool * | enabled | ) |
Query if message notifications are enabled.
enabled | A pointer to a bool to hold the status |
Swarm_M138_Error_e SWARM_M138::getPowerStatus | ( | Swarm_M138_Power_Status_t * | powerStatus | ) |
Get the most recent $PW message.
Power Status
powerStatus | A pointer to a Swarm_M138_Power_Status_t struct which will hold the result |
Swarm_M138_Error_e SWARM_M138::getPowerStatusRate | ( | uint32_t * | rate | ) |
Query the current $PW rate.
rate | A pointer to a uint32_t which will hold the result |
Swarm_M138_Error_e SWARM_M138::getReceiveTest | ( | Swarm_M138_Receive_Test_t * | rxTest | ) |
Get the most recent $RT message.
Receive Test
rxTest | A pointer to a Swarm_M138_Receive_Test_t struct which will hold the result |
Swarm_M138_Error_e SWARM_M138::getReceiveTestRate | ( | uint32_t * | rate | ) |
Query the current $RT rate.
rate | A pointer to a uint32_t which will hold the result |
Swarm_M138_Error_e SWARM_M138::getRxMessageCount | ( | uint16_t * | count, |
bool | unread = false |
||
) |
Return the count of all messages (default) or unread messages (unread = true)
Messages Received Management
count | A pointer to a uint16_t which will hold the message count |
unread | If false (default): returns the count of all messages If true: returns the count of the unread messages |
Swarm_M138_Error_e SWARM_M138::getTemperature | ( | float * | temperature | ) |
Get the modem temperature.
temperature | A pointer to a float which will hold the result |
Swarm_M138_Error_e SWARM_M138::getUnsentMessageCount | ( | uint16_t * | count | ) |
Return the count of all unsent messages.
Messages To Transmit Management
count | A pointer to a uint16_t which will hold the message count |
bool SWARM_M138::isConnected | ( | void | ) |
Check if the modem is connected and responding by getting the configuration settings.
Swarm_M138_Error_e SWARM_M138::listMessage | ( | uint64_t | msg_id, |
char * | asciiHex, | ||
size_t | len, | ||
uint32_t * | epoch = NULL , |
||
uint16_t * | appID = NULL |
||
) |
List the message with the specified ID. Does not change message state.
msg_id | The ID of the message to be listed |
asciiHex | A pointer to a char array to hold the message |
len | The maximum message length which asciiHex can hold |
epoch | Optional: a pointer to a uint32_t to hold the epoch at which the modem received the message |
appID | Optional: a pointer to a uint16_t to hold the message appID if there is one |
Swarm_M138_Error_e SWARM_M138::listTxMessage | ( | uint64_t | msg_id, |
char * | asciiHex, | ||
size_t | len, | ||
uint32_t * | epoch = NULL , |
||
uint16_t * | appID = NULL |
||
) |
List the unsent message with the specified ID.
msg_id | The ID of the message to be listed |
asciiHex | A pointer to a char array to hold the message |
len | The maximum message length which asciiHex can hold |
epoch | Optional: a pointer to a uint32_t to hold the epoch at which the modem received the message |
appID | Optional: a pointer to a uint16_t to hold the message appID if there is one |
Swarm_M138_Error_e SWARM_M138::markAllRxMessages | ( | void | ) |
Mark all RX messages as read.
Swarm_M138_Error_e SWARM_M138::markRxMessage | ( | uint64_t | msg_id | ) |
Mark the RX message with the specified ID as read.
msg_id | The ID of the message to be marked as read |
const char * SWARM_M138::modemErrorString | ( | Swarm_M138_Error_e | error | ) |
Convert modem error enum into printable text.
error | The modem error (enumerated) |
const char * SWARM_M138::modemStatusString | ( | Swarm_M138_Modem_Status_e | status | ) |
Convert modem status enum into printable text.
Convert modem status enum etc. into printable text
status | The modem status (enumerated) |
Swarm_M138_Error_e SWARM_M138::powerOff | ( | void | ) |
The Modem enters a low power mode until power is completely removed and restored.
Power Off
Swarm_M138_Error_e SWARM_M138::readGPIO1voltage | ( | float * | voltage | ) |
Read the voltage on GPIO1 (Modes 1 and 2 only)
voltage | A pointer to a float where the voltage will be stored. Mode 1 (ADC) returns a true voltage. Mode 2 (INPUT) returns 0.00 for low or 3.30 for high. |
Swarm_M138_Error_e SWARM_M138::readMessage | ( | uint64_t | msg_id, |
char * | asciiHex, | ||
size_t | len, | ||
uint32_t * | epoch = NULL , |
||
uint16_t * | appID = NULL |
||
) |
Read the message with the specified ID.
msg_id | The ID of the message to be read |
asciiHex | A pointer to a char array to hold the message |
len | The maximum message length which asciiHex can hold |
epoch | Optional: a pointer to a uint32_t to hold the epoch at which the modem received the message |
appID | Optional: a pointer to a uint16_t to hold the message appID if there is one |
Swarm_M138_Error_e SWARM_M138::readNewestMessage | ( | char * | asciiHex, |
size_t | len, | ||
uint64_t * | msg_id, | ||
uint32_t * | epoch = NULL , |
||
uint16_t * | appID = NULL |
||
) |
Read the newest unread message.
asciiHex | A pointer to a char array to hold the message |
len | The maximum message length which asciiHex can hold |
msg_id | A pointer to a uint64_t to hold the message ID |
epoch | Optional: a pointer to a uint32_t to hold the epoch at which the modem received the message |
appID | Optional: a pointer to a uint16_t to hold the message appID if there is one |
Swarm_M138_Error_e SWARM_M138::readOldestMessage | ( | char * | asciiHex, |
size_t | len, | ||
uint64_t * | msg_id, | ||
uint32_t * | epoch = NULL , |
||
uint16_t * | appID = NULL |
||
) |
Read the oldest unread message.
asciiHex | A pointer to a char array to hold the message |
len | The maximum message length which asciiHex can hold |
msg_id | A pointer to a uint64_t to hold the message ID |
epoch | Optional: a pointer to a uint32_t to hold the epoch at which the modem received the message |
appID | Optional: a pointer to a uint16_t to hold the message appID if there is one |
Swarm_M138_Error_e SWARM_M138::restartDevice | ( | bool | deletedb = false | ) |
Restart the modem.
Restart Device
deletedb | Bool: If true, the database will be cleared. Default is false. |
void SWARM_M138::setDateTimeCallback | ( | void(*)(const Swarm_M138_DateTimeData_t *dateTime) | swarmDateTimeCallback | ) |
Set up the callback for the $DT Date Time message.
Callbacks (called by checkUnsolicitedMsg)
swarmDateTimeCallback | The address of the function to be called when an unsolicited $DT message arrives |
Swarm_M138_Error_e SWARM_M138::setDateTimeRate | ( | uint32_t | rate | ) |
Set the rate of $DT Date/Time messages.
rate | The interval between messages 0 == Disable. Max is 2147483647 (2^31 - 1) |
void SWARM_M138::setGeospatialInfoCallback | ( | void(*)(const Swarm_M138_GeospatialData_t *info) | swarmGeospatialCallback | ) |
Set up the callback for the $GN geospatial information message.
swarmGeospatialCallback | The address of the function to be called when an unsolicited $GN message arrives |
Swarm_M138_Error_e SWARM_M138::setGeospatialInfoRate | ( | uint32_t | rate | ) |
Set the rate of $GN geospatial information messages.
rate | The interval between messages 0 == Disable. Max is 2147483647 (2^31 - 1) |
Swarm_M138_Error_e SWARM_M138::setGPIO1Mode | ( | Swarm_M138_GPIO1_Mode_e | mode | ) |
Get the current GPIO1 pin mode using the $GP message.
mode | A pointer to a Swarm_M138_GPIO1_Mode_e enum where the mode will be stored |
void SWARM_M138::setGpsFixQualityCallback | ( | void(*)(const Swarm_M138_GPS_Fix_Quality_t *fixQuality) | swarmGpsFixQualityCallback | ) |
Set up the callback for the $GS GPS fix quality message.
swarmGpsFixQualityCallback | The address of the function to be called when an unsolicited $GS message arrives |
Swarm_M138_Error_e SWARM_M138::setGpsFixQualityRate | ( | uint32_t | rate | ) |
Set the rate of $GS GPS fix quality messages.
rate | The interval between messages 0 == Disable. Max is 2147483647 (2^31 - 1) |
void SWARM_M138::setGpsJammingCallback | ( | void(*)(const Swarm_M138_GPS_Jamming_Indication_t *jamming) | swarmGpsJammingCallback | ) |
Set up the callback for the $GJ jamming indication message.
swarmGpsJammingCallback | The address of the function to be called when an unsolicited $GJ message arrives |
Swarm_M138_Error_e SWARM_M138::setGpsJammingIndicationRate | ( | uint32_t | rate | ) |
Set the rate of $GJ jamming indication messages.
rate | The interval between messages 0 == Disable. Max is 2147483647 (2^31 - 1) |
Swarm_M138_Error_e SWARM_M138::setMessageNotifications | ( | bool | enable | ) |
Enable / disable receive message notifications.
enable | If true: enable $RD message notifications If false: disable $RD message notifications |
void SWARM_M138::setModemStatusCallback | ( | void(*)(Swarm_M138_Modem_Status_e status, const char *data) | swarmModemStatusCallback | ) |
Set up the callback for the $M138 modem status messages.
swarmModemStatusCallback | The address of the function to be called when an unsolicited $M138 message arrives |
void SWARM_M138::setPowerStatusCallback | ( | void(*)(const Swarm_M138_Power_Status_t *status) | swarmPowerStatusCallback | ) |
Set up the callback for the $PW power status message.
swarmPowerStatusCallback | The address of the function to be called when an unsolicited $PW message arrives |
Swarm_M138_Error_e SWARM_M138::setPowerStatusRate | ( | uint32_t | rate | ) |
Set the rate of $PW power status messages.
rate | The interval between messages 0 == Disable. Max is 2147483647 (2^31 - 1) |
void SWARM_M138::setReceiveMessageCallback | ( | void(*)(const uint16_t *appID, const int16_t *rssi, const int16_t *snr, const int16_t *fdev, const char *asciiHex) | swarmReceiveMessageCallback | ) |
Set up the callback for the $RD receive data message.
swarmReceiveMessageCallback | The address of the function to be called when an unsolicited $RD message arrives |
void SWARM_M138::setReceiveTestCallback | ( | void(*)(const Swarm_M138_Receive_Test_t *rxTest) | swarmReceiveTestCallback | ) |
Set up the callback for the $RT receive test message.
swarmReceiveTestCallback | The address of the function to be called when an unsolicited $RT message arrives |
Swarm_M138_Error_e SWARM_M138::setReceiveTestRate | ( | uint32_t | rate | ) |
Set the rate of $RT receive test messages.
rate | The interval between messages 0 == Disable. Max is 2147483647 (2^31 - 1) |
void SWARM_M138::setSleepWakeCallback | ( | void(*)(Swarm_M138_Wake_Cause_e cause) | swarmSleepWakeCallback | ) |
Set up the callback for the $SL WAKE sleep mode messages.
swarmSleepWakeCallback | The address of the function to be called when an unsolicited $SL WAKE message arrives |
void SWARM_M138::setTransmitDataCallback | ( | void(*)(const int16_t *rssi_sat, const int16_t *snr, const int16_t *fdev, const uint64_t *msg_id) | swarmTransmitDataCallback | ) |
Set up the callback for $TD SENT messages.
swarmTransmitDataCallback | The address of the function to be called when an unsolicited $TD SENT message arrives |
Swarm_M138_Error_e SWARM_M138::sleepMode | ( | Swarm_M138_DateTimeData_t | sleepUntil, |
bool | dateAndTime = true |
||
) |
Instruct the modem to sleep until this date and time.
sleepUntil | A Swarm_M138_DateTimeData_t struct containing the date and time the modem should sleep until |
dateAndTime | If true (default), the modem will sleep until the specified date and time If false, the modem will sleep until the specified time |
Swarm_M138_Error_e SWARM_M138::sleepMode | ( | uint32_t | seconds | ) |
Instruct the modem to sleep for this many seconds.
Sleep Mode
seconds | The sleep duration in seconds |
Swarm_M138_Error_e SWARM_M138::transmitBinary | ( | const uint8_t * | data, |
size_t | len, | ||
uint64_t * | msg_id | ||
) |
Queue a binary message for transmission.
data | The binary message |
len | The length of the binary message in bytes |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
Swarm_M138_Error_e SWARM_M138::transmitBinary | ( | const uint8_t * | data, |
size_t | len, | ||
uint64_t * | msg_id, | ||
uint16_t | appID | ||
) |
Queue a binary message for transmission with an appID.
data | The binary message |
len | The length of the binary message in bytes |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
appID | The application ID: 0 to 64999 |
Swarm_M138_Error_e SWARM_M138::transmitBinaryExpire | ( | const uint8_t * | data, |
size_t | len, | ||
uint64_t * | msg_id, | ||
uint32_t | epoch | ||
) |
Queue a binary message for transmission with an expiry time (epoch)
data | The binary message |
len | The length of the binary message in bytes |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
epoch | The second date after which the message will be expired if it has not been sent. 1577836800 to 2147483647 (2020-01-01 00:00:00 to 2038-01-19 03:14:07) |
Swarm_M138_Error_e SWARM_M138::transmitBinaryExpire | ( | const uint8_t * | data, |
size_t | len, | ||
uint64_t * | msg_id, | ||
uint32_t | epoch, | ||
uint16_t | appID | ||
) |
Queue a binary message for transmission with an expiry time (epoch) and an appID.
data | The binary message |
len | The length of the binary message in bytes |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
epoch | The second date after which the message will be expired if it has not been sent. 1577836800 to 2147483647 (2020-01-01 00:00:00 to 2038-01-19 03:14:07) |
appID | The application ID: 0 to 64999 |
Swarm_M138_Error_e SWARM_M138::transmitBinaryHold | ( | const uint8_t * | data, |
size_t | len, | ||
uint64_t * | msg_id, | ||
uint32_t | hold | ||
) |
Queue a binary message for transmission with a hold duration.
data | The binary message |
len | The length of the binary message in bytes |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
hold | The hold duration in seconds: 60 to 34819200 (13 months) The message expires if it has not been transmitted within the hold duration The default hold duration is 172800 seconds (48 hours) |
Swarm_M138_Error_e SWARM_M138::transmitBinaryHold | ( | const uint8_t * | data, |
size_t | len, | ||
uint64_t * | msg_id, | ||
uint32_t | hold, | ||
uint16_t | appID | ||
) |
Queue a binary message for transmission with a hold duration and an appID.
data | The binary message |
len | The length of the binary message in bytes |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
hold | The hold duration in seconds: 60 to 34819200 (13 months) The message expires if it has not been transmitted within the hold duration The default hold duration is 172800 seconds (48 hours) |
appID | The application ID: 0 to 64999 |
Swarm_M138_Error_e SWARM_M138::transmitText | ( | const char * | data, |
uint64_t * | msg_id | ||
) |
List the IDs of all the unsent messages.
Transmit Data
ids | A pointer to an array of uint64_t to hold the message IDs. Call getUnsentMessageCount first so you know how many IDs to expect and allocate storage for them. Listing all the messages through the backlog could blow up the memory, so this function reads the returned text one byte at a time and extracts the IDs from that. |
maxCount | Stop after listing the IDs for this many messages Set this to the size of your uint64_t array |
if (maxCount == 0) // Quit if maxCount is zero. It must be at least one. return (SWARM_M138_ERROR_ERROR);
// Calculate the "size of" each element in the array of uint64_t // Note: sizeof(uint64_t) doesn't seem to give the correct result? uint64_t test[2]; size_t sizeOfUint64Array = &test[1] - &test[0];
if (_printDebug == true) { _debugPort->print(F("listTxMessagesIDs: sizeOfUint64Array is ")); _debugPort->println(sizeOfUint64Array); }
err = getUnsentMessageCount(&msgTotal); // Get the message count so we know how many messages to expect if (err != SWARM_M138_ERROR_SUCCESS) return (err);
if (_printDebug == true) { _debugPort->print(F("listTxMessagesIDs: msgTotal is ")); _debugPort->println(msgTotal); }
if (msgTotal == 0) // Quit if there are no messages in the buffer return (SWARM_M138_ERROR_ERROR);
// Allocate memory for the response response = swarm_m138_alloc_char(_RxBuffSize); if (response == NULL) { return(SWARM_M138_ERROR_MEM_ALLOC); } memset(response, 0, _RxBuffSize); // Clear it
// Allocate memory for the command, asterix, checksum bytes,
and \0 command = swarm_m138_alloc_char(strlen(SWARM_M138_COMMAND_MSG_TX_MGMT) + 9); if (command == NULL) { swarm_m138_free_char(response); return (SWARM_M138_ERROR_MEM_ALLOC); } memset(command, 0, strlen(SWARM_M138_COMMAND_MSG_TX_MGMT) + 9); // Clear it sprintf(command, "%s L=U*", SWARM_M138_COMMAND_MSG_TX_MGMT); // Copy the command, add the asterix addChecksumLF(command); // Add the checksum bytes and line feed
// if (_printDebug == true) // { // _debugPort->println(F("listTxMessagesIDs: ====>")); // _debugPort->flush(); // }
sendCommand(command); // Send the command
swarm_m138_free_char(command); // Free command now - we are done with it
unsigned long startTime = millis(); bool keepGoing = true;
// Keep checking incoming chars for up to SWARM_M138_MESSAGE_ID_TIMEOUT secs total while ((millis() < (startTime + SWARM_M138_MESSAGE_ID_TIMEOUT)) && keepGoing) { int hwAvail = hwAvailable();
if (hwAvail > 0) //hwAvailable can return -1 if the serial port is NULL { rxBuff = swarm_m138_alloc_char((size_t)(hwAvail + 1)); // Allocate memory to hold the data if (rxBuff != NULL) { memset(rxBuff, 0, (size_t)(hwAvail + 1)); // Clear it int charsRead = hwReadChars(rxBuff, hwAvail); // Read the characters
// if (_printDebug == true) // _debugPort->print(rxBuff);
for (int i = 0; i < charsRead; i++) // Go through a character at a time { char cc[2]; cc[0] = rxBuff[i]; cc[1] = 0; if (strlen(response) < _RxBuffSize) // Check if response is full { strcat(response, cc); // Copy a single character into response if (cc[0] == '
') // Check if this is a newline { idStart = strstr(response, "$MT "); // Check for $MT if (idStart != NULL) { idStart = strstr(idStart, " AI="); // Check if the message has AI= at the start if (idStart != NULL) { idStart = strchr(idStart, ','); // Find the first comma if (idStart != NULL) { idStart++; idStart = strchr(idStart, ','); // Find the second comma } } else // Message does not have AI= { idStart = strstr(response, "$MT "); // Find the $MT again if (idStart != NULL) { idStart = strchr(idStart, ','); // Find the first comma } }
if (idStart != NULL) { idStart++; // Point to the first digit of the message ID idEnd = strchr(idStart, ','); // Find the second/third comma if (idEnd != NULL) { // We have (hopefully) a valid ID to extract uint64_t theID = 0; char c = *idStart; while ((c != ',') && (idStart < idEnd)) { // if (_printDebug == true) // _debugPort->write(c); theID *= 10; theID += (uint64_t)(c - '0'); idStart++; c = *idStart; } (ids + (sizeOfUint64Array * (size_t)msgCount)) = theID; // Store the extracted ID msgCount++; // Increment the count if (_printDebug == true) { _debugPort->println(); _debugPort->print(F("listTxMessagesIDs: msgCount is ")); _debugPort->println(msgCount); } if ((msgCount == msgTotal) || (msgCount == maxCount)) keepGoing = false; // Stop if we have reached msgTotal or maxCount } } } else { // We got a
but failed to find $MT. // So, let's be nice and copy whatever this message is into the backlog if possible size_t backlogLength = strlen((const char *)_swarmBacklog); size_t msgLen = strlen((const char *)response); if ((backlogLength + msgLen) < _RxBuffSize) { memcpy(&_swarmBacklog[backlogLength], response, msgLen); } } memset(response, 0, _RxBuffSize); // Clear the response } } else // Response is full... We are stuck... And we are still in the for loop... { swarm_m138_free_char(rxBuff); swarm_m138_free_char(response); return (SWARM_M138_ERROR_ERROR); } } swarm_m138_free_char(rxBuff); // Free the buffer } else // The memory allocation failed { err = SWARM_M138_ERROR_MEM_ALLOC; keepGoing = false; } } else delay(1); }
swarm_m138_free_char(response);
// if (_printDebug == true) // { // _debugPort->println(F("listTxMessagesIDs: <====")); // _debugPort->flush(); // }
return (err); }
/*
Queue a printable text message for transmission
data | The message as printable ASCII characters (0x20 to 0x7E, space to ~) |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
Swarm_M138_Error_e SWARM_M138::transmitText | ( | const char * | data, |
uint64_t * | msg_id, | ||
uint16_t | appID | ||
) |
Queue a printable text message for transmission with an appID.
data | The message as printable ASCII characters (0x20 to 0x7E, space to ~) |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
appID | The application ID: 0 to 64999 |
Swarm_M138_Error_e SWARM_M138::transmitTextExpire | ( | const char * | data, |
uint64_t * | msg_id, | ||
uint32_t | epoch | ||
) |
Queue a printable text message for transmission with an expiry time (epoch)
data | The message as printable ASCII characters (0x20 to 0x7E, space to ~) |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
epoch | The second date after which the message will be expired if it has not been sent. 1577836800 to 2147483647 (2020-01-01 00:00:00 to 2038-01-19 03:14:07) |
Swarm_M138_Error_e SWARM_M138::transmitTextExpire | ( | const char * | data, |
uint64_t * | msg_id, | ||
uint32_t | epoch, | ||
uint16_t | appID | ||
) |
Queue a printable text message for transmission with an expiry time (epoch) and an appID.
data | The message as printable ASCII characters (0x20 to 0x7E, space to ~) |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
epoch | The second date after which the message will be expired if it has not been sent. 1577836800 to 2147483647 (2020-01-01 00:00:00 to 2038-01-19 03:14:07) |
appID | The application ID: 0 to 64999 |
Swarm_M138_Error_e SWARM_M138::transmitTextHold | ( | const char * | data, |
uint64_t * | msg_id, | ||
uint32_t | hold | ||
) |
Queue a printable text message for transmission with a hold duration.
data | The message as printable ASCII characters (0x20 to 0x7E, space to ~) |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
hold | The hold duration in seconds: 60 to 34819200 (13 months) The message expires if it has not been transmitted within the hold duration The default hold duration is 172800 seconds (48 hours) |
Swarm_M138_Error_e SWARM_M138::transmitTextHold | ( | const char * | data, |
uint64_t * | msg_id, | ||
uint32_t | hold, | ||
uint16_t | appID | ||
) |
Queue a printable text message for transmission with a hold duration and an appID.
data | The message as printable ASCII characters (0x20 to 0x7E, space to ~) |
msg_id | A pointer to a uint64_t which will hold the assigned message ID |
hold | The hold duration in seconds: 60 to 34819200 (13 months) The message expires if it has not been transmitted within the hold duration The default hold duration is 172800 seconds (48 hours) |
appID | The application ID: 0 to 64999 |