diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/math.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/math.md" new file mode 100644 index 0000000000000000000000000000000000000000..a24c1fed74e866a51dce2ba46084a4b71fe300e2 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/math.md" @@ -0,0 +1,802 @@ +# `math` - 数学运算 + +math 模块提供数学运算函数。该模块实现相应CPython模块的子集。更多信息请参阅阅CPython文档：[math](https://docs.python.org/3.5/library/math.html#module-math) + +## 返回x的y次方 + +### `math.pow` + +```python +math.pow(x, y) +``` + +返回x的y次方 + +**参数描述** + +* `x`：浮点数 +* `y`：浮点数 + +**返回值描述** +浮点数：`x`的 `y`次方 + +**示例：** + +``` +>>> import math +>>> math.pow(2, 3) +8.0 +``` + +## 返回x的反余弦弧度值 + +### `math.acos` + +```python +math.acos(x) +``` + +返回x的反余弦弧度值 + +**参数描述** + +* `x`：浮点数，是-1~1之间的数，包括-1和1，如果小于-1或者大于1，会产生错误。 + +**返回值描述** +浮点数：`x`的反余弦弧度值 + +**示例：** + +``` +>>> import math +>>> math.acos(0.6) +0.9272952 +``` + +## 返回x的反正弦弧度值 + +### `math.asin` + +```python +math.asin(x) +``` + +返回x的反正弦弧度值 + +**参数描述** + +* `x`：浮点数，是-1~1之间的数，包括-1和1，如果小于-1或者大于1，会产生错误。 + +**返回值描述** +浮点数：`x`的反正弦弧度值 + +**示例**： + +``` +>>> import math +>>> math.asin(-1) +-1.570796 +``` + +## 返回x的反正切弧度值 + +### `math.atan` + +```python +math.atan(x) +``` + +返回x的反正切弧度值 + +**参数描述** + +* `x`：浮点数 + +**返回值描述** +浮点数：`x`的反正切弧度值 + +**示例：** + +``` +>>> import math +>>> math.atan(-8) +-1.446441 +>>> math.atan(6.4) +1.4158 +``` + +## 返回给定的 X 及 Y 坐标值的反正切值 + +### `math.atan2` + +```python +math.atan2(x, y) +``` + +返回给定的 X 及 Y 坐标值的反正切值 + +**参数描述** + +* `x`：浮点数 +* `y`：浮点数 + +**返回值描述** +浮点数：坐标 (`x` ,`y`)的反正切值 + +**示例：** + +``` +>>> import math +>>> math.atan2(-0.50,0.48) +-0.8058035 +>>> math.atan2(7, 9) +0.6610432 +``` + +## 返回数字的上入整数 + +### `math.ceil` + +```python +math.ceil(x) +``` + +返回数字的上入整数 + +**参数描述** + +* `x`：浮点数 + +**返回值描述** +整数：`x`的上入整数 + +**示例：** + +``` +>>> import math +>>> math.ceil(4.1) +5 +``` + +## 把y的正负号加到x前面 + +### `math.copysign` + +```python +math.copysign(x, y) +``` + +把y的正负号加到x前面 + +**参数描述** + +* `x`：浮点数 +* `y`：浮点数 + +**返回值描述** +浮点数，把 `y`的正负号加到 `x`前面 + +**示例：** + +``` +>>> import math +>>> math.copysign(5, 0) +5.0 +>>> math.copysign(5, -4) +-5.0 +>>> math.copysign(5, 9) +5.0 +``` + +## 返回x的弧度的余弦值 + +### `math.cos` + +```python +math.cos(x) +``` + +返回x的弧度的余弦值 + +**参数描述** + +* `x`：浮点数 + +**返回值描述** +浮点数，`x`的弧度的余弦值，范围-1~1之间 + +**示例：** + +```python +>>> import math +>>> math.cos(3) +-0.9899925 +``` + +## 将弧度转换为角度 + +### `math.degrees` + +```python +math.degrees(x) +``` + +将弧度转换为角度 + +**参数描述** + +* `x`：浮点数 + +**返回值描述** +浮点数，弧度 `x`转换为角度 + +**示例：** + +``` +>>> import math +>>> math.degrees(5) +286.4789 +>>> math.degrees(math.pi/2) +90.0 +``` + +## 数学常量 `e` + +### `math.e` + +数学常量 `e`，`e`即自然常数。 + +## 返回e的x次幂 + +### `math.exp` + +```python +math.exp(x) +``` + +返回e的x次幂 + +**参数描述** + +* `x`：浮点数 + +**返回值描述** +浮点数，`e`的 `x`次幂 + +**示例：** + +``` +>>> import math +>>> math.exp(1) +2.718282 +>>> print(math.e) +2.718282 +``` + +## 返回数字的绝对值 + +### `math.fabs` + +```python +math.fabs(x) +``` + +返回数字的绝对值 + +**参数描述** + +* `x`：浮点数 + +**返回值描述** +浮点数，`x`的绝对值 + +**示例：** + +``` +>>> import math +>>> math.fabs(-3.88) +3.88 +``` + +## 返回数字的下舍整数 + +### `math.floor` + +```python +math.floor(x) +``` + +返回数字的下舍整数 + +**参数描述** + +* `x`：浮点数 + +**返回值描述** +浮点数，`x`的下舍整数 + +**示例：** + +``` +>>> import math +>>> math.floor(8.7) +8 +>>> math.floor(9) +9 +>>> math.floor(-7.6) +-8 +``` + +## 返回x/y的余数 + +### `math.fmod` + +```python +math.fmod(x, y) +``` + +返回x/y的余数 + +**参数描述** + +* `x`：浮点数 +* `y`：浮点数 + **返回值描述** + `x`/`y`的余数，浮点数 + +**示例：** + +``` +>>> import math +>>> math.fmod(15, 4) +3.0 +>>> math.fmod(15, 3) +0.0 +``` + +## 返回由x的小数部分和整数部分组成的元组 + +### `math.modf` + +```python +math.modf(x) +``` + +返回由x的小数部分和整数部分组成的元组。 + +**参数描述** + +* `x`：浮点数 + **返回值描述** + `x`/`y`的余数，浮点数 + +**示例：** + +``` +>>> import math +>>> math.modf(17.592) +(0.5919991, 17.0) +``` + +## 返回一个元组(m,e) + +### `math.modf` + +```python +math.modf(x) +``` + +返回一个元组(m,e) + +**参数描述** + +* `x`：浮点数 + **返回值描述** + 返回一个元组 `(m,e)`,其计算方式为：`x`分别除0.5和1,得到一个值的范围，`2e`的值在这个范围内，`e`取符合要求的最大整数值,然后 `x/(2e)`，得到 `m`的值。如果 `x`等于0，则 `m`和 `e`的值都为0，`m`的绝对值的范围为(0.5,1)之间，不包括0.5和1。 + +**示例：** + +``` +>>> import math +>>> math.frexp(52) +(0.8125, 6) +``` + +## 判断 x 是否为有限数 + +### `math.isfinite` + +```python +math.isfinite(x) +``` + +判断 x 是否为有限数 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +判断 `x` 是否为有限数，是则返回 `True`，否则返回 `False`。 + +**示例：** + +``` +>>> import math +>>> math.isfinite(8) +True +``` + +## 判断是否无穷大或负无穷大 + +### `math.isinf` + +```python +math.isinf(x) +``` + +判断是否无穷大或负无穷大 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +如果 `x`是正无穷大或负无穷大，则返回 `True`,否则返回 `False`。 + +**示例：** + +``` +>>> import math +>>> math.isinf(123) +False +``` + +## 判断是否数字 + +### `math.isnan` + +```python +pymath.isnan(x) +``` + +判断是否数字 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +如果 `x`不是数字，返回 `True`,否则返回 `False`。 + +**示例：** + +``` +>>> import math +>>> math.isnan(23) +False +``` + +## 返回x*(2**i)的值 + +### `math.ldexp` + +```python +math.ldexp(x, exp) +``` + +**返回x*(2**i)的值 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +浮点数，返回 `x`*(2**i)的值。 + +**示例：** + +``` +>>> import math +>>> math.ldexp(2, 1) +4.0 +``` + +## 返回x的自然对数 + +### `math.log` + +```python +math.log(x) +``` + +返回x的自然对数 + +**参数描述** + +* `x`,浮点数，小于0会报错 + +**返回值描述** + +浮点数，返回 `x`的自然对数 + +**示例：** + +``` +>>> import math +>>> math.log(2) +0.6931472 +``` + +## 数学常量 pi + +### `math.pi` + +数学常量 pi（圆周率，一般以π来表示）。 + +## 将角度转换为弧度 + +### `math.radians` + +```python +math.radians(x) +``` + +将角度转换为弧度 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +浮点数，将角度 `x`转换为弧度 + +**示例：** + +``` +>>> import math +>>> math.radians(90) +1.570796 +``` + +## 返回x弧度的正弦值 + +### `math.sin` + +```python +math.sin(x) +``` + +返回x弧度的正弦值 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +返回 `x`弧度的正弦值，数值在 -1 到 1 之间。 + +**示例：** + +``` +>>> import math +>>> math.sin(-18) +0.7509873 +>>> math.sin(50) +-0.2623749 +``` + +## 返回数字x的平方根 + +### `math.sqrt` + +```python +math.sqrt(x) +``` + +返回x弧度的平方根 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +返回数字 `x`的平方根，返回值为浮点数。 + +**示例：** + +``` +>>> import math +>>> math.sqrt(4) +2.0 +>>> math.sqrt(7) +2.645751 +``` + +## 返回 x 弧度的正切值 + +### `math.tan` + +```python +math.tan(x) +``` + +返回 x 弧度的正切值 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +返回 `x` 弧度的正切值，数值在 -1 到 1 之间，为浮点数。 + +**示例：** + +``` +>>> import math +>>> math.tan(9) +-0.4523157 +``` + +## 返回x的整数部分 + +### `math.trunc` + +```python +math.trunc(x) +``` + +返回x的整数部分 + +**参数描述** + +* `x`,浮点数 + +**返回值描述** + +返回x的整数部分，为整数。 + +**示例：** + +``` +>>> import math +>>> math.trunc(7.123) +7 +``` + +**使用示例** + +```python +# 数学运算math函数示例 + +import math +import log +import utime + + +''' +下面两个全局变量是必须有的，用户可以根据自己的实际项目修改下面两个全局变量的值 +''' +PROJECT_NAME = "QuecPython_Math_example" +PROJECT_VERSION = "1.0.0" + + +if __name__ == '__main__': + # 设置日志输出级别 + log.basicConfig(level=log.INFO) + math_log = log.getLogger("Math") + + # x**y运算后的值 + result = math.pow(2,3) + math_log.info(result) + # 8.0 + + # 取大于等于x的最小的整数值，如果x是一个整数，则返回x + result = math.ceil(4.12) + math_log.info(result) + # 5 + + # 把y的正负号加到x前面，可以使用0 + result = math.copysign(2,-3) + math_log.info(result) + # -2.0 + + # 求x的余弦，x必须是弧度 + result = math.cos(math.pi/4) + math_log.info(result) + # 0.7071067811865476 + + # 把x从弧度转换成角度 + result = math.degrees(math.pi/4) + math_log.info(result) + # 45.0 + + # e表示一个常量 + result = math.e + math_log.info(result) + # 2.718281828459045 + + # exp()返回math.e(其值为2.71828)的x次方 + result = math.exp(2) + math_log.info(result) + # 7.38905609893065 + + # fabs()返回x的绝对值 + result = math.fabs(-0.03) + math_log.info(result) + # 0.03 + + # floor()取小于等于x的最大的整数值，如果x是一个整数，则返回自身 + result = math.floor(4.999) + math_log.info(result) + # 4 + + # fmod()得到x/y的余数，其值是一个浮点数 + result = math.fmod(20,3) + math_log.info(result) + # 2.0 + + # frexp()返回一个元组(m,e),其计算方式为：x分别除0.5和1,得到一个值的范围，2e的值在这个范围内，e取符合要求的最大整数值,然后x/(2e),得到m的值。如果x等于0,则m和e的值都为0,m的绝对值的范围为(0.5,1)之间，不包括0.5和1 + result = math.frexp(75) + math_log.info(result) + # (0.5859375, 7) + + # isfinite()如果x不是无穷大的数字,则返回True,否则返回False + result = math.isfinite(0.1) + math_log.info(result) + # True + + # isinf()如果x是正无穷大或负无穷大，则返回True,否则返回False + result = math.isinf(234) + math_log.info(result) + # False + + # isnan()如果x不是数字True,否则返回False + result = math.isnan(23) + math_log.info(result) + # False + + # ldexp()返回x*(2**i)的值 + result = math.ldexp(5,5) + math_log.info(result) + # 160.0 + + # modf()返回由x的小数部分和整数部分组成的元组 + result = math.modf(math.pi) + math_log.info(result) + # (0.14159265358979312, 3.0) + + # pi:数字常量，圆周率 + result = math.pi + math_log.info(result) + # 3.141592653589793 + + # sin()求x(x为弧度)的正弦值 + result = math.sin(math.pi/4) + math_log.info(result) + # 0.7071067811865476 + + # sqrt()求x的平方根 + result = math.sqrt(100) + math_log.info(result) + # 10.0 + + # tan()返回x(x为弧度)的正切值 + result = math.tan(math.pi/4) + math_log.info(result) + # 0.9999999999999999 + + # trunc()返回x的整数部分 + result = math.trunc(6.789) + math_log.info(result) + # 6 + +``` diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/sys.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/sys.md" new file mode 100644 index 0000000000000000000000000000000000000000..299751163836a1fa406ae85f08e04068f4e5a938 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/sys.md" @@ -0,0 +1,89 @@ +# `sys` - 系统相关功能 + +> 新架构代码升级了MPY的版本，sys变更为usys。导入模块时建议使用以下方式进行导入 + +```python +try: + import usys as sys +except ImportError: + import sys +``` + +## 常数说明 + +### `sys.argv` + +当前程序启动的可变参数列表。 + +### `sys.byteorder` + +字节顺序 (‘little’ - 小端， ‘big’ - 大端)。 + +### `sys.implementation` + +返回当前microPython版本信息。对于MicroPython，它具有以下属性： + +- name - 字符串“ micropython” +- version - 元组（主要，次要，微型），例如（1、7、0） + +建议使用此对象来将MicroPython与其他Python实现区分开。 + +### `sys.maxsize` + +本机整数类型可以在当前平台上保留的最大值，如果它小于平台最大值，则为MicroPython整数类型表示的最大值（对于不支持长整型的MicroPython端口就是这种情况）。 + +### `sys.modules` + +已载入模块的字典。 + +### `sys.platform` + +MicroPython运行的平台。 + +### `sys.stdin` + +标准输入（默认是USB虚拟串口，可选其他串口）。 + +### `sys.stdout` + +标准输出（默认是USB虚拟串口，可选其他串口）。 + +### `sys.version` + +MicroPython 语言版本，字符串格式。 + +### `sys.version_info` + +MicroPython 语言版本，整数元组格式。 + +## **方法** + +### `sys.exit` + +```python +sys.exit(retval=0) +``` + +使用给定的参数退出当前程序。 + +**参数描述** + +* `retval`，int型，退出参数 + +**返回值描述** + +该函数会引发 `SystemExit`退出。如果给定了参数，则将其值作为参数赋值给 `SystemExit`。 + +### `sys.print_exception` + +```python +sys.print_exception(exc, file=sys.stdout) +``` + +打印异常到文件对象，默认是 sys.stdout，即输出异常信息的标准输出。 + +**参数描述** + +* `exc`，exception对象 + +* `file`，指定输出文件，默认为sys.stdout diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/uos.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/uos.md" index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..4f5c55dd9a1d96b8cd00a5308d6db1f6d0f0292d 100644 --- "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/uos.md" +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/uos.md" @@ -0,0 +1,551 @@ +# `uos` - 基本系统服务 + +`uos`模块包含文件系统访问和挂载构建，该模块实现了CPython模块相应模块的子集。更多信息请参阅阅CPython文档：[os](https://docs.python.org/3.5/library/os.html#module-os) + +## 删除文件 + +### `uos.remove` + +```python +uos.remove(path) +``` + +删除文件。 + +**参数描述** + +* `path`，字符串，表示文件名。 + +## 改变当前目录 + +### `uos.chdir` + +```python +uos.chdir(path) +``` + +改变当前目录。 + +**参数描述** + +* `path`，字符串，表示目录名。 + +## 获取当前路径 + +### `uos.getcwd` + +```python +uos.getcwd() +``` + +获取当前路径。 + +**返回值描述** + +字符串，当前路径 + +## 列出指定目录文件 + +### `uos.listdir` + +```python +uos.listdir( [dir] ) +``` + +没有参数列出当前目录文件，否则列出给定目录的文件。 + +**参数描述** + +* `dir`为字符串，可选参数，表示目录名，默认为 ‘/’ 目录。 + +**返回值描述** + +元组，列出路径下所有存在的对象（目录&文件） + +**示例：** + +```python +>>> uos.listdir() +[‘file1’, ‘read.txt’, ‘demo.py’] +``` + +## 创建新目录 + +### `uos.mkdir` + +``` +uos.mkdir(path) +``` + +创建一个新的目录。 + +**参数描述** + +* `path`表示准备创建的目录名。 + +**示例：** + +```python +>>> uos.mkdir('testdir') +>>> uos.listdir() +[‘file1’, ‘read.txt’, ‘demo.py’, 'testdir'] +``` + +## 重命名文件 + +### `uos.rename` + +```python +uos.rename(old_path, new_path) +``` + +重命名文件。 + +**参数描述** + +* `old_path`，字符串，表示旧文件或目录名， +* `new_path`，字符串，表示新文件或目录名。 + +**示例：** + +```python +>>> uos.rename('testdir', 'testdir1') +``` + +## 删除指定目录 + +### `uos.rmdir` + +```python +uos.rmdir(path) +``` + +删除指定目录。 + +**参数描述** + +* `path`，字符串，表示目录名。 + +**示例：** + +```python +>>> uos.rmdir('testdir') +>>> uos.listdir() +[‘file1’, ‘read.txt’, ‘demo.py’] +``` + +## 列出当前目录参数 + +### `uos.ilistdir` + +```python +uos.ilistdir( [dir] ) +``` + +该函数返回一个迭代器，该迭代器会生成所列出条目对应的3元组。 + +**参数描述** + +* `dir`为可选参数，字符串，表示目录名，没有参数时，默认列出当前目录，有参数时，则列出dir参数指定的目录。 + +**返回值描述** + +返回一个迭代器，该迭代器会生成所列出条目对应的3元组 + +元组的形式为 `(name, type, inode[, size])`: + +* `name` 是条目的名称，字符串类型，如果dir是字节对象，则名称为字节; +* `type` 是条目的类型，整型数，0x4000表示目录，0x8000表示常规文件； +* `inode`是一个与文件的索引节点相对应的整数，对于没有这种概念的文件系统来说，可能为0； +* 一些平台可能会返回一个4元组，其中包含条目的size。对于文件条目，size表示文件大小的整数，如果未知，则为-1。对于目录项，其含义目前尚未定义。 + +## 获取文件或目录的状态 + +### `uos.stat` + +```python +uos.stat(path) +``` + +获取文件或目录的状态。 + +**参数描述** + +* `path`，字符串，表示文件或目录名。 + +**返回值描述** + +返回值是一个元组，返回值形式为： + +`(mode, ino, dev, nlink, uid, gid, size, atime, mtime, ctime)` + +* `mode` – inode保护模式 +* `ino` – inode节点号 +* `dev` – inode驻留的设备 +* `nlink` – inode的链接数 +* `uid ` – 所有者的用户ID +* `gid` – 所有者的组ID +* `size` – 文件大小，单位字节 +* `atime` – 上次访问的时间 +* `mtime` – 最后一次修改的时间 +* `ctime` – 操作系统报告的“ctime”，在某些系统上是最新的元数据更改的时间，在其它系统上是创建时间，详细信息参见平台文档 + +## 获取文件系统状态信息 + +### `uos.statvfs` + +```python +uos.statvfs(path) +``` + +获取文件系统状态信息。 + +**参数描述** + +* `path`，字符串，表示文件或目录名。 + +**返回值描述** + +返回一个包含文件系统信息的元组： + +`(f_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax)` + +* `f_bsize` – 文件系统块大小，单位字节 +* `f_frsize` – 分栈大小，单位字节 +* `f_blocks` – 文件系统数据块总数 +* `f_bfree` – 可用块数 +* `f_bavai` – 非超级用户可获取的块数 +* `f_files` – 文件结点总数 +* `f_ffree` – 可用文件结点数 +* `f_favail` – 超级用户的可用文件结点数 +* `f_flag` – 挂载标记 +* `f_namemax` – 最大文件长度，单位字节 + +**示例：** + +```python +>>> import uos +>>> res = uos.statvfs("main.py") +>>> print(res) +(4096, 4096, 256, 249, 249, 0, 0, 0, 0, 255) +``` + +## 获取关于底层信息或其操作系统的信息 + +### `uos.uname` + +```python +uos.uname() +``` + +获取关于底层信息或其操作系统的信息。 + +**返回值描述** + +该接口与micropython官方接口返回值形式有所区别，返回一个元组，形式为： + +`(sysname, nodename, release, version, machine)` + +* `sysname` – 底层系统的名称，string类型 +* `nodename` – 网络名称(可以与 sysname 相同) ，string类型 +* `release` – 底层系统的版本，string类型 +* `version` – MicroPython版本和构建日期，string类型 +* `machine` – 底层硬件(如主板、CPU)的标识符，string类型 +* `qpyver` – QuecPython 短版本号，string类型 + +**示例：** + +```python +>>> import uos +>>> uos.uname() +('sysname=EC600S-CNLB', 'nodename=EC600S', 'release=1.12.0', 'version=v1.12 on 2020-06-23', 'machine=EC600S with QUECTEL', 'qpyver=V0001') +>>> uos.uname()[0].split('=')[1] # 可通过这种方式来获取sysname的值 +'EC600S-CNLB' +``` + +### `uos.uname2` + +```python +uos.uname2() +``` + +获取关于底层信息或其操作系统的信息。 + +**返回值描述** + +该接口与micropython官方接口返回值形式一致。注意与上面uos.uname()接口返回值的区别，返回值形式为： + +`(sysname, nodename, release, version, machine, qpyver=)` + +* `sysname` – 底层系统的名称，string类型 +* `nodename` – 网络名称(可以与 sysname 相同) ，string类型 +* `release` – 底层系统的版本，string类型 +* `version` – MicroPython版本和构建日期，string类型 +* `machine` – 底层硬件(如主板、CPU)的标识符，string类型 +* `qpyver` – QuecPython 短版本号，string类型 + +**示例：** + +```python +>>> import uos +>>> uos.uname2() +(sysname='EC600S-CNLB', nodename='EC600S', release='1.12.0', version='v1.12 on 2020-06-23', machine='EC600S with QUECTEL', qpyver='V0001') +>>> uos.uname2().sysname # 可通过这种方式直接获取sysname的值 +'EC600S-CNLB' +>>> uos.uname2().machine +'EC600S with QUECTEL' +``` + +## 返回具有*n个*随机字节的bytes对象 + +### `uos.urandom` + +```python +uos.urandom(n) +``` + +返回具有*n个*随机字节的bytes对象，只要有可能，它就会由硬件随机数生成器生成。 + +**参数描述** + +* `n`，整形，随机字节的个数 + +**返回值描述** + +具有*n个*随机字节的bytes对象 + +**示例：** + +```python +>>> import uos +>>> uos.urandom(5) +b'\xb3\xc9Y\x1b\xe9' +``` + +## 注册存储设备 - SPI - SD卡 + +> 目前仅EC600N/EC800N平台支持。 + +### `uos.VfsFat` + +```python +uos.VfsFat(spi_port, spimode, spiclk, spics) +``` + +初始化SD卡，和SD卡通信。使用SPI通信方式。 + +**参数描述** + +* `spi_port`，int，通道选择[0,1] +* `spimode`，int，PI 的工作模式(模式0最常用):`
`0 : CPOL=0, CPHA=0 1 : CPOL=0, CPHA=12: CPOL=1, CPHA=0 3: CPOL=1, CPHA=1 + +> 时钟极性CPOL: 即SPI空闲时，时钟信号SCLK的电平（0:空闲时低电平; 1:空闲时高电平） + +* `spiclk`， int， 时钟频率 0 : 812.5kHz 1 : 1.625MHz 2 : 3.25MHz 3 : 6.5MHz 4 : 13MHz +* `spics`，int，指定CS片选引脚为任意GPIO，硬件CS可以接这里指定的脚，也可以接默认的SPI CS脚 + +> 1-n:指定Pin.GPIO1-Pin.GPIOn为CS脚 + +**返回值描述** + +成功则返回VfsFat object，失败则会卡住。 + +**示例：** + +```python +>>> cdev = uos.VfsFat(1, 0, 4, 1) +``` + +## 注册存储设备 - SDIO - SD卡 + +> 目前仅EC600U/EC200U平台支持。 + +### `uos.VfsSd` + +```python +uos.VfsSd(str) +``` + +初始化SD卡，使用SDIO通信方式。 + +**参数描述** + +* `str`，str， 传入"sd_fs" + +**返回值描述** + +成功则返回vfs object，失败则会报错。 + +**引脚说明** + +| 平台 | 引脚 | +| ------ | --------------------------------------------------------------------------------------------------------------- | +| EC600U | CMD:引脚号48
DATA0:引脚号39
DATA1:引脚号40
DATA2:引脚号49
DATA3:引脚号50
CLK:引脚号132 | +| EC200U | CMD:引脚号33
DATA0:引脚号31
DATA1:引脚号30
DATA2:引脚号29
DATA3:引脚号28
CLK:引脚号32 | + +**示例：** + +```python +>>> from uos import VfsSd +>>> udev = VfsSd("sd_fs") +``` + +## 设置SD卡检测管脚 + +### `uos.set_det` + +```python +uos.set_det(vfs_obj.GPIOn,mode) +``` + +指定sd卡插拔卡的检测管脚和模式。 + +**参数描述** + +* `vfs_obj.GPIOn`，int类型，用于sd卡插拔卡检测的GPIO引脚号，参照Pin模块的定义 +* `mode`，int类型 `
0`:sd卡插上后，检测口为低电平；sd卡取出后，检测口为高电平 `
1`:sd卡插上后，检测口为高电平；sd卡取出后，检测口为低电平 + +**返回值描述** + +成功返回 `0`，失败返回 `-1`。 + +**示例：** + +```python +>>> from uos import VfsSd +>>> udev = VfsSd("sd_fs") +>>> uos.mount(udev, '/sd') +>>> udev.set_det(udev.GPIO10,0)#使用GPIO10作为卡检测管脚，sd卡插上，检测口为低电平，sd卡取出，检测口为高电平（实际使用根据硬件） +``` + +## 设置插拔SD卡回调函数 + +### `uos.set_callback` + +```python +uos.set_callback(fun) +``` + +设定发生插拔卡事件时的用户回调函数。 + +**参数描述** + +* `fun`，function类型，插拔卡回调 `[ind_type]` +* `ind_type`: 事件类型，0：拔卡 1：插卡 + +**返回值描述** + +成功返回 `0`，失败返回 `-1`。 + +**SD卡使用示例（SDIO接口）** + +> 目前仅EC600U/EC200U平台支持。 + +**示例：** + +```python +from uos import VfsSd +import ql_fs +udev = VfsSd("sd_fs") +uos.mount(udev, '/sd') +udev.set_det(udev.GPIO10,0) +#文件读写 +f = open('/sd/test.txt','w+') +f.write('1234567890abcdefghijkl') +f.close() +uos.listdir('/sd') +f = open('/sd/test.txt','r') +f.read() +f.close() +#插拔卡回调函数 +def call_back(para): + if(para == 1): + print("insert") + print(uos.listdir('/usr')) + print(ql_fs.file_copy('/usr/1.txt','/sd/test.txt'))#复制sd卡里的test.txt内容到usr下的1.txt中 + print(uos.listdir('/usr')) + elif(para == 0): + print("plug out") + +udev.set_callback(call_back) +``` + +## 注册littleFS存储设备 - SPI NOR FLASH + +> 目前仅EG915U/EC600N支持 + +### `uos.VfsLfs1` + +```python +uos.VfsLfs1(readsize,progsize,lookahead,pname,spi_port,spi_clk) +``` + +初始化spi nor flash,和外挂nor flash通信。使用SPI通信方式,将此存储设备挂载为littleFS文件系统。 + +**参数描述** + +* readsize，int类型，预留，暂未使用 +* progsize，int类型，预留，暂未使用 +* lookahead，int类型，预留，暂未使用 +* pname，str类型，固定为“ext_fs”。后续扩展 +* spi_port，int类型，支持的端口参照SPI章节说明 +* spi_clk，int类型 `
`时钟频率：`
`0：6.25M 1:12.5M 2:25M 3:50M 4:3.125M 5:1.5625M 6:781.25K + +**返回值描述** + +成功则返回VfsLfs1 object,失败则 OSError 19。 + +**示例：** + +```python +>>>ldev = uos.VfsLfs1(32, 32, 32, "ext_fs",1,0) +>>>uos.mount(ldev,'/ext') +>>>f = open('/ext/test.txt','w+') +>>>f.write('hello world!!!') +>>>f.close() + +>>>uos.listdir('ext') + +>>>f = open('/ext/test.txt','r') +>>>f.read() +>>>f.close() + +``` + +## 挂载文件系统 + +### `uos.mount` + +```python +uos.mount(vfs_obj, path) +``` + +挂载实体文件系统(如littleFS/FATFS等)到虚拟文件系统(VFS)。 + +**参数描述** + +* vfs_obj，vfs object，文件系统对象 +* path，str类型，文件系统的根目录 + +**示例：** + +```python +>>> cdev = uos.VfsFat(1, 0, 4, 1) +>>> uos.mount(cdev, '/sd') +``` + +**SD卡（SPI接口）使用示例:** + +> 目前仅EC600N/EC800N/EC600U/EC200U平台支持。 + +```python +>>> cdev = uos.VfsFat(1, 0, 4, 1) +>>> uos.mount(cdev, '/sd') +>>> f = open('/sd/test.txt','w+') +>>> f.write('0123456') +>>> f.close() +>>> uos.listdir('/sd') +>>> f = open('/sd/test.txt','r') +>>> f.read() +>>> f.close() +``` diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/urandom.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/urandom.md" index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..c7625bf803bc11424b827ee636e1addd527b6cab 100644 --- "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/urandom.md" +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/urandom.md" @@ -0,0 +1,266 @@ +# `urandom` - 生成随机数 + +urandom 模块提供了生成随机数的工具。 + +## 随机生成对象 obj 中的元素 + +### `urandom.choice` + +```python +urandom.choice(obj) +``` + +随机生成对象 obj 中的元素，obj 类型 string。 + +**参数描述** + +* `obj`，str类型 + +**返回值描述** + +`obj`中随机某个元素，str + +**示例**： + +``` +>>> import urandom +>>> urandom.choice("QuecPython") +'t' +``` + +## 随机产生一个在k bits范围内的十进制数 + +### `urandom.getrandbits` + +```python +urandom.getrandbits(k) +``` + +随机产生一个在k bits范围内的十进制数。 + +**参数描述** + +* `k`，int类型，表示范围（单位bit） + +**返回值描述** + +int类型，在k bits范围内的十进制随机数 + +**示例**： + +``` +>>> import urandom +>>> urandom.getrandbits(1) #1位二进制位，范围为0~1（十进制：0~1） +1 +>>> urandom.getrandbits(1) +0 +>>> urandom.getrandbits(8) #8位二进制位，范围为0000 0000~1111 11111（十进制：0~255） +224 +``` + +## 随机生成一个 start 到 end 之间的整数 + +### `urandom.randint` + +``` +urandom.randint(start, end) +``` + +随机生成一个 start 到 end 之间的整数。 + +**参数描述** + +* `start`，int类型，区间最小值 +* `end`，int类型，区间最大值 + +**返回值描述** + +int类型，在`start `到 `end` 之间的随机整数 + +**示例**： + +``` +>>> import urandom +>>> urandom.randint(1, 4) +4 +>>> urandom.randint(1, 4) +2 +``` + +## 随机生成一个 0 到 1 之间的浮点数 + +### `urandom.random` + +```python +urandom.random() +``` + +随机生成一个 0 到 1 之间的浮点数。 + +**返回值描述** + +浮点数，在0 到 1 之间。 + +**示例**： + +``` +>>> import urandom +>>> urandom.random() +0.8465231 +``` + +## 随机生成 start 到 end 间并且递增为 step 的正整数 + +### `urandom.randrange` + +```python +urandom.randrange(start, end, step) +``` + +随机生成 start 到 end 间并且递增为 step 的正整数。 + +**参数描述** + +* `start`，int类型，区间最小值 +* `end`，int类型，区间最大值 +* `step`，int类型，递增长度 + +**返回值描述** + +int类型，在 `start `到 `end` 之间的随机整数 + +**示例**： + +``` +>>> import urandom +>>> urandom.randrange(0, 8, 2) +0 +>>> urandom.randrange(0, 8, 2) +6 +``` + +## 指定随机数种子 + +### `urandom.seed` + +```python +urandom.seed(sed) +``` + +指定随机数种子，通常和其它随机数生成函数搭配使用。 + +**参数描述** + +* `sed`，int类型，区间最小值 + +**示例**： + +```python +>>> import urandom +>>> urandom.seed(20) #指定随机数种子 +>>> for i in range(0, 15): #生成0~15范围内的随机序列 +... print(urandom.randint(1, 10)) +... +8 +10 +9 +10 +2 +1 +9 +3 +2 +2 +6 +1 +10 +9 +6 +``` + +## 随机生成 start 到 end 范围内的浮点数 + +### `urandom.uniform` + +```python +urandom.uniform(start, end) +``` + +**参数描述** + +* `start`，任意实数类型，区间最小值 +* `end`，任意实数类型，区间最大值 + +**返回值描述** + +浮点数类型，在 `start `到 `end` 之间的随机整数 + +**示例**： + +``` +>>> import urandom +>>> urandom.uniform(3, 5) +3.219261 +>>> urandom.uniform(3, 5) +4.00403 +``` + +**使用示例** + +```python +''' +@Author: Baron +@Date: 2020-06-22 +@LastEditTime: 2020-06-22 17:16:20 +@Description: example for module urandom +@FilePath: example_urandom_file.py +''' +import urandom as random +import log +import utime + +''' +下面两个全局变量是必须有的，用户可以根据自己的实际项目修改下面两个全局变量的值 +''' +PROJECT_NAME = "QuecPython_Random_example" +PROJECT_VERSION = "1.0.0" + +log.basicConfig(level=log.INFO) +random_log = log.getLogger("random") + + +if __name__ == '__main__': + # urandom.randint(start, end) + # 随机1 ~ 4之间 + num = random.randint(1, 4) + random_log.info(num) + + # random between 0~1 + num = random.random() + random_log.info(num) + + # urandom.unifrom(start, end) + # 在开始和结束之间生成浮点数 + num = random.uniform(2, 4) + random_log.info(num) + + # urandom.randrange(start, end, step) + # 2-bit binary,the range is [00~11] (0~3) + num = random.getrandbits(2) + random_log.info(num) + + # 8-bit binary,the range is [0000 0000~1111 11111] (0~255) + num = random.getrandbits(8) + random_log.info(num) + + # urandom.randrange(start, end, step) + # 从开始到结束随机生成递增的正整数 + num = random.randrange(2, 8, 2) + random_log.info(num) + + # urandom.choice(obj) + # 随机生成对象中元素的数量 + num = random.choice("QuecPython") + random_log.info(num) + +``` 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 89f7673194152e4dcd4500e241e3ac540dece9ad..09511d64b70a19fc8618aa0c062308025c46896e 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" @@ -12,6 +12,11 @@ - [wifilocator - WiFi定位](./wifilocator.md) - [atcmd - 发送AT指令](./atcmd.md) - [machine - 硬件相关功能](./machine.md) +- [pm - 低功耗相关功能](./pm.md) +- [modem - 设备相关功能](./modem.md) +- [quecgnss - 内置GNSS相关功能](./quecgnss.md) +- [gnss - GNSS相关功能](./gnss.md) +- [securedata - 安全数据区相关功能](./securedata.md) - [...](./....md) diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/example.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/example.md" index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..373fb4b4d1ddf4334daa8531b0a7fddc489e207f 100644 --- "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/example.md" +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/example.md" @@ -0,0 +1,47 @@ +# `example` - 执行python脚本 + +模块功能：提供方法让用户可以在命令行或者代码中执行python脚本。 + +### `example.exec` + +```python +example.exec(filePath) +``` + +执行指定的python脚本文件。 + +**参数描述** + +* `filePath`，string类型， 要执行python脚本文件的绝对路径 + +**示例** + +```python +# 假设有文件test.py,内容如下 + +def myprint(): + count = 10 + while count > 0: + count -= 1 + print('##### test #####') + +myprint() + +#将test.py文件上传到模块中，进入命令行执行如下代码 +>>> uos.listdir('/usr/') +['apn_cfg.json', 'test.py'] +>>> import example +>>> example.exec('/usr/test.py') +# 执行结果如下 + +##### test ##### +##### test ##### +##### test ##### +##### test ##### +##### test ##### +##### test ##### +##### test ##### +##### test ##### +##### test ##### +##### test ##### +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/gnss.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/gnss.md" new file mode 100644 index 0000000000000000000000000000000000000000..dee1a610ab2e1cd3a72a516ff0b9ae1ae055e84d --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/gnss.md" @@ -0,0 +1,365 @@ +# `gnss` - 外置GNSS + +对L76K GPS型号（或数据类型与之类似的GPS模组）进行数据获取，可以得到模块定位是否成功，定位的经纬度数据，UTC授时时间，获取GPS模块的定位模式，获取GPS模块定位使用卫星数量，获取GPS模块定位可见卫星数量，获取定位方位角，GPS模块对地速度，模块定位大地高等数据信息。目前，该模块提供的功能接口，所获取的数据都来源于从串口读出的原始GNSS数据包中的GNGGA、GNRMC和GPGSV语句。 + +注意：当前仅EC600S/EC600N/EC800N/200U/600U/600M/800M模块支持该功能。 + +## 创建gnss对象 + +### `gnss.GnssGetData` + +```python +gnss.GnssGetData(uartn,baudrate,databits,parity,stopbits,flowctl) +``` + +创建获取GNSS的对象，参数为挂载GNSS模块的串口以及通信参数 + +**参数描述** + +* `uartn`，int类型 + UARTn范围为0-3： + `0`-UART0 - DEBUG PORT + `1`-UART1 – BT PORT + `2`-UART2 – MAIN PORT + `3`-UART3 – USB CDC PORT +* `baudrate`，int类型，常用波特率都支持，如4800、9600、19200、38400、57600、115200、230400等 +* `databits`，int类型，数据位（5 ~ 8），ECX00U系列平台当前仅支持8位 +* `parity`，int类型，奇偶校验（0 – NONE，1 – EVEN，2 - ODD） +* `stopbits`，int类型，停止位（1 ~ 2） +* `flowctl`，int类型，硬件控制流（0 – FC_NONE， 1 – FC_HW） + +**返回值描述** +gnss类的对象 + +**示例** + +```python +from gnss import GnssGetData +gnss = GnssGetData(1, 9600, 8, 0, 1, 0) +``` + +## 读取GNSS数据并解析 + +### `gnss.read_gnss_data` + +```python +gnss.read_gnss_data(max_retry=1, debug=0) +``` + +从串口读取GNSS数据，返回数据长度 + +**参数描述** + +* `max_retry`，int类型，可选参数，可不填该参数，默认为1；表示当读取的GNSS无效时，自动重新读取的最大尝试次数，如果读取数据长度为0（即没有读取到数据）则直接退出。 +* `debug`，int类型， 可选参数，可不填该参数，默认为0；表示在读取解析GNSS数据过程中，是否输出一些调试信息，为0表示不输出详细信息，为1表示输出详细信息。 + +**返回值描述** + +返回从串口读取的GNSS数据长度，int类型，单位字节。 + +**示例** + +```python +#========================================================================= +gnss.read_gnss_data() # 使用默认设置，仅读取一次，不输出详细调试信息 +4224 # 读取数据成功，并解析GNGGA、GNRMC和GPGSV语句都成功，直接返回读取的原始数据长度 +#========================================================================= +gnss.read_gnss_data() # 使用默认设置，仅读取一次，不输出详细调试信息 +GNGGA data is invalid. # 读取数据成功，获取的GNGGA定位数据无效 +GNRMC data is invalid. # 读取数据成功，获取的GNRMC定位数据无效 +648 # 返回读取的原始数据长度 +#========================================================================= +gnss.read_gnss_data(max_retry=3) # 设置最大自动读取次数为3次 +Not find GPGSV data or GPGSV data is invalid. # 第1次读取，GPGSV数据未找到或无效 +continue read. # 继续读取下一包数据 +Not find GNGGA data. # 第2次读取，没有找到GNGGA数据 +Not find GNRMC data. # 第2次读取，没有找到GNRMC数据 +continue read. # 继续尝试读取下一包 +Not find GNGGA data. # 第3次读取，没有找到GNGGA数据 +Not find GNRMC data. # 第3次读取，没有找到GNRMC数据 +continue read. # 第3次依然失败，准备继续读取，判断出已经达到最大尝试次数，退出 +128 +#========================================================================= +gnss.read_gnss_data(debug=1) # 设置读取解析过程输出详细信息 +GGA data : ['GNGGA', '021224.000', '3149.27680', 'N', '11706.93369', 'E', '1', '19', '0.9', '168.2', 'M', '-5.0', 'M', '', '*52'] # 输出从原始GNSS数据中匹配到并简单处理后的GNGGA数据 +RMC data : ['GNRMC', '021224.000', 'A', '3149.27680', 'N', '11706.93369', 'E', '0.00', '153.28', '110122', '', '', 'A', 'V*02'] # 输出从原始GNSS数据中匹配到并简单处理后的GNRMC数据 +total_sen_num = 3, total_sat_num = 12 # 输出一组完整GPGSV语句总条数和可视卫星数量 +# 下面是具体的匹配到的GPGSV语句信息 +[0] : ['$GPGSV', '3', '1', '12', '10', '79', '210', '35', '12', '40', '070', '43', '21', '08', '305', '31', '23', '46', '158', '43', '0*6E'] +[1] : ['$GPGSV', '3', '2', '12', '24', '', '', '26', '25', '54', '125', '42', '31', '', '', '21', '32', '50', '324', '34', '0*64'] +[2] : ['$GPGSV', '3', '3', '12', '193', '61', '104', '44', '194', '58', '117', '42', '195', '05', '162', '35', '199', '', '', '32', '0*54'] +4224 +``` + +## 获取读取的原始GNSS数据 + +### `gnss.getOriginalData` + +```python +gnss.getOriginalData() +``` + +该接口用于返回从串口读取的原始GNSS数据，如果用户希望拿到原始GNSS数据，自己进行处理或者进行一些数据确认，可以通过该接口来获取。该接口在每次调用 `gnss.read_gnss_data(max_retry=1, debug=0)`接口后，返回的即本次读取的原始数据。 + +**返回值描述** + +返回从串口读取的原始GNSS数据，string类型。 + +**示例** + +```python +data = gnss.getOriginalData() +print(data) +# 数据量较大，仅列出部分结果 +00,A,3149.28094,N,11706.93869,E,0.00,153.28,110122,,,A,V*04 +$GNVTG,153.28,T,,M,0.00,N,0.00,K,A*2E +$GNZDA,021555.000,11,01,2022,00,00*4D +$GPTXT,01,01,01,ANTENNA OK*35 +$GNGGA,021556.000,3149.28095,N,11706.93869,E,1,24,0.6,166.5,M,-5.0,M,,*5E +$GNGLL,3149.28095,N,11706.93869,E,021556.000,A,A*47 +$GNGSA,A,3,10,12,21,23,24,25,32,193,194,195,199,,1.0,0.6,0.8,1*35 +$GNGSA,A,3,01,04,07,09,14,21,22,24,38,39,42,45,1.0,0.6,0.8,4*36 +... +$GNGGA,021600.000,3149.28096,N,11706.93877,E,1,25,0.6,166.4,M,-5.0,M,,*52 +$GNGLL,3149.28096,N,11706.93877,E,021600.000,A,A*4B +$GNGSA,A,3,10,12,21,23,24,25,31,32,193,194,195,199,1.0,0.6,0.8,1*37 +$GNGSA,A,3,01,04,07,09,$GNGGA,021601.000,3149.28096,N,11706.93878,E,1,25,0.6,166.4,M,-5.0,M,,*5C +$GNGLL,3149.2809 +``` + +## 检查本次读取解析结果有效性 + +### `gnss.checkDataValidity` + +```python +gnss.checkDataValidity() +``` + +GNSS模块提供的功能接口，所获取的数据都来源于从串口读出的原始GNSS数据包中的GNGGA、GNRMC和GPGSV语句，该接口用于检查读取的一包GNSS数据中，GNGGA、GNRMC和GPGSV语句的有效性。 + +**返回值描述** + +返回一个元组，形式为 ` (gga_valid, rmc_valid, gsv_valid)` + +`gga_valid` - 表示本次读取解析，是否匹配到GNGGA数据并解析成功，0表示没有匹配到GNGGA数据或数据无效，1表示有效； + +`rmc_valid` - 表示本次读取解析，是否匹配到GNRMC数据并解析成功，0表述没有匹配到GNRMC数据或数据无效，1表示有效； + +`gsv_valid` - 表示本地读取解析，是否匹配到GPGSV数据并解析成功，0表示没有匹配到GPGSV数据或数据无效，1表示有效。 + +如果用户只关心定位结果，即GNGGA数据是否有效，只要gga_valid参数为1即可（或者通过gnss.isFix()接口来判断定位是否成功），不一定要三个参数都为1；解析GNRMC数据是为了获取对地速度，解析GPGSV数据是为了获取可视卫星数量以及这些卫星对应的方位角，所以用户如果不关心这些参数，可忽略rmc_valid和gsv_valid。 + +**示例** + +```python +gnss.checkDataValidity() +(1, 1, 1) # 说明本次读取解析，GNGGA、GNRMC和GPGSV这三种数据都匹配成功并解析成功 +``` + +## 检查是否定位成功 + +### `gnss.isFix` + +```python +gnss.isFix() +``` + +检查指定串口是否读取到有效GNSS信息 + +**返回值描述** + +`1`：定位成功 + +`0`：定位失败 + +**示例** + +``` +gnss.isFix() +1 +``` + +## 获取定位的UTC时间 + +### `gnss.getUtcTime` + +```python +gnss.getUtcTime() +``` + +获取GNSS信息中携带的时间 + +**返回值描述** + +成功返回UTC时间，字符串类型，失败返回整型`-1`。 + +**示例** + +```python +gnss.getUtcTime() +'06:22:05.000' # hh:mm:ss.sss +``` + +## 获取GPS模块定位模式 + +### `gnss.getLocationMode` + +```python +gnss.getLocationMode() +``` + +获取GNSS信息中携带的定位模式 + +**返回值描述** + +| 返回值 | 描述 | +| ------ | ---------------------------------------- | +| -1 | 获取失败，串口未读到数据或未读到有效数据 | +| 0 | 定位不可用或者无效 | +| 1 | 定位有效,定位模式：GPS、SPS 模式 | +| 2 | 定位有效,定位模式： DGPS、DSPS 模式 | +| 6 | 估算（航位推算）模式 | + +**示例** + +```python +gnss.getLocationMode() +1 +``` + +## 获取GPS模块定位使用卫星数量 + +### `gnss.getUsedSateCnt` + +```python +gnss.getUsedSateCnt() +``` + +获取GNSS信息中携带的使用卫星数量 + +**返回值描述** + +成功返回GPS模块定位使用卫星数量，返回值类型为整型，失败返回整型`-1`。 + +**示例** + +``` +gnss.getUsedSateCnt() +24 +``` + +## 获取GPS模块定位的经纬度信息 + +### `gnss.getLocation` + +```python +gnss.getLocation() +``` + +获取GNSS信息中携带的经纬度信息 + +**返回值描述** + +成功返回GPS模块定位的经纬度信息，失败返回整型`-1`；成功时返回值格式如下： + +`(longitude, lon_direction, latitude, lat_direction)` + +`longitude` - 经度，float型 + +`lon_direction` - 经度方向，字符串类型，E表示东经，W表示西经 + +`latitude` - 纬度，float型 + +`lat_direction` - 纬度方向，字符串类型，N表示北纬，S表示南纬 + +**示例** + +```python +gnss.getLocation() +(117.1156448333333, 'E', 31.82134916666667, 'N') +``` + +## 获取GPS模块定位可见卫星数量 + +### **`gnss.getViewedSateCnt`** + +```python +gnss.getViewedSateCnt() +``` + +获取GNSS信息中携带的可见卫星数量 + +**返回值描述** + +成功返回GPS模块定位可见卫星数量，整型值，失败返回整型-1。 + +**示例** + +```python +gnss.getViewedSateCnt() +12 +``` + +## 获取可视的GNSS卫星方位角 + +### **`gnss.getCourse`** + +```python +gnss.getCourse() +``` + +获取GNSS信息中携带的卫星方位角 + +**返回值描述** +返回所有可视的GNSS卫星方位角，范围：`0 ~ 359`，以正北为参考平面。返回形式为字典，其中key表示卫星编号，value表示方位角。要注意，value的值可能是一个整型值，也可能是""，这取决于原始的GNSS数据中GPGSV语句中方位角是否有值。返回值形式如下： + +`{key:value, ..., key:value}` + +**示例** + +```python + gnss.getCourse() +{'10': 204, '195': 162, '12': 68, '193': 105, '32': 326, '199': 162, '25': 122, '31': 247, '24': 52, '194': 116, '21': 304, '23': 159} +``` + +## 获取GPS模块定位海拔高度 + +### **`gnss.getGeodeticHeight`** + +```python +gnss.getGeodeticHeight() +``` + +获取GNSS信息中携带的海拔高度 + +**返回值描述** + +成功返回浮点类型海拔高度(单位:米)，失败返回整型`-1`。 + +**示例** + +```python +gnss.getGeodeticHeight() +166.5 +``` + +## 获取GPS模块对地速度 + +### `gnss.getSpeed` + +```python +gnss.getSpeed() +``` + +获取GNSS信息中携带的对地速度 + +**返回值描述** + +成功返回GPS模块对地速度(单位:KM/h)，浮点类型，失败返回整型`-1` + +**示例** + +```python +gnss.getSpeed() +0.0 +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/modem.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/modem.md" new file mode 100644 index 0000000000000000000000000000000000000000..b53d30ba293a308a1137e36ece15a2cf85e447b0 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/modem.md" @@ -0,0 +1,109 @@ +# `modem` - 设备相关 + +modem模块提供读取设备信息的方法 + +## 获取设备的IMEI + +### `modem.getDevImei` + +```python +modem.getDevImei() +``` + +获取设备的IMEI。 + +**返回值描述** + +成功返回string类型设备的IMEI，失败返回整型值 `-1`。 + +**示例** + +```python +>>> import modem +>>> modem.getDevImei() +'866327040830317' +``` + +## 获取设备型号 + +### `modem.getDevModel` + +```python +modem.getDevModel() +``` + +获取设备型号。 + +****返回值描述**** + + 成功返回string类型设备型号，失败返回整型值 `-1`。 + +**示例** + +```python +>>> modem.getDevModel() +'EC100Y' +``` + +## 获取设备序列号 + +### `modem.getDevSN` + +```python +modem.getDevSN() +``` + +获取设备序列号。 + +**返回值描述** + + 成功返回string类型设备序列号，失败返回整型值 `-1`。 + +**示例** + +```python +>>> modem.getDevSN() +'D1Q20GM050038341P' +``` + +## 获取固件版本号 + +### `modem.getDevFwVersion` + +```python +modem.getDevFwVersion() +``` + +获取设备固件版本号。 + +****返回值描述**** + + 成功返回string类型固件版本号，失败返回整型值 `-1`。 + +**示例** + +```python +>>> modem.getDevFwVersion() +'EC100YCNAAR01A01M16_OCPU_PY' +``` + +## 获取设备制造商ID + +### `modem.getDevProductId` + +```python +modem.getDevProductId() +``` + +获取设备的制造商ID。 + +**返回值描述** + + 成功返回设备制造商ID，失败返回整型值`-1`。 + +**示例** + +```python +>>> modem.getDevProductId() +'Quectel' +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/pm.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/pm.md" new file mode 100644 index 0000000000000000000000000000000000000000..9cf1268ffa53fecbcd1053c5ff21db002608f450 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/pm.md" @@ -0,0 +1,238 @@ +# `pm` - 低功耗 + +在无业务处理时使系统进入休眠状态，进入低功耗模式。 + +## 创建wake_lock锁 + +### `pm.create_wakelock` + +```python +pm.create_wakelock(lock_name, name_size) +``` + +创建wake_lock锁。 + +**参数描述** + +* `lock_name`，自定义lock名，string类型， +* `name_size`， lock_name的长度， int类型 + +**返回值描述** + +成功返回wakelock的标识号，否则返回 `-1`。 + +> **注意**:BC25PA平台不支持此方法。 + +## 删除wake_lock锁 + +### `pm.delete_wakelock` + +```python +pm.delete_wakelock(lpm_fd) +``` + +删除wake_lock锁。 + +**参数描述** + +* `lpm_fd`，需要删除的锁对应标识id，int类型 + +**返回值描述** + +成功返回 `0`。 + +> **注意**：BC25PA平台不支持此方法。 + +## 加锁 + +### `pm.wakelock_lock` + +```python +pm.wakelock_lock(lpm_fd) +``` + +将指定的wakelock置于锁定状态，存在锁定状态的锁时，模组不会进入低功耗状态 + +**参数描述** + +* `lpm_fd`，需要执行加锁操作的wakelock标识id，int类型 + +**返回值描述** + +成功返回 `0`，否则返回 `-1`。 + +> **注意**：BC25PA平台不支持此方法。 + +## 释放锁 + +### `pm.wakelock_unlock` + +```python +pm.wakelock_unlock(lpm_fd) +``` + +释放锁，所有wakelock被释放时，模组才允许进入低功耗 + +**参数描述** + +* `lpm_fd`，需要执行释放锁操作的wakelock标识id，int类型 + +**返回值描述** + +成功返回 `0`，否则返回 `-1`。 + +> **注意**：BC25PA平台不支持此方法。 + +## 自动休眠模式控制 + +### `pm.autosleep` + +```python +pm.autosleep(sleep_flag) +``` + +自动休眠模式控制 + +**参数描述** + +* `sleep_flag`，`0`关闭自动休眠， `1`开启自动休眠，int类型 + +**返回值描述** + +成功返回 `0`，失败返回 `-1` + +## 获取已创建的锁数量 + +### `pm.get_wakelock_num` + +```python +pm.get_wakelock_num() +``` + +获取已创建的锁数量 + +**返回值描述** + +int类型，返回已创建wakelock锁的数量。 + +> 注意：BC25PA平台不支持此方法。 + +## 设置PSM模式的控制时间 + +### `pm.set_psm_time` + +```python +pm.set_psm_time(tau_uint,tau_time,act_uint,act_time) # 设置并启用PSM <模式1> + +pm.set_psm_time(mode)# 单独设置启用或禁用 <模式2> +``` + +**参数描述** + +* `mode`，是否启用PSM，int类型: + `0 `禁用PSM + `1 `启用PSM + `2 `(仅BC25平台)禁用PSM并删除PSM的所有参数，如有默认值，则重置默认值。(注意此种模式禁用的情况下，如果要启用PSM必须用**模式1**，用**模式2**没有任何的意义,因为设置的TAU和ACT时间全部清零了)。 +* `tau_uint`，tau(T3412)定时器单位，int类型 + +| tau定时器单位值 | 类型 | 单位值说明 | +| --------------- | ---- | ------------ | +| 0 | int | 10 分钟 | +| 1 | int | 1 小时 | +| 2 | int | 10 小时 | +| 3 | int | 2 秒 | +| 4 | int | 30 秒 | +| 5 | int | 1 分钟 | +| 6 | int | 320 小时 | +| 7 | int | 定时器被停用 | + +* `tau_time`，tau(T3412)定时器时间周期值，int类型 +* `act_uint`，act(T3324)定时器单位，int类型 + +| act定时器单位值 | 类型 | 单位值说明 | +| --------------- | ---- | ------------ | +| 0 | int | 2 秒 | +| 1 | int | 1 分钟 | +| 2 | int | 6 分钟 | +| 7 | int | 定时器被停用 | + +* `act_time`，act(T3324)定时器时间周期值，int类型 + +> **注意：**实际设置的tau和act，为单位值和周期值的积 + +**返回值描述** + +`True: ` 成功 +`False:` 失败 + +**示例** + +```python +>>> import pm +>>> pm.set_psm_time(1,2,1,4) #设置tau定时器周期为 1小时 * 2 = 2小时， act定时器周期值为 1分钟 * 4 = 4分钟。 +True +>>> +``` + +> **注意**：仅BC25/ECX00U/ECX00E支持 + +## 获取PSM模式的控制时间 + +### `pm.get_psm_time` + +```python +pm.get_psm_time() +``` + +**返回值描述** + +成功：返回值为list类型，说明如下： + +| 参数 | 类型 | 单位值说明 | +| ------- | ---- | ------------------------------------------------------------------------------------------------------------------------- | +| list[0] | int | mode说明:
0-禁用PSM.
1-启用PSM.
2-(仅BC25平台)禁用 PSM 并删除 PSM 的所有参数,若有默认值,则重置为默认值。 | +| list[1] | int | tau定时器单位 | +| list[2] | int | tau定时器时间周期值 | +| list[3] | int | act定时器单位 | +| list[4] | int | act定时器时间周期值 | + +失败：返回 `None`。 + +**示例** + +```python +>>> pm.get_psm_time() + +[1, 1, 1, 1, 2] + + +``` + +> **注意**：仅BC25/ECX00U/ECX00E平台支持 + +**使用示例** + +模拟测试，实际开发请根据业务场景选择使用！ + +```python +import pm +import utime + +# 创建wakelock锁 +lpm_fd = pm.create_wakelock("test_lock", len("test_lock")) +# 设置自动休眠模式 +pm.autosleep(1) + +# 模拟测试，实际开发请根据业务场景选择使用 +while 1: + utime.sleep(20) # 休眠 + res = pm.wakelock_lock(lpm_fd) + print("ql_lpm_idlelock_lock, g_c1_axi_fd = %d" %lpm_fd) + print("unlock sleep") + utime.sleep(20) + res = pm.wakelock_unlock(lpm_fd) + print(res) + print("ql_lpm_idlelock_unlock, g_c1_axi_fd = %d" % lpm_fd) + num = pm.get_wakelock_num() # 获取已创建锁的数量 + print(num) +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/quecgnss.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/quecgnss.md" new file mode 100644 index 0000000000000000000000000000000000000000..5561732e8c4e26aca13502b88a0c37cd116de616 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/quecgnss.md" @@ -0,0 +1,143 @@ +# `quecgnss` - 内置GNSS + +此模块提供内置GNSS的使用接口 + +> **说明**：当前仅 EC200UCNAA/EC200UCNLA/EC200UEUAA/EC800MCNGA/EC800GCNGA 型号支持该功能。 + +## GNSS 功能初始化 + +### **`quecgnss.init`** + +```python +quecgnss.init() +``` + +模组内置GNSS模块功能的初始化。 + +**返回值描述** +成功返回整形`0`，失败返回整形`-1`。 + +## GNSS 工作状态获取 + +### **`quecgnss.get_state`** + +```python +quecgnss.get_state() +``` + +获取GNSS模块当前工作状态 + +**返回值描述** + +| 返回值 | 类型 | 说明 | +| ------ | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 0 | int | GNSS模块处于关闭状态 | +| 1 | int | GNSS模块固件升级中 | +| 2 | int | GNSS模块定位中，这种模式下即可开始读取GNSS定位数据，定位数据是否有效需要用户获取到定位数据后，解析对应语句来判断，比如判断GNRMC语句的status是 A 还是 V，A 表示定位有效，V 表示定位无效。 | + +## GNSS开关 + +### `quecgnss.gnssEnable` + +```python +quecgnss.gnssEnable(opt) +``` + +开启或者关闭GNSS模块。如果是上电后第一次使用内置GNSS功能，一般不需要调用该接口来开启GNSS功能，直接调用init()接口即可，init() 接口在初始化时会自动开启GNSS功能。 + +**参数描述** + +`opt`，int类型 + + `0` - 关闭GNSS功能 + + `1` - 开启GNSS功能 + +**返回值描述** + +成功返回整形 `0`，失败返回整形 `-1`。 + +## GNSS定位数据获取 + +### `quecgnss.read` + +```python +quecgnss.read(size) +``` + +读取GNSS定位数据。 + +**参数描述** + +`size`，int类型，指定读取数据的大小，单位字节。 + +**返回值描述** + +成功返回一个元组，失败返回整形-1。元组形式如下： +`(size, data)` +`size` - 实际读取数据的大小 +`data` - GNSS定位数据 + +**GNSS使用示例** + +```python +import quecgnss + + +def main(): + ret = quecgnss.init() + if ret == 0: + print('GNSS init ok.') + else: + print('GNSS init failed.') + return -1 + data = quecgnss.read(4096) + print(data[1].decode()) + + quecgnss.gnssEnable(0) + + +if __name__ == '__main__': + main() + + +#=================================================================================================== +#运行结果 +167,169,170,,,,,,,,1.773,1.013,1.455*15 +$GPGSV,2,1,8,3,23,303,34,16,32,219,28,22,74,98,26,25,16,43,25*77 +$GPGSV,2,2,8,26,70,236,28,31,59,12,38,32,55,127,34,4,5,,21*49 +$BDGSV,2,1,8,163,51,192,32,166,70,11,31,167,52,197,32,169,59,334,31*61 +$BDGSV,2,2,8,170,40,205,31,161,5,,31,164,5,,27,165,5,,29*59 +$GNRMC,022326.000,A,3149.324624,N,11706.921702,E,0.000,261.541,180222,,E,A*38 +$GNGGA,022326.000,3149.324624,N,11706.921702,E,1,12,1.013,-8.580,M,0,M,,*47 +$GNGLL,3149.324624,N,11706.921702,E,022326.000,A,A*44 +$GNGSA,A,3,31,32,3,16,22,25,26,,,,,,1.773,1.013,1.455*1C +$GNGSA,A,3,163,166,167,169,170,,,,,,,,1.773,1.013,1.455*15 +$GPGSV,2,1,8,3,23,303,34,16,32,219,27,22,74,98,26,25,16,43,25*78 +$GPGSV,2,2,8,26,70,236,28,31,59,12,37,32,55,127,34,4,5,,20*47 +$BDGSV,2,1,8,163,51,192,32,166,70,11,31,167,52,197,32,169,59,334,31*61 +$BDGSV,2,2,8,170,40,205,31,161,5,,31,164,5,,27,165,5,,29*59 +$GNRMC,022327.000,A,3149.324611,N,11706.921713,E,0.000,261.541,180222,,E,A*3F +$GNGGA,022327.000,3149.324611,N,11706.921713,E,1,12,1.013,-8.577,M,0,M,,*48 +$GNGLL,3149.324611,N,11706.921713,E,022327.000,A,A*43 +...... # 数据较多，省略 +$GNGSA,A,3,31,32,3,16,22,25,26,,,,,,1.837,1.120,1.456*11 +$GNGSA,A,3,163,166,167,169,170,,,,,,,,1.837,1.120,1.456*18 +$GPGSV,2,1,8,3,23,302,27,16,32,220,26,22,73,101,27,25,16,43,27*45 +$GPGSV,2,2,8,26,70,237,28,31,59,13,33,32,54,128,28,4,5,,24*44 +$BDGSV,2,1,8,163,51,192,33,166,71,11,35,167,52,198,33,169,59,334,34*6E +$BDGSV,2,2,8,170,40,205,32,161,5,,33,164,5,,28,165,5,,30*5F +$GNRMC,022507.000,A,3149.324768,N,11706.922344,E,0.000,261.541,180222,,E,A*31 +$GNGGA,022507.000,3149.324768,N,11706.922344,E,1,12,1.120,-8.794,M,0,M,,*48 +$GNGLL,3149.324768,N,11706.922344,E,022507.000,A,A*4D +$GNGSA,A,3,31,32,3,16,22,25,26,,,,,,1.837,1.120,1.455*12 +$GNGSA,A,3,163,166,167,169,170,,,,,,,,1.837,1.120,1.455*1B +$GPGSV,2,1,8,3,23,302,26,16,32,220,26,22,73,101,27,25,16,43,26*45 +$GPGSV,2,2,8,26,70,237,28,31,59,13,32,32,54,128,28,4,5,,24*45 +$BDGSV,2,1,8,163,51,192,24,166,71,11,35,167,52,198,33,169,59,334,34*68 +$BDGSV,2,2,8,170,40,205,31,161,5,,33,164,5,,28,165,5,,30*5C +$GNRMC,022508.000,A,3149.324754,N,11706.922338,E,0.002,261.541,180222,,E,A*38 +$GNGGA,022508.000,3149.324754,N,11706.922338,E,1,12,1.120,-8.750,M,0,M,,*4B +$GNGLL,3149.324754,N,11706.922338,E,022508.000,A,A*46 +$GNGSA,A,3,31,3 +``` diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/securedata.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/securedata.md" new file mode 100644 index 0000000000000000000000000000000000000000..e7771e957bbc72508cec58f84d71757e1fbecaec --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/securedata.md" @@ -0,0 +1,84 @@ +# `SecureData` - 安全数据区 + +模组提供一块裸flash区域及专门的读写接口供客户存贮重要信息，且信息在烧录固件后不丢失(烧录不包含此功能的固件无法保证不丢失)。提供一个存储和读取接口，不提供删除接口。 + +> 目前除BC25/BG95/EC200A系列外，其余平台均支持本功能 + +## 数据存储 + +### `SecureData.Store` + +```python +SecureData.Store(index,databuf,len) +``` + +**参数描述** + +* `index`，int类型 + | index序号 | 最大存储量 | + | --------- | ---------- | + | 1 - 8 | 52字节 | + | 9 - 12 | 100字节 | + | 13 - 14 | 500字节 | + | 15 - 16 | 1000字节 | +* `databuf`，待存储的数据数组，bytearray类型 +* `len`，要写入数据的长度，int类型 + +> 存储时按照databuf和len两者中长度较小的进行存储 + +**返回值描述** + +`-1`: 参数有误 +`0`: 执行正常 + +## 数据读取 + +### `SecureData.Read` + +```python +SecureData.Read(index,databuf,len) +``` + +**参数描述** + +* `index`，index范围为1-16：读取存储数据对应的索引号，int类型 +* `databuf`，存储读取到的数据，bytearray类型 +* `len`，要读取数据的长度，int类型 + +> 若存储的数据没有传入的len大，则返回实际存储的数据长度 + +**返回值描述** + +`-2`存储数据不存在且备份数据也不存在 +`-1`参数有误 +`其他`实际读取到的数据长度 + +**示例** + +```python +import SecureData +# 即将存储的数据buf +databuf = '\x31\x32\x33\x34\x35\x36\x37\x38' +# 在index为1的存储区域中存储长度为8的数据databuf +SecureData.Store(1, databuf, 8) +# 定义一个长度为20的数组用于读取存储的数据 +buf = bytearray(20) +# 读取index为1的存储区域中的数据至buf中,将读取到数据的长度存储在变量length中 +length = SecureData.Read(1, buf, 20) +# 输出读到的数据 +print(buf[:length]) +``` + +**使用示例** + +```python +>>> import SecureData +>>> databuf = '\x31\x32\x33\x34\x35\x36\x37\x38' +>>> SecureData.Store(1, databuf, 8) +0 +>>> buf = bytearray(20) +>>> length = SecureData.Read(1, buf, 20) +>>> print(buf[:length]) +bytearray(b'12345678') +>>> +``` diff --git a/docs/API_reference/zh/sidebar.yaml b/docs/API_reference/zh/sidebar.yaml index 062a2a92d0383e8e03098e8b9939dd6dca4a0d4b..50660c6fa0db78c12d6be821bd9580f9c820a688 100644 --- a/docs/API_reference/zh/sidebar.yaml +++ b/docs/API_reference/zh/sidebar.yaml @@ -34,6 +34,19 @@ items: file: QuecPython标准库/uhashlib.md - label: QuecPython类库 file: QuecPython类库/README.md + items: + - label: - 执行Python脚本 + file: QuecPython类库/example.md + - label: - 低功耗相关功能 + file: QuecPython类库/pm.md + - label: - 设备相关功能 + file: QuecPython类库/modem.md + - label: - 内置GNSS相关功能 + file: QuecPython类库/quecgnss.md + - label: - GNSS相关功能 + file: QuecPython类库/gnss.md + - label: - 安全数据区相关功能 + file: QuecPython标准库/securedata.md - label: QuecPython组件库 file: QuecPython组件库/README.md items: