Bluetooth API¶

Generic Access Profile (GAP)
Connection Management
Generic Attribute Profile (GATT)
Mesh Profile
Universal Unique Identifiers (UUIDs)
Logical Link Control and Adaptation Protocol (L2CAP)
Serial Port Emulation (RFCOMM)
Data Buffers
Persistent Storage
HCI Drivers
HCI RAW channel

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_BT_CONN and any BR/EDR (Bluetooth Classic) APIs require CONFIG_BT_BREDR.

Generic Access Profile (GAP)¶

enum [anonymous]::__anonymous22¶

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.

BT_LE_ADV_OPT_ONE_TIME = BIT(1)¶: Don’t try to resume connectable advertising after a connection. This option is only meaningful when used together with BT_LE_ADV_OPT_CONNECTABLE. If set the advertising will be stopped when bt_le_adv_stop() is called or when an incoming (slave) connection happens. If this option is not set the stack will take care of keeping advertising enabled even as connections occur.

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 containing 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_BT_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.

BT_DATA(_type, _data, _data_len)¶

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...)¶

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)¶

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_NCONN¶

BT_LE_SCAN_PARAM(_type, _filter, _interval, _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¶: Helper macro to enable active scanning to discover new devices.

BT_LE_SCAN_PASSIVE¶

Helper macro to enable passive scanning to discover new devices.

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

BT_ADDR_STR_LEN¶

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¶

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]::__anonymous23¶

Connection Type

Values:

BT_CONN_TYPE_LE¶: LE Connection Type

BT_CONN_TYPE_BR¶: BR/EDR Connection Type

BT_CONN_TYPE_SCO¶: SCO Connection Type

enum [anonymous]::__anonymous24¶

Connection role (master or slave)

Values:

BT_CONN_ROLE_MASTER¶

BT_CONN_ROLE_SLAVE¶

enum bt_conn::bt_security_t¶

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

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, u8_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. Every time the device loses 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 canceled 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 (e.g., input output capabilities).

Return

0 on success or negative error

Parameters

conn: Connection object.
sec: Requested security level.

u8_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.

struct bt_conn *bt_conn_create_sco(const bt_addr_t *peer)¶

Initiate an SCO connection to a remote device.

Allows initiate new SCO 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.

BT_LE_CONN_PARAM(int_min, int_max, lat, 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¶: Default LE connection parameters: Connection Interval: 30-50 ms Latency: 0 Timeout: 4 s

BT_BR_CONN_PARAM(role_switch)¶

Helper to declare BR/EDR connection parameters inline

Parameters

role_switch: True if role switch is allowed

BT_BR_CONN_PARAM_DEFAULT¶: 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

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 permissible 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]::__anonymous27¶

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]::__anonymous28¶

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]::__anonymous29¶

Values:

BT_GATT_ITER_STOP = 0¶

BT_GATT_ITER_CONTINUE¶

enum [anonymous]::__anonymous30¶

Values:

BT_GATT_DISCOVER_PRIMARY¶

BT_GATT_DISCOVER_SECONDARY¶

BT_GATT_DISCOVER_INCLUDE¶

BT_GATT_DISCOVER_CHARACTERISTIC¶

BT_GATT_DISCOVER_DESCRIPTOR¶

enum [anonymous]::__anonymous31¶

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.

int bt_gatt_service_register(struct bt_gatt_service *svc)¶

Register GATT service.

Register GATT service. 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

svc: Service containing the available attributes

int bt_gatt_service_unregister(struct bt_gatt_service *svc)¶

Unregister GATT service. *.

Return

0 in case of success or negative value in case of error.

Parameters

svc: Service to be unregistered.

void bt_gatt_foreach_attr(u16_t start_handle, u16_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, u16_t buf_len, u16_t offset, const void *value, u16_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, u16_t len, u16_t offset)¶

Read Service Attribute helper.

Read service attribute value storing the result into buffer after encoding 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, u16_t len, u16_t offset)¶

Read Include Attribute helper.

Read include service attribute value storing the result into buffer after encoding 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, u16_t len, u16_t offset)¶

Read Characteristic Attribute helper.

Read characteristic attribute value storing the result into buffer after encoding 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, u16_t len, u16_t offset)¶

