Pairing Module

The Pairing Module is used by applications to dynamically assign addresses to new nodes wanting to join a network. This module runs at the application level, so it uses the SWC API to create a dedicated schedule with its own connections.

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 occured 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.

Pairing Procedure

Pairing Phases

The Pairing Procedure will pass through three phases: the Authentication phase, the Identification phase and the Addressing phase.

Authentication Phase

The Authentication phase is essential for verifying the compatibility of the unpaired devices. It involves the verification of the devices’ Application Code. If the Application Codes do not match, the pairing procedure is aborted since the node’s response field for ‘authentication_action’ will reflect a failure. This mismatch indicates an incompatibility between the devices. On the other hand, if the Application Codes match, the next step in the pairing process is initiated, signifying that both devices and the application they run are compatible.

This phase helps to prevent the pairing of two devices that possess pairing capabilities but lack compatibility. For instance, it ensures that a mouse device cannot pair with a headset device, as such a pairing would be functionally inappropriate.

Identification Phase

The Identification phase involves the Node transmitting its device role and unique identifier number to the Coordinator. The Coordinator generates the Node address with the received unique identifier number. It then stores the Node’s device role, the generated Node address and the unique identifier number in its Pairing Discovery List. If the device role was already present in the Discovery List, it will be overwritten by the new Node address and unique identifier number. The Coordinator then proceeds to initiate the Addressing States.

Addressing phase

The Addressing phase involves the Coordinator sending to the Node device the network PAN ID, the Coordinator address and the newly generated Node address.

During this stage, the Pairing procedure should be completed successfully.

Pairing Module Wireless Configuration

When entering the Pairing Mode, a pre-defined wireless configuration is employed, overriding any previously used wireless configurations within the application. The handling of the wireless configuration is internally managed by the Pairing Module through the SWC API.

During the Pairing Procedure, the PAN ID for both devices is fixed at 0x000, as it is the reserved address specifically designated for the Pairing Module. The coordinator is assigned the fixed address of 0x01, while the node is assigned the fixed address of 0x02. These predetermined addresses ensure proper identification and communication between the devices within the pairing framework.

The Pairing Schedule follows an alternating pattern of transmissions between the Coordinator and Node, with each device taking turns every 3 milliseconds (ms).

The wireless configuration utilizes a single channel whose frequency is automatically selected based on the detected radio model:

SR1x20 radios (SR1020/SR1120): Frequency code 195 (7.987 GHz), which corresponds to IEEE 802.15.4 UWB channel 9. The define PAIRING_SR1x20_CHANNEL_FREQUENCY is used for SR1x20 radios.
SR1x10 radios (SR1010/SR1110): Frequency code 100 (4.096 GHz). The define PAIRING_SR1x10_CHANNEL_FREQUENCY is used for SR1x10 radios.

The pairing module automatically detects the radio model during initialization and selects the appropriate frequency within the supported range of each radio family.

Figure 68: Pairing Module’s Schedule

After the completion of the Pairing Procedure, the wireless configuration will be reset. As a result, the application must reconfigure Wireless Core using the newly obtained network information.