Functions

Functions
uint32_t	sd_ble_enable (uint32_t *p_app_ram_base)
	Enable the BLE stack. More...
uint32_t	sd_ble_cfg_set (uint32_t cfg_id, ble_cfg_t const *p_cfg, uint32_t app_ram_base)
	Add configurations for the BLE stack. More...
uint32_t	sd_ble_evt_get (uint8_t *p_dest, uint16_t *p_len)
	Get an event from the pending events queue. More...
uint32_t	sd_ble_uuid_vs_add (ble_uuid128_t const *p_vs_uuid, uint8_t *p_uuid_type)
	Add a Vendor Specific base UUID. More...
uint32_t	sd_ble_uuid_vs_remove (uint8_t *p_uuid_type)
	Remove a Vendor Specific base UUID. More...
uint32_t	sd_ble_uuid_decode (uint8_t uuid_le_len, uint8_t const *p_uuid_le, ble_uuid_t *p_uuid)
	Decode little endian raw UUID bytes (16-bit or 128-bit) into a 24 bit ble_uuid_t structure. More...
uint32_t	sd_ble_uuid_encode (ble_uuid_t const *p_uuid, uint8_t *p_uuid_le_len, uint8_t *p_uuid_le)
	Encode a ble_uuid_t structure into little endian raw UUID bytes (16-bit or 128-bit). More...
uint32_t	sd_ble_version_get (ble_version_t *p_version)
	Get Version Information. More...
uint32_t	sd_ble_user_mem_reply (uint16_t conn_handle, ble_user_mem_block_t const *p_block)
	Provide a user memory block. More...
uint32_t	sd_ble_opt_set (uint32_t opt_id, ble_opt_t const *p_opt)
	Set a BLE option. More...
uint32_t	sd_ble_opt_get (uint32_t opt_id, ble_opt_t *p_opt)
	Get a BLE option. More...

Detailed Description

Function Documentation

uint32_t sd_ble_cfg_set	(	uint32_t	cfg_id,
		ble_cfg_t const *	p_cfg,
		uint32_t	app_ram_base
	)

Add configurations for the BLE stack.

Parameters

[in]	cfg_id	Config ID, see BLE_CONN_CFGS, BLE_COMMON_CFGS, BLE_GAP_CFGS or BLE_GATTS_CFGS.
[in]	p_cfg	Pointer to a ble_cfg_t structure containing the configuration value.
[in]	app_ram_base	The start address of the application RAM region (APP_RAM_BASE). See sd_ble_enable for details about APP_RAM_BASE.

Note

The memory requirement for a specific configuration will not increase between SoftDevices with the same major version number.

If a configuration is set more than once, the last one set is the one that takes effect on sd_ble_enable.

Any part of the BLE stack that is NOT configured with sd_ble_cfg_set will have default configuration.

sd_ble_cfg_set may be called at any time when the SoftDevice is enabled (see sd_softdevice_enable) while the BLE part of the SoftDevice is not enabled (see sd_ble_enable).

Error codes for the configurations are described in the configuration structs.

Relevant Message Sequence Charts

BLE Stack Enable

Return values

NRF_SUCCESS	The configuration has been added successfully.
NRF_ERROR_INVALID_STATE	The BLE stack had already been initialized.
NRF_ERROR_INVALID_ADDR	Invalid or not sufficiently aligned pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid cfg_id supplied.
NRF_ERROR_NO_MEM	The amount of memory assigned to the SoftDevice by app_ram_base is not large enough to fit this configuration's memory requirement.

uint32_t sd_ble_enable

(

uint32_t *

p_app_ram_base

)

Enable the BLE stack.

Parameters

[in,out]

p_app_ram_base

Pointer to a variable containing the start address of the application RAM region (APP_RAM_BASE). On return, this will contain the minimum start address of the application RAM region required by the SoftDevice for this configuration.

Warning

After this call, the SoftDevice may generate several events. The list of events provided below require the application to initiate a SoftDevice API call. The corresponding API call is referenced in the event documentation. If the application fails to do so, the BLE connection may timeout, or the SoftDevice may stop communicating with the peer device.

