@doubao-apps/ai 0.0.33 → 0.0.34

package/dist/skills/doubao-apps-dev/references/reference/open-api/14-/350/223/235/347/211/231.md

@@ -0,0 +1,598 @@
+# Open API: 蓝牙
+
+蓝牙和 BLE 能力；通常先打开适配器，再扫描、连接和读写。
+
+[返回目录](./README.md) | [返回速查](../open-api.md)
+
+## 速查
+
+| API | 说明 |
+| --- | --- |
+| [openBluetoothAdapter](#openbluetoothadapter) | 打开蓝牙适配器。 |
+| [startBluetoothDevicesDiscovery](#startbluetoothdevicesdiscovery) | 开始搜索附近的蓝牙设备。 |
+| [stopBluetoothDevicesDiscovery](#stopbluetoothdevicesdiscovery) | 停止搜索附近的蓝牙设备。 |
+| [getBluetoothAdapterState](#getbluetoothadapterstate) | 获取蓝牙适配器状态。 |
+| [getBluetoothDevices](#getbluetoothdevices) | 获取当前蓝牙模块发现的设备列表。 |
+| [getConnectedBluetoothDevices](#getconnectedbluetoothdevices) | 获取已连接的蓝牙设备列表。 |
+| [makeBluetoothPair](#makebluetoothpair) | 发起蓝牙配对。 |
+| [isBluetoothDevicePaired](#isbluetoothdevicepaired) | 查询蓝牙设备是否已经配对。 |
+| [closeBluetoothAdapter](#closebluetoothadapter) | 关闭蓝牙适配器。 |
+| [createBLEConnection](#createbleconnection) | 创建 BLE 连接。 |
+| [closeBLEConnection](#closebleconnection) | 关闭 BLE 连接。 |
+| [getBLEDeviceServices](#getbledeviceservices) | 获取 BLE 服务列表。 |
+| [getBLEDeviceCharacteristics](#getbledevicecharacteristics) | 获取 BLE 特征值列表。 |
+| [getBLEDeviceRSSI](#getbledevicerssi) | 获取 BLE 设备 RSSI。 |
+| [getBLEMTU](#getblemtu) | 获取 BLE MTU。 |
+| [notifyBLECharacteristicValueChange](#notifyblecharacteristicvaluechange) | 订阅 BLE 特征值变化。 |
+| [readBLECharacteristicValue](#readblecharacteristicvalue) | 读取 BLE 特征值。 |
+| [setBLEMTU](#setblemtu) | 设置 BLE MTU。 |
+| [writeBLECharacteristicValue](#writeblecharacteristicvalue) | 写入 BLE 特征值。 |
+
+## API 详情
+
+<a id="openbluetoothadapter"></a>
+### openBluetoothAdapter()
+
+打开蓝牙适配器。
+
+## 代码示例
+
+```typescript
+import { openBluetoothAdapter } from '@doubao-apps/framework/api';
+
+await openBluetoothAdapter({ mode: 'central' });
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|mode|`BluetoothAdapterMode`|否|蓝牙模式。|
+
+**类型说明**
+
+- `BluetoothAdapterMode`: `"central" | "peripheral"`
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="startbluetoothdevicesdiscovery"></a>
+### startBluetoothDevicesDiscovery()
+
+开始搜索附近的蓝牙设备。
+
+## 代码示例
+
+```typescript
+import { openBluetoothAdapter, startBluetoothDevicesDiscovery } from '@doubao-apps/framework/api';
+
+await openBluetoothAdapter();
+await startBluetoothDevicesDiscovery({ allowDuplicatesKey: false });
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|allowDuplicatesKey|`boolean`|否|是否允许重复上报同一设备。|
+|interval|`number`|否|上报设备的间隔，单位毫秒。|
+|powerLevel|`BluetoothPowerLevel`|否|扫描功耗等级。|
+|services|`string[]`|否|按主服务 UUID 过滤搜索范围。|
+
+**类型说明**
+
+- `BluetoothPowerLevel`: `"low" | "medium" | "high"`
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="stopbluetoothdevicesdiscovery"></a>
+### stopBluetoothDevicesDiscovery()
+
+停止搜索附近的蓝牙设备。
+
+## 代码示例
+
+```typescript
+import { stopBluetoothDevicesDiscovery } from '@doubao-apps/framework/api';
+
+await stopBluetoothDevicesDiscovery();
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="getbluetoothadapterstate"></a>
+### getBluetoothAdapterState()
+
+获取蓝牙适配器状态。
+
+## 代码示例
+
+```typescript
+import { getBluetoothAdapterState } from '@doubao-apps/framework/api';
+
+const { available, discovering } = await getBluetoothAdapterState();
+
+console.log(available, discovering);
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<GetBluetoothAdapterStateResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|available|`boolean`|蓝牙适配器是否可用。|
+|discovering|`boolean`|是否正在搜索蓝牙设备。|
+
+<a id="getbluetoothdevices"></a>
+### getBluetoothDevices()
+
+获取当前蓝牙模块发现的设备列表。
+
+## 代码示例
+
+```typescript
+import { getBluetoothDevices } from '@doubao-apps/framework/api';
+
+const { devices } = await getBluetoothDevices();
+
+console.log(devices.map((device) => device.name));
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<GetBluetoothDevicesResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|devices|`BluetoothDevice[]`|当前蓝牙模块已发现的设备列表。|
+|devices[].advertisingData|`ArrayBuffer`|广播二进制数据。|
+|devices[].advertisingServiceUuids|`string[]`|广播中的服务 UUID 列表。|
+|devices[].connectable|`boolean`|是否可连接。|
+|devices[].deviceId|`string`|设备 ID。|
+|devices[].localName|`string`|广播中的本地名称。|
+|devices[].name|`string`|设备名称。|
+|devices[].rssi|`number`|RSSI 信号强度，单位 dBm。|
+|devices[].serviceData|`Record<string, unknown>`|广播中的服务数据。|
+
+<a id="getconnectedbluetoothdevices"></a>
+### getConnectedBluetoothDevices()
+
+获取已连接的蓝牙设备列表。
+
+## 代码示例
+
+```typescript
+import { getConnectedBluetoothDevices } from '@doubao-apps/framework/api';
+
+const { devices } = await getConnectedBluetoothDevices({
+  services: ['0000180D-0000-1000-8000-00805F9B34FB']
+});
+
+console.log(devices);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|services|`string[]`|是|蓝牙主服务 UUID 列表。|
+
+## 返回值
+
+返回 `Promise<GetConnectedBluetoothDevicesResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|devices|`ConnectedBluetoothDevice[]`|已连接设备列表。|
+|devices[].deviceId|`string`|设备 ID。|
+|devices[].name|`string`|设备名称。|
+
+<a id="makebluetoothpair"></a>
+### makeBluetoothPair()
+
+发起蓝牙配对。
+
+## 代码示例
+
+```typescript
+import { makeBluetoothPair } from '@doubao-apps/framework/api';
+
+await makeBluetoothPair({
+  deviceId: 'device-id',
+  pin: '000000',
+  timeout: 10000
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|pin|`string`|是|配对 PIN 码。|
+|timeout|`number`|否|超时时间，单位毫秒。|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="isbluetoothdevicepaired"></a>
+### isBluetoothDevicePaired()
+
+查询蓝牙设备是否已经配对。
+
+## 代码示例
+
+```typescript
+import { isBluetoothDevicePaired } from '@doubao-apps/framework/api';
+
+await isBluetoothDevicePaired({ deviceId: 'device-id' });
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="closebluetoothadapter"></a>
+### closeBluetoothAdapter()
+
+关闭蓝牙适配器。
+
+## 代码示例
+
+```typescript
+import { closeBluetoothAdapter } from '@doubao-apps/framework/api';
+
+await closeBluetoothAdapter();
+```
+
+## 入参
+
+无入参。
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="createbleconnection"></a>
+### createBLEConnection()
+
+创建 BLE 连接。
+
+## 代码示例
+
+```typescript
+import { createBLEConnection } from '@doubao-apps/framework/api';
+
+await createBLEConnection({
+  deviceId: 'device-id',
+  timeout: 10000
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|timeout|`number`|否|超时时间，单位毫秒。|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="closebleconnection"></a>
+### closeBLEConnection()
+
+关闭 BLE 连接。
+
+## 代码示例
+
+```typescript
+import { closeBLEConnection } from '@doubao-apps/framework/api';
+
+await closeBLEConnection({ deviceId: 'device-id' });
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="getbledeviceservices"></a>
+### getBLEDeviceServices()
+
+获取 BLE 服务列表。
+
+## 代码示例
+
+```typescript
+import { getBLEDeviceServices } from '@doubao-apps/framework/api';
+
+const { services } = await getBLEDeviceServices({ deviceId: 'device-id' });
+
+console.log(services);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+
+## 返回值
+
+返回 `Promise<GetBLEDeviceServicesResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|services|`BluetoothService[]`|设备服务列表。|
+|services[].isPrimary|`boolean`|是否为主服务。|
+|services[].uuid|`string`|服务 UUID。|
+
+<a id="getbledevicecharacteristics"></a>
+### getBLEDeviceCharacteristics()
+
+获取 BLE 特征值列表。
+
+## 代码示例
+
+```typescript
+import { getBLEDeviceCharacteristics } from '@doubao-apps/framework/api';
+
+const { characteristics } = await getBLEDeviceCharacteristics({
+  deviceId: 'device-id',
+  serviceId: 'service-id'
+});
+
+console.log(characteristics);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|serviceId|`string`|是|服务 ID。|
+
+## 返回值
+
+返回 `Promise<GetBLEDeviceCharacteristicsResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|characteristics|`BluetoothCharacteristic[]`|特征值列表。|
+|characteristics[].properties|`BluetoothCharacteristicProperties`|特征值能力。|
+|characteristics[].properties.indicate|`boolean`|是否支持 indicate。|
+|characteristics[].properties.notify|`boolean`|是否支持 notify。|
+|characteristics[].properties.read|`boolean`|是否支持 read。|
+|characteristics[].properties.write|`boolean`|是否支持 write。|
+|characteristics[].properties.writeDefault|`boolean`|是否支持带响应写入。|
+|characteristics[].properties.writeNoResponse|`boolean`|是否支持无响应写入。|
+|characteristics[].uuid|`string`|特征值 UUID。|
+
+<a id="getbledevicerssi"></a>
+### getBLEDeviceRSSI()
+
+获取 BLE 设备 RSSI。
+
+## 代码示例
+
+```typescript
+import { getBLEDeviceRSSI } from '@doubao-apps/framework/api';
+
+const { rssi } = await getBLEDeviceRSSI({ deviceId: 'device-id' });
+
+console.log(rssi);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+
+## 返回值
+
+返回 `Promise<GetBLEDeviceRSSIResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|rssi|`number`|RSSI 信号强度，单位 dBm。|
+
+<a id="getblemtu"></a>
+### getBLEMTU()
+
+获取 BLE MTU。
+
+## 代码示例
+
+```typescript
+import { getBLEMTU } from '@doubao-apps/framework/api';
+
+const { mtu } = await getBLEMTU({ deviceId: 'device-id' });
+
+console.log(mtu);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|writeType|`BluetoothWriteType`|否|写入模式。|
+
+**类型说明**
+
+- `BluetoothWriteType`: `"write" | "writeNoResponse"`
+
+## 返回值
+
+返回 `Promise<GetBLEMTUResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|mtu|`number`|当前 MTU。|
+
+<a id="notifyblecharacteristicvaluechange"></a>
+### notifyBLECharacteristicValueChange()
+
+订阅 BLE 特征值变化。
+
+## 代码示例
+
+```typescript
+import { notifyBLECharacteristicValueChange } from '@doubao-apps/framework/api';
+
+await notifyBLECharacteristicValueChange({
+  deviceId: 'device-id',
+  serviceId: 'service-id',
+  characteristicId: 'characteristic-id',
+  state: true
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|characteristicId|`string`|是|特征值 ID。|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|serviceId|`string`|是|服务 ID。|
+|state|`boolean`|是|是否启用订阅。|
+|type|`BluetoothNotifyType`|否|订阅类型。|
+
+**类型说明**
+
+- `BluetoothNotifyType`: `"notification" | "indication"`
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="readblecharacteristicvalue"></a>
+### readBLECharacteristicValue()
+
+读取 BLE 特征值。
+
+## 代码示例
+
+```typescript
+import { readBLECharacteristicValue } from '@doubao-apps/framework/api';
+
+await readBLECharacteristicValue({
+  deviceId: 'device-id',
+  serviceId: 'service-id',
+  characteristicId: 'characteristic-id'
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|characteristicId|`string`|是|特征值 ID。|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|serviceId|`string`|是|服务 ID。|
+
+## 返回值
+
+返回 `Promise<object>`。
+
+<a id="setblemtu"></a>
+### setBLEMTU()
+
+设置 BLE MTU。
+
+## 代码示例
+
+```typescript
+import { setBLEMTU } from '@doubao-apps/framework/api';
+
+const { mtu } = await setBLEMTU({
+  deviceId: 'device-id',
+  mtu: 512
+});
+
+console.log(mtu);
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|mtu|`number`|是|目标 MTU。|
+
+## 返回值
+
+返回 `Promise<SetBLEMTUResult>`。
+
+|字段名|类型|说明|
+|---|---|---|
+|mtu|`string \| number`|最终协商得到的 MTU。|
+
+<a id="writeblecharacteristicvalue"></a>
+### writeBLECharacteristicValue()
+
+写入 BLE 特征值。
+
+## 代码示例
+
+```typescript
+import { writeBLECharacteristicValue } from '@doubao-apps/framework/api';
+
+await writeBLECharacteristicValue({
+  deviceId: 'device-id',
+  serviceId: 'service-id',
+  characteristicId: 'characteristic-id',
+  value: new Uint8Array([1, 2, 3]).buffer
+});
+```
+
+## 入参
+
+|参数名|类型|必填|说明|
+|---|---|---|---|
+|characteristicId|`string`|是|特征值 ID。|
+|deviceId|`string`|是|蓝牙设备 ID。|
+|serviceId|`string`|是|服务 ID。|
+|value|`ArrayBuffer`|是|要写入的二进制数据。|
+|writeType|`BluetoothWriteType`|否|写入模式。|
+
+**类型说明**
+
+- `BluetoothWriteType`: `"write" | "writeNoResponse"`
+
+## 返回值
+
+返回 `Promise<object>`。