BLE Device Manager

Note

When running with the S130 SoftDevice, the Device Manager can be used for either the central or the peripheral role, decided at compile time. Currently, it cannot be used to handle bonds for both roles concurrently.

Device Manager manages all bonded devices managing all contexts for a bonded device. Various contexts are identified under

• Device Context: Bonding and peer identification information.
• Service Context: GATT Server's configuration for peer device is a typical example for service context. Module has provision to store GATT client related information as well, but not completely implemented. In case application does not implement GATT Server or Client, DM_PROTOCOL_CNTXT_NONE can be used when registering the application to indicate respective service context are not used. See Service/Protocol Types for details.
• Application Context: In case application requires to store application specific data per bonded device, it can do so by requesting Device Manager to store application context for the device. Application context is not permitted to be set for a non bonded device.

Device Manager can be configured at compile time to suit the application. Configuration includes number of active peers, bonded device module should support, number of CCCDs in GATT Server, Application context size etc. Active refers to maximum connections that the module wants to be able to manage concurrently. Configurable parameters are described in device_manager_cnfg.h.

Initialization

Device manager should be initialized before using any of module APIs. Initialization should be done once.

Note

In case deleting all device context is requested during initialization DM_EVT_DEVICE_CONTEXT_DELETED events are not generated for each of the devices stored persistently.

pstorage module shall be initialized before initializing this module. Application shall be

uint32_t retval;
dm_init_param_t init_param;

// Indicate if all context in persistent memory is to be cleared or not on start-up.
init_param.clear_persistent_data = true.

// Initialize device manager
retval = dm_init(&init_param);

if(retval == NRF_SUCCESS)
{
    // Module successfully initialized.
}
else
{
    // Module initialization failed. Take corrective action.
}

Associated Events

None. Asynchronous events from module are only received after module is successfully initialized and registered.

Associated Configuration Parameters

None. Initialization procedure is unaltered by configuration of the module.

Registration

The application should register with the device manager before using any other APIs of the module. Registration is done using the dm_register API. Sample code below demonstrate registration procedure with the module.

uint32_t                   retval;
dm_application_param_t     param;
dm_application_instance_t  appl_id;

// Set notification callback in registration parameter.
param.ntf_cb = example_cm_event_handler;

// Indicate no service type being used by application.
param.service_type = DM_PROTOCOL_CNTXT_NONE;

// Set security parameters to be used for establishing bond with peer.
memset (&param.sec_param, 0, sizeof(ble_gap_sec_params_t));
param.sec_param.bond         = 1;                    // Bonding set to 1, meaning bond should be established.
param.sec_param.mitm         = 1;                    // MITM protection needed.
param.sec_param.io_caps      = BLE_GAP_IO_CAPS_NONE; // No Input, No Output.
param.sec_param.oob          = 0;                    // No out of band information used.
param.sec_param.min_key_size = 16;                   // Minimum key size.
param.sec_param.max_key_size = 16;                   // Maximum key size.
param.sec_param.kdist_periph.enc = 1;                // Exchange encryption information of peripheral. (Parameter is applicable only for GAP Central role.)
param.sec_param.kdist_periph.id  = 1;                // Exchange identification information of peripheral.(Parameter is applicable only for GAP Central role.)

// Request registration with device manager.
retval = dm_register(&param);

if(retval == NRF_SUCCESS)
{
    // Successfully registered with module.
    // 'appl_id' identifies the application, to be remembered for subsequent procedures.
}
else
{
    // Registration failed. Take corrective action.
}

Associated Events

None. Asynchronous events from module are only received after module is successfully initialized and registered. Once successfully registered, application will have one or more events associated with each procedure it requests. Few events could be triggered due to an action on the peer. An example of such an event is the disconnection event DM_EVT_DISCONNECTION.

Associated Configuration Parameters

1. DEVICE_MANAGER_MAX_APPLICATIONS: Number of applications that can be registered with the module is determined by this configuration parameter. Currently only one application can be registered with the connection manager.
2. DEVICE_MANAGER_MAX_CONNECTIONS: Maximum number of concurrent connection for which security procedures and contexts are managed by the application.

   Note

   for GAP Central, this should not exceed 8 and for GAP Peripheral this should not exceed 1.

3. DEVICE_MANAGER_MAX_BONDS: Maximum number of bonds that the module should manage for the application.

   Note

   Currently module cannot handle more than 10 bonds.