• BLE_GAP_EVT_CONN_PARAM_UPDATE_REQUEST
• BLE_GAP_EVT_DATA_LENGTH_UPDATE_REQUEST
• BLE_GAP_EVT_PHY_UPDATE_REQUEST
• BLE_GAP_EVT_SEC_PARAMS_REQUEST
• BLE_GAP_EVT_SEC_INFO_REQUEST
• BLE_GAP_EVT_SEC_REQUEST
• BLE_GAP_EVT_AUTH_KEY_REQUEST
• BLE_GATTS_EVT_EXCHANGE_MTU_REQUEST
• BLE_EVT_USER_MEM_REQUEST
• BLE_L2CAP_EVT_CH_SETUP_REQUEST

Note

The memory requirement for a specific configuration will not increase between SoftDevices with the same major version number.

At runtime the IC's RAM is split into 2 regions: The SoftDevice RAM region is located between 0x20000000 and APP_RAM_BASE-1 and the application's RAM region is located between APP_RAM_BASE and the start of the call stack.

This call initializes the BLE stack, no BLE related function other than sd_ble_cfg_set can be called before this one.

Relevant Message Sequence Charts

BLE Stack Enable

Return values

NRF_SUCCESS	The BLE stack has been initialized successfully.
NRF_ERROR_INVALID_STATE	The BLE stack had already been initialized and cannot be reinitialized.
NRF_ERROR_INVALID_ADDR	Invalid or not sufficiently aligned pointer supplied.
NRF_ERROR_NO_MEM	One or more of the following is true: The amount of memory assigned to the SoftDevice by *p_app_ram_base is not large enough to fit this configuration's memory requirement. Check *p_app_ram_base and set the start address of the application RAM region accordingly. Dynamic part of the SoftDevice RAM region is larger then 64 kB which is currently not supported.
NRF_ERROR_RESOURCES	The total number of L2CAP Channels configured using sd_ble_cfg_set is too large.

uint32_t sd_ble_evt_get	(	uint8_t *	p_dest,
		uint16_t *	p_len
	)

Get an event from the pending events queue.

Parameters

[out]	p_dest	Pointer to buffer to be filled in with an event, or NULL to retrieve the event length. This buffer must be aligned to the extend defined by BLE_EVT_PTR_ALIGNMENT. The buffer should be interpreted as a ble_evt_t struct.
[in,out]	p_len	Pointer the length of the buffer, on return it is filled with the event length.

This call allows the application to pull a BLE event from the BLE stack. The application is signaled that an event is available from the BLE stack by the triggering of the SD_EVT_IRQn interrupt. The application is free to choose whether to call this function from thread mode (main context) or directly from the Interrupt Service Routine that maps to SD_EVT_IRQn. In any case however, and because the BLE stack runs at a higher priority than the application, this function should be called in a loop (until NRF_ERROR_NOT_FOUND is returned) every time SD_EVT_IRQn is raised to ensure that all available events are pulled from the BLE stack. Failure to do so could potentially leave events in the internal queue without the application being aware of this fact.

Sizing the p_dest buffer is equally important, since the application needs to provide all the memory necessary for the event to be copied into application memory. If the buffer provided is not large enough to fit the entire contents of the event, NRF_ERROR_DATA_SIZE will be returned and the application can then call again with a larger buffer size. The maximum possible event length is defined by BLE_EVT_LEN_MAX. The application may also "peek" the event length by providing p_dest as a NULL pointer and inspecting the value of *p_len upon return:

uint16_t len;
errcode = sd_ble_evt_get(NULL, &len);

Relevant Message Sequence Charts

Interrupt-driven Event Retrieval

Thread Mode Event Retrieval

Return values

NRF_SUCCESS	Event pulled and stored into the supplied buffer.
NRF_ERROR_INVALID_ADDR	Invalid or not sufficiently aligned pointer supplied.
NRF_ERROR_NOT_FOUND	No events ready to be pulled.
NRF_ERROR_DATA_SIZE	Event ready but could not fit into the supplied buffer.

uint32_t sd_ble_opt_get	(	uint32_t	opt_id,
		ble_opt_t *	p_opt
	)

Get a BLE option.

This call allows the application to retrieve the value of an option.

