Logo
Link Labs LTE Interface Library
External host library for using Link Labs LTE modules.
top
Modules | Functions
lte_ifc_common

Detailed Description

Modules

 lte_ifc_ack_code
 A common result code for most functions.
 
 lte_ifc_irq_flags
 A vector of bits each indicating an event code.
 

Functions

int32_t lte_ifc_bootloader_mode (void)
 Force the module to reset and enter bootloader mode (takes a few seconds). More...
 
int32_t lte_ifc_debug_msg (uint8_t *chars, uint16_t len)
 Adds an ASCII message to the debug log. More...
 
int32_t lte_ifc_fota_check_at_boot_get (uint8_t *p_check_at_boot)
 Get when the module checks for the availability of a FOTA image. More...
 
int32_t lte_ifc_fota_check_at_boot_set (uint8_t check_at_boot)
 Set when the module checks for the availability of a FOTA image. More...
 
int32_t lte_ifc_fota_check_period_get (uint16_t *p_period)
 Get fota check period. More...
 
int32_t lte_ifc_fota_check_period_set (uint16_t period)
 Set how often the module checks for the availability of a FOTA image. More...
 
int32_t lte_ifc_fota_download (uint8_t *filename, uint16_t len)
 Retrieves a firmware-over-the-air image. More...
 
int32_t lte_ifc_fota_get_state (uint8_t *p_state, uint8_t *p_end_reason, uint32_t *p_num_blocks_received, uint32_t *p_num_requests_sent, bool *p_transfer_complete)
 Retrieves the state of a firmware-over-the-air download. More...
 
int32_t lte_ifc_get_assert_info (char *filename, uint32_t *p_line, uint32_t *p_uptime_sec)
 Gets assert info from the module, if any is available. More...
 
int32_t lte_ifc_mailbox_request (uint32_t *p_packet_id)
 Commands the module to check the downlink mailbox. This triggers an uplink transmission containing the mailbox request. More...
 
int32_t lte_ifc_message_send (uint8_t *buf, uint16_t len, uint8_t port, uint32_t *p_packet_id)
 Request the module to send an uplink message. More...
 
int32_t lte_ifc_message_status (uint8_t *p_new_status, uint32_t *p_packet_id, int32_t *p_packet_status, uint32_t *p_packet_time_in_queue_ms)
 Request Check for a status update on pending uplink transmissions. More...
 
int32_t lte_ifc_message_status_ext (uint8_t *p_new_status, uint32_t *p_packet_id, int32_t *p_packet_status, uint32_t *p_packet_time_in_queue_ms, int16_t *p_i16_rsrq_db, int16_t *p_i16_rsrp_dbm, uint32_t *p_u32_cell_id, uint16_t *p_u16_cell_tac)
 Request Check for a status update on pending uplink transmissions. Returns a more detailed status than lte_ifc_message_status(). More...
 
int32_t lte_ifc_network_info_get (uint32_t *p_u32_time_utc_last_rx_s, uint32_t *p_u32_time_utc_now_s, int8_t *p_i8_ofst_qhrs, int16_t *p_i16_rsrp_dbm, int16_t *p_i16_rsrq_db, uint32_t *p_u32_cell_id, uint16_t *p_u16_cell_tac)
 Get the latest snapshot of the LTE Network Info data. More...
 
int32_t lte_ifc_network_info_update (uint32_t *p_request_id)
 Command the module to search for a cell tower and update the LTE Network Info data. More...
 
int32_t lte_ifc_pwr_policy_get (uint8_t *p_pwr_policy)
 Get the module's power policy. More...
 
int32_t lte_ifc_pwr_policy_set (uint8_t pwr_policy)
 Set the module's power policy. More...
 
int32_t lte_ifc_receive_mode_get (uint8_t *p_rx_mode)
 Get received mode. More...
 
int32_t lte_ifc_receive_mode_set (uint8_t rx_mode)
 Set received mode. More...
 
int32_t lte_ifc_reset_mcu (void)
 Force the module to reset (if safe to do so). More...
 
int32_t lte_ifc_reset_mcu_force (void)
 Force the module to reset (unconditionally). More...
 
int32_t lte_ifc_retrieve_message (uint8_t *buf, uint16_t *size, uint8_t *port)
 Retrieves a downlink message received by the module. More...
 
int32_t lte_ifc_settings_delete (void)
 Delete all settings from flash storage, restoring factory defaults on all configurable values. More...
 
int32_t lte_ifc_settings_save (void)
 Save configurable settings to flash. More...
 
int32_t lte_ifc_trigger_assert (void)
 Triggers an assert (for test purposes only). More...
 
int32_t lte_ifc_version_get (lte_version_t *version)
 Get the module firmware version number. More...
 
int32_t lte_imei_get (uint64_t *p_imei)
 Reads out the IMEI of the device. More...
 

Function Documentation

◆ lte_ifc_bootloader_mode()

int32_t lte_ifc_bootloader_mode ( void  )

Force the module to reset and enter bootloader mode (takes a few seconds).

This function forces the module to reset and enter bootloader mode. The module only resets and enters bootloader mode if the success code is returned.

Returns
lte_ifc_ack_code

◆ lte_ifc_debug_msg()

int32_t lte_ifc_debug_msg ( uint8_t *  chars,
uint16_t  len 
)

Adds an ASCII message to the debug log.

Parameters
[in]charsASCII chars that make up the 'message'. Only printable characters are accepted: must be in range (0x20 <= x <= 0x7E).
[in]lenLength of the message (number of ASCII chars). This is needed since the message argument is not NULL-terminated. Max length is 32 chars.
Returns
lte_ifc_ack_code

◆ lte_ifc_fota_check_at_boot_get()

int32_t lte_ifc_fota_check_at_boot_get ( uint8_t *  p_check_at_boot)

Get when the module checks for the availability of a FOTA image.

Parameters
[out]p_check_at_bootSee set command for parameter details.
Returns
lte_ifc_ack_code

◆ lte_ifc_fota_check_at_boot_set()

int32_t lte_ifc_fota_check_at_boot_set ( uint8_t  check_at_boot)

Set when the module checks for the availability of a FOTA image.

Parameters
[in]check_at_bootShould a check be performed when the Link Labs MCU is reset? 0 = No 1 = Yes
Returns
lte_ifc_ack_code

◆ lte_ifc_fota_check_period_get()

int32_t lte_ifc_fota_check_period_get ( uint16_t *  p_period)

Get fota check period.

Parameters
[out]p_periodSee set command for parameter details.
Returns
lte_ifc_ack_code

◆ lte_ifc_fota_check_period_set()

int32_t lte_ifc_fota_check_period_set ( uint16_t  period)

Set how often the module checks for the availability of a FOTA image.

Parameters
[in]periodCheck period, in minutes. All uint16_t values are allowed: 0 = FOTA check is disabled 1-65535 = FOTA check every 1 to 65,535 minutes.
Returns
lte_ifc_ack_code

◆ lte_ifc_fota_download()

int32_t lte_ifc_fota_download ( uint8_t *  filename,
uint16_t  len 
)

Retrieves a firmware-over-the-air image.

Parameters
[in]filenameThe ASCII filename of the file to download. Does not need to be NULL-terminated, since the length is also passed in. Can only contain either alphanumeric characters or a character in the set {-._}.
[in]lenLength of the filename (number of ASCII chars). This is needed since the filename argument is not NULL-terminated.
Returns
lte_ifc_ack_code

◆ lte_ifc_fota_get_state()

int32_t lte_ifc_fota_get_state ( uint8_t *  p_state,
uint8_t *  p_end_reason,
uint32_t *  p_num_blocks_received,
uint32_t *  p_num_requests_sent,
bool *  p_transfer_complete 
)

Retrieves the state of a firmware-over-the-air download.

Parameters
[out]p_stateThe state of the FOTA process.
[out]p_end_reasonThe result of the last run FOTA process since power-on reset.
[out]p_num_blocks_receivedThe number of blocks received.
[out]p_num_requests_sentThe number of file requests sent.
[out]p_transfer_completeWhether the transfer is complete or not.
Returns
lte_ifc_ack_code

◆ lte_ifc_get_assert_info()

int32_t lte_ifc_get_assert_info ( char *  filename,
uint32_t *  p_line,
uint32_t *  p_uptime_sec 
)

Gets assert info from the module, if any is available.

Returns
lte_ifc_ack_code

◆ lte_ifc_mailbox_request()

int32_t lte_ifc_mailbox_request ( uint32_t *  p_packet_id)

Commands the module to check the downlink mailbox. This triggers an uplink transmission containing the mailbox request.

Parameters
[out]p_packet_idIf the success code is returned, this address will be populated with a packet id for the mailbox request.
Returns
lte_ifc_ack_code

◆ lte_ifc_message_send()

int32_t lte_ifc_message_send ( uint8_t *  buf,
uint16_t  len,
uint8_t  port,
uint32_t *  p_packet_id 
)

Request the module to send an uplink message.

