Logo
Link Labs Interface Library
External host library for using Link Lab's modules.
top
Enumerations | Functions | Variables
Symphony Link

Detailed Description

Communicate with a Symphony Link network.

Symphony Link mode allows the external host to communicate with Symphony Link networks, a dynamic IEEE 802.15.4 based LoRa wireless system built specifically for low power, wide-area connectivity.

Enumerations

enum  ll_downlink_mode { LL_DL_OFF = 0, LL_DL_ALWAYS_ON = 1, LL_DL_MAILBOX = 2 }
 
enum  ll_rx_state { LL_RX_STATE_NO_MSG = 0, LL_RX_STATE_RECEIVED_MSG = 1 }
 
enum  ll_state { LL_STATE_IDLE_CONNECTED = 1, LL_STATE_IDLE_DISCONNECTED = 2, LL_STATE_INITIALIZING = 3, LL_STATE_ERROR = -1 }
 
enum  ll_tx_state { LL_TX_STATE_TRANSMITTING = 1, LL_TX_STATE_SUCCESS = 2, LL_TX_STATE_ERROR = -1 }
 

Functions

int32_t ll_app_reg_get (uint8_t *is_registered)
 Get the end node's application token's registration status. More...
 
int32_t ll_config_get (uint32_t *net_token, uint8_t app_token[APP_TOKEN_LEN], enum ll_downlink_mode *dl_mode, uint8_t *qos)
 Get the current configuration of the module. More...
 
int32_t ll_config_set (uint32_t net_token, const uint8_t app_token[APP_TOKEN_LEN], enum ll_downlink_mode dl_mode, uint8_t qos)
 Set the current configuration of the module. More...
 
int32_t ll_connection_filter_get (uint8_t *p_f)
 Get the Connection Filter value. More...
 
int32_t ll_connection_filter_set (uint8_t f)
 Set the Connection Filter value. More...
 
int32_t ll_dl_band_cfg_get (llabs_dl_band_cfg_t *p_dl_band_cfg)
 Get the Downlink Band Configuration. More...
 
int32_t ll_dl_band_cfg_set (const llabs_dl_band_cfg_t *p_dl_band_cfg)
 Set the Downlink Band Configuration. More...
 
int32_t ll_encryption_key_exchange_request (void)
 Request a new key exchange between end node and gateway. More...
 
int32_t ll_get_state (enum ll_state *state, enum ll_tx_state *tx_state, enum ll_rx_state *rx_state)
 Gets the state of the module. More...
 
int32_t ll_mailbox_request (void)
 Request. More...
 
int32_t ll_message_send (uint8_t buf[], uint16_t len, bool ack, uint8_t port)
 Request Symphony MAC to send an acknowledged uplink message. More...
 
int32_t ll_net_info_get (llabs_network_info_t *net_info)
 Get the Network Info. More...
 
int32_t ll_retrieve_message (uint8_t *buf, uint16_t *size, uint8_t *port, int16_t *rssi, uint8_t *snr)
 Retrieves a downlink message received by the module. More...
 
int32_t ll_stats_get (llabs_stats_t *s)
 Get the Network Communication Statistics. More...
 
int32_t ll_system_time_get (llabs_time_info_t *time_info)
 Get the system time as number of seconds since the UNIX epoch 00:00:00 UTC on 1 January 1970 and the time the module last synchronized time with the gateway. More...
 
int32_t ll_system_time_sync (uint8_t sync_mode)
 Force the module to synchronize system time from the gateway. More...
 

Variables

const llabs_dl_band_cfg_t DL_BAN_AUS
 Australia DL Band Configuration. More...
 
const llabs_dl_band_cfg_t DL_BAN_BRA
 Brazil DL Band Configuration. More...
 
const llabs_dl_band_cfg_t DL_BAN_ETSI
 Europe (ETSI) DL Band Configuration. More...
 
const llabs_dl_band_cfg_t DL_BAN_FCC
 USA / Mexico DL Band Configuration. More...
 
const llabs_dl_band_cfg_t DL_BAN_NZL
 New Zealand DL Band Configuration. More...
 
uint8_t * uplink_message_buff
 An exposed buffer that will be used internally, but can also be used to hold uplink messages for 'll_message_send' to avoid double-buffering. The buffer has size 256 bytes. More...
 

Enumeration Type Documentation