Read Client Characteristic Configuration Attribute helper.

Read CCC attribute value storing the result into buffer after encoding 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, u16_t len, u16_t offset, u8_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, u16_t len, u16_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, u16_t len, u16_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, u16_t len, u16_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, u16_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.

The attribute object must be the so called Characteristic Value Descriptor, its usually declared with BT_GATT_DESCRIPTOR after BT_GATT_CHARACTERISTIC and before BT_GATT_CCC.

Parameters

conn: Connection object.
attr: Characteristic Value Descriptor attribute.
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.

u16_t bt_gatt_get_mtu(struct bt_conn *conn)¶

Get ATT MTU for a connection.

Get negotiated ATT connection MTU, note that this does not equal the largest amount of attribute data that can be transferred within a single packet.

Return

MTU in bytes

Parameters

conn: Connection object.

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, u16_t handle, const void *data, u16_t length, bool sign)¶

Write Attribute Value by handle without response.

This procedure write the attribute value without requiring an acknowledgment 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 be called if subscription was removed by this call, until then the parameters cannot be reused.

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)¶

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¶

Characteristic broadcast property.

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

BT_GATT_CHRC_READ¶

Characteristic read property.

If set, permits reads of the Characteristic Value.

BT_GATT_CHRC_WRITE_WITHOUT_RESP¶

Characteristic write without response property.

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

BT_GATT_CHRC_WRITE¶

Characteristic write with response property.

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

BT_GATT_CHRC_NOTIFY¶

Characteristic notify property.

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

BT_GATT_CHRC_INDICATE¶

Characteristic indicate property.

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

BT_GATT_CHRC_AUTH¶

Characteristic Authenticated Signed Writes property.

If set, permits signed writes to the Characteristic Value.

BT_GATT_CHRC_EXT_PROP¶

Characteristic Extended Properties property.

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

BT_GATT_CEP_RELIABLE_WRITE¶

BT_GATT_CEP_WRITABLE_AUX¶

BT_GATT_CCC_NOTIFY¶

Client Characteristic Configuration Notification.

If set, changes to Characteristic Value shall be notified.

BT_GATT_CCC_INDICATE¶

Client Characteristic Configuration Indication.

If set, changes to Characteristic Value shall be indicated.

BT_GATT_SERVICE(_attrs)¶

Service Structure Declaration Macro.

Helper macro to declare a service structure.

Parameters

_attrs: Service attributes.

BT_GATT_PRIMARY_SERVICE(_service)¶

Primary Service Declaration Macro.

Helper macro to declare a primary service attribute.

Parameters

_service: Service attribute value.

BT_GATT_SECONDARY_SERVICE(_service)¶

Secondary Service Declaration Macro.

Helper macro to declare a secondary service attribute.

Parameters

_service: Service attribute value.

BT_GATT_INCLUDE_SERVICE(_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)¶

Characteristic Declaration Macro.

Helper macro to declare a characteristic attribute.

Parameters

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

BT_GATT_CCC_MAX¶

BT_GATT_CCC(_cfg, _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)¶

Characteristic Extended Properties Declaration Macro.

Helper macro to declare a CEP attribute.

Parameters

_value: Descriptor attribute value.

BT_GATT_CUD(_value, _perm)¶

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)¶

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)¶

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>
GATT Service structure.

struct bt_gatt_service_val¶: #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.

Parameters

valid: Valid flag
peer: Remote peer address
value: Configuration value.
data: Configuration pointer data.

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.

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

struct bt_gatt_write_params¶: #include <gatt.h>
GATT Write parameters.

struct bt_gatt_subscribe_params¶: #include <gatt.h>
GATT Subscribe parameters.

Mesh Profile ¶

int bt_mesh_init(const struct bt_mesh_prov *prov, const struct bt_mesh_comp *comp)¶

Initialize Mesh support.

Return

Zero on success or (negative) error code otherwise.

Parameters

prov: Node provisioning information.
comp: Node Composition.

void bt_mesh_reset(void)¶

Reset the state of the local Mesh node.

Resets the state of the node, which in turn causes it to start sending out unprovisioned beacons.

int bt_mesh_provision(const u8_t net_key[16], u16_t net_idx, u8_t flags, u32_t iv_index, u32_t seq, u16_t addr, const u8_t dev_key[16])¶

Provision the local Mesh Node.

This API should normally not be used directly by the application. The only exception is for testing purposes where manual provisioning is desired without an actual external provisioner.

Return

Zero on success or (negative) error code otherwise.

Parameters

net_key: Network Key
net_idx: Network Key Index
flags: Provisioning Flags
iv_index: IV Index
seq: Sequence Number (0 if newly provisioned).
addr: Primary element address
dev_key: Device Key

int bt_mesh_lpn_set(bool enable)¶

Toggle the Low Power feature of the local device.

Enables or disables the Low Power feature of the local device. This is exposed as a run-time feature, since the device might want to change this e.g. based on being plugged into a stable power source or running from a battery power source.

Return

Zero on success or (negative) error code otherwise.

Parameters

enable: true to enable LPN functionality, false to disable it.

BT_MESH_NET_PRIMARY¶

BT_MESH_RELAY_DISABLED¶

BT_MESH_RELAY_ENABLED¶

BT_MESH_RELAY_NOT_SUPPORTED¶

BT_MESH_BEACON_DISABLED¶

BT_MESH_BEACON_ENABLED¶

BT_MESH_GATT_PROXY_DISABLED¶

BT_MESH_GATT_PROXY_ENABLED¶

BT_MESH_GATT_PROXY_NOT_SUPPORTED¶

BT_MESH_FRIEND_DISABLED¶

BT_MESH_FRIEND_ENABLED¶

BT_MESH_FRIEND_NOT_SUPPORTED¶

BT_MESH_NODE_IDENTITY_STOPPED¶

BT_MESH_NODE_IDENTITY_RUNNING¶

BT_MESH_NODE_IDENTITY_NOT_SUPPORTED¶

BT_MESH_FEAT_RELAY¶

BT_MESH_FEAT_PROXY¶

BT_MESH_FEAT_FRIEND¶

BT_MESH_FEAT_LOW_POWER¶

Universal Unique Identifiers (UUIDs)¶

enum [anonymous]::__anonymous47¶

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)¶

BT_UUID_INIT_32(value)¶

BT_UUID_INIT_128(value...)¶

BT_UUID_DECLARE_16(value)¶

BT_UUID_DECLARE_32(value)¶

BT_UUID_DECLARE_128(value...)¶

BT_UUID_16(__u)¶

BT_UUID_32(__u)¶

BT_UUID_128(__u)¶

BT_UUID_GAP¶: Generic Access.

BT_UUID_GAP_VAL¶

BT_UUID_GATT¶: Generic Attribute.

BT_UUID_GATT_VAL¶

BT_UUID_CTS¶: Current Time Service.

BT_UUID_CTS_VAL¶

BT_UUID_DIS¶: Device Information Service.

BT_UUID_DIS_VAL¶

BT_UUID_HRS¶: Heart Rate Service.

BT_UUID_HRS_VAL¶

BT_UUID_BAS¶: Battery Service.

BT_UUID_BAS_VAL¶

BT_UUID_HIDS¶: HID Service.

BT_UUID_HIDS_VAL¶

BT_UUID_CSC¶: Cycling Speed and Cadence Service.

BT_UUID_CSC_VAL¶

BT_UUID_ESS¶: Environmental Sensing Service.

BT_UUID_ESS_VAL¶

BT_UUID_IPSS¶: IP Support Service.

BT_UUID_IPSS_VAL¶

BT_UUID_MESH_PROV¶: Mesh Provisioning Service.

BT_UUID_MESH_PROV_VAL¶

BT_UUID_MESH_PROXY¶: Mesh Proxy Service.

BT_UUID_MESH_PROXY_VAL¶

BT_UUID_GATT_PRIMARY¶: GATT Primary Service.

BT_UUID_GATT_PRIMARY_VAL¶

BT_UUID_GATT_SECONDARY¶: GATT Secondary Service.

BT_UUID_GATT_SECONDARY_VAL¶

BT_UUID_GATT_INCLUDE¶: GATT Include Service.

BT_UUID_GATT_INCLUDE_VAL¶

BT_UUID_GATT_CHRC¶: GATT Characteristic.

BT_UUID_GATT_CHRC_VAL¶

BT_UUID_GATT_CEP¶: GATT Characteristic Extended Properties.

BT_UUID_GATT_CEP_VAL¶

BT_UUID_GATT_CUD¶: GATT Characteristic User Description.

BT_UUID_GATT_CUD_VAL¶

BT_UUID_GATT_CCC¶: GATT Client Characteristic Configuration.

BT_UUID_GATT_CCC_VAL¶

BT_UUID_GATT_SCC¶: GATT Server Characteristic Configuration.

BT_UUID_GATT_SCC_VAL¶

BT_UUID_GATT_CPF¶: GATT Characteristic Presentation Format.

BT_UUID_GATT_CPF_VAL¶

BT_UUID_VALID_RANGE¶: Valid Range Descriptor.

BT_UUID_VALID_RANGE_VAL¶

BT_UUID_HIDS_EXT_REPORT¶: HID External Report Descriptor.

BT_UUID_HIDS_EXT_REPORT_VAL¶

BT_UUID_HIDS_REPORT_REF¶: HID Report Reference Descriptor.

BT_UUID_HIDS_REPORT_REF_VAL¶

BT_UUID_ES_CONFIGURATION¶: Environmental Sensing Configuration Descriptor.

BT_UUID_ES_CONFIGURATION_VAL¶

BT_UUID_ES_MEASUREMENT¶: Environmental Sensing Measurement Descriptor.

BT_UUID_ES_MEASUREMENT_VAL¶

BT_UUID_ES_TRIGGER_SETTING¶: Environmental Sensing Trigger Setting Descriptor.

BT_UUID_ES_TRIGGER_SETTING_VAL¶

BT_UUID_GAP_DEVICE_NAME¶: GAP Characteristic Device Name.

BT_UUID_GAP_DEVICE_NAME_VAL¶

BT_UUID_GAP_APPEARANCE¶: GAP Characteristic Appearance.

BT_UUID_GAP_APPEARANCE_VAL¶

BT_UUID_GAP_PPCP¶: GAP Characteristic Peripheral Preferred Connection Parameters.

BT_UUID_GAP_PPCP_VAL¶

BT_UUID_GATT_SC¶: GATT Characteristic Service Changed.

BT_UUID_GATT_SC_VAL¶

BT_UUID_BAS_BATTERY_LEVEL¶: BAS Characteristic Battery Level.

BT_UUID_BAS_BATTERY_LEVEL_VAL¶

BT_UUID_DIS_SYSTEM_ID¶: DIS Characteristic System ID.

BT_UUID_DIS_SYSTEM_ID_VAL¶

BT_UUID_DIS_MODEL_NUMBER¶: DIS Characteristic Model Number String.

BT_UUID_DIS_MODEL_NUMBER_VAL¶

BT_UUID_DIS_SERIAL_NUMBER¶: DIS Characteristic Serial Number String.

BT_UUID_DIS_SERIAL_NUMBER_VAL¶

BT_UUID_DIS_FIRMWARE_REVISION¶: DIS Characteristic Firmware Revision String.

BT_UUID_DIS_FIRMWARE_REVISION_VAL¶

BT_UUID_DIS_HARDWARE_REVISION¶: DIS Characteristic Hardware Revision String.

BT_UUID_DIS_HARDWARE_REVISION_VAL¶

BT_UUID_DIS_SOFTWARE_REVISION¶: DIS Characteristic Software Revision String.

BT_UUID_DIS_SOFTWARE_REVISION_VAL¶

BT_UUID_DIS_MANUFACTURER_NAME¶: DIS Characteristic Manufacturer Name String.

BT_UUID_DIS_MANUFACTURER_NAME_VAL¶

BT_UUID_DIS_PNP_ID¶: DIS Characteristic PnP ID.

BT_UUID_DIS_PNP_ID_VAL¶

BT_UUID_CTS_CURRENT_TIME¶: CTS Characteristic Current Time.

BT_UUID_CTS_CURRENT_TIME_VAL¶

BT_UUID_MAGN_DECLINATION¶: Magnetic Declination Characteristic.

BT_UUID_MAGN_DECLINATION_VAL¶

BT_UUID_HRS_MEASUREMENT¶: HRS Characteristic Measurement Interval.

BT_UUID_HRS_MEASUREMENT_VAL¶

BT_UUID_HRS_BODY_SENSOR¶: HRS Characteristic Body Sensor Location.

BT_UUID_HRS_BODY_SENSOR_VAL¶

BT_UUID_HRS_CONTROL_POINT¶: HRS Characteristic Control Point.

BT_UUID_HRS_CONTROL_POINT_VAL¶

BT_UUID_HIDS_INFO¶: HID Information Characteristic.

BT_UUID_HIDS_INFO_VAL¶

BT_UUID_HIDS_REPORT_MAP¶: HID Report Map Characteristic.

BT_UUID_HIDS_REPORT_MAP_VAL¶

BT_UUID_HIDS_CTRL_POINT¶: HID Control Point Characteristic.

BT_UUID_HIDS_CTRL_POINT_VAL¶

BT_UUID_HIDS_REPORT¶: HID Report Characteristic.

BT_UUID_HIDS_REPORT_VAL¶

BT_UUID_CSC_MEASUREMENT¶: CSC Measurement Characteristic.

BT_UUID_CSC_MEASUREMENT_VAL¶

BT_UUID_CSC_FEATURE¶: CSC Feature Characteristic.

BT_UUID_CSC_FEATURE_VAL¶

BT_UUID_SENSOR_LOCATION¶: Sensor Location Characteristic.

BT_UUID_SENSOR_LOCATION_VAL¶

BT_UUID_SC_CONTROL_POINT¶: SC Control Point Characteristic.

BT_UUID_SC_CONTROL_POINT_VAl¶

BT_UUID_ELEVATION¶: Elevation Characteristic.

BT_UUID_ELEVATION_VAL¶

BT_UUID_PRESSURE¶: Pressure Characteristic.

BT_UUID_PRESSURE_VAL¶

BT_UUID_TEMPERATURE¶: Temperature Characteristic.

BT_UUID_TEMPERATURE_VAL¶

BT_UUID_HUMIDITY¶: Humidity Characteristic.

BT_UUID_HUMIDITY_VAL¶

BT_UUID_TRUE_WIND_SPEED¶: True Wind Speed Characteristic.

BT_UUID_TRUE_WIND_SPEED_VAL¶

BT_UUID_TRUE_WIND_DIR¶: True Wind Direction Characteristic.

BT_UUID_TRUE_WIND_DIR_VAL¶

BT_UUID_APPARENT_WIND_SPEED¶: Apparent Wind Speed Characteristic.

BT_UUID_APPARENT_WIND_SPEED_VAL¶

BT_UUID_APPARENT_WIND_DIR¶: Apparent Wind Direction Characteristic.

BT_UUID_APPARENT_WIND_DIR_VAL¶

BT_UUID_GUST_FACTOR¶: Gust Factor Characteristic.

BT_UUID_GUST_FACTOR_VAL¶

BT_UUID_POLLEN_CONCENTRATION¶: Pollen Concentration Characteristic.

BT_UUID_POLLEN_CONCENTRATION_VAL¶

BT_UUID_UV_INDEX¶: UV Index Characteristic.

BT_UUID_UV_INDEX_VAL¶

BT_UUID_IRRADIANCE¶: Irradiance Characteristic.

BT_UUID_IRRADIANCE_VAL¶

BT_UUID_RAINFALL¶: Rainfall Characteristic.

BT_UUID_RAINFALL_VAL¶

BT_UUID_WIND_CHILL¶: Wind Chill Characteristic.

BT_UUID_WIND_CHILL_VAL¶

BT_UUID_HEAT_INDEX¶: Heat Index Characteristic.

BT_UUID_HEAT_INDEX_VAL¶

BT_UUID_DEW_POINT¶: Dew Point Characteristic.

BT_UUID_DEW_POINT_VAL¶

BT_UUID_DESC_VALUE_CHANGED¶: Descriptor Value Changed Characteristic.

BT_UUID_DESC_VALUE_CHANGED_VAL¶

BT_UUID_MAGN_FLUX_DENSITY_2D¶: Magnetic Flux Density - 2D Characteristic.

BT_UUID_MAGN_FLUX_DENSITY_2D_VAL¶

BT_UUID_MAGN_FLUX_DENSITY_3D¶: Magnetic Flux Density - 3D Characteristic.

