System API

In this article:

Non hardware interface related API.

SDK version

voidSDKVersionGet(uint32_t * Major,uint32_t * Minor,uint32_t * Patch)

Get module ID string and part number

char *ModuleIDGet(void)

Returns the string of module ID in the format of "00xxxxxxxx Mx-2x" where 00xxxxxxxx is the module ID in hexadecimal string and Mx-2x is the module's part number.

Returns null if module ID is not available.

char *RegistrationCodeGet(void)

Returns the string of registration code.

Returns null if registration code is not available.

Application initialisation

User defined application initialisation logic.

voidAppInit(void)

Must be implemented by the application.

Will be called at device startup before any application jobs.

Time and job scheduling

intScheduleJob(ScheduledJobJob,time_t Time)

Reset the schedule for an existing job or add a new job.

Return 0 if succeeded and -1 if maximum number of jobs reached.

time_tASAP(void)

time_tNever(void)

time_tSecondsFromNow(unsigned Secs)

time_tMinutesFromNow(unsigned Mins)

time_tHoursFromNow(unsigned Hours)

time_tDaysFromNow(unsigned Days)

time_tOnGPIOWakeup(void)

GPIO wakeup event.

time_tOnPulseCounterEvent(void)

Pulse counter overflow event.

time_tOnLeuartReceive(void)

Leuart activity event.

time_tBeforeSatelliteTransmit(time_t After,time_t Before)

Return a time after After and before Before immediately prior to a satellite transmit opportunity.

Can be used to reduce latency between sensor reading and satellite transmission. If no opportunity is found between After and Before, then Before is returned.

typedef time_t(*ScheduledJob)(void)

The return value is the time at which the job should next run.

User message

#defineMAX_MESSAGE_SIZE20

Maximum size in bytes of individual transmit message.

int ScheduleMessage(const uint8_t * Message,size_t MessageSize)

Schedule a message of bytes of given size for transmission.

The maximum message size is given by MAX_MESSAGE_SIZE. Regardless of the value of MessageSize the number bytes consumed is MAX_MESSAGE_SIZE. Calling ScheduleMessage when the number of bytes returned by MessageBytesFree is less than MAX_MESSAGE_SIZE replaces an existing message in the queue. This may result in dropped messages. See also MessageBytesFree. Returns >=0 when succeeded or <0 if failed.

size_tMessageBytesFree(void)

Returns number of bytes remaining in internal queue, that is, the number of bytes that can be scheduled with ScheduleMessage.

voidSaveMessages(void)

Save all messages in the message queue to module's persistent storage.

Saved messages will be transmitted after reset.

voidMessageQueueClear(void)

Clear all messages in the message queue.

Device Control

time_t OnReceiveMessage (void)

Received user message event at returned time.

uint8_t * ReceiveMessage (int *size)

Retrieve the received user message. The length of received message is indicated in pointer size. Returns a pointer to the message if size is greater than 0 or NULL otherwise.

Delays

voidDelay(uint32_t mSec)

Delay for a number of milliseconds.

voidMicroSecondDelay(uint32_t uSec)

Delay for a number of microseconds.

voidSleep(uint32_t Sec)

Put the system in lower power mode for Sec seconds.

The calling job won't be interrupted by other jobs except for events while sleeping.

Time and location

intGNSSFix(void)

Get a time and location fix from GNSS.

Updates real-time clock and latitude and longitude values. Returns 0 if GNSS fix was correctly obtained and -1 otherwise.

boolHasValidGNSSFix(void)

Returns true if the system has obtained a valid time and location fix.

voidLocationGet(int32_t * Latitude,int32_t * Longitude,time_t * TimeStamp)

Returns last recorded latitude and longitude in fixed point format and timestamp of last fix.

Values are in degrees multiplied by 1e7.

voidLocationSet(int32_t Latitude,int32_t Longitude)

Set the location, Lat and Lon are in degrees multiplied by 1e7.

Location set may be overridden by GNSS fix if GNSS location fix is enabled.

time_tTimeGet(void)

Get current epoch time.

voidTimeSet(time_t Time)

Set current epoch time.

Temperature sensor

intTemperatureGet(float * Temperature)

Get the temperature inside the module in degrees Celsius Returns 0 if succeeded and -1 if failed.

LED control

voidLedTurnOn(void)

voidLedTurnOff(void)

voidLedToggle(void)

Battery voltage

intBatteryGetVoltage(uint32_t * mV)

Get the battery voltage in millivolt.

Returns 0 if succeeded and -1 if failed. If battery measurement is not supported then both voltage and the return value are 0.

System tick

uint32_tTickGet(void)

Get the current system tick (1000 ticks per second).

Error logging

intLogAdd(uint8_t ErrorCode,const void * Buffer,uint8_t BufferSize)

Log errors.

Error codes are user defined (0 - 127). The size can be 0 to log only the error code Returns 0 if logging succeeds and -1 if logging fails.

Suspend mode

voidSuspendModeEnable(bool Enable)

Change suspend mode state.

Set true to enable and false to disable. Has no effect if the system is already in the same state.

boolSuspendModeIsEnabled(void)

Returns true if suspend mode is enabled and false if disabled.

Network Information

Interface for user to perform system update, i.e Network information.

This is done in two steps: The first step is to transfter the content the internal storage, in one or multiple steps. The second step is to validate the content and perform requried system update from the internal storage. It is recommended that the entire update process done in a single task window.

enumSystemUpdateID

System update IDs.

intSystemUpdateStart(uint8_t ID,uint32_t Size,uint32_t Timeout)

Initiate a system update request, with update id, size, and maximum time in seconds for the entire update.

Update will be cancelled automatically when the Timeout expires. Returns 0 if the update starts successfully and -1 if ID is unknown, Size is too big or there is an ongoing update.

intSystemUpdateXfer(uint32_t Offset,const uint8_t * Buf,size_t BufSize)

Transfer the content to the module.

For best speed performance, it is recommended that Offset and BufSize are set to multiple of 2048 bytes where possible. Returns 0 if the transfer succeeds and -1 if it fails.

intSystemUpdateFinish(void)

Indicates the finish of the content transfer and perform the system update.

Update will only be performed if content validation is successful. Returns 0 if update succeeds and -1 if the validation fails.