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

Bluetooth Mesh Profile

group bt_mesh

Bluetooth Mesh.

Defines

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
BT_MESH_FEAT_SUPPORTED

Functions

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

Initialize Mesh support.

After calling this API, the node will not automatically advertise as unprovisioned, rather the bt_mesh_prov_enable() API needs to be called to enable unprovisioned advertising on one or more provisioning bearers.

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 means that it needs to be reprovisioned to become an active node in a Mesh network again.

After calling this API, the node will not automatically advertise as unprovisioned, rather the bt_mesh_prov_enable() API needs to be called to enable unprovisioned advertising on one or more provisioning bearers.

int bt_mesh_provision(const u8_t net_key[16], u16_t net_idx, u8_t flags, u32_t iv_index, 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
  • addr: Primary element address
  • dev_key: Device Key

bool bt_mesh_is_provisioned(void)

Check if the local node has been provisioned.

This API can be used to check if the local node has been provisioned or not. It can e.g. be helpful to determine if there was a stored network in flash, i.e. if the network was restored after calling settings_load().

Return
True if the node is provisioned. False otherwise.

void bt_mesh_iv_update_test(bool enable)

Toggle the IV Update test mode.

This API is only available if the IV Update test mode has been enabled in Kconfig. It is needed for passing most of the IV Update qualification test cases.

Parameters
  • enable: true to enable IV Update test mode, false to disable it.

bool bt_mesh_iv_update(void)

Toggle the IV Update state.

This API is only available if the IV Update test mode has been enabled in Kconfig. It is needed for passing most of the IV Update qualification test cases.

Return
true if IV Update In Progress state was entered, false otherwise.

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.

int bt_mesh_lpn_poll(void)

Send out a Friend Poll message.

Send a Friend Poll message to the Friend of this node. If there is no established Friendship the function will return an error.

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

void bt_mesh_lpn_set_cb(void (*cb)(u16_t friend_addr, bool established))

Register a callback for Friendship changes.

Registers a callback that will be called whenever Friendship gets established or is lost.

Parameters
  • cb: Function to call when the Friendship status changes.

Bluetooth Mesh Access Layer

group bt_mesh_access

Bluetooth Mesh Access Layer.

Defines

BT_MESH_ADDR_UNASSIGNED
BT_MESH_ADDR_ALL_NODES
BT_MESH_ADDR_PROXIES
BT_MESH_ADDR_FRIENDS
BT_MESH_ADDR_RELAYS
BT_MESH_KEY_UNUSED
BT_MESH_KEY_DEV
BT_MESH_ELEM(_loc, _mods, _vnd_mods)

Helper to define a mesh element within an array.

In case the element has no SIG or Vendor models the helper macro BT_MESH_MODEL_NONE can be given instead.

Parameters
  • _loc: Location Descriptor.
  • _mods: Array of models.
  • _vnd_mods: Array of vendor models.

BT_MESH_MODEL_ID_CFG_SRV
BT_MESH_MODEL_ID_CFG_CLI
BT_MESH_MODEL_ID_HEALTH_SRV
BT_MESH_MODEL_ID_HEALTH_CLI
BT_MESH_MODEL_ID_GEN_ONOFF_SRV
BT_MESH_MODEL_ID_GEN_ONOFF_CLI
BT_MESH_MODEL_ID_GEN_LEVEL_SRV
BT_MESH_MODEL_ID_GEN_LEVEL_CLI
BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_SRV
BT_MESH_MODEL_ID_GEN_DEF_TRANS_TIME_CLI
BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SRV
BT_MESH_MODEL_ID_GEN_POWER_ONOFF_SETUP_SRV
BT_MESH_MODEL_ID_GEN_POWER_ONOFF_CLI
BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SRV
BT_MESH_MODEL_ID_GEN_POWER_LEVEL_SETUP_SRV
BT_MESH_MODEL_ID_GEN_POWER_LEVEL_CLI
BT_MESH_MODEL_ID_GEN_BATTERY_SRV
BT_MESH_MODEL_ID_GEN_BATTERY_CLI
BT_MESH_MODEL_ID_GEN_LOCATION_SRV
BT_MESH_MODEL_ID_GEN_LOCATION_SETUPSRV
BT_MESH_MODEL_ID_GEN_LOCATION_CLI
BT_MESH_MODEL_ID_GEN_ADMIN_PROP_SRV
BT_MESH_MODEL_ID_GEN_MANUFACTURER_PROP_SRV
BT_MESH_MODEL_ID_GEN_USER_PROP_SRV
BT_MESH_MODEL_ID_GEN_CLIENT_PROP_SRV
BT_MESH_MODEL_ID_GEN_PROP_CLI
BT_MESH_MODEL_ID_SENSOR_SRV
BT_MESH_MODEL_ID_SENSOR_SETUP_SRV
BT_MESH_MODEL_ID_SENSOR_CLI
BT_MESH_MODEL_ID_TIME_SRV
BT_MESH_MODEL_ID_TIME_SETUP_SRV
BT_MESH_MODEL_ID_TIME_CLI
BT_MESH_MODEL_ID_SCENE_SRV
BT_MESH_MODEL_ID_SCENE_SETUP_SRV
BT_MESH_MODEL_ID_SCENE_CLI
BT_MESH_MODEL_ID_SCHEDULER_SRV
BT_MESH_MODEL_ID_SCHEDULER_SETUP_SRV
BT_MESH_MODEL_ID_SCHEDULER_CLI
BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SRV
BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_SETUP_SRV
BT_MESH_MODEL_ID_LIGHT_LIGHTNESS_CLI
BT_MESH_MODEL_ID_LIGHT_CTL_SRV
BT_MESH_MODEL_ID_LIGHT_CTL_SETUP_SRV
BT_MESH_MODEL_ID_LIGHT_CTL_CLI
BT_MESH_MODEL_ID_LIGHT_CTL_TEMP_SRV
BT_MESH_MODEL_ID_LIGHT_HSL_SRV
BT_MESH_MODEL_ID_LIGHT_HSL_SETUP_SRV
BT_MESH_MODEL_ID_LIGHT_HSL_CLI
BT_MESH_MODEL_ID_LIGHT_HSL_HUE_SRV
BT_MESH_MODEL_ID_LIGHT_HSL_SAT_SRV
BT_MESH_MODEL_ID_LIGHT_XYL_SRV
BT_MESH_MODEL_ID_LIGHT_XYL_SETUP_SRV
BT_MESH_MODEL_ID_LIGHT_XYL_CLI
BT_MESH_MODEL_ID_LIGHT_LC_SRV
BT_MESH_MODEL_ID_LIGHT_LC_SETUPSRV
BT_MESH_MODEL_ID_LIGHT_LC_CLI
BT_MESH_MODEL_OP_1(b0)
BT_MESH_MODEL_OP_2(b0, b1)
BT_MESH_MODEL_OP_3(b0, cid)
BT_MESH_MODEL_OP_END
BT_MESH_MODEL_NO_OPS
BT_MESH_MODEL_NONE

Helper to define an empty model array

BT_MESH_MODEL(_id, _op, _pub, _user_data)
BT_MESH_MODEL_VND(_company, _id, _op, _pub, _user_data)
BT_MESH_TRANSMIT(count, int_ms)

Encode transmission count & interval steps.

Return
Mesh transmit value that can be used e.g. for the default values of the configuration model data.
Parameters
  • count: Number of retransmissions (first transmission is excluded).
  • int_ms: Interval steps in milliseconds. Must be greater than 0, less than or equal to 320, and a multiple of 10.

BT_MESH_TRANSMIT_COUNT(transmit)

Decode transmit count from a transmit value.

Return
Transmission count (actual transmissions is N + 1).
Parameters
  • transmit: Encoded transmit count & interval value.

BT_MESH_TRANSMIT_INT(transmit)

Decode transmit interval from a transmit value.

Return
Transmission interval in milliseconds.
Parameters
  • transmit: Encoded transmit count & interval value.

BT_MESH_PUB_TRANSMIT(count, int_ms)

Encode Publish Retransmit count & interval steps.

Return
Mesh transmit value that can be used e.g. for the default values of the configuration model data.
Parameters
  • count: Number of retransmissions (first transmission is excluded).
  • int_ms: Interval steps in milliseconds. Must be greater than 0 and a multiple of 50.

BT_MESH_PUB_TRANSMIT_COUNT(transmit)

Decode Publish Retransmit count from a given value.

Return
Retransmission count (actual transmissions is N + 1).
Parameters
  • transmit: Encoded Publish Retransmit count & interval value.

BT_MESH_PUB_TRANSMIT_INT(transmit)

Decode Publish Retransmit interval from a given value.

Return
Transmission interval in milliseconds.
Parameters
  • transmit: Encoded Publish Retransmit count & interval value.

BT_MESH_MODEL_PUB_DEFINE(_name, _update, _msg_len)

Define a model publication context.

Parameters
  • _name: Variable name given to the context.
  • _update: Optional message update callback (may be NULL).
  • _msg_len: Length of the publication message.

BT_MESH_TTL_DEFAULT

Special TTL value to request using configured default TTL

BT_MESH_TTL_MAX

Maximum allowed TTL value

Functions

void bt_mesh_model_msg_init(struct net_buf_simple *msg, u32_t opcode)
int bt_mesh_model_send(struct bt_mesh_model *model, struct bt_mesh_msg_ctx *ctx, struct net_buf_simple *msg, const struct bt_mesh_send_cb *cb, void *cb_data)

Send an Access Layer message.

Return
0 on success, or (negative) error code on failure.
Parameters
  • model: Mesh (client) Model that the message belongs to.
  • ctx: Message context, includes keys, TTL, etc.
  • msg: Access Layer payload (the actual message to be sent).
  • cb: Optional “message sent” callback.
  • cb_data: User data to be passed to the callback.

int bt_mesh_model_publish(struct bt_mesh_model *model)

Send a model publication message.

Before calling this function, the user needs to ensure that the model publication message (bt_mesh_model_pub::msg) contains a valid message to be sent. Note that this API is only to be used for non-period publishing. For periodic publishing the app only needs to make sure that bt_mesh_model_pub::msg contains a valid message whenever the bt_mesh_model_pub::update callback is called.

Return
0 on success, or (negative) error code on failure.
Parameters
  • model: Mesh (client) Model that’s publishing the message.

struct bt_mesh_elem *bt_mesh_model_elem(struct bt_mesh_model *mod)

Get the element that a model belongs to.

Return
Pointer to the element that the given model belongs to.
Parameters
  • mod: Mesh model.

struct bt_mesh_elem
#include <access.h>

Abstraction that describes a Mesh Element

struct bt_mesh_msg_ctx
#include <access.h>

Message sending context.

struct bt_mesh_model_pub
#include <access.h>

Model publication context.

The context should primarily be created using the BT_MESH_MODEL_PUB_DEFINE macro.

struct bt_mesh_model
#include <access.h>

Abstraction that describes a Mesh Model instance

struct bt_mesh_comp
#include <access.h>

Node Composition

Bluetooth Mesh Configuration Client Model

group bt_mesh_cfg_cli

Bluetooth Mesh.

Defines

BT_MESH_MODEL_CFG_CLI(cli_data)

Functions

int bt_mesh_cfg_comp_data_get(u16_t net_idx, u16_t addr, u8_t page, u8_t *status, struct net_buf_simple *comp)
int bt_mesh_cfg_beacon_get(u16_t net_idx, u16_t addr, u8_t *status)
int bt_mesh_cfg_beacon_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status)
int bt_mesh_cfg_ttl_get(u16_t net_idx, u16_t addr, u8_t *ttl)
int bt_mesh_cfg_ttl_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *ttl)
int bt_mesh_cfg_friend_get(u16_t net_idx, u16_t addr, u8_t *status)
int bt_mesh_cfg_friend_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status)
int bt_mesh_cfg_gatt_proxy_get(u16_t net_idx, u16_t addr, u8_t *status)
int bt_mesh_cfg_gatt_proxy_set(u16_t net_idx, u16_t addr, u8_t val, u8_t *status)
int bt_mesh_cfg_relay_get(u16_t net_idx, u16_t addr, u8_t *status, u8_t *transmit)
int bt_mesh_cfg_relay_set(u16_t net_idx, u16_t addr, u8_t new_relay, u8_t new_transmit, u8_t *status, u8_t *transmit)
int bt_mesh_cfg_net_key_add(u16_t net_idx, u16_t addr, u16_t key_net_idx, const u8_t net_key[16], u8_t *status)
int bt_mesh_cfg_app_key_add(u16_t net_idx, u16_t addr, u16_t key_net_idx, u16_t key_app_idx, const u8_t app_key[16], u8_t *status)
int bt_mesh_cfg_mod_app_bind(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_app_idx, u16_t mod_id, u8_t *status)
int bt_mesh_cfg_mod_app_bind_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_app_idx, u16_t mod_id, u16_t cid, u8_t *status)
int bt_mesh_cfg_mod_pub_get(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)
int bt_mesh_cfg_mod_pub_get_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, u16_t cid, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)
int bt_mesh_cfg_mod_pub_set(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)
int bt_mesh_cfg_mod_pub_set_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t mod_id, u16_t cid, struct bt_mesh_cfg_mod_pub *pub, u8_t *status)
int bt_mesh_cfg_mod_sub_add(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status)
int bt_mesh_cfg_mod_sub_add_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status)
int bt_mesh_cfg_mod_sub_del(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status)
int bt_mesh_cfg_mod_sub_del_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status)
int bt_mesh_cfg_mod_sub_overwrite(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u8_t *status)
int bt_mesh_cfg_mod_sub_overwrite_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, u16_t sub_addr, u16_t mod_id, u16_t cid, u8_t *status)
int bt_mesh_cfg_mod_sub_va_add(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status)
int bt_mesh_cfg_mod_sub_va_add_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status)
int bt_mesh_cfg_mod_sub_va_del(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status)
int bt_mesh_cfg_mod_sub_va_del_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status)
int bt_mesh_cfg_mod_sub_va_overwrite(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t *virt_addr, u8_t *status)
int bt_mesh_cfg_mod_sub_va_overwrite_vnd(u16_t net_idx, u16_t addr, u16_t elem_addr, const u8_t label[16], u16_t mod_id, u16_t cid, u16_t *virt_addr, u8_t *status)
int bt_mesh_cfg_hb_sub_set(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_sub *sub, u8_t *status)
int bt_mesh_cfg_hb_sub_get(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_sub *sub, u8_t *status)
int bt_mesh_cfg_hb_pub_set(u16_t net_idx, u16_t addr, const struct bt_mesh_cfg_hb_pub *pub, u8_t *status)
int bt_mesh_cfg_hb_pub_get(u16_t net_idx, u16_t addr, struct bt_mesh_cfg_hb_pub *pub, u8_t *status)
s32_t bt_mesh_cfg_cli_timeout_get(void)
void bt_mesh_cfg_cli_timeout_set(s32_t timeout)

