Application common modules

The following application common modules are meant to offer a simplified API for generic Connection Handover procedures and allow for quick integration into existing applications.

Handover application common module

Introduction

The Connection Handover application common module allows for quick integration of the Connection Handover feature in a Bluetooth LE application.

Integration

All the APIs referenced in this section are available in the Connection Handover application common module.

Connection handover requires a communication interface with the other devices involved in the connection handover process.

Perform the following steps to integrate Connection Handover in an application:

Add app_handover.c and app_handover.h from middleware\wireless\bluetooth\application\common\auto\ in the application project.
Initialize the Connection Handover application common module by calling AppHandover_Init().
Call AppHandover_ProcessA2ACommand() to handle connection handover commands received.
Call AppHandover_GenericCallback() in the application generic events callback to handle the following events:
- gHandoverAnchorSearchStarted_c
- gHandoverAnchorSearchStopped_c
- gHandoverAnchorMonitorEvent_c
- gHandoverSuspendTransmitComplete_c
- gHandoverGetComplete_c
- gGetConnParamsComplete_c
- gHandoverTimeSyncEvent_c
- gHandoverTimeSyncTransmitStateChanged_c
- gHandoverTimeSyncReceiveComplete_c
- gLlSkdReportEvent_c
- gInternalError_c
- gHandoverAnchorMonitorPacketEvent_c
- gHandoverAnchorMonitorPacketContinueEvent_c
- gHandoverFreeComplete_c
- gHandoverLlPendingData_c
- gHandoverConnectionUpdateProcedureEvent_c
- gHandoverApplyConnectionUpdateProcedureComplete_c
Call AppHandover_ConnectionCallback in the application connection events callback to handle the following events:
- gConnEvtHandoverConnected_c
- gHandoverDisconnected_c
To trigger connection handover call AppHandover_SetPeerDevice() followed by AppHandover_StartTimeSync()

Connection Handover application common module APIs

AppHandover_Init

bleResult_t AppHandover_Init(appHandoverEventCb_t pfAppEventCb, gapConnectionCallback_t pfConnectionCallback, appHandoverA2AInterfaceCb_t pfAppA2AInterfaceCb);

Description: Initializes the handover application common module.

Parameters:

pfAppEventCb: Application callback for handover events.
pfConnectionCallback: Connection callback for connection events.
pfAppA2AInterfaceCb: Communication callback for handover data.

Returns: bleResult_t

AppHandover_TimeSyncTransmit

bleResult_t AppHandover_TimeSyncTransmit(bleHandoverTimeSyncEnable_t enable);

Description: Enables/disables transmission of time synchronization information.

Parameters:

enable: Enables or disables the transmission of time synchronization parameters.

Returns: bleResult_t

AppHandover_TimeSyncReceive

bleResult_t AppHandover_TimeSyncReceive(bleHandoverTimeSyncEnable_t enable);

Description: Enables/disables reception of time synchronization information.

Parameters:

enable: Enables or disables the reception of time synchronization parameters.

Returns: bleResult_t

AppHandover_StartTimeSync

bleResult_t AppHandover_StartTimeSync(bool_t bTimeSyncForHandover);

Description: Triggers handover time synchronization.

Parameters:

bTimeSyncForHandover: TRUE if handover is following, FALSE if RSSI sniffing is following.

Returns: bleResult_t

AppHandover_TimeSyncTransmitSetParams

void AppHandover_TimeSyncTransmitSetParams(gapHandoverTimeSyncTransmitParams_t *pParams);

Description: Sets parameters for the transmission of time synchronization information.

Parameters:

pParams: Tx params.

Returns: None

AppHandover_TimeSyncReceiveSetParams

void AppHandover_TimeSyncReceiveSetParams(gapHandoverTimeSyncReceiveParams_t *pParams);

Description: Sets parameters for the reception of time synchronization information.

Parameters:

pParams: Rx params.

Returns: None

AppHandover_SetPeerDevice

void AppHandover_SetPeerDevice(deviceId_t deviceId);

Description: Sets the peer device for connection handover.

Parameters:

deviceId: Peer device identifier.

Returns: None

AppHandover_ProcessA2ACommand

