这个页面的最新开发版本可能比这个发布的 2.3-beta.1 版本新。

蓝牙标准服务

电池服务

group bt_bas

Battery Service (BAS)

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Functions

uint8_t bt_bas_get_battery_level(void)

Read battery level value.

Read the characteristic value of the battery level

返回:: The battery level in percent.

int bt_bas_set_battery_level(uint8_t level)

Update battery level value.

Update the characteristic value of the battery level This will send a GATT notification to all current subscribers.

参数:: level – The battery level in percent.
返回:: Zero in case of success and error code in case of error.

心率服务

group bt_hrs

Heart Rate Service (HRS)

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Functions

int bt_hrs_notify(uint16_t heartrate)

Notify heart rate measurement.

This will send a GATT notification to all current subscribers.

参数:: heartrate – The heartrate measurement in beats per minute.
返回:: Zero in case of success and error code in case of error.

即时警报服务

group bt_ias

Immediate Alert Service (IAS)

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Defines

BT_IAS_CB_DEFINE(_name)

Register a callback structure for immediate alert events.

参数:

_name – Name of callback structure.

Enums

enum bt_ias_alert_lvl

Values:

enumerator BT_IAS_ALERT_LVL_NO_ALERT: No alerting should be done on device

enumerator BT_IAS_ALERT_LVL_MILD_ALERT: Device shall alert

enumerator BT_IAS_ALERT_LVL_HIGH_ALERT: Device should alert in strongest possible way

Functions

int bt_ias_local_alert_stop(void)

Method for stopping alert locally.

返回:: Zero in case of success and error code in case of error.

int bt_ias_client_alert_write(struct bt_conn *conn, enum bt_ias_alert_lvl)

Set alert level.

参数:

conn – Bluetooth connection object
bt_ias_alert_lvl – Level of alert to write

返回:

Zero in case of success and error code in case of error.

int bt_ias_discover(struct bt_conn *conn)

Discover Immediate Alert Service.

参数:: conn – Bluetooth connection object
返回:: Zero in case of success and error code in case of error.

int bt_ias_client_cb_register(const struct bt_ias_client_cb *cb)

Register Immediate Alert Client callbacks.

参数:: cb – The callback structure
返回:: Zero in case of success and error code in case of error.

struct bt_ias_cb: Immediate Alert Service callback structure.

struct bt_ias_client_cb

对象传输服务

group bt_ots

Object Transfer Service (OTS)

[Experimental] Users should note that the APIs can change as a part of ongoing development.

Defines

BT_OTS_OBJ_ID_SIZE: Size of OTS object ID (in bytes).

BT_OTS_OBJ_ID_MIN: Minimum allowed value for object ID (except ID for directory listing)

BT_OTS_OBJ_ID_MAX: Maximum allowed value for object ID (except ID for directory listing)

OTS_OBJ_ID_DIR_LIST: ID of the Directory Listing Object.

BT_OTS_OBJ_ID_MASK: Mask for OTS object IDs, preserving the 48 bits.

BT_OTS_OBJ_ID_STR_LEN: Length of OTS object ID string (in bytes).

BT_OTS_OBJ_SET_PROP_DELETE(prop)

Set BT_OTS_OBJ_PROP_DELETE property.

参数:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_EXECUTE(prop)

Set BT_OTS_OBJ_PROP_EXECUTE property.

参数:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_READ(prop)

Set BT_OTS_OBJ_PROP_READ property.

参数:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_WRITE(prop)

Set BT_OTS_OBJ_PROP_WRITE property.

参数:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_APPEND(prop)

Set BT_OTS_OBJ_PROP_APPEND property.

参数:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_TRUNCATE(prop)

Set BT_OTS_OBJ_PROP_TRUNCATE property.

参数:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_PATCH(prop)

Set BT_OTS_OBJ_PROP_PATCH property.

参数:

prop – Object properties.

BT_OTS_OBJ_SET_PROP_MARKED(prop)

Set BT_OTS_OBJ_SET_PROP_MARKED property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_DELETE(prop)

Get BT_OTS_OBJ_PROP_DELETE property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_EXECUTE(prop)

Get BT_OTS_OBJ_PROP_EXECUTE property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_READ(prop)

Get BT_OTS_OBJ_PROP_READ property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_WRITE(prop)

Get BT_OTS_OBJ_PROP_WRITE property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_APPEND(prop)

Get BT_OTS_OBJ_PROP_APPEND property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_TRUNCATE(prop)

Get BT_OTS_OBJ_PROP_TRUNCATE property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_PATCH(prop)

Get BT_OTS_OBJ_PROP_PATCH property.

参数:

prop – Object properties.

BT_OTS_OBJ_GET_PROP_MARKED(prop)

Get BT_OTS_OBJ_PROP_MARKED property.

参数:

prop – Object properties.

BT_OTS_OACP_SET_FEAT_CREATE(feat)

Set BT_OTS_OACP_SET_FEAT_CREATE feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_DELETE(feat)

Set BT_OTS_OACP_FEAT_DELETE feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_CHECKSUM(feat)

Set BT_OTS_OACP_FEAT_CHECKSUM feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_EXECUTE(feat)

Set BT_OTS_OACP_FEAT_EXECUTE feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_READ(feat)

Set BT_OTS_OACP_FEAT_READ feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_WRITE(feat)

Set BT_OTS_OACP_FEAT_WRITE feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_APPEND(feat)

Set BT_OTS_OACP_FEAT_APPEND feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_TRUNCATE(feat)

Set BT_OTS_OACP_FEAT_TRUNCATE feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_PATCH(feat)

Set BT_OTS_OACP_FEAT_PATCH feature.

参数:

feat – OTS features.

BT_OTS_OACP_SET_FEAT_ABORT(feat)

Set BT_OTS_OACP_FEAT_ABORT feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_CREATE(feat)

Get BT_OTS_OACP_FEAT_CREATE feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_DELETE(feat)

Get BT_OTS_OACP_FEAT_DELETE feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_CHECKSUM(feat)

Get BT_OTS_OACP_FEAT_CHECKSUM feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_EXECUTE(feat)

Get BT_OTS_OACP_FEAT_EXECUTE feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_READ(feat)

Get BT_OTS_OACP_FEAT_READ feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_WRITE(feat)

Get BT_OTS_OACP_FEAT_WRITE feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_APPEND(feat)

Get BT_OTS_OACP_FEAT_APPEND feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_TRUNCATE(feat)

Get BT_OTS_OACP_FEAT_TRUNCATE feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_PATCH(feat)

Get BT_OTS_OACP_FEAT_PATCH feature.

参数:

feat – OTS features.

BT_OTS_OACP_GET_FEAT_ABORT(feat)

Get BT_OTS_OACP_FEAT_ABORT feature.

参数:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_GO_TO(feat)

Set BT_OTS_OLCP_FEAT_GO_TO feature.

参数:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_ORDER(feat)

Set BT_OTS_OLCP_FEAT_ORDER feature.

参数:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_NUM_REQ(feat)

Set BT_OTS_OLCP_FEAT_NUM_REQ feature.

参数:

feat – OTS features.

BT_OTS_OLCP_SET_FEAT_CLEAR(feat)

Set BT_OTS_OLCP_FEAT_CLEAR feature.

参数:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_GO_TO(feat)

Get BT_OTS_OLCP_GET_FEAT_GO_TO feature.

参数:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_ORDER(feat)

Get BT_OTS_OLCP_GET_FEAT_ORDER feature.

参数:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_NUM_REQ(feat)

Get BT_OTS_OLCP_GET_FEAT_NUM_REQ feature.

参数:

feat – OTS features.

BT_OTS_OLCP_GET_FEAT_CLEAR(feat)

Get BT_OTS_OLCP_GET_FEAT_CLEAR feature.

参数:

feat – OTS features.

BT_OTS_DATE_TIME_FIELD_SIZE

BT_OTS_STOP

BT_OTS_CONTINUE

Typedefs

typedef int (*bt_ots_client_dirlisting_cb)(struct bt_ots_obj_metadata *meta)

Directory listing object metadata callback.

If a directory listing is decoded using bt_ots_client_decode_dirlisting(), this callback will be called for each object in the directory listing.

Param meta:: The metadata of the decoded object
Return:: int BT_OTS_STOP or BT_OTS_CONTINUE. BT_OTS_STOP can be used to stop the decoding.

Enums

enum bt_ots_obj_propertie

Properties of an OTS object.

Values:

enumerator BT_OTS_OBJ_PROP_DELETE: Bit 0 Deletion of this object is permitted

enumerator BT_OTS_OBJ_PROP_EXECUTE: Bit 1 Execution of this object is permitted

enumerator BT_OTS_OBJ_PROP_READ: Bit 2 Reading this object is permitted

enumerator BT_OTS_OBJ_PROP_WRITE: Bit 3 Writing data to this object is permitted

enumerator BT_OTS_OBJ_PROP_APPEND

Bit 4 Appending data to this object is permitted.

Appending data increases its Allocated Size.

enumerator BT_OTS_OBJ_PROP_TRUNCATE: Bit 5 Truncation of this object is permitted

enumerator BT_OTS_OBJ_PROP_PATCH

Bit 6 Patching this object is permitted.

Patching this object overwrites some of the object’s existing contents.

