From ffbb06d56a005a9cd2a2f68addcad4d6d26fb9f5 Mon Sep 17 00:00:00 2001 From: "forrest.liu" Date: Mon, 4 Sep 2023 20:57:25 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs=20(firmware-ota.md):=20=E4=BF=AE?= =?UTF-8?q?=E6=94=B9=E5=9B=BA=E4=BB=B6OTA=E5=8D=87=E7=BA=A7=E5=BA=94?= =?UTF-8?q?=E7=94=A8=E6=8C=87=E5=AF=BC=E6=96=87=E6=A1=A3=E4=B8=AD=E4=B8=8D?= =?UTF-8?q?=E5=8F=AF=E7=94=A8=E8=B7=B3=E8=BD=AC=E9=93=BE=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 固件版本: N 是否需要文案翻译: 是 --- .../zh/firmware-upgrade/firmware-ota.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md b/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md index 8e308bb1..d39cc3f7 100644 --- a/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md +++ b/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md @@ -81,7 +81,7 @@ OTA云平台的作用是： 3.升级状态管理，如升级成功或者失败。 -借助于OTA云平台可实现网页控制OTA自动升级。使用前需要先初始化云平台相关的功能。API细节参考wiki API [QuecPython云平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/index.html)。 +借助于OTA云平台可实现网页控制OTA自动升级。使用前需要先初始化云平台相关的功能。API细节参考[QuecPython IoT 平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/index.html)。 ###### 2.接收云平台升级消息 @@ -89,7 +89,7 @@ OTA云平台的作用是： ###### 3.下载升级包 -获取到升级包URL后，设备则调用固件升级相关API进行升级包下载、写入及校验。API细节参考wiki API[固件升级相关功能](https://python.quectel.com/doc/API_reference/zh/QuecPython_classlib/fota.html)。 +获取到升级包URL后，设备则调用固件升级相关API进行升级包下载、写入及校验。API细节参考[fota - 固件升级相关功能](https://python.quectel.com/doc/API_reference/zh/syslib/fota.html)。 ###### 4.重启 @@ -103,7 +103,7 @@ OTA云平台的作用是： ##### 阿里云 -如果使用阿里云平台的OTA功能，首先需要接入阿里云，设备如何接入阿里云可以参见[QuecPython接入阿里云操作文档](https://my.qpy.wiki/doc/Getting_started/zh/clouds/aliyun.html)。接入阿里云之后如何使用云平台OTA功能可以参见[阿里云物联网平台OTA升级操作相关文档](https://help.aliyun.com/document_detail/130990.html?spm=a2c4g.130990.0.0.28722110xYe5Td)。 +如果使用阿里云平台的OTA功能，首先需要接入阿里云，设备如何接入阿里云可以参考[aLiYun - 阿里 IoT 平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/aLiYun.html)。接入阿里云之后如何使用云平台OTA功能可以参见[阿里云物联网平台OTA升级操作相关文档](https://help.aliyun.com/document_detail/130990.html?spm=a2c4g.130990.0.0.28722110xYe5Td)。 这里以阿里云为例展示OTA平台使用操作步骤： @@ -125,7 +125,7 @@ OTA云平台的作用是： ##### 腾讯云 -如果使用腾讯云平台的OTA功能，首先需要接入腾讯云，设备如何接入腾讯云可以参见[QuecPython接入腾讯云操作文档](https://my.qpy.wiki/doc/Getting_started/zh/clouds/tencent.html)。接入腾讯云之后如何使用云平台OTA功能可以参见[腾讯云物联网开发平台固件升级协议](https://cloud.tencent.com/document/product/1081/39359)。[腾讯云物联网开发平台固件升级操作](https://cloud.tencent.com/document/product/1081/40296)。 +如果使用腾讯云平台的OTA功能，首先需要接入腾讯云，设备如何接入腾讯云可以参考[TenCentYun- 腾讯 IoT 平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/TenCentYun.html)。接入腾讯云之后如何使用云平台OTA功能可以参见[腾讯云物联网开发平台固件升级协议](https://cloud.tencent.com/document/product/1081/39359)。[腾讯云物联网开发平台固件升级操作](https://cloud.tencent.com/document/product/1081/40296)。 ##### 移远云 @@ -153,7 +153,7 @@ OTA云平台的作用是： ###### 3.下载升级包 -获取到升级包URL后，设备根据URL下载待升级的目标文件到文件系统中。支持单文件下载和多文件批量下载方式。API细节参考wiki API[用户文件升级相关功能](https://python.quectel.com/doc/API_reference/zh/syslib/app_fota.html)。 +获取到升级包URL后，设备根据URL下载待升级的目标文件到文件系统中。支持单文件下载和多文件批量下载方式。API细节参考[app_fota - 用户文件升级相关功能](https://python.quectel.com/doc/API_reference/zh/syslib/app_fota.html)。 ###### 4.设置升级标志 -- Gitee From d43a44dd20cf556b14eee28a66b9634650697f5f Mon Sep 17 00:00:00 2001 From: "forrest.liu" Date: Fri, 8 Sep 2023 19:07:16 +0800 Subject: [PATCH 2/3] =?UTF-8?q?docs=20(firmware-upgrade/system):=20?= =?UTF-8?q?=E6=A0=B9=E6=8D=AEST=E5=BB=BA=E8=AE=AE=E4=BF=AE=E6=94=B9?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 固件版本: N 是否需要文案翻译: 是 --- docs/Application_guide/zh/firmware-upgrade/README.md | 2 +- .../firmware-ota-delta-package-making.md | 2 +- .../zh/firmware-upgrade/firmware-ota-issues.md | 10 +++++----- .../zh/firmware-upgrade/firmware-ota.md | 8 ++++---- docs/Application_guide/zh/system/fs.md | 10 +++++----- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/Application_guide/zh/firmware-upgrade/README.md b/docs/Application_guide/zh/firmware-upgrade/README.md index 511b4918..5766bfc5 100644 --- a/docs/Application_guide/zh/firmware-upgrade/README.md +++ b/docs/Application_guide/zh/firmware-upgrade/README.md @@ -1,4 +1,4 @@ -# 关于固件升级 +# 固件升级 众所周知，做 QuecPython 脚本软件开发离不开 Python 脚本运行环境，而这个运行环境则是编译在支持 QuecPython 的模组的固件中的。因此，开发拿到移远通信的模组时，必须先烧录 QuecPython 团队提供的、支持了Python 脚本运行环境的固件，方能进行脚本软件开发。 diff --git a/docs/Application_guide/zh/firmware-upgrade/firmware-ota-delta-package-making.md b/docs/Application_guide/zh/firmware-upgrade/firmware-ota-delta-package-making.md index 768846c1..c8582627 100644 --- a/docs/Application_guide/zh/firmware-upgrade/firmware-ota-delta-package-making.md +++ b/docs/Application_guide/zh/firmware-upgrade/firmware-ota-delta-package-making.md @@ -1,4 +1,4 @@ -# 固件OTA差分包制作操作指引 +# 固件 OTA 升级包制作指引 本文档旨在介绍QuecPython固件OTA差分包制作方法，指导客户使用工具制作OTA差分包。 diff --git a/docs/Application_guide/zh/firmware-upgrade/firmware-ota-issues.md b/docs/Application_guide/zh/firmware-upgrade/firmware-ota-issues.md index 1d92c01f..55363cab 100644 --- a/docs/Application_guide/zh/firmware-upgrade/firmware-ota-issues.md +++ b/docs/Application_guide/zh/firmware-upgrade/firmware-ota-issues.md @@ -1,4 +1,4 @@ -# 固件及应用OTA升级常见问题 +# 固件 OTA 升级常见问题 ## 固件OTA升级是否一定要制作升级包 @@ -6,11 +6,11 @@ ## 如何制作差分包 -不同型号略有差异，参见[固件OTA差分包制作操作指引](./firmware-ota-delta-package-making.md)。 +不同型号略有差异，参见[固件OTA升级包制作指引](./firmware-ota-delta-package-making.md)。 ## 制作差分包失败原因 -不同分区结构的固件无法相互OTA升级，所以需要确保制作差分包的2各固件分区一致。官方固件中同一型号的固件分区会保持一致，如果因为特殊情况导致无法OTA会特殊说明。 +不同分区结构的固件无法相互OTA升级，所以需要确保制作差分包的2个固件分区一致。官方固件中同一型号的固件分区会保持一致，如果因为特殊情况导致无法OTA会特殊说明。 ## 固件OTA升级异常断电处理 @@ -38,7 +38,7 @@ MiniFota升级方案属于特殊定制的方案，在进行OTA升级功能之前 ## MiniFOTA升级方式如何升级文件系统分区 -MiniFOTA升级支持将文件系统分区一起升级，而用户的脚本文件和其他文件也是存在文件系统分区。这样MiniFOTA升级就可以实现固件和用户文件一起进行升级。具体需要制作升级包的时候带上fs分区，可以参见[固件OTA差分包制作操作指引](./firmware-ota-delta-package-making.md)。 +MiniFOTA升级支持将文件系统分区一起升级，而用户的脚本文件和其他文件也是存在文件系统分区。这样MiniFOTA升级就可以实现固件和用户文件一起进行升级。具体需要制作升级包的时候带上fs分区，可以参见[固件OTA升级包制作指引](./firmware-ota-delta-package-making.md)。 ## 应用OTA升级下载是否有完整性校验 @@ -58,7 +58,7 @@ OTA功能模块本身没有，客户可以自己加入完整性校验。方法 ## 下载协议 -下载协议支持 HTTP和FTP，具体支持情况如下表。 +下载协议支持 HTTP、HTTPS和FTP，具体支持情况如下表。 | 型号 | HTTP | HTTPS | FTP | | ------------------------------------ | ---- | ------ | ------ | diff --git a/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md b/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md index d39cc3f7..c87d0001 100644 --- a/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md +++ b/docs/Application_guide/zh/firmware-upgrade/firmware-ota.md @@ -67,7 +67,7 @@ QuecPython分区表构成细节可以参见[QuecPython存储设备介绍](../sys ##### 差分包准备 -不同型号设备制作方法会有差异，具体参见[固件OTA差分包制作操作指引](./firmware-ota-delta-package-making.md)。 +不同型号设备制作方法会有差异，具体参见[固件OTA升级包制作指引](./firmware-ota-delta-package-making.md)。 ##### 代码准备 @@ -125,7 +125,7 @@ OTA云平台的作用是： ##### 腾讯云 -如果使用腾讯云平台的OTA功能，首先需要接入腾讯云，设备如何接入腾讯云可以参考[TenCentYun- 腾讯 IoT 平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/TenCentYun.html)。接入腾讯云之后如何使用云平台OTA功能可以参见[腾讯云物联网开发平台固件升级协议](https://cloud.tencent.com/document/product/1081/39359)。[腾讯云物联网开发平台固件升级操作](https://cloud.tencent.com/document/product/1081/40296)。 +如果使用腾讯云平台的OTA功能，首先需要接入腾讯云，设备如何接入腾讯云可以参考[TenCentYun- 腾讯 IoT 平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/TenCentYun.html)。接入腾讯云之后如何使用云平台OTA功能可以参见[腾讯云物联网开发平台固件升级协议](https://cloud.tencent.com/document/product/1081/39359)、[腾讯云物联网开发平台固件升级操作](https://cloud.tencent.com/document/product/1081/40296)。 ##### 移远云 @@ -145,7 +145,7 @@ OTA云平台的作用是： ###### 1.初始化云平台功能 -借助于OTA云平台可实现网页控制OTA自动升级。使用前需要先初始化云平台相关的功能。API细节参考wiki API [QuecPython云平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/index.html)。 +借助于OTA云平台可实现网页控制OTA自动升级。使用前需要先初始化云平台相关的功能。API细节参考 [QuecPython IoT 平台](https://python.quectel.com/doc/API_reference/zh/cloudlib/index.html)。 ###### 2.接收云平台升级消息 @@ -312,7 +312,7 @@ cloud.setCallBack(sub_cb) # 订阅Topic qos = 1 cloud.subscribe(ota_topic_device_upgrade, qos) -cloud.subscribe(ota_topic_firmware_get_reply￿, qos) +cloud.subscribe(ota_topic_firmware_get_reply, qos) # 阿里云功能启动 cloud.start() diff --git a/docs/Application_guide/zh/system/fs.md b/docs/Application_guide/zh/system/fs.md index 61a1f836..74a45b16 100644 --- a/docs/Application_guide/zh/system/fs.md +++ b/docs/Application_guide/zh/system/fs.md @@ -80,7 +80,7 @@ write(str) - str: 要写入的数据 -该函数返回成功写入的字符串长度 +该接口返回成功写入的字符串长度 ##### 读取文件 @@ -90,7 +90,7 @@ read(size) - size:要读取的长度，单位字节 -该函数返回成功读到的数据 +该接口返回成功读到的数据 读取文件的一行 @@ -100,7 +100,7 @@ readline(size) - size:要读取的长度，单位字节 -调用此方法会根据结束符自动读取，并返回一个等于size长度的字符串，如果size为-1则返回整行。 +调用此接口会根据结束符自动读取，并返回一个等于size长度的字符串，如果size为-1则返回整行。 读取文件所有行 @@ -108,7 +108,7 @@ readline(size) readlines() ``` -调用此方法会根据结束符自动分行读取，并返回一个包含所有分行的列表。 +调用此接口会根据结束符自动分行读取，并返回一个包含所有分行的列表。 ##### 移动文件指针 @@ -444,7 +444,7 @@ QuecPython设备软件由固件和用户应用脚本2部分组成。其中固件 ### with open 和 open的区别 -open是python的一个内置函数。with open是使用了with语句的open函数。open()完成后必须调用close()方法关闭文件。因为文件对象会占用系统的资源，同一时间能打开的文件数量也是有限的，另外不成对使用可能会导致其他异常。由于文件读写时有可能产生IO异常，一旦出错，后面的close()就不会调用。with open则可以避免这样的情况，即便在文件读写过程中发生IO异常，也会自动调用close()方法关闭文件。 +open是python的一个内置接口。with open是使用了with语句的open接口。open()完成后必须调用close()接口关闭文件。因为文件对象会占用系统的资源，同一时间能打开的文件数量也是有限的，另外不成对使用可能会导致其他异常。由于文件读写时有可能产生IO异常，一旦出错，后面的close()就不会调用。with open则可以避免这样的情况，即便在文件读写过程中发生IO异常，也会自动调用close()接口关闭文件。 ```python with open('/usr/test.txt','w+')as f: -- Gitee From 3fad5bf03a7ac2d546735fe10cb71e40c165cd28 Mon Sep 17 00:00:00 2001 From: "forrest.liu" Date: Fri, 29 Mar 2024 11:39:09 +0800 Subject: [PATCH 3/3] docs (ble): add BLE SMP API description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 固件版本: N/A 是否需要文案翻译: 否 --- docs/API_reference/en/btlib/ble.md | 225 ++++++++++++++++++++++++++++ docs/API_reference/zh/btlib/ble.md | 227 ++++++++++++++++++++++++++++- 2 files changed, 451 insertions(+), 1 deletion(-) diff --git a/docs/API_reference/en/btlib/ble.md b/docs/API_reference/en/btlib/ble.md index 55b0705a..ceff1ad7 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 8f31a260..6ee63e3a 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 -- Gitee