Bluetooth API

This is the full set of available Bluetooth APIs. It’s important to note that the set that will in practice be available for the application depends on the exact Kconfig options that have been chosen, since most of the Bluetooth functionality is build-time selectable. E.g. any connection-related APIs require CONFIG_BLUETOOTH_CONN and any BR/EDR (Bluetooth Classic) APIs require CONFIG_BLUETOOTH_BREDR.

Generic Access Profile (GAP)

enum [anonymous]__anonymous0

Advertising options

Values:

BT_LE_ADV_OPT_NONE = 0

Convenience value when no options are specified.

BT_LE_ADV_OPT_CONNECTABLE = BIT(0)

Advertise as connectable. Type of advertising is determined by providing SCAN_RSP data and/or enabling local privacy support.

typedef bt_ready_cb_t

Callback for notifying that Bluetooth has been enabled.

Parameters
  • err: zero on success or (negative) error code otherwise.

typedef bt_le_scan_cb_t

Callback type for reporting LE scan results.

A function of this type is given to the bt_le_scan_start() function and will be called for any discovered LE device.

Parameters
  • addr: Advertiser LE address and type.
  • rssi: Strength of advertiser signal.
  • adv_type: Type of advertising response from advertiser.
  • data: Buffer containig advertiser data.

typedef bt_br_discovery_cb_t

Callback type for reporting BR/EDR discovery (inquiry) results.

A callback of this type is given to the bt_br_discovery_start() function and will be called at the end of the discovery with information about found devices populated in the results array.

Parameters
  • results: Storage used for discovery results
  • count: Number of valid discovery results.

int bt_enable(bt_ready_cb_t cb)

Enable Bluetooth.

Enable Bluetooth. Must be the called before any calls that require communication with the local Bluetooth hardware.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • cb: Callback to notify completion or NULL to perform the enabling synchronously.

int bt_le_adv_start(const struct bt_le_adv_param *param, const struct bt_data *ad, size_t ad_len, const struct bt_data *sd, size_t sd_len)

Start advertising.

Set advertisement data, scan response data, advertisement parameters and start advertising.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • param: Advertising parameters.
  • ad: Data to be used in advertisement packets.
  • ad_len: Number of elements in ad
  • sd: Data to be used in scan response packets.
  • sd_len: Number of elements in sd

int bt_le_adv_stop(void)

Stop advertising.

Stops ongoing advertising.

Return
Zero on success or (negative) error code otherwise.

int bt_le_scan_start(const struct bt_le_scan_param *param, bt_le_scan_cb_t cb)

Start (LE) scanning.

Start LE scanning with given parameters and provide results through the specified callback.

Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error
Parameters
  • param: Scan parameters.
  • cb: Callback to notify scan results.

int bt_le_scan_stop(void)

Stop (LE) scanning.

Stops ongoing LE scanning.

Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error

int bt_le_oob_get_local(struct bt_le_oob *oob)

Get LE local Out Of Band information.

This function allows to get local information that are useful for Out Of Band pairing or connection creation process.

If privacy is enabled this will result in generating new Resolvable Private Address that is valid for CONFIG_BLUETOOTH_RPA_TIMEOUT seconds. This address will be used for advertising, active scanning and connection creation.

Parameters
  • oob: LE related information

int bt_br_discovery_start(const struct bt_br_discovery_param *param, struct bt_br_discovery_result *results, size_t count, bt_br_discovery_cb_t cb)

Start BR/EDR discovery.

Start BR/EDR discovery (inquiry) and provide results through the specified callback. When bt_br_discovery_cb_t is called it indicates that discovery has completed. If more inquiry results were received during session than fits in provided result storage, only ones with highest RSSI will be reported.

Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error
Parameters
  • param: Discovery parameters.
  • results: Storage for discovery results.
  • count: Number of results in storage. Valid range: 1-255.
  • cb: Callback to notify discovery results.

int bt_br_discovery_stop(void)

Stop BR/EDR discovery.

Stops ongoing BR/EDR discovery. If discovery was stopped by this call results won’t be reported

Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error

int bt_br_oob_get_local(struct bt_br_oob *oob)

Get BR/EDR local Out Of Band information.

This function allows to get local controller information that are useful for Out Of Band pairing or connection creation process.

Parameters
  • oob: Out Of Band information

static int bt_addr_to_str(const bt_addr_t *addr, char *str, size_t len)

Converts binary Bluetooth address to string.

Return
Number of successfully formatted bytes from binary address.
Parameters
  • addr: Address of buffer containing binary Bluetooth address.
  • str: Address of user buffer with enough room to store formatted string containing binary address.
  • len: Length of data to be copied to user string buffer. Refer to BT_ADDR_STR_LEN about recommended value.

static int bt_addr_le_to_str(const bt_addr_le_t *addr, char *str, size_t len)

Converts binary LE Bluetooth address to string.

Return
Number of successfully formatted bytes from binary address.
Parameters
  • addr: Address of buffer containing binary LE Bluetooth address.
  • str: Address of user buffer with enough room to store formatted string containing binary LE address.
  • len: Length of data to be copied to user string buffer. Refer to BT_ADDR_LE_STR_LEN about recommended value.

int bt_br_set_discoverable(bool enable)

Enable/disable set controller in discoverable state.

Allows make local controller to listen on INQUIRY SCAN channel and responds to devices making general inquiry. To enable this state it’s mandatory to first be in connectable state.

Return
Negative if fail set to requested state or requested state has been already set. Zero if done successfully.
Parameters
  • enable: Value allowing/disallowing controller to become discoverable.

int bt_br_set_connectable(bool enable)

Enable/disable set controller in connectable state.

Allows make local controller to be connectable. It means the controller start listen to devices requests on PAGE SCAN channel. If disabled also resets discoverability if was set.

Return
Negative if fail set to requested state or requested state has been already set. Zero if done successfully.
Parameters
  • enable: Value allowing/disallowing controller to be connectable.

int bt_rand(void *buf, size_t len)

Generate random data.

A random number generation helper which utilizes the Bluetooth controller’s own RNG.

Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error
Parameters
  • buf: Buffer to insert the random data
  • len: Length of random data to generate

BT_DATA(_type, _data, _data_len) { \ .type = (_type), \ .data_len = (_data_len), \ .data = (const uint8_t *)(_data), \ }

Helper to declare elements of bt_data arrays.

This macro is mainly for creating an array of struct bt_data elements which is then passed to bt_le_adv_start().

Parameters
  • _type: Type of advertising data field
  • _data: Pointer to the data field payload
  • _data_len: Number of bytes behind the _data pointer

BT_DATA_BYTES(_type, _bytes...) BT_DATA(_type, ((uint8_t []) { _bytes }), \ sizeof((uint8_t []) { _bytes }))

Helper to declare elements of bt_data arrays.

This macro is mainly for creating an array of struct bt_data elements which is then passed to bt_le_adv_start().

Parameters
  • _type: Type of advertising data field
  • _bytes: Variable number of single-byte parameters

BT_LE_ADV_PARAM(_options, _int_min, _int_max) (&(struct bt_le_adv_param) { \ .options = (_options), \ .interval_min = (_int_min), \ .interval_max = (_int_max), \ })

Helper to declare advertising parameters inline

Parameters
  • _options: Advertising Options
  • _int_min: Minimum advertising interval
  • _int_max: Maximum advertising interval

BT_LE_ADV_CONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE, \ BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2)
BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2)
BT_LE_SCAN_PARAM(_type, _filter, _interval, _window) (&(struct bt_le_scan_param) { \ .type = (_type), \ .filter_dup = (_filter), \ .interval = (_interval), \ .window = (_window), \ })

Helper to declare scan parameters inline

Parameters
  • _type: Scan Type (BT_HCI_LE_SCAN_ACTIVE/BT_HCI_LE_SCAN_PASSIVE)
  • _filter: Filter Duplicates
  • _interval: Scan Interval (N * 0.625 ms)
  • _window: Scan Window (N * 0.625 ms)

BT_LE_SCAN_ACTIVE BT_LE_SCAN_PARAM(BT_HCI_LE_SCAN_ACTIVE, \ BT_HCI_LE_SCAN_FILTER_DUP_ENABLE, \ BT_GAP_SCAN_FAST_INTERVAL, \ BT_GAP_SCAN_FAST_WINDOW)

Helper macro to enable active scanning to discover new devices.