Variables

const struct bt_mesh_model_op bt_mesh_cfg_cli_op[]
struct bt_mesh_cfg_cli
#include <cfg_cli.h>

Mesh Configuration Client Model Context

Bluetooth Mesh Configuration Server Model

group bt_mesh_cfg_srv

Bluetooth Mesh.

Defines

BT_MESH_MODEL_CFG_SRV(srv_data)

Variables

const struct bt_mesh_model_op bt_mesh_cfg_srv_op[]
struct bt_mesh_cfg_srv
#include <cfg_srv.h>

Mesh Configuration Server Model Context

Bluetooth Mesh Health Client Model

group bt_mesh_health_cli

Bluetooth Mesh.

Defines

BT_MESH_MODEL_HEALTH_CLI(cli_data)

Functions

int bt_mesh_health_cli_set(struct bt_mesh_model *model)
int bt_mesh_health_fault_get(u16_t net_idx, u16_t addr, u16_t app_idx, u16_t cid, u8_t *test_id, u8_t *faults, size_t *fault_count)
int bt_mesh_health_fault_clear(u16_t net_idx, u16_t addr, u16_t app_idx, u16_t cid, u8_t *test_id, u8_t *faults, size_t *fault_count)
int bt_mesh_health_fault_test(u16_t net_idx, u16_t addr, u16_t app_idx, u16_t cid, u8_t test_id, u8_t *faults, size_t *fault_count)
int bt_mesh_health_period_get(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t *divisor)
int bt_mesh_health_period_set(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t divisor, u8_t *updated_divisor)
int bt_mesh_health_attention_get(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t *attention)
int bt_mesh_health_attention_set(u16_t net_idx, u16_t addr, u16_t app_idx, u8_t attention, u8_t *updated_attention)
s32_t bt_mesh_health_cli_timeout_get(void)
void bt_mesh_health_cli_timeout_set(s32_t timeout)

