From bdc53f387c598046da9689f4d8e9c9dbb7593254 Mon Sep 17 00:00:00 2001 From: "Francis.Qin" <1371316129@qq.com> Date: Thu, 20 Apr 2023 20:54:21 +0800 Subject: [PATCH] =?UTF-8?q?=20(WIFI=E5=92=8CUSBNET):=20?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 固件版本: N/A 是否需要文案翻译: 是 --- .../WLAN.ESP8266.md" | 50 +++--- docs/Application_guide/zh/README.md | 1 + docs/Application_guide/zh/sidebar.yaml | 2 + docs/Application_guide/zh/usbnet/README.md | 37 +++++ docs/Application_guide/zh/usbnet/usbnet.md | 145 ++++++++++++++++++ 5 files changed, 210 insertions(+), 25 deletions(-) create mode 100644 docs/Application_guide/zh/usbnet/README.md create mode 100644 docs/Application_guide/zh/usbnet/usbnet.md diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" index 7fe72ef3..bcca7885 100644 --- "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" @@ -14,12 +14,12 @@ class ESP8266(uart=UART.UART1, mod=ESP8266.STA， callback=None) 加载ESP8266驱动，初始化虚拟网卡，并返回ESP8266对象。 **参数描述：** -- `uart` - 模组UART口选择，表示模组与ESP8266所连接的`串口号`，默认使用`UART1`。 -- `mode` - 无线网卡工作模式配置，用来指定ESP8266的`工作模式`，STA客户端模式为ESP8266.STA，AP接入点模式为ESP8266.AP，默认使用`STA客户端`模式。 -- `callback` - 设置回调函数，用于`网络变化`以及`ota升级`通知，默认为未开启。 +- `uart` - 整型值，模组UART口选择，表示模组与ESP8266所连接的`串口号`，默认使用`UART1`。 +- `mode` - 整型值，无线网卡工作模式配置，用来指定ESP8266的`工作模式`，STA客户端模式为ESP8266.STA，AP接入点模式为ESP8266.AP，默认使用`STA客户端`模式。 +- `callback` - 回调函数名。设置回调函数，用于`网络变化`以及`ota升级`通知，默认为未开启。 **callback参数描述：** -- `content` - 用户回调，表示上报消息内容 +- `content` - 字符串类型，用户回调，表示上报消息内容 **上报消息内容描述：** @@ -72,7 +72,7 @@ ESP8266.status() **返回值描述：** -返回int类型，枚举值，具体说明如下： +返回整型值，具体说明如下： - `0` - esp8266 设备不存在 - `1` - esp8266 station模式已连接 - `2` - esp8266 station模式未连接 @@ -93,7 +93,7 @@ ESP8266.version() **返回值描述：** -返回string类型，格式为(sdk, model, version, time),具体说明如下： +返回字符串类型，格式为(sdk, model, version, time),具体说明如下： - `sdk` - sdk信息 - `model` - 无线网卡型号 - `version` - 版本号 @@ -111,14 +111,14 @@ ESP8266.ipconfig() **返回值描述：** - 返回tuple类型，格式为 (ip, subnet, gateway, mtu, primary_dns, secondary_dns)，具体说明如下： + 返回元组类型，格式为 (ip, subnet, gateway, mtu, primary_dns, secondary_dns)，具体说明如下： -- `ip` - ip地址 -- `subnet` - 子网掩码 -- `gateway` - 网关 -- `mtu` - 最大传输单元 -- `primary_dns` - DNS服务器主地址 -- `secondary_dns` - DNS服务器辅地址 +- `ip` - 字符串类型，ip地址 +- `subnet` - 字符串类型，子网掩码 +- `gateway` - 字符串类型，网关 +- `mtu` - 整型值，最大传输单元 +- `primary_dns` - 字符串类型，DNS服务器主地址 +- `secondary_dns` - 字符串类型，DNS服务器辅地址 @@ -132,8 +132,8 @@ ESP8266.station(username，password) **参数描述：** -- `username` - 填写所要连接的 `WiFi` 的名称（1~32 个字符） -- `password` - 填写所要连接的 `WiFi` 的密码（8~64 个字符） +- `username` - 字符串类型，填写所要连接的 `WiFi` 的名称（1~32 个字符） +- `password` - 字符串类型，填写所要连接的 `WiFi` 的密码（8~64 个字符） **返回值描述：** @@ -153,8 +153,8 @@ ESP8266.ap(username，password) **参数描述：** -- `username` - 配置 `WiFi热点` 的名称（1~32 个字符） -- `password` - 配置 `WiFi热点` 的密码（8~64 个字符） +- `username` - 字符串类型，配置 `WiFi热点` 的名称（1~32 个字符） +- `password` - 字符串类型，配置 `WiFi热点` 的密码（8~64 个字符） **返回值描述：** @@ -174,8 +174,8 @@ ESP8266.web_config(username，password) **参数描述：** -- `username` - 配置 `配网热点` 的名称（1~32 个字符） -- `password` - 配置 `配网热点` 的密码（8~64 个字符） +- `username` - 字符串类型，配置 `配网热点` 的名称（1~32 个字符） +- `password` - 字符串类型，配置 `配网热点` 的密码（8~64 个字符） **返回值描述：** @@ -195,7 +195,7 @@ ESP8266.ota(url) **参数描述：** -- `url` - 填写网址地址，表示固件下载地址，当前仅支持 http 协议，最长 256 字节。 +- `url` - 字符串类型，填写网址地址，表示固件下载地址，当前仅支持 http 协议，最长 256 字节。 **返回值描述：** @@ -238,7 +238,7 @@ ESP8266.set_default_NIC(ip_str) **参数描述：** -- `ip_str` - 所要设置默认转发网卡的网卡 ip 地址，如：'192.168.1.100' +- `ip_str` - 字符串类型，所要设置默认转发网卡的网卡 ip 地址，如：'192.168.1.100' **返回值描述：** @@ -256,8 +256,8 @@ ESP8266.set_dns(pri_dns, sec_dns) **参数描述：** -- `pri_dns` - 设置无线网卡的`首选 dns` 服务器，默认为 `8.8.8.8` -- `sec_dns` - 设置无线网卡的`备选 dns` 服务器，默认为 `114.114.114.114` +- `pri_dns` - 字符串类型，设置无线网卡的`首选 dns` 服务器，默认为 `8.8.8.8` +- `sec_dns` - 字符串类型，设置无线网卡的`备选 dns` 服务器，默认为 `114.114.114.114` **返回值描述：** @@ -275,8 +275,8 @@ ESP8266.router_add(ip, mask) **参数描述：** -- `ip` - 设置 `ap` 模式的网段，默认为 192.168.4.1 -- `mask` - 设置子网掩码，默认为 255.255.255.0 +- `ip` - 字符串类型，设置 `ap` 模式的网段，默认为 192.168.4.1 +- `mask` - 字符串类型，设置子网掩码，默认为 255.255.255.0 **返回值描述：** diff --git a/docs/Application_guide/zh/README.md b/docs/Application_guide/zh/README.md index 3b45bbb7..e0d54b29 100644 --- a/docs/Application_guide/zh/README.md +++ b/docs/Application_guide/zh/README.md @@ -9,5 +9,6 @@ QuecPython 应用指导，是对QuecPython常用功能模块如何使用的指 * [bluetooth](./bluetooth/README.md) * [fota](./fota/README.md) * [gnss](./gnss/README.md) +* [usbnet](./usbnet/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 4ae6b919..351fc4ec 100644 --- a/docs/Application_guide/zh/sidebar.yaml +++ b/docs/Application_guide/zh/sidebar.yaml @@ -5,5 +5,7 @@ items: file: bluetooth/README.md - label: GNSS定位 file: gnss/README.md +- label: USB网卡 + file: usbnet/README.md - label: WiFi扫描 file: wifiscan/README.md \ No newline at end of file diff --git a/docs/Application_guide/zh/usbnet/README.md b/docs/Application_guide/zh/usbnet/README.md new file mode 100644 index 00000000..1317d196 --- /dev/null +++ b/docs/Application_guide/zh/usbnet/README.md @@ -0,0 +1,37 @@ +# USBNET应用指导说明 + +本文中对USBNET一些基础概念进行了简要说明，描述了如何使用 QuecPython 的`USBNET`模块的功能，包含USB网卡使用的前提条件。 + + + +## 1. 基础概念说明 + +### 1.1 什么是USBNET + +USBNET（Universal Serial Bus Network），是一种USB网络技术，可以通过USB接口在计算机之间传输数据。它通常用于连接嵌入式设备，例如智能手机或网络路由器，与计算机进行通信。USBNET技术使嵌入式设备可以像普通计算机一样直接连接到网络，从而方便了设备的管理和控制。因此，USBNET被广泛应用于各种计算机和网络设备中。 + + + +### 1.3 `ECM`模式和`RNDIS`模式的区别 +ECM和RNDIS是USBNET中的两种网络模式。具体区别如下： + +* `ECM` - 全称是"Ethernet Control Model"，它是一种通过USB连接来模拟Ethernet网络连接的技术。ECM能够在device和host之间交换ethernet frame， 符合ECM规范的设备，认为自己是一个虚拟的网络接口， 可以被分配MAC和IP。ECM可以被用于连接任何支持TCP/IP协议的设备，例如计算机、网络路由器、智能手机等，从而使它们可以直接访问网络。 + +* `RNDIS` - 全称是"Remote Network Driver Interface Specification"，它是一种使嵌入式设备通过USB接口来实现远程网络连接的技术，实际上就是TCP/IP over USB。RNDIS可以让嵌入式设备直接连接到计算机的网络，从而方便了设备的管理和控制。 + +因此，ECM和RNDIS都是USBNET中常见的网络模式，它们可以使嵌入式设备通过USB连接实现网络连接和通信。 + + + +### 1.2 什么是PID + +PID是"Product ID"的缩写，指的是USB设备的产品标识号。每一个USB设备都必须拥有唯一的PID，以便计算机能够识别和区分不同的USB设备。PID通常由USB设备制造商进行分配，并写入设备的固件中。 +在USB连接建立时，计算机会读取USB设备的PID信息，并根据PID来确定设备的厂商和型号等信息。这些信息可以用来识别设备，并为其加载正确的驱动程序，以确保设备可以正常工作。因此，PID是USB设备中重要的标识之一。 + + + +## 2. USBNET应用指导文档列表 + +* [USBNET功能应用指导](./usbnet.md) + + diff --git a/docs/Application_guide/zh/usbnet/usbnet.md b/docs/Application_guide/zh/usbnet/usbnet.md new file mode 100644 index 00000000..8b2624f4 --- /dev/null +++ b/docs/Application_guide/zh/usbnet/usbnet.md @@ -0,0 +1,145 @@ +# 1. 简介 + +QuecPython提供了`USBNET`功能模块来为用户提供USB网卡功能。该功能模块使得用户只需调用几个接口即可开启USBNET功能，提高了开发效率。 + +目前支持USBNET功能的模组系列：EC600S/EC600N/EC800N/EC200U/EC600U/EC600M。 + +> 本文档中示例代码前面有 `>>> `字符串的，表示在QuecPython的命令交互界面输入的代码。 + + + +# 2. 使用说明 + +`USBNET`模块接口的详细说明，请参考QuecPython官网的Wiki文档中相关部分的说明。下面将说明如何使用`USBNET`模块的相关功能。 + +## 2.1 USB网卡相关设置 + +下面将详细描述使用USBNET模块接口的步骤，同时说明在使用过程中一些注意事项。 + +### 2.1.1 使用步骤 + +步骤1：从misc中导入USBNET包 + +```python +>>> from misc import USBNET +``` + + +步骤2：获取USB网卡工作模式 + +对于一块全新的模组，使用USBNET功能之前要先获取其工作模式，确认是用户想要使用的模式。 + +```python +>>> USBNET.get_worktype() +1 +``` + + + +步骤3：设置USB网卡工作模式 + +用户需要调用如下接口，设置自己需要的网卡工作模式(以RNDIS模式为例)： + +```python +>>> USBNET.set_worktype(USBNET.Type_RNDIS) +0 +``` + + +步骤4：重启模组 + +设置完USB网卡工作模式，需要重启模组使其生效： + +```python +>>> from misc import Power +>>> Power.powerRestart() +``` + + + +步骤5：打开USBNET功能 + +重启后之前设置的工作模式已生效，直接打开USBNET即可： + +```python +>>> from misc import USBNET +>>> USBNET.open() +``` + + + +### 2.1.2 示例代码 + +如下代码是一个完整的使用`USBNET`模块的例程： + +```python + +from misc import USBNET +from misc import Power + +#work on ECM mode default +USBNET.open() + +USBNET.set_worktype(USBNET.Type_RNDIS) + +#reset the module +Power.powerRestart() + +#after restart +from misc import USBNET + +#work on RNDIS mode +USBNET.open() +``` + + + +## 2.2 NAT相关设置 + +`USBNET.set_worktype()`接口调用的时候会使对应的`nat`值变为`1`，使得该`pid`无法`IPV6`拨号，所以在`close USBnet`后，可以使用该接口关闭`NAT`，使`IPV6`功能正常。 + +> 目前仅EC200U/EC600U系列支持此功能 + +### 2.2.1 获取NAT使能情况 + +获取某一路网卡的NAT使能情况（是否支持ipv6拨号）。命令如下： + +```python +USBNET.getNat(simid, pid) +``` + +参数说明： + +- `imid` - 整型值，范围0/1，目前仅支持`0`。 +- `pid` - 整型值，PDP索引，范围`1-7`。 + +返回值说明： + +成功：返回NAT使能情况，整型0/1，`0`：使能，支持ipv6拨号；`1`：未使能，不支持ipv6拨号。 +失败：返回整型`-1`。 + +### 2.2.2 NAT设置 + +NAT设置，设置成功后重启生效。命令为： + +```python +USBNET.setNat(simid, pid, nat) +``` + +参数说明： + +- `simid` - 整型值，范围0/1,目前仅支持0。 +- `pid` - 整型值，PDP索引, 范围1-7。 +- `Nat` - 整型值，范围：0/1,0：支持ipv6拨号；1：不支持ipv6拨号。 + +返回值说明： + +`0`表示设置成功，`-1`表示设置失败。 + +```python +USBNET.setNat(0, 1, 0) +0 +``` + + + -- Gitee