The RockBLOCK 9704 library. Maintained by Ground Control (https://www.groundcontrol.com/) and license under the MIT License. More...

#include "serial.h"
#include "jspr.h"
#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
#include <stddef.h>
#include "gpio.h"

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	rbCallbacks_t
	Struct containing user defined callback functions for asynchronous operations. More...

Macros
#define	BASE64_TEMP_BUFFER 2048U
	Temporary buffer size used for Base64 encoding/decoding of IMT messages.

#define	RB9704_BAUD 230400U
	Fixed serial baud rate for communication with the RockBLOCK 9704 modem.

#define	SERIAL_CONTEXT_SETUP_FUNC setContextLinux
	Platform-specific macro to define the serial context setup function.

Typedefs
typedef void(*	updateProgressCallback) (void *context, const unsigned long sofar, const unsigned long total)
	A callback definition for the kermit transfer.

Enumerations
enum	rbMsgStatus_t { RB_MSG_STATUS_OK = 1 , RB_MSG_STATUS_FAIL = -1 }
	Indicates the result of a message operation. More...

enum	cloudloopTopics_t { RAW_TOPIC = 244 , PURPLE_TOPIC = 313 , PINK_TOPIC = 314 , RED_TOPIC = 315 , ORANGE_TOPIC = 316 , YELLOW_TOPIC = 317 }
	Predefined Cloudloop topic identifiers for RockBLOCK 9704. More...

Functions
void	rbRegisterCallbacks (const rbCallbacks_t *callbacks)
	Registers a set of user-defined callbacks with the library.

bool	rbBegin (const char *port)
	Initialise the the serial connection in the detected context (or user defined), if successful continue to set the API, SIM & state of the modem in order to be ready for messaging.

bool	rbEnd (void)
	Uninitialise/close the the serial connection.

bool	rbSendMessage (const char *data, const size_t length, const int timeout)
	Send a mobile originated message from the modem on the default topic (244).

bool	rbSendMessageCloudloop (cloudloopTopics_t topic, const char *data, const size_t length, const int timeout)
	Send a mobile originated message from the modem on a cloudloop topic of choice.

bool	rbSendMessageAny (uint16_t topic, const char *data, const size_t length, const int timeout)
	Send a mobile originated message from the modem on any topic.

size_t	rbReceiveMessage (char **buffer)
	Listen for a mobile terminated message from the modem.

size_t	rbReceiveMessageWithTopic (char **buffer, uint16_t topic)
	Listen for a mobile terminated message from the modem.

size_t	rbReceiveMessageAsync (char **buffer)
	Check if a valid message exists, stored at the head of the receiving queue.

bool	rbAcknowledgeReceiveHeadAsync (void)
	Acknowledge the head of the receiving queue by discarding it.

void	rbReceiveLockAsync (void)
	Locks the receiving queue so that old messages aren't discarded when incoming ones arrive.

void	rbReceiveUnlockAsync (void)
	Unlocks the receiving queue so that old messages are discarded to make space for incoming ones.

bool	rbSendMessageAsync (uint16_t topic, const char *data, const size_t length)
	Queue a message to be sent.

void	rbPoll (void)
	Polling function that handles all incoming communication from the modem.

int8_t	rbGetSignal (void)
	Get the current signal strength from the modem.

char *	rbGetHwVersion (void)
	Get the hardware version.

char *	rbGetSerialNumber (void)
	Get the serial number.

char *	rbGetImei (void)
	Get the imei.

int8_t	rbGetBoardTemp (void)
	Get the board temperature.

bool	rbGetCardPresent (void)
	Check if SIM presence is currently asserted.

bool	rbGetSimConnected (void)
	Check if SIM card is present, communicating properly with, and has presented no errors in SIM transactions with the transceiver.

char *	rbGetIccid (void)
	Get the iccid.

char *	rbGetFirmwareVersion (void)
	Get the Iridium modem firmware version as vX.Y.X with X being the major number, Y being the minor number and X being the patch number.

bool	rbResyncServiceConfig (void)
	Requests a resynchronisation of the service configuration.

bool	rbUpdateFirmware (const char firmwareFile, updateProgressCallback progress, void context)
	Update 9704 firmware. This is a blocking call and will take approximately 10 minutes to upgrade, the updateProgressCallback is recommended.

bool	rbBeginGpio (char port, const rbGpioTable_t gpioInfo, const int timeout)
	Drives user defined pin (power enable) low and user defined pin (iridium enable) high to initialise the RB9704 PiHat. Initialise the serial connection in the detected context (or user defined), if successful continue to set the API, SIM & state of the modem in order to be ready for messaging.

bool	rbEndGpio (const rbGpioTable_t *gpioInfo)
	Drives user defined pin (power enable) high and another user defined pin (iridium enable) low to deinitialise the RB9704 PiHat. Deinitialises/closes the the serial connection.

static uint16_t	calculateCrc (const uint8_t *buffer, const size_t bufferLength, const uint16_t initialCRC)
	Calculate CRC for a buffer.

static bool	appendCrc (uint8_t *buffer, size_t length)
	Append CRC to the end of a buffer.

static size_t	encodeData (const char srcBuffer, const size_t srcLength, char destBuffer, const size_t destLength)
	Encode binary data to base64 format.

static size_t	decodeData (const char srcBuffer, const size_t srcLength, char destBuffer, const size_t destLength)
	Decode base64 data back into binary.

static bool	setApi (void)
	Set the modem API version.

static bool	setSim (void)
	Initialise SIM card configuration.

static bool	setState (void)
	Set operational state for the modem.

static bool	checkProvisioning (uint16_t topic)
	Check if the given topic is provisioned.

static bool	sendMoFromQueue (const int timeout)
	Send a queued message using mobile originated (MO) transmission.

static bool	listenForMt (void)
	Listen for an incoming mobile terminated (MT) message.

static bool	getHwInfo (jsprHwInfo_t *hwInfo)
	Retrieve hardware information from the modem.

static bool	getSimStatus (jsprSimStatus_t *simStatus)
	Get current SIM card status.

static bool	sendMoFromQueueAsync (void)
	Send a the modem a request to queue a message.

static bool	checkMoQueue (void)
	Checks if any more messages have been queued, if so, send them.

Detailed Description

The RockBLOCK 9704 library. Maintained by Ground Control (https://www.groundcontrol.com/) and license under the MIT License.

Macro Definition Documentation

◆ BASE64_TEMP_BUFFER

#define BASE64_TEMP_BUFFER 2048U

Temporary buffer size used for Base64 encoding/decoding of IMT messages.

◆ RB9704_BAUD

#define RB9704_BAUD 230400U

Fixed serial baud rate for communication with the RockBLOCK 9704 modem.

This value should not be changed, as it is required by the modem hardware.

◆ SERIAL_CONTEXT_SETUP_FUNC

#define SERIAL_CONTEXT_SETUP_FUNC setContextLinux

Platform-specific macro to define the serial context setup function.

This macro resolves to a platform-appropriate function used to configure the serial context. By default, it maps to:

setContextLinux on Linux and macOS
setContextWindows on Windows
setContextArduino on Arduino platforms

You can override this macro by defining SERIAL_CONTEXT_SETUP_FUNC manually before including this library, allowing for custom serial context initialisation logic.

Example:

#define SERIAL_CONTEXT_SETUP_FUNC myCustomSerialSetup

Typedef Documentation

◆ updateProgressCallback

typedef void(* updateProgressCallback) (void *context, const unsigned long sofar, const unsigned long total)

A callback definition for the kermit transfer.

Parameters

context	a pointer to some shared context given in rbUpdateFirmware.
sofar	the number of bytes transferred so far.
total	the total number of bytes to transfer.

Returns

void

Note: This is only defined if KERMIT was defined during the build.

Enumeration Type Documentation

◆ cloudloopTopics_t

enum cloudloopTopics_t

Predefined Cloudloop topic identifiers for RockBLOCK 9704.

This enum defines known topic IDs used to route messages through the Cloudloop data.

Enumerator
RAW_TOPIC	Raw topic ID used for unfiltered transmission.
PURPLE_TOPIC	Topic ID for messages labeled "Purple".
PINK_TOPIC	Topic ID for messages labeled "Pink".
RED_TOPIC	Topic ID for messages labeled "Red".
ORANGE_TOPIC	Topic ID for messages labeled "Orange".
YELLOW_TOPIC	Topic ID for messages labeled "Yellow".

◆ rbMsgStatus_t

enum rbMsgStatus_t

Indicates the result of a message operation.

This enum represents success or failure of processing either an incoming or outgoing message.

Enumerator
RB_MSG_STATUS_OK	Message was processed successfully.
RB_MSG_STATUS_FAIL	Message failed to be processed.

Function Documentation

◆ appendCrc()

static bool appendCrc	(	uint8_t *	buffer,
		size_t	length
	)

static

Append CRC to the end of a buffer.

Parameters

buffer	Pointer to the buffer to append CRC to.
length	Length of the buffer in bytes.

Returns: true on success, false on failure.

◆ calculateCrc()

static uint16_t calculateCrc	(	const uint8_t *	buffer,
		const size_t	bufferLength,
		const uint16_t	initialCRC
	)

static

Calculate CRC for a buffer.

Parameters

buffer	Pointer to the data buffer.
bufferLength	Length of the buffer in bytes.
initialCRC	Initial CRC value to start from.

Returns: Calculated CRC as an uint16_t.

◆ checkMoQueue()

static bool checkMoQueue ( void )

static

Checks if any more messages have been queued, if so, send them.

Returns: true on success, false on failure.

◆ checkProvisioning()

static bool checkProvisioning ( uint16_t topic )

static

Check if the given topic is provisioned.

Parameters

topic Topic ID to check.

Returns: true if the topic is provisioned, false otherwise.

◆ decodeData()

static size_t decodeData	(	const char *	srcBuffer,
		const size_t	srcLength,
		char *	destBuffer,
		const size_t	destLength
	)

static

Decode base64 data back into binary.

Parameters

srcBuffer	Pointer to base64-encoded string.
srcLength	Length of encoded string.
destBuffer	Pointer to destination binary buffer.
destLength	Length of destination buffer.

Returns: Number of bytes written to destBuffer.

◆ encodeData()

static size_t encodeData	(	const char *	srcBuffer,
		const size_t	srcLength,
		char *	destBuffer,
		const size_t	destLength
	)

static

Encode binary data to base64 format.

Parameters

srcBuffer	Pointer to source binary data.
srcLength	Length of source data in bytes.
destBuffer	Pointer to destination buffer for base64 string.
destLength	Length of destination buffer.

Returns: Number of bytes written to destBuffer.

◆ getHwInfo()

static bool getHwInfo ( jsprHwInfo_t * hwInfo )

static

Retrieve hardware information from the modem.

Parameters

hwInfo Pointer to structure to populate with hardware info.

Returns: true on success, false on failure.

◆ getSimStatus()

static bool getSimStatus ( jsprSimStatus_t * simStatus )

static

Get current SIM card status.

Parameters

simStatus Pointer to structure to populate with SIM status.

Returns: true on success, false on failure.

◆ listenForMt()

static bool listenForMt ( void )

static

Listen for an incoming mobile terminated (MT) message.

Returns: true if a message was received, false otherwise.

◆ rbAcknowledgeReceiveHeadAsync()

bool rbAcknowledgeReceiveHeadAsync ( void )

Acknowledge the head of the receiving queue by discarding it.

Returns: bool depicting success or failure.

Note
This function will clear the head of the receiving queue to make space for other incoming messages, new messages will always be brought to the head of the queue whilst old ones will be automatically discarded if they reach the end of the queue to make space.

◆ rbBegin()

bool rbBegin ( const char * port )

Initialise the the serial connection in the detected context (or user defined), if successful continue to set the API, SIM & state of the modem in order to be ready for messaging.

Parameters

port	pointer to port name.

Returns: bool depicting success or failure.

◆ rbBeginGpio()

bool rbBeginGpio	(	char *	port,
		const rbGpioTable_t *	gpioInfo,
		const int	timeout
	)

Drives user defined pin (power enable) low and user defined pin (iridium enable) high to initialise the RB9704 PiHat. Initialise the serial connection in the detected context (or user defined), if successful continue to set the API, SIM & state of the modem in order to be ready for messaging.

Parameters

port	pointer to port name.
gpioInfo	structure containing a valid chip & pin for powerEnable, IridiumEnable and booted.
timeout	in seconds.

Returns: bool depicting success or failure.

◆ rbEnd()

bool rbEnd ( void )

Uninitialise/close the the serial connection.

Returns: bool depicting success or failure.

◆ rbEndGpio()

bool rbEndGpio ( const rbGpioTable_t * gpioInfo )

Drives user defined pin (power enable) high and another user defined pin (iridium enable) low to deinitialise the RB9704 PiHat. Deinitialises/closes the the serial connection.

Parameters

gpioInfo structure containing a valid chip & pin for powerEnable, IridiumEnable and booted.

Returns: bool depicting success or failure.

◆ rbGetBoardTemp()

int8_t rbGetBoardTemp ( void )

Get the board temperature.

Returns: int8_t of the current temperature (-100 on error).

◆ rbGetCardPresent()

bool rbGetCardPresent ( void )

Check if SIM presence is currently asserted.

Returns

bool depicting SIM presence.

Note: This function will return false either if it received it from the modem or the function failed.

◆ rbGetFirmwareVersion()

char * rbGetFirmwareVersion ( void )

Get the Iridium modem firmware version as vX.Y.X with X being the major number, Y being the minor number and X being the patch number.

Returns: char pointer to firmware version

◆ rbGetHwVersion()

char * rbGetHwVersion ( void )

Get the hardware version.

Returns: char pointer to hwVersion string.

◆ rbGetIccid()

char * rbGetIccid ( void )

Get the iccid.

Returns: char pointer to iccid string.

◆ rbGetImei()

char * rbGetImei ( void )

Get the imei.

Returns: char pointer to imei string.

◆ rbGetSerialNumber()

char * rbGetSerialNumber ( void )

Get the serial number.

Returns: char pointer to serial number string.

◆ rbGetSignal()

int8_t rbGetSignal ( void )

Get the current signal strength from the modem.

The signal strength is returned in signal bars from 0 to 5:

0: No signal
5: Maximum signal strength

Note: A return value of -1 indicates an error occurred while communicating with the modem to retrieve the signal strength.

Returns: int8_t Signal strength in bars (0–5), or -1 on error.

◆ rbGetSimConnected()

bool rbGetSimConnected ( void )

Check if SIM card is present, communicating properly with, and has presented no errors in SIM transactions with the transceiver.

Returns

bool depicting SIM communicating correctly.

Note: This function will return false either if it received it from the modem or the function failed.

◆ rbPoll()

void rbPoll ( void )

Polling function that handles all incoming communication from the modem.

Note
This function is used in a asynchronous approach and will need to be called very frequently as it is non-blocking.

◆ rbReceiveLockAsync()

void rbReceiveLockAsync ( void )

Locks the receiving queue so that old messages aren't discarded when incoming ones arrive.

Note
Locking the queue will cause new messages to be rejected unless more space is made in the queue by acknowledging existing messages.

◆ rbReceiveMessage()

size_t rbReceiveMessage ( char ** buffer )

Listen for a mobile terminated message from the modem.

Parameters

buffer pointer to buffer of the stored MT messages.

Returns: size_t the length of the buffer minus the IMT CRC.

Note
this pointer is a pointer to a pointer to the MT queue buffer, it may be reused to store another MT. It must be copied if the application code needs to preserve it for a period of time.

◆ rbReceiveMessageAsync()

size_t rbReceiveMessageAsync ( char ** buffer )

Check if a valid message exists, stored at the head of the receiving queue.

Parameters

buffer pointer to buffer of the stored MT messages.

Returns: size_t the length of the buffer minus the IMT CRC.

Note
this pointer is a pointer to a pointer to the MT queue buffer, it may be reused to store another MT. It must be copied if the application code needs to preserve it for a period of time.

◆ rbReceiveMessageWithTopic()

size_t rbReceiveMessageWithTopic	(	char **	buffer,
		uint16_t	topic
	)

Listen for a mobile terminated message from the modem.

Parameters

buffer	pointer to buffer of the stored MT messages.
topic	uint16_t topic.

Returns: size_t the length of the buffer minus the IMT CRC.

Note
this pointer is a pointer to a pointer to the MT queue buffer, it may be reused to store another MT. It must be copied if the application code needs to preserve it for a period of time.

◆ rbReceiveUnlockAsync()

void rbReceiveUnlockAsync ( void )

Unlocks the receiving queue so that old messages are discarded to make space for incoming ones.

Note
The queue is unlocked by default, so there is no need to call this function unless rbReceiveLockAsync() was previously used.

◆ rbRegisterCallbacks()

void rbRegisterCallbacks ( const rbCallbacks_t * callbacks )

Registers a set of user-defined callbacks with the library.

This function will store the user provided callback functions, which will be called by the library during relevant events.

Parameters

callbacks Pointer to a structure containing function pointers to user-defined callbacks.

◆ rbResyncServiceConfig()

bool rbResyncServiceConfig ( void )

Requests a resynchronisation of the service configuration.

Call this method if the provisioning state has changed but the modem is still reporting outdated configuration data. This will clear the stored provisioning configuration and force a resync with the gateway.

This function must be called after the modem has been power-cycled. It is recommended to:

Power off the RockBLOCK 9704.
Power it back on.
Call rbBegin().
Then call this method.

Returns: true on success, false on failure.

◆ rbSendMessage()

bool rbSendMessage	(	const char *	data,
		const size_t	length,
		const int	timeout
	)

Send a mobile originated message from the modem on the default topic (244).

Parameters

data	pointer to data (message).
length	size_t of data length. (Max 100kB).
timeout	in seconds.

Returns: bool depicting success or failure.

◆ rbSendMessageAny()

bool rbSendMessageAny	(	uint16_t	topic,
		const char *	data,
		const size_t	length,
		const int	timeout
	)

Send a mobile originated message from the modem on any topic.

Parameters

topic	uint16_t topic.
data	pointer to data (message).
length	size_t of data length. (Max 100kB).
timeout	in seconds.

Returns: bool depicting success or failure.

◆ rbSendMessageAsync()

bool rbSendMessageAsync	(	uint16_t	topic,
		const char *	data,
		const size_t	length
	)

Queue a message to be sent.

Parameters

topic	uint16_t topic.
data	pointer to data (message).
length	size_t of data length. (Max 100kB).

Returns: bool depicting success or failure.

Note
This function will put a message in the outgoing queue to be handled by rbPoll().

◆ rbSendMessageCloudloop()

bool rbSendMessageCloudloop	(	cloudloopTopics_t	topic,
		const char *	data,
		const size_t	length,
		const int	timeout
	)

Send a mobile originated message from the modem on a cloudloop topic of choice.

Parameters

topic	uint16_t topic.
data	pointer to data (message).
length	size_t of data length. (Max 100kB).
timeout	in seconds.

Returns: bool depicting success or failure.

◆ rbUpdateFirmware()

bool rbUpdateFirmware	(	const char *	firmwareFile,
		updateProgressCallback	progress,
		void *	context
	)

Update 9704 firmware. This is a blocking call and will take approximately 10 minutes to upgrade, the updateProgressCallback is recommended.

Parameters

firmwareFile	path to the sxbin firmware files from Iridium
progress	pointer to the update progress callback, this can be NULL.
context	pointer to to some shared memory to pass to progress, this can be NULL.

Returns

bool true if the upgrade was successful.

Note: This is only defined if KERMIT was defined during the build.

◆ sendMoFromQueue()

static bool sendMoFromQueue ( const int timeout )

static

Send a queued message using mobile originated (MO) transmission.

Parameters

timeout Timeout duration in seconds.

Returns: true if message was sent successfully, false otherwise.

◆ sendMoFromQueueAsync()

static bool sendMoFromQueueAsync ( void )

static

Send a the modem a request to queue a message.

Returns: true if request was sent successfully, false otherwise.

◆ setApi()

static bool setApi ( void )

static

Set the modem API version.

Returns: true if successful, false otherwise.

◆ setSim()

static bool setSim ( void )

static

Initialise SIM card configuration.

Returns: true if SIM setup succeeded, false otherwise.

◆ setState()

static bool setState ( void )

static

Set operational state for the modem.

Returns: true if successful, false otherwise.

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ BASE64_TEMP_BUFFER

◆ RB9704_BAUD

◆ SERIAL_CONTEXT_SETUP_FUNC

Typedef Documentation

◆ updateProgressCallback

Enumeration Type Documentation

◆ cloudloopTopics_t

◆ rbMsgStatus_t

Function Documentation

◆ appendCrc()

◆ calculateCrc()

◆ checkMoQueue()

◆ checkProvisioning()

◆ decodeData()

◆ encodeData()

◆ getHwInfo()

◆ getSimStatus()

◆ listenForMt()

◆ rbAcknowledgeReceiveHeadAsync()

◆ rbBegin()

◆ rbBeginGpio()

◆ rbEnd()

◆ rbEndGpio()

◆ rbGetBoardTemp()

◆ rbGetCardPresent()

◆ rbGetFirmwareVersion()

◆ rbGetHwVersion()

◆ rbGetIccid()

◆ rbGetImei()

◆ rbGetSerialNumber()

◆ rbGetSignal()

◆ rbGetSimConnected()

◆ rbPoll()

◆ rbReceiveLockAsync()

◆ rbReceiveMessage()

◆ rbReceiveMessageAsync()

◆ rbReceiveMessageWithTopic()

◆ rbReceiveUnlockAsync()

◆ rbRegisterCallbacks()

◆ rbResyncServiceConfig()

◆ rbSendMessage()

◆ rbSendMessageAny()

◆ rbSendMessageAsync()

◆ rbSendMessageCloudloop()

◆ rbUpdateFirmware()

◆ sendMoFromQueue()

◆ sendMoFromQueueAsync()

◆ setApi()

◆ setSim()

◆ setState()