Variables

const struct bt_mesh_model_op bt_mesh_health_cli_op[]
struct bt_mesh_health_cli
#include <health_cli.h>

Mesh Health Client Model Context

Bluetooth Mesh Health Server Model

group bt_mesh_health_srv

Bluetooth Mesh Health Server Model.

Defines

BT_MESH_HEALTH_PUB_DEFINE(_name, _max_faults)

A helper to define a health publication context

Parameters
  • _name: Name given to the publication context variable.
  • _max_faults: Maximum number of faults the element can have.

BT_MESH_MODEL_HEALTH_SRV(srv, pub)

Define a new health server model. Note that this API needs to be repeated for each element that the application wants to have a health server model on. Each instance also needs a unique bt_mesh_health_srv and bt_mesh_model_pub context.

Return
New mesh model instance.
Parameters

Functions

int bt_mesh_fault_update(struct bt_mesh_elem *elem)

Variables

const struct bt_mesh_model_op bt_mesh_health_srv_op[]
struct bt_mesh_health_srv
#include <health_srv.h>

Mesh Health Server Model Context

Bluetooth Mesh Provisioning

group bt_mesh_prov

Bluetooth Mesh Provisioning.

Enums

enum bt_mesh_output_action_t

Values:

BT_MESH_NO_OUTPUT = 0
BT_MESH_BLINK = BIT(0)
BT_MESH_BEEP = BIT(1)
BT_MESH_VIBRATE = BIT(2)
BT_MESH_DISPLAY_NUMBER = BIT(3)
BT_MESH_DISPLAY_STRING = BIT(4)
enum bt_mesh_input_action_t

Values:

BT_MESH_NO_INPUT = 0
BT_MESH_PUSH = BIT(0)
BT_MESH_TWIST = BIT(1)
BT_MESH_ENTER_NUMBER = BIT(2)
BT_MESH_ENTER_STRING = BIT(3)
enum bt_mesh_prov_bearer_t

Values:

BT_MESH_PROV_ADV = BIT(0)
BT_MESH_PROV_GATT = BIT(1)
enum bt_mesh_prov_oob_info_t

Values:

BT_MESH_PROV_OOB_OTHER = BIT(0)
BT_MESH_PROV_OOB_URI = BIT(1)
BT_MESH_PROV_OOB_2D_CODE = BIT(2)
BT_MESH_PROV_OOB_BAR_CODE = BIT(3)
BT_MESH_PROV_OOB_NFC = BIT(4)
BT_MESH_PROV_OOB_NUMBER = BIT(5)
BT_MESH_PROV_OOB_STRING = BIT(6)
BT_MESH_PROV_OOB_ON_BOX = BIT(11)
BT_MESH_PROV_OOB_IN_BOX = BIT(12)
BT_MESH_PROV_OOB_ON_PAPER = BIT(13)
BT_MESH_PROV_OOB_IN_MANUAL = BIT(14)
BT_MESH_PROV_OOB_ON_DEV = BIT(15)

Functions

int bt_mesh_input_string(const char *str)

Provide provisioning input OOB string.

This is intended to be called after the bt_mesh_prov input callback has been called with BT_MESH_ENTER_STRING as the action.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • str: String.

int bt_mesh_input_number(u32_t num)

Provide provisioning input OOB number.

This is intended to be called after the bt_mesh_prov input callback has been called with BT_MESH_ENTER_NUMBER as the action.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • num: Number.

int bt_mesh_prov_enable(bt_mesh_prov_bearer_t bearers)

Enable specific provisioning bearers.

Enable one or more provisioning bearers.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • bearers: Bit-wise or of provisioning bearers.

int bt_mesh_prov_disable(bt_mesh_prov_bearer_t bearers)

Disable specific provisioning bearers.

Disable one or more provisioning bearers.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • bearers: Bit-wise or of provisioning bearers.

struct bt_mesh_prov
#include <main.h>

Provisioning properties & capabilities.

Bluetooth Mesh Proxy

group bt_mesh_proxy

Bluetooth Mesh Proxy.

Functions

int bt_mesh_proxy_identity_enable(void)

Enable advertising with Node Identity.

This API requires that GATT Proxy support has been enabled. Once called each subnet will start advertising using Node Identity for the next 60 seconds.

Return
0 on success, or (negative) error code on failure.

Connection Management

group bt_conn

Connection management.

Defines

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_PASSKEY_INVALID

Special passkey value that can be used to disable a previously set fixed passkey.

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

Enums

enum [anonymous]

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]

Connection role (master or slave)

Values:

BT_CONN_ROLE_MASTER
BT_CONN_ROLE_SLAVE
enum 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

Functions

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(u8_t id, 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
  • id: Local identity (in most cases BT_ID_DEFAULT).
  • 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.

void bt_set_bondable(bool enable)

Enable/disable bonding.

Set/clear the Bonding flag in the Authentication Requirements of SMP Pairing Request/Response data. The initial value of this flag depends on BT_BONDABLE Kconfig setting. For the vast majority of applications calling this function shouldn’t be needed.

Parameters
  • enable: Value allowing/disallowing to be bondable.

int bt_passkey_set(unsigned int passkey)

Set a fixed passkey to be used for pairing.

This API is only available when the CONFIG_BT_FIXED_PASSKEY configuration option has been enabled.

Sets a fixed passkey to be used for pairing. If set, the pairing_confim() callback will be called for all incoming pairings.

Return
0 on success or a negative error code on failure.
Parameters
  • passkey: A valid passkey (0 - 999999) or BT_PASSKEY_INVALID to disable a previously set fixed passkey.

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

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
  • id: Which local identity the connection was created with
  • 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

Cryptography

group bt_crypto

Cryptography.

Functions

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

int bt_encrypt_le(const u8_t key[16], const u8_t plaintext[16], u8_t enc_data[16])

AES encrypt little-endian data.

An AES encrypt helper is used to request the Bluetooth controller’s own hardware to encrypt the plaintext using the key and returns the encrypted data.

Return
Zero on success or error code otherwise.
Parameters
  • key: 128 bit LS byte first key for the encryption of the plaintext
  • plaintext: 128 bit LS byte first plaintext data block to be encrypted
  • enc_data: 128 bit LS byte first encrypted data block

int bt_encrypt_be(const u8_t key[16], const u8_t plaintext[16], u8_t enc_data[16])

AES encrypt big-endian data.

An AES encrypt helper is used to request the Bluetooth controller’s own hardware to encrypt the plaintext using the key and returns the encrypted data.

Return
Zero on success or error code otherwise.
Parameters
  • key: 128 bit MS byte first key for the encryption of the plaintext
  • plaintext: 128 bit MS byte first plaintext data block to be encrypted
  • enc_data: 128 bit MS byte first encrypted data block

Data Buffers

group bt_buf

Data buffers.

Defines

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

Enums

enum 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

Functions

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

Generic Access Profile (GAP)

group bt_gap

Generic Access Profile.

Defines

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_CONN_NAME
BT_LE_ADV_CONN_DIR_LOW_DUTY
BT_LE_ADV_CONN_DIR
BT_LE_ADV_NCONN
BT_LE_ADV_NCONN_NAME
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.

Typedefs

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.

Enums

enum [anonymous]

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.

BT_LE_ADV_OPT_USE_IDENTITY = BIT(2)

Advertise using the identity address as the own address.

Warning
This will compromise the privacy of the device, so care must be taken when using this option.

BT_LE_ADV_OPT_USE_NAME = BIT(3)
BT_LE_ADV_OPT_DIR_MODE_LOW_DUTY = BIT(4)

Use low duty directed advertising mode, otherwise high duty mode will be used. This option is only effective when used with bt_conn_create_slave_le().

Functions

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_set_name(const char *name)

Set Bluetooth Device Name.

Set Bluetooth GAP Device Name.

Return
Zero on success or (negative) error code otherwise.
Parameters
  • name: New name

const char *bt_get_name(void)

Get Bluetooth Device Name.

Get Bluetooth GAP Device Name.

Return
Bluetooth Device Name

int bt_set_id_addr(const bt_addr_le_t *addr)

Set the local Identity Address.

Allows setting the local Identity Address from the application. This API must be called before calling bt_enable(). Calling it at any other time will cause it to fail. In most cases the application doesn’t need to use this API, however there are a few valid cases where it can be useful (such as for testing).

At the moment, the given address must be a static random address. In the future support for public addresses may be added.

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

void bt_id_get(bt_addr_le_t *addrs, size_t *count)

Get the currently configured identities.

Returns an array of the currently configured identity addresses. To make sure all available identities can be retrieved, the number of elements in the addrs array should be CONFIG_BT_ID_MAX. The identity identifier that some APIs expect (such as advertising parameters) is simply the index of the identity in the addrs array.

Note: Deleted identities may show up as BT_LE_ADDR_ANY in the returned array.

Parameters
  • addrs: Array where to store the configured identities.
  • count: Should be initialized to the array size. Once the function returns it will contain the number of returned identities.

int bt_id_create(bt_addr_le_t *addr, u8_t *irk)

Create a new identity.

Create a new identity using the given address and IRK. This function can be called before calling bt_enable(), in which case it can be used to override the controller’s public address (in case it has one). However, the new identity will only be stored persistently in flash when this API is used after bt_enable(). The reason is that the persistent settings are loaded after bt_enable() and would therefore cause potential conflicts with the stack blindly overwriting what’s stored in flash. The identity will also not be written to flash in case a pre-defined address is provided, since in such a situation the app clearly has some place it got the address from and will be able to repeat the procedure on every power cycle, i.e. it would be redundant to also store the information in flash.

If the application wants to have the stack randomly generate identities and store them in flash for later recovery, the way to do it would be to first initialize the stack (using bt_enable), then call settings_load(), and after that check with bt_id_get() how many identities were recovered. If an insufficient amount of identities were recovered the app may then call bt_id_create() to create new ones.

Return
Identity identifier (>= 0) in case of success, or a negative error code on failure.
Parameters
  • addr: Address to use for the new identity. If NULL or initialized to BT_ADDR_LE_ANY the stack will generate a new static random address for the identity and copy it to the given parameter upon return from this function (in case the parameter was non-NULL).
  • irk: Identity Resolving Key (16 bytes) to be used with this identity. If set to all zeroes or NULL, the stack will generate a random IRK for the identity and copy it back to the parameter upon return from this function (in case the parameter was non-NULL). If privacy support (CONFIG_BT_PRIVACY) is not enabled this parameter must be NULL.

int bt_id_reset(u8_t id, bt_addr_le_t *addr, u8_t *irk)

Reset/reclaim an identity for reuse.

The semantics of the addr and irk parameters of this function are the same as with bt_id_create(). The difference is the first id parameter that needs to be an existing identity (if it doesn’t exist this function will return an error). When given an existing identity this function will disconnect any connections created using it, remove any pairing keys or other data associated with it, and then create a new identity in the same slot, based on the addr and irk parameters.

Note: the default identity (BT_ID_DEFAULT) cannot be reset, i.e. this API will return an error if asked to do that.

Return
Identity identifier (>= 0) in case of success, or a negative error code on failure.
Parameters
  • id: Existing identity identifier.
  • addr: Address to use for the new identity. If NULL or initialized to BT_ADDR_LE_ANY the stack will generate a new static random address for the identity and copy it to the given parameter upon return from this function (in case the parameter was non-NULL).
  • irk: Identity Resolving Key (16 bytes) to be used with this identity. If set to all zeroes or NULL, the stack will generate a random IRK for the identity and copy it back to the parameter upon return from this function (in case the parameter was non-NULL). If privacy support (CONFIG_BT_PRIVACY) is not enabled this parameter must be NULL.

int bt_id_delete(u8_t id)

Delete an identity.

When given a valid identity this function will disconnect any connections created using it, remove any pairing keys or other data associated with it, and then flag is as deleted, so that it can not be used for any operations. To take back into use the slot the identity was occupying the bt_id_reset() API needs to be used.

Note: the default identity (BT_ID_DEFAULT) cannot be deleted, i.e. this API will return an error if asked to do that.

Return
0 in case of success, or a negative error code on failure.
Parameters
  • id: Existing identity identifier.

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_set_chan_map(u8_t chan_map[5])

Set (LE) channel map.

Return
Zero on success or error code otherwise, positive in case of protocol error or negative (POSIX) in case of stack internal error
Parameters
  • chan_map: Channel map.

void bt_data_parse(struct net_buf_simple *ad, bool (*func)(struct bt_data *data, void *user_data), void *user_data, )

Helper for parsing advertising (or EIR or OOB) data.

A helper for parsing the basic data types used for Extended Inquiry Response (EIR), Advertising Data (AD), and OOB data blocks. The most common scenario is to call this helper on the advertising data received in the callback that was given to bt_le_scan_start().

Parameters
  • ad: Advertising data as given to the bt_le_scan_cb_t callback.
  • func: Callback function which will be called for each element that’s found in the data. The callback should return true to continue parsing, or false to stop parsing.
  • user_data: User data to be passed to the callback.

int bt_le_oob_get_local(u8_t id, 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
  • id: Local identity, in most cases BT_ID_DEFAULT.
  • 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_unpair(u8_t id, const bt_addr_le_t *addr)

Clear pairing information.

Return
0 on success or negative error value on failure.
Parameters
  • id: Local identity (mostly just BT_ID_DEFAULT).
  • addr: Remote address, NULL or BT_ADDR_LE_ANY to clear all remote devices.

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

Generic Attribute Profile (GATT)

group bt_gatt

Generic Attribute Profile (GATT)

Defines

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, _perm, _read, _write, _value)

Characteristic and Value Declaration Macro.

Helper macro to declare a characteristic attribute along with its attribute value.

Parameters
  • _uuid: Characteristic attribute uuid.
  • _props: Characteristic attribute properties.
  • _perm: Characteristic Attribute access permissions.
  • _read: Characteristic Attribute read callback.
  • _write: Characteristic Attribute write callback.
  • _value: Characteristic Attribute value.

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.

BT_GATT_ATTRIBUTE(_uuid, _perm, _read, _write, _value)

Attribute Declaration Macro.

Helper macro to declare an attribute.

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

Typedefs

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 void (*bt_gatt_notify_complete_func_t)(struct bt_conn *conn)

Notification complete result callback.

Parameters
  • conn: Connection object.

typedef bt_gatt_indicate_func_t

Indication complete result callback.

Return
0 in case of success or negative value in case of error.
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.

Enums

enum [anonymous]

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]

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]

