|Device Manager API|
The DM subsystem implements device management procedures required by the stack. These procedures are partitioned by procedure category and device role (master or slave). The following procedures are implemented in DM:
DM procedures are implemented in support of the GAP profile when applicable.
The Device Manager controls all GAP behavior which includes the following:
For full API, see Device Manager API
The DM interface for advertising and device visibility configures, enables, and disables the advertising procedure. A device advertises when it wants to connect to or be discovered by other devices. Devices may also advertise to simply broadcast data.
This interface can only be used when operating as a slave or broadcaster.
This implementation handles Legacy and Extended Advertising including Periodic Advertising.
The DM scanning and device discovery interface configures, enables, and disables the scanning procedure. A device scans when it wants to discover or connect to other devices. A device may also scan simply to receive broadcast advertisements.
This interface can only be used when operating as a master or observer.
This implementation handles Legacy and Extended Scanning features including Synchronization on Periodic Advertisements.
Here is the state machine for DM Synchronization Behavior.
The DM connection management interface is used to open, accept, configure, and close connections. It is also used to read connection-related information such as the RSSI, channel map, and remote device information.
Here is the state machine for DM Connection Behavior
The DM local device management interface is used for initialization and reset, setting local parameters, sending vendor-specific commands, and LE GAP attribute management.
The DM security management interface is used for pairing, authentication, and encryption.
The DM Privacy interface is used by a master or slave device for private address resolution.
The DM PHY interface is used by a master or slave device to access the transmitter and receiver PHY settings for connections.
Figure 2 shows a master device performing a scan and a slave device advertising. The slave application first configures the advertising parameters by calling DmAdvSetInterval() to set the advertising interval and then DmAdvSetData() twice to set the advertising data and the scan response data. Then it calls DmAdvStart() to start advertising.
The master application configures the scan interval and then calls DmScanStart() to begin scanning. When advertisements are received the stack sends DM_SCAN_REPORT_IND events to the application. The master application stops scanning by calling DmScanStop(). The slave application stops advertising by calling DmAdvStop().
Figure 3 shows connection procedures between two devices. The scenario starts with the slave device advertising and the master device already having the address of the slave. The master application calls DmConnOpen() to initiate a connection. A connection is established and a DM_CONN_OPEN_IND is sent to the application from the stack on each device.
Next, the master performs a connection update by calling DmConnUpdate(). When the connection update is complete, a DM_CONN_UPDATE_IND is sent to the application from the stack on each device.
Next, the slave closes the connection by calling DmConnClose(). A DM_CONN_CLOSE_IND event is sent from the stack on each device when the connection is closed.
Figure 4 shows a pairing procedure between two devices. A connection is established between the two devices and the master application initiates pairing by calling DmSecPairReq(). The slave application receives a DM_SEC_PAIR_IND and calls DmSecPairRsp() to proceed with pairing. In this example, a PIN is used and a DM_SEC_AUTH_REQ_IND is sent to the application on each device to request a PIN. Each application responds with the PIN by calling DmSecAuthRsp().
In the next phase of pairing, the connection is encrypted and a DM_SEC_ENCRYPT_IND event is sent to the application on each device. Then key exchange begins. According to the Bluetooth specification, the slave device always distributes keys first. In this example, the slave distributes two keys and the master device distributes one. The slave sends its key data to the master. Note that when the slave sends its LTK, the slave application receives a DM_SEC_KEY_IND containing its own LTK. Then the master sends its key data to the slave. When the key exchange is completed successfully, a DM_SEC_PAIR_CMPL_IND event is sent to the application on each device.
Figure 5 shows an encryption procedure. In this example the slave device requests security by calling DmSecSlaveReq() to sends a slave security request message to the master. The stack on the master sends a DM_SEC_SLAVE_REQ_IND to the application. On receiving the event the master application determines that this is a bonded device and its LTK is available, so it calls DmSecEncryptReq() to enable encryption.
After the encryption procedure is initiated the slave application receives a DM_SEC_LTK_REQ_IND, requesting the LTK used with this master device. The application finds the key and calls DmSecLtkRsp(). The encryption procedure completes and a DM_SEC_ENCRYPT_IND event is sent to the application on each device.
Figure 6 shows a master device performing a scan and a slave device advertising with a private resolvable address. Before a master device can resolve a slave’s address, the devices must have paired and the master must have received the slave’s IRK during pairing.
The slave application first enables use of a private resolvable address by calling DmDevPrivStart(). If this is the first time since device reset that DmDevPrivStart() has been called, the application must wait for a DM_ADV_NEW_ADDR_IND before it starts advertising. Then it calls DmAdvStart() to start advertising.
The master application calls DmScanStart() to begin scanning. When advertisements are received the stack sends DM_SCAN_REPORT_IND events to the application. The master application calls DmPrivResolveAddr() with the address and address type from the scan report to resolve the address with the IRK it had received previously. After the slave application stops advertising, it can call DmDevPrivStop() to stop using a private resolvable address.
An ECC Key must be stored in the Device Manager before use in LE Secure Connections pairing. The Device Manager can generate an ECC, Elliptic Curve Cryptography, key, or the application can store an ECC Key in Non-Volatile storage. An ECC key cannot be generated until after the Device Manager reset is complete.
To generate an ECC Key, call the DmSecGenerateEccKeyReq() function after receiving the DM_RESET_CMPL_IND event. The DM_SEC_ECC_KEY_IND event will be called after the ECC Key generation is complete. The ECC Key can then be stored into the DM using the DmSecSetEccKey() function.
Note: For some applications, it may be desirable to skip ECC Key Generation and store an ECC key in Non Volatile storage. In these situations, the ECC key can be written to the Device Manager with DmSecSetEccKey() any time after the DM is reset, and before pairing begins.
Note: The Device Manager makes use of the Security service to generate and validate ECC keys. The Security service's ECC subsystem may need to be ported to an application’s target hardware or software framework for LE Secure Connections to operate properly.
The following figure shows the ECC Key generation scenario:
When using Out-of-Band (OOB) LE Secure Connections pairing, devices must generate random and confirm values. Furthermore, the devices must exchange random and confirm values through an out-of-band mechanism. At which point, the local and peer random and confirm values must be stored in the Device Manager before OOB pairing starts .
The OOB confirm calculation can be performed with DmSecCalcOobReq(), and requires an ECC, Elliptic Curve Cryptography, key. Therefore, on receipt of the ECC key indication event, DM_SEC_ECC_KEY_IND, an application may call the DmSecCalcOobReq() function to calculate an OOB confirm value. The result of the confirm calculation is returned via the DM_SEC_CALC_OOB_IND event.
After an application exchanges random and confirm values via an out-of-band mechanism with a peer, the application must store the local random and confirm values in the device manager. This is performed with the DmSecSetOob() function on receipt of the DM_SEC_AUTH_REQ_IND event. The following figure shows the OOB confirm calculation scenario: