Merge pull request #84 from Lawlieta/master

【添加】machine.WDT 模块和 machine.Timer 模块

Author: armink

docs/04-Hardware_Control_Module/10-machine-WDT.md

@@ -0,0 +1,40 @@
+## machine.WDT
+
+**machine.WDT** 类是 machine 模块下的一个硬件类，用于 WDT 设备的配置和控制，提供对 WDT 设备的操作方法。
+
+如下为 WDT 设备基本介绍：
+
+- WDT（WatchDog Timer，硬件看门狗），是一个定时器设备，用于系统程序结束或出错导致系统进入不可恢复状态时重启系统。
+
+- WDT 启动之后，计数器开始计数，在计数器溢出前没有被复位，会对 CPU 产生一个复位信号使设备重启（简称 “被狗咬”）；
+
+- 系统正常运行时，需要在 WDT 设备允许的时间间隔内对看门狗计数清零（简称“喂狗”），WDT 设备一旦启动，需要定时“喂狗”以确保设备正常运行。
+
+### 构造函数
+
+在 RT-Thread MicroPython 中 `WDT` 对象的构造函数如下：
+
+#### **class machine.WDT**(timeout=5)
+
+- **timeout**：设置看门狗超时时间，单位：秒（s）；
+
+用于创建一个 WDT 对象并且启动 WDT 功能。一旦启动，设置的超时时间无法改动，WDT 功能无法停止。
+
+如果该函数入参为空，则设置超时时间为 5 秒；如果入参非空，则使用该入参设置 WDT 超时时间，超时时间最小设置为 1 秒。
+
+### 方法
+
+#### **WDT.feed**()
+
+用于执行“喂狗”操作，清空看门狗设备计数。应用程序应该合理的周期性调用该函数，以防止系统重启。
+
+### 示例
+
+``` python
+>>> from machine import WDT     # 从 machine 导入 WDT 类
+>>> wdt = WDT()                 # 创建 WDT 对象，默认超时时间为 5 秒
+>>> wdt = WDT(10)               # 创建 WDT 对象，设置超时时间为 10 秒
+>>> wdt.feed()                  # 在 10 秒超时时间内需要执行“喂狗”操作，清空看门狗设备计数，否则系统将重启
+```
+
+更多内容可参考 [machine.WDT](http://docs.micropython.org/en/latest/library/machine.WDT.html) 。

docs/04-Hardware_Control_Module/11-machine-Timer.md

@@ -0,0 +1,73 @@
+## machine.Timer
+
+**machine.Timer** 类是 machine 模块下的一个硬件类，用于 Timer 设备的配置和控制，提供对 Timer 设备的操作方法。
+
+- Timer（硬件定时器），是一种用于处理周期性和定时性事件的设备。
+- Timer 硬件定时器主要通过内部计数器模块对脉冲信号进行计数，实现周期性设备控制的功能。
+- Timer 硬件定时器可以自定义**超时时间**和**超时回调函数**，并且提供两种**定时器模式**：
+  - `ONE_SHOT`：定时器只执行一次设置的回调函数；
+  - `PERIOD`：定时器会周期性执行设置的回调函数；
+- 打印 Timer 对象会打印出配置的信息。
+
+### 构造函数
+
+在 RT-Thread MicroPython 中 `Timer` 对象的构造函数如下：
+
+#### **class machine.Timer**(id)
+
+- **id**：使用的 Timer 设备编号，`id = 1` 表示编号为 1 的 Timer 设备；
+
+该函数主要用于通过设备编号创建 Timer 设备对象。
+
+### 方法
+
+#### **Timer.init**(mode = Timer.PERIODIC, period = 0, callback = None)
+
+- **mode**：设置 Timer 定时器模式，可以设置两种模式：`ONE_SHOT`（执行一次）、`PERIOD`（周期性执行），默认设置的模式为 `PERIOD` 模式；
+
+- **period**：设置 Timer 定时器定时周期，单位：毫秒（ms）
+
+- **callback**：设置 Timer 定义器超时回调函数，默认设置的函数为 None 空函数，设置的函数格式如下所示：
+
+```python
+def callback_test(device):         # 回调函数有且只有一个入参，为创建的 Timer 对象
+    print("Timer callback test")
+    print(device)                  # 打印 Timer 对象配置信息
+```
+
+该函数使用方式如下示例所示：
+
+```python
+timer.init(wdt.PERIOD,5000,callback_test)   # 设置定时器模式为周期性执行，超时时间为 5 秒, 超时函数为 callback_test
+```
+#### **Timer.deinit**()
+
+该函数用于停止并关闭 Timer 设备。
+
+### 常量
+
+下面的常量用来配置 `Timer` 对象。
+
+#### 选择定时器模式：
+##### **Timer.PERIODIC**
+##### **Timer.ONE_SHOT**
+
+### 示例
+
+```python
+>>> from machine import Timer                       # 从 machine 导入 Timer 类
+>>> timer = Timer(11)                               # 创建 Timer 对象，当前设备编号为 11
+>>>                                                 # 进入粘贴模式
+paste mode; Ctrl-C to cancel, Ctrl-D to finish
+=== def callback_test(device):                      # 定义超时回调函数 
+===     print("Timer callback test")
+>>> timer.init(timer.PERIODIC, 5000, callback_test) # 初始化 Timer 对象，设置定时器模式为循环执行，超时时间为 5 秒，超时回调函数 callback_test
+>>> Timer callback test                             # 5 秒超时循环执行回调函数，打印日志
+>>> Timer callback test
+>>> Timer callback test
+>>> timer.init(timer.ONE_SHOT, 5000, callback_test) # 设置定时器模式为只执行一次，超时时间为 5 秒，超时回调函数为 callback_test
+>>> Timer callback test                             # 5 秒超时后执行一次回调函数，打印日志
+>>> timer.deinit()                                  # 停止并关闭 Timer 定时器
+```
+
+更多内容可参考 [machine.Timer](http://docs.micropython.org/en/latest/library/machine.Timer.html)。

port/genhdr/qstrdefs.generated.h

@@ -755,4 +755,10 @@ QDEF(MP_QSTR_GRAY240, (const byte*)"\x3e\x07" "GRAY240")
 QDEF(MP_QSTR_line, (const byte*)"\xcb\x04" "line")
 QDEF(MP_QSTR_rectangle, (const byte*)"\xa4\x09" "rectangle")
 QDEF(MP_QSTR_circle, (const byte*)"\xb7\x06" "circle")
+QDEF(MP_QSTR_WDT, (const byte*)"\x62\x03" "WDT")
+QDEF(MP_QSTR_feed, (const byte*)"\xa7\x04" "feed")
+QDEF(MP_QSTR_Timer, (const byte*)"\xa2\x05" "Timer")
+QDEF(MP_QSTR_ONE_SHOT, (const byte*)"\x5e\x08" "ONE_SHOT")
+QDEF(MP_QSTR_PERIODIC, (const byte*)"\x0a\x08" "PERIODIC")
+QDEF(MP_QSTR_period, (const byte*)"\xa0\x06" "period")
 // This file was automatically generated by makeqstrdata.py

port/machine_timer.c

@@ -0,0 +1,212 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2019 ChenYong ([email protected])
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "py/obj.h"
+#include "py/runtime.h"
+#include "modmachine.h"
+#include "mphalport.h"
+
+#ifdef MICROPYTHON_USING_MACHINE_TIMER
+
+#include <rtthread.h>
+#include <drivers/hwtimer.h>
+#include "machine_timer.h"
+
+typedef struct _machine_timer_obj_t {
+    mp_obj_base_t base;
+    rt_device_t timer_device;
+    mp_obj_t timeout_cb;
+    uint8_t timerid;
+    uint32_t timeout;
+    rt_bool_t is_repeat;
+    rt_bool_t is_init;
+} machine_timer_obj_t;
+
+const mp_obj_type_t machine_timer_type;
+
+STATIC void error_check(bool status, const char *msg) {
+    if (!status) {
+        nlr_raise(mp_obj_new_exception_msg(&mp_type_ValueError, msg));
+    }
+}
+
+STATIC void machine_timer_print(const mp_print_t *print, mp_obj_t self_in, mp_print_kind_t kind) {
+    machine_timer_obj_t *self = self_in;
+
+    mp_printf(print, "Timer(%p; ", self);
+
+    mp_printf(print, "timerid=%d, ", self->timerid);
+    mp_printf(print, "period=%d, ", self->timeout);
+    mp_printf(print, "auto_reload=%d)", self->is_repeat);
+}
+
+STATIC mp_obj_t machine_timer_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
+    machine_timer_obj_t *self = m_new_obj(machine_timer_obj_t);
+    char timer_dev_name[RT_NAME_MAX] = {0};
+    int device_id = 0;
+
+    // check arguments
+    mp_arg_check_num(n_args, n_kw, 1, 1, true);
+    device_id = mp_obj_get_int(args[0]);
+
+    // find timer device
+    rt_snprintf(timer_dev_name, sizeof(timer_dev_name), "timer%d", device_id);
+    self->timer_device = rt_device_find(timer_dev_name);
+    if (self->timer_device == RT_NULL || self->timer_device->type != RT_Device_Class_Timer) {
+        nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError, "Timer(%s) don't exist", timer_dev_name)); 
+    }
+
+    // initialize timer device
+    self->base.type = &machine_timer_type;
+    self->timerid = device_id;
+    self->timeout = 0;
+    self->is_repeat = RT_TRUE;
+    self->is_init = RT_FALSE;
+    
+    // return constant object
+    return MP_OBJ_FROM_PTR(self);
+}
+
+STATIC mp_obj_t machine_timer_deinit(mp_obj_t self_in) {
+    machine_timer_obj_t *self = self_in;
+    rt_err_t result = RT_EOK;
+
+    if (self->is_init == RT_TRUE) {
+        result = rt_device_close(self->timer_device);
+        error_check(result == RT_EOK, "Timer device close error");
+        self->is_init = RT_FALSE;
+    }
+
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_1(machine_timer_deinit_obj, machine_timer_deinit);
+
+static machine_timer_obj_t *timer_self = RT_NULL;
+
+STATIC rt_err_t timer_event_handler(rt_device_t dev, rt_size_t size) {
+    machine_timer_obj_t *self = timer_self;
+
+    mp_sched_schedule(self->timeout_cb, MP_OBJ_FROM_PTR(self));
+    return RT_EOK;
+}
+
+STATIC mp_obj_t machine_timer_init(mp_uint_t n_args, const mp_obj_t *args, mp_map_t *kw_args) {
+    machine_timer_obj_t *self = (machine_timer_obj_t *)args[0];
+    rt_bool_t result = RT_EOK;
+    int mode = 0;
+
+    enum {
+        ARG_mode,
+        ARG_period,
+        ARG_callback,
+    };
+    static const mp_arg_t allowed_args[] = {
+        { MP_QSTR_mode,         MP_ARG_INT, {.u_int = 1} },
+        { MP_QSTR_period,       MP_ARG_INT, {.u_int = 0xffffffff} },
+        { MP_QSTR_callback,     MP_ARG_OBJ, {.u_obj = mp_const_none} },
+    };
+
+    mp_arg_val_t dargs[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args - 1, args + 1, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, dargs);
+
+    if (2 == n_args) {
+        self->timeout = dargs[0].u_int;
+    } else if (3 == n_args) {
+        self->is_repeat = dargs[ARG_mode].u_int;
+        self->timeout = dargs[ARG_period].u_int;
+    } else if (4 == n_args) {
+        self->is_repeat = dargs[ARG_mode].u_int;
+        self->timeout = dargs[ARG_period].u_int;
+        self->timeout_cb = dargs[ARG_callback].u_obj;
+    } else {
+        mp_raise_ValueError("invalid format");
+    }
+
+    error_check(self->timeout > 0, "Set timeout value error");
+
+    if (self->is_init == RT_FALSE)
+    {
+        // open timer device
+        result = rt_device_open(self->timer_device, RT_DEVICE_OFLAG_RDWR);
+        error_check(result == RT_EOK, "Timer device open error");
+    }
+    
+    if (self->timeout_cb != RT_NULL) {
+        // set callback timer
+        if (timer_self && timer_self != self) {
+            // TODO add multi-timer device support
+            error_check(result == RT_EOK, "Only supports one timer device work");
+        } else {
+            timer_self = self;
+        }
+        result = rt_device_set_rx_indicate(self->timer_device, timer_event_handler);
+        error_check(result == RT_EOK, "Timer set timout callback error");
+    }
+
+    // set timer mode 
+    mode = self->is_repeat ? HWTIMER_MODE_PERIOD : HWTIMER_MODE_ONESHOT;
+    result = rt_device_control(self->timer_device, HWTIMER_CTRL_MODE_SET, &mode);
+    error_check(result == RT_EOK, "Timer set mode error");
+
+    if (self->timeout) {
+        rt_hwtimerval_t timeout_s;
+        rt_size_t len;
+
+        timeout_s.sec = self->timeout / 1000;      // second
+        timeout_s.usec = self->timeout % 1000;     // microsecond
+
+        len = rt_device_write(self->timer_device, 0, &timeout_s, sizeof(timeout_s));
+        error_check(len == sizeof(timeout_s), "Timer set timout error");
+    }
+
+    self->is_init = RT_TRUE;
+    
+    return mp_const_none;
+}
+STATIC MP_DEFINE_CONST_FUN_OBJ_KW(machine_timer_init_obj, 1, machine_timer_init);
+
+STATIC const mp_rom_map_elem_t machine_timer_locals_dict_table[] = {
+    { MP_ROM_QSTR(MP_QSTR_deinit), MP_ROM_PTR(&machine_timer_deinit_obj) },
+    { MP_ROM_QSTR(MP_QSTR_init), MP_ROM_PTR(&machine_timer_init_obj) },
+    { MP_ROM_QSTR(MP_QSTR_ONE_SHOT), MP_ROM_INT(RT_FALSE) },
+    { MP_ROM_QSTR(MP_QSTR_PERIODIC), MP_ROM_INT(RT_TRUE) },
+};
+STATIC MP_DEFINE_CONST_DICT(machine_timer_locals_dict, machine_timer_locals_dict_table);
+
+const mp_obj_type_t machine_timer_type = {
+    { &mp_type_type },
+    .name = MP_QSTR_Timer,
+    .print = machine_timer_print,
+    .make_new = machine_timer_make_new,
+    .locals_dict = (mp_obj_t) &machine_timer_locals_dict,
+};
+
+#endif // MICROPYTHON_USING_MACHINE_TIMER
+

port/machine_timer.h

@@ -0,0 +1,36 @@
+/*
+ * This file is part of the MicroPython project, http://micropython.org/
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2019 ChenYong ([email protected])
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+#ifndef MICROPY_INCLUDED_MACHINE_TIMER_H
+#define MICROPY_INCLUDED_MACHINE_TIMER_H
+
+#include "py/obj.h"
+#include <rtthread.h>
+
+extern const mp_obj_type_t machine_timer_type;
+
+#endif // MICROPY_INCLUDED_MACHINE_TIMER_H
+