Values:

BT_GATT_ITER_STOP = 0
BT_GATT_ITER_CONTINUE
enum [anonymous]

Values:

BT_GATT_DISCOVER_PRIMARY
BT_GATT_DISCOVER_SECONDARY
BT_GATT_DISCOVER_INCLUDE
BT_GATT_DISCOVER_CHARACTERISTIC
BT_GATT_DISCOVER_DESCRIPTOR
enum [anonymous]

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.

Functions

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_cb(struct bt_conn *conn, const struct bt_gatt_attr *attr, const void *data, u16_t len, bt_gatt_notify_complete_func_t func)

Notify attribute value change with callback.

This function works in the same way as bt_gatt_notify. With the addition that after sending the notification the callback function will be called.

Parameters
  • conn: Connection object.
  • attr: Characteristic or Characteristic Value attribute.
  • data: Pointer to Attribute data.
  • len: Attribute value length.
  • func: Notification value callback.

static 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 can be the so called Characteristic Declaration, which is usually declared with BT_GATT_CHARACTERISTIC followed by BT_GATT_CCC, or the Characteristic Value Declaration which is automatically created after the Characteristic Declaration when using BT_GATT_CHARACTERISTIC.

Parameters
  • conn: Connection object.
  • attr: Characteristic or Characteristic Value 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.

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
  • id: Local identity, BT_ID_DEFAULT in most cases.
  • 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.

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.

group hci_raw

HCI RAW channel.

Functions

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.

HCI Drivers

group bt_hci_driver

HCI drivers.

Enums

enum [anonymous]

Values:

BT_QUIRK_NO_RESET = BIT(0)
enum 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

Functions

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

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.

Hands Free Profile (HFP)

group bt_hfp

Hands Free Profile (HFP)

Defines

HFP_HF_CMD_OK
HFP_HF_CMD_ERROR
HFP_HF_CMD_CME_ERROR
HFP_HF_CMD_UNKNOWN_ERROR

Enums

enum bt_hfp_hf_at_cmd

Values:

BT_HFP_HF_ATA
BT_HFP_HF_AT_CHUP

Functions

int bt_hfp_hf_register(struct bt_hfp_hf_cb *cb)

Register HFP HF profile.

Register Handsfree profile callbacks to monitor the state and get the required HFP details to display.

Return
0 in case of success or negative value in case of error.
Parameters
  • cb: callback structure.

int bt_hfp_hf_send_cmd(struct bt_conn *conn, enum bt_hfp_hf_at_cmd cmd)

Handsfree client Send AT.

Send specific AT commands to handsfree client profile.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Connection object.
  • cmd: AT command to be sent.

struct bt_hfp_hf_cmd_complete
#include <hfp_hf.h>

HFP HF Command completion field.

struct bt_hfp_hf_cb
#include <hfp_hf.h>

HFP profile application callback.

Serial Port Emulation (RFCOMM)

group bt_rfcomm

RFCOMM.

Typedefs

typedef enum bt_rfcomm_role bt_rfcomm_role_t

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

Enums

enum [anonymous]

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_role

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

Values:

BT_RFCOMM_ROLE_ACCEPTOR
BT_RFCOMM_ROLE_INITIATOR

Functions

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.

Service Discovery Protocol (SDP)

group bt_sdp

Service Discovery Protocol (SDP)

Defines

