Merge pull request #120 from Lawlieta/master

【更新】ADC、PWM、Timer、WDT 驱动模块，添加对设备名称入参判断，更新文档说明

Author: armink

docs/04-Hardware_Control_Module/08-machine-PWM.md

@@ -16,7 +16,7 @@
 
 在给定的总线上构建一个 `PWM` 对象，参数介绍如下：
 
-- **id**：使用的 PWM 设备编号，如  `id = 1` 表示编号为 1 的 PWM 设备；
+- **id**：使用的 PWM 设备编号，如  `id = 1` 表示编号为 1 的 PWM 设备，或者表示使用的 PWM 设备名，如 `id = "pwm"` 表示设备名为 `pwm` 的 PWM 设备；
 - **channel**：使用的 PWM 设备通道号，每个 PWM 设备包含多个通道，范围为 [0, 4]；
 - **freq**：初始化频率，范围 [1, 156250]；
 - **duty**：初始化占空比数值，范围 [0 255]；

docs/04-Hardware_Control_Module/09-machine-ADC.md

@@ -13,7 +13,7 @@
 
 #### **class machine.ADC**(id, channel)
 
-- **id**：使用的 ADC 设备编号，`id = 1` 表示编号为 1 的 ADC 设备；
+- **id**：使用的 ADC 设备编号，`id = 1` 表示编号为 1 的 ADC 设备，或者表示使用的 ADC 设备名，如 `id = "adc"` 表示设备名为 `adc` 的 ADC 设备；
 - **channel**：使用的 ADC 设备通道号，每个 ADC 设备对应多个通道；
 
 例如：`ADC(1,4)` 表示当前使用编号为 1 的 ADC 设备的 4 通道。

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

@@ -14,7 +14,9 @@
 
 在 RT-Thread MicroPython 中 `WDT` 对象的构造函数如下：
 
-#### **class machine.WDT**(timeout=5)
+#### **class machine.WDT**(id = "wdt", timeout=5)
+
+- **id**: 使用的 WDT 设备编号，`id = 1` 表示编号为 1 的 WDT 设备，或者表示使用的 WDT 设备名，如 `id = "wdt"` 表示设备名为 `wdt` 的 WDT 设备；
 
 - **timeout**：设置看门狗超时时间，单位：秒（s）；
 

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

@@ -15,7 +15,7 @@
 
 #### **class machine.Timer**(id)
 
-- **id**：使用的 Timer 设备编号，`id = 1` 表示编号为 1 的 Timer 设备；
+- **id**：使用的 Timer 设备编号，`id = 1` 表示编号为 1 的 Timer 设备，或者表示使用的 timer 设备名，如 `id = "timer"` 表示设备名为 `timer` 的 Timer 设备；
 
 该函数主要用于通过设备编号创建 Timer 设备对象。
 

port/modules/machine/machine_adc.c

@@ -60,7 +60,6 @@ STATIC mp_obj_t machine_adc_make_new(const mp_obj_type_t *type,
     struct rt_adc_device *adc_device = RT_NULL;
     char adc_dev_name[RT_NAME_MAX] = {0};
     rt_err_t result = RT_EOK;
-    int dev_id = 0;
 
     // init machine adc object information
     self->channel = 0;
@@ -69,11 +68,18 @@ STATIC mp_obj_t machine_adc_make_new(const mp_obj_type_t *type,
 
     mp_arg_check_num(n_args, n_kw, 1, 2, true);
 
-    dev_id = mp_obj_get_int(args[0]);
-    rt_snprintf(adc_dev_name, sizeof(adc_dev_name), "adc%d", dev_id);
+    // check input ADC device name or ID
+    if (mp_obj_is_small_int(args[0])) {
+        rt_snprintf(adc_dev_name, sizeof(adc_dev_name), "adc%d", mp_obj_get_int(args[0]));
+    } else if (mp_obj_is_qstr(args[0])) {
+        rt_strncpy(adc_dev_name, mp_obj_str_get_str(args[0]), RT_NAME_MAX);
+    } else {
+        error_check(0, "Input ADC device name or ID error.");
+    }
+
     adc_device = (struct rt_adc_device *) rt_device_find(adc_dev_name);
     if (adc_device == RT_NULL || adc_device->parent.type != RT_Device_Class_Miscellaneous) {
-        nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError, 
+        nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError,
                                                 "ADC(%s) don't exist", adc_dev_name));
     }
     self->adc_device = adc_device;

