SparkFun_Swarm_Satellite_Arduino_Library
SparkFun_Swarm_Satellite_Arduino_Library.h
Go to the documentation of this file.
1 
20 #ifndef SPARKFUN_SWARM_SATELLITE_ARDUINO_LIBRARY_H
21 #define SPARKFUN_SWARM_SATELLITE_ARDUINO_LIBRARY_H
22 
23 #if (ARDUINO >= 100)
24 #include "Arduino.h"
25 #else
26 #include "WProgram.h"
27 #endif
28 
29 #ifdef ARDUINO_ARCH_AVR // Arduino AVR boards (Uno, Pro Micro, etc.)
30 #define SWARM_M138_SOFTWARE_SERIAL_ENABLED // Enable software serial
31 #endif
32 
33 #ifdef ARDUINO_ARCH_SAMD // Arduino SAMD boards (SAMD21, etc.)
34 #define SWARM_M138_SOFTWARE_SERIAL_ENABLEDx // Disable software serial
35 #endif
36 
37 #ifdef ARDUINO_ARCH_APOLLO3 // Arduino Apollo boards (Artemis module, RedBoard Artemis, etc)
38 #define SWARM_M138_SOFTWARE_SERIAL_ENABLEDx // Disable software serial (no longer supported with v2 of Apollo3)
39 // Note: paulvha has provided software serial support for v2 of the Apollo3 / Artemis core.
40 // Further details are available at:
41 // https://github.com/paulvha/apollo3/tree/master/SoftwareSerial
42 #endif
43 
44 #ifdef ARDUINO_ARCH_STM32 // STM32 based boards (Disco, Nucleo, etc)
45 #define SWARM_M138_SOFTWARE_SERIAL_ENABLED // Enable software serial
46 #endif
47 
48 #ifdef ARDUINO_ARCH_ESP32 // ESP32 based boards
49 // Check to see if ESP Software Serial has been included
50 // Note: you need to #include <SoftwareSerial.h> at the very start of your script,
51 // _before_ the #include <SparkFun_u-blox_SARA-R5_Arduino_Library.h>, for this to work.
52 #if __has_include(<SoftwareSerial.h> )
53 #define SWARM_M138_SOFTWARE_SERIAL_ENABLED // Enable software serial
54 #else
55 #define SWARM_M138_SOFTWARE_SERIAL_ENABLEDx // Disable software serial
56 #endif
57 #endif
58 
59 #ifdef ARDUINO_ARCH_ESP8266 // ESP8266 based boards
60 // Check to see if ESP Software Serial has been included
61 // Note: you need to #include <SoftwareSerial.h> at the very start of your script,
62 // _before_ the #include <SparkFun_u-blox_SARA-R5_Arduino_Library.h>, for this to work.
63 #if __has_include(<SoftwareSerial.h> )
64 #define SWARM_M138_SOFTWARE_SERIAL_ENABLED // Enable software serial
65 #else
66 #define SWARM_M138_SOFTWARE_SERIAL_ENABLEDx // Disable software serial
67 #endif
68 #endif
69 
70 #ifdef SWARM_M138_SOFTWARE_SERIAL_ENABLED
71 #include <SoftwareSerial.h> // SoftwareSerial.h is guarded. It is OK to include it twice.
72 #endif
73 
74 #include <Wire.h> // Needed for I2C communication with Qwiic Swarm
75 
77 #define SWARM_M138_STANDARD_RESPONSE_TIMEOUT 1000
78 #define SWARM_M138_MESSAGE_DELETE_TIMEOUT 5000
79 #define SWARM_M138_MESSAGE_ID_TIMEOUT 5000
80 #define SWARM_M138_MESSAGE_READ_TIMEOUT 3000
81 #define SWARM_M138_MESSAGE_TRANSMIT_TIMEOUT 3000
82 
84 #define SWARM_M138_SERIAL_BAUD_RATE 115200
85 
87 #define SFE_QWIIC_SWARM_DEFAULT_I2C_ADDRESS 0x52
88 
90 #define SWARM_M138_MAX_PACKET_LENGTH_BYTES 192
91 #define SWARM_M138_MAX_PACKET_LENGTH_HEX 384
92 
94 #define SWARM_M138_MEM_ALLOC_CS 30
95 #define SWARM_M138_MEM_ALLOC_FV 37
96 #define SWARM_M138_MEM_ALLOC_MS 128
97 
99 const char SWARM_M138_COMMAND_CONFIGURATION[] = "$CS";
100 const char SWARM_M138_COMMAND_DATE_TIME_STAT[] = "$DT";
101 const char SWARM_M138_COMMAND_FIRMWARE_VER[] = "$FV";
102 const char SWARM_M138_COMMAND_GPS_JAMMING[] = "$GJ";
104 const char SWARM_M138_COMMAND_GPIO1_CONTROL[] = "$GP";
105 const char SWARM_M138_COMMAND_GPS_FIX_QUAL[] = "$GS";
106 const char SWARM_M138_COMMAND_MSG_RX_MGMT[] = "$MM";
107 const char SWARM_M138_COMMAND_MSG_TX_MGMT[] = "$MT";
108 const char SWARM_M138_COMMAND_POWER_OFF[] = "$PO";
109 const char SWARM_M138_COMMAND_POWER_STAT[] = "$PW";
110 const char SWARM_M138_COMMAND_RX_DATA_MSG[] = "$RD";
111 const char SWARM_M138_COMMAND_RESTART[] = "$RS";
112 const char SWARM_M138_COMMAND_RX_TEST[] = "$RT";
113 const char SWARM_M138_COMMAND_SLEEP[] = "$SL";
114 const char SWARM_M138_COMMAND_MODEM_STAT[] = "$M138";
115 const char SWARM_M138_COMMAND_TX_DATA[] = "$TD";
116 
118 typedef enum
119 {
130 #define SWARM_M138_SUCCESS SWARM_M138_ERROR_SUCCESS
131 
133 const uint32_t SWARM_M138_MAX_MESSAGE_RATE = 0x7FFFFFFF;
134 
136 typedef struct
137 {
138  uint16_t YYYY; // Year: 1970..2099
139  uint8_t MM; // Month: 01..12
140  uint8_t DD; // Day: 01..31
141  uint8_t hh; // Hour: 00..23
142  uint8_t mm; // Minutes: 00..59
143  uint8_t ss; // Seconds: 00..59
144  bool valid; // flag: I == Invalid == false; V == Valid == true
146 
148 typedef struct
149 {
150  uint8_t spoof_state; // 0 Spoofing unknown or deactivated
151  // 1 No spoofing indicated
152  // 2 Spoofing indicated
153  // 3 Multiple spoofing indications
154  uint8_t jamming_level; // 0 = no CW jamming, 255 = strong CW jamming
156 
158 typedef struct
159 {
160  float lat; // Degrees: +/- 90
161  float lon; // Degrees: +/- 180
162  float alt; // m
163  float course; // Degrees: 0..359 : 0=north, 90=east, 180=south, and 270=west
164  float speed; // km/h
166 
168 typedef enum
169 {
170  SWARM_M138_GPIO1_ANALOG = 0,
171  SWARM_M138_GPIO1_EXIT_SLEEP_LOW_HIGH,
172  SWARM_M138_GPIO1_EXIT_SLEEP_HIGH_LOW,
173  SWARM_M138_GPIO1_OUTPUT_LOW,
174  SWARM_M138_GPIO1_OUTPUT_HIGH,
175  SWARM_M138_GPIO1_MESSAGES_PENDING_LOW,
176  SWARM_M138_GPIO1_MESSAGES_PENDING_HIGH,
177  SWARM_M138_GPIO1_SLEEP_MODE_LOW,
178  SWARM_M138_GPIO1_SLEEP_MODE_HIGH,
179  SWARM_M138_GPIO1_INVALID
181 
183 typedef enum
184 {
185  SWARM_M138_GPS_FIX_TYPE_NF = 0, // No Fix
186  SWARM_M138_GPS_FIX_TYPE_DR, // Dead reckoning only solution
187  SWARM_M138_GPS_FIX_TYPE_G2, // Standalone 2D solution
188  SWARM_M138_GPS_FIX_TYPE_G3, // Standalone 3D solution
189  SWARM_M138_GPS_FIX_TYPE_D2, // Differential 2D solution
190  SWARM_M138_GPS_FIX_TYPE_D3, // Differential 3D solution
191  SWARM_M138_GPS_FIX_TYPE_RK, // Combined GNSS + dead reckoning solution
192  SWARM_M138_GPS_FIX_TYPE_TT, // Time only solution
193  SWARM_M138_GPS_FIX_TYPE_INVALID
195 
197 typedef struct
198 {
199  uint16_t hdop; // Horizontal dilution of precision (0..9999) (integer = actual hdop * 100)
200  uint16_t vdop; // Vertical dilution of precision (0..9999) (integer = actual vdop * 100)
201  uint8_t gnss_sats; // Number of GNSS satellites used in solution (integer)
202  uint8_t unused; // Always reads as 0, unused
203  Swarm_M138_GPS_Fix_Type_e fix_type;
205 
207 typedef struct
208 {
209  float unused1;
210  float unused2;
211  float unused3;
212  float unused4;
213  float temp; // CPU Temperature in degrees C to one decimal point
215 
217 typedef struct
218 {
219  bool background; // If true: the struct holds the rssi_background only. If false: the struct holds everything except rssi_background.
220  int16_t rssi_background; // Received background noise signal strength in dBm for open channel (integer).
221  int16_t rssi_sat; // Received signal strength in dBm for packet from satellite (integer)
222  int16_t snr; // Signal to noise ratio in dB for packet (integer)
223  int16_t fdev; // Frequency deviation in Hz for packet (integer)
224  Swarm_M138_DateTimeData_t time; // Date and time (UTC) of received packet (valid flag is unused - always set to true)
225  uint32_t sat_id; // Device ID of satellite heard (hexadecimal)
227 
229 typedef enum
230 {
231  SWARM_M138_WAKE_CAUSE_GPIO = 0, // GPIO input changed from inactive to active state
232  SWARM_M138_WAKE_CAUSE_SERIAL, // Activity was detected on the RX pin of the Modem's UART
233  SWARM_M138_WAKE_CAUSE_TIME, // The S or U parameter time has been reached
234  SWARM_M138_WAKE_CAUSE_INVALID
236 
238 typedef enum
239 {
240  SWARM_M138_MODEM_STATUS_BOOT_ABORT = 0, // A firmware crash occurred that caused a restart
241  SWARM_M138_MODEM_STATUS_BOOT_POWERON, // Power has been applied
242  SWARM_M138_MODEM_STATUS_BOOT_RUNNING, // Boot has completed and ready to accept commands
243  SWARM_M138_MODEM_STATUS_BOOT_UPDATED, // A firmware update was performed
244  SWARM_M138_MODEM_STATUS_BOOT_VERSION, // Current firmware version information
245  SWARM_M138_MODEM_STATUS_BOOT_RESTART, // Modem is restarting after $RS Restart Device
246  SWARM_M138_MODEM_STATUS_BOOT_SHUTDOWN, // Modem has shutdown after $PO Power Off. Disconnect and reconnect power to restart
247  SWARM_M138_MODEM_STATUS_DATETIME, // The first time GPS has acquired a valid date/time reference
248  SWARM_M138_MODEM_STATUS_POSITION, // The first time GPS has acquired a valid position 3D fix
249  SWARM_M138_MODEM_STATUS_DEBUG, // Debug message (data - debug text)
250  SWARM_M138_MODEM_STATUS_ERROR, // Error message (data - error text)
251  SWARM_M138_MODEM_STATUS_UNKNOWN, // A new, undocumented message
252  SWARM_M138_MODEM_STATUS_INVALID
254 
257 {
258 public:
259  // Constructor
261  SWARM_M138(void);
262 
264 #ifdef SWARM_M138_SOFTWARE_SERIAL_ENABLED
265  bool begin(SoftwareSerial &softSerial);
266 #endif
267  bool begin(HardwareSerial &hardSerial);
268  bool begin(byte deviceAddress = SFE_QWIIC_SWARM_DEFAULT_I2C_ADDRESS, TwoWire &wirePort = Wire);
269 
271  void enableDebugging(Stream &debugPort = Serial); // Turn on debug printing. If user doesn't specify then Serial will be used.
272  void disableDebugging(void); // Turn off debug printing
273 
277  Swarm_M138_Error_e getConfigurationSettings(char *settings); // Get the Swarm device ID and type name
278  Swarm_M138_Error_e getDeviceID(uint32_t *id); // Get the Swarm device ID
279  bool isConnected(void); // isConnected calls getDeviceID
280 
282  Swarm_M138_Error_e getDateTime(Swarm_M138_DateTimeData_t *dateTime); // Get the most recent $DT message
283  Swarm_M138_Error_e getDateTimeRate(uint32_t *rate); // Query the current $DT rate
284  Swarm_M138_Error_e setDateTimeRate(uint32_t rate); // Set the rate of $DT messages. 0 == Disable. Max is 2147483647 (2^31 - 1)
285 
287  Swarm_M138_Error_e getFirmwareVersion(char *version); // Get the Swarm device firmware version
288 
290  Swarm_M138_Error_e getGpsJammingIndication(Swarm_M138_GPS_Jamming_Indication_t *jamming); // Get the most recent $GJ message
291  Swarm_M138_Error_e getGpsJammingIndicationRate(uint32_t *rate); // Query the current $GJ rate
292  Swarm_M138_Error_e setGpsJammingIndicationRate(uint32_t rate); // Set the rate of $GJ messages. 0 == Disable. Max is 2147483647 (2^31 - 1)
293 
295  Swarm_M138_Error_e getGeospatialInfo(Swarm_M138_GeospatialData_t *info); // Get the most recent $GN message
296  Swarm_M138_Error_e getGeospatialInfoRate(uint32_t *rate); // Query the current $GN rate
297  Swarm_M138_Error_e setGeospatialInfoRate(uint32_t rate); // Set the rate of $GN messages. 0 == Disable. Max is 2147483647 (2^31 - 1)
298 
300  Swarm_M138_Error_e getGPIO1Mode(Swarm_M138_GPIO1_Mode_e *mode); // Get the GPIO1 pin mode
301  Swarm_M138_Error_e setGPIO1Mode(Swarm_M138_GPIO1_Mode_e mode); // Set the GPIO1 pin mode
302 
304  Swarm_M138_Error_e getGpsFixQuality(Swarm_M138_GPS_Fix_Quality_t *fixQuality); // Get the most recent $GS message
305  Swarm_M138_Error_e getGpsFixQualityRate(uint32_t *rate); // Query the current $GS rate
306  Swarm_M138_Error_e setGpsFixQualityRate(uint32_t rate); // Set the rate of $GS messages. 0 == Disable. Max is 2147483647 (2^31 - 1)
307 
309  Swarm_M138_Error_e powerOff(void); // The Modem enters a low power mode until power is completely removed and restored
310 
312  Swarm_M138_Error_e getPowerStatus(Swarm_M138_Power_Status_t *powerStatus); // Get the most recent $PW message
313  Swarm_M138_Error_e getPowerStatusRate(uint32_t *rate); // Query the current $PW rate
314  Swarm_M138_Error_e setPowerStatusRate(uint32_t rate); // Set the rate of $PW messages. 0 == Disable. Max is 2147483647 (2^31 - 1)
315  Swarm_M138_Error_e getTemperature(float *temperature); // Get the most recent temperature
316 
318  Swarm_M138_Error_e restartDevice(bool dbinit = false); // Restart the modem. Optionally clear the message database, to clear the DBXTOHIVEFULL error
319 
321  Swarm_M138_Error_e getReceiveTest(Swarm_M138_Receive_Test_t *rxTest); // Get the most recent $RT message
322  Swarm_M138_Error_e getReceiveTestRate(uint32_t *rate); // Query the current $RT rate
323  Swarm_M138_Error_e setReceiveTestRate(uint32_t rate); // Set the rate of $RT messages. 0 == Disable. Max is 2147483647 (2^31 - 1)
324 
326  Swarm_M138_Error_e sleepMode(uint32_t seconds); // Sleep for this many seconds
327  Swarm_M138_Error_e sleepMode(Swarm_M138_DateTimeData_t sleepUntil, bool dateAndTime = true); // Sleep until this date and time. Set dateAndTime to false to sleep until a time
328 
330  Swarm_M138_Error_e getRxMessageCount(uint16_t *count, bool unread = false); // Return count of all messages (default) or unread messages (unread = true)
331  Swarm_M138_Error_e deleteRxMessage(uint64_t msg_id); // Delete RX message with ID
332  Swarm_M138_Error_e deleteAllRxMessages(bool read = true); // Delete all read RX messages (default) or all messages (read = false)
333  Swarm_M138_Error_e markRxMessage(uint64_t msg_id); // Mark message ID as read
334  Swarm_M138_Error_e markAllRxMessages(void); // Mark all messages as read
335  Swarm_M138_Error_e getMessageNotifications(bool *enabled); // Query if message notifications are enabled
336  Swarm_M138_Error_e setMessageNotifications(bool enable); // Enable / disable message notifications
337  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 ID. Message contents are copied to asciiHex as ASCII Hex
338  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 message. Message contents are copied to asciiHex. ID is copied to id.
339  Swarm_M138_Error_e readNewestMessage(char *asciiHex, size_t len, uint64_t *msg_id, uint32_t *epoch = NULL, uint16_t *appID = NULL); // Read the oldest message. Message contents are copied to asciiHex. ID is copied to id.
340 
342  Swarm_M138_Error_e getUnsentMessageCount(uint16_t *count); // Return count of all unsent messages
343  Swarm_M138_Error_e deleteTxMessage(uint64_t msg_id); // Delete TX message with ID
344  Swarm_M138_Error_e deleteAllTxMessages(void); // Delete all unsent messages
345  Swarm_M138_Error_e listTxMessage(uint64_t msg_id, char *asciiHex, size_t len, uint32_t *epoch = NULL, uint16_t *appID = NULL); // List unsent message with ID
346  Swarm_M138_Error_e listTxMessagesIDs(uint64_t *ids, uint16_t maxCount); // List the IDs of all unsent messages. Call getUnsentMessageCount first so you know how many IDs to expect
347 
349  // The application ID is optional. Valid appID's are: 0 to 64999. Swarm reserves use of 65000 - 65535.
350  Swarm_M138_Error_e transmitText(const char *data, uint64_t *msg_id); // Send ASCII string. Assigned message ID is returned in id.
351  Swarm_M138_Error_e transmitText(const char *data, uint64_t *msg_id, uint16_t appID); // Send ASCII string. Assigned message ID is returned in id.
352  Swarm_M138_Error_e transmitTextHold(const char *data, uint64_t *msg_id, uint32_t hold); // Send ASCII string. Assigned message ID is returned in id. Hold for up to hold seconds
353  Swarm_M138_Error_e transmitTextHold(const char *data, uint64_t *msg_id, uint32_t hold, uint16_t appID); // Send ASCII string. Assigned message ID is returned in id. Hold for up to hold seconds
354  Swarm_M138_Error_e transmitTextExpire(const char *data, uint64_t *msg_id, uint32_t epoch); // Send ASCII string. Assigned message ID is returned in id. Expire message at epoch
355  Swarm_M138_Error_e transmitTextExpire(const char *data, uint64_t *msg_id, uint32_t epoch, uint16_t appID); // Send ASCII string. Assigned message ID is returned in id. Expire message at epoch
356  Swarm_M138_Error_e transmitBinary(const uint8_t *data, size_t len, uint64_t *msg_id); // Send binary data. Assigned message ID is returned in id.
357  Swarm_M138_Error_e transmitBinary(const uint8_t *data, size_t len, uint64_t *msg_id, uint16_t appID); // Send binary data. Assigned message ID is returned in id.
358  Swarm_M138_Error_e transmitBinaryHold(const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t hold); // Send binary data. Assigned message ID is returned in id. Hold for up to hold seconds
359  Swarm_M138_Error_e transmitBinaryHold(const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t hold, uint16_t appID); // Send binary data. Assigned message ID is returned in id. Hold for up to hold seconds
360  Swarm_M138_Error_e transmitBinaryExpire(const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t epoch); // Send binary data. Assigned message ID is returned in id. Expire message at epoch
361  Swarm_M138_Error_e transmitBinaryExpire(const uint8_t *data, size_t len, uint64_t *msg_id, uint32_t epoch, uint16_t appID); // Send binary data. Assigned message ID is returned in id. Expire message at epoch
362 
364  bool checkUnsolicitedMsg(void);
365 
367  void setDateTimeCallback(void (*swarmDateTimeCallback)(const Swarm_M138_DateTimeData_t *dateTime)); // Set callback for $DT
368  void setGpsJammingCallback(void (*swarmGpsJammingCallback)(const Swarm_M138_GPS_Jamming_Indication_t *jamming)); // Set callback for $GJ
369  void setGeospatialInfoCallback(void (*swarmGeospatialCallback)(const Swarm_M138_GeospatialData_t *info)); // Set callback for $GN
370  void setGpsFixQualityCallback(void (*swarmGpsFixQualityCallback)(const Swarm_M138_GPS_Fix_Quality_t *fixQuality)); // Set callback for $GS
371  void setPowerStatusCallback(void (*swarmPowerStatusCallback)(const Swarm_M138_Power_Status_t *status)); // Set callback for $PW
372  void setReceiveMessageCallback(void (*swarmReceiveMessageCallback)(const uint16_t *appID, const int16_t *rssi, const int16_t *snr, const int16_t *fdev, const char *asciiHex)); // Set callback for $RD
373  void setReceiveTestCallback(void (*swarmReceiveTestCallback)(const Swarm_M138_Receive_Test_t *rxTest)); // Set callback for $RT
374  void setSleepWakeCallback(void (*swarmSleepWakeCallback)(Swarm_M138_Wake_Cause_e cause)); // Set callback for $SL WAKE
375  void setModemStatusCallback(void (*swarmModemStatusCallback)(Swarm_M138_Modem_Status_e status, const char *data)); // Set callback for $M138. data could be NULL for messages like BOOT_RUNNING
376  void setTransmitDataCallback(void (*swarmTransmitDataCallback)(const int16_t *rssi_sat, const int16_t *snr, const int16_t *fdev, const uint64_t *msg_id)); // Set callback for $TD SENT
377 
379  const char *modemStatusString(Swarm_M138_Modem_Status_e status);
380  const char *modemErrorString(Swarm_M138_Error_e error);
381  const char *commandErrorString(const char *ERR);
382 
384 #define SWARM_M138_MAX_CMD_ERROR_LEN 32
385  char *commandError;
386 
387 private:
388  HardwareSerial *_hardSerial;
389 #ifdef SWARM_M138_SOFTWARE_SERIAL_ENABLED
390  SoftwareSerial *_softSerial;
391 #endif
392 
393  unsigned long _baud; // Baud rate for serial communication with the modem
394 
395  Stream *_debugPort; // The stream to send debug messages to if enabled. Usually Serial.
396  bool _printDebug; // Flag to print debugging variables
397 
398  bool _checkUnsolicitedMsgReentrant; // Prevent reentry of checkUnsolicitedMsg - just in case it gets called from a callback
399 
400 #define _RxBuffSize 512
401  const unsigned long _rxWindowMillis = 5; // Wait up to 5ms for any more serial characters to arrive
402  char *_swarmBacklog; // Allocated in SWARM_M138::begin
403 
404  // Callbacks for unsolicited messages
405  void (*_swarmDateTimeCallback)(const Swarm_M138_DateTimeData_t *dateTime);
406  void (*_swarmGpsJammingCallback)(const Swarm_M138_GPS_Jamming_Indication_t *jamming);
407  void (*_swarmGeospatialCallback)(const Swarm_M138_GeospatialData_t *info);
408  void (*_swarmGpsFixQualityCallback)(const Swarm_M138_GPS_Fix_Quality_t *fixQuality);
409  void (*_swarmPowerStatusCallback)(const Swarm_M138_Power_Status_t *status);
410  void (*_swarmReceiveMessageCallback)(const uint16_t *appID, const int16_t *rssi, const int16_t *snr, const int16_t *fdev, const char *asciiHex);
411  void (*_swarmReceiveTestCallback)(const Swarm_M138_Receive_Test_t *rxTest);
412  void (*_swarmSleepWakeCallback)(Swarm_M138_Wake_Cause_e cause);
413  void (*_swarmModemStatusCallback)(Swarm_M138_Modem_Status_e status, const char *data);
414  void (*_swarmTransmitDataCallback)(const int16_t *rssi_sat, const int16_t *snr, const int16_t *fdev, const uint64_t *id);
415 
416  // Add the two NMEA checksum bytes and line feed to a command
417  void addChecksumLF(char *command);
418 
419  // Check if the response / message format and checksum is valid
420  Swarm_M138_Error_e checkChecksum(char *startPosition);
421 
422  // Extract the error from the command response
423  Swarm_M138_Error_e extractCommandError(char *startPosition);
424 
425  // Send command with the start of an expected response
426  Swarm_M138_Error_e sendCommandWithResponse(const char *command, const char *expectedResponseStart, const char *expectedErrorStart,
427  char *responseDest, size_t destSize, unsigned long commandTimeout = SWARM_M138_STANDARD_RESPONSE_TIMEOUT);
428 
429  // Send a command (don't wait for a response)
430  void sendCommand(const char *command);
431 
432  // Wait for an expected response or error (don't send a command)
433  Swarm_M138_Error_e waitForResponse(const char *expectedResponseStart, const char *expectedErrorStart,
434  char *responseDest, size_t destSize, unsigned long timeout = SWARM_M138_STANDARD_RESPONSE_TIMEOUT);
435 
436  // Queue a text message for transmission
437  Swarm_M138_Error_e transmitText(const char *data, uint64_t *msg_id, bool useAppID, uint16_t appID,
438  bool useHold, uint32_t hold, bool useEpoch, uint32_t epoch);
439 
440  // Queue a binary message for transmission
441  Swarm_M138_Error_e transmitBinary(const uint8_t *data, size_t len, uint64_t *msg_id, bool useAppID, uint16_t appID,
442  bool useHold, uint32_t hold, bool useEpoch, uint32_t epoch);
443 
444  // Common code for readMessage / readOldestMessage / readNewestMessage
445  Swarm_M138_Error_e readMessageInternal(const char mode, uint64_t msg_id_in, char *asciiHex, size_t len, uint64_t *msg_id_out, uint32_t *epoch, uint16_t *appID);
446 
447  bool initializeBuffers(void);
448  bool processUnsolicitedEvent(const char *event);
449  void pruneBacklog(void);
450 
451  // Support for Qwiic Swarm
452 
453  TwoWire *_i2cPort; // The I2C (Wire) port for the Qwiic Swarm
454  byte _address; // I2C address of the Qwiic Swarm
455  int qwiicSwarmAvailable(void); // Check how many serial bytes Qwiic Sawrm has in its buffer
456  int qwiicSwarmReadChars(int len, char *dest); // Read bytes from Qwiic Swarm
457  int qwiicSwarmWriteChars(int len, const char *dest); // Write bytes to Qwiic Swarm
458  unsigned long _lastI2cCheck;
459 #define QWIIC_SWARM_I2C_POLLING_WAIT_MS 2 // Avoid pounding the I2C bus. Wait at least 2ms between calls to qwiicSwarmAvailable
460 // Define the I2C 'registers'
461 #define QWIIC_SWARM_LEN_REG 0xFD // The serial length regsiter: 2 bytes (MSB, LSB) indicating how many serial characters are available to be read
462 #define QWIIC_SWARM_DATA_REG 0xFF // The serial data register: used to read and write serial data from/to the modem
463 // Define the maximum number of serial bytes to be requested from the ATtiny841
464 #define QWIIC_SWARM_SER_PACKET_SIZE 8
465 // Qwiic Iridium ATtiny841 I2C buffer length
466 #define QWIIC_SWARM_I2C_BUFFER_LENGTH 32
467 
468  // Memory allocation
469 
470  char *swarm_m138_alloc_char(size_t num);
471  void swarm_m138_free_char(char *freeMe);
472 
473  // UART / I2C Functions
474  size_t hwPrint(const char *s);
475  size_t hwWriteData(const char *buff, int len);
476  size_t hwWrite(const char c);
477  int hwAvailable(void);
478  int hwReadChars(char *buf, int len);
479 
480  void beginSerial(unsigned long baud);
481 };
482 
483 #endif // SPARKFUN_SWARM_M138_ARDUINO_LIBRARY_H
Swarm_M138_Error_e
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:119
@ SWARM_M138_ERROR_INVALID_MODE
Indicates the GPIO1 pin mode was invalid.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:127
@ SWARM_M138_ERROR_ERR
Command input error (ERR) - the error is copied into commandError.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:128
@ SWARM_M138_ERROR_INVALID_RATE
Indicates the message rate was invalid.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:126
@ SWARM_M138_ERROR_ERROR
Just a plain old communication error.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:120
@ SWARM_M138_ERROR_MEM_ALLOC
Memory allocation error.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:122
@ SWARM_M138_ERROR_TIMEOUT
Communication timeout.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:123
@ SWARM_M138_ERROR_INVALID_FORMAT
Indicates the command response format was invalid.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:124
@ SWARM_M138_ERROR_SUCCESS
Hey, it worked!
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:121
@ SWARM_M138_ERROR_INVALID_CHECKSUM
Indicates the command response checksum was invalid.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:125
const char SWARM_M138_COMMAND_GPS_JAMMING[]
GPS Jamming/Spoofing Indication.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:102
Swarm_M138_Modem_Status_e
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:239
const char SWARM_M138_COMMAND_RX_DATA_MSG[]
Receive Data Message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:110
Swarm_M138_GPIO1_Mode_e
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:169
const char SWARM_M138_COMMAND_MSG_RX_MGMT[]
Messages Received Management.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:106
const char SWARM_M138_COMMAND_FIRMWARE_VER[]
Retrieve Firmware Version.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:101
const char SWARM_M138_COMMAND_MSG_TX_MGMT[]
Messages to Transmit Management.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:107
const char SWARM_M138_COMMAND_SLEEP[]
Sleep Mode.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:113
const char SWARM_M138_COMMAND_POWER_STAT[]
Power Status.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:109
const char SWARM_M138_COMMAND_GPIO1_CONTROL[]
GPIO1 Control.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:104
const char SWARM_M138_COMMAND_GPS_FIX_QUAL[]
GPS Fix Quality.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:105
const char SWARM_M138_COMMAND_TX_DATA[]
Transmit Data.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:115
#define SFE_QWIIC_SWARM_DEFAULT_I2C_ADDRESS
The default I2C address for the SparkFun Qwiic Swarm Breakout.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:87
const char SWARM_M138_COMMAND_GEOSPATIAL_INFO[]
Geospatial Information.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:103
const char SWARM_M138_COMMAND_RX_TEST[]
Receive Test.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:112
Swarm_M138_GPS_Fix_Type_e
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:184
const char SWARM_M138_COMMAND_RESTART[]
Restart Device.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:111
const char SWARM_M138_COMMAND_MODEM_STAT[]
Modem Status.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:114
Swarm_M138_Wake_Cause_e
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:230
#define SWARM_M138_STANDARD_RESPONSE_TIMEOUT
Standard command timeout: allow one second for the modem to respond.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:77
const char SWARM_M138_COMMAND_CONFIGURATION[]
Configuration Settings.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:99
const char SWARM_M138_COMMAND_DATE_TIME_STAT[]
Date/Time Status.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:100
const uint32_t SWARM_M138_MAX_MESSAGE_RATE
2147483647 (2^31 - 1)
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:133
const char SWARM_M138_COMMAND_POWER_OFF[]
Power Off.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:108
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:257
Swarm_M138_Error_e getReceiveTestRate(uint32_t *rate)
Query the current $RT rate.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2511
Swarm_M138_Error_e listTxMessagesIDs(uint64_t *ids, uint16_t maxCount)
List the IDs of all the unsent messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3924
Swarm_M138_Error_e getPowerStatus(Swarm_M138_Power_Status_t *powerStatus)
Get the most recent $PW message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2124
Swarm_M138_Error_e deleteTxMessage(uint64_t msg_id)
Delete the TX message with the specified ID.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3590
void setDateTimeCallback(void(*swarmDateTimeCallback)(const Swarm_M138_DateTimeData_t *dateTime))
Set up the callback for the $DT Date Time message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4622
void setPowerStatusCallback(void(*swarmPowerStatusCallback)(const Swarm_M138_Power_Status_t *status))
Set up the callback for the $PW power status message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4670
Swarm_M138_Error_e getConfigurationSettings(char *settings)
Read the modem device ID and name using the $CS message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:946
Swarm_M138_Error_e deleteAllTxMessages(void)
Delete all unsent messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3678
void setSleepWakeCallback(void(*swarmSleepWakeCallback)(Swarm_M138_Wake_Cause_e cause))
Set up the callback for the $SL WAKE sleep mode messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4706
void setReceiveTestCallback(void(*swarmReceiveTestCallback)(const Swarm_M138_Receive_Test_t *rxTest))
Set up the callback for the $RT receive test message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4682
Swarm_M138_Error_e setGPIO1Mode(Swarm_M138_GPIO1_Mode_e mode)
Get the current GPIO1 pin mode using the $GP message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1824
void setGeospatialInfoCallback(void(*swarmGeospatialCallback)(const Swarm_M138_GeospatialData_t *info))
Set up the callback for the $GN geospatial information message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4646
Swarm_M138_Error_e getDateTimeRate(uint32_t *rate)
Query the current $DT rate.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1163
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3295
Swarm_M138_Error_e getGeospatialInfo(Swarm_M138_GeospatialData_t *info)
Get the most recent $GN message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1549
Swarm_M138_Error_e markRxMessage(uint64_t msg_id)
Mark the RX message with the specified ID as read.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3027
bool isConnected(void)
Check if the modem is connected and responding by getting the configuration settings.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:136
Swarm_M138_Error_e setMessageNotifications(bool enable)
Enable / disable receive message notifications.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3221
Swarm_M138_Error_e deleteAllRxMessages(bool read=true)
Delete all read RX messages (default) or all messages (read = false)
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2948
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4171
Swarm_M138_Error_e getMessageNotifications(bool *enabled)
Query if message notifications are enabled.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3173
void setGpsJammingCallback(void(*swarmGpsJammingCallback)(const Swarm_M138_GPS_Jamming_Indication_t *jamming))
Set up the callback for the $GJ jamming indication message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4634
Swarm_M138_Error_e transmitText(const char *data, uint64_t *msg_id)
Queue a printable text message for transmission.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4129
Swarm_M138_Error_e setGpsFixQualityRate(uint32_t rate)
Set the rate of $GS GPS fix quality messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2039
Swarm_M138_Error_e getDateTime(Swarm_M138_DateTimeData_t *dateTime)
Get the most recent $DT message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1088
Swarm_M138_Error_e sleepMode(uint32_t seconds)
Instruct the modem to sleep for this many seconds.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2639
Swarm_M138_Error_e powerOff(void)
The Modem enters a low power mode until power is completely removed and restored.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2085
Swarm_M138_Error_e setGpsJammingIndicationRate(uint32_t rate)
Set the rate of $GJ jamming indication messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1502
Swarm_M138_Error_e getDeviceID(uint32_t *id)
Read the modem device ID using the $CS message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1010
const char * modemStatusString(Swarm_M138_Modem_Status_e status)
Convert modem status enum into printable text.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4745
bool checkUnsolicitedMsg(void)
Check for the arrival of new serial data. Parse it. Process any unsolicited messages....
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:199
const char * commandErrorString(const char *ERR)
Convert command error into a printable description.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4843
Swarm_M138_Error_e getGpsFixQualityRate(uint32_t *rate)
Query the current $GS rate.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1959
Swarm_M138_Error_e setDateTimeRate(uint32_t rate)
Set the rate of $DT Date/Time messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1243
bool begin(HardwareSerial &hardSerial)
Begin communication with the Swarm M138 modem.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:89
Swarm_M138_Error_e setPowerStatusRate(uint32_t rate)
Set the rate of $PW power status messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2295
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)
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4467
Swarm_M138_Error_e deleteRxMessage(uint64_t msg_id)
Delete the RX message with the specified ID.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2857
void setGpsFixQualityCallback(void(*swarmGpsFixQualityCallback)(const Swarm_M138_GPS_Fix_Quality_t *fixQuality))
Set up the callback for the $GS GPS fix quality message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4658
Swarm_M138_Error_e getTemperature(float *temperature)
Get the modem temperature.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2342
Swarm_M138_Error_e getGpsJammingIndicationRate(uint32_t *rate)
Query the current $GJ rate.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1422
Swarm_M138_Error_e getGpsFixQuality(Swarm_M138_GPS_Fix_Quality_t *fixQuality)
Get the most recent $GS message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1867
void disableDebugging(void)
Disable debug messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:187
Swarm_M138_Error_e markAllRxMessages(void)
Mark all RX messages as read.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3115
Swarm_M138_Error_e getGpsJammingIndication(Swarm_M138_GPS_Jamming_Indication_t *jamming)
Get the most recent $GJ message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1353
Swarm_M138_Error_e getUnsentMessageCount(uint16_t *count)
Return the count of all unsent messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3508
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3272
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4731
Swarm_M138_Error_e getPowerStatusRate(uint32_t *rate)
Query the current $PW rate.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2215
Swarm_M138_Error_e getGPIO1Mode(Swarm_M138_GPIO1_Mode_e *mode)
Get the current GPIO1 pin mode using the $GP message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1756
const char * modemErrorString(Swarm_M138_Error_e error)
Convert modem error enum into printable text.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4799
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4417
void setModemStatusCallback(void(*swarmModemStatusCallback)(Swarm_M138_Modem_Status_e status, const char *data))
Set up the callback for the $M138 modem status messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4694
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4718
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3750
Swarm_M138_Error_e setReceiveTestRate(uint32_t rate)
Set the rate of $RT receive test messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2591
Swarm_M138_Error_e restartDevice(bool dbinit=false)
Restart the modem.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2363
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)
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4217
Swarm_M138_Error_e getFirmwareVersion(char *version)
Read the modem firmware version using the $FV message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1292
SWARM_M138(void)
Class to communicate with the Swarm M138 satellite modem.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:28
Swarm_M138_Error_e transmitBinary(const uint8_t *data, size_t len, uint64_t *msg_id)
Queue a binary message for transmission.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:4371
Swarm_M138_Error_e getReceiveTest(Swarm_M138_Receive_Test_t *rxTest)
Get the most recent $RT message.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2407
Swarm_M138_Error_e setGeospatialInfoRate(uint32_t rate)
Set the rate of $GN geospatial information messages.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1709
Swarm_M138_Error_e getGeospatialInfoRate(uint32_t *rate)
Query the current $GN rate.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:1629
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.
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:3318
Swarm_M138_Error_e getRxMessageCount(uint16_t *count, bool unread=false)
Return the count of all messages (default) or unread messages (unread = true)
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:2772
void enableDebugging(Stream &debugPort=Serial)
Enable debug messages on the chosen serial port Calling this function with nothing sets the debug por...
Definition: SparkFun_Swarm_Satellite_Arduino_Library.cpp:176
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:137
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:198
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:149
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:159
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:208
Definition: SparkFun_Swarm_Satellite_Arduino_Library.h:218