enumerator BT_OTS_OBJ_PROP_MARKED: Bit 7 This object is a marked object

enum bt_ots_oacp_features_bit

Object Action Control Point Feature bits.

Values:

enumerator BT_OTS_OACP_FEAT_CREATE: Bit 0 OACP Create Op Code Supported

enumerator BT_OTS_OACP_FEAT_DELETE: Bit 1 OACP Delete Op Code Supported

enumerator BT_OTS_OACP_FEAT_CHECKSUM: Bit 2 OACP Calculate Checksum Op Code Supported

enumerator BT_OTS_OACP_FEAT_EXECUTE: Bit 3 OACP Execute Op Code Supported

enumerator BT_OTS_OACP_FEAT_READ: Bit 4 OACP Read Op Code Supported

enumerator BT_OTS_OACP_FEAT_WRITE: Bit 5 OACP Write Op Code Supported

enumerator BT_OTS_OACP_FEAT_APPEND: Bit 6 Appending Additional Data to Objects Supported

enumerator BT_OTS_OACP_FEAT_TRUNCATE: Bit 7 Truncation of Objects Supported

enumerator BT_OTS_OACP_FEAT_PATCH: Bit 8 Patching of Objects Supported

enumerator BT_OTS_OACP_FEAT_ABORT: Bit 9 OACP Abort Op Code Supported

enum bt_ots_oacp_write_op_mode

Values:

enumerator BT_OTS_OACP_WRITE_OP_MODE_NONE

enumerator BT_OTS_OACP_WRITE_OP_MODE_TRUNCATE

enum bt_ots_olcp_feature_bit

Object List Control Point Feature bits.

Values:

enumerator BT_OTS_OLCP_FEAT_GO_TO: Bit 0 OLCP Go To Op Code Supported

enumerator BT_OTS_OLCP_FEAT_ORDER: Bit 1 OLCP Order Op Code Supported

enumerator BT_OTS_OLCP_FEAT_NUM_REQ: Bit 2 OLCP Request Number of Objects Op Code Supported

enumerator BT_OTS_OLCP_FEAT_CLEAR: Bit 3 OLCP Clear Marking Op Code Supported

enum bt_ots_metadata_request_bit

Object metadata request bit field values.

Values:

enumerator BT_OTS_METADATA_REQ_NAME: Request object name.

enumerator BT_OTS_METADATA_REQ_TYPE: Request object type.

enumerator BT_OTS_METADATA_REQ_SIZE: Request object size.

enumerator BT_OTS_METADATA_REQ_CREATED: Request object first created time.

enumerator BT_OTS_METADATA_REQ_MODIFIED: Request object last modified time.

enumerator BT_OTS_METADATA_REQ_ID: Request object ID.

enumerator BT_OTS_METADATA_REQ_PROPS: Request object properties.

enumerator BT_OTS_METADATA_REQ_ALL: Request all object metadata.

Functions

int bt_ots_obj_add(struct bt_ots *ots, const struct bt_ots_obj_add_param *param)

Add an object to the OTS instance.

This function adds an object to the OTS database. When the object is being added, a callback obj_created() is called to notify the user about a new object ID.

参数:

ots – OTS instance.
param – Object addition parameters.

返回:

ID of created object in case of success.

返回:

negative value in case of error.

int bt_ots_obj_delete(struct bt_ots *ots, uint64_t id)

Delete an object from the OTS instance.

This function deletes an object from the OTS database. When the object is deleted a callback obj_deleted() is called to notify the user about this event. At this point, it is possible to free allocated buffer for object data.

参数:

ots – OTS instance.
id – ID of the object to be deleted (uint48).

返回:

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

void *bt_ots_svc_decl_get(struct bt_ots *ots)

Get the service declaration attribute.

This function is enabled for CONFIG_BT_OTS_SECONDARY_SVC configuration. The first service attribute can be included in any other GATT service.

参数:: ots – OTS instance.
返回:: The first OTS attribute instance.

int bt_ots_init(struct bt_ots *ots, struct bt_ots_init_param *ots_init)

Initialize the OTS instance.

参数:

ots – OTS instance.
ots_init – OTS initialization descriptor.

返回:

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

struct bt_ots *bt_ots_free_instance_get(void)

Get a free instance of OTS from the pool.

返回:: OTS instance in case of success or NULL in case of error.

int bt_ots_client_register(struct bt_ots_client *ots_inst)

Register an Object Transfer Service Instance.

Register an Object Transfer Service instance discovered on the peer. Call this function when an OTS instance is discovered (discovery is to be handled by the higher layer).

参数:: ots_inst – [in] Discovered OTS instance.
返回:: int 0 if success, ERRNO on failure.

int bt_ots_client_unregister(uint8_t index)

Unregister an Object Transfer Service Instance.