BT_SDP_SDP_SERVER_SVCLASS
BT_SDP_BROWSE_GRP_DESC_SVCLASS
BT_SDP_PUBLIC_BROWSE_GROUP
BT_SDP_SERIAL_PORT_SVCLASS
BT_SDP_LAN_ACCESS_SVCLASS
BT_SDP_DIALUP_NET_SVCLASS
BT_SDP_IRMC_SYNC_SVCLASS
BT_SDP_OBEX_OBJPUSH_SVCLASS
BT_SDP_OBEX_FILETRANS_SVCLASS
BT_SDP_IRMC_SYNC_CMD_SVCLASS
BT_SDP_HEADSET_SVCLASS
BT_SDP_CORDLESS_TELEPHONY_SVCLASS
BT_SDP_AUDIO_SOURCE_SVCLASS
BT_SDP_AUDIO_SINK_SVCLASS
BT_SDP_AV_REMOTE_TARGET_SVCLASS
BT_SDP_ADVANCED_AUDIO_SVCLASS
BT_SDP_AV_REMOTE_SVCLASS
BT_SDP_AV_REMOTE_CONTROLLER_SVCLASS
BT_SDP_INTERCOM_SVCLASS
BT_SDP_FAX_SVCLASS
BT_SDP_HEADSET_AGW_SVCLASS
BT_SDP_WAP_SVCLASS
BT_SDP_WAP_CLIENT_SVCLASS
BT_SDP_PANU_SVCLASS
BT_SDP_NAP_SVCLASS
BT_SDP_GN_SVCLASS
BT_SDP_DIRECT_PRINTING_SVCLASS
BT_SDP_REFERENCE_PRINTING_SVCLASS
BT_SDP_IMAGING_SVCLASS
BT_SDP_IMAGING_RESPONDER_SVCLASS
BT_SDP_IMAGING_ARCHIVE_SVCLASS
BT_SDP_IMAGING_REFOBJS_SVCLASS
BT_SDP_HANDSFREE_SVCLASS
BT_SDP_HANDSFREE_AGW_SVCLASS
BT_SDP_DIRECT_PRT_REFOBJS_SVCLASS
BT_SDP_REFLECTED_UI_SVCLASS
BT_SDP_BASIC_PRINTING_SVCLASS
BT_SDP_PRINTING_STATUS_SVCLASS
BT_SDP_HID_SVCLASS
BT_SDP_HCR_SVCLASS
BT_SDP_HCR_PRINT_SVCLASS
BT_SDP_HCR_SCAN_SVCLASS
BT_SDP_CIP_SVCLASS
BT_SDP_VIDEO_CONF_GW_SVCLASS
BT_SDP_UDI_MT_SVCLASS
BT_SDP_UDI_TA_SVCLASS
BT_SDP_AV_SVCLASS
BT_SDP_SAP_SVCLASS
BT_SDP_PBAP_PCE_SVCLASS
BT_SDP_PBAP_PSE_SVCLASS
BT_SDP_PBAP_SVCLASS
BT_SDP_MAP_MSE_SVCLASS
BT_SDP_MAP_MCE_SVCLASS
BT_SDP_MAP_SVCLASS
BT_SDP_GNSS_SVCLASS
BT_SDP_GNSS_SERVER_SVCLASS
BT_SDP_MPS_SC_SVCLASS
BT_SDP_MPS_SVCLASS
BT_SDP_PNP_INFO_SVCLASS
BT_SDP_GENERIC_NETWORKING_SVCLASS
BT_SDP_GENERIC_FILETRANS_SVCLASS
BT_SDP_GENERIC_AUDIO_SVCLASS
BT_SDP_GENERIC_TELEPHONY_SVCLASS
BT_SDP_UPNP_SVCLASS
BT_SDP_UPNP_IP_SVCLASS
BT_SDP_UPNP_PAN_SVCLASS
BT_SDP_UPNP_LAP_SVCLASS
BT_SDP_UPNP_L2CAP_SVCLASS
BT_SDP_VIDEO_SOURCE_SVCLASS
BT_SDP_VIDEO_SINK_SVCLASS
BT_SDP_VIDEO_DISTRIBUTION_SVCLASS
BT_SDP_HDP_SVCLASS
BT_SDP_HDP_SOURCE_SVCLASS
BT_SDP_HDP_SINK_SVCLASS
BT_SDP_GENERIC_ACCESS_SVCLASS
BT_SDP_GENERIC_ATTRIB_SVCLASS
BT_SDP_APPLE_AGENT_SVCLASS
BT_SDP_SERVER_RECORD_HANDLE
BT_SDP_ATTR_RECORD_HANDLE
BT_SDP_ATTR_SVCLASS_ID_LIST
BT_SDP_ATTR_RECORD_STATE
BT_SDP_ATTR_SERVICE_ID
BT_SDP_ATTR_PROTO_DESC_LIST
BT_SDP_ATTR_BROWSE_GRP_LIST
BT_SDP_ATTR_LANG_BASE_ATTR_ID_LIST
BT_SDP_ATTR_SVCINFO_TTL
BT_SDP_ATTR_SERVICE_AVAILABILITY
BT_SDP_ATTR_PROFILE_DESC_LIST
BT_SDP_ATTR_DOC_URL
BT_SDP_ATTR_CLNT_EXEC_URL
BT_SDP_ATTR_ICON_URL
BT_SDP_ATTR_ADD_PROTO_DESC_LIST
BT_SDP_ATTR_GROUP_ID
BT_SDP_ATTR_IP_SUBNET
BT_SDP_ATTR_VERSION_NUM_LIST
BT_SDP_ATTR_SUPPORTED_FEATURES_LIST
BT_SDP_ATTR_GOEP_L2CAP_PSM
BT_SDP_ATTR_SVCDB_STATE
BT_SDP_ATTR_MPSD_SCENARIOS
BT_SDP_ATTR_MPMD_SCENARIOS
BT_SDP_ATTR_MPS_DEPENDENCIES
BT_SDP_ATTR_SERVICE_VERSION
BT_SDP_ATTR_EXTERNAL_NETWORK
BT_SDP_ATTR_SUPPORTED_DATA_STORES_LIST
BT_SDP_ATTR_DATA_EXCHANGE_SPEC
BT_SDP_ATTR_NETWORK
BT_SDP_ATTR_FAX_CLASS1_SUPPORT
BT_SDP_ATTR_REMOTE_AUDIO_VOLUME_CONTROL
BT_SDP_ATTR_MCAP_SUPPORTED_PROCEDURES
BT_SDP_ATTR_FAX_CLASS20_SUPPORT
BT_SDP_ATTR_SUPPORTED_FORMATS_LIST
BT_SDP_ATTR_FAX_CLASS2_SUPPORT
BT_SDP_ATTR_AUDIO_FEEDBACK_SUPPORT
BT_SDP_ATTR_NETWORK_ADDRESS
BT_SDP_ATTR_WAP_GATEWAY
BT_SDP_ATTR_HOMEPAGE_URL
BT_SDP_ATTR_WAP_STACK_TYPE
BT_SDP_ATTR_SECURITY_DESC
BT_SDP_ATTR_NET_ACCESS_TYPE
BT_SDP_ATTR_MAX_NET_ACCESSRATE
BT_SDP_ATTR_IP4_SUBNET
BT_SDP_ATTR_IP6_SUBNET
BT_SDP_ATTR_SUPPORTED_CAPABILITIES
BT_SDP_ATTR_SUPPORTED_FEATURES
BT_SDP_ATTR_SUPPORTED_FUNCTIONS
BT_SDP_ATTR_TOTAL_IMAGING_DATA_CAPACITY
BT_SDP_ATTR_SUPPORTED_REPOSITORIES
BT_SDP_ATTR_MAS_INSTANCE_ID
BT_SDP_ATTR_SUPPORTED_MESSAGE_TYPES
BT_SDP_ATTR_PBAP_SUPPORTED_FEATURES
BT_SDP_ATTR_MAP_SUPPORTED_FEATURES
BT_SDP_ATTR_SPECIFICATION_ID
BT_SDP_ATTR_VENDOR_ID
BT_SDP_ATTR_PRODUCT_ID
BT_SDP_ATTR_VERSION
BT_SDP_ATTR_PRIMARY_RECORD
BT_SDP_ATTR_VENDOR_ID_SOURCE
BT_SDP_ATTR_HID_DEVICE_RELEASE_NUMBER
BT_SDP_ATTR_HID_PARSER_VERSION
BT_SDP_ATTR_HID_DEVICE_SUBCLASS
BT_SDP_ATTR_HID_COUNTRY_CODE
BT_SDP_ATTR_HID_VIRTUAL_CABLE
BT_SDP_ATTR_HID_RECONNECT_INITIATE
BT_SDP_ATTR_HID_DESCRIPTOR_LIST
BT_SDP_ATTR_HID_LANG_ID_BASE_LIST
BT_SDP_ATTR_HID_SDP_DISABLE
BT_SDP_ATTR_HID_BATTERY_POWER
BT_SDP_ATTR_HID_REMOTE_WAKEUP
BT_SDP_ATTR_HID_PROFILE_VERSION
BT_SDP_ATTR_HID_SUPERVISION_TIMEOUT
BT_SDP_ATTR_HID_NORMALLY_CONNECTABLE
BT_SDP_ATTR_HID_BOOT_DEVICE
BT_SDP_PRIMARY_LANG_BASE
BT_SDP_ATTR_SVCNAME_PRIMARY
BT_SDP_ATTR_SVCDESC_PRIMARY
BT_SDP_ATTR_PROVNAME_PRIMARY
BT_SDP_DATA_NIL
BT_SDP_UINT8
BT_SDP_UINT16
BT_SDP_UINT32
BT_SDP_UINT64
BT_SDP_UINT128
BT_SDP_INT8
BT_SDP_INT16
BT_SDP_INT32
BT_SDP_INT64
BT_SDP_INT128
BT_SDP_UUID_UNSPEC
BT_SDP_UUID16
BT_SDP_UUID32
BT_SDP_UUID128
BT_SDP_TEXT_STR_UNSPEC
BT_SDP_TEXT_STR8
BT_SDP_TEXT_STR16
BT_SDP_TEXT_STR32
BT_SDP_BOOL
BT_SDP_SEQ_UNSPEC
BT_SDP_SEQ8
BT_SDP_SEQ16
BT_SDP_SEQ32
BT_SDP_ALT_UNSPEC
BT_SDP_ALT8
BT_SDP_ALT16
BT_SDP_ALT32
BT_SDP_URL_STR_UNSPEC
BT_SDP_URL_STR8
BT_SDP_URL_STR16
BT_SDP_URL_STR32
BT_SDP_TYPE_DESC_MASK
BT_SDP_SIZE_DESC_MASK
BT_SDP_SIZE_INDEX_OFFSET
BT_SDP_ARRAY_8(...)