Parameters
[in]bufA byte array containing the data payload.
[in]lenLength of the input buffer in bytes. Must be less than or equal to MAX_USER_UPLINK_LENGTH_BYTES.
[in]portReserved for future use.
[out]p_packet_idThe address pointed to by this pointer will be populated with a packet id for the uplink message.
Returns
lte_ifc_ack_code Note that the success code only indicates if the uplink message was succesfully queued for transmission, not whether it was successfully transmitted. In order to check the delivery status the lte_ifc_message_status function should be called.

◆ lte_ifc_message_status()

int32_t lte_ifc_message_status ( uint8_t *  p_new_status,
uint32_t *  p_packet_id,
int32_t *  p_packet_status,
uint32_t *  p_packet_time_in_queue_ms 
)

Request Check for a status update on pending uplink transmissions.

Parameters
[out]p_new_statusThis will be set to 1 if a new packet status is available, 0 otherwise.
[out]p_packet_idThe packet id that the status applies to. Only set if new_status is 1.
[out]p_packet_statuslte_ifc_ack_code indicating the result of the transmission attempt on the packet. Only set if new_status is 1.
[out]p_packet_time_in_queue_msHow long (in milliseconds) the packet was queued in the module, before it was able to be sent. Only set if new_status is 1.
Returns
lte_ifc_ack_code

◆ lte_ifc_message_status_ext()

int32_t lte_ifc_message_status_ext ( uint8_t *  p_new_status,
uint32_t *  p_packet_id,
int32_t *  p_packet_status,
uint32_t *  p_packet_time_in_queue_ms,
int16_t *  p_i16_rsrq_db,
int16_t *  p_i16_rsrp_dbm,
uint32_t *  p_u32_cell_id,
uint16_t *  p_u16_cell_tac 
)

Request Check for a status update on pending uplink transmissions. Returns a more detailed status than lte_ifc_message_status().

Parameters
[out]p_new_statusThis will be set to 1 if a new packet status is available, 0 otherwise.
[out]p_packet_idThe packet id that the status applies to. Only set if new_status is 1.
[out]p_packet_statuslte_ifc_ack_code indicating the result of the transmission attempt on the packet. Only set if new_status is 1.
[out]p_packet_time_in_queue_msHow long (in milliseconds) the packet was queued in the module, before it was able to be sent. Only set if new_status is 1.
[out]p_i16_rsrq_dbThe Reference Signal Received Quality (RSRQ) in dB, corresponding to the cell that the message was sent through. Only set if new_status is 1.
[out]p_i16_rsrp_dbmThe Reference Signal Received Power (RSRP) in dBm, corresponding to the cell that the message was sent through. Only set if new_status is 1.
[out]p_u32_cell_idThe 4-byte E-UTRAN Cell Id of the cell that the message was sent through. Only set if new_status is 1.
[out]p_u16_cell_tacThe Tracking Area Code of the cell that the message was sent through. Only set if new_status is 1.
Returns
lte_ifc_ack_code

◆ lte_ifc_network_info_get()

int32_t lte_ifc_network_info_get ( uint32_t *  p_u32_time_utc_last_rx_s,
uint32_t *  p_u32_time_utc_now_s,
int8_t *  p_i8_ofst_qhrs,
int16_t *  p_i16_rsrp_dbm,
int16_t *  p_i16_rsrq_db,
uint32_t *  p_u32_cell_id,
uint16_t *  p_u16_cell_tac 
)

Get the latest snapshot of the LTE Network Info data.

The module periodically obtains a structure of data fields known as the "Network Info". This structure contains all of the arguments of this function. Calling this function writes out the most up-to-date values of these fields. The info is updated any time the module interacts with the network (e.g. when sending uplink messages or checking its mailbox). If an update of the network info is desired, it can be requested using the lte_ifc_network_info_update() function, which will perform just the update and not send or received any data.

Parameters
[out]p_u32_time_utc_last_rx_sThe UTC time in seconds since the Unix epoch (e.g. seconds since 00:00 hours, Jan 1, 1970 UTC). This value is not the current time but instead the exact last time that was provided from the network. For example, if the last network attach was 45 seconds ago, then this time will differ from the current time by 45 seconds.
[out]p_u32_time_utc_now_sAn estimate of the current UTC time now. This time is computed by taking the last p_u32_time_utc_last_rx_s and adding to it an estimate of how much time has elapsed since that time was provided by the network. Note that since the module does not have an accurate clock, there can be significant error in this value if that last network attach was a long time ago. If accurate time is needed, it is recommended to first request a network time update (either by performing an uplink or downlink transaction or by calling lte_ifc_network_info_update()), and then waiting for that transaction to complete succesfully (using lte_ifc_message_status()), and then calling this function.
[out]p_i8_ofst_qhrsThe difference between UTC time and local time, in quarter-hour units. For example, a value of 20 corresponds to 5 hours difference between UTC and local.
[out]p_i16_rsrp_dbmThe Reference Signal Received Power (RSRP) in dBm.
[out]p_i16_rsrq_dbThe Reference Signal Received Quality (RSRQ) in dB.
[out]p_u32_cell_idThe 4-byte E-UTRAN Cell Id of the cell that the message was sent through.
[out]p_u16_cell_tacThe Tracking Area Code of the cell that the message was sent through.
Returns
lte_ifc_ack_code

