From 29b993837d1bdb88ed7dd3f38475ebd9ce375efc Mon Sep 17 00:00:00 2001 From: "jayceon.fu" Date: Thu, 6 Apr 2023 19:12:37 +0800 Subject: [PATCH 1/4] =?UTF-8?q?docs=20(gnss):=20gnss=E5=BA=94=E7=94=A8?= =?UTF-8?q?=E6=8C=87=E5=AF=BC=E6=96=87=E6=A1=A3=E7=BB=86=E8=8A=82=E4=BF=AE?= =?UTF-8?q?=E6=94=B9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 对gnss应用指导文档部分细节进行完善； 2. 将原来的coordinate_transform.md重命名为coordinate_convert.md。 固件版本: N/A 是否需要文案翻译: 是 --- .../zh/gnss/{coordinate_transform.md => coordinate_convert.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/Application_guide/zh/gnss/{coordinate_transform.md => coordinate_convert.md} (100%) diff --git a/docs/Application_guide/zh/gnss/coordinate_transform.md b/docs/Application_guide/zh/gnss/coordinate_convert.md similarity index 100% rename from docs/Application_guide/zh/gnss/coordinate_transform.md rename to docs/Application_guide/zh/gnss/coordinate_convert.md -- Gitee From 86868af9a48af7fc0b5a65d9eea14b0183eee3df Mon Sep 17 00:00:00 2001 From: "jayceon.fu" Date: Thu, 6 Apr 2023 19:17:30 +0800 Subject: [PATCH 2/4] =?UTF-8?q?docs=20(gnss):=20gnss=E5=8A=9F=E8=83=BD?= =?UTF-8?q?=E5=BA=94=E7=94=A8=E6=8C=87=E5=AF=BC=E6=96=87=E6=A1=A3=E7=BB=86?= =?UTF-8?q?=E8=8A=82=E5=AE=8C=E5=96=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 固件版本: N/A 是否需要文案翻译: 是 --- docs/Application_guide/zh/gnss/README.md | 6 +++--- docs/Application_guide/zh/gnss/gnss.md | 2 ++ 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/Application_guide/zh/gnss/README.md b/docs/Application_guide/zh/gnss/README.md index 9c6a2df1..64122c81 100644 --- a/docs/Application_guide/zh/gnss/README.md +++ b/docs/Application_guide/zh/gnss/README.md @@ -26,15 +26,15 @@ AGPS是指辅助全球卫星定位系统（Assisted Global Positioning System） ### 1.3 参考坐标系 -坐标都是相对于某一参考系而言，才有意义，GNSS定位坐标也不例外。我们通过各种渠道获取到的经纬度坐标，很可能并不是同一个坐标系下的数据。如果想利用这些坐标在地图上做可视化相关功能，就需要经过计算转换为对应地图坐标系下的坐标。目前国内比较常见的坐标系有： +坐标都是相对于某一参考系而言，才有意义，GNSS定位坐标也不例外。我们通过各种渠道获取到的经纬度坐标，很可能并不是同一个坐标系下的数据。如果想利用这些坐标在地图上做可视化相关功能，就需要经过计算转换为对应地图坐标系下的坐标。目前在中国比较常见的坐标系有： | 坐标系 | 说明 | | ------ | ------------------------------------------------------------ | | WGS-84 | 世界大地测量系统（World Geodetic System 1984），是全球通用的坐标系，也是使用最广泛的坐标系。一般GPS定位设备得到的经纬度坐标都是使用WGS-84坐标系。 | -| GCJ-02 | 由中国国家测绘局制定的地理信息系统的坐标系，它是由WGS-84坐标加密得到。国内的高德地图、腾讯地图使用的都是GCJ-02坐标系。 | +| GCJ-02 | 由中国国家测绘局制定的地理信息系统的坐标系，也叫火星坐标系。它是由WGS-84坐标加密得到。国内的高德地图、腾讯地图使用的都是GCJ-02坐标系。 | | BD-09 | 由百度开发定制的坐标系统，它是在GCJ-02坐标的基础上再次加密得到。百度地图使用的是BD-09坐标系。 | -通过上述说明，应明确一点，通过GNSS定位芯片拿到的经纬度坐标是WGS-84坐标系下的数据，如果用户需要将获取的经纬度坐标放到地图上显示位置，则需要将WGS-84坐标进行计算转换为对应坐标系下的坐标，才可用于在地图上拾取位置。 +通过上述说明，应明确一点，通过GNSS定位芯片拿到的经纬度坐标是WGS-84坐标系下的数据。在中国，如果用户需要将获取的经纬度坐标放到地图上显示位置，则需要将WGS-84坐标进行计算转换为该地图所使用坐标系下的坐标，才可用于在地图上拾取位置。 diff --git a/docs/Application_guide/zh/gnss/gnss.md b/docs/Application_guide/zh/gnss/gnss.md index d2d60e6c..9a26eb6d 100644 --- a/docs/Application_guide/zh/gnss/gnss.md +++ b/docs/Application_guide/zh/gnss/gnss.md @@ -14,6 +14,8 @@ QuecPython提供了`gnss`功能模块来获取外置GNSS模块的定位数据。 ## 2.1 获取定位数据 +下面将详细描述使用gnss模块接口获取定位数据的步骤，同时说明在使用过程中一些注意事项。 + ### 2.1.1 使用步骤 步骤1：确定串口信息 -- Gitee From 99bef49ff79411be1db3f3e53b596f921d4519c9 Mon Sep 17 00:00:00 2001 From: "jayceon.fu" Date: Thu, 6 Apr 2023 19:28:19 +0800 Subject: [PATCH 3/4] =?UTF-8?q?docs=20(checkNet/wifiScan):=20API=5Freferen?= =?UTF-8?q?ce\zh\QuecPython=E7=B1=BB=E5=BA=93=20=E7=9B=AE=E5=BD=95?= =?UTF-8?q?=E4=B8=8B=E7=9A=84README=E4=B8=AD=E5=A2=9E=E5=8A=A0=E5=AF=B9che?= =?UTF-8?q?ckNet/wifiScan=E6=A8=A1=E5=9D=97=E7=9A=84=E8=B6=85=E9=93=BE?= =?UTF-8?q?=E6=8E=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 固件版本: N/A 是否需要文案翻译: 是 --- .../zh/QuecPython\347\261\273\345\272\223/README.md" | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/README.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/README.md" index 1f4c449b..b3ee230e 100644 --- "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/README.md" +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/README.md" @@ -15,8 +15,10 @@ - [net - 网络相关功能](./net.md) - [cellLocator - 基站定位](./cellLocator.md) - [wifilocator - WiFi定位](./wifilocator.md) -- [fota-固件升级相关功能](./fota.md) -- [app_fota-用户文件升级相关功能](./app_fota.md) +- [fota - 固件升级相关功能](./fota.md) +- [app_fota - 用户文件升级相关功能](./app_fota.md) +- [checkNet - 网络就绪检测](./checkNet.md) +- [wifiScan - WiFi扫描](./wifiScan.md) - [machine - 硬件相关功能](./machine.md) - [misc - 其他](./misc.md) - [qrcode - 二维码显示](./qrcode.md) -- Gitee From efff26326a311b405fbe500cc19884c30726c9cc Mon Sep 17 00:00:00 2001 From: "jayceon.fu" Date: Sat, 8 Apr 2023 11:17:54 +0800 Subject: [PATCH 4/4] =?UTF-8?q?docs=20(wifiScan):=20=E5=A2=9E=E5=8A=A0wifi?= =?UTF-8?q?Scan=E5=8A=9F=E8=83=BD=E5=BA=94=E7=94=A8=E6=8C=87=E5=AF=BC?= =?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/A 是否需要文案翻译: 是 --- docs/Application_guide/zh/README.md | 1 + docs/Application_guide/zh/sidebar.yaml | 4 +- docs/Application_guide/zh/wifiscan/README.md | 12 + .../Application_guide/zh/wifiscan/wifiscan.md | 240 ++++++++++++++++++ 4 files changed, 256 insertions(+), 1 deletion(-) create mode 100644 docs/Application_guide/zh/wifiscan/README.md create mode 100644 docs/Application_guide/zh/wifiscan/wifiscan.md diff --git a/docs/Application_guide/zh/README.md b/docs/Application_guide/zh/README.md index f3b9cbea..3b45bbb7 100644 --- a/docs/Application_guide/zh/README.md +++ b/docs/Application_guide/zh/README.md @@ -9,4 +9,5 @@ QuecPython 应用指导，是对QuecPython常用功能模块如何使用的指 * [bluetooth](./bluetooth/README.md) * [fota](./fota/README.md) * [gnss](./gnss/README.md) +* [wifiScan](./wifiscan/README.md) * [peripherals](./peripherals/README.md) \ No newline at end of file diff --git a/docs/Application_guide/zh/sidebar.yaml b/docs/Application_guide/zh/sidebar.yaml index caf23d1e..4ae6b919 100644 --- a/docs/Application_guide/zh/sidebar.yaml +++ b/docs/Application_guide/zh/sidebar.yaml @@ -4,4 +4,6 @@ items: - label: 蓝牙 file: bluetooth/README.md - label: GNSS定位 - file: gnss/README.md \ No newline at end of file + file: gnss/README.md +- label: WiFi扫描 + file: wifiscan/README.md \ No newline at end of file diff --git a/docs/Application_guide/zh/wifiscan/README.md b/docs/Application_guide/zh/wifiscan/README.md new file mode 100644 index 00000000..625a2aea --- /dev/null +++ b/docs/Application_guide/zh/wifiscan/README.md @@ -0,0 +1,12 @@ +# wifiScan应用指导说明 + +本文描述了如何使用QuecPython的wifiScan模块的功能，包含相关API的使用以及一些注意事项。 + + + +## wifiScan应用指导文档列表 + +* [wifiScan功能应用指导](./wifiscan.md) + + + diff --git a/docs/Application_guide/zh/wifiscan/wifiscan.md b/docs/Application_guide/zh/wifiscan/wifiscan.md new file mode 100644 index 00000000..4cc374b6 --- /dev/null +++ b/docs/Application_guide/zh/wifiscan/wifiscan.md @@ -0,0 +1,240 @@ +# 1. 简介 + +QuecPython提供了`wifiScan`功能模块来扫描周边的WiFi热点信息，包括WiFi热点的MAC地址和RSSI信号强度。 + +> 本文档中示例代码前面有 `>>> `字符串的，表示在QuecPython的命令交互界面输入的代码。 + + + +# 2. 使用说明 + +`wifiScan`有同步扫描和异步扫描两种扫描方式。同步扫描是一直等待扫描结束才返回扫描结果，因此扫描接口会阻塞一段时间；而异步扫描则是将扫描结果通过回调来返回给用户，因此扫描接口本身并不会阻塞。具体使用哪一种扫描方式，取决于用户的实际需求。下面分别说明这两种扫描方式的用法。 + +## 2.1 同步扫描 + +如前述所，同步扫描接口会阻塞一段时间，具体阻塞时间的长短取决于扫描配置参数，因此并没有一个固定的时间值。如果用户允许相关线程中使用阻塞性质接口，则可按照如下步骤来使用`wifiScan`的同步扫描功能。 + +### 2.1.1 使用步骤 + +步骤1：确认状态 + +先通过如下接口获取`wifiScan`的状态，确认是否已开启。返回值为`True`表示功能已开启，为`False`表示功能未开启。 + +```python +>>> wifiScan.getState() +False +``` + +步骤2：打开`wifiScan`功能 + +如果`wifiScan.getState()`返回`False`，则使用如下接口来开启`wifiScan`功能。 + +```python +>>> wifiScan.control(1) +0 +``` + +步骤3：扫描参数设置 + +`wifiScan`模块提供了配置接口来设置扫描的相关参数，比如超时时间、扫描轮数、最大扫描热点数量以及扫描优先级。用户可根据需要来设置对应参数。这里设置超时时间为10s、扫描1次、最大扫描数量20个。由于优先级参数是可选参数，对于不支持的模组，我们可以不写该参数。 + +```python +>>> wifiScan.getCfgParam() +(5, 1, 10, 0) +>>> wifiScan.setCfgParam(10, 1, 20) +0 +>>> wifiScan.getCfgParam() +(10, 1, 20, 0) +``` + + + +> * 并不是所有的模组都支持优先级参数，上述示例是基于EC600U系列模组，不支持优先级参数，因此没有配置。不支持优先级参数的模组有：EC200U/EC600U/EG912U/EG915U/EC600G/EC800G系列。 +> +> * 设置的扫描参数掉电不保存。 + + + +步骤4：开始扫描 + +```python +>>> wifiScan.start() +(8, [('34:CE:00:09:E5:A8', -38), ('50:D2:F5:B4:70:BF', -40), ('00:60:92:57:0A:F4', -47), ('00:03:7F:12:06:06', -53), ('F0:2F:74:2A:41:78', -54), ('00:03:7F:12:15:15', -68), ('08:4F:0A:05:22:8B', -73), ('08:4F:0A:05:22:8F', -76)]) +``` + + + +### 2.1.2 示例代码 + +```python +""" +本例程示范了如何使用wifiScan模块的同步扫描功能 +""" +import utime +import wifiScan + + +def main(): + isOpen = wifiScan.getState() + if not isOpen: + ret = wifiScan.control(1) + if ret == 0: + print('wifi scan 打开成功') + else: + print('wifi scan 打开失败') + return -1 + else: + print('wifi scan 已经开启') + + ret = wifiScan.setCfgParam(5, 1, 20, 0) + if ret == 0: + print('扫描参数设置成功') + else: + print('扫描参数配置出错') + return -1 + curCfg = wifiScan.getCfgParam() + if curCfg != -1: + print('当前扫描参数为：') + print('超时时间：{}'.format(curCfg[0])) + print('扫描轮数：{}'.format(curCfg[1])) + print('最大扫描数量：{}'.format(curCfg[2])) + else: + print('获取扫描配置出错') + return -1 + count = 0 + while True: + count += 1 + scanInfo = wifiScan.start() + if scanInfo != -1: + scanNums = scanInfo[0] + wifiInfo = scanInfo[1] + print('扫描到{}个热点：'.format(scanNums)) + for i in wifiInfo: + print(i) + utime.sleep(2) + if count >= 3: + break + else: + print('扫描出错') + return -1 + + ret = wifiScan.control(0) + if ret == 0: + print('wifi scan 关闭成功') + return 0 + else: + print('wifi scan 关闭失败') + return -1 + + +if __name__ == '__main__': + main() + +``` + + + +## 2.2 异步扫描 + +异步扫描方式在使用上和同步扫描区别不大，大部分步骤和同步扫描一致。 + +### 2.2.1 使用步骤 + +步骤1：确认状态 + +步骤2：打开`wifiScan`功能 + +步骤3：扫描参数设置 + +步骤4：注册异步扫描回调函数 + +步骤5：开始扫描 + + + +### 2.2.2 示例代码 + +关于如下例程有两点需要说明： + +* 例程中，`wifiscanCallback`回调中使用消息队列将扫描数据发到`main`中显示处理了。这是因为，在回调中，尽量只做一些耗时短的操作，一些耗时较长、处理较为复杂的操作一般放到其他任务中进行处理，不一定是放到主任务`main`中处理，也可以是其他子任务中。 + +* 消息队列的`get`方法，在没有消息时，会一直阻塞。如果应用代码中某个线程中不能阻塞，则不应该在其中使用该方法。 + +```python +""" +本例程示范了如何使用wifiScan模块的异步扫描功能 +""" +import utime +import wifiScan +from queue import Queue + +msgq = Queue(5) + + +def wifiscanCallback(args): + global msgq + msgq.put(args) + + +def main(): + global msgq + isOpen = wifiScan.getState() + if not isOpen: + ret = wifiScan.control(1) + if ret == 0: + print('wifi scan 打开成功') + else: + print('wifi scan 打开失败') + return -1 + else: + print('wifi scan 已经开启') + + ret = wifiScan.setCfgParam(5, 1, 20, 0) + if ret == 0: + print('扫描参数设置成功') + else: + print('扫描参数配置出错') + return -1 + curCfg = wifiScan.getCfgParam() + if curCfg != -1: + print('当前扫描参数为：') + print('超时时间：{}'.format(curCfg[0])) + print('扫描轮数：{}'.format(curCfg[1])) + print('最大扫描数量：{}'.format(curCfg[2])) + else: + print('获取扫描配置出错') + return -1 + # 注册回调函数 + wifiScan.setCallback(wifiscanCallback) + + count = 0 + while True: + count += 1 + if wifiScan.asyncStart() == 0: + scanInfo = msgq.get() # 没有消息时会阻塞在这里 + scanNums = scanInfo[0] + wifiInfo = scanInfo[1] + print('扫描到{}个热点：'.format(scanNums)) + for i in wifiInfo: + print(i) + utime.sleep(2) + if count >= 3: + break + else: + print('扫描出错') + return -1 + + ret = wifiScan.control(0) + if ret == 0: + print('wifi scan 关闭成功') + return 0 + else: + print('wifi scan 关闭失败') + return -1 + + +if __name__ == '__main__': + main() + +``` + -- Gitee