| S132 SoftDevice v3.0.0 |

Choose documentation: | nRF5 SDK | S130 SoftDevice API | S132 SoftDevice API | S212 SoftDevice API | S332 SoftDevice API

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

## Functions
uint32_t | sd_ble_enable (ble_enable_params_t *p_ble_enable_params, uint32_t *p_app_ram_base)
| Enable 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_tx_packet_count_get (uint16_t conn_handle, uint8_t *p_count)
| Get the total number of available guaranteed application transmission packets for a particular connection. 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_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_enable | ( | ble_enable_params_t * | p_ble_enable_params,
|  | uint32_t * | p_app_ram_base
| ) |  |

Enable the BLE stack.

Parameters

  [in,out] | p_ble_enable_params | Pointer to ble_enable_params_t
  [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. Calling sd_ble_enable() with *p_app_ram_base set to 0 can be used during development to find out how much memory a specific configuration will need.

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 other BLE related function 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_INVALID_LENGTH | One or more of the following is true: The specified Attribute Table size is too small. The minimum acceptable size is defined by BLE_GATTS_ATTR_TAB_SIZE_MIN. The specified Attribute Table size is not a multiple of 4. The device name length is invalid (must be between 0 and BLE_GAP_DEVNAME_MAX_LEN). The device name length is too long for the given Attribute Table.
  NRF_ERROR_INVALID_PARAM | One or more of the following is true: Incorrectly configured VS UUID count. Invalid connection count parameters. Invalid device name location (vloc). Invalid device name security mode. Invalid maximum ATT_MTU size, see ble_gatt_enable_params_t::att_mtu.
  NRF_ERROR_NOT_SUPPORTED | Device name security mode is not supported.
  NRF_ERROR_NO_MEM | 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.
  NRF_ERROR_CONN_COUNT | The requested number of connections exceeds the maximum supported by the SoftDevice. Please refer to the SoftDevice Specification for more information on role configuration.

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_EVTS_PTR_ALIGNMENT.
  [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_EVTS_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.

Relevant Message Sequence Charts

  Bonding: Passkey Entry with static passkey
  Connection Bandwidth Configuration

Parameters

  [in] | opt_id | Option ID, see BLE_COMMON_OPTS and BLE_GAP_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_tx_packet_count_get | ( | uint16_t | conn_handle,
|  | uint8_t * | p_count
| ) |  |

Get the total number of available guaranteed application transmission packets for a particular connection.

This call allows the application to obtain the total number of guaranteed application transmission packets available for a connection. Please note that this does not return the number of free packets, but rather the total amount of them for that particular connection. The application has two options to handle transmitting application packets:

- Use a simple arithmetic calculation: after connection creation time the application should use this function to find out the total amount of guaranteed packets available to it and store it in a variable. Every time a packet is successfully queued for a transmission on this connection using any of the exposed functions in this BLE API, the application should decrement that variable. Conversely, whenever a BLE_EVT_TX_COMPLETE event with the conn_handle matching the particular connection 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 guaranteed packets. This mechanism allows the application to be aware at any time of the number of guaranteed application packets available for each of the active connections, 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. The application can still pursue transmissions when the number of guaranteed application packets available is smaller than or equal to zero, but successful queuing of the tranmsission is not guaranteed.
- Choose to simply not keep track of available packets at all, and instead handle the BLE_ERROR_NO_TX_PACKETS 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 packet depending on the parameters supplied to them can be found below:

- sd_ble_gattc_write (write without response only)
- sd_ble_gatts_hvx (notifications only)
- sd_ble_l2cap_tx (all packets)

Parameters

  [in] | conn_handle | Connection handle.
    [out] | p_count | Pointer to a uint8_t which will contain the number of application transmission packets upon successful return. Relevant Message Sequence Charts
    App TX Packet Management

Return values

  NRF_SUCCESS | Number of application transmission packets retrieved successfully.
  BLE_ERROR_INVALID_CONN_HANDLE | Invalid Connection Handle.
  NRF_ERROR_INVALID_ADDR | Invalid pointer supplied.

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,out] | p_block | Pointer to a user memory block structure.

Relevant Message Sequence Charts

  GATTS Queued Writes: App handled, 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.
  BLE_ERROR_INVALID_CONN_HANDLE | Invalid Connection Handle.
  NRF_ERROR_INVALID_STATE | Invalid Connection state or no execute write request pending.
  NRF_ERROR_BUSY | The BLE stack is busy. Retry at later time.

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 UUIDs populated 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_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 indices 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 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 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_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).