BT_LE_SCAN_PASSIVE BT_LE_SCAN_PARAM(BT_HCI_LE_SCAN_PASSIVE, \ BT_HCI_LE_SCAN_FILTER_DUP_ENABLE, \ BT_GAP_SCAN_FAST_INTERVAL, \ BT_GAP_SCAN_FAST_WINDOW)

Helper macro to enable passive scanning to discover new devices.

This macro should be used if information required for device identification (eg UUID) are known to be placed in Advertising Data.

BT_ADDR_STR_LEN 18

Recommended length of user string buffer for Bluetooth address.

The recommended length guarantee the output of address conversion will not lose valuable information about address being processed.

BT_ADDR_LE_STR_LEN 27

Recommended length of user string buffer for Bluetooth LE address.

The recommended length guarantee the output of address conversion will not lose valuable information about address being processed.

struct bt_data
#include <bluetooth.h>

Description of different data types that can be encoded into advertising data. Used to form arrays that are passed to the bt_le_adv_start() function.

struct bt_le_adv_param
#include <bluetooth.h>

LE Advertising Parameters.

struct bt_le_scan_param
#include <bluetooth.h>

LE scan parameters

struct bt_br_discovery_result
#include <bluetooth.h>

BR/EDR discovery result structure.

struct bt_br_discovery_param
#include <bluetooth.h>

BR/EDR discovery parameters

Connection Management

enum [anonymous]__anonymous1

Connection Type

Values:

BT_CONN_TYPE_LE

LE Connection Type

BT_CONN_TYPE_BR

BR/EDR Connection Type

enum [anonymous]__anonymous2

Connection role (master or slave)

Values:

BT_CONN_ROLE_MASTER
BT_CONN_ROLE_SLAVE
enum bt_conn::__packed

Security level.

Values:

BT_SECURITY_NONE

Only for BR/EDR special cases, like SDP

BT_SECURITY_LOW

No encryption and no authentication.

BT_SECURITY_MEDIUM

Encryption and no authentication (no MITM).

BT_SECURITY_HIGH

Encryption and authentication (MITM).

BT_SECURITY_FIPS

Authenticated Secure Connections

typedef enum __packed bt_security_t

Security level.

struct bt_conn *bt_conn_ref(struct bt_conn *conn)

Increment a connection’s reference count.

Increment the reference count of a connection object.

Return
Connection object with incremented reference count.
Parameters
  • conn: Connection object.

void bt_conn_unref(struct bt_conn *conn)

Decrement a connection’s reference count.

Decrement the reference count of a connection object.

Parameters
  • conn: Connection object.

struct bt_conn *bt_conn_lookup_addr_le(const bt_addr_le_t *peer)

Look up an existing connection by address.

Look up an existing connection based on the remote address.

Return
Connection object or NULL if not found. The caller gets a new reference to the connection object which must be released with bt_conn_unref() once done using the object.
Parameters
  • peer: Remote address.

const bt_addr_le_t *bt_conn_get_dst(const struct bt_conn *conn)

Get destination (peer) address of a connection.

Return
Destination address.
Parameters
  • conn: Connection object.

int bt_conn_get_info(const struct bt_conn *conn, struct bt_conn_info *info)

Get connection info.

Return
Zero on success or (negative) error code on failure.
Parameters
  • conn: Connection object.
  • info: Connection info object.

int bt_conn_le_param_update(struct bt_conn *conn, const struct bt_le_conn_param *param)

Update the connection parameters.

Return
Zero on success or (negative) error code on failure.
Parameters
  • conn: Connection object.
  • param: Updated connection parameters.

int bt_conn_disconnect(struct bt_conn *conn, uint8_t reason)

Disconnect from a remote device or cancel pending connection.

Disconnect an active connection with the specified reason code or cancel pending outgoing connection.

Return
Zero on success or (negative) error code on failure.
Parameters
  • conn: Connection to disconnect.
  • reason: Reason code for the disconnection.

struct bt_conn *bt_conn_create_le(const bt_addr_le_t *peer, const struct bt_le_conn_param *param)

Initiate an LE connection to a remote device.

Allows initiate new LE link to remote peer using its address. Returns a new reference that the the caller is responsible for managing.

Return
Valid connection object on success or NULL otherwise.
Parameters
  • peer: Remote address.
  • param: Initial connection parameters.

int bt_le_set_auto_conn(bt_addr_le_t *addr, const struct bt_le_conn_param *param)

Automatically connect to remote device if it’s in range.

This function enables/disables automatic connection initiation. Everytime the device looses the connection with peer, this connection will be re-established if connectable advertisement from peer is received.

Return
Zero on success or error code otherwise.
Parameters
  • addr: Remote Bluetooth address.
  • param: If non-NULL, auto connect is enabled with the given parameters. If NULL, auto connect is disabled.

struct bt_conn *bt_conn_create_slave_le(const bt_addr_le_t *peer, const struct bt_le_adv_param *param)

Initiate directed advertising to a remote device.

Allows initiating a new LE connection to remote peer with the remote acting in central role and the local device in peripheral role.

The advertising type must be either BT_LE_ADV_DIRECT_IND or BT_LE_ADV_DIRECT_IND_LOW_DUTY.

In case of high duty cycle this will result in a callback with connected() with a new connection or with an error.

The advertising may be cancelled with bt_conn_disconnect().

Returns a new reference that the the caller is responsible for managing.

Return
Valid connection object on success or NULL otherwise.
Parameters
  • peer: Remote address.
  • param: Directed advertising parameters.

int bt_conn_security(struct bt_conn *conn, bt_security_t sec)

Set security level for a connection.

This function enable security (encryption) for a connection. If device is already paired with sufficiently strong key encryption will be enabled. If link is already encrypted with sufficiently strong key this function does nothing.

If device is not paired pairing will be initiated. If device is paired and keys are too weak but input output capabilities allow for strong enough keys pairing will be initiated.

This function may return error if required level of security is not possible to achieve due to local or remote device limitation (eg input output capabilities).

Return
0 on success or negative error
Parameters
  • conn: Connection object.
  • sec: Requested security level.

uint8_t bt_conn_enc_key_size(struct bt_conn *conn)

Get encryption key size.

This function gets encryption key size. If there is no security (encryption) enabled 0 will be returned.

Return
Encryption key size.
Parameters
  • conn: Existing connection object.

void bt_conn_cb_register(struct bt_conn_cb *cb)

Register connection callbacks.

Register callbacks to monitor the state of connections.

Parameters
  • cb: Callback struct.

int bt_conn_auth_cb_register(const struct bt_conn_auth_cb *cb)

Register authentication callbacks.

Register callbacks to handle authenticated pairing. Passing NULL unregisters previous callbacks structure.

Return
Zero on success or negative error code otherwise
Parameters
  • cb: Callback struct.

int bt_conn_auth_passkey_entry(struct bt_conn *conn, unsigned int passkey)

Reply with entered passkey.

This function should be called only after passkey_entry callback from bt_conn_auth_cb structure was called.

Return
Zero on success or negative error code otherwise
Parameters
  • conn: Connection object.
  • passkey: Entered passkey.

int bt_conn_auth_cancel(struct bt_conn *conn)

Cancel ongoing authenticated pairing.

This function allows to cancel ongoing authenticated pairing.

Return
Zero on success or negative error code otherwise
Parameters
  • conn: Connection object.

int bt_conn_auth_passkey_confirm(struct bt_conn *conn)

Reply if passkey was confirmed to match by user.

This function should be called only after passkey_confirm callback from bt_conn_auth_cb structure was called.

Return
Zero on success or negative error code otherwise
Parameters
  • conn: Connection object.

int bt_conn_auth_pairing_confirm(struct bt_conn *conn)

Reply if incoming pairing was confirmed by user.

This function should be called only after pairing_confirm callback from bt_conn_auth_cb structure was called if user confirmed incoming pairing.

Return
Zero on success or negative error code otherwise
Parameters
  • conn: Connection object.

int bt_conn_auth_pincode_entry(struct bt_conn *conn, const char *pin)

Reply with entered PIN code.

This function should be called only after PIN code callback from bt_conn_auth_cb structure was called. It’s for legacy 2.0 devices.

Return
Zero on success or negative error code otherwise
Parameters
  • conn: Connection object.
  • pin: Entered PIN code.

struct bt_conn *bt_conn_create_br(const bt_addr_t *peer, const struct bt_br_conn_param *param)

Initiate an BR/EDR connection to a remote device.

Allows initiate new BR/EDR link to remote peer using its address. Returns a new reference that the the caller is responsible for managing.

Return
Valid connection object on success or NULL otherwise.
Parameters
  • peer: Remote address.
  • param: Initial connection parameters.

BT_LE_CONN_PARAM(int_min, int_max, lat, to) (&(struct bt_le_conn_param) { \ .interval_min = (int_min), \ .interval_max = (int_max), \ .latency = (lat), \ .timeout = (to), \ })

Helper to declare connection parameters inline

Parameters
  • int_min: Minimum Connection Interval (N * 1.25 ms)
  • int_max: Maximum Connection Interval (N * 1.25 ms)
  • lat: Connection Latency
  • to: Supervision Timeout (N * 10 ms)

BT_LE_CONN_PARAM_DEFAULT BT_LE_CONN_PARAM(BT_GAP_INIT_CONN_INT_MIN, \ BT_GAP_INIT_CONN_INT_MAX, \ 0, 400)

Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s

BT_BR_CONN_PARAM(role_switch) (&(struct bt_br_conn_param) { \ .allow_role_switch = (role_switch), \ })

Helper to declare BR/EDR connection parameters inline

Parameters
  • role_switch: True if role switch is allowed

BT_BR_CONN_PARAM_DEFAULT BT_BR_CONN_PARAM(true)

Default BR/EDR connection parameters: Role switch allowed

struct bt_le_conn_param
#include <conn.h>

Connection parameters for LE connections

struct bt_conn_le_info
#include <conn.h>

LE Connection Info Structure

struct bt_conn_br_info
#include <conn.h>

BR/EDR Connection Info Structure

struct bt_conn_info
#include <conn.h>

Connection Info Structure.

Parameters
  • type: Connection Type
  • role: Connection Role
  • le: LE Connection specific Info
  • br: BR/EDR Connection specific Info

union

Public Members

struct bt_conn_cb
#include <conn.h>

Connection callback structure.

This structure is used for tracking the state of a connection. It is registered with the help of the bt_conn_cb_register() API. It’s premissible to register multiple instances of this bt_conn_cb type, in case different modules of an application are interested in tracking the connection state. If a callback is not of interest for an instance, it may be set to NULL and will as a consequence not be used for that instance.

struct bt_conn_auth_cb
#include <conn.h>

Authenticated pairing callback structure

struct bt_br_conn_param
#include <conn.h>

Connection parameters for BR/EDR connections

Generic Attribute Profile (GATT)

enum [anonymous]__anonymous5

Values:

BT_GATT_PERM_NONE = 0

No operations supported, e.g. for notify-only

BT_GATT_PERM_READ = BIT(0)

Attribute read permission.

BT_GATT_PERM_WRITE = BIT(1)

Attribute write permission.

BT_GATT_PERM_READ_ENCRYPT = BIT(2)

Attribute read permission with encryption. 

    If set, requires encryption for read access.

BT_GATT_PERM_WRITE_ENCRYPT = BIT(3)

Attribute write permission with encryption. 

    If set, requires encryption for write access.

BT_GATT_PERM_READ_AUTHEN = BIT(4)

Attribute read permission with authentication. 

    If set, requires encryption using authenticated link-key for read
    access.

BT_GATT_PERM_WRITE_AUTHEN = BIT(5)

Attribute write permission with authentication. 

    If set, requires encryption using authenticated link-key for write
    access.

BT_GATT_PERM_PREPARE_WRITE = BIT(6)

Attribute prepare write permission. 

    If set, allows prepare writes with use of BT_GATT_WRITE_FLAG_PREPARE
    passed to write callback.

enum [anonymous]__anonymous6

Values:

BT_GATT_WRITE_FLAG_PREPARE = BIT(0)

Attribute prepare write flag 

   If set, write callback should only check if the device is
   authorized but no data shall be written.

enum [anonymous]__anonymous7

Values:

BT_GATT_ITER_STOP = 0
BT_GATT_ITER_CONTINUE
enum [anonymous]__anonymous8

Values:

BT_GATT_DISCOVER_PRIMARY
BT_GATT_DISCOVER_SECONDARY
BT_GATT_DISCOVER_INCLUDE
BT_GATT_DISCOVER_CHARACTERISTIC
BT_GATT_DISCOVER_DESCRIPTOR
enum [anonymous]__anonymous9

Values:

BT_GATT_SUBSCRIBE_FLAG_VOLATILE = BIT(0)

Persistence flag 

   If set, indicates that the subscription is not saved
   on the GATT server side. Therefore, upon disconnection,
   the subscription will be automatically removed
   from the client's subscriptions list and
   when the client reconnects, it will have to
   issue a new subscription.

typedef bt_gatt_attr_func_t

Attribute iterator callback.

Return
BT_GATT_ITER_CONTINUE if should continue to the next attribute or BT_GATT_ITER_STOP to stop.
Parameters
  • attr: Attribute found.
  • user_data: Data given.

typedef bt_gatt_indicate_func_t

Indication complete result callback.

Parameters
  • conn: Connection object.
  • attr: Attribute object.
  • err: ATT error code

typedef bt_gatt_discover_func_t

Discover attribute callback function.

If discovery procedure has completed this callback will be called with attr set to NULL. This will not happen if procedure was stopped by returning BT_GATT_ITER_STOP. The attribute is read-only and cannot be cached without copying its contents.

Parameters
  • conn: Connection object.
  • attr: Attribute found.
  • params: Discovery parameters given.

Return
BT_GATT_ITER_CONTINUE if should continue attribute discovery or BT_GATT_ITER_STOP to stop discovery procedure.

typedef bt_gatt_read_func_t

Read callback function.

Parameters
  • conn: Connection object.
  • err: ATT error code.
  • params: Read parameters used.
  • data: Attribute value data. NULL means read has completed.
  • length: Attribute value length.

typedef bt_gatt_write_func_t

Write callback function.

Parameters
  • conn: Connection object.
  • err: ATT error code.
  • params: Write parameters used.

typedef bt_gatt_notify_func_t

Notification callback function.

Parameters
  • conn: Connection object.
  • params: Subscription parameters.
  • data: Attribute value data. If NULL then subscription was removed.
  • length: Attribute value length.

struct bt_gatt_cpf __packed
int bt_gatt_register(struct bt_gatt_attr *attrs, size_t count)

Register attribute database.

Register GATT attribute database table. Applications can make use of macros such as BT_GATT_PRIMARY_SERVICE, BT_GATT_CHARACTERISTIC, BT_GATT_DESCRIPTOR, etc.

Return
0 in case of success or negative value in case of error.
Parameters
  • attrs: Database table containing the available attributes.
  • count: Size of the database table.

void bt_gatt_foreach_attr(uint16_t start_handle, uint16_t end_handle, bt_gatt_attr_func_t func, void *user_data)

Attribute iterator.

Iterate attributes in the given range.

Parameters
  • start_handle: Start handle.
  • end_handle: End handle.
  • func: Callback function.
  • user_data: Data to pass to the callback.

struct bt_gatt_attr *bt_gatt_attr_next(const struct bt_gatt_attr *attr)

Iterate to the next attribute.

Iterate to the next attribute following a given attribute.

Return
The next attribute or NULL if it cannot be found.
Parameters
  • attr: Current Attribute.

ssize_t bt_gatt_attr_read(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t buf_len, uint16_t offset, const void *value, uint16_t value_len)

Generic Read Attribute value helper.

Read attribute value storing the result into buffer.

Return
int number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object.
  • attr: Attribute to read.
  • buf: Buffer to store the value.
  • buf_len: Buffer length.
  • offset: Start offset.
  • value: Attribute value.
  • value_len: Length of the attribute value.