Enumerator
LL_DL_OFF 

0x00

LL_DL_ALWAYS_ON 

0x01

LL_DL_MAILBOX 

0x02

Enumerator
LL_RX_STATE_NO_MSG 

0x00

LL_RX_STATE_RECEIVED_MSG 

0x01

enum ll_state
Enumerator
LL_STATE_IDLE_CONNECTED 

0x01

LL_STATE_IDLE_DISCONNECTED 

0x02

LL_STATE_INITIALIZING 

0x03

LL_STATE_ERROR 

0xFF

Enumerator
LL_TX_STATE_TRANSMITTING 

0x01

LL_TX_STATE_SUCCESS 

0x02

LL_TX_STATE_ERROR 

0xFF

Function Documentation

int32_t ll_app_reg_get ( uint8_t *  is_registered)

Get the end node's application token's registration status.

Parameters
[out]is_registered1=>registered, 0=>otherwise
Returns
0 - success, negative otherwise.
int32_t ll_config_get ( uint32_t *  net_token,
uint8_t  app_token[APP_TOKEN_LEN],
enum ll_downlink_mode dl_mode,
uint8_t *  qos 
)

Get the current configuration of the module.

Returns the configuration set by the user (or defaults if the user didn't set config yet). The config parameters may not be in effect yet. For example, this function will return the downlink mode that the user requested even though the module may not have entered that downlink mode yet.

Parameters
[out]net_tokenThe network token set for this module.
[out]app_tokenThe app token set for this module.
[out]dl_modeThe downlink mode requested for this module.
[out]qosThe quality of service level [0-15] requested for this module.
Returns
0 - success, negative otherwise.
int32_t ll_config_set ( uint32_t  net_token,
const uint8_t  app_token[APP_TOKEN_LEN],
enum ll_downlink_mode  dl_mode,
uint8_t  qos 
)

Set the current configuration of the module.

Sets the configuration values for the module. The module will only respond to values that have changed. For example, if the app token is set to the app token that the module already has, it will not try to re-register the app token.

The user should call this function whenever the module is powered on.

Parameters
[in]net_tokenThe network token set for this module. This determines what gateways the module will connect to. Use OPEN_NET_TOKEN if you don't have a particular network token.
[in]app_tokenThe app token set for this module. This is what registers your uplink messages with your Conductor account.
[in]dl_modeThe downlink mode for this module.
[in]qosThe quality of service level [0-15] for this module. The higher the quality of service, the faster uplink messages will be transmitted. Note that too many modules with a high quality of service may adversely affect network capacity.
Returns
0 - success, negative otherwise.
int32_t ll_connection_filter_get ( uint8_t *  p_f)

Get the Connection Filter value.

Parameters
[out]p_fThe current value is written to *p_f. 0 = Allow connections to any available devices 1 = Allow connection to Gateways only 2 = Allow connection to Repeaters only
Returns
0 - success, negative otherwise.
int32_t ll_connection_filter_set ( uint8_t  f)

Set the Connection Filter value.

Parameters
[in]fSame param ll_connection_filter_get().
Returns
0 - success, negative otherwise.
int32_t ll_dl_band_cfg_get ( llabs_dl_band_cfg_t p_dl_band_cfg)

Get the Downlink Band Configuration.

Parameters
[out]p_dl_band_cfgThe band cfg struct sent by the module.
Returns
0 - success, negative otherwise.
int32_t ll_dl_band_cfg_set ( const llabs_dl_band_cfg_t p_dl_band_cfg)

Set the Downlink Band Configuration.

Parameters
[in]p_dl_band_cfgThe band cfg struct sent by the module.
Returns
0 - success, negative otherwise.
int32_t ll_encryption_key_exchange_request ( void  )

Request a new key exchange between end node and gateway.

Returns
0 - success, negative otherwise.
int32_t ll_get_state ( enum ll_state state,
enum ll_tx_state tx_state,
enum ll_rx_state rx_state 
)

Gets the state of the module.

Returns the state of the module as three separate states: The general connection state, the state of the current uplink message, and the state of the current downlink message.

Parameters
[out]stateThe state of the connection. If the state is LL_STATE_ERROR, then this invalidates any of the other state variables.
[out]tx_stateThe state of the transmission. If no messages have been sent by the user since the last reboot, then this variable is invalid. Otherwise, it returns the result of the last transmission (or LL_TX_STATE_TRANSMITTING if the message is in progress).
[out]rx_stateThe state of the received message. Either the module has a downlink message ready for the user to pull out with ll_retrieve_message, or not. Once the user pulls out the message using ll_retrieve_message, this state will be reset.
Returns
0 - success, negative otherwise.
int32_t ll_mailbox_request ( void  )

Request.

Returns
0 - success, negative otherwise (Fails if module is not in MAILBOX mode).
int32_t ll_message_send ( uint8_t  buf[],
uint16_t  len,
bool  ack,
uint8_t  port 
)

Request Symphony MAC to send an acknowledged uplink message.

When the message finishes transmission the module will return to the idle state. Internally the function copies the message into a larger buffer. If you want to avoid having two buffers you can use the larger buffer (uplink_message_buff) to hold the message then call this function with that buffer.

Parameters
[in]bufbyte array containing the data payload.
[in]lenlength of the input buffer in bytes.
[in]ackWhether or not to request an ACK from the gateway.
[in]portThe port number to send to. Valid user ports are 0 through 127. Ports 128 through 255 are reserved for predefined protocols.
Returns
positive number of bytes queued, negative if an error.
int32_t ll_net_info_get ( llabs_network_info_t net_info)

Get the Network Info.

Parameters
[out]net_infoNetwork Info: All multi byte values are sent over in little-endian mode. Byte [0-3] : uint32_t network id (node) Byte [4-7] : uint32_t network id (gateway) Byte [8] : int8_t gateway channel Byte [9-12] : uint32_t gateway frequency Byte [13-16] : uint32_t Seconds elapsed since last beacon Rx'd Byte [17-18] : int16_t Downlink RSSI [dBm] Byte [19] : uint8_t Downlink SNR [dB] Byte [20-23] : uint32_t Connection Status (0=Unknown, 1=Disconnected, 2=Connected)
Returns
0 - success, negative otherwise.
int32_t ll_retrieve_message ( uint8_t *  buf,
uint16_t *  size,
uint8_t *  port,
int16_t *  rssi,
uint8_t *  snr 
)

Retrieves a downlink message received by the module.

This function should be called when the rx_state variable from the get_state function is `LL_RX_STATE_RECEIVED_MSG'.

Parameters
[out]bufThe buffer into which the received message will be placed. This buffer must be at least 4 bytes larger than the maximum message size expected (4 bytes will be used to get the RSSI, SNR, and port).
[in,out]sizeThe size of the output buffer. If the message is successfully retrieved, this will be set to the size of the message (without the RSSI, SNR, and port).
[out]portThe port number associated with the message.
[out]rssiThe rssi of the received message.
[out]snrThe snr of the received message.
Returns
0 - success, negative otherwise.
int32_t ll_stats_get ( llabs_stats_t s)

Get the Network Communication Statistics.

Parameters
[out]sThe stats struct sent by the module.
Returns
0 - success, negative otherwise.
int32_t ll_system_time_get ( llabs_time_info_t time_info)

Get the system time as number of seconds since the UNIX epoch 00:00:00 UTC on 1 January 1970 and the time the module last synchronized time with the gateway.

Parameters
[out]Thetime_info struct sent by the module.
Returns
0 - success, negative otherwise.
int32_t ll_system_time_sync ( uint8_t  sync_mode)

Force the module to synchronize system time from the gateway.

Note
worse-case delay for synchronization is the Info Block period which defaults to 8 seconds.
Parameters
[in]sync_mode0 - Time sync only when requested. 1 - Time sync opportunistically.
Returns
0 - success, negative otherwise.

Variable Documentation

const llabs_dl_band_cfg_t DL_BAN_AUS

Australia DL Band Configuration.

const llabs_dl_band_cfg_t DL_BAN_BRA

Brazil DL Band Configuration.

const llabs_dl_band_cfg_t DL_BAN_ETSI

Europe (ETSI) DL Band Configuration.

const llabs_dl_band_cfg_t DL_BAN_FCC

USA / Mexico DL Band Configuration.

const llabs_dl_band_cfg_t DL_BAN_NZL

New Zealand DL Band Configuration.

uint8_t* uplink_message_buff

An exposed buffer that will be used internally, but can also be used to hold uplink messages for 'll_message_send' to avoid double-buffering. The buffer has size 256 bytes.