void AppHandover_ProcessA2ACommand(uint8_t cmdId, uint32_t cmdLen, uint8_t *pCmdData);

Description: Processes handover commands.

Parameters:

cmdId: Command identifier.
cmdLen: Command length.
pCmdData: Command data.

Returns: None

AppHandover_SetPeerSkd

bleResult_t AppHandover_SetPeerSkd(uint8_t *pSkd, uint8_t nvmIndex);

Description: Sets the peer LL SKD for connection handover with advanced secure mode.

Parameters:

nvmIndex: Peer device NVM index.
pSkd:

A2A application common module

Introduction

The A2A (Anchor-to-Anchor) application common module implements a sample communication interface between devices involved in the connection handover process.

Integration

Perform the following steps to integrate A2A application common module in an application:

Add app_a2a_interface.c and app_a2a_interface.h from middleware\wireless\bluetooth\application\common\auto\ in the application project.
Initialize the Connection Handover application common module by calling A2A_Init().
Use A2A_SendCommand() as the communication callback for the Connection Handover application common module.
Use A2A_SendSetBondingDataCommand() in the application to send the bonding data from the connected anchor to the target anchor after pairing a new device is successful.

A2A application common module APIs

A2A_Init

bleResult_t A2A_Init(serial_handle_t pSerialHandle, appA2ADataIndicationCb_t pfDataIndCb);

Description: Performs initialization of the Anchor to Anchor serial communication.

Parameters:

pSerialHandle: Serial interface handle to be used for communication.
pfConnectionCallback: Application callback for received packets.

Returns: bleResult_t

A2A_SendCommand

void A2A_SendCommand(uint8_t opGroup, uint8_t opCode, uint8_t *pPayload, uint16_t len);

Description: Send packet over the Anchor to Anchor interface.

Parameters:

opGroup: Group identifier.
opCode: Command identifier.
pPayload: Pointer to command data.
len: Command length.

Returns: None

A2B application common module

Introduction

The A2B (Alice to Bob) application common module takes advantage of the EdgeLock to EdgeLock Key Exchange feature of the EdgeLock Secure Enclave integrated in the KW45 and KW47 to derive a special internal key (E2E key) that may be used to import/export encrypted key material between two devices. This may be used to allow for secure transfer of the key material between the anchors involved in the Connection Handover process. The LTK and IRK included in the bonding data are transferred as encrypted blobs that may only be decrypted by the EdgeLock Secure Enclave of the destination device.

Integration

Perform the following steps to integrate A2B application common module in an application:

Add app_a2b.c and app_a2b.h from middleware\wireless\bluetooth\application\common\auto\ in the application project.
Initialize the A2B application common module by calling A2B_Init().
One of the device involved in the Connection Handover process must be configured with the gA2BInitiator_d macro set to 1, the other must be configured with the gA2BInitiator_d macro set to 0. The initiator device triggers the EdgeLock-to-EdgeLock (E2E) key derivation and local IRK synchronization. Therefore, it should be started last.
After initialization the E2E key will be derived and the gSecLibFunctions.pfSecLib_ExportA2BBlob() and gSecLibFunctions.pfSecLib_ImportA2BBlob() functions can be used to export and import encrypted key material between the two devices.

A2B application common module APIs

A2B_Init

bleResult_t A2B_Init(appA2BEventCb_t pfAppEventCb, appA2BA2ACommInterfaceCb_t pfAppA2AInterfaceCb);

Description: Trigger the A2B feature initialization by generating the public key used for the Edgelock to Edgelock key derivation.

Parameters:

pfAppEventCb: Application callback functions for A2B events.
pfAppA2AInterfaceCb: Communication callback for A2B data.

Returns: bleResult_t - Result of the operation.

A2B_ProcessA2ACommand

void A2B_ProcessA2ACommand(uint8_t cmdId, uint32_t cmdLen, uint8_t *pCmdData);

Description: Process A2B commands received through the A2A interface.

Parameters:

cmdId: Command identifier.
cmdLen: Command length.
pCmdData: Command data.

Returns: None

A2B_FreeE2EKey

bleResult_t A2B_FreeE2EKey(void);

Description: Free the EdgeLock to EdgeLock key.

Parameters: None

Returns: bleResult_t - Result of the operation.