ssize_t bt_gatt_attr_read_service(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Service Attribute helper.

Read service attribute value storing the result into buffer after enconding it. NOTE: Only use this with attributes which user_data is a bt_uuid.

Return
int number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object.
  • attr: Attribute to read.
  • buf: Buffer to store the value read.
  • len: Buffer length.
  • offset: Start offset.

ssize_t bt_gatt_attr_read_included(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Include Attribute helper.

Read include service attribute value storing the result into buffer after enconding it. NOTE: Only use this with attributes which user_data is a bt_gatt_include.

Return
int number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object.
  • attr: Attribute to read.
  • buf: Buffer to store the value read.
  • len: Buffer length.
  • offset: Start offset.

ssize_t bt_gatt_attr_read_chrc(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic Attribute helper.

Read characteristic attribute value storing the result into buffer after enconding it. NOTE: Only use this with attributes which user_data is a bt_gatt_chrc.

Return
number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object.
  • attr: Attribute to read.
  • buf: Buffer to store the value read.
  • len: Buffer length.
  • offset: Start offset.

ssize_t bt_gatt_attr_read_ccc(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Client Characteristic Configuration Attribute helper.

Read CCC attribute value storing the result into buffer after enconding it. NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc.

Return
number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object.
  • attr: Attribute to read.
  • buf: Buffer to store the value read.
  • len: Buffer length.
  • offset: Start offset.

ssize_t bt_gatt_attr_write_ccc(struct bt_conn *conn, const struct bt_gatt_attr *attr, const void *buf, uint16_t len, uint16_t offset, uint8_t flags)

Write Client Characteristic Configuration Attribute helper.

Write value in the buffer into CCC attribute. NOTE: Only use this with attributes which user_data is a _bt_gatt_ccc.

Return
number of bytes written in case of success or negative values in case of error.
Parameters
  • conn: Connection object.
  • attr: Attribute to read.
  • buf: Buffer to store the value read.
  • len: Buffer length.
  • offset: Start offset.
  • flags: Write flags.

ssize_t bt_gatt_attr_read_cep(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic Extended Properties Attribute helper.

Read CEP attribute value storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a bt_gatt_cep.

Return
number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object
  • attr: Attribute to read
  • buf: Buffer to store the value read
  • len: Buffer length
  • offset: Start offset

ssize_t bt_gatt_attr_read_cud(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic User Description Descriptor Attribute helper.

Read CUD attribute value storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a NULL-terminated C string.

Return
number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object
  • attr: Attribute to read
  • buf: Buffer to store the value read
  • len: Buffer length
  • offset: Start offset

ssize_t bt_gatt_attr_read_cpf(struct bt_conn *conn, const struct bt_gatt_attr *attr, void *buf, uint16_t len, uint16_t offset)

Read Characteristic Presentation format Descriptor Attribute helper.

Read CPF attribute value storing the result into buffer after encoding it. NOTE: Only use this with attributes which user_data is a bt_gatt_pf.

Return
number of bytes read in case of success or negative values in case of error.
Parameters
  • conn: Connection object
  • attr: Attribute to read
  • buf: Buffer to store the value read
  • len: Buffer length
  • offset: Start offset

int bt_gatt_notify(struct bt_conn *conn, const struct bt_gatt_attr *attr, const void *data, uint16_t len)

Notify attribute value change.

Send notification of attribute value change, if connection is NULL notify all peer that have notification enabled via CCC otherwise do a direct notification only the given connection.

Parameters
  • conn: Connection object.
  • attr: Attribute object.
  • data: Pointer to Attribute data.
  • len: Attribute value length.

int bt_gatt_indicate(struct bt_conn *conn, struct bt_gatt_indicate_params *params)

Indicate attribute value change.

Send an indication of attribute value change. Note: This function should only be called if CCC is declared with BT_GATT_CCC otherwise it cannot find a valid peer configuration.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • params: Indicate parameters.

int bt_gatt_exchange_mtu(struct bt_conn *conn, struct bt_gatt_exchange_params *params)

Exchange MTU.

This client procedure can be used to set the MTU to the maximum possible size the buffers can hold.

NOTE: Shall only be used once per connection.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • params: Exchange MTU parameters.

int bt_gatt_discover(struct bt_conn *conn, struct bt_gatt_discover_params *params)

GATT Discover function.

This procedure is used by a client to discover attributes on a server.

Primary Service Discovery: Procedure allows to discover specific Primary Service based on UUID. Include Service Discovery: Procedure allows to discover all Include Services within specified range. Characteristic Discovery: Procedure allows to discover all characteristics within specified handle range as well as discover characteristics with specified UUID. Descriptors Discovery: Procedure allows to discover all characteristic descriptors within specified range.

For each attribute found the callback is called which can then decide whether to continue discovering or stop.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • params: Discover parameters.

int bt_gatt_read(struct bt_conn *conn, struct bt_gatt_read_params *params)

Read Attribute Value by handle.

This procedure read the attribute value and return it to the callback.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • params: Read parameters.

int bt_gatt_write(struct bt_conn *conn, struct bt_gatt_write_params *params)

Write Attribute Value by handle.

This procedure write the attribute value and return the result in the callback.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • params: Write parameters.

int bt_gatt_write_without_response(struct bt_conn *conn, uint16_t handle, const void *data, uint16_t length, bool sign)

Write Attribute Value by handle without response.

This procedure write the attribute value without requiring an acknowledgement that the write was successfully performed

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • handle: Attribute handle.
  • data: Data to be written.
  • length: Data length.
  • sign: Whether to sign data

int bt_gatt_subscribe(struct bt_conn *conn, struct bt_gatt_subscribe_params *params)

Subscribe Attribute Value Notification.

This procedure subscribe to value notification using the Client Characteristic Configuration handle. If notification received subscribe value callback is called to return notified value. One may then decide whether to unsubscribe directly from this callback. Notification callback with NULL data will not be called if subscription was removed by this method.

Note: This procedure is asynchronous therefore the parameters need to remains valid while it is active.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • params: Subscribe parameters.

int bt_gatt_unsubscribe(struct bt_conn *conn, struct bt_gatt_subscribe_params *params)

Unsubscribe Attribute Value Notification.

This procedure unsubscribe to value notification using the Client Characteristic Configuration handle. Notification callback with NULL data will not be called if subscription was removed by this call.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • params: Subscribe parameters.

void bt_gatt_cancel(struct bt_conn *conn, void *params)

Cancel GATT pending request.

Parameters
  • conn: Connection object.
  • params: Requested params address.

BT_GATT_ERR(_att_err) (-(_att_err))

Construct error return value for attribute read and write callbacks.

Return
Appropriate error code for the attribute callbacks.
Parameters
  • _att_err: ATT error code

BT_GATT_CHRC_BROADCAST 0x01

Characteristic broadcast property.

If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor.

BT_GATT_CHRC_READ 0x02

Characteristic read property.

If set, permits reads of the Characteristic Value.

BT_GATT_CHRC_WRITE_WITHOUT_RESP 0x04

Characteristic write without response property.

If set, permits write of the Characteristic Value without response.

BT_GATT_CHRC_WRITE 0x08

Characteristic write with response property.

If set, permits write of the Characteristic Value with response.

BT_GATT_CHRC_NOTIFY 0x10

Characteristic notify property.

If set, permits notifications of a Characteristic Value without acknowledgment.

BT_GATT_CHRC_INDICATE 0x20

Characteristic indicate property.

If set, permits indications of a Characteristic Value with acknowledgment.

BT_GATT_CHRC_AUTH 0x40

Characteristic Authenticated Signed Writes property.

If set, permits signed writes to the Characteristic Value.

BT_GATT_CHRC_EXT_PROP 0x80

Characteristic Extended Properties property.

If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor.

BT_GATT_CEP_RELIABLE_WRITE 0x0001
BT_GATT_CEP_WRITABLE_AUX 0x0002
BT_GATT_CCC_NOTIFY 0x0001

Client Characteristic Configuration Notification.

If set, changes to Characteristic Value shall be notified.

BT_GATT_CCC_INDICATE 0x0002

Client Characteristic Configuration Indication.

If set, changes to Characteristic Value shall be indicated.

BT_GATT_SERVICE(_uuid, _service) { \ .uuid = _uuid, \ .perm = BT_GATT_PERM_READ, \ .read = bt_gatt_attr_read_service, \ .user_data = _service, \ }

Generic Service Declaration Macro.

Helper macro to declare a service attribute.

Parameters
  • _uuid: Service attribute type.
  • _service: Service attribute value.

BT_GATT_PRIMARY_SERVICE(_service) { \ .uuid = BT_UUID_GATT_PRIMARY, \ .perm = BT_GATT_PERM_READ, \ .read = bt_gatt_attr_read_service, \ .user_data = _service, \ }

Primary Service Declaration Macro.

Helper macro to declare a primary service attribute.

Parameters
  • _service: Service attribute value.

BT_GATT_SECONDARY_SERVICE(_service) { \ .uuid = BT_UUID_GATT_SECONDARY, \ .perm = BT_GATT_PERM_READ, \ .read = bt_gatt_attr_read_service, \ .user_data = _service, \ }

Secondary Service Declaration Macro.

Helper macro to declare a secondary service attribute.

Parameters
  • _service: Service attribute value.

BT_GATT_INCLUDE_SERVICE(_service_incl) { \ .uuid = BT_UUID_GATT_INCLUDE, \ .perm = BT_GATT_PERM_READ, \ .read = bt_gatt_attr_read_included, \ .user_data = _service_incl, \ }

Include Service Declaration Macro.

Helper macro to declare database internal include service attribute.

Parameters
  • _service_incl: the first service attribute of service to include

BT_GATT_CHARACTERISTIC(_uuid, _props) { \ .uuid = BT_UUID_GATT_CHRC, \ .perm = BT_GATT_PERM_READ, \ .read = bt_gatt_attr_read_chrc, \ .user_data = (&(struct bt_gatt_chrc) { .uuid = _uuid, \ .properties = _props, }),\ }

Characteristic Declaration Macro.

Helper macro to declare a characteristic attribute.

Parameters
  • _uuid: Characteristic attribute uuid.
  • _props: Characteristic attribute properties.

BT_GATT_CCC(_cfg, _cfg_changed) { \ .uuid = BT_UUID_GATT_CCC, \ .perm = BT_GATT_PERM_READ | BT_GATT_PERM_WRITE, \ .read = bt_gatt_attr_read_ccc, \ .write = bt_gatt_attr_write_ccc, \ .user_data = (&(struct _bt_gatt_ccc) { .cfg = _cfg, \ .cfg_len = ARRAY_SIZE(_cfg), \ .cfg_changed = _cfg_changed, }),\ }

Client Characteristic Configuration Declaration Macro.

Helper macro to declare a CCC attribute.

Parameters
  • _cfg: Initial configuration.
  • _cfg_changed: Configuration changed callback.

BT_GATT_CEP(_value) { \ .uuid = BT_UUID_GATT_CEP, \ .perm = BT_GATT_PERM_READ, \ .read = bt_gatt_attr_read_cep, \ .user_data = _value, \ }

Characteristic Extended Properties Declaration Macro.

Helper macro to declare a CEP attribute.

Parameters
  • _value: Descriptor attribute value.

BT_GATT_CUD(_value, _perm) { \ .uuid = BT_UUID_GATT_CUD, \ .perm = _perm, \ .read = bt_gatt_attr_read_cud, \ .user_data = _value, \ }

Characteristic User Format Descriptor Declaration Macro.

Helper macro to declare a CUD attribute.

Parameters
  • _value: User description NULL-terminated C string.
  • _perm: Descriptor attribute access permissions.

BT_GATT_CPF(_value) { \ .uuid = BT_UUID_GATT_CPF, \ .perm = BT_GATT_PERM_READ, \ .read = bt_gatt_attr_read_cpf, \ .user_data = _value, \ }

Characteristic Presentation Format Descriptor Declaration Macro.

Helper macro to declare a CPF attribute.

Parameters
  • _value: Descriptor attribute value.

BT_GATT_DESCRIPTOR(_uuid, _perm, _read, _write, _value) { \ .uuid = _uuid, \ .perm = _perm, \ .read = _read, \ .write = _write, \ .user_data = _value, \ }

Descriptor Declaration Macro.

Helper macro to declare a descriptor attribute.

Parameters
  • _uuid: Descriptor attribute uuid.
  • _perm: Descriptor attribute access permissions.
  • _read: Descriptor attribute read callback.
  • _write: Descriptor attribute write callback.
  • _value: Descriptor attribute value.

struct bt_gatt_attr
#include <gatt.h>

GATT Attribute structure.

struct bt_gatt_service
#include <gatt.h>

Service Attribute Value.

struct bt_gatt_include
#include <gatt.h>

Include Attribute Value.

struct bt_gatt_chrc
#include <gatt.h>

Characteristic Attribute Value.

struct bt_gatt_cep
#include <gatt.h>

Characteristic Extended Properties Attribute Value.

struct bt_gatt_cpf
#include <gatt.h>

GATT Characteristic Presentation Format Attribute Value.

struct bt_gatt_ccc_cfg
#include <gatt.h>

GATT CCC configuration entry.

struct bt_gatt_indicate_params
#include <gatt.h>

GATT Indicate Value parameters.

struct bt_gatt_exchange_params
#include <gatt.h>

GATT Exchange MTU parameters.

struct bt_gatt_discover_params
#include <gatt.h>

GATT Discover Attributes parameters.

union

Public Members

Discover start handle

struct bt_gatt_read_params
#include <gatt.h>

GATT Read parameters.

Parameters
  • func: Read attribute callback
  • handle_count: If equals to 1 single.handle and single.offset are used. If >1 Read Multiple Characteristic Values is performed and handles are used.
  • handle: Attribute handle
  • offset: Attribute data offset
  • handles: Handles to read in Read Multiple Characteristic Values

union

Public Members

struct bt_gatt_write_params
#include <gatt.h>

GATT Write parameters.

struct bt_gatt_subscribe_params
#include <gatt.h>

GATT Subscribe parameters.

Universal Unique Identifiers (UUIDs)

enum [anonymous]__anonymous19

Bluetooth UUID types.

Values:

BT_UUID_TYPE_16
BT_UUID_TYPE_32
BT_UUID_TYPE_128
int bt_uuid_cmp(const struct bt_uuid *u1, const struct bt_uuid *u2)

Compare Bluetooth UUIDs.

Compares 2 Bluetooth UUIDs, if the types are different both UUIDs are first converted to 128 bits format before comparing.

Return
negative value if u1 < u2, 0 if u1 == u2, else positive
Parameters
  • u1: First Bluetooth UUID to compare
  • u2: Second Bluetooth UUID to compare

static void bt_uuid_to_str(const struct bt_uuid *uuid, char *str, size_t len)
static const char *bt_uuid_str(const struct bt_uuid *uuid)
BT_UUID_INIT_16(value) { \ .uuid.type = BT_UUID_TYPE_16, \ .val = (value), \ }
BT_UUID_INIT_32(value) { \ .uuid.type = BT_UUID_TYPE_32, \ .val = (value), \ }
BT_UUID_INIT_128(value...) { \ .uuid.type = BT_UUID_TYPE_128, \ .val = { value }, \ }
BT_UUID_DECLARE_16(value) ((struct bt_uuid *) (&(struct bt_uuid_16) BT_UUID_INIT_16(value)))
BT_UUID_DECLARE_32(value) ((struct bt_uuid *) (&(struct bt_uuid_32) BT_UUID_INIT_32(value)))
BT_UUID_DECLARE_128(value...) ((struct bt_uuid *) (&(struct bt_uuid_128) BT_UUID_INIT_128(value)))
BT_UUID_16(__u) CONTAINER_OF(__u, struct bt_uuid_16, uuid)
BT_UUID_32(__u) CONTAINER_OF(__u, struct bt_uuid_32, uuid)
BT_UUID_128(__u) CONTAINER_OF(__u, struct bt_uuid_128, uuid)
BT_UUID_GAP BT_UUID_DECLARE_16(0x1800)

Generic Access.

BT_UUID_GAP_VAL 0x1800
BT_UUID_GATT BT_UUID_DECLARE_16(0x1801)

Generic Attribute.

BT_UUID_GATT_VAL 0x1801
BT_UUID_CTS BT_UUID_DECLARE_16(0x1805)

Current Time Service.

BT_UUID_CTS_VAL 0x1805
BT_UUID_DIS BT_UUID_DECLARE_16(0x180a)

Device Information Service.

BT_UUID_DIS_VAL 0x180a
BT_UUID_HRS BT_UUID_DECLARE_16(0x180d)

Heart Rate Service.

BT_UUID_HRS_VAL 0x180d
BT_UUID_BAS BT_UUID_DECLARE_16(0x180f)

Battery Service.

BT_UUID_BAS_VAL 0x180f
BT_UUID_HIDS BT_UUID_DECLARE_16(0x1812)

HID Service.

BT_UUID_HIDS_VAL 0x1812
BT_UUID_CSC BT_UUID_DECLARE_16(0x1816)

Cycling Speed and Cadence Service.

BT_UUID_CSC_VAL 0x1816
BT_UUID_ESS BT_UUID_DECLARE_16(0x181a)

Environmental Sensing Service.

BT_UUID_ESS_VAL 0x181a
BT_UUID_IPSS BT_UUID_DECLARE_16(0x1820)

IP Support Service.

BT_UUID_IPSS_VAL 0x1820
BT_UUID_GATT_PRIMARY BT_UUID_DECLARE_16(0x2800)

GATT Primary Service.

BT_UUID_GATT_PRIMARY_VAL 0x2800
BT_UUID_GATT_SECONDARY BT_UUID_DECLARE_16(0x2801)

GATT Secondary Service.

BT_UUID_GATT_SECONDARY_VAL 0x2801
BT_UUID_GATT_INCLUDE BT_UUID_DECLARE_16(0x2802)

GATT Include Service.

BT_UUID_GATT_INCLUDE_VAL 0x2802
BT_UUID_GATT_CHRC BT_UUID_DECLARE_16(0x2803)

GATT Characteristic.

BT_UUID_GATT_CHRC_VAL 0x2803
BT_UUID_GATT_CEP BT_UUID_DECLARE_16(0x2900)

GATT Characteristic Extended Properties.

BT_UUID_GATT_CEP_VAL 0x2900
BT_UUID_GATT_CUD BT_UUID_DECLARE_16(0x2901)

GATT Characteristic User Description.

BT_UUID_GATT_CUD_VAL 0x2901
BT_UUID_GATT_CCC BT_UUID_DECLARE_16(0x2902)

GATT Client Characteristic Configuration.

BT_UUID_GATT_CCC_VAL 0x2902
BT_UUID_GATT_SCC BT_UUID_DECLARE_16(0x2903)

GATT Server Characteristic Configuration.

BT_UUID_GATT_SCC_VAL 0x2903
BT_UUID_GATT_CPF BT_UUID_DECLARE_16(0x2904)

GATT Characteristic Presentation Format.

BT_UUID_GATT_CPF_VAL 0x2904
BT_UUID_VALID_RANGE BT_UUID_DECLARE_16(0x2906)

Valid Range Descriptor.

BT_UUID_VALID_RANGE_VAL 0x2906
BT_UUID_HIDS_EXT_REPORT BT_UUID_DECLARE_16(0x2907)

HID External Report Descriptor.

BT_UUID_HIDS_EXT_REPORT_VAL 0x2907
BT_UUID_HIDS_REPORT_REF BT_UUID_DECLARE_16(0x2908)

HID Report Reference Descriptor.

BT_UUID_HIDS_REPORT_REF_VAL 0x2908
BT_UUID_ES_CONFIGURATION BT_UUID_DECLARE_16(0x290b)

Environmental Sensing Configuration Descriptor.

BT_UUID_ES_CONFIGURATION_VAL 0x290b
BT_UUID_ES_MEASUREMENT BT_UUID_DECLARE_16(0x290c)

Environmental Sensing Measurement Descriptor.

BT_UUID_ES_MEASUREMENT_VAL 0x290c
BT_UUID_ES_TRIGGER_SETTING BT_UUID_DECLARE_16(0x290d)

Environmental Sensing Trigger Setting Descriptor.

BT_UUID_ES_TRIGGER_SETTING_VAL 0x290d
BT_UUID_GAP_DEVICE_NAME BT_UUID_DECLARE_16(0x2a00)

GAP Characteristic Device Name.

BT_UUID_GAP_DEVICE_NAME_VAL 0x2a00
BT_UUID_GAP_APPEARANCE BT_UUID_DECLARE_16(0x2a01)

GAP Characteristic Appearance.

BT_UUID_GAP_APPEARANCE_VAL 0x2a01
BT_UUID_GAP_PPCP BT_UUID_DECLARE_16(0x2a04)

GAP Characteristic Peripheral Preferred Connection Parameters.

BT_UUID_GAP_PPCP_VAL 0x2a04
BT_UUID_BAS_BATTERY_LEVEL BT_UUID_DECLARE_16(0x2a19)

BAS Characteristic Battery Level.

BT_UUID_BAS_BATTERY_LEVEL_VAL 0x2a19
BT_UUID_DIS_SYSTEM_ID BT_UUID_DECLARE_16(0x2a23)

DIS Characteristic System ID.

BT_UUID_DIS_SYSTEM_ID_VAL 0x2a23
BT_UUID_DIS_MODEL_NUMBER BT_UUID_DECLARE_16(0x2a24)

DIS Characteristic Model Number String.

BT_UUID_DIS_MODEL_NUMBER_VAL 0x2a24
BT_UUID_DIS_SERIAL_NUMBER BT_UUID_DECLARE_16(0x2a25)

DIS Characteristic Serial Number String.

BT_UUID_DIS_SERIAL_NUMBER_VAL 0x2a25
BT_UUID_DIS_FIRMWARE_REVISION BT_UUID_DECLARE_16(0x2a26)

DIS Characteristic Firmware Revision String.

BT_UUID_DIS_FIRMWARE_REVISION_VAL 0x2a26
BT_UUID_DIS_HARDWARE_REVISION BT_UUID_DECLARE_16(0x2a27)

DIS Characteristic Hardware Revision String.

BT_UUID_DIS_HARDWARE_REVISION_VAL 0x2a27
BT_UUID_DIS_SOFTWARE_REVISION BT_UUID_DECLARE_16(0x2a28)

DIS Characteristic Software Revision String.

BT_UUID_DIS_SOFTWARE_REVISION_VAL 0x2a28
BT_UUID_DIS_MANUFACTURER_NAME BT_UUID_DECLARE_16(0x2a29)

DIS Characteristic Manufacturer Name String.

BT_UUID_DIS_MANUFACTURER_NAME_VAL 0x2a29
BT_UUID_DIS_PNP_ID BT_UUID_DECLARE_16(0x2a50)

DIS Characteristic PnP ID.

BT_UUID_DIS_PNP_ID_VAL 0x2a50
BT_UUID_CTS_CURRENT_TIME BT_UUID_DECLARE_16(0x2a2b)

CTS Characteristic Current Time.

BT_UUID_CTS_CURRENT_TIME_VAL 0x2a2b
BT_UUID_MAGN_DECLINATION BT_UUID_DECLARE_16(0x2a2c)

Magnetic Declination Characteristic.

BT_UUID_MAGN_DECLINATION_VAL 0x2a2c
BT_UUID_HRS_MEASUREMENT BT_UUID_DECLARE_16(0x2a37)

HRS Characteristic Measurement Interval.

BT_UUID_HRS_MEASUREMENT_VAL 0x2a37
BT_UUID_HRS_BODY_SENSOR BT_UUID_DECLARE_16(0x2a38)

HRS Characteristic Body Sensor Location.

BT_UUID_HRS_BODY_SENSOR_VAL 0x2a38
BT_UUID_HRS_CONTROL_POINT BT_UUID_DECLARE_16(0x2a39)

HRS Characteristic Control Point.

BT_UUID_HRS_CONTROL_POINT_VAL 0x2a39
BT_UUID_HIDS_INFO BT_UUID_DECLARE_16(0x2a4a)

HID Information Characteristic.

BT_UUID_HIDS_INFO_VAL 0x2a4a
BT_UUID_HIDS_REPORT_MAP BT_UUID_DECLARE_16(0x2a4b)

HID Report Map Characteristic.

BT_UUID_HIDS_REPORT_MAP_VAL 0x2a4b
BT_UUID_HIDS_CTRL_POINT BT_UUID_DECLARE_16(0x2a4c)

HID Control Point Characteristic.

BT_UUID_HIDS_CTRL_POINT_VAL 0x2a4c
BT_UUID_HIDS_REPORT BT_UUID_DECLARE_16(0x2a4d)

HID Report Characteristic.

BT_UUID_HIDS_REPORT_VAL 0x2a4d
BT_UUID_CSC_MEASUREMENT BT_UUID_DECLARE_16(0x2a5b)

CSC Measurement Characteristic.

BT_UUID_CSC_MEASUREMENT_VAL 0x2a5b
BT_UUID_CSC_FEATURE BT_UUID_DECLARE_16(0x2a5c)

CSC Feature Characteristic.

BT_UUID_CSC_FEATURE_VAL 0x2a5c
BT_UUID_SENSOR_LOCATION BT_UUID_DECLARE_16(0x2a5d)

Sensor Location Characteristic.

BT_UUID_SENSOR_LOCATION_VAL 0x2a5d
BT_UUID_SC_CONTROL_POINT BT_UUID_DECLARE_16(0x2a55)

SC Control Point Characteristic.

BT_UUID_SC_CONTROL_POINT_VAl 0x2a55
BT_UUID_ELEVATION BT_UUID_DECLARE_16(0x2a6c)

Elevation Characteristic.

BT_UUID_ELEVATION_VAL 0x2a6c
BT_UUID_PRESSURE BT_UUID_DECLARE_16(0x2a6d)

Pressure Characteristic.

BT_UUID_PRESSURE_VAL 0x2a6d
BT_UUID_TEMPERATURE BT_UUID_DECLARE_16(0x2a6e)

Temperature Characteristic.

BT_UUID_TEMPERATURE_VAL 0x2a6e
BT_UUID_HUMIDITY BT_UUID_DECLARE_16(0x2a6f)

Humidity Characteristic.

BT_UUID_HUMIDITY_VAL 0x2a6f
BT_UUID_TRUE_WIND_SPEED BT_UUID_DECLARE_16(0x2a70)

True Wind Speed Characteristic.

BT_UUID_TRUE_WIND_SPEED_VAL 0x2a70
BT_UUID_TRUE_WIND_DIR BT_UUID_DECLARE_16(0x2a71)

True Wind Direction Characteristic.

BT_UUID_TRUE_WIND_DIR_VAL 0x2a71
BT_UUID_APPARENT_WIND_SPEED BT_UUID_DECLARE_16(0x2a72)

Apparent Wind Speed Characteristic.

BT_UUID_APPARENT_WIND_SPEED_VAL 0x2a72
BT_UUID_APPARENT_WIND_DIR BT_UUID_DECLARE_16(0x2a73)

Apparent Wind Direction Characteristic.

BT_UUID_APPARENT_WIND_DIR_VAL 0x2a73
BT_UUID_GUST_FACTOR BT_UUID_DECLARE_16(0x2a74)

Gust Factor Characteristic.

BT_UUID_GUST_FACTOR_VAL 0x2a74
BT_UUID_POLLEN_CONCENTRATION BT_UUID_DECLARE_16(0x2a75)

Pollen Concentration Characteristic.

BT_UUID_POLLEN_CONCENTRATION_VAL 0x2a75
BT_UUID_UV_INDEX BT_UUID_DECLARE_16(0x2a76)

UV Index Characteristic.

BT_UUID_UV_INDEX_VAL 0x2a76
BT_UUID_IRRADIANCE BT_UUID_DECLARE_16(0x2a77)

Irradiance Characteristic.

BT_UUID_IRRADIANCE_VAL 0x2a77
BT_UUID_RAINFALL BT_UUID_DECLARE_16(0x2a78)

Rainfall Characteristic.

BT_UUID_RAINFALL_VAL 0x2a78
BT_UUID_WIND_CHILL BT_UUID_DECLARE_16(0x2a79)

Wind Chill Characteristic.

BT_UUID_WIND_CHILL_VAL 0x2a79
BT_UUID_HEAT_INDEX BT_UUID_DECLARE_16(0x2a7a)

Heat Index Characteristic.

BT_UUID_HEAT_INDEX_VAL 0x2a7a
BT_UUID_DEW_POINT BT_UUID_DECLARE_16(0x2a7b)

Dew Point Characteristic.

BT_UUID_DEW_POINT_VAL 0x2a7b
BT_UUID_DESC_VALUE_CHANGED BT_UUID_DECLARE_16(0x2a7d)

Descriptor Value Changed Characteristic.

BT_UUID_DESC_VALUE_CHANGED_VAL 0x2a7d
BT_UUID_MAGN_FLUX_DENSITY_2D BT_UUID_DECLARE_16(0x2aa0)

Magnetic Flux Density - 2D Characteristic.

BT_UUID_MAGN_FLUX_DENSITY_2D_VAL 0x2aa0
BT_UUID_MAGN_FLUX_DENSITY_3D BT_UUID_DECLARE_16(0x2aa1)

Magnetic Flux Density - 3D Characteristic.

BT_UUID_MAGN_FLUX_DENSITY_3D_VAL 0x2aa1
BT_UUID_BAR_PRESSURE_TREND BT_UUID_DECLARE_16(0x2aa3)

Barometric Pressure Trend Characteristic.

BT_UUID_BAR_PRESSURE_TREND_VAL 0x2aa3
BT_UUID_SDP BT_UUID_DECLARE_16(0x0001)
BT_UUID_SDP_VAL 0x0001
BT_UUID_UDP BT_UUID_DECLARE_16(0x0002)
BT_UUID_UDP_VAL 0x0002
BT_UUID_RFCOMM BT_UUID_DECLARE_16(0x0003)
BT_UUID_RFCOMM_VAL 0x0003
BT_UUID_TCP BT_UUID_DECLARE_16(0x0004)
BT_UUID_TCP_VAL 0x0004
BT_UUID_TCS_BIN BT_UUID_DECLARE_16(0x0005)
BT_UUID_TCS_BIN_VAL 0x0005
BT_UUID_TCS_AT BT_UUID_DECLARE_16(0x0006)
BT_UUID_TCS_AT_VAL 0x0006
BT_UUID_ATT BT_UUID_DECLARE_16(0x0007)
BT_UUID_ATT_VAL 0x0007
BT_UUID_OBEX BT_UUID_DECLARE_16(0x0008)
BT_UUID_OBEX_VAL 0x0008
BT_UUID_IP BT_UUID_DECLARE_16(0x0009)
BT_UUID_IP_VAL 0x0009
BT_UUID_FTP BT_UUID_DECLARE_16(0x000a)
BT_UUID_FTP_VAL 0x000a
BT_UUID_HTTP BT_UUID_DECLARE_16(0x000c)
BT_UUID_HTTP_VAL 0x000c
BT_UUID_BNEP BT_UUID_DECLARE_16(0x000f)
BT_UUID_BNEP_VAL 0x000f
BT_UUID_UPNP BT_UUID_DECLARE_16(0x0010)
BT_UUID_UPNP_VAL 0x0010
BT_UUID_HIDP BT_UUID_DECLARE_16(0x0011)
BT_UUID_HIDP_VAL 0x0011
BT_UUID_HCRP_CTRL BT_UUID_DECLARE_16(0x0012)
BT_UUID_HCRP_CTRL_VAL 0x0012
BT_UUID_HCRP_DATA BT_UUID_DECLARE_16(0x0014)
BT_UUID_HCRP_DATA_VAL 0x0014
BT_UUID_HCRP_NOTE BT_UUID_DECLARE_16(0x0016)
BT_UUID_HCRP_NOTE_VAL 0x0016
BT_UUID_AVCTP BT_UUID_DECLARE_16(0x0017)
BT_UUID_AVCTP_VAL 0x0017
BT_UUID_AVDTP BT_UUID_DECLARE_16(0x0019)
BT_UUID_AVDTP_VAL 0x0019
BT_UUID_CMTP BT_UUID_DECLARE_16(0x001b)
BT_UUID_CMTP_VAL 0x001b
BT_UUID_UDI BT_UUID_DECLARE_16(0x001d)
BT_UUID_UDI_VAL 0x001d
BT_UUID_MCAP_CTRL BT_UUID_DECLARE_16(0x001e)
BT_UUID_MCAP_CTRL_VAL 0x001e
BT_UUID_MCAP_DATA BT_UUID_DECLARE_16(0x001f)
BT_UUID_MCAP_DATA_VAL 0x001f
BT_UUID_L2CAP BT_UUID_DECLARE_16(0x0100)
BT_UUID_L2CAP_VAL 0x0100
struct bt_uuid
#include <uuid.h>

This is a ‘tentative’ type and should be used as a pointer only.

Serial Port Emulation (RFCOMM)

enum [anonymous]__anonymous15

Values:

BT_RFCOMM_CHAN_HFP_HF = 1
BT_RFCOMM_CHAN_HFP_AG
BT_RFCOMM_CHAN_HSP_AG
BT_RFCOMM_CHAN_HSP_HS
BT_RFCOMM_CHAN_SPP
enum bt_rfcomm::bt_rfcomm_role

Role of RFCOMM session and dlc. Used only by internal APIs.

Values:

BT_RFCOMM_ROLE_ACCEPTOR
BT_RFCOMM_ROLE_INITIATOR
typedef enum bt_rfcomm_role bt_rfcomm_role_t

Role of RFCOMM session and dlc. Used only by internal APIs.

int bt_rfcomm_server_register(struct bt_rfcomm_server *server)

Register RFCOMM server.

Register RFCOMM server for a channel, each new connection is authorized using the accept() callback which in case of success shall allocate the dlc structure to be used by the new connection.

Return
0 in case of success or negative value in case of error.
Parameters
  • server: Server structure.

int bt_rfcomm_dlc_connect(struct bt_conn *conn, struct bt_rfcomm_dlc *dlc, uint8_t channel)

Connect RFCOMM channel.

Connect RFCOMM dlc by channel, once the connection is completed dlc connected() callback will be called. If the connection is rejected disconnected() callback is called instead.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • dlc: Dlc object.
  • channel: Server channel to connect to.

int bt_rfcomm_dlc_send(struct bt_rfcomm_dlc *dlc, struct net_buf *buf)

Send data to RFCOMM.

Send data from buffer to the dlc. Length should be less than or equal to mtu.

Return
Bytes sent in case of success or negative value in case of error.
Parameters
  • dlc: Dlc object.
  • buf: Data buffer.

int bt_rfcomm_dlc_disconnect(struct bt_rfcomm_dlc *dlc)

Disconnect RFCOMM dlc.

Disconnect RFCOMM dlc, if the connection is pending it will be canceled and as a result the dlc disconnected() callback is called.

Return
0 in case of success or negative value in case of error.
Parameters
  • dlc: Dlc object.

struct net_buf *bt_rfcomm_create_pdu(struct net_buf_pool *pool)

Allocate the buffer from pool after reserving head room for RFCOMM, L2CAP and ACL headers.

Return
New buffer.
Parameters
  • pool: Which pool to take the buffer from.

struct bt_rfcomm_dlc_ops
#include <rfcomm.h>

RFCOMM DLC operations structure.

struct bt_rfcomm_dlc
#include <rfcomm.h>

RFCOMM DLC structure.

Data Buffers

enum bt_buf::bt_buf_type

Possible types of buffers passed around the Bluetooth stack

Values:

BT_BUF_CMD

HCI command

BT_BUF_EVT

HCI event

BT_BUF_ACL_OUT

Outgoing ACL data

BT_BUF_ACL_IN

Incoming ACL data

struct net_buf *bt_buf_get_rx(int32_t timeout)

Allocate a buffer for incoming data

This will not set the buffer type so bt_buf_set_type() needs to be called before bt_recv().

Return
A new buffer.
Parameters
  • timeout: Timeout in milliseconds, or one of the special values K_NO_WAIT and K_FOREVER.

struct net_buf *bt_buf_get_cmd_complete(int32_t timeout)

Allocate a buffer for an HCI Command Complete/Status Event

This will set the buffer type so bt_buf_set_type() does not need to be explicitly called before bt_recv_prio().

Return
A new buffer.
Parameters
  • timeout: Timeout in milliseconds, or one of the special values K_NO_WAIT and K_FOREVER.

static void bt_buf_set_type(struct net_buf *buf, enum bt_buf_type type)

Set the buffer type

Parameters
  • buf: Bluetooth buffer
  • type: The BT_* type to set the buffer to

static enum bt_buf_type bt_buf_get_type(struct net_buf *buf)

Get the buffer type

Return
The BT_* type to of the buffer
Parameters
  • buf: Bluetooth buffer

BT_BUF_USER_DATA_MIN 4

Minimum amount of user data size for buffers passed to the stack.

BT_BUF_RX_SIZE (CONFIG_BLUETOOTH_HCI_RESERVE + \ CONFIG_BLUETOOTH_RX_BUF_LEN)

Data size neeed for HCI RX buffers

Persistent Storage

enum [anonymous]__anonymous17

Well known storage keys

Values:

BT_STORAGE_ID_ADDR

Identity Address. Type: bt_addr_le_t (7 bytes)

BT_STORAGE_LOCAL_IRK

Local Identity Resolving Key. Type: uint8_t key[16]

BT_STORAGE_ADDRESSES

List of addresses of remote devices. Type: bt_addr_le_t addrs[n] (length is variable).

This is only used for reading. Modification of the list happens implicitly by writing entries for each remote device. This value is only used with the local storage, i.e. NULL as the target bt_addr_le_t passed to the read callback.

BT_STORAGE_SLAVE_LTK

Slave Long Term Key for legacy pairing. Type: struct bt_storage_ltk

BT_STORAGE_LTK

Long Term Key for legacy pairing. Type: struct bt_storage_ltk

BT_STORAGE_IRK

Identity Resolving Key Type: uint8_t key[16]

enum [anonymous]__anonymous18

LTK key flags

Values:

BT_STORAGE_LTK_AUTHENTICATED = BIT(0)
BT_STORAGE_LTK_SC = BIT(1)
void bt_storage_register(const struct bt_storage *storage)

Register callbacks for storage handling.

Parameters
  • storage: Callback struct.

int bt_storage_clear(const bt_addr_le_t *addr)

Clear all storage keys for a specific address

Return
0 on success or negative error value on failure.
Parameters
  • addr: Remote address, NULL for local storage or BT_ADDR_LE_ANY to clear all remote devices.

HCI Drivers

enum bt_hci_driver::bt_hci_driver_bus

Possible values for the ‘bus’ member of the bt_hci_driver struct

Values:

BT_HCI_DRIVER_BUS_VIRTUAL = 0
BT_HCI_DRIVER_BUS_USB = 1
BT_HCI_DRIVER_BUS_PCCARD = 2
BT_HCI_DRIVER_BUS_UART = 3
BT_HCI_DRIVER_BUS_RS232 = 4
BT_HCI_DRIVER_BUS_PCI = 5
BT_HCI_DRIVER_BUS_SDIO = 6
BT_HCI_DRIVER_BUS_SPI = 7
BT_HCI_DRIVER_BUS_I2C = 8
static bool bt_hci_evt_is_prio(uint8_t evt)

Check if an HCI event is high priority or not.

Helper for the HCI driver to know which events are ok to be passed through the RX thread and which must be given to bt_recv_prio() from another context (e.g. ISR). If this function returns true it’s safe to pass the event through the RX thread, however if it returns false then this risks a deadlock.

Return
true if the event can be processed in the RX thread, false if it cannot.
Parameters
  • evt: HCI event code.

int bt_recv(struct net_buf *buf)

Receive data from the controller/HCI driver.

This is the main function through which the HCI driver provides the host with data from the controller. The buffer needs to have its type set with the help of bt_buf_set_type() before calling this API. This API should not be used for so-called high priority HCI events, which should instead be delivered to the host stack through bt_recv_prio().

Return
0 on success or negative error number on failure.
Parameters
  • buf: Network buffer containing data from the controller.

int bt_recv_prio(struct net_buf *buf)

Receive high priority data from the controller/HCI driver.

This is the same as bt_recv(), except that it should be used for so-called high priority HCI events. There’s a separate bt_hci_evt_is_prio() helper that can be used to identify which events are high priority.

As with bt_recv(), the buffer needs to have its type set with the help of bt_buf_set_type() before calling this API. The only exception is so called high priority HCI events which should be delivered to the host stack through bt_recv_prio() instead.

Return
0 on success or negative error number on failure.
Parameters
  • buf: Network buffer containing data from the controller.

int bt_hci_driver_register(struct bt_hci_driver *drv)

Register a new HCI driver to the Bluetooth stack.

This needs to be called before any application code runs. The bt_enable() API will fail if there is no driver registered.

Return
0 on success or negative error number on failure.
Parameters

struct bt_hci_driver
#include <hci_driver.h>

Abstraction which represents the HCI transport to the controller.

This struct is used to represent the HCI transport to the Bluetooth controller.

HCI RAW channel

HCI RAW channel API is intended to expose HCI interface to the remote entity. The local Bluetooth controller gets owned by the remote entity and host Bluetooth stack is not used. RAW API provides direct access to packets which are sent and received by the Bluetooth HCI driver.

int bt_send(struct net_buf *buf)

Send packet to the Bluetooth controller.

Send packet to the Bluetooth controller. Caller needs to implement netbuf pool.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • buf: netbuf packet to be send

int bt_enable_raw(struct k_fifo *rx_queue)

Enable Bluetooth RAW channel.

Enable Bluetooth RAW HCI channel.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • rx_queue: netbuf queue where HCI packets received from the Bluetooth controller are to be queued. The queue is defined in the caller while the available buffers pools are handled in the stack.