diff --git a/docs/API_reference/en/btlib/ble.md b/docs/API_reference/en/btlib/ble.md index ceff1ad7def3730854f8cb3ba304a8c126623e05..7187345e6673ec01abc0b1c286ff6280e75ed432 100644 --- a/docs/API_reference/en/btlib/ble.md +++ b/docs/API_reference/en/btlib/ble.md @@ -1382,7 +1382,7 @@ Initializes BLE Server and registers a callback function. | 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. | +| 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 Pairing: Just Works, no PIN code is required.
2 - Legacy Pairing: Passkey Entry output, display PIN code, not need to enter the PIN code.
3 - Legacy Pairing: Passkey Entry input, need to enter the PIN code.
4 - Legacy Pairing: OOB, not support.
5 - Secure Connections Pairing: Just Works, no PIN code is required.
6 - Secure Connections Pairing: Numeric Comparison,display PIN code, not need to enter the PIN code.
7 - Secure Connections Pairing: Passkey Entry output, display PIN code, not need to enter the PIN code.
8 - Secure Connections Pairing: Passkey Entry input, need to enter the PIN code.
9 - Secure Connections Pairing: OOB, not support.
args[4] ：pin_code. PIN code, Integer type. | **Return Value：** @@ -1996,7 +1996,7 @@ Initializes BLE Client and registers a callback function. | 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. | +| 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 Pairing: Just Works, no PIN code is required.
2 - Legacy Pairing: Passkey Entry output, display PIN code, not need to enter the PIN code.
3 - Legacy Pairing: Passkey Entry input, need to enter the PIN code.
4 - Legacy Pairing: OOB, not support.
5 - Secure Connections Pairing: Just Works, no PIN code is required.
6 - Secure Connections Pairing: Numeric Comparison,display PIN code, not need to enter the PIN code.
7 - Secure Connections Pairing: Passkey Entry output, display PIN code, not need to enter the PIN code.
8 - Secure Connections Pairing: Passkey Entry input, need to enter the PIN code.
9 - Secure Connections Pairing: OOB, not support.
args[4] ：pin_code. PIN code, Integer type. | **Return Value：** @@ -2330,9 +2330,28 @@ Writes the characteristic description. - `0`- Successful execution; `-1`- Failed execution. +### ble.exchangeMtu + +```python +ble.exchangeMtu(connect_id, mtu_size) +``` + +Send MTU exchange request. The MTU exchange request should be initiated by the client. + +**Parameter:** + +- `connect_id`-Integer type. The connection ID obtained when the connection was established. +- `mtu_size`-MTU size。 + +**Return Value:** + +* `0`- Successful execution; `-1`- Failed execution. + + + ## BLE SMP Related Features -### `ble.smpSetConfig` +### ble.smpSetConfig ```python ble.smpSetConfig(io_cap, auth_req, passkey, timeout) @@ -2342,12 +2361,21 @@ 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. +* `io_cap`-Integer type. Device input and output capabilities. Default value is 3. + +| Value | Description | +| ----- | ------------------------------------------------------------ | +| 0 | Device has the ability to display a 6 digit decimal number. | +| 1 | Device only has the ability to display Yes/No, cant not display PIN. | +| 2 | Device only has the ability to input PIN. | +| 3 | Device has no input or output capabilities. | +| 4 | Device has input or output capabilities, can display PIN and enter PIN. | + - `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 | +| 0 | not bound after pairing | reserved | not enable MITM | use legacy pairing | | 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. @@ -2355,12 +2383,36 @@ config the pairing capabilities. **Return Value：** -`0`- Successful execution; `-1`- Failed execution. +* `0`- Successful execution; `-1`- Failed execution. + +**Pairing method selection instructions:** + +BLE smp pairing has two modes: `Legacy Pairing` and `Secure Connections Pairing`. There are specifically the following 4 pairing methods: -### `ble.smpGetConfig` +* OOB + +* Just Works + +* Passkey Entry + +* Numeric Comparison (For LE Secure Connections Pairing) + +The specific pairing method to choose is decided by the two parties after exchanging their respective IO capabilities. It is basically divided into the following stages: + +Stage 1: The pairing parties will first confirm whether to use `Legacy Pairing` or `Secure Connections Pairing` mode for pairing. The principle is: only if both parties set the `Secure Connections Pairing` flag, this pairing mode will be used, otherwise` Legacy Pairing`. + +Stage 2: Determine whether OOB is supported. For the `Legacy Pairing` mode, the OOB method will be used only if both parties support OOB. For `Secure Connections Pairing` mode, if `Initiator` supports OOB, use OOB mode. + +Stage 3: Check MITM (Man-in-the-Middle). If neither party is configured with the MITM flag, the `Just Works` method is used to pair directly. Otherwise, the pairing method is selected based on the IO capabilities of both parties. + +Stage 4: Choose the pairing method based on the IO capabilities of both parties. + +For specific instructions on Stage 2 ~ Stage 4, please refer to the content of Chapter ***2.3.5.1 Selecting Key Generation Method*** in the official Bluetooth manual document "**BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part H]**". + +### ble.smpGetConfig ```python -ble.smpSetConfig(io_cap, auth_req, passkey, timeout) +ble.smpGetConfig(io_cap, auth_req, passkey, timeout) ``` query the pairing capabilities. @@ -2369,111 +2421,27 @@ query the pairing capabilities. `-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. +* `io_cap`-Integer type. Device input and output capabilities. Default value is 3. + +| Value | Description | +| ----- | ------------------------------------------------------------ | +| 0 | Device has the ability to display a 6 digit decimal number. | +| 1 | Device only has the ability to display Yes/No, cant not display PIN. | +| 2 | Device only has the ability to input PIN. | +| 3 | Device has no input or output capabilities. | +| 4 | Device has input or output capabilities, can display PIN and enter PIN. | + - `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 | +| 0 | not bound after pairing | reserved | not enable MITM | use legacy pairing | | 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` +### ble.smpStartPair ```python ble.smpStartPair(connect_id) @@ -2489,25 +2457,33 @@ Start the BLE SMP pairing process. SMP pairing is initiated by the client, and t `0`- Successful execution; `-1`- Failed execution. -### `ble.smpUserConfirm` +### ble.smpUserConfirm ```python -ble.smpUserConfirm(connect_id, pair_type, pin) +ble.smpUserConfirm(connect_id, pair_operation, 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). +* `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). + +| Value | Description | +| ----- | ------------------------------------------------------------ | +| 0 | Cancel pairing, This operation is only possible during pairing, and it will cause the Bluetooth connection to be lost. | +| 1 | Accept pairing, not carry a PIN code(used in Just Works or Numeric 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` +### ble.smpGetPairedDevInfo ```python ble.smpGetPairedDevInfo() @@ -2521,7 +2497,7 @@ Get paired device information. - `addr_list`- List type, the list element is bytearray type. List of BLE addresses of paired devices. -### `ble.smpRemovePairedDev` +### ble.smpRemovePairedDev ```python ble.smpRemovePairedDev(addr) @@ -2537,7 +2513,7 @@ Delete the specified paired device information. `0`- Successful execution; `-1`- Failed execution. -### `ble.smpCleanPairedDev` +### ble.smpCleanPairedDev ```python ble.smpCleanPairedDev() diff --git a/docs/API_reference/zh/btlib/ble.md b/docs/API_reference/zh/btlib/ble.md index 6ee63e3a947e6ae83f523700ba3f0b411bfe4e81..3ce55911f2ac165eab4dd640ab7a90024df85f77 100644 --- a/docs/API_reference/zh/btlib/ble.md +++ b/docs/API_reference/zh/btlib/ble.md @@ -103,7 +103,7 @@ ble.serverInit(user_cb) | 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码，整型值 | +| 64 | 5 | args[0] ：event_id，表示SMP配对用户确认通知
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：connect_id
args[3] ：pair_mode，配对模式，整型值。
0 - 配对失败
1 - Legacy Pairing：使用Just Works，不需要输入PIN码
2 - Legacy Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码
3 - Legacy Pairing：使用Passkey Entry，需要输入PIN码
4 - Legacy Pairing：使用OOB，目前不支持这种方式
5 - Secure Connections Pairing：使用Just Works，不需要输入PIN码
6 - Secure Connections Pairing：使用Numeric Comparison，显示PIN码，不需要输入PIN码
7 - Secure Connections Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码
8 - Secure Connections Pairing：使用Passkey Entry，需要输入PIN码
9 - Secure Connections Pairing：使用OOB，目前不支持这种方式
args[4] ：pin_code，PIN码，整型值 | **返回值描述：** @@ -273,7 +273,7 @@ ble.setAdvParam(min_adv,max_adv,adv_type,addr_type,channel,filter_policy,discov_ - `filter_policy`-广播过滤策略，0 - 处理所有设备的扫描和连接请求，1 - 处理所有设备的连接请求和只处理白名单设备的扫描请求（暂不支持），2 - 处理所有设备的扫描请求和只处理白名单设备的连接请求（暂不支持），3 - 只处理白名单设备的连接和扫描请求（暂不支持）。类型为整型。 - `discov_mode`-发现模式，GAP协议使用，1 - 有限可发现模式，2 - 一般可发现模式。类型为整型。 - `no_br_edr`-不用BR/EDR，1-不用BR/EDR，默认为该值，0-使用BR/EDR。类型为整型。 -- enable_adv-使能广播，1-使能，默认为该值，0-不使能。类型为整型。 +- `enable_adv`-使能广播，1-使能，默认为该值，0-不使能。类型为整型。 **返回值描述：** @@ -718,7 +718,7 @@ ble.clientInit(user_cb) | 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码，整型值 | +| 64 | 5 | args[0] ：event_id，表示SMP配对用户确认通知
args[1] ：status，表示操作的状态，0-成功，非0-失败
args[2] ：connect_id
args[3] ：pair_mode，配对模式，整型值。
0 - 配对失败
1 - Legacy Pairing：使用Just Works，不需要输入PIN码
2 - Legacy Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码
3 - Legacy Pairing：使用Passkey Entry，需要输入PIN码
4 - Legacy Pairing：使用OOB，目前不支持这种方式
5 - Secure Connections Pairing：使用Just Works，不需要输入PIN码
6 - Secure Connections Pairing：使用Numeric Comparison，显示PIN码，不需要输入PIN码
7 - Secure Connections Pairing：使用Passkey Entry，显示PIN码，不需要输入PIN码
8 - Secure Connections Pairing：使用Passkey Entry，需要输入PIN码
9 - Secure Connections Pairing：使用OOB，目前不支持这种方式
args[4] ：pin_code，PIN码，整型值 | **返回值描述：** @@ -1054,6 +1054,25 @@ ble.writeCharaDesc(connect_id, handle, data) 执行成功返回整型0，失败返回整型-1。 +### `ble.exchangeMtu` + +```python +ble.exchangeMtu(connect_id, mtu_size) +``` + +发送MTU交换请求。MTU交换请求应该由client端发起。 + +**参数描述：** + +- `connect_id`-连接ID，建立连接时得到的连接ID，类型为整型。 +- `mtu_size`-MTU大小。 + +**返回值描述：** + +执行成功返回整型0，失败返回整型-1。 + + + ## BLE SMP相关功能 ### `ble.smpSetConfig` @@ -1066,12 +1085,21 @@ ble.smpSetConfig(io_cap, auth_req, passkey, timeout) **参数描述：** -- `io_cap`-设备输入输出能力，类型为整型，默认为3。0 - 只有显示能力，可以显示PIN码，1 - 只有显示能力，只能显示Yes/No，不能显示PIN码，2 -只有输入能力，可以输入PIN码，3 - 没有输入输出能力，4 - 有输入输出能力，既可以显示PIN码，又可以输入PIN码。 +* `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 | +| 0 | 配对后不绑定 | 预留，无实际含义 | 不启用MITM | 使用Legacy Pairing | | 1 | 配对后绑定 | 预留，无实际含义 | 启用MITM | 使用Secure Connections Pairing | - `passkey`-配对显示的PIN码，类型为整型，默认为123456。 @@ -1081,10 +1109,34 @@ ble.smpSetConfig(io_cap, auth_req, passkey, timeout) 执行成功返回整型0，失败返回整型-1。 +**配对方法选择过程：** + +BLE smp配对有`Legacy Pairing`和`Secure Connections Pairing`两种模式，具体有如下4种配对方法： + +* OOB + +* Just Works + +* Passkey Entry + +* Numeric Comparison (只有 Secure Connections Pairing 模式才有) + +具体选择哪一种方法配对，是由配对的双方在交换各自的IO能力后协商决定的，基本分为下面几个阶段： + +阶段1：配对双方会先确认使用`Legacy Pairing`还是`Secure Connections Pairing`模式来进行配对，原则是：只有双方都设置了`Secure Connections Pairing`标志，才会使用这种配对模式，否则使用`Legacy Pairing`。 + +阶段2：判断是否支持OOB。对于`Legacy Pairing`模式，只有双方均支持OOB，才会使用OOB方式。对于`Secure Connections Pairing`模式，如果`Initiator`支持OOB，则使用OOB方式。 + +阶段3：检查MITM（中间人）。如果配对双方都没有配置MITM标志，则直接使用`Just Works`方法来配对，否则按照双方的IO能力来选择配对方法。 + +阶段4：根据双方的IO能力来选择配对方法。 + +关于阶段2 ~ 阶段4的具体说明可以参考蓝牙官方手册文档《BLUETOOTH SPECIFICATION Version 4.2 [Vol 3, Part H]》的 ***2.3.5.1 Selecting Key Generation Method*** 章节的内容。 + ### `ble.smpGetConfig` ```python -ble.smpSetConfig(io_cap, auth_req, passkey, timeout) +ble.smpGetConfig(io_cap, auth_req, passkey, timeout) ``` 配对能力查询。 @@ -1093,117 +1145,33 @@ ble.smpSetConfig(io_cap, auth_req, passkey, timeout) 执行成功返回值如下，失败返回整型-1。 -- `io_cap`-设备输入输出能力，类型为整型，默认为3。0 - 只有显示能力，可以显示PIN码，1 - 只有显示能力，只能显示Yes/No，不能显示PIN码，2 -只有输入能力，可以输入PIN码，3 - 没有输入输出能力，4 - 有输入输出能力，既可以显示PIN码，又可以输入PIN码。 +* `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 | +| 0 | 配对后不绑定 | 预留，无实际含义 | 不启用MITM | 使用Legacy Pairing | | 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配对请求。 +开始BLE SMP配对流程。SMP配对由client发起，server也可以通过该接口来通知client发起SMP配对请求。 **参数描述：** @@ -1216,15 +1184,23 @@ ble.smpStartPair(connect_id) ### `ble.smpUserConfirm` ```python -ble.smpUserConfirm(connect_id, pair_type, pin) +ble.smpUserConfirm(connect_id, pair_operation, pin) ``` 确认配对。收到配对请求后确认是否接受配对。 **参数描述：** -- `connect_id`-连接ID，建立连接时得到的连接ID，类型为整型。 -- `pair_operation`-配对的操作类型，类型为整型。0 - 取消配对，1 - 确认配对，不携带PIN码（用于Just Work或者Number Comparison模式），2 -确认配对，携带PIN码（用于Passkey模式）。 +* `connect_id`-连接ID，建立连接时得到的连接ID，类型为整型。 + +* `pair_operation`-配对的操作类型，类型为整型。 + +| 值 | 含义 | +| ---- | ------------------------------------------------------------ | +| 0 | 取消配对，只有在配对过程中，才能执行该操作。取消配对会导致蓝牙连接断开。 | +| 1 | 确认配对，不携带PIN码（用于Just Work或者Numeric Comparison模式） | +| 2 | 确认配对，携带PIN码（用于Passkey模式） | + - `pin`-PIN码，类型为整型。 **返回值描述：**