From ad76de6ba67b61bf4d543a45bd62ff00f8c6d1a4 Mon Sep 17 00:00:00 2001 From: zhangxiaowei16 Date: Thu, 14 May 2026 18:02:40 +0800 Subject: [PATCH] docs(bluetooth): add CS API, remove AVRCP/BLE scan/advertiser per team decision --- en/api/framework/bluetooth/bt_avrcp.md | 188 --------------- en/api/framework/bluetooth/bt_cs.md | 217 ++++++++++++++++++ .../framework/bluetooth/bt_le_advertiser.md | 139 ----------- en/api/framework/bluetooth/bt_le_scan.md | 141 ------------ en/api/framework/bluetooth/index.md | 10 +- zh-cn/api/framework/bluetooth/bt_avrcp.md | 193 ---------------- zh-cn/api/framework/bluetooth/bt_cs.md | 217 ++++++++++++++++++ .../framework/bluetooth/bt_le_advertiser.md | 141 ------------ zh-cn/api/framework/bluetooth/bt_le_scan.md | 141 ------------ zh-cn/api/framework/bluetooth/index.md | 15 +- 10 files changed, 443 insertions(+), 959 deletions(-) delete mode 100644 en/api/framework/bluetooth/bt_avrcp.md create mode 100644 en/api/framework/bluetooth/bt_cs.md delete mode 100644 en/api/framework/bluetooth/bt_le_advertiser.md delete mode 100644 en/api/framework/bluetooth/bt_le_scan.md delete mode 100644 zh-cn/api/framework/bluetooth/bt_avrcp.md create mode 100644 zh-cn/api/framework/bluetooth/bt_cs.md delete mode 100644 zh-cn/api/framework/bluetooth/bt_le_advertiser.md delete mode 100644 zh-cn/api/framework/bluetooth/bt_le_scan.md diff --git a/en/api/framework/bluetooth/bt_avrcp.md b/en/api/framework/bluetooth/bt_avrcp.md deleted file mode 100644 index 72399f62..00000000 --- a/en/api/framework/bluetooth/bt_avrcp.md +++ /dev/null @@ -1,188 +0,0 @@ -\[ English | [简体中文](../../../../zh-cn/api/framework/bluetooth/bt_avrcp.md) \] - -# Bluetooth AVRCP API - -The openvela Bluetooth AVRCP (Audio/Video Remote Control Profile) interface supports playback control, track information queries, and more. - -Header files: #include "bt_avrcp.h", #include "bt_avrcp_control.h", #include "bt_avrcp_target.h" - - -## openvela Implementation Notes - -- **Dual-role support**: Controller (control side) and Target (target side) -- **Features**: Play/pause/skip tracks, volume control, track information retrieval - - -## Synchronous Interfaces - - -### bt_avrcp_control_unregister_callbacks - -```c -bool bt_avrcp_control_unregister_callbacks(bt_instance_t* ins, void* cookie); -``` - -Unregister callback functions and stop receiving state change notifications. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `cookie` User context. - -**Returns**: - -Returns the callback cookie on success, or NULL on failure. - - -### bt_avrcp_control_get_element_attributes - -```c -bt_status_t bt_avrcp_control_get_element_attributes(bt_instance_t* ins, bt_address_t* addr); -``` - -Get media element attributes from the remote device. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the remote device. - - -**Returns**: - -Returns BT_STATUS_SUCCESS on success, or an error code on failure. - - -### bt_avrcp_control_send_passthrough_cmd - -```c -bt_status_t bt_avrcp_control_send_passthrough_cmd(bt_instance_t* ins, bt_address_t* addr, uint8_t cmd, uint8_t state); -``` - -Send a passthrough command to the remote device. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the remote device. -- `cmd` Command code. -- `state` Key state. - - -### bt_avrcp_control_get_unit_info - -```c -bt_status_t bt_avrcp_control_get_unit_info(bt_instance_t* ins, bt_address_t* addr); -``` - -Get unit information from the remote AVRCP device. - - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the remote device. - - -### bt_avrcp_control_get_subunit_info - -```c -bt_status_t bt_avrcp_control_get_subunit_info(bt_instance_t* ins, bt_address_t* addr); -``` - -Get subunit information from the remote device. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the remote device. - - -### bt_avrcp_control_get_playback_state - -```c -bt_status_t bt_avrcp_control_get_playback_state(bt_instance_t* ins, bt_address_t* addr); -``` - -Get the current playback state of the remote device. - - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the remote device. - - -### bt_avrcp_control_register_notification - -```c -bt_status_t bt_avrcp_control_register_notification(bt_instance_t* ins, bt_address_t* addr, uint8_t event, uint32_t interval); -``` - -Register for event notifications from the remote device. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the remote device. -- `event` Event type. -- `interval` Notification interval. - - -### bt_avrcp_target_unregister_callbacks - -```c -bool bt_avrcp_target_unregister_callbacks(bt_instance_t* ins, void* cookie); -``` - -Unregister callback functions and stop receiving state change notifications. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `cookie` User context. - -**Returns**: - -Returns the callback cookie on success, or NULL on failure. - - -### bt_avrcp_target_get_play_status_response - -```c -bt_status_t bt_avrcp_target_get_play_status_response(bt_instance_t* ins, bt_address_t* addr, avrcp_play_status_t status, uint32_t song_len, uint32_t song_pos); -``` - -Respond to a play status query from the remote device. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the peer device. -- `status` Play status code. -- `song_len` Song length in milliseconds. -- `song_pos` Current playback position in milliseconds. - -**Returns**: - -Returns BT_STATUS_SUCCESS on success, or an error code on failure. - - -### bt_avrcp_target_play_status_notify - -```c -bt_status_t bt_avrcp_target_play_status_notify(bt_instance_t* ins, bt_address_t* addr, avrcp_play_status_t status); -``` - -Notify the remote device of a playback status change. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `addr` Bluetooth address of the remote device. -- `status` Play status code. - - -**Returns**: - -Returns BT_STATUS_SUCCESS on success, or an error code on failure. diff --git a/en/api/framework/bluetooth/bt_cs.md b/en/api/framework/bluetooth/bt_cs.md new file mode 100644 index 00000000..384c8112 --- /dev/null +++ b/en/api/framework/bluetooth/bt_cs.md @@ -0,0 +1,217 @@ +\[ English | [简体中文](../../../../zh-cn/api/framework/bluetooth/bt_cs.md) \] + +# Bluetooth Channel Sounding API + +The openvela Bluetooth Channel Sounding (CS) interface provides distance measurement and positioning capabilities between Bluetooth devices. Based on the channel sounding technology introduced in the Bluetooth 5.4 specification, it supports centimeter-level ranging accuracy. + +Header file: `#include ` + +## openvela Implementation Notes + +- **Ranging methods**: Supports automatic selection (AUTO), RSSI, and CS ranging methods +- **Role model**: Supports Initiator and Reflector roles +- **RAS features**: Supports real-time ranging data, lost data segment retrieval, abort operation, and data filtering +- **Callback notifications**: Ranging start, stop, and result events are delivered asynchronously via callbacks +- **Configuration dependency**: Test interface requires `CONFIG_BT_CS_RAS_TEST` + +## Callback Management + +### bt_cs_register_callbacks + +```c +void* bt_cs_register_callbacks(bt_instance_t* ins, const cs_callbacks_t* callbacks); +``` + +Register CS event callback functions. After successful registration, the system notifies the application via callbacks when distance measurement starts, stops, or produces results. + +**Parameters**: + +- `ins` Bluetooth client instance. +- `callbacks` CS event callback function set, see `cs_callbacks_t`. + +**Returns**: + +On success, returns a callback cookie (non-NULL) for later unregistration; on failure, returns NULL. + +### bt_cs_unregister_callbacks + +```c +bool bt_cs_unregister_callbacks(bt_instance_t* ins, void* cookie); +``` + +Unregister previously registered CS event callback functions. + +**Parameters**: + +- `ins` Bluetooth client instance. +- `cookie` Cookie returned during callback registration. + +**Returns**: + +Returns `true` on success, `false` on failure. + +## Distance Measurement + +### bt_cs_start_distance_measurement + +```c +bt_status_t bt_cs_start_distance_measurement(bt_instance_t* ins, const bt_distance_measurement_params_t* params); +``` + +Start distance measurement. Callbacks must be registered via `bt_cs_register_callbacks` before calling this function. Measurement results are delivered through the `cs_distance_measure_result_cb` callback. + +**Parameters**: + +- `ins` Bluetooth client instance. +- `params` Distance measurement parameters, see `bt_distance_measurement_params_t`. + +**Returns**: + +Returns `BT_STATUS_SUCCESS` on success, or an error code on failure. + +### bt_cs_stop_distance_measurement + +```c +bt_status_t bt_cs_stop_distance_measurement(bt_instance_t* ins, bt_address_t* addr, uint8_t method, bool timeout); +``` + +Stop distance measurement. + +**Parameters**: + +- `ins` Bluetooth client instance. +- `addr` Remote device address. +- `method` Ranging method (AUTO/RSSI/CS). +- `timeout` Whether stopping due to timeout. + +**Returns**: + +Returns `BT_STATUS_SUCCESS` on success, or an error code on failure. + +## Capability Query + +### bt_get_cs_max_supported_security_level + +```c +bt_status_t bt_get_cs_max_supported_security_level(bt_instance_t* ins, bt_address_t* addr); +``` + +Get the maximum CS security level supported by the remote device. + +**Parameters**: + +- `ins` Bluetooth client instance. +- `addr` Remote device address. + +**Returns**: + +Returns `BT_STATUS_SUCCESS` on success, or an error code on failure. + +## Configuration Management + +### bt_cs_set_config + +```c +bt_status_t bt_cs_set_config(bt_instance_t* ins, bt_address_t* addr, const bt_cs_set_params_t* params); +``` + +Set CS configuration parameters, including RAS features, role, antenna selection, and maximum transmit power. + +**Parameters**: + +- `ins` Bluetooth client instance. +- `addr` Remote device address. +- `params` CS configuration parameters, see `bt_cs_set_params_t`. + +**Returns**: + +Returns `BT_STATUS_SUCCESS` on success, or an error code on failure. + +## Data Structures + +### bt_distance_measurement_params_t + +Distance measurement parameters structure. + +| Field | Type | Description | +| -------------------- | -------------- | ------------------------------------- | +| `addr` | `bt_address_t` | Remote device address | +| `method` | `uint8_t` | Ranging method (0=AUTO, 1=RSSI, 2=CS) | +| `role` | `uint8_t` | Role (initiator/reflector) | +| `interval_ms` | `uint16_t` | Measurement interval (milliseconds) | +| `duration_ms` | `uint16_t` | Measurement duration (milliseconds) | +| `submode` | `uint8_t` | CS submode | +| `max_steps` | `uint8_t` | Maximum steps | +| `mode0_steps` | `uint8_t` | Mode 0 steps | +| `rtt_type` | `uint8_t` | RTT type | +| `sync_phy` | `uint8_t` | Sync PHY | +| `channel_map` | `uint8_t` | Channel map | +| `antenna_paths_mask` | `uint8_t` | Antenna paths mask | +| `vendor_specific` | `uint8_t` | Vendor-specific parameter | +| `debug_flags` | `uint8_t` | Debug flags | + +### bt_distance_measurement_result_t + +Distance measurement result structure. + +| Field | Type | Description | +| --------------------------- | --------- | ------------------------------ | +| `centimeter` | `uint8_t` | Distance (centimeters) | +| `error_centimeter` | `uint8_t` | Distance error (centimeters) | +| `azimuth_angle` | `uint8_t` | Azimuth angle | +| `error_azimuthAngle` | `uint8_t` | Azimuth angle error | +| `altitude_angle` | `uint8_t` | Altitude angle | +| `error_altitudeAngle` | `uint8_t` | Altitude angle error | +| `elapsed_realtime_nanos` | `long` | Elapsed realtime (nanoseconds) | +| `confidence_level` | `uint8_t` | Confidence level | +| `delay_spread_meters` | `double` | Delay spread (meters) | +| `detected_attack_level` | `uint8_t` | Detected attack level | +| `velocity_meters_persecond` | `double` | Velocity (meters/second) | +| `method` | `uint8_t` | Ranging method used | + +### bt_cs_set_params_t + +CS configuration parameters structure. + +| Field | Type | Description | +| --------------------------- | ---------- | ------------------------------------------------- | +| `ras_feature` | `uint32_t` | RAS feature bits (see macro definitions below) | +| `role` | `uint8_t` | CS role bits (Bit 0: initiator, Bit 1: reflector) | +| `cs_sync_antenna_selection` | `uint8_t` | CS_SYNC antenna selection | +| `max_tx_power` | `int8_t` | Maximum TX power (dBm, range -127 to 20) | + +### cs_callbacks_t + +CS event callback function set. + +| Field | Type | Description | +| -------------------------------- | ---------------- | ------------------------------------- | +| `size` | `size_t` | Structure size | +| `cs_distance_measure_started_cb` | Function pointer | Distance measurement started callback | +| `cs_distance_measure_stopped_cb` | Function pointer | Distance measurement stopped callback | +| `cs_distance_measure_result_cb` | Function pointer | Distance measurement result callback | + +## Macro Definitions + +### RAS Feature Bits + +| Macro | Value | Description | +| --------------------------------------- | ----- | ----------------------------------- | +| `BT_CS_RAS_REAL_TIME_RANGING_DATA` | 0x01 | Real-time ranging data | +| `BT_CS_RAS_RETRIEVE_LOST_DATA_SEGMENTS` | 0x02 | Retrieve lost ranging data segments | +| `BT_CS_RAS_ABORT_OPERATION` | 0x04 | Abort operation | +| `BT_CS_RAS_FILTER_RANGING_DATA` | 0x08 | Filter ranging data | + +### Antenna Selection + +| Macro | Value | Description | +| ---------------------------------- | ----- | ---------------------------------------------- | +| `BT_CS_ANTENNA_SEL_1` | 0x01 | Use antenna identifier 1 | +| `BT_CS_ANTENNA_SEL_2` | 0x02 | Use antenna identifier 2 | +| `BT_CS_ANTENNA_SEL_3` | 0x03 | Use antenna identifier 3 | +| `BT_CS_ANTENNA_SEL_4` | 0x04 | Use antenna identifier 4 | +| `BT_CS_ANTENNA_SEL_SINGLE_REPEATE` | 0xFD | Antenna identifiers in single repetitive order | +| `BT_CS_ANTENNA_SEL_DOUBLE_REPEATE` | 0xFE | Antenna identifiers in double repetitive order | +| `BT_CS_ANTENNA_SEL_NO_RECOMMEND` | 0xFF | Host has no recommendation | + +**openvela extension interface.** diff --git a/en/api/framework/bluetooth/bt_le_advertiser.md b/en/api/framework/bluetooth/bt_le_advertiser.md deleted file mode 100644 index 74b1ca76..00000000 --- a/en/api/framework/bluetooth/bt_le_advertiser.md +++ /dev/null @@ -1,139 +0,0 @@ -\[ English | [简体中文](../../../../zh-cn/api/framework/bluetooth/bt_le_advertiser.md) \] - -# Bluetooth BLE Advertising API - -The openvela Bluetooth BLE advertising interface is used to send BLE advertising data and manage advertising instances. - -Header file: `#include "bt_le_advertiser.h"` - - -## openvela Implementation Notes - -- **Advertising types**: Supports connectable advertising, non-connectable advertising, scan response, etc. -- **Advertising data**: Supports custom advertising data and scan response data -- **Multiple instances**: Supports running multiple advertising instances simultaneously - - -## Synchronous Interfaces - - -### bt_le_stop_advertising - -```c -void bt_le_stop_advertising(bt_instance_t* ins, bt_advertiser_t* adver); -``` - -Stop BLE advertising. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `adver` Advertiser instance. - -**Returns**: - -None. - - -### bt_le_stop_advertising_id - -```c -void bt_le_stop_advertising_id(bt_instance_t* ins, uint8_t adv_id); -``` - -Stop the BLE advertising instance with the specified ID. - -**Parameters**: - -- `ins` Bluetooth client instance. -- `adv_id` Advertising instance ID. - - -### bt_le_advertising_is_supported - -```c -bool bt_le_advertising_is_supported(bt_instance_t* ins); -``` - -Query whether BLE advertising is supported. - -**Parameters**: - -- `ins` Bluetooth client instance. - - -**Returns**: - -Returns true if BLE advertising is supported, false otherwise. - - -## Asynchronous Interfaces - - -### bt_le_start_advertising_async - -```c -bt_status_t bt_le_start_advertising_async(bt_instance_t* ins, ble_adv_params_t* params, uint8_t* adv_data, uint16_t adv_len, uint8_t* scan_rsp_data, uint16_t scan_rsp_len, advertiser_callback_t* adv_cbs, bt_le_start_adv_callback_cb_t cb, void* userdata); -``` - -Start BLE advertising (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `params` Advertising parameters structure. -- `adv_data` Advertising data. -- `adv_len` Advertising data length. -- `scan_rsp_data` Scan response data. -- `scan_rsp_len` Scan response data length. -- `adv_cbs` Advertiser callback function set. -- `cb` Completion callback function. -- `userdata` User data. - - -### bt_le_stop_advertising_async - -```c -bt_status_t bt_le_stop_advertising_async(bt_instance_t* ins, bt_advertiser_t* adver, bt_status_cb_t cb, void* userdata); -``` - -Stop BLE advertising (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `adver` Advertiser instance. -- `cb` Completion callback function. -- `userdata` User data. - - - -### bt_le_stop_advertising_id_async - -```c -bt_status_t bt_le_stop_advertising_id_async(bt_instance_t* ins, uint8_t adv_id, bt_status_cb_t cb, void* userdata); -``` - -Stop BLE advertising by specified ID (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `adv_id` Advertising instance ID. -- `cb` Completion callback function. -- `userdata` User data. - - -### bt_le_advertising_is_supported_async - -```c -bt_status_t bt_le_advertising_is_supported_async(bt_instance_t* ins, bt_bool_cb_t cb, void* userdata); -``` - -Query whether BLE advertising is supported (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `cb` Completion callback function. -- `userdata` User data. diff --git a/en/api/framework/bluetooth/bt_le_scan.md b/en/api/framework/bluetooth/bt_le_scan.md deleted file mode 100644 index 41fd5cea..00000000 --- a/en/api/framework/bluetooth/bt_le_scan.md +++ /dev/null @@ -1,141 +0,0 @@ -\[ English | [简体中文](../../../../zh-cn/api/framework/bluetooth/bt_le_scan.md) \] - -# Bluetooth BLE Scanning API - -The openvela Bluetooth BLE scanning interface is used to discover nearby BLE devices and receive broadcast data. - -Header file: `#include "bt_le_scan.h"` - - -## openvela Implementation Notes - -- **Scan modes**: Supports passive scanning and active scanning -- **Filters**: Supports filtering scan results by name, address, UUID, and other criteria -- **Callback notifications**: Scan results are returned asynchronously via callback functions - - -## Synchronous Interfaces - - -### bt_le_stop_scan - -```c -void bt_le_stop_scan(bt_instance_t* ins, bt_scanner_t* scanner); -``` - -Stop BLE scanning. - -**Parameters**: - -- `scanner` Scanner instance. -- `ins` Bluetooth client instance. - -**Returns**: - -None. - - -### bt_le_scan_is_supported - -```c -bool bt_le_scan_is_supported(bt_instance_t* ins); -``` - -Query whether BLE scanning is supported. - -**Parameters**: - -- `ins` Bluetooth client instance. - - -**Returns**: - -Returns true if BLE scanning is supported, false otherwise. - - -## Asynchronous Interfaces - - -### bt_le_start_scan_async - -```c -bt_status_t bt_le_start_scan_async(bt_instance_t* ins, const scanner_callbacks_t* scan_cbs, bt_le_start_scan_cb_t cb, void* userdata); -``` - -Start BLE scanning (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `scan_cbs` Scanner callback function set. -- `cb` Completion callback function. -- `userdata` User data. - - -### bt_le_start_scan_settings_async - -```c -bt_status_t bt_le_start_scan_settings_async(bt_instance_t* ins, ble_scan_settings_t* settings, const scanner_callbacks_t* scan_cbs, bt_le_start_scan_cb_t cb, void* userdata); -``` - -Start BLE scanning with custom settings (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `settings` Scan settings. -- `scan_cbs` Scanner callback function set. -- `cb` Completion callback function. -- `userdata` User data. - - - -### bt_le_start_scan_with_filters_async - -```c -bt_status_t bt_le_start_scan_with_filters_async(bt_instance_t* ins, ble_scan_settings_t* settings, ble_scan_filter_t* filter, const scanner_callbacks_t* scan_cbs, bt_le_start_scan_cb_t cb, void* userdata); -``` - -Start BLE scanning with filters (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `settings` Scan settings. -- `filter` Filter criteria. -- `scan_cbs` Scanner callback function set. -- `cb` Completion callback function. -- `userdata` User data. - - -### bt_le_stop_scan_async - -```c -bt_status_t bt_le_stop_scan_async(bt_instance_t* ins, bt_scanner_t* scanner, bt_le_stop_scan_cb_t cb, void* userdata); -``` - -Stop BLE scanning (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `scanner` Scanner instance. -- `cb` Completion callback function. -- `userdata` User data. - - - - -### bt_le_scan_is_supported_async - -```c -bt_status_t bt_le_scan_is_supported_async(bt_instance_t* ins, bt_bool_cb_t cb, void* userdata); -``` - -Query whether BLE scanning is supported (asynchronous version). - -**Parameters**: - -- `ins` Bluetooth client instance. -- `cb` Completion callback function. -- `userdata` User data. diff --git a/en/api/framework/bluetooth/index.md b/en/api/framework/bluetooth/index.md index 5b8d8faa..c2626d82 100644 --- a/en/api/framework/bluetooth/index.md +++ b/en/api/framework/bluetooth/index.md @@ -10,17 +10,15 @@ The openvela Bluetooth framework provides a complete Bluetooth stack interface, - **[GATT](bt_gatt.md)** (Generic Attribute Profile) — BLE data attribute read/write and notifications - **[Device Management](bt_device.md)** — Remote device pairing, connection, and property queries -## BLE Interfaces - -- **[BLE Scanning](bt_le_scan.md)** — BLE device discovery and broadcast data reception -- **[BLE Advertising](bt_le_advertiser.md)** — BLE advertising data transmission and management - ## Audio and Media - **[A2DP](bt_a2dp.md)** (Advanced Audio Distribution Profile) — High-quality stereo music streaming -- **[AVRCP](bt_avrcp.md)** (Audio/Video Remote Control Profile) — Playback control, track change, volume adjustment - **[HFP](bt_hfp.md)** (Hands-Free Profile) — Bluetooth call functionality +## Positioning and Ranging + +- **[CS](bt_cs.md)** (Channel Sounding) — Bluetooth channel sounding for distance measurement and positioning + ## Data and Peripherals - **[HID](bt_hid.md)** (Human Interface Device) — Keyboards, mice, game controllers diff --git a/zh-cn/api/framework/bluetooth/bt_avrcp.md b/zh-cn/api/framework/bluetooth/bt_avrcp.md deleted file mode 100644 index b47c4167..00000000 --- a/zh-cn/api/framework/bluetooth/bt_avrcp.md +++ /dev/null @@ -1,193 +0,0 @@ -\[ [English](../../../../en/api/framework/bluetooth/bt_avrcp.md) | 简体中文 \] - -# 蓝牙 AVRCP API - -openvela 蓝牙 AVRCP（音视频远程控制）接口，支持播放控制、曲目信息查询等。 - -头文件：#include "bt_avrcp.h"、#include "bt_avrcp_control.h"、#include "bt_avrcp_target.h" - - -## openvela 实现说明 - -- **双角色支持**：Controller（控制端）和 Target（目标端） -- **功能**：播放/暂停/切歌、音量控制、曲目信息获取 - - -## 同步接口 - - -### bt_avrcp_control_unregister_callbacks - -```c -bool bt_avrcp_control_unregister_callbacks(bt_instance_t* ins, void* cookie); -``` - -取消注册回调函数，停止接收状态变更通知。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `cookie` 用户上下文。 - -**返回值**： - -取消注册回调函数。 - - -### bt_avrcp_control_get_element_attributes - -```c -bt_status_t bt_avrcp_control_get_element_attributes(bt_instance_t* ins, bt_address_t* addr); -``` - -获取媒体元素属性。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 远程设备蓝牙地址。 - - -**返回值**： - -成功时返回 BT_STATUS_SUCCESS，失败时返回错误码。 - - -### bt_avrcp_control_send_passthrough_cmd - -```c -bt_status_t bt_avrcp_control_send_passthrough_cmd(bt_instance_t* ins, bt_address_t* addr, uint8_t cmd, uint8_t state); -``` - -发送透传命令。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 远程设备蓝牙地址。 -- `cmd` 命令。 -- `state` 状态。 - - -### bt_avrcp_control_get_unit_info - -```c -bt_status_t bt_avrcp_control_get_unit_info(bt_instance_t* ins, bt_address_t* addr); -``` - -获取远程 AVRCP 设备的单元信息。 - - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 蓝牙地址。 - - -### bt_avrcp_control_get_subunit_info - -```c -bt_status_t bt_avrcp_control_get_subunit_info(bt_instance_t* ins, bt_address_t* addr); -``` - -获取子单元信息。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 远程设备蓝牙地址。 - - -### bt_avrcp_control_get_playback_state - -```c -bt_status_t bt_avrcp_control_get_playback_state(bt_instance_t* ins, bt_address_t* addr); -``` - -获取远程设备的当前播放状态。 - - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 蓝牙地址。 - - -### bt_avrcp_control_register_notification - -```c -bt_status_t bt_avrcp_control_register_notification(bt_instance_t* ins, bt_address_t* addr, uint8_t event, uint32_t interval); -``` - -注册事件通知。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 远程设备蓝牙地址。 -- `event` 事件类型。 -- `interval` 间隔。 - - -### bt_avrcp_target_unregister_callbacks - -```c -bool bt_avrcp_target_unregister_callbacks(bt_instance_t* ins, void* cookie); -``` - -取消注册回调函数，停止接收状态变更通知。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `cookie` 用户上下文。 - - - -- `cookie` 用户上下文。 -- `ins` 蓝牙客户端实例。 - -**返回值**： - -成功时返回回调 cookie，失败或已注册时返回 NULL。 - - -### bt_avrcp_target_get_play_status_response - -```c -bt_status_t bt_avrcp_target_get_play_status_response(bt_instance_t* ins, bt_address_t* addr, avrcp_play_status_t status, uint32_t song_len, uint32_t song_pos); -``` - -回复播放状态查询。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 蓝牙地址 of the peer device. -- `status` 状态码。 -- `song_len` 歌曲长度（毫秒）。 -- `song_pos` 当前播放位置（毫秒）。 - -**返回值**： - -成功时返回 BT_STATUS_SUCCESS，失败时返回错误码。 - - -### bt_avrcp_target_play_status_notify - -```c -bt_status_t bt_avrcp_target_play_status_notify(bt_instance_t* ins, bt_address_t* addr, avrcp_play_status_t status); -``` - -通知播放状态变更。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `addr` 远程设备蓝牙地址。 -- `status` 状态码。 - - -**返回值**： - -成功时返回 BT_STATUS_SUCCESS，失败时返回错误码。 diff --git a/zh-cn/api/framework/bluetooth/bt_cs.md b/zh-cn/api/framework/bluetooth/bt_cs.md new file mode 100644 index 00000000..f95476f4 --- /dev/null +++ b/zh-cn/api/framework/bluetooth/bt_cs.md @@ -0,0 +1,217 @@ +\[ [English](../../../../en/api/framework/bluetooth/bt_cs.md) | 简体中文 \] + +# 蓝牙 Channel Sounding API + +openvela 蓝牙 Channel Sounding（CS）接口，用于蓝牙设备间的距离测量和定位功能。CS 基于蓝牙 5.4 规范引入的信道探测技术，支持厘米级精度的测距。 + +头文件：`#include ` + +## openvela 实现说明 + +- **测距方法**：支持自动选择（AUTO）、RSSI 和 CS 三种测距方法 +- **角色模型**：支持发起方（Initiator）和反射方（Reflector）两种角色 +- **RAS 特性**：支持实时测距数据、丢失数据段恢复、中止操作和数据过滤 +- **回调通知**：通过回调函数异步返回测距启动、停止和结果事件 +- **配置依赖**：测试接口需启用 `CONFIG_BT_CS_RAS_TEST` + +## 回调管理 + +### bt_cs_register_callbacks + +```c +void* bt_cs_register_callbacks(bt_instance_t* ins, const cs_callbacks_t* callbacks); +``` + +注册 CS 事件回调函数。注册成功后，当距离测量启动、停止或产生结果时，系统会通过回调函数通知应用。 + +**参数**： + +- `ins` 蓝牙客户端实例。 +- `callbacks` CS 事件回调函数集合，参见 `cs_callbacks_t`。 + +**返回值**： + +成功时返回回调 cookie（非 NULL），用于后续注销；失败时返回 NULL。 + +### bt_cs_unregister_callbacks + +```c +bool bt_cs_unregister_callbacks(bt_instance_t* ins, void* cookie); +``` + +注销已注册的 CS 事件回调函数。 + +**参数**： + +- `ins` 蓝牙客户端实例。 +- `cookie` 注册回调时返回的 cookie。 + +**返回值**： + +成功时返回 `true`，失败时返回 `false`。 + +## 距离测量 + +### bt_cs_start_distance_measurement + +```c +bt_status_t bt_cs_start_distance_measurement(bt_instance_t* ins, const bt_distance_measurement_params_t* params); +``` + +启动距离测量。调用前需先通过 `bt_cs_register_callbacks` 注册回调函数，测量结果将通过 `cs_distance_measure_result_cb` 回调返回。 + +**参数**： + +- `ins` 蓝牙客户端实例。 +- `params` 距离测量参数，参见 `bt_distance_measurement_params_t`。 + +**返回值**： + +成功时返回 `BT_STATUS_SUCCESS`，失败时返回错误码。 + +### bt_cs_stop_distance_measurement + +```c +bt_status_t bt_cs_stop_distance_measurement(bt_instance_t* ins, bt_address_t* addr, uint8_t method, bool timeout); +``` + +停止距离测量。 + +**参数**： + +- `ins` 蓝牙客户端实例。 +- `addr` 远端设备地址。 +- `method` 测距方法（AUTO/RSSI/CS）。 +- `timeout` 是否因超时而停止。 + +**返回值**： + +成功时返回 `BT_STATUS_SUCCESS`，失败时返回错误码。 + +## 能力查询 + +### bt_get_cs_max_supported_security_level + +```c +bt_status_t bt_get_cs_max_supported_security_level(bt_instance_t* ins, bt_address_t* addr); +``` + +获取远端设备支持的最大 CS 安全等级。 + +**参数**： + +- `ins` 蓝牙客户端实例。 +- `addr` 远端设备地址。 + +**返回值**： + +成功时返回 `BT_STATUS_SUCCESS`，失败时返回错误码。 + +## 配置管理 + +### bt_cs_set_config + +```c +bt_status_t bt_cs_set_config(bt_instance_t* ins, bt_address_t* addr, const bt_cs_set_params_t* params); +``` + +设置 CS 配置参数，包括 RAS 特性、角色、天线选择和最大发射功率。 + +**参数**： + +- `ins` 蓝牙客户端实例。 +- `addr` 远端设备地址。 +- `params` CS 配置参数，参见 `bt_cs_set_params_t`。 + +**返回值**： + +成功时返回 `BT_STATUS_SUCCESS`，失败时返回错误码。 + +## 数据结构 + +### bt_distance_measurement_params_t + +距离测量参数结构体。 + +| 字段 | 类型 | 说明 | +| -------------------- | -------------- | -------------------------------- | +| `addr` | `bt_address_t` | 远端设备地址 | +| `method` | `uint8_t` | 测距方法（0=AUTO, 1=RSSI, 2=CS） | +| `role` | `uint8_t` | 角色（发起方/反射方） | +| `interval_ms` | `uint16_t` | 测量间隔（毫秒） | +| `duration_ms` | `uint16_t` | 测量持续时间（毫秒） | +| `submode` | `uint8_t` | CS 子模式 | +| `max_steps` | `uint8_t` | 最大步数 | +| `mode0_steps` | `uint8_t` | Mode 0 步数 | +| `rtt_type` | `uint8_t` | RTT 类型 | +| `sync_phy` | `uint8_t` | 同步 PHY | +| `channel_map` | `uint8_t` | 信道映射 | +| `antenna_paths_mask` | `uint8_t` | 天线路径掩码 | +| `vendor_specific` | `uint8_t` | 厂商自定义参数 | +| `debug_flags` | `uint8_t` | 调试标志 | + +### bt_distance_measurement_result_t + +距离测量结果结构体。 + +| 字段 | 类型 | 说明 | +| --------------------------- | --------- | ---------------------- | +| `centimeter` | `uint8_t` | 距离（厘米） | +| `error_centimeter` | `uint8_t` | 距离误差（厘米） | +| `azimuth_angle` | `uint8_t` | 方位角 | +| `error_azimuthAngle` | `uint8_t` | 方位角误差 | +| `altitude_angle` | `uint8_t` | 仰角 | +| `error_altitudeAngle` | `uint8_t` | 仰角误差 | +| `elapsed_realtime_nanos` | `long` | 经过的实时时间（纳秒） | +| `confidence_level` | `uint8_t` | 置信度 | +| `delay_spread_meters` | `double` | 延迟扩展（米） | +| `detected_attack_level` | `uint8_t` | 检测到的攻击等级 | +| `velocity_meters_persecond` | `double` | 速度（米/秒） | +| `method` | `uint8_t` | 使用的测距方法 | + +### bt_cs_set_params_t + +CS 配置参数结构体。 + +| 字段 | 类型 | 说明 | +| --------------------------- | ---------- | ----------------------------------------- | +| `ras_feature` | `uint32_t` | RAS 特性位（见下方宏定义） | +| `role` | `uint8_t` | CS 角色位（Bit 0: 发起方, Bit 1: 反射方） | +| `cs_sync_antenna_selection` | `uint8_t` | CS_SYNC 天线选择 | +| `max_tx_power` | `int8_t` | 最大发射功率（dBm，范围 -127 到 20） | + +### cs_callbacks_t + +CS 事件回调函数集合。 + +| 字段 | 类型 | 说明 | +| -------------------------------- | -------- | ---------------- | +| `size` | `size_t` | 结构体大小 | +| `cs_distance_measure_started_cb` | 函数指针 | 距离测量启动回调 | +| `cs_distance_measure_stopped_cb` | 函数指针 | 距离测量停止回调 | +| `cs_distance_measure_result_cb` | 函数指针 | 距离测量结果回调 | + +## 宏定义 + +### RAS 特性位 + +| 宏 | 值 | 说明 | +| --------------------------------------- | ---- | -------------------- | +| `BT_CS_RAS_REAL_TIME_RANGING_DATA` | 0x01 | 实时测距数据 | +| `BT_CS_RAS_RETRIEVE_LOST_DATA_SEGMENTS` | 0x02 | 恢复丢失的测距数据段 | +| `BT_CS_RAS_ABORT_OPERATION` | 0x04 | 中止操作 | +| `BT_CS_RAS_FILTER_RANGING_DATA` | 0x08 | 过滤测距数据 | + +### 天线选择 + +| 宏 | 值 | 说明 | +| ---------------------------------- | ---- | ---------------------- | +| `BT_CS_ANTENNA_SEL_1` | 0x01 | 使用天线 1 | +| `BT_CS_ANTENNA_SEL_2` | 0x02 | 使用天线 2 | +| `BT_CS_ANTENNA_SEL_3` | 0x03 | 使用天线 3 | +| `BT_CS_ANTENNA_SEL_4` | 0x04 | 使用天线 4 | +| `BT_CS_ANTENNA_SEL_SINGLE_REPEATE` | 0xFD | 天线标识符单次重复顺序 | +| `BT_CS_ANTENNA_SEL_DOUBLE_REPEATE` | 0xFE | 天线标识符双次重复顺序 | +| `BT_CS_ANTENNA_SEL_NO_RECOMMEND` | 0xFF | 主机无推荐 | + +**openvela 扩展接口。** diff --git a/zh-cn/api/framework/bluetooth/bt_le_advertiser.md b/zh-cn/api/framework/bluetooth/bt_le_advertiser.md deleted file mode 100644 index c9ae7232..00000000 --- a/zh-cn/api/framework/bluetooth/bt_le_advertiser.md +++ /dev/null @@ -1,141 +0,0 @@ -\[ [English](../../../../en/api/framework/bluetooth/bt_le_advertiser.md) | 简体中文 \] - -# 蓝牙 BLE 广播 API - -openvela 蓝牙 BLE 广播接口，用于发送 BLE 广播数据和管理广播实例。 - -头文件：`#include "bt_le_advertiser.h"` - - -## openvela 实现说明 - -- **广播类型**：支持可连接广播、不可连接广播、扫描响应等 -- **广播数据**：支持自定义广播数据和扫描响应数据 -- **多实例**：支持同时运行多个广播实例 - - -## 同步接口 - - -### bt_le_stop_advertising - -```c -void bt_le_stop_advertising(bt_instance_t* ins, bt_advertiser_t* adver); -``` - -停止 BLE 广播。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `adver` 广播器实例。 - -**返回值**： - - - -### bt_le_stop_advertising_id - -```c -void bt_le_stop_advertising_id(bt_instance_t* ins, uint8_t adv_id); -``` - -停止指定 ID 的 BLE 广播实例。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `adv_id` 广播实例 ID。 - - -### bt_le_advertising_is_supported - -```c -bool bt_le_advertising_is_supported(bt_instance_t* ins); -``` - -广播数据查询supported。 - -**参数**： - -- `ins` 蓝牙客户端实例。 - - -**返回值**： - -bt_le_advertising_is_supported 操作。 - - -## 异步接口 - - -### bt_le_start_advertising_async - -```c -bt_status_t bt_le_start_advertising_async(bt_instance_t* ins, ble_adv_params_t* params, uint8_t* adv_data, uint16_t adv_len, uint8_t* scan_rsp_data, uint16_t scan_rsp_len, advertiser_callback_t* adv_cbs, bt_le_start_adv_callback_cb_t cb, void* userdata); -``` - -开始 BLE 广播（异步版本）。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `params` 参数结构体。 -- `adv_data` 广播数据。 -- `adv_len` 广播数据长度。 -- `scan_rsp_data` 扫描响应数据。 -- `scan_rsp_len` 扫描响应数据长度。 -- `adv_cbs` 广播回调函数集合。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - - -### bt_le_stop_advertising_async - -```c -bt_status_t bt_le_stop_advertising_async(bt_instance_t* ins, bt_advertiser_t* adver, bt_status_cb_t cb, void* userdata); -``` - - - - - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `adver` 广播器实例。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - - - -### bt_le_stop_advertising_id_async - -```c -bt_status_t bt_le_stop_advertising_id_async(bt_instance_t* ins, uint8_t adv_id, bt_status_cb_t cb, void* userdata); -``` - -停止BLE 广播（指定 ID）（异步版本）。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `adv_id` 广播实例 ID。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - - -### bt_le_advertising_is_supported_async - -```c -bt_status_t bt_le_advertising_is_supported_async(bt_instance_t* ins, bt_bool_cb_t cb, void* userdata); -``` - -查询是否支持 BLE 广播（异步版本）。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - diff --git a/zh-cn/api/framework/bluetooth/bt_le_scan.md b/zh-cn/api/framework/bluetooth/bt_le_scan.md deleted file mode 100644 index 27d1e986..00000000 --- a/zh-cn/api/framework/bluetooth/bt_le_scan.md +++ /dev/null @@ -1,141 +0,0 @@ -\[ [English](../../../../en/api/framework/bluetooth/bt_le_scan.md) | 简体中文 \] - -# 蓝牙 BLE 扫描 API - -openvela 蓝牙 BLE 扫描接口，用于发现周围的 BLE 设备和广播数据。 - -头文件：`#include "bt_le_scan.h"` - - -## openvela 实现说明 - -- **扫描模式**：支持被动扫描和主动扫描 -- **过滤器**：支持按名称、地址、UUID 等条件过滤扫描结果 -- **回调通知**：通过回调函数异步返回扫描结果 - - -## 同步接口 - - -### bt_le_stop_scan - -```c -void bt_le_stop_scan(bt_instance_t* ins, bt_scanner_t* scanner); -``` - -停止 BLE 扫描。 - -**参数**： - -- `scanner` 扫描器实例。 -- `ins` 蓝牙客户端实例, 参见 bt_instance_t. - -**返回值**： - - - -### bt_le_scan_is_supported - -```c -bool bt_le_scan_is_supported(bt_instance_t* ins); -``` - -查询操作。 - -**参数**： - -- `ins` 蓝牙客户端实例。 - - -**返回值**： - -bt_le_scan_is_supported 操作。 - - -## 异步接口 - - -### bt_le_start_scan_async - -```c -bt_status_t bt_le_start_scan_async(bt_instance_t* ins, const scanner_callbacks_t* scan_cbs, bt_le_start_scan_cb_t cb, void* userdata); -``` - -开始BLE 扫描（异步版本）。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `scan_cbs` 扫描回调函数集合。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - - -### bt_le_start_scan_settings_async - -```c -bt_status_t bt_le_start_scan_settings_async(bt_instance_t* ins, ble_scan_settings_t* settings, const scanner_callbacks_t* scan_cbs, bt_le_start_scan_cb_t cb, void* userdata); -``` - -异步版本。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `settings` 设置。 -- `scan_cbs` 扫描回调函数集合。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - - - -### bt_le_start_scan_with_filters_async - -```c -bt_status_t bt_le_start_scan_with_filters_async(bt_instance_t* ins, ble_scan_settings_t* settings, ble_scan_filter_t* filter, const scanner_callbacks_t* scan_cbs, bt_le_start_scan_cb_t cb, void* userdata); -``` - -开始操作（异步版本）。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `settings` 设置。 -- `filter` 过滤条件。 -- `scan_cbs` 扫描回调函数集合。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - - -### bt_le_stop_scan_async - -```c -bt_status_t bt_le_stop_scan_async(bt_instance_t* ins, bt_scanner_t* scanner, bt_le_stop_scan_cb_t cb, void* userdata); -``` - -停止扫描（异步版本）。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `scanner` 扫描器实例。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - - - - -### bt_le_scan_is_supported_async - -```c -bt_status_t bt_le_scan_is_supported_async(bt_instance_t* ins, bt_bool_cb_t cb, void* userdata); -``` - -查询是否支持 BLE 扫描（异步版本）。 - -**参数**： - -- `ins` 蓝牙客户端实例。 -- `cb` 回调函数。 -- `userdata` 用户数据。 - diff --git a/zh-cn/api/framework/bluetooth/index.md b/zh-cn/api/framework/bluetooth/index.md index 88b7de24..6228c000 100644 --- a/zh-cn/api/framework/bluetooth/index.md +++ b/zh-cn/api/framework/bluetooth/index.md @@ -10,19 +10,14 @@ openvela 蓝牙框架提供完整的蓝牙协议栈接口，支持经典蓝牙 - **[GATT](bt_gatt.md)**（通用属性规范）— BLE 数据属性读写与通知 - **[设备管理](bt_device.md)** — 远程设备配对、连接、属性查询 -## BLE 接口 - -- **[BLE 扫描](bt_le_scan.md)** — BLE 设备发现与广播数据接收 -- **[BLE 广播](bt_le_advertiser.md)** — BLE 广播数据发送与管理 - -## 音频与媒体 +## 经典蓝牙规范 - **[A2DP](bt_a2dp.md)**（高级音频分发）— 高质量立体声音乐传输 -- **[AVRCP](bt_avrcp.md)**（音视频远程控制）— 播放控制、切歌、音量调节 - **[HFP](bt_hfp.md)**（免提规范）— 蓝牙通话功能 - -## 数据与外设 - - **[HID](bt_hid.md)**（人机接口设备）— 键盘、鼠标、游戏手柄 - **[SPP](bt_spp.md)**（串口仿真）— 数据透传 - **[PAN](bt_pan.md)**（个人局域网）— 网络共享与蓝牙组网 + +## 低功耗蓝牙规范 + +- **[CS](bt_cs.md)**（Channel Sounding）— 蓝牙信道探测测距与定位