BT_UUID_MAGN_FLUX_DENSITY_3D_VAL¶

BT_UUID_BAR_PRESSURE_TREND¶: Barometric Pressure Trend Characteristic.

BT_UUID_BAR_PRESSURE_TREND_VAL¶

BT_UUID_MESH_PROV_DATA_IN¶: Mesh Provisioning Data In.

BT_UUID_MESH_PROV_DATA_IN_VAL¶

BT_UUID_MESH_PROV_DATA_OUT¶: Mesh Provisioning Data Out.

BT_UUID_MESH_PROV_DATA_OUT_VAL¶

BT_UUID_MESH_PROXY_DATA_IN¶: Mesh Proxy Data In.

BT_UUID_MESH_PROXY_DATA_IN_VAL¶

BT_UUID_MESH_PROXY_DATA_OUT¶: Mesh Proxy Data Out.

BT_UUID_MESH_PROXY_DATA_OUT_VAL¶

BT_UUID_SDP¶

BT_UUID_SDP_VAL¶

BT_UUID_UDP¶

BT_UUID_UDP_VAL¶

BT_UUID_RFCOMM¶

BT_UUID_RFCOMM_VAL¶

BT_UUID_TCP¶

BT_UUID_TCP_VAL¶

BT_UUID_TCS_BIN¶

BT_UUID_TCS_BIN_VAL¶

BT_UUID_TCS_AT¶

BT_UUID_TCS_AT_VAL¶

BT_UUID_ATT¶

BT_UUID_ATT_VAL¶

BT_UUID_OBEX¶

BT_UUID_OBEX_VAL¶

BT_UUID_IP¶

BT_UUID_IP_VAL¶

BT_UUID_FTP¶

BT_UUID_FTP_VAL¶

BT_UUID_HTTP¶

BT_UUID_HTTP_VAL¶

BT_UUID_BNEP¶

BT_UUID_BNEP_VAL¶

BT_UUID_UPNP¶

BT_UUID_UPNP_VAL¶

BT_UUID_HIDP¶

BT_UUID_HIDP_VAL¶

BT_UUID_HCRP_CTRL¶

BT_UUID_HCRP_CTRL_VAL¶

BT_UUID_HCRP_DATA¶

BT_UUID_HCRP_DATA_VAL¶

BT_UUID_HCRP_NOTE¶

BT_UUID_HCRP_NOTE_VAL¶

BT_UUID_AVCTP¶

BT_UUID_AVCTP_VAL¶

BT_UUID_AVDTP¶

BT_UUID_AVDTP_VAL¶

BT_UUID_CMTP¶

BT_UUID_CMTP_VAL¶

BT_UUID_UDI¶

BT_UUID_UDI_VAL¶

BT_UUID_MCAP_CTRL¶

BT_UUID_MCAP_CTRL_VAL¶

BT_UUID_MCAP_DATA¶

BT_UUID_MCAP_DATA_VAL¶

BT_UUID_L2CAP¶

BT_UUID_L2CAP_VAL¶

struct bt_uuid¶: #include <uuid.h>
This is a ‘tentative’ type and should be used as a pointer only.

Logical Link Control and Adaptation Protocol (L2CAP)¶

enum bt_l2cap::bt_l2cap_chan_state¶

Life-span states of L2CAP CoC channel. Used only by internal APIs dealing with setting channel to proper state depending on operational context.

Values:

BT_L2CAP_DISCONNECTED¶: Channel disconnected

BT_L2CAP_CONNECT¶: Channel in connecting state

BT_L2CAP_CONFIG¶: Channel in config state, BR/EDR specific

BT_L2CAP_CONNECTED¶: Channel ready for upper layer traffic on it

BT_L2CAP_DISCONNECT¶: Channel in disconnecting state

typedef bt_l2cap_chan_destroy_t¶

Channel destroy callback.

Parameters

chan: Channel object.

typedef enum bt_l2cap_chan_state bt_l2cap_chan_state_t¶: Life-span states of L2CAP CoC channel. Used only by internal APIs dealing with setting channel to proper state depending on operational context.

int bt_l2cap_server_register(struct bt_l2cap_server *server)¶

Register L2CAP server.