Parameters

[in]	opt_id	Option ID, see BLE_COMMON_OPTS and BLE_GAP_OPTS.
[out]	p_opt	Pointer to a ble_opt_t structure to be filled in.

Return values

NRF_SUCCESS	Option retrieved successfully.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied, check parameter limits and constraints.
NRF_ERROR_INVALID_STATE	Unable to retrieve the parameter at this time.
NRF_ERROR_BUSY	The BLE stack is busy or the previous procedure has not completed.
NRF_ERROR_NOT_SUPPORTED	This option is not supported.

uint32_t sd_ble_opt_set	(	uint32_t	opt_id,
		ble_opt_t const *	p_opt
	)

Set a BLE option.

This call allows the application to set the value of an option.

Parameters

[in]	opt_id	Option ID, see BLE_COMMON_OPTS, BLE_GAP_OPTS, and BLE_GATTC_OPTS.
[in]	p_opt	Pointer to a ble_opt_t structure containing the option value.

Return values

NRF_SUCCESS	Option set successfully.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_PARAM	Invalid parameter(s) supplied, check parameter limits and constraints.
NRF_ERROR_INVALID_STATE	Unable to set the parameter at this time.
NRF_ERROR_BUSY	The BLE stack is busy or the previous procedure has not completed.

uint32_t sd_ble_user_mem_reply	(	uint16_t	conn_handle,
		ble_user_mem_block_t const *	p_block
	)

Provide a user memory block.

Note

This call can only be used as a response to a BLE_EVT_USER_MEM_REQUEST event issued to the application.

Parameters

[in]	conn_handle	Connection handle.
[in]	p_block	Pointer to a user memory block structure or NULL if memory is managed by the application.

Relevant Message Sequence Charts

GATTS Queued Writes: Peer cancels operation

GATTS Queued Writes: App handled, one or more attributes require authorization

GATTS Queued Writes: App handled, no attributes require authorization

GATTS Queued Writes: Stack handled, one or more attributes require authorization

GATTS Queued Writes: Stack handled, no attributes require authorization

GATTS Queued Writes: Prepare Queue Full

Return values

NRF_SUCCESS	Successfully queued a response to the peer.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_BUSY	The stack is busy, process pending events and retry.
BLE_ERROR_INVALID_CONN_HANDLE	Invalid Connection Handle.
NRF_ERROR_INVALID_LENGTH	Invalid user memory block length supplied.
NRF_ERROR_INVALID_STATE	Invalid Connection state or no user memory request pending.

uint32_t sd_ble_uuid_decode	(	uint8_t	uuid_le_len,
		uint8_t const *	p_uuid_le,
		ble_uuid_t *	p_uuid
	)

Decode little endian raw UUID bytes (16-bit or 128-bit) into a 24 bit ble_uuid_t structure.

The raw UUID bytes excluding bytes 12 and 13 (i.e. bytes 0-11 and 14-15) of p_uuid_le are compared to the corresponding ones in each entry of the table of Vendor Specific base UUIDs to look for a match. If there is such a match, bytes 12 and 13 are returned as p_uuid->uuid and the index relative to BLE_UUID_TYPE_VENDOR_BEGIN as p_uuid->type.

Note

If the UUID length supplied is 2, then the type set by this call will always be BLE_UUID_TYPE_BLE.

Parameters

[in]	uuid_le_len	Length in bytes of the buffer pointed to by p_uuid_le (must be 2 or 16 bytes).
[in]	p_uuid_le	Pointer pointing to little endian raw UUID bytes.
[out]	p_uuid	Pointer to a ble_uuid_t structure to be filled in.

Return values

NRF_SUCCESS	Successfully decoded into the ble_uuid_t structure.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_LENGTH	Invalid UUID length.
NRF_ERROR_NOT_FOUND	For a 128-bit UUID, no match in the populated table of UUIDs.

uint32_t sd_ble_uuid_encode	(	ble_uuid_t const *	p_uuid,
		uint8_t *	p_uuid_le_len,
		uint8_t *	p_uuid_le
	)

Encode a ble_uuid_t structure into little endian raw UUID bytes (16-bit or 128-bit).

Note

