Pairing Module API
Pairing Usage
To initiate the Pairing Procedure, the application needs to invoke either the pairing_coordinator_start() or the pairing_node_start() function from the Pairing API, depending on the device’s network role.
Both functions require the inclusion of the Pairing Configuration, Pairing Address, and Pairing Error structures.
In the case of the coordinator, it is also necessary to provide the Pairing Discovery List along with its corresponding size. The list size depends on the number of devices within the application’s network and cannot be less than PAIRING_DISCOVERY_LIST_MINIMUM_SIZE, that’s defined as 2.
For the node, in addition to the parameters, it is crucial to include the Pairing Device Role. This role is application-specific and allows the coordinator to store the node’s unique ID and address within the Pairing Discovery List.
Both functions yield a Pairing Event as a return value, which needs to be appropriately handled at the application level.
/** @brief Start a pairing procedure with the coordinator.
*
* @param[in] pairing_cfg Pairing configurations from the application.
* @param[out] pairing_assigned_address Pairing addresses exchanged during the pairing procedure.
* @param[in] discovery_list List of discovered devices used by the coordinator.
* @param[in] discovery_list_size The size of the discovery list.
* @param[out] pairing_err Pairing module error code.
* @return The pairing event.
*/
pairing_event_t pairing_coordinator_start(pairing_cfg_t *pairing_cfg,
pairing_assigned_address_t *pairing_assigned_address,
pairing_discovery_list_t *discovery_list, uint8_t discovery_list_size,
pairing_error_t *pairing_err);
/** @brief Start a pairing procedure with the node.
*
* @param[in] pairing_cfg Pairing configurations from the application.
* @param[out] pairing_assigned_address Pairing addresses exchanged during the pairing procedure.
* @param[in] device_role Application level device role from the node.
* @param[out] pairing_err Pairing module error code.
* @return The pairing event.
*/
pairing_event_t pairing_node_start(pairing_cfg_t *pairing_cfg, pairing_assigned_address_t *pairing_assigned_address,
uint8_t device_role, pairing_error_t *pairing_err);
/** @brief Get the SWC error that occurred during the pairing.
*
* @return The SWC error.
*/
swc_error_t pairing_get_swc_error(void);
Pairing Configuration
The pairing configuration structure is used to configure the Pairing Module. It is essential to populate all parameters within the structure to ensure proper function of the Pairing Module. Only the application callback is optional.
/** @brief Pairing parameters from the application.
*/
typedef struct pairing_cfg {
/*! Application code to prevent pairing unwanted devices. */
uint64_t app_code;
/*! The timeout period in seconds after which the pairing process will stop. */
uint16_t timeout_sec;
/*! Optional application callback function pointer. */
void (*application_callback)(void);
/*! A function pointer to the logic initiating context switches. */
void (*context_switch_callback)(void);
/*! Memory pool instance from which memory allocation is done. */
uint8_t *memory_pool;
/*! Memory pool size in bytes. */
uint32_t memory_pool_size;
} pairing_cfg_t;
Pairing Assigned Address
The Pairing Assigned Address structure serves as an output parameter that gets populated during the pairing procedure. Upon successful completion of the pairing process, the application can utilize the PAN ID, coordinator address, and node address from this structure to establish a wireless connection. For applications with multiple Nodes, the Node’s assigned address will correspond to the most recently paired device.
/** @brief Pairing addresses discoverable during the pairing procedure.
*/
typedef struct pairing_assigned_address {
/*! Coordinator's PAN ID. */
uint16_t pan_id;
/*! Coordinator's address. */
uint8_t coordinator_address;
/*! Node's assigned address. */
uint8_t node_address;
} pairing_assigned_address_t;
Pairing Discovery List
The pairing_coordinator_start() function requires the Discovery List structure and the discovery list size parameter as inputs.
The Discovery List serves a crucial purpose when an application involves multiple nodes. It is used by the coordinator to remember the different paired nodes inside the network.
As the application already possesses knowledge of the number of nodes it encompasses, it is responsible for creating the Discovery List locally and passing it through the pairing_coordinator_start() function, along with the corresponding list size.
Upon a successful pairing procedure, both the coordinator and the newly paired device will be added to the discovery list. This information can then be utilized by the application to configure wireless connections.
/** @brief Pairing list of discovered devices used by the coordinator.
*/
typedef struct pairing_discovery_list {
/*! Generated unique ID. */
uint64_t unique_id;
/*! Address of the node. */
uint8_t node_address;
} pairing_discovery_list_t;
Device Role
The Device Role parameter is utilized by the pairing_node_start() function and serves as the index within the Pairing Discovery List.
In any network, the Coordinator is assigned a “0” device role, thus always occupies the discovery list’s index 0. Hence, it is the responsibility of the application to assign a Device Role to each node, ensuring proper indexing within the discovery list.
Pairing Error
The Pairing Error parameter serves as a tool to communicate any critical issues that might occur during the Pairing Procedure, leading to an automatic pairing process abortion in such cases. It is essential for the user to handle the returned error by utilizing the pairing error parameter.
/** @brief Pairing API error structure.
*/
typedef enum pairing_error {
/*! No error occurred. */
PAIRING_ERR_NONE = 0,
/*! A NULL pointer is passed as argument. */
PAIRING_ERR_NULL_PTR,
/*! Discovery list size must be 2 or more. */
PAIRING_ERR_DISCOVERY_LIST_SIZE_TOO_SMALL,
/*! The application code is not configured. */
PAIRING_ERR_APP_CODE_NOT_CONFIGURED,
/*! Timeout is shorter than the minimum timeout duration. */
PAIRING_ERR_TIMEOUT,
/*! HAL has not been initialized at the application level. */
PAIRING_ERR_HAL_NOT_INITIALIZED,
/*! The node's device role conflicts with the coordinator's reserved role. */
PAIRING_ERR_DEVICE_ROLE,
/*! A wireless error occurred. */
PAIRING_ERR_WIRELESS_ERROR,
/*! Wireless configurations can't be changed while the SWC is running. */
PAIRING_ERR_CHANGING_WIRELESS_CONFIG_WHILE_RUNNING,
} pairing_error_t;
Pairing Events
Pairing Events are used to communicate the outcome of the Pairing Procedure back to the application. The application must then handle those events and act accordingly whether the pairing procedure was successful or not.
/** @brief Pairing event when exiting pairing procedure.
*/
typedef enum pairing_event {
/*! No event occurred. */
PAIRING_EVENT_NONE = 0,
/*! The pairing procedure is successful. */
PAIRING_EVENT_SUCCESS,
/*! The timeout was reached. */
PAIRING_EVENT_TIMEOUT,
/*! The application code is not valid. */
PAIRING_EVENT_INVALID_APP_CODE,
/*! The pairing procedure was aborted from an external source. */
PAIRING_EVENT_ABORT,
} pairing_event_t;
Pairing Application Callback
The Application callback is an optional feature aimed at preventing the user application from being blocked while the pairing procedure is underway.
With the Application callback, the application is given CPU control at the completion of each state, allowing it to handle background tasks such as button press detection or LED management.
It is advised for the user to exercise caution and refrain from implementing lengthy functions or delays within this callback, as this may increase the pairing procedure time.
To use this feature, the application must assign a function pointer to the application callback member of the pairing configuration structure before starting the Pairing Procedure.
Pairing Abort
The pairing abort feature provides a mechanism for externally stopping the pairing procedure and making it return an “Abort Event”.
This feature can be effectively combined with the application callback, granting the application the ability to initiate the cancellation of the pairing procedure if necessary.
To use this feature, the pairing_abort() function must be called while the Pairing Procedure is underway.
Timeout
As part of the pairing configuration, the user is required to define a timeout duration in seconds for the pairing procedure. This timeout duration is internally managed by the pairing module.
This timeout is checked between each step of the pairing process. Once the specified time limit is reached, the pairing procedure will automatically cease, and the application will be notified through the timeout event.
There is a minimum timeout, PAIRING_MINIMUM_TIMEOUT_SEC, define as 5 seconds, for the pairing procedure. This means that the timeout configured in pairing_cfg_t cannot be less than PAIRING_MINIMUM_TIMEOUT_SEC.
Application Code
The application code serves as a crucial security feature to prevent unauthorized pairing between incompatible devices. As all SPARK devices utilize the Wireless Core and have access to the pairing module, the possibility exists for any device to attempt pairing with others. By specifying an application code, users can limit the chances of undesired pairing by ensuring that only devices sharing the same application code can complete the pairing procedure successfully.
During the authentication phase, the coordinator will transmit its application code, which is then compared by the node to check for a match. If the codes match, the pairing continues. However, if there is a mismatch, the pairing procedure is promptly terminated, and the application is notified through the invalid application code event.
Unique ID
The unique ID comes from SPARK Radio’s 64-bit serial number. The serial number has been assigned during manufacturing and is unique among all SPARK transceivers of the same model. The serial number is automatically stored when starting a Pairing Procedure, no user action is needed.
Pairing Address Generation
During the pairing procedure, the coordinator generates its own address and the nodes’ address. Such addresses are generated using a CRC16-CITT scheme which uses the device’s unique ID as its seed. The following PAN ID are reserved: 0x000 and 0xFFF. The following addresses are reserved: 0x00 and 0xFF. If the address generator lands on a reserved address or an address already in use by another device in the network, it starts again using a different seed until a valid address is generated.