diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..1d4ab1622a96b1b03f7675c488bedf1f5c161dbc 100644 --- "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ucollections.md" @@ -0,0 +1,95 @@ + +# `ucollections` - 集合和容器类型 + +模块功能:ucollections 模块可以创建一个新的容器类型,用于保存各种对象。该模块实现了CPython模块相应模块的子集。更多信息请参阅阅CPython文档:[collections](https://docs.python.org/3/library/collections.html) + +## `ucollections`方法 +### `ucollections.namedtuple` + +```python +mytuple = ucollections.namedtuple(name, fields) +``` + +创建一个具有特定名称和一组字段的新`namedtuple`容器类型,`namedtuple`是元组的子类,允许通过索引来访问它的字段。 + +**参数描述:** + +- `name` - str类型,表示新建容器的类型名称 +- `fields` - tuple类型,表示新创建容器类型包含子类型的字段 + +**示例:** + +```python +>>> import ucollections +>>> mytuple = ucollections.namedtuple("mytuple", ("id", "name")) +>>> t1 = mytuple(1, "foo") +>>> t2 = mytuple(2, "bar") +>>> print(t1.name) +foo +``` + +### `ucollections.deque` + +```python +ucollections.deque(iterable, maxlen, flag) +``` + +创建`deque`双向队列 + +**参数描述:** + +- `iterable` - tuple类型,必须是一个空元组 +- `maxlen` - int类型,表示指定maxlen并将双端队列限制为此最大长度 +- `flag` - int类型,可选参数;0(默认):不检查队列是否溢出,达到最大长度时继续append会丢弃之前的值 ,1:当队列达到最大设定长度会抛出IndexError: full + +**返回值:** + +- deque对象 + + + +## deque对象方法 + +### `deque.append` + +```python +deque.append(data) +``` + +往队列中插入值。 + +**参数描述:** + +- `data` - 基本数据类型,表示需要添加到队列的数值 + + + +### `deque.popleft` + +```python +deque.popleft() +``` + +从`deque`的左侧移除并返回移除的数据。如果`deque`为空,会引起索引错误 + +**返回值:** + +- 返回pop出的值 + +**使用示例** + +```python +from ucollections import deque + +>>> dq = deque((),5) +>>> dq.append(1) +>>> dq.append(['a']) +>>> dq.append('a') + +>>> dq.popleft() +1 +>>> dq.popleft() +['a'] +>>> dq.popleft() +'a' +``` \ No newline at end of file diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" new file mode 100644 index 0000000000000000000000000000000000000000..b3cb0dc2a28f1a826c7f567d922fb08e560129a3 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/ustruct.md" @@ -0,0 +1,161 @@ + +# `ustruct` - 打包和解压原始数据类型 + +模块功能:`ustruct`模块实现相应CPython模块的子集。更多信息请参阅阅CPython文档:[struct](https://docs.python.org/3/library/struct.html) + + +## 格式字符串 + +格式字符串是用来在打包和解包数据时指定预期布局的机制。 其使用指定被打包/解包数据类型的`格式字符`进行构建。 此外,还有一些特殊字符用来控制`字节顺序`,`大小`和`对齐方式`。 + + +### **字节顺序,大小和对齐方式** + +默认情况下,C类型以机器的本机格式和字节顺序表示,并在必要时通过跳过填充字节来正确对齐(根据C编译器使用的规则)。根据下表,格式字符串的第一个字符可用于指示打包数据的字节顺序,大小和对齐方式: + +| Character | Byte order | Size | Alignment | +| --------- | ---------------------- | -------- | --------- | +| `@` | native | native | native | +| `=` | native | standard | none | +| `<` | little-endian | standard | none | +| `>` | big-endian | standard | none | +| `!` | network (= big-endian) | standard | none | + +> 如果第一个字符不是其中之一,则假定为 '@' 。 + + +### **格式化字符表** + +| Format | C Type | Python type | Standard size | +| ------ | -------------------- | ----------- | ------------- | +| `x` | `pad byte` | no value | | +| `c` | `char` | bytes of length 1 | 1 | +| `b` | `signed char` | integer | 1 | +| `B` | `unsigned char` | integer | 1 | +| `?` | `_Bool` | bool | 1 | +| `h` | `short` | integer | 2 | +| `H` | `unsigned short` | integer | 2 | +| `i` | `int` | integer | 4 | +| `I` | `unsigned int` | integer | 4 | +| `l` | `long` | integer | 4 | +| `L` | `unsigned long` | integer | 4 | +| `q` | `long long` | integer | 8 | +| `Q` | `unsigned long long` | integer | 8 | +| `n` | `ssize_t` | integer | | +| `N` | `size_t` | integer | | +| `e` | `` | float | 2 | +| `f` | `float` | float | 4 | +| `d` | `double` | float | 8 | +| `s` | `char[]` | bytes | | +| `p` | `char[]` | bytes | | +| `P` | `void *` | integer | 4 | + + +## `ustruct`方法 + +### `ustruct.calcsize` + +```python +ustruct.calcsize(fmt) +``` + +返回存放 `fmt` 需要的字节数。 + +**参数描述:** + +- `fmt` - 格式字符的类型,详情见上文格化式字符表 + +**示例:** + +```python +>>> import ustruct +>>> ustruct.calcsize('i') +4 +>>> ustruct.calcsize('f') +4 +>>> ustruct.calcsize('d') +8 +``` + + + +### `ustruct.pack` + +```python +ustruct.pack(fmt, v1, v2, ...) +``` + +按照格式字符串 `fmt` 压缩参数v1、 v2、…。 + +**参数描述:** + +- `fmt` - 格式字符的类型,详情见上文格化式字符表 + +**返回值描述:** + +- 返回参数编码后的字节对象。 + + + +### `ustruct.unpack` + +```python +ustruct.unpack(fmt, data) +``` + +根据格式化字符串 `fmt` 对数据进行解压,返回值为一个元组。 + +**参数描述:** + +- `fmt` - 格式字符的类型,详情见上文格化式字符表 +- `data` - 要进行解压的数据 + +**返回值描述:** + +- 返回包含解压值的元组(即使只包含一个项)。 + +**示例:** + +```python +>>> import ustruct +>>> ustruct.pack('ii', 7, 9) #打包两个整数 +b'\x07\x00\x00\x00\t\x00\x00\x00' +>>> ustruct.unpack('ii', b'\x07\x00\x00\x00\t\x00\x00\x00') #解压两个整数 +(7, 9) +``` + + + +### `ustruct.pack_into` + +```python +ustruct.pack_into(fmt, buffer, offset, v1, v2, ...) +``` + +根据格式字符串`fmt`将值v1、v2、 …打包到从`offset`开始的缓冲区中。从缓冲区的末尾算起,`offset`可能为负。 + +**参数描述:** + +- `fmt` - 格式字符的类型,详情见上文格化式字符表 +- `buffer` - 可写数据缓冲区 +- `offset` - 写入的起始位置 + + + +### `ustruct.unpack_from` + +```python +ustruct.unpack_from(fmt, data, offset=0) +``` + +根据格式化字符串 `fmt` 解析从 `offest` 开始的数据解压,从缓冲区末尾开始计数的偏移量可能为负值。 + +**参数描述:** + +- `fmt` - 格式字符的类型,详情见上文格化式字符表 +- `data` - 数据缓冲区(缓冲区大小以字节为单位) +- `offset` - 解压的起始位置 + +**返回值描述:** + +- 返回解压值的元组(即使只包含一个项)。 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" new file mode 100644 index 0000000000000000000000000000000000000000..58d0d839b5c44615cb3b999f88324ab79c4863d5 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.ESP8266.md" @@ -0,0 +1,251 @@ + +# `class ESP8266` - ESP8266无线网络控制 + +该类用于控制`ESP8266`型号无线网卡设备。 + +## 构造函数 + +### `ESP8266` + +```python +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升级`通知,默认为未开启。 + +**callback参数描述:** +- `content` - 用户回调,表示上报消息内容 + +**上报消息内容描述:** +- `ota`信息上报: + - `ota,begin` - ota升级开始 + - `ota,downloading,xx` - ota升级下载百分比 + - `ota,restart` - ota升级下载完成进行重启 + - `ota,err_code,1` - ota升级错误码 +- `station`网络连接变化上报: + - `station, connected` - wifi已连接 + - `station, disconnected` - wifi未连接 + + + +## 方法 + +### `ESP8266.status` + +```python +ESP8266.status() +``` + +获取无线网卡状态信息,用以判断无线网卡当前工作模式。 + +**返回值描述:** +- `0` - esp8266 设备不存在 +- `1` - esp8266 station模式已连接 +- `2` - esp8266 station模式未连接 +- `3` - esp8266 web配网模式 +- `4` - esp8266 ap模式 +- `5` - esp8266 ota升级中 + + + + +### `ESP8266.version` + +```python +ESP8266.version() +``` + +获取无线网卡当前固件版本信息 + +**返回值描述:** + +- 返回字符串,格式为(sdk, model, version, time),具体描述如下: + - `sdk` - sdk信息 + - `model` - 无线网卡型号 + - `version` - 版本号 + - `time` - 版本时间 + + + +### `ESP8266.ipconfig` + +```python +ESP8266.ipconfig() +``` + +获取网卡当前网络配置信息(IP地址、DNS服务器等信息) + +**返回值描述:** + + - 返回tuple类型,格式为 (ip, subnet, gateway, mtu, primary_dns, secondary_dns),具体描述如下: + + - `ip` - ip地址 + - `subnet` - 子网掩码 + - `gateway` - 网关 + - `mtu` - 最大传输单元 + - `primary_dns` - DNS服务器主地址 + - `secondary_dns` - DNS服务器辅地址 + + + +### `ESP8266.station` + +```python +ESP8266.station(username,password) +``` + +使无线网卡以`station`工作模式启动,连接指定wifi。 + +**参数描述:** + +- `username` - 填写所要连接的 `WiFi` 的名称(1~32 个字符) +- `password` - 填写所要连接的 `WiFi` 的密码(8~64 个字符) + +**返回值描述:** + +- 配置成功返回`0`,配置失败返回其他值。 + + + +### `ESP8266.ap` + +```python +ESP8266.ap(username,password) +``` + +使无线网卡以`ap`工作模式启动,作为无线热点。 + +**参数描述:** + +- `username` - 配置 `WiFi热点` 的名称(1~32 个字符) +- `password` - 配置 `WiFi热点` 的密码(8~64 个字符) + +**返回值描述:** + +- 配置成功返回`0`,配置失败返回其他值。 + + + +### `ESP8266.web_config` + +```python +ESP8266.web_config(username,password) +``` + +使无线网卡以`web 配网`工作模式启动,用户可通过web页面进行网络配置。 + +> 提示:启用配网功能后,需使用手机/电脑等终端设备通过无线网络连接至无线网卡(用户自定义名称和密码),然后通过浏览器输入192.168.4.1进入配网页面。 + +**参数描述:** + +- `username` - 配置 `配网热点` 的名称(1~32 个字符) +- `password` - 配置 `配网热点` 的密码(8~64 个字符) + +**返回值描述:** + +- 配置成功返回`0`,配置失败返回其他值。 + + + +### `ESP8266.ota` + +```python +ESP8266.ota(url) +``` + +开启`ota`后,网卡将更新新版本固件 + +> 注意:升级过程中只可查询当前状态,不可进行其他操作 + +**参数描述:** + +- `url` - 填写网址地址,表示固件下载地址,当前仅支持 http 协议,最长 256 字节。 + +**返回值描述:** + +- 执行成功返回`0`,执行失败返回其他值。 + +**示例:** + +```python + +url='http://www.example.com/fota.bin' + +esp8266.ota(url) + +``` + + + +### `ESP8266.stop` + +```python +ESP8266.stop() +``` + +释放掉为无线网卡所配置的虚拟网卡 + +**返回值描述:** + +- 释放成功返回`0`,释放失败返回其他值。 + + + +### `ESP8266.set_default_NIC` + +```python +ESP8266.set_default_NIC(ip_str) +``` + +指定网卡进行网络转发 + +**参数描述:** + +- `ip_str` - 所要设置默认转发网卡的网卡 ip 地址,如:'192.168.1.100' + +**返回值描述:** + +- 配置成功返回`0`,配置失败返回其他值。 + + + +### `ESP8266.set_dns` + +```python +ESP8266.set_dns(pri_dns, sec_dns) +``` + +指定无线网卡的`dns`服务器进行地址解析 + +**参数描述:** + +- `pri_dns` - 设置无线网卡的`首选 dns` 服务器,默认为 `8.8.8.8` +- `sec_dns` - 设置无线网卡的`备选 dns` 服务器,默认为 `114.114.114.114` + +**返回值描述:** + +- 配置成功返回`0`,配置失败返回其他值。 + + + +### `ESP8266.router_add` + +```python +ESP8266.router_add(ip, mask) +``` + +设置无线网卡路由转发规则 + +**参数描述:** + +- `ip` - 设置 `ap` 模式的网段,默认为 192.168.4.1 +- `mask` - 设置子网掩码,默认为 255.255.255.0 + +**返回值描述:** + +- 配置成功返回`0`,配置失败返回其他值。 diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.md" new file mode 100644 index 0000000000000000000000000000000000000000..677c109957577bcae87e75e3d1f36127d15368ca --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/WLAN.md" @@ -0,0 +1,115 @@ + +# `WLAN` - 无线局域网相关功能 + +`WLAN`模块包含无线局域网控制及网络配置功能。主要是针对不同类型无线网卡提供统一的管理方式。 + +> 当前仅支持ESP8266无线网卡 + +**示例:** + +以ESP8266为例,根据不同应用场景,分别展示以`station`模式、`ap`模式、`web配网`模式下无线网卡初始化使用过程。 + +**station客户端模式:** +```python +# 在station工作模式下,无线网卡连接路由器的WiFi,由路由器分配IP等信息,使模组通过无线网卡连接外部网络。 +>>> from usr.WLAN import ESP8266 +>>> from machine import UART + + +# 加载ESP8266网卡驱动,并初始化网卡相关配置 +>>> ESP8266 = ESP8266(UART.UART2, ESP8266.STA) + +# 配置无线网卡以station模式启动并连接WiFi热点 +>>> ESP8266.station('wifiname','wifipassword') +0 + +# 查看无线网卡的IP信息 +>>> ESP8266.ipconfig() + ('172.16.1.2', '255.255.255.0', '172.16.1.1', 1500, '0.0.0.0', +'0.0.0.0') + +# 配置DNS服务器 +>>> ESP8266.set_dns('8.8.8.8','114.114.114.114') +0 + +# 查看无线网卡的IP信息,可以看到DNS已被配置成功 +>>> ESP8266.ipconfig() +('172.16.1.2', '255.255.255.0', '172.16.1.1', 1500, '8.8.8.8', +'114.114.114.114') + +# 设置无线网卡作为默认网卡,使用无线网卡进行网络通信 +>>> ESP8266.set_default_NIC('172.16.1.2') +0 + +# 获取当前网卡状态 返回“1”说明无线网卡已连接WiFi,返回“2”说明未连接WiFi +>>> ESP8266.status() +1 + +# 此时可以启动其他网络服务,并通过无线网络进行网络访问 +``` + + + +**AP接入点模式:** +```python +# 在ap工作模式下,无线网卡开启ap热点,使用模组的4G网络 连接外网,并为连接到热点的终端设备分配IP信息,其他终端设备即可连接外部网络。 +>>> from usr.WLAN import ESP8266 +>>> from machine import UART +>>> import dataCall + + +# 加载ESP8266网卡驱动,并初始化网卡相关配置 +>>> ESP8266 = ESP8266(UART.UART2, ESP8266.AP) + +# 配置无线网卡以ap模式启动WiFi热点 +>>> ESP8266.ap('wifiname','wifipassword') +0 + +#获取拨号信息 +>>> Info = dataCall.getInfo(1,0) + +#设置默认网卡,ap模式下设置4G为默认网卡 +>>> ESP8266.set_default_NIC(Info[2][2]) +0 + +#添加路由信息,设置网卡转发规则 +>>> ESP8266.router_add('192.168.4.0', '255.255.255.0') +0 + +# 获取当前网卡状态 返回“4”说明无线网卡已启用ap热点模式 +>>> ESP8266.status() +4 + +# 此时可用其他终端设备连接ap热点,进行网络访问 +``` + + + +**web配网模式:** +```python +# 在web配网模式下,可以使用手机等设备连接无线网卡的WiFi热点,通过浏览器进入web页面,配置无线网卡的网络信息。 +>>> from usr.WLAN import ESP8266 +>>> from machine import UART + + +# 初始化网卡,若使用web配置ap模式,需把模式字段设置为ESP8266.AP +>>> ESP8266 = ESP8266(UART.UART2, ESP8266.STA) + +# 获取当前网卡状态 +>>> ESP8266.status() +1 + +# 配置web配网模式热点的信息 +>>> ESP8266.web_config('admin','adminpwd') +0 + +# 获取当前网卡状态 返回“3”表示web配网已启用,可以使用web配网模式 +>>> ESP8266.status() +3 + +# 此时可用其他终端设备连接热点,登录web界面进行网络配置 +``` + + +## Classes +- [class ESP8266 – ESP8266驱动](./WLAN.ESP8266.md) \ No newline at end of file