port/modules/machine/machine_pwm.c

@@ -47,8 +47,9 @@ extern const mp_obj_type_t machine_pwm_type;
 typedef struct _machine_pwm_obj_t {
     mp_obj_base_t base;
     struct rt_device_pwm *pwm_device;
+    char dev_name[RT_NAME_MAX];
     uint8_t is_init;
-    uint8_t id;
+    int8_t id;
     uint8_t channel;
     uint8_t duty;
     uint32_t freq;
@@ -58,7 +59,11 @@ STATIC void machine_pwm_print(const mp_print_t *print, mp_obj_t self_in, mp_prin
     machine_pwm_obj_t *self = self_in;
 
     mp_printf(print, "PWM(%p; ", self);
-    mp_printf(print, "id=%d, ", self->id);
+    if (self->id >= 0) {
+        mp_printf(print, "pwm_id=%d, ", self->id);
+    } else {
+        mp_printf(print, "pwm_name=%s, ", self->dev_name);
+    }
     mp_printf(print, "channel=%d, ", self->channel);
     mp_printf(print, "freq=%d, ", self->freq);
     mp_printf(print, "duty=%d)", self->duty);
@@ -107,10 +112,15 @@ STATIC void machine_pwm_init_helper(machine_pwm_obj_t *self,
     }
     self->duty = tval;
 
-    snprintf(pwm_dev_name, sizeof(pwm_dev_name), "pwm%d", self->id);
+    if (self->id >= 0) {
+        rt_snprintf(pwm_dev_name, sizeof(pwm_dev_name), "pwm%d", self->id);
+    } else {
+        rt_strncpy(pwm_dev_name, self->dev_name, RT_NAME_MAX);
+    }
+
     pwm_device = (struct rt_device_pwm *) rt_device_find(pwm_dev_name);
     if (pwm_device == RT_NULL || pwm_device->parent.type != RT_Device_Class_Miscellaneous) {
-        nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError, 
+        nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError,
                                                 "PWM(%s) don't exist", pwm_dev_name));
     }
     self->pwm_device = pwm_device;
@@ -137,7 +147,17 @@ STATIC mp_obj_t machine_pwm_make_new(const mp_obj_type_t *type,
     machine_pwm_obj_t *self = m_new_obj(machine_pwm_obj_t);
     self->base.type = &machine_pwm_type;
     self->is_init = RT_FALSE;
-    self->id = mp_obj_get_int(args[0]);
+
+    // check input PWM device name or ID
+    if (mp_obj_is_small_int(args[0])) {
+        self->id = mp_obj_get_int(args[0]);
+    } else if (mp_obj_is_qstr(args[0])) {
+        self->id = -1;
+        rt_strncpy(self->dev_name, mp_obj_str_get_str(args[0]), RT_NAME_MAX);
+    } else {
+        error_check(0, "Input PWM device name or ID error.");
+    }
+
     self->channel = 0;
     self->freq = 1;
     self->duty = 0;
@@ -187,16 +207,16 @@ STATIC mp_obj_t machine_pwm_freq(size_t n_args, const mp_obj_t *args) {
         nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError,
                                                 "Bad frequency %d", tval));
     }
-    
+
     // get period number by frequency
     period = MP_PWM_PERIOD_GET(tval);
     // get pulse number by duty
     pulse = MP_PWM_PULSE_GET(period, self->duty);
-    
+
     result = rt_pwm_set(self->pwm_device, self->channel, period, pulse);
     error_check(result == RT_EOK, "PWM set information error");
     self->freq = tval;