Declare an array of 8-bit elements in an attribute.

BT_SDP_ARRAY_16(...)

Declare an array of 16-bit elements in an attribute.

BT_SDP_ARRAY_32(...)

Declare an array of 32-bit elements in an attribute.

BT_SDP_TYPE_SIZE(_type)

Declare a fixed-size data element header.

Parameters
  • _type: Data element header containing type and size descriptors.

BT_SDP_TYPE_SIZE_VAR(_type, _size)

Declare a variable-size data element header.

Parameters
  • _type: Data element header containing type and size descriptors.
  • _size: The actual size of the data.

BT_SDP_DATA_ELEM_LIST(...)

Declare a list of data elements.

BT_SDP_NEW_SERVICE

SDP New Service Record Declaration Macro.

Helper macro to declare a new service record. Default attributes: Record Handle, Record State, Language Base, Root Browse Group

BT_SDP_LIST(_att_id, _type_size, _data_elem_seq)

Generic SDP List Attribute Declaration Macro.

Helper macro to declare a list attribute.

Parameters
  • _att_id: List Attribute ID.
  • _data_elem_seq: Data element sequence for the list.
  • _type_size: SDP type and size descriptor.

BT_SDP_SERVICE_ID(_uuid)

SDP Service ID Attribute Declaration Macro.

Helper macro to declare a service ID attribute.

Parameters
  • _uuid: Service ID 16bit UUID.

BT_SDP_SERVICE_NAME(_name)

SDP Name Attribute Declaration Macro.

Helper macro to declare a service name attribute.

Parameters
  • _name: Service name as a string (up to 256 chars).

BT_SDP_SUPPORTED_FEATURES(_features)

SDP Supported Features Attribute Declaration Macro.

Helper macro to declare supported features of a profile/protocol.

Parameters
  • _features: Feature mask as 16bit unsigned integer.

BT_SDP_RECORD(_attrs)

SDP Service Declaration Macro.

Helper macro to declare a service.

Parameters
  • _attrs: List of attributes for the service record.

Typedefs

typedef bt_sdp_discover_func_t

Callback type reporting to user that there is a resolved result on remote for given UUID and the result record buffer can be used by user for further inspection.

A function of this type is given by the user to the bt_sdp_discover_params object. It’ll be called on each valid record discovery completion for given UUID. When UUID resolution gives back no records then NULL is passed to the user. Otherwise user can get valid record(s) and then the internal hint ‘next record’ is set to false saying the UUID resolution is complete or the hint can be set by caller to true meaning that next record is available for given UUID. The returned function value allows the user to control retrieving follow-up resolved records if any. If the user doesn’t want to read more resolved records for given UUID since current record data fulfills its requirements then should return BT_SDP_DISCOVER_UUID_STOP. Otherwise returned value means more subcall iterations are allowable.

Return
BT_SDP_DISCOVER_UUID_STOP in case of no more need to read next record data and continue discovery for given UUID. By returning BT_SDP_DISCOVER_UUID_CONTINUE user allows this discovery continuation.
Parameters
  • conn: Connection object identifying connection to queried remote.
  • result: Object pointing to logical unparsed SDP record collected on base of response driven by given UUID.

Enums

enum [anonymous]

Helper enum to be used as return value of bt_sdp_discover_func_t. The value informs the caller to perform further pending actions or stop them.

Values:

BT_SDP_DISCOVER_UUID_STOP = 0
BT_SDP_DISCOVER_UUID_CONTINUE
enum bt_sdp_proto

Protocols to be asked about specific parameters.

Values:

BT_SDP_PROTO_RFCOMM = 0x0003
BT_SDP_PROTO_L2CAP = 0x0100

Functions

int bt_sdp_register_service(struct bt_sdp_record *service)

Register a Service Record.

Register a Service Record. Applications can make use of macros such as BT_SDP_DECLARE_SERVICE, BT_SDP_LIST, BT_SDP_SERVICE_ID, BT_SDP_SERVICE_NAME, etc. A service declaration must start with BT_SDP_NEW_SERVICE.

Return
0 in case of success or negative value in case of error.
Parameters
  • service: Service record declared using BT_SDP_DECLARE_SERVICE.

int bt_sdp_discover(struct bt_conn *conn, const struct bt_sdp_discover_params *params)

Allows user to start SDP discovery session.

The function performs SDP service discovery on remote server driven by user delivered discovery parameters. Discovery session is made as soon as no SDP transaction is ongoing between peers and if any then this one is queued to be processed at discovery completion of previous one. On the service discovery completion the callback function will be called to get feedback to user about findings.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Object identifying connection to remote.
  • params: SDP discovery parameters.

int bt_sdp_discover_cancel(struct bt_conn *conn, const struct bt_sdp_discover_params *params)

Release waiting SDP discovery request.

It can cancel valid waiting SDP client request identified by SDP discovery parameters object.

Return
0 in case of success or negative value in case of error.
Parameters
  • conn: Object identifying connection to remote.
  • params: SDP discovery parameters.

int bt_sdp_get_proto_param(const struct net_buf *buf, enum bt_sdp_proto proto, u16_t *param)

Give to user parameter value related to given stacked protocol UUID.

API extracts specific parameter associated with given protocol UUID available in Protocol Descriptor List attribute.

Return
0 on success when specific parameter associated with given protocol value is found, or negative if error occurred during processing.
Parameters
  • buf: Original buffered raw record data.
  • proto: Known protocol to be checked like RFCOMM or L2CAP.
  • param: On success populated by found parameter value.

int bt_sdp_get_profile_version(const struct net_buf *buf, u16_t profile, u16_t *version)

Get profile version.

Helper API extracting remote profile version number. To get it proper generic profile parameter needs to be selected usually listed in SDP Interoperability Requirements section for given profile specification.

Return
0 on success, negative value if error occurred during processing.
Parameters
  • buf: Original buffered raw record data.
  • profile: Profile family identifier the profile belongs.
  • version: On success populated by found version number.

int bt_sdp_get_features(const struct net_buf *buf, u16_t *features)

Get SupportedFeatures attribute value.

Allows if exposed by remote retrieve SupportedFeature attribute.

Return
0 on success if feature found and valid, negative in case any error
Parameters
  • buf: Buffer holding original raw record data from remote.
  • features: On success object to be populated with SupportedFeature mask.

struct bt_sdp_data_elem
#include <sdp.h>

SDP Generic Data Element Value.

struct bt_sdp_attribute
#include <sdp.h>

SDP Attribute Value.

struct bt_sdp_record
#include <sdp.h>

SDP Service Record Value.

struct bt_sdp_client_result
#include <sdp.h>

Generic SDP Client Query Result data holder.

struct bt_sdp_discover_params
#include <sdp.h>

Main user structure used in SDP discovery of remote.

Universal Unique Identifiers (UUIDs)

group bt_uuid

UUIDs.

Defines

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_GATT

Generic Attribute.

BT_UUID_CTS

Current Time Service.

BT_UUID_DIS