The pointer to the destination buffer p_uuid_le may be NULL, in which case only the validity and size of p_uuid is computed.

Parameters

[in]	p_uuid	Pointer to a ble_uuid_t structure that will be encoded into bytes.
[out]	p_uuid_le_len	Pointer to a uint8_t that will be filled with the encoded length (2 or 16 bytes).
[out]	p_uuid_le	Pointer to a buffer where the little endian raw UUID bytes (2 or 16) will be stored.

Return values

NRF_SUCCESS	Successfully encoded into the buffer.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_INVALID_PARAM	Invalid UUID type.

uint32_t sd_ble_uuid_vs_add	(	ble_uuid128_t const *	p_vs_uuid,
		uint8_t *	p_uuid_type
	)

Add a Vendor Specific base UUID.

This call enables the application to add a Vendor Specific base UUID to the BLE stack's table, for later use with all other modules and APIs. This then allows the application to use the shorter, 24-bit ble_uuid_t format when dealing with both 16-bit and 128-bit UUIDs without having to check for lengths and having split code paths. This is accomplished by extending the grouping mechanism that the Bluetooth SIG standard base UUID uses for all other 128-bit UUIDs. The type field in the ble_uuid_t structure is an index (relative to BLE_UUID_TYPE_VENDOR_BEGIN) to the table populated by multiple calls to this function, and the UUID field in the same structure contains the 2 bytes at indexes 12 and 13. The number of possible 128-bit UUIDs available to the application is therefore the number of Vendor Specific UUIDs added with the help of this function times 65536, although restricted to modifying bytes 12 and 13 for each of the entries in the supplied array.

Note

Bytes 12 and 13 of the provided UUID will not be used internally, since those are always replaced by the 16-bit uuid field in ble_uuid_t.

If a UUID is already present in the BLE stack's internal table, the corresponding index will be returned in p_uuid_type along with an NRF_SUCCESS error code.

Parameters

[in]	p_vs_uuid	Pointer to a 16-octet (128-bit) little endian Vendor Specific base UUID disregarding bytes 12 and 13.
[out]	p_uuid_type	Pointer to a uint8_t where the type field in ble_uuid_t corresponding to this UUID will be stored.

Return values

NRF_SUCCESS	Successfully added the Vendor Specific base UUID.
NRF_ERROR_INVALID_ADDR	If p_vs_uuid or p_uuid_type is NULL or invalid.
NRF_ERROR_NO_MEM	If there are no more free slots for VS UUIDs.

uint32_t sd_ble_uuid_vs_remove

(

uint8_t *

p_uuid_type

)

Remove a Vendor Specific base UUID.

This call removes a Vendor Specific base UUID. This function allows the application to reuse memory allocated for Vendor Specific base UUIDs.

Note

Currently this function can only be called with a p_uuid_type set to BLE_UUID_TYPE_UNKNOWN or the last added UUID type.

Parameters

[in,out]

p_uuid_type

Pointer to a uint8_t where its value matches the UUID type in ble_uuid_t::type to be removed. If the type is set to BLE_UUID_TYPE_UNKNOWN, or the pointer is NULL, the last Vendor Specific base UUID will be removed. If the function returns successfully, the UUID type that was removed will be written back to p_uuid_type. If function returns with a failure, it contains the last type that is in use by the ATT Server.

Return values

NRF_SUCCESS	Successfully removed the Vendor Specific base UUID.
NRF_ERROR_INVALID_ADDR	If p_uuid_type is invalid.
NRF_ERROR_INVALID_PARAM	If p_uuid_type points to a non-valid UUID type.
NRF_ERROR_FORBIDDEN	If the Vendor Specific base UUID is in use by the ATT Server.

uint32_t sd_ble_version_get

(

ble_version_t *

p_version

)

Get Version Information.

This call allows the application to get the BLE stack version information.

Parameters

[out]

p_version

Pointer to a ble_version_t structure to be filled in.

Return values

NRF_SUCCESS	Version information stored successfully.
NRF_ERROR_INVALID_ADDR	Invalid pointer supplied.
NRF_ERROR_BUSY	The BLE stack is busy (typically doing a locally-initiated disconnection procedure).