-    
+
     return mp_const_none;
 }
 
@@ -220,12 +240,12 @@ STATIC mp_obj_t machine_pwm_duty(size_t n_args, const mp_obj_t *args) {
         nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError,
                                                 "Bad duty %d", tval));
     }
-    
+
     // get period number by frequency
     period = MP_PWM_PERIOD_GET(self->freq);
     // get pulse number by duty
     pulse = MP_PWM_PULSE_GET(period, tval);
-    
+
     result = rt_pwm_set(self->pwm_device, self->channel, period, pulse);
     error_check(result == RT_EOK, "PWM set information error");
     self->duty = tval;

port/modules/machine/machine_timer.c

@@ -44,8 +44,9 @@
 typedef struct _machine_timer_obj_t {
     mp_obj_base_t base;
     rt_device_t timer_device;
+    char dev_name[RT_NAME_MAX];
     mp_obj_t timeout_cb;
-    uint8_t timerid;
+    int8_t timerid;
     uint32_t timeout;
     rt_bool_t is_repeat;
     rt_bool_t is_init;
@@ -64,36 +65,51 @@ STATIC void machine_timer_print(const mp_print_t *print, mp_obj_t self_in, mp_pr
 
     mp_printf(print, "Timer(%p; ", self);
 
-    mp_printf(print, "timerid=%d, ", self->timerid);
+    if (self->timerid >= 0) {
+        mp_printf(print, "timer_id=%d, ", self->timerid);
+    } else {
+        mp_printf(print, "timer_name=%s, ", self->dev_name);
+    }
     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]);
+
+    // check input timer device name or ID
+    if (mp_obj_is_small_int(args[0])) {
+        int device_id = mp_obj_get_int(args[0]);
+        self->timerid = device_id;
+        self->timer_device->device_id = device_id;
+        rt_snprintf(timer_dev_name, sizeof(timer_dev_name), "timer%d", mp_obj_get_int(args[0]));
+    } else if (mp_obj_is_qstr(args[0])) {
+        static int device_id = 0;
+        self->timerid = -1;
+        self->timer_device->device_id = device_id++;
+        rt_strncpy(self->dev_name, mp_obj_str_get_str(args[0]), RT_NAME_MAX);
+        rt_strncpy(timer_dev_name, self->dev_name, RT_NAME_MAX);
+    } else {
+        error_check(0, "Input ADC device name or ID error.");
+    }
 
     // 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)); 
+        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->timeout_cb = RT_NULL;
     self->is_repeat = RT_TRUE;
     self->is_init = RT_FALSE;
-    self->timer_device->device_id = device_id-1;
-    
+
     // return constant object
     return MP_OBJ_FROM_PTR(self);
 }
@@ -162,7 +178,7 @@ STATIC mp_obj_t machine_timer_init(mp_uint_t n_args, const mp_obj_t *args, mp_ma
         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[self->timer_device->device_id] && timer_self[self->timer_device->device_id] != self) {
@@ -174,7 +190,7 @@ STATIC mp_obj_t machine_timer_init(mp_uint_t n_args, const mp_obj_t *args, mp_ma
         error_check(result == RT_EOK, "Timer set timout callback error");
     }
 
-    // set timer mode 
+    // 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");
@@ -191,7 +207,7 @@ STATIC mp_obj_t machine_timer_init(mp_uint_t n_args, const mp_obj_t *args, mp_ma
     }
 
     self->is_init = RT_TRUE;
-    
+
     return mp_const_none;
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_KW(machine_timer_init_obj, 1, machine_timer_init);
@@ -200,20 +216,20 @@ STATIC MP_DEFINE_CONST_FUN_OBJ_KW(machine_timer_init_obj, 1, machine_timer_init)
 STATIC mp_obj_t machine_timer_callback(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;
-    
+
     static const mp_arg_t allowed_args[] = {
         { 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);
-    
+
     self->timeout_cb = dargs[0].u_obj;
-    
+
     if(n_args == 1)
     {
         self->timeout_cb = RT_NULL;
-        self->timer_device->rx_indicate = RT_NULL;//Log-off callback function 
+        self->timer_device->rx_indicate = RT_NULL;//Log-off callback function
     }
     else if(n_args == 2)
     {
@@ -226,7 +242,7 @@ STATIC mp_obj_t machine_timer_callback(mp_uint_t n_args, const mp_obj_t *args, m
         else
         {
             self->timeout_cb = RT_NULL;
-            self->timer_device->rx_indicate = RT_NULL;//Log-off callback function 
+            self->timer_device->rx_indicate = RT_NULL;//Log-off callback function
         }
     }
     return mp_const_none;

port/modules/machine/machine_wdt.c

@@ -54,22 +54,42 @@ STATIC void error_check(bool status, const char *msg) {
 STATIC mp_obj_t machine_wdt_make_new(const mp_obj_type_t *type_in, size_t n_args, size_t n_kw, const mp_obj_t *args) {
 #define MP_WDT_DEV_NAME "wdt"
     machine_wdt_obj_t *self = m_new_obj(machine_wdt_obj_t);
+    char wdt_dev_name[RT_NAME_MAX] = {0};
     rt_err_t result = RT_EOK;
     mp_int_t timeout = 5;
 
     // check arguments
-    mp_arg_check_num(n_args, n_kw, 0, 1, false);
-
-    if (n_args > 0) {
-        timeout = mp_obj_get_int(args[0]);
+    mp_arg_check_num(n_args, n_kw, 0, 2, false);
+
+    if (n_args == 2) {
+        // check input WDT device name or ID
+        if (mp_obj_is_small_int(args[0])) {
+            rt_snprintf(wdt_dev_name, sizeof(wdt_dev_name), "wdt%d", mp_obj_get_int(args[0]));
+        } else if (mp_obj_is_qstr(args[0])) {
+            rt_strncpy(wdt_dev_name, mp_obj_str_get_str(args[0]), RT_NAME_MAX);
+        } else {
+            error_check(0, "Input WDT device name or ID error.");
+        }
+        timeout = mp_obj_get_int(args[1]);
         error_check(timeout >= 1, "input timeout value error");
+    } else if (n_args == 1) {
+        if (mp_obj_is_small_int(args[0])) {
+            timeout = mp_obj_get_int(args[0]);
+            error_check(timeout >= 1, "input timeout value error");
+        } else if (mp_obj_is_qstr(args[0])) {
+            rt_strncpy(wdt_dev_name, mp_obj_str_get_str(args[0]), RT_NAME_MAX);
+        } else {
+            error_check(0, "Input WDT device name or ID error.");
+        }
+    } else {
+        rt_strncpy(wdt_dev_name, MP_WDT_DEV_NAME, RT_NAME_MAX);
     }
 
     self->base.type = &machine_wdt_type;
     // find WDT device
-    self->wdt_device = rt_device_find(MP_WDT_DEV_NAME);
+    self->wdt_device = rt_device_find(wdt_dev_name);
     if (self->wdt_device == RT_NULL || self->wdt_device->type != RT_Device_Class_Miscellaneous) {
-        nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError, "WDT(%s) don't exist", MP_WDT_DEV_NAME)); 
+        nlr_raise(mp_obj_new_exception_msg_varg(&mp_type_ValueError, "WDT(%s) don't exist", wdt_dev_name));
     }
 
     result = rt_device_init(self->wdt_device);
@@ -93,7 +113,7 @@ STATIC mp_obj_t machine_wdt_feed(mp_obj_t self_in) {
 
     result = rt_device_control(self->wdt_device, RT_DEVICE_CTRL_WDT_KEEPALIVE, RT_NULL);
     error_check(result == RT_EOK, "WDT feed failed");
-    
+
     return mp_const_none;
 }
 STATIC MP_DEFINE_CONST_FUN_OBJ_1(machine_wdt_feed_obj, machine_wdt_feed);