rockblock_9704.c File Reference

#include "rockblock_9704.h"
#include "jspr_command.h"
#include "serial.h"
#include "imt_queue.h"
#include "third_party/cJSON/cJSON.h"
#include "third_party/base64/base64.h"
#include <stddef.h>
#include <errno.h>
#include <stdlib.h>
#include "crossplatform.h"
#include <unistd.h>
#include "kermit_io.h"

Macros
#define	IMT_MIN_TOPIC_ID   64U
#define	IMT_MAX_TOPIC_ID   65535U
#define	FIRMWARE_VERSION_STRING_LEN   13U

Functions
void	rbRegisterCallbacks (const rbCallbacks_t *callbacks)
	Registers a set of user-defined callbacks with the library.
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 bool	setApi (void)
static bool	setSim (void)
static bool	setState (void)
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.
static size_t	encodeData (const char *srcBuffer, const size_t srcLength, char *destBuffer, const size_t destLength)
static size_t	decodeData (const char *srcBuffer, const size_t srcLength, char *destBuffer, const size_t destLength)
static bool	appendCrc (uint8_t *buffer, size_t length)
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.
static bool	sendMoFromQueue (const int timeout)
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.
static bool	listenForMt (void)
static bool	sendMoFromQueueAsync (void)
bool	rbSendMessageAsync (uint16_t topic, const char *data, const size_t length)
	Queue a message to be sent.
size_t	rbReceiveMessageAsync (char **buffer)
	Check if a valid message exists, stored at the head of the receiving queue.
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	rbAcknowledgeReceiveHeadAsync (void)
	Acknowledge the head of the receiving queue by discarding it.
static bool	checkMoQueue (void)
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.
static bool	getHwInfo (jsprHwInfo_t *hwInfo)
char *	rbGetImei (void)
	Get the imei.
char *	rbGetHwVersion (void)
	Get the hardware version.
char *	rbGetSerialNumber (void)
	Get the serial number.
int8_t	rbGetBoardTemp (void)
	Get the board temperature.
static bool	getSimStatus (jsprSimStatus_t *simStatus)
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.
static bool	getFirmwareInfo (jsprFirmwareInfo_t *fwInfo)
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.
static uint16_t	calculateCrc (const uint8_t *buffer, const size_t bufferLength, const uint16_t initialCRC)
bool	rbEnd (void)
	Uninitialise/close the the serial connection.
static bool	checkProvisioning (uint16_t topic)
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.

Variables
int	messageReference
serialContext	context
enum serialState	serialState
static uint8_t	base64Buffer [2048U]
static uint8_t	crcBuffer [2U]
static char	firmwareVersion [13U]
jsprHwInfo_t	hwInfo
jsprSimStatus_t	simStatus
jsprFirmwareInfo_t	firmwareInfo
jsprMessageProvisioning_t	messageProvisioningInfo
uint32_t	messageLengthAsync = 0
uint16_t	moQueuedMessages = 0
uint16_t	mtQueuedMessages = 0
bool	Receivelock = false
bool	moDropped = false
bool	moSent = false
bool	mtDropped = false
bool	mtReceived = false
static const rbCallbacks_t *	rbCallbacks = NULL
static const uint16_t	CRC16Table [256]
struct k_data	kermitData
struct k_response	kermitResponse
int	kermitStatus = 0
unsigned char	i_buf [IBUFLEN+8]

Macro Definition Documentation

FIRMWARE_VERSION_STRING_LEN

#define FIRMWARE_VERSION_STRING_LEN   13U

IMT_MAX_TOPIC_ID

#define IMT_MAX_TOPIC_ID   65535U

IMT_MIN_TOPIC_ID

#define IMT_MIN_TOPIC_ID   64U

Function Documentation

appendCrc()

static bool appendCrc ( uint8_t *  buffer, size_t  length  )

static

calculateCrc()

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

static

checkMoQueue()

static bool checkMoQueue ( void  )

static

checkProvisioning()

static bool checkProvisioning ( uint16_t  topic )

static

decodeData()

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

static

encodeData()

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

static

getFirmwareInfo()

static bool getFirmwareInfo ( jsprFirmwareInfo_t *  fwInfo )

static

getHwInfo()

static bool getHwInfo ( jsprHwInfo_t *  hwInfo )

static

getSimStatus()

static bool getSimStatus ( jsprSimStatus_t *  simStatus )

static

listenForMt()

static bool listenForMt ( void  )

static

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:

1. Power off the RockBLOCK 9704.
2. Power it back on.
3. Call rbBegin().
4. 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

sendMoFromQueueAsync()

static bool sendMoFromQueueAsync ( void  )

static

setApi()

static bool setApi ( void  )

static

setSim()

static bool setSim ( void  )

static

setState()

static bool setState ( void  )

static

Variable Documentation

base64Buffer

uint8_t base64Buffer[2048U]

static

context

serialContext context

extern

CRC16Table

const uint16_t CRC16Table[256]

static

crcBuffer

uint8_t crcBuffer[2U]

static

firmwareInfo

jsprFirmwareInfo_t firmwareInfo

firmwareVersion

char firmwareVersion[13U]

static

hwInfo

jsprHwInfo_t hwInfo

i_buf

unsigned char i_buf[IBUFLEN+8]

kermitData

struct k_data kermitData

kermitResponse

struct k_response kermitResponse

kermitStatus

int kermitStatus = 0

messageLengthAsync

uint32_t messageLengthAsync = 0

messageProvisioningInfo

jsprMessageProvisioning_t messageProvisioningInfo

messageReference

int messageReference

extern

moDropped

bool moDropped = false

moQueuedMessages

uint16_t moQueuedMessages = 0

moSent

bool moSent = false

mtDropped

bool mtDropped = false

mtQueuedMessages

uint16_t mtQueuedMessages = 0

mtReceived

bool mtReceived = false

rbCallbacks

const rbCallbacks_t* rbCallbacks = NULL

static

Receivelock

bool Receivelock = false

serialState

enum serialState serialState

extern

simStatus

jsprSimStatus_t simStatus