◆ lte_ifc_network_info_update()

int32_t lte_ifc_network_info_update ( uint32_t *  p_request_id)

Command the module to search for a cell tower and update the LTE Network Info data.

Parameters
[out]p_request_idA request id, which can be used to query the result of the specific update request (e.g. success or failure).
Returns
lte_ifc_ack_code

◆ lte_ifc_pwr_policy_get()

int32_t lte_ifc_pwr_policy_get ( uint8_t *  p_pwr_policy)

Get the module's power policy.

Parameters
[out]p_pwr_policySee set command for parameter details.
Returns
lte_ifc_ack_code

◆ lte_ifc_pwr_policy_set()

int32_t lte_ifc_pwr_policy_set ( uint8_t  pwr_policy)

Set the module's power policy.

Parameters
[in]pwr_policy0 = On/Off with inactivity timer 1 = LTE Cat-M1 Power Savings Mode (PSM)
Returns
lte_ifc_ack_code

◆ lte_ifc_receive_mode_get()

int32_t lte_ifc_receive_mode_get ( uint8_t *  p_rx_mode)

Get received mode.

Parameters
[out]p_rx_modeReserved for future use.
Returns
lte_ifc_ack_code

◆ lte_ifc_receive_mode_set()

int32_t lte_ifc_receive_mode_set ( uint8_t  rx_mode)

Set received mode.

Parameters
[in]rx_modeReserved for future use.
Returns
lte_ifc_ack_code

◆ lte_ifc_reset_mcu()

int32_t lte_ifc_reset_mcu ( void  )

Force the module to reset (if safe to do so).

The module only resets if an ACK code is returned. If any other code is returned, the reset command was rejected. In this case, the function should be called again some time later (e.g. 1 second) until an ACK code is returned. The module should eventually return an ACK, although it may take as much as 30-45 seconds in the worst case.

Returns
lte_ifc_ack_code

◆ lte_ifc_reset_mcu_force()

int32_t lte_ifc_reset_mcu_force ( void  )

Force the module to reset (unconditionally).

This function is not recommended to be used regularly or as a first resort to reset. See lte_ifc_reset_mcu() - which should be used first instead. This function is provided as a last resort for rare cases. The LTE-M SoC needs to be properly shutdown rather than having its power cut abruptly. Failure to do so may cause corruption in rare cases.

Returns
lte_ifc_ack_code

◆ lte_ifc_retrieve_message()

int32_t lte_ifc_retrieve_message ( uint8_t *  buf,
uint16_t *  size,
uint8_t *  port 
)

Retrieves a downlink message received by the module.

Parameters
[out]bufThe buffer into which the received message will be placed. This buffer must be at least 1 byte larger than the maximum message size expected.
[in,out]sizeThe size of the output buffer. If the message is successfully retrieved, this will be set to the size of the message (not including the port).
[out]portThe port number associated with the message.
Returns
lte_ifc_ack_code

◆ lte_ifc_settings_delete()

int32_t lte_ifc_settings_delete ( void  )

Delete all settings from flash storage, restoring factory defaults on all configurable values.

Returns
lte_ifc_ack_code

◆ lte_ifc_settings_save()

int32_t lte_ifc_settings_save ( void  )

Save configurable settings to flash.

Returns
lte_ifc_ack_code

◆ lte_ifc_trigger_assert()

int32_t lte_ifc_trigger_assert ( void  )

Triggers an assert (for test purposes only).

Returns
lte_ifc_ack_code

◆ lte_ifc_version_get()

int32_t lte_ifc_version_get ( lte_version_t version)

Get the module firmware version number.

Parameters
[in,out]versionPass in a pointer to a lte_version_t data type. This data structure will be populated if the ack code indicates success.
Returns
lte_ifc_ack_code

◆ lte_imei_get()

int32_t lte_imei_get ( uint64_t *  p_imei)

Reads out the IMEI of the device.

Parameters
[out]p_imeiThe IMEI is returned in hex format. The IMEI is 15 decimal digits, so when represented in hex the length will be 13 hex digits. For example, an IMEI of 357353080026273 will be returned in uint64_t format as 0x00014502bf64f4a1.
Returns
lte_ifc_ack_code