Device Information Service.

BT_UUID_HRS

Heart Rate Service.

BT_UUID_BAS

Battery Service.

BT_UUID_HIDS

HID Service.

BT_UUID_CSC

Cycling Speed and Cadence Service.

BT_UUID_ESS

Environmental Sensing Service.

BT_UUID_IPSS

IP Support Service.

BT_UUID_MESH_PROV

Mesh Provisioning Service.

BT_UUID_MESH_PROXY

Mesh Proxy Service.

BT_UUID_GATT_PRIMARY

GATT Primary Service.

BT_UUID_GATT_SECONDARY

GATT Secondary Service.

BT_UUID_GATT_INCLUDE

GATT Include Service.

BT_UUID_GATT_CHRC

GATT Characteristic.

BT_UUID_GATT_CEP

GATT Characteristic Extended Properties.

BT_UUID_GATT_CUD

GATT Characteristic User Description.

BT_UUID_GATT_CCC

GATT Client Characteristic Configuration.

BT_UUID_GATT_SCC

GATT Server Characteristic Configuration.

BT_UUID_GATT_CPF

GATT Characteristic Presentation Format.

BT_UUID_VALID_RANGE

Valid Range Descriptor.

BT_UUID_HIDS_EXT_REPORT

HID External Report Descriptor.

BT_UUID_HIDS_REPORT_REF

HID Report Reference Descriptor.

BT_UUID_ES_CONFIGURATION

Environmental Sensing Configuration Descriptor.

BT_UUID_ES_MEASUREMENT

Environmental Sensing Measurement Descriptor.

BT_UUID_ES_TRIGGER_SETTING

Environmental Sensing Trigger Setting Descriptor.

BT_UUID_GAP_DEVICE_NAME

GAP Characteristic Device Name.

BT_UUID_GAP_APPEARANCE

GAP Characteristic Appearance.

BT_UUID_GAP_PPCP

GAP Characteristic Peripheral Preferred Connection Parameters.

BT_UUID_GATT_SC

GATT Characteristic Service Changed.

BT_UUID_BAS_BATTERY_LEVEL

BAS Characteristic Battery Level.

BT_UUID_HIDS_BOOT_KB_IN_REPORT

HID Characteristic Boot Keyboard Input Report.

BT_UUID_DIS_SYSTEM_ID

DIS Characteristic System ID.

BT_UUID_DIS_MODEL_NUMBER

DIS Characteristic Model Number String.

BT_UUID_DIS_SERIAL_NUMBER

DIS Characteristic Serial Number String.

BT_UUID_DIS_FIRMWARE_REVISION

DIS Characteristic Firmware Revision String.

BT_UUID_DIS_HARDWARE_REVISION

DIS Characteristic Hardware Revision String.

BT_UUID_DIS_SOFTWARE_REVISION

DIS Characteristic Software Revision String.

BT_UUID_DIS_MANUFACTURER_NAME

DIS Characteristic Manufacturer Name String.

BT_UUID_DIS_PNP_ID

DIS Characteristic PnP ID.

BT_UUID_CTS_CURRENT_TIME

CTS Characteristic Current Time.

BT_UUID_MAGN_DECLINATION

Magnetic Declination Characteristic.

BT_UUID_HIDS_BOOT_KB_OUT_REPORT

HID Boot Keyboard Output Report Characteristic.

BT_UUID_HIDS_BOOT_MOUSE_IN_REPORT

HID Boot Mouse Input Report Characteristic.

BT_UUID_HRS_MEASUREMENT

HRS Characteristic Measurement Interval.

BT_UUID_HRS_BODY_SENSOR

HRS Characteristic Body Sensor Location.

BT_UUID_HRS_CONTROL_POINT

HRS Characteristic Control Point.

BT_UUID_HIDS_INFO

HID Information Characteristic.

BT_UUID_HIDS_REPORT_MAP

HID Report Map Characteristic.

BT_UUID_HIDS_CTRL_POINT

HID Control Point Characteristic.

BT_UUID_HIDS_REPORT

HID Report Characteristic.

BT_UUID_HIDS_PROTOCOL_MODE

HID Protocol Mode Characteristic.

BT_UUID_CSC_MEASUREMENT

CSC Measurement Characteristic.

BT_UUID_CSC_FEATURE

CSC Feature Characteristic.

BT_UUID_SENSOR_LOCATION

Sensor Location Characteristic.

BT_UUID_SC_CONTROL_POINT

SC Control Point Characteristic.

BT_UUID_ELEVATION

Elevation Characteristic.

BT_UUID_PRESSURE

Pressure Characteristic.

BT_UUID_TEMPERATURE

Temperature Characteristic.

BT_UUID_HUMIDITY

Humidity Characteristic.

BT_UUID_TRUE_WIND_SPEED

True Wind Speed Characteristic.

BT_UUID_TRUE_WIND_DIR

True Wind Direction Characteristic.

BT_UUID_APPARENT_WIND_SPEED

Apparent Wind Speed Characteristic.

BT_UUID_APPARENT_WIND_DIR

Apparent Wind Direction Characteristic.

BT_UUID_GUST_FACTOR

Gust Factor Characteristic.

BT_UUID_POLLEN_CONCENTRATION

Pollen Concentration Characteristic.

BT_UUID_UV_INDEX

UV Index Characteristic.

BT_UUID_IRRADIANCE

Irradiance Characteristic.

BT_UUID_RAINFALL

Rainfall Characteristic.

BT_UUID_WIND_CHILL

Wind Chill Characteristic.

BT_UUID_HEAT_INDEX

Heat Index Characteristic.

BT_UUID_DEW_POINT

Dew Point Characteristic.

BT_UUID_DESC_VALUE_CHANGED

Descriptor Value Changed Characteristic.

BT_UUID_MAGN_FLUX_DENSITY_2D

Magnetic Flux Density - 2D Characteristic.

BT_UUID_MAGN_FLUX_DENSITY_3D

Magnetic Flux Density - 3D Characteristic.

BT_UUID_BAR_PRESSURE_TREND

Barometric Pressure Trend Characteristic.

BT_UUID_CENTRAL_ADDR_RES

Central Address Resolution Characteristic.

BT_UUID_MESH_PROV_DATA_IN

Mesh Provisioning Data In.

BT_UUID_MESH_PROV_DATA_OUT

Mesh Provisioning Data Out.

BT_UUID_MESH_PROXY_DATA_IN

Mesh Proxy Data In.

BT_UUID_MESH_PROXY_DATA_OUT

Mesh Proxy Data Out.

BT_UUID_SDP
BT_UUID_UDP
BT_UUID_RFCOMM
BT_UUID_TCP
BT_UUID_TCS_BIN
BT_UUID_TCS_AT
BT_UUID_ATT
BT_UUID_OBEX
BT_UUID_IP
BT_UUID_FTP
BT_UUID_HTTP
BT_UUID_BNEP
BT_UUID_UPNP
BT_UUID_HIDP
BT_UUID_HCRP_CTRL
BT_UUID_HCRP_DATA
BT_UUID_HCRP_NOTE
BT_UUID_AVCTP
BT_UUID_AVDTP
BT_UUID_CMTP
BT_UUID_UDI
BT_UUID_MCAP_CTRL
BT_UUID_MCAP_DATA
BT_UUID_L2CAP

Enums

enum [anonymous]

Bluetooth UUID types.

Values:

BT_UUID_TYPE_16
BT_UUID_TYPE_32
BT_UUID_TYPE_128

Functions

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)
struct bt_uuid
#include <uuid.h>

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