Register L2CAP server for a PSM, each new connection is authorized using the accept() callback which in case of success shall allocate the channel 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_l2cap_br_server_register(struct bt_l2cap_server *server)¶

Register L2CAP server on BR/EDR oriented connection.

Register L2CAP server for a PSM, each new connection is authorized using the accept() callback which in case of success shall allocate the channel 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_l2cap_chan_connect(struct bt_conn *conn, struct bt_l2cap_chan *chan, u16_t psm)¶

Connect L2CAP channel.

Connect L2CAP channel by PSM, once the connection is completed channel connected() callback will be called. If the connection is rejected disconnected() callback is called instead. Channel object passed (over an address of it) as second parameter shouldn’t be instantiated in application as standalone. Instead of, application should create transport dedicated L2CAP objects, i.e. type of bt_l2cap_le_chan for LE and/or type of bt_l2cap_br_chan for BR/EDR. Then pass to this API the location (address) of bt_l2cap_chan type object which is a member of both transport dedicated objects.

Return

0 in case of success or negative value in case of error.

Parameters

conn: Connection object.
chan: Channel object.
psm: Channel PSM to connect to.

int bt_l2cap_chan_disconnect(struct bt_l2cap_chan *chan)¶

Disconnect L2CAP channel.

Disconnect L2CAP channel, if the connection is pending it will be canceled and as a result the channel disconnected() callback is called. Regarding to input parameter, to get details see reference description to bt_l2cap_chan_connect() API above.

Return

0 in case of success or negative value in case of error.

Parameters

chan: Channel object.

int bt_l2cap_chan_send(struct bt_l2cap_chan *chan, struct net_buf *buf)¶

Send data to L2CAP channel.

Send data from buffer to the channel. If credits are not available, buf will be queued and sent as and when credits are received from peer. Regarding to first input parameter, to get details see reference description to bt_l2cap_chan_connect() API above.

Return: Bytes sent in case of success or negative value in case of error.

BT_L2CAP_HDR_SIZE¶

BT_L2CAP_BUF_SIZE(mtu)¶

Helper to calculate needed outgoing buffer size, useful e.g. for creating buffer pools.

Return

Needed buffer size to match the requested L2CAP MTU.

Parameters

mtu: Needed L2CAP MTU.

BT_L2CAP_LE_CHAN(_ch)¶

Helper macro getting container object of type bt_l2cap_le_chan address having the same container chan member address as object in question.

Return

Address of in memory bt_l2cap_le_chan object type containing the address of in question object.

Parameters

_ch: Address of object of bt_l2cap_chan type

BT_L2CAP_CHAN_SEND_RESERVE¶: Headroom needed for outgoing buffers.

struct bt_l2cap_chan¶: #include <l2cap.h>
L2CAP Channel structure.

struct bt_l2cap_le_endpoint¶: #include <l2cap.h>
LE L2CAP Endpoint structure.

struct bt_l2cap_le_chan¶: #include <l2cap.h>
LE L2CAP Channel structure.

struct bt_l2cap_br_endpoint¶: #include <l2cap.h>
BREDR L2CAP Endpoint structure.

struct bt_l2cap_br_chan¶: #include <l2cap.h>
BREDR L2CAP Channel structure.

struct bt_l2cap_chan_ops¶: #include <l2cap.h>
L2CAP Channel operations structure.

struct bt_l2cap_server¶: #include <l2cap.h>
L2CAP Server structure.

Serial Port Emulation (RFCOMM)¶

enum [anonymous]::__anonymous43¶

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, u8_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(enum bt_buf_type type, s32_t timeout)¶

Allocate a buffer for incoming data

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

type: Type of buffer. Only BT_BUF_EVT and BT_BUF_ACL_IN are allowed.
timeout: Timeout in milliseconds, or one of the special values K_NO_WAIT and K_FOREVER.

struct net_buf *bt_buf_get_cmd_complete(s32_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¶: Minimum amount of user data size for buffers passed to the stack.

BT_BUF_RX_SIZE¶: Data size neeed for HCI RX buffers

Persistent Storage ¶

enum [anonymous]::__anonymous45¶

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: u8_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: u8_t key[16]

enum [anonymous]::__anonymous46¶

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(u8_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(const 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

drv: A bt_hci_driver struct representing the driver.

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.