Unregister an Object Transfer Service instance when disconnect from the peer. Call this function when an ACL using OTS instance is disconnected.

参数:: index – [in] Index of OTS instance.
返回:: int 0 if success, ERRNO on failure.

uint8_t bt_ots_client_indicate_handler(struct bt_conn *conn, struct bt_gatt_subscribe_params *params, const void *data, uint16_t length)

OTS Indicate Handler function.

Set this function as callback for indicate handler when discovering OTS.

参数:

conn – Connection object. May be NULL, indicating that the peer is being unpaired.
params – Subscription parameters.
data – Attribute value data. If NULL then subscription was removed.
length – Attribute value length.

int bt_ots_client_read_feature(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Read the OTS feature characteristic.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_id(struct bt_ots_client *otc_inst, struct bt_conn *conn, uint64_t obj_id)

Select an object by its Object ID.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
obj_id – Object’s ID.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_first(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the first object.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_last(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the last object.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_next(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the next object.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_select_prev(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Select the previous object.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_read_object_metadata(struct bt_ots_client *otc_inst, struct bt_conn *conn, uint8_t metadata)

Read the metadata of the current object.

The metadata are returned in the obj_metadata_read() callback.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
metadata – Bitfield (`BT_OTS_METADATA_REQ_*`) of the metadata to read.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_read_object_data(struct bt_ots_client *otc_inst, struct bt_conn *conn)

Read the data of the current selected object.

This will trigger an OACP read operation for the current size of the object with a 0 offset and then expect receiving the content via the L2CAP CoC.

The data of the object are returned in the obj_data_read() callback.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_write_object_data(struct bt_ots_client *otc_inst, struct bt_conn *conn, const void *buf, size_t len, off_t offset, enum bt_ots_oacp_write_op_mode mode)

Write the data of the current selected object.

This will trigger an OACP write operation for the current object with a specified offset and then expect transferring the content via the L2CAP CoC.

The length of the data written to object is returned in the obj_data_written() callback.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
buf – Pointer to the data buffer to be written.
len – Size of data.
offset – Offset to write, usually 0.
mode – Mode Parameter for OACP Write Op Code. See bt_ots_oacp_write_op_mode.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_get_object_checksum(struct bt_ots_client *otc_inst, struct bt_conn *conn, off_t offset, size_t len)

Get the checksum of the current selected object.

This will trigger an OACP calculate checksum operation for the current object with a specified offset and length.

The checksum goes to OACP IND and obj_checksum_calculated() callback.

参数:

otc_inst – Pointer to the OTC instance.
conn – Pointer to the connection object.
offset – Offset to calculate, usually 0.
len – Len of data to calculate checksum for. May be less than the current object’s size, but shall not be larger.

返回:

int 0 if success, ERRNO on failure.

int bt_ots_client_decode_dirlisting(uint8_t *data, uint16_t length, bt_ots_client_dirlisting_cb cb)

Decode Directory Listing object into object metadata.

If the Directory Listing object contains multiple objects, then the callback will be called for each of them.

参数:

data – The data received for the directory listing object.
length – Length of the data.
cb – The callback that will be called for each object.

static inline int bt_ots_obj_id_to_str(uint64_t obj_id, char *str, size_t len)

Converts binary OTS Object ID to string.

参数:

obj_id – Object ID.
str – Address of user buffer with enough room to store formatted string containing binary Object ID.
len – Length of data to be copied to user string buffer. Refer to BT_OTS_OBJ_ID_STR_LEN about recommended value.

返回:

Number of successfully formatted bytes from binary ID.

void bt_ots_metadata_display(struct bt_ots_obj_metadata *metadata, uint16_t count)

Displays one or more object metadata as text with LOG_INF.

参数:

metadata – Pointer to the first (or only) metadata in an array.
count – Number of metadata objects to display information of.

struct bt_ots_obj_type: Type of an OTS object.

struct bt_ots_obj_size: Descriptor for OTS Object Size parameter.

struct bt_ots_feat: Features of the OTS.

struct bt_ots_date_time: Date and Time structure.

struct bt_ots_obj_metadata

Metadata of an OTS object.

Used by the server as a descriptor for OTS object initialization. Used by the client to present object metadata to the application.

struct bt_ots_obj_add_param: Descriptor for OTS object addition.

struct bt_ots_obj_created_desc

Descriptor for OTS created object.

Descriptor for OTS object created by the application. This descriptor is returned by bt_ots_cb::obj_created callback which contains further documentation on distinguishing between server and client object creation.

struct bt_ots_cb: OTS callback structure.

struct bt_ots_init_param: Descriptor for OTS initialization.

struct bt_ots_client: OTS client instance.

struct bt_ots_client_cb: OTS client callback structure