diff --git a/docs/API_reference/en/btlib/ble.md b/docs/API_reference/en/btlib/ble.md index 55b0705aae9127ee09117908e45e1b664c67463a..ceff1ad7def3730854f8cb3ba304a8c126623e05 100644 --- a/docs/API_reference/en/btlib/ble.md +++ b/docs/API_reference/en/btlib/ble.md @@ -1381,6 +1381,8 @@ Initializes BLE Server and registers a callback function. | 21 | 7 | args[0]: event_id. BLE server. When the BLE client writes a characteristic value or descriptor, the server gets the notice.
args[1]: status. The operation status. 0 - successful operation; other values - failed operation.
args[2]: data_len. The length of the data to be got.
args[3]: data. An array that stores the data got.
args[4]: attr_handle. Integer type. Attribute handle.
args[5]: short_uuid. Integer type.
args[6]: long_uuid. A 16-byte array that stores long UUID. | | 22 | 7 | args[0]: event_id. When the BLE client reads a characteristic value or descriptor, the server gets the notice.
args[1]: status. The operation status. 0 - successful operation; other values - failed operation.
args[2]: data_len. The length of the data to be got.
args[3]: data. An array that stores the got data.
args[4]: attr_handle. Integer type, attribute handle.
args[5]: short_uuid. Integer type.
args[6]: long_uuid. A 16-byte array that stores long UUID. | | 25 | 2 | args[0]: event_id. Server sends notification, and receives notice sent by the peer end.
args[1]: status. The operation status. 0 - successful operation; other values - failed operation. | +| 63 | 2 | args[0] ：event_id. Completion of the SMP pairing process notification.
args[1] ：status. The operation status. 0 - successful operation; other values - failed operation. | +| 64 | 5 | args[0] ：event_id. user confirmation of the SMP pairing notification.
args[1] ：status. The operation status. 0 - successful operation; other values - failed operation.
args[2] ：connect_id
args[3] ：pair_mode. Pairing mode, Integer type. 0 - pairing failure, 1 - legacy paring: just work, no PIN code is required, 2 - legacy paring: passkey entry output, display PIN code, not need to enter the PIN code, 3 - legacy paring: passkey entry input, need to enter the PIN code, 4 - legacy paring: OOB, not support, 5 - secure connection paring: just work, no PIN code is required, 6 - secure connection paring: number comparison, display PIN code, not need to enter the PIN code, 7 - secure connection paring: passkey entry output, display PIN code, not need to enter the PIN code, 8 - secure connection paring: passkey entry input, need to enter the PIN code, 9 - secure connection paring: OOB, not support
args[4] ：pin_code, PIN code, Integer type. | **Return Value：** @@ -1993,6 +1995,8 @@ Initializes BLE Client and registers a callback function. | 35 | 2 | args[0]: event_id. Writes characteristic descriptor.
args[1]: status. The operation status. 0 - successful operation; other values - failed operation. | | 36 | 4 | args[0]: event_id. Reads characteristic descriptor.
args[1]: status. The operation status. 0 - successful operation; other values - failed operation.
args[2]: data_len. Data length.
args[3]: data. Raw data. | | 37 | 3 | args[0]: event_id. Attribute error.
args[1]: status. The operation status. 0 - successful operation; other values - failed operation.
args[2]: errcode. Error code. | +| 63 | 2 | args[0] ：event_id. Completion of the SMP pairing process notification.
args[1] ：status. The operation status. 0 - successful operation; other values - failed operation. | +| 64 | 5 | args[0] ：event_id. user confirmation of the SMP pairing notification.
args[1] ：status. The operation status. 0 - successful operation; other values - failed operation.
args[2] ：connect_id
args[3] ：pair_mode. Pairing mode, Integer type. 0 - pairing failure, 1 - legacy paring: just work, no PIN code is required, 2 - legacy paring: passkey entry output, display PIN code, not need to enter the PIN code, 3 - legacy paring: passkey entry input, need to enter the PIN code, 4 - legacy paring: OOB, not support, 5 - secure connection paring: just work, no PIN code is required, 6 - secure connection paring: number comparison, display PIN code, not need to enter the PIN code, 7 - secure connection paring: passkey entry output, display PIN code, not need to enter the PIN code, 8 - secure connection paring: passkey entry input, need to enter the PIN code, 9 - secure connection paring: OOB, not support
args[4] ：pin_code, PIN code, Integer type. | **Return Value：** @@ -2326,3 +2330,224 @@ Writes the characteristic description. - `0`- Successful execution; `-1`- Failed execution. +## BLE SMP Related Features + +### `ble.smpSetConfig` + +```python +ble.smpSetConfig(io_cap, auth_req, passkey, timeout) +``` + +config the pairing capabilities. + +**Parameter：** + +- `io_cap`-Integer type. Device input and output capabilities. 0 - Only display ability, can display PIN code, 1 - Only display ability, can only display Yes/No, can not display PIN code, 2 - Only input ability, can enter PIN code, 3 - No input-output capability, 4 - Have input-output capability, can display PIN code and can enter PIN code. Default value: 3. +- `auth_req`-Integer type. Authentication request parameters. Default value: 9. + +| | Bit0 | Bit1 | Bit2 | Bit3 | +| ---- | ----------------------- | -------- | --------------- | ----------------------------- | +| 0 | not bound after pairing | reserved | not enable MITM | use legacy paring | +| 1 | bound after pairing | reserved | enable MITM | use secure connection pairing | + +- `passkey`-Integer type. The PIN code displayed during the pairing process. Default value: 123456. +- `timeout`-Integer type. Pairing timeout time, the unit is 100ms. Default value: 160. + +**Return Value：** + +`0`- Successful execution; `-1`- Failed execution. + +### `ble.smpGetConfig` + +```python +ble.smpSetConfig(io_cap, auth_req, passkey, timeout) +``` + +query the pairing capabilities. + +**Return Value：** + +`-1`- Failed execution; returns the following value when successful execution. + +- `io_cap`-Integer type. Device input and output capabilities. 0 - Only display ability, can display PIN code, 1 - Only display ability, can only display Yes/No, can not display PIN code, 2 - Only input ability, can enter PIN code, 3 - No input-output capability, 4 - Have input-output capability, can display PIN code and can enter PIN code. Default value: 3. +- `auth_req`-Integer type. Authentication request parameters. Default value: 9. + +| | Bit0 | Bit1 | Bit2 | Bit3 | +| ---- | ----------------------- | -------- | --------------- | ----------------------------- | +| 0 | not bound after pairing | reserved | not enable MITM | use legacy paring | +| 1 | bound after pairing | reserved | enable MITM | use secure connection pairing | + +- `passkey`-Integer type. The PIN code displayed during the pairing process. Default value: 123456. +- `timeout`-Integer type. Pairing timeout time, the unit is 100ms. Default value: 160. + +The mapping table of pairing capabilities and pairing methods is as follows: + +legacy paring + +| | **Initiator** | | | | | +| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------ | +| ***Responder*** | DisplayOnly | DisplayYesNo | KeyboardOnly | NoInputNoOutput | KeyboardDisplay | +| DisplayOnly | Just Works +Unauthenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | +| DisplayYesNo | Just Works +Unauthenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | +| KeyboardOnly | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator and +responder inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | +| NoInputNoOutput | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works Unauthenticated | +| KeyboardDisplay | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | + +secure connection paring + +| | **Initiator** | | | | | +| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------ | +| ***Responder*** | DisplayOnly | DisplayYesNo | KeyboardOnly | NoInputNoOutput | KeyboardDisplay | +| DisplayOnly | Just Works +Unauthenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | +| DisplayYesNo | Just Works +Unauthenticated | Numeric Comparison +Authenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Numeric Comparison +Authenticated | +| KeyboardOnly | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator and +responder inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | +| NoInputNoOutput | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works Unauthenticated | +| KeyboardDisplay | Passkey Entry: initiator displays, +responder inputs +Authenticated | Numeric Comparison +Authenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Numeric Comparison +Authenticated | + +### `ble.smpStartPair` + +```python +ble.smpStartPair(connect_id) +``` + +Start the BLE SMP pairing process. SMP pairing is initiated by the client, and the server can notify the client to initiate SMP pairing requests. + +**Parameter：** + +- `connect_id`- Integer type. The connection ID obtained when the connection was established. + +**Return Value：** + +`0`- Successful execution; `-1`- Failed execution. + +### `ble.smpUserConfirm` + +```python +ble.smpUserConfirm(connect_id, pair_type, pin) +``` + +Confirm pairing. Whether to accept the pairing request. + +**Parameter：** + +- `connect_id`-Integer type. The connection ID obtained when the connection was established. +- `pair_operation`-Integer type. The operation type of the pairing. 0 - cancel pairing, 1 - accept pairing, not carry a PIN code(used in Just Work or Number Comparison mode), 2 - accept pairing, carry a PIN code(used in Passkey mode). +- `pin`- Integer type. PIN code. + +**Return Value：** + +`0`- Successful execution; `-1`- Failed execution. + +### `ble.smpGetPairedDevInfo` + +```python +ble.smpGetPairedDevInfo() +``` + +Get paired device information. + +**Return Value：** + +`0`- Successful execution; `-1`- Failed execution. + +- `addr_list`- List type, the list element is bytearray type. List of BLE addresses of paired devices. + +### `ble.smpRemovePairedDev` + +```python +ble.smpRemovePairedDev(addr) +``` + +Delete the specified paired device information. + +**Parameter：** + +- `addr`- bytearray type. BLE address of the device to be deleted. (size: 6 bytes) + +**Return Value：** + +`0`- Successful execution; `-1`- Failed execution. + +### `ble.smpCleanPairedDev` + +```python +ble.smpCleanPairedDev() +``` + +Delete all paired device information. + +**Return Value：** + +`0`- Successful execution; `-1`- Failed execution. + +> **Note**: The above BLE SMP-related interfaces must be executed with the BLE already initialized, otherwise they will return a failure. And BLE SMP functionality is currently only supported in EC200UEUAA model specific firmware. + diff --git a/docs/API_reference/zh/btlib/ble.md b/docs/API_reference/zh/btlib/ble.md index 8f31a2603ffbd33c43a80f8037895984b2967d2b..6ee63e3a947e6ae83f523700ba3f0b411bfe4e81 100644 --- a/docs/API_reference/zh/btlib/ble.md +++ b/docs/API_reference/zh/btlib/ble.md @@ -102,6 +102,8 @@ ble.serverInit(user_cb) | 21 | 7 | args[0] ：event_id，表示 client写入特征值或描述符通知
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：data_len，获取数据的长度
args[3] ：data，一个数组，存放获取的数据
args[4] ：attr_handle，属性句柄，整型值
args[5] ：short_uuid，整型值
args[6] ：long_uuid，一个16字节数组，存放长UUID | | 22 | 7 | args[0] ：event_id，表示client读取特征值或描述符通知
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：data_len，获取数据的长度
args[3] ：data，一个数组，存放获取的数据
args[4] ：attr_handle，属性句柄，整型值
args[5] ：short_uuid，整型值
args[6] ：long_uuid，一个16字节数组，存放长UUID | | 25 | 2 | args[0] ：event_id，表示 server发送通知并接收到了发送结束通知
args[1] ：status，表示操作的状态，0-成功，非0-失败 | +| 63 | 2 | args[0] ：event_id，表示SMP配对流程完成通知
args[1] ：status，表示操作的状态，0-成功，非0-失败 | +| 64 | 5 | args[0] ：event_id，表示SMP配对用户确认通知
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：connect_id
args[3] ：pair_mode，配对模式，整型值。0-配对失败，1-legacy paring:使用just work，不需要输入PIN码，2-legacy paring:使用passkey entry，显示PIN码，不需要输入PIN码，3-legacy paring:使用passkey entry，需要输入PIN码，4-legacy paring:使用OOB，不支持，5-secure connection paring:使用just work，不需要输入PIN码，6-secure connection paring:使用number comparison，显示PIN码，不需要输入PIN码，7-secure connection paring:使用passkey entry，显示PIN码，不需要输入PIN码，8-secure connection paring:使用passkey。需要输入PIN码，9-secure connection paring:使用OOB，不支持
args[4] ：pin_code，PIN码，整型值 | **返回值描述：** @@ -715,6 +717,8 @@ ble.clientInit(user_cb) | 35 | 2 | args[0] ：event_id，表示 写入特征描述，需server端确认
args[1] ：status，表示操作的状态，0-成功，非0-失败 | | 36 | 4 | args[0] ：event_id，表示读特征描述
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：data_len，数据长度
args[3] ：data，原始数据 | | 37 | 3 | args[0] ：event_id，表示属性错误
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：errcode，错误码 | +| 63 | 2 | args[0] ：event_id，表示SMP配对流程完成通知
args[1] ：status，表示操作的状态，0-成功，非0-失败 | +| 64 | 5 | args[0] ：event_id，表示SMP配对用户确认通知
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：connect_id
args[3] ：pair_mode，配对模式，整型值。0-配对失败，1-legecy paring:使用just work，不需要输入PIN码，2-legecy paring:使用passkey entry，显示PIN码，不需要输入PIN码，3-legecy paring:使用passkey entry，需要输入PIN码，4-legecy paring:使用OOB，不支持，5-secure connection paring:使用just work，不需要输入PIN码，6-secure connection paring:使用number compairison，显示PIN码，不需要输入PIN码，7-secure connection paring:使用passkey entry，显示PIN码，不需要输入PIN码，8-secure connection paring:使用passkey。需要输入PIN码，9-secure connection paring:使用OOB，不支持
args[4] ：pin_code，PIN码，整型值 | **返回值描述：** @@ -1048,4 +1052,225 @@ ble.writeCharaDesc(connect_id, handle, data) **返回值描述：** -执行成功返回整型0，失败返回整型-1。 \ No newline at end of file +执行成功返回整型0，失败返回整型-1。 + +## BLE SMP相关功能 + +### `ble.smpSetConfig` + +```python +ble.smpSetConfig(io_cap, auth_req, passkey, timeout) +``` + +配对能力配置。 + +**参数描述：** + +- `io_cap`-设备输入输出能力，类型为整型，默认为3。0 - 只有显示能力，可以显示PIN码，1 - 只有显示能力，只能显示Yes/No，不能显示PIN码，2 -只有输入能力，可以输入PIN码，3 - 没有输入输出能力，4 - 有输入输出能力，既可以显示PIN码，又可以输入PIN码。 +- `auth_req`-认证请求参数，类型为整型，默认为9。 + +| | Bit0 | Bit1 | Bit2 | Bit3 | +| ---- | ------------ | ---------------- | ---------- | ------------------------------ | +| 0 | 配对后不绑定 | 预留，无实际含义 | 不启用MITM | 使用Legacy Paring | +| 1 | 配对后绑定 | 预留，无实际含义 | 启用MITM | 使用Secure Connections Pairing | + +- `passkey`-配对显示的PIN码，类型为整型，默认为123456。 +- `timeout`-配对超时时间，单位为100ms，类型为整型，默认为160。 + +**返回值描述：** + +执行成功返回整型0，失败返回整型-1。 + +### `ble.smpGetConfig` + +```python +ble.smpSetConfig(io_cap, auth_req, passkey, timeout) +``` + +配对能力查询。 + +**返回值描述：** + +执行成功返回值如下，失败返回整型-1。 + +- `io_cap`-设备输入输出能力，类型为整型，默认为3。0 - 只有显示能力，可以显示PIN码，1 - 只有显示能力，只能显示Yes/No，不能显示PIN码，2 -只有输入能力，可以输入PIN码，3 - 没有输入输出能力，4 - 有输入输出能力，既可以显示PIN码，又可以输入PIN码。 +- `auth_req`-认证请求参数，类型为整型，默认为9。 + +| | Bit0 | Bit1 | Bit2 | Bit3 | +| ---- | ------------ | ---------------- | ---------- | ------------------------------ | +| 0 | 配对后不绑定 | 预留，无实际含义 | 不启用MITM | 使用Legacy Paring | +| 1 | 配对后绑定 | 预留，无实际含义 | 启用MITM | 使用Secure Connections Pairing | + +- `passkey`-配对显示的PIN码，类型为整型，默认为123456。 +- `timeout`-配对超时时间，单位为100ms，类型为整型，默认为160。 + +配对能力和配对方法对应表如下： + +legacy paring + +| | **Initiator** | | | | | +| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------ | +| ***Responder*** | DisplayOnly | DisplayYesNo | KeyboardOnly | NoInputNoOutput | KeyboardDisplay | +| DisplayOnly | Just Works +Unauthenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | +| DisplayYesNo | Just Works +Unauthenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | +| KeyboardOnly | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator and +responder inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | +| NoInputNoOutput | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works Unauthenticated | +| KeyboardDisplay | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | + +secure connection paring + +| | **Initiator** | | | | | +| --------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------ | +| ***Responder*** | DisplayOnly | DisplayYesNo | KeyboardOnly | NoInputNoOutput | KeyboardDisplay | +| DisplayOnly | Just Works +Unauthenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | +| DisplayYesNo | Just Works +Unauthenticated | Numeric Comparison +Authenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Numeric Comparison +Authenticated | +| KeyboardOnly | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | Passkey Entry: initiator and +responder inputs +Authenticated | Just Works +Unauthenticated | Passkey Entry: initiator displays, +responder inputs +Authenticated | +| NoInputNoOutput | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works +Unauthenticated | Just Works Unauthenticated | +| KeyboardDisplay | Passkey Entry: initiator displays, +responder inputs +Authenticated | Numeric Comparison +Authenticated | Passkey Entry: +responder displays, initiator inputs +Authenticated | Just Works +Unauthenticated | Numeric Comparison +Authenticated | + +### `ble.smpStartPair` + +```python +ble.smpStartPair(connect_id) +``` + +开始BLE SMP配对流程。SMP配对由client发起，server可以通知client发起SMP配对请求。 + +**参数描述：** + +- `connect_id`-连接ID，建立连接时得到的连接ID，类型为整型。 + +**返回值描述：** + +执行成功返回整型0，失败返回整型-1。 + +### `ble.smpUserConfirm` + +```python +ble.smpUserConfirm(connect_id, pair_type, pin) +``` + +确认配对。收到配对请求后确认是否接受配对。 + +**参数描述：** + +- `connect_id`-连接ID，建立连接时得到的连接ID，类型为整型。 +- `pair_operation`-配对的操作类型，类型为整型。0 - 取消配对，1 - 确认配对，不携带PIN码（用于Just Work或者Number Comparison模式），2 -确认配对，携带PIN码（用于Passkey模式）。 +- `pin`-PIN码，类型为整型。 + +**返回值描述：** + +执行成功返回整型0，失败返回整型-1。 + +### `ble.smpGetPairedDevInfo` + +```python +ble.smpGetPairedDevInfo() +``` + +获取已配对设备信息。 + +**返回值描述：** + +执行成功返回值如下，失败返回整型-1。 + +- `addr_list`-已配对设备的BLE地址列表，类型为list，list成员为bytearray类型的BLE地址。 + +### `ble.smpRemovePairedDev` + +```python +ble.smpRemovePairedDev(addr) +``` + +删除指定的已配对设备信息。 + +**参数描述：** + +- `addr`-待删除的设备BLE地址，类型为bytearray，大小为6字节。 + +**返回值描述：** + +执行成功返回整型0，失败返回整型-1。 + +### `ble.smpCleanPairedDev` + +```python +ble.smpCleanPairedDev() +``` + +删除所有已配对设备信息。 + +**返回值描述：** + +执行成功返回整型0，失败返回整型-1。 + +> 注意：以上BLE SMP相关接口均需要在BLE已经初始化的情况下执行，否则会返回失败。当前仅EC200UEUAA型号特定固件支持BLE SMP功能。 \ No newline at end of file