nRF51 SDK
 All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups Pages
Events, type definitions and API calls

Module independent events, type definitions and API calls for the S110 SoftDevice. More...

Macros

#define BLE_EVTS_PTR_ALIGNMENT   4
 Required pointer alignment for BLE Events.
 

Enumerations

enum  BLE_COMMON_SVCS {
  SD_BLE_EVT_GET = BLE_SVC_BASE,
  SD_BLE_TX_BUFFER_COUNT_GET,
  SD_BLE_UUID_VS_ADD,
  SD_BLE_UUID_DECODE,
  SD_BLE_UUID_ENCODE,
  SD_BLE_VERSION_GET
}
 Common API SVC numbers. More...
 
enum  BLE_COMMON_EVTS { BLE_EVT_TX_COMPLETE = BLE_EVT_BASE }
 BLE Module Independent Event IDs. More...
 

Functions

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_tx_buffer_count_get (uint8_t *p_count)
 Get the total number of available application transmission buffers in the BLE stack. More...
 
uint32_t sd_ble_uuid_vs_add (ble_uuid128_t const *const p_vs_uuid, uint8_t *const p_uuid_type)
 Add a Vendor Specific UUID. More...
 
uint32_t sd_ble_uuid_decode (uint8_t uuid_le_len, uint8_t const *const p_uuid_le, ble_uuid_t *const 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 *const p_uuid, uint8_t *const p_uuid_le_len, uint8_t *const 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...
 

Data Structures

struct  ble_evt_tx_complete_t
 TX complete event. More...
 
struct  ble_common_evt_t
 Event structure for events not associated with a specific function module. More...
 
struct  ble_evt_hdr_t
 BLE Event header. More...
 
struct  ble_evt_t
 Common BLE Event type, wrapping the module specific event reports. More...
 
struct  ble_version_t
 Version Information. More...
 

Detailed Description

Enumeration Type Documentation

Enumerator
SD_BLE_EVT_GET 

Get an event from the pending events queue.

SD_BLE_TX_BUFFER_COUNT_GET 

Get the total number of available application transmission buffers from the stack.

SD_BLE_UUID_VS_ADD 

Add a Vendor Specific UUID.

SD_BLE_UUID_DECODE 

Decode UUID bytes.

SD_BLE_UUID_ENCODE 

Encode UUID bytes.

SD_BLE_VERSION_GET 

Get the local version information (company id, LMP Version, LMP Subversion).

Enumerator
BLE_EVT_TX_COMPLETE 

Transmission Complete.

Function Documentation

uint32_t sd_ble_evt_get ( uint8_t *  p_dest,
uint16_t *  p_len 
)
Parameters
[in]p_destPointer to buffer to be filled in with an event, or NULL to retrieve the event length. This buffer must be 4-byte aligned in memory.
[in,out]p_lenPointer 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 signalled that an event is available from the BLE Stack by the triggering of the SD_EVENT_IRQn interrupt (mapped to IRQ 22). 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_EVENT_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_EVENT_IRQn is raised to ensure that all available events are pulled from the 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. Please note that because of the variable length nature of some events, sizeof(ble_evt_t) will not always be large enough to fit certain events, and so it is the application's responsability to provide an amount of memory large enough so that the relevant event is copied in full. The application may "peek" the event length by providing p_dest as a NULL pointer and inspecting the value of *p_len upon return.

Note
The pointer supplied must be aligned to the extend defined by BLE_EVTS_PTR_ALIGNMENT
Returns
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_tx_buffer_count_get ( uint8_t *  p_count)

This call allows the application to obtain the total number of transmission buffers available for application data. Please note that this does not give the number of free buffers, but rather the total amount of them. The application has two options to handle its own application transmission buffers:

  • Use a simple arithmetic calculation: at boot time the application should use this function to find out the total amount of buffers available to it and store it in a variable. Every time a packet that consumes an application buffer is sent using any of the exposed functions in this BLE API, the application should decrement that variable. Conversely, whenever a BLE_EVT_TX_COMPLETE event is received by the application it should retrieve the count field in such event and add that number to the same variable storing the number of available packets. This mechanism allows the application to be aware at any time of the number of application packets available in the BLE stack's internal buffers, and therefore it can know with certainty whether it is possible to send more data or it has to wait for a BLE_EVT_TX_COMPLETE event before it proceeds.
  • Choose to simply not keep track of available buffers at all, and instead handle the BLE_ERROR_NO_TX_BUFFERS error by queueing the packet to be transmitted and try again as soon as a BLE_EVT_TX_COMPLETE event arrives.

The API functions that may consume an application buffer depending on the parameters supplied to them can be found below:

Parameters
[out]p_countPointer to a uint8_t which will contain the number of application transmission buffers upon successful return.
Returns
NRF_SUCCESS Number of application transmission buffers retrieved successfully.
NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
uint32_t sd_ble_uuid_vs_add ( ble_uuid128_t const *const  p_vs_uuid,
uint8_t *const  p_uuid_type 
)

This call enables the application to add a vendor specific UUID to the BLE stack's table, for later use 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. The way that this is accomplished is 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 (byte 12 and byte 13) corresponding to the TimeLow portion of the UUID. 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 the TimeLow bytes 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.
Parameters
[in]p_vs_uuidPointer to a 16-octet (128-bit) little endian Vendor Specific UUID disregarding the TimeLow (bytes 12 and 13) portion of it.
[out]p_uuid_typePointer where the type field in ble_uuid_t corresponding to this UUID will be stored.
Returns
NRF_SUCCESS Successfully added the Vendor Specific UUID.
NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
NRF_ERROR_NO_MEM If the size exceeds the number of free slots for VS UUIDs.
NRF_ERROR_INVALID_LENGTH If vs_uuid_count is 0.
NRF_ERROR_INVALID_ADDR if p_vs_uuids is NULL or invalid.
uint32_t sd_ble_uuid_decode ( uint8_t  uuid_le_len,
uint8_t const *const  p_uuid_le,
ble_uuid_t *const  p_uuid 
)

The raw UUID bytes excluding the TimeLow portion (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 UUIDs pouplated with sd_ble_uuid_vs_add 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_lenLength in bytes of the buffer pointed to by p_uuid_le (must be 2 or 16 bytes).
[in]p_uuid_lePointer pointing to little endian raw UUID bytes.
[in,out]p_uuidPointer to a ble_uuid_t structure to be filled in.
Returns
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 *const  p_uuid,
uint8_t *const  p_uuid_le_len,
uint8_t *const  p_uuid_le 
)
Note
The pointer to the destination buffer p_uuid_le may be NULL, in which case only the validitiy and size of p_uuid is computed.
Parameters
[in]p_uuidPointer to a ble_uuid_t structure that will be encoded into bytes.
[out]p_uuid_le_lenPointer to a uint8_t that will be filled with the encoded length (2 or 16 bytes).
[out]p_uuid_lePointer to a buffer where the little endian raw UUID bytes (2 or 16) will be stored.
Returns
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_version_get ( ble_version_t p_version)

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

Parameters
[in]p_versionPointer to ble_version_t structure to be filled in.
Returns
NRF_SUCCESS Version information stored successfully.
NRF_ERROR_INVALID_ADDR Invalid pointer supplied.
NRF_ERROR_BUSY The stack is busy (typically doing a locally-initiated disconnection procedure).