diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/_thread.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/_thread.md" new file mode 100644 index 0000000000000000000000000000000000000000..2d588e86517ebb8f11d92ba400c58ba8c18f84c2 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/_thread.md" @@ -0,0 +1,279 @@ +# _thread- 线程相关功能 + +`_thread` 模块包含线程操作相关的功能。提供创建、删除线程的方法,提供互斥锁、信号量相关的接口。 + +**示例:** + +```python +''' +@Author: Baron +@Date: 2020-06-22 +@LastEditTime: 2020-06-22 17:16:20 +@Description: example for module _thread +@FilePath: example_thread_file.py +''' +import _thread +import log +import utime + + +''' +下面两个全局变量是必须有的,用户可以根据自己的实际项目修改下面两个全局变量的值 +''' +PROJECT_NAME = "QuecPython_Thread_example" +PROJECT_VERSION = "1.0.0" + + +# 设置日志输出级别 +log.basicConfig(level=log.INFO) +thread_log = log.getLogger("Thread") + +a = 0 +state = 1 +state1 = 1 +# 创建一个lock的实例 +lock = _thread.allocate_lock() + +def th_func(delay, id): + global a + global state,state1 + while True: + lock.acquire() # 获取锁 + if a >= 10: + thread_log.info('thread %d exit' % id) + lock.release() # 释放锁 + if id == 1: + state = 0 + else: + state1 = 0 + break + a += 1 + thread_log.info('[thread %d] a is %d' % (id, a)) + lock.release() # 释放锁 + utime.sleep(delay) + +def th_func1(): + while True: + thread_log.info('thread th_func1 is running') + utime.sleep(1) + +if __name__ == '__main__': + for i in range(2): + _thread.start_new_thread(th_func, (i + 1, i)) # 创建一个线程,当函数无参时传入空的元组 + + thread_id = _thread.start_new_thread(th_func1, ()) # 创建一个线程,当函数无参时传入空的元组 + + while state or state1: + pass + + _thread.stop_thread(thread_id) # 删除线程 + _thread.delete_lock(lock) # 删除锁 + thread_log.info('thread th_func1 is stopped') +``` + +## 线程相关功能 + +### `_thread.get_ident` + +```python +_thread.get_ident() +``` + +获取当前线程号。 + +**返回值描述:** + +返回当前线程号。 + +### `_thread.stack_size` + +```python +_thread.stack_size(size) +``` + +设置或获取创建新线程使用的栈大小(以字节为单位),取决于参数`size`是否提供。默认为8448字节,最小8192字节。 + +**参数描述:** + +- `size`- 提供该参数,用于创建新线程使用的栈大小。 + +**返回值描述:** + +- 当参数`size`没有提供时,返回创建新线程使用的栈大小。 + +### `_thread.start_new_thread` + +```python +_thread.start_new_thread(function, args) +``` + +创建一个新线程。接收执行函数和被执行函数参数,当 function 函数无参时传入空的元组。 + +**参数描述:** + +- `function`- 线程执行函数。 + +- `args`- 线程执行函数的参数,当 `function` 函数无参时传入空的元组。 + +**返回值描述:** + +- 返回创建的新线程的id。 + +### `_thread.stop_thread` + +```python +_thread.stop_thread(thread_id) +``` + +删除一个线程。不可删除主线程。 + +**参数描述:** + +- `thread_id`- 为创建线程时返回的线程id,为0时则删除当前线程。 + +### `_thread.get_heap_size` + +```python +_thread.get_heap_size() +``` + +获取系统heap内存剩余大小。 + +**返回值描述:** + +- 返回系统heap内存剩余大小(以字节为单位)。 + +## 互斥锁相关功能 + +### `_thread.allocate_lock` + +```python +_thread.allocate_lock() +``` + +创建一个互斥锁对象。 + +**返回值描述:** + +- 返回创建的互斥锁对象。 + +**示例**: + +```python +import _thread +lock = _thread.allocate_lock() +``` + +### `lock.acquire` + +```python +lock.acquire() +``` + +获取锁。 + +**返回值描述:** + +- 成功返回True,失败返回False。 + +### `lock.release` + +```python +lock.release() +``` + +释放锁。 + +### `lock.locked` + +```python +lock.locked() +``` + +返回锁的状态。 + +**返回值描述:** + +- True表示被某个线程获取,False则表示没有。 + +### `_thread.delete_lock` + +```python +_thread.delete_lock(lock) +``` + +删除已经创建的互斥锁。 + +**参数描述:** + +- `lock`- 为创建时返回的互斥锁对象。 + +## 信号量相关功能 + +### `_thread.allocate_semphore` + +```python +_thread.allocate_semphore(initcount) +``` + +创建一个信号量对象。 + +**参数描述:** + +`initcount`- 为信号量的计数初始值也是最大值。 + +**返回值描述:** + +- 返回创建的信号量对象。 + +**示例**: + +``` +import _thread +semphore = _thread.allocate_semphore(1) +``` + +### `semphore.acquire` + +```python +semphore.acquire() +``` + +获取信号量。 + +**返回值描述:** + +- 成功返回True,失败返回False。 + +### `semphore.release` + +```python +semphore.release() +``` + +释放信号量。 + +### `semphore.getCnt` + +```python +semphore.getCnt() +``` + +获取信号量计数最大值和当前剩余计数值。 + +**返回值描述:** + +- `(maxCnt, curCnt)`-元组:maxCnt为计数最大值,curCnt为当前剩余计数值。 + +### `_thread.delete_semphore` + +```python +_thread.delete_semphore(semphore) +``` + +删除已经创建的信号量。 + +**参数描述:** + +`semphore`- 为创建时返回的信号量对象。 + diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/gc.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/gc.md" index e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..670c812ddb63369b0a030ac2655f1c8d3ed0c28c 100644 --- "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/gc.md" +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/gc.md" @@ -0,0 +1,68 @@ +# gc-内存相关功能 + +`gc` 模块实现内存垃圾回收机制,该模块实现了CPython模块相应模块的子集。更多信息请参阅CPython文档:[gc](https://docs.python.org/3.5/library/gc.html#module-gc) + +## 内存回收相关功能 + +### `gc.enable` + +```python +gc.enable() +``` + +启用自动回收内存碎片机制。 + +### `gc.disable` + +```python +gc.disable() +``` + +禁用自动回收内存碎片机制。 + +### `gc.isenabled` + +```python +gc.isenabled() +``` + +查询是否启动了自动回收内存碎片机制。 + +**返回值描述:** + +- True-已启动自动回收内存碎片机制,False-未启动自动回收内存碎片机制。 + +### `gc.collect` + +```python +gc.collect() +``` + +主动回收内存碎片。 + +## 内存查询相关功能 + +### `gc.mem_alloc` + +```python +gc.mem_alloc() +``` + +查询已申请的内存大小。 + +**返回值描述:** + +- 返回已申请的内存大小,单位字节。 + +### `gc.mem_free` + +```python +gc.mem_free() +``` + +查询剩余可用的内存大小。 + +**返回值描述:** + +- 返回剩余可用的内存大小,单位字节。 + diff --git "a/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/utime.md" "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/utime.md" new file mode 100644 index 0000000000000000000000000000000000000000..8384e77101caf79a8e4b684307a4aac586501dcf --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\346\240\207\345\207\206\345\272\223/utime.md" @@ -0,0 +1,258 @@ +# utime - 时间相关功能 + +`utime`模块用于获取当前时间、测量时间间隔和休眠。该模块实现相应CPython模块的子集。更多信息请参阅CPython文档:[time](https://docs.python.org/3.5/library/time.html#module-time) + +**示例**: + +```python +''' +@Author: Baron +@Date: 2020-06-17 +@LastEditTime: 2020-06-17 17:06:08 +@Description: example for module utime +@FilePath: example_utime_loacltime_file.py +''' +import utime +import log + + +''' +下面两个全局变量是必须有的,用户可以根据自己的实际项目修改下面两个全局变量的值 +''' +PROJECT_NAME = "QuecPython_localtime_example" +PROJECT_VERSION = "1.0.0" + + +# 设置日志输出级别 +log.basicConfig(level=log.INFO) +time_log = log.getLogger("LocalTime") + +if __name__ == '__main__': + # 获取本地时间,返回元组 + tupe_t = utime.localtime() + time_log.info(tupe_t) + # 返回当前时间戳,参数为元组 + t = utime.mktime(utime.localtime()) + time_log.info(t) + # 休眠sleep示例 + for i in [0, 1, 2, 3, 4, 5]: + utime.sleep(1) # 休眠(单位 m) + time_log.info(i) + + for i in [0, 1, 2, 3, 4, 5]: + utime.sleep_ms(1000) # 休眠(单位 ms) + time_log.info(i) +``` + + + +## 当前时间相关功能 + +### `utime.localtime` + +```python +utime.localtime(secs) +``` + +将一个以秒为单位的时间转换为一个日期格式的时间并返回,或者返回本地RTC的时间,取决于参数`secs`是否提供。 + +**参数描述:** + +- `secs`-int类型,一个以秒为单位的时间。 + +**返回值描述:** + +- `(year, month, mday, hour, minute, second, weekday, yearday)`-类型为元组,包含了年、月、日、时、分、秒、星期、一年中第几天。当提供参数`secs`时,返回转换后的时间。当参数`secs`没有提供时,则返回本地RTC的时间。返回值含义如下: + +| 元组成员 | 范围 | 含义 | +| -------- | ---------------------- | ---------------- | +| year | int型 | 年份 | +| month | int型,1~12 | 月份 | +| mday | int型,1~31 | 日,当月多少号 | +| hour | int型,0~23 | 小时 | +| minute | int型,0~59 | 分钟 | +| second | int型,0~59 | 秒 | +| weekday | int型,周一到周日是0~6 | 星期 | +| yearday | int型 | 一年中的第多少天 | + +**示例**: + +```python +>>> import utime +>>> utime.localtime() +(2020, 9, 29, 8, 54, 42, 1, 273) +>>> utime.localtime(646898736) +(2020, 7, 1, 6, 5, 36, 2, 183) +``` + +### `utime.mktime` + +```python +utime.mktime(date) +``` + +将一个存放在元组中的日期格式的时间转换为以秒为单位的时间并返回。 + +**参数描述:** + +- `date`-日期格式的时间,类型为元组,格式:(year, month, mday, hour, minute, second, weekday, yearday)。 + +**返回值描述:** + +- 以秒为单位的时间,类型为int。 + +**示例**: + +```python +>>> import utime +>>> date = (2020, 9, 29, 8, 54, 42, 1, 273) +>>> utime.mktime(date) +1601340882 +``` + +### `utime.time` + +```python +utime.time() +``` + +返回自设备开机以来的秒数。 + +**返回值描述:** + +- 以秒为单位的时间,类型为int。 + +### `utime.getTimeZone` + +```python +utime.getTimeZone() +``` + +获取当前时区。 + +**返回值描述:** + +- 单位小时,范围[-12, 12],负值表示西时区,正值表示东时区,0表示零时区。 + +### `utime.setTimeZone` + +```python +utime.setTimeZone(offset) +``` + +设置时区。设置时区后,本地时间会随之变化为对应时区的时间。 + +**参数描述:** + +- 单位小时,范围[-12, 12],负值表示西时区,正值表示东时区,0表示零时区。 + +## 测量时间间隔相关功能 + +### `utime.ticks_ms` + +```python +utime.ticks_ms() +``` + +返回不断递增的毫秒计数器,在超过0x3FFFFFFF值后会重新计数。 + +**返回值描述:** + +- 毫秒计数值,计数值本身无特定意义,只适合用在 `ticks_diff()`函数中。 + +### `utime.ticks_us` + +```python +utime.ticks_us() +``` + +返回不断递增的微秒计数器,在超过0x3FFFFFFF值后会重新计数。 + +**返回值描述:** + +- 微秒计数值,计数值本身无特定意义,只适合用在 `ticks_diff()`函数中。 + +### `utime.ticks_cpu` + +```python +utime.ticks_cpu() +``` + +返回不断递增的cpu计数器,单位不确定,取决于硬件平台底层的时钟。 + +**返回值描述:** + +- 计数值,计数值本身无特定意义,只适合用在 `ticks_diff()`函数中。 + +### `utime.ticks_diff` + +```python +utime.ticks_diff(ticks1, ticks2) +``` + +计算两次调用` ticks_ms`, `ticks_us`,或 `ticks_cpu`之间的时间间隔。因为`ticks_xxx`这些函数的计数值可能会回绕,所以不能直接相减,需要使用 `ticks_diff`函数。通常用法是在带超时的轮询事件中调用。 + +**参数描述:** + +- `ticks1`-第二次调用` ticks_ms`, `ticks_us`,或 `ticks_cpu`获取的tick值。 +- `ticks2`-第一次调用` ticks_ms`, `ticks_us`,或 `ticks_cpu`获取的tick值。 + +**返回值描述:** + +- 时间间隔,两次调用` ticks_ms`, `ticks_us`,或 `ticks_cpu`之间的时间间隔。单位和传入的`ticks2`和`ticks1`的单位一致。 + +**注意**: + +`ticks2`和`ticks1`的顺序不能颠倒,否则结果无法确定。且这个函数不要用在计算很长的时间间隔,具体限制为`ticks2`和`ticks1`的tick差值不能超过0x1FFFFFFF,否则结果无法确定。 + +**示例**: + +```python +import utime +start = utime.ticks_us() +while pin.value() == 0: + if utime.ticks_diff(utime.ticks_us(), start) > 500: + raise TimeoutError +``` + +## 休眠相关功能 + +### `utime.sleep` + +```python +utime.sleep(seconds) +``` + +休眠给定秒数的时间。 + +**参数描述:** + +- `seconds`-休眠的时长,单位秒。 + +### `utime.sleep_ms` + +```python +utime.sleep_ms(ms) +``` + +休眠给定毫秒数的时间。 + +**参数描述:** + +`ms`-休眠的时长,单位毫秒。 + +### `utime.sleep_us` + +```python +utime.sleep_us(us) +``` + +休眠给定微秒数的时间。 + +**参数描述:** + +`us`-休眠的时长,单位微秒。 + +**注意**: + +`utime.sleep`、`utime.sleep_ms`及`utime.sleep_us`函数的调用会导致程序休眠阻塞。 \ No newline at end of file diff --git "a/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/app_fota.md" "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/app_fota.md" new file mode 100644 index 0000000000000000000000000000000000000000..e1bb5cdf95cc84aa7294bdb221d16739b01f8db4 --- /dev/null +++ "b/docs/API_reference/zh/QuecPython\347\261\273\345\272\223/app_fota.md" @@ -0,0 +1,92 @@ +# app_fota - 用户文件升级相关功能 + +`app_fota`模块用于用户文件升级。 + +**示例**: + +```python +import app_fota +from misc import Power + +fota = app_fota.new() +download_list = [{'url': 'http://www.example.com/app.py', 'file_name': '/usr/app.py'}, {'url': 'http://www.example.com/test.txt', 'file_name': '/usr/text.txt'}] +fota.bulk_download(download_list) # 下载 +fota.set_update_flag() # 设置升级标志 +Power.powerRestart() # 重启 +``` + +## 初始化相关功能 + +### `app_fota.new` + +```python +app_fota.new() +``` + +创建app_fota对象。 + +**返回值描述:** + +- app_fota对象。 + +**示例**: + +```python +import app_fota +fota = app_fota.new() +``` + +## 下载相关功能 + +### `fota.download` + +```python +fota.download(url, file_name) +``` + +下载单个文件。 + +**参数描述:** + +- `url`-待下载文件的url,类型为str。 +- `file_name`-本地待升级文件的绝对路径,类型str。 + +**返回值描述**: + +- 成功返回0,否则返回-1。 + +### `fota.bulk_download` + +```python +fota.bulk_download(info=[]) +``` + +下载批量文件。 + +**参数描述:** + +- `info`-批量下载列表,列表的元素均为包含了`url`和`file_name`的字典,类型为list。 + +**返回值描述**: + +- 返回下载失败的列表,类型为list。 + +**示例**: + +```python +download_list = [{'url': 'http://www.example.com/app.py', 'file_name': '/usr/app.py'}, {'url': 'http://www.example.com/test.txt', 'file_name': '/usr/text.txt'}] +fota.bulk_download(download_list) +``` + +该示例中,假设`http://www.example.com/test.txt`下载失败,则该方法返回值为`[{url: 'http://www.example.com/test.txt', file_name: '/usr/text.txt'}]`。 + +## 设置升级标志相关功能 + +### `fota.set_update_flag` + +```python +fota.set_update_flag() +``` + +设置升级标志。设置完成升级标志后,调用重启接口,重启后即可启动升级工作。升级完成后会直接进入应用程序。 +