使用官方文档的方式为micropython添加一个全局模块
文章目录
- 使用官方文档的方式为micropython添加一个全局模块
- 概述
- 根据官方描述步骤创建一个led模块
- 为新模块创建一个源文件
- 逐层封装
- 在Makefile文件中更新SRC_C和SRC_QSTR
- 进一步调试
- 在mpconfigport.h文件中注册新模块
- 总结
概述
在本文中, 我分析管官方开发指导文档中的代码撰写流程, 根据自己的理解, 创建一个新的模块. 并试图通过实践, 观察代码的实际工作效果.
在我的样例代码中, 我将要创建一个LED灯的模块, 并包含on()和off()两个函数对应开灯和关灯两个动作。
根据官方描述步骤创建一个led模块
为新模块创建一个源文件
参考官方样例的命名规范, 这里在lpc5500移植项目的目录下创建mod_led.c
PS: 原始的命名范例中没有使用下划线"_"将前缀"mod"单独分隔出来, 但我通过阅读代码发现, 增加下划线的命名方式更符合micropython的命名规范. 实际上, 在micropython的源代码中, 都是使用下划线作为命名单词的分隔符的. 我有点不明白为什么文件的命令没有使用分隔符. 按照我的开发习惯, 在规模比较大的软件项目中, 使用分隔符的命名方式可读性更好, 所以在我自己的练习代码中, 将会使用下划线作为名字之间的分隔符.
在新模块中首先编写最基本的led模块对应底层驱动的三个函数:
- hw_led_init()
- hw_led_on()
- hw_led_off()
目前先做一个最简单的样例, 实现从python到c语言函数的调用. 目前的样例中仅仅传递函数指针, 不传入任何参数, 在后续的文章中将专门探讨传递参数的问题.
逐层封装
毕竟使用了armgcc编译器, 底层的代码还是以C语言方式运行的, 从python到底层的C就是层层调用. 反过来在开发过程中, 准备好底层的C代码之后, 想要在python层面上被识别, 就需要层层封装并注册.
从官方的样例代码中可以看到, 大体上分为三个层次的封装, 对应了三个封装的宏操作:
- MP_DEFINE_CONST_FUN_OBJ_0. 将函数封装成对象. 在python中, 一切皆是对象.
- MP_DEFINE_CONST_DICT. 将所有的函数对象封装成一个操作清单.
- MP_REGISTER_MODULE. 将操作清单和对象绑定在一起, 注册到python系统中.
到目前为止, 完整的mod_led.c源文件内容如下:
/* mod_led.c */
#include "py/runtime.h"
#include "fsl_common.h"
#include "fsl_iocon.h"
#include "fsl_clock.h"
#include "fsl_gpio.h"
/******************************************************************************
* hardware level functions.
*****************************************************************************/
void hw_led_init(void)
{
CLOCK_EnableClock(kCLOCK_Iocon);
CLOCK_EnableClock(kCLOCK_Gpio1);
uint32_t pinmode = IOCON_FUNC0
| IOCON_MODE_INACT
| IOCON_GPIO_MODE
| IOCON_DIGITAL_EN
;
IOCON_PinMuxSet(IOCON, 1u, 6u, pinmode); /* pio1_6. */
gpio_pin_config_t gpio_pin_config;
gpio_pin_config.pinDirection = kGPIO_DigitalOutput;
gpio_pin_config.outputLogic = 1u;
GPIO_PinInit(GPIO, 1u, 6u, &gpio_pin_config);
}
void hw_led_on(void)
{
GPIO_PinWrite(GPIO, 1u, 6u, 0u);
}
void hw_led_off(void)
{
GPIO_PinWrite(GPIO, 1u, 6u, 1u);
}
/******************************************************************************
* object function wrappers.
*****************************************************************************/
STATIC mp_obj_t led_init_func(void)
{
hw_led_init();
return mp_const_none;
}
STATIC MP_DEFINE_CONST_FUN_OBJ_0(led_init_obj, led_init_func);
STATIC mp_obj_t led_on_func(void)
{
hw_led_on();
return mp_const_none;
}
STATIC MP_DEFINE_CONST_FUN_OBJ_0(led_on_obj, led_on_func);
STATIC mp_obj_t led_off_func(void)
{
hw_led_off();
return mp_const_none;
}
STATIC MP_DEFINE_CONST_FUN_OBJ_0(led_off_obj, led_off_func);
/******************************************************************************
* pack the objects into module.
*****************************************************************************/
STATIC const mp_rom_map_elem_t led_module_globals_table[] = {
{ MP_OBJ_NEW_QSTR(MP_QSTR___name__), MP_OBJ_NEW_QSTR(MP_QSTR_led) },
{ MP_ROM_QSTR(MP_QSTR_init), MP_ROM_PTR(&led_init_obj) },
{ MP_ROM_QSTR(MP_QSTR_on) , MP_ROM_PTR(&led_on_obj) },
{ MP_ROM_QSTR(MP_QSTR_off) , MP_ROM_PTR(&led_off_obj) },
};
STATIC MP_DEFINE_CONST_DICT(led_module_globals, led_module_globals_table);
const mp_obj_module_t led_module = {
.base = { &mp_type_module },
.globals = (mp_obj_dict_t *)&led_module_globals,
};
MP_REGISTER_MODULE(MP_QSTR_led, led_module, 1);
/* EOF. */在Makefile文件中更新SRC_C和SRC_QSTR
在SRC_C中添加mod_led.c文件, 将新增代码编译firmware中.
在SRC_QSTR中添加mod_led.c文件, 让build过程扫描mod_led.c文件, 从中提取字符串关键字增加到micropython的qstr列表当中.
第二步操作是根据官方文档的说明进行的操作, 应该是比较正式的添加qstr的方式. 实际上, 在之前的研究中, 我是人为地在qstrdefsport.h文件中增加qstr关键字的. 这里终于看到官方推荐的做法了.
按照官方开发文档的说明, 到这里就可以重新make, 然后可以在micropython的交互命令行中引用led模块的. 但实际情况呢… 然并卵.
好不容易清除编译错误, 把firmware下载到板子上, 还是不能识别新模块, "import led"报错无效.
…
进一步调试
通过各种比较代码, 比较同mimxrt的移植和自己早年开发的参考代码, 最终通过如下操作实现了预期的功能.
在mpconfigport.h文件中注册新模块
在mpconfigport.h文件中添加代码如下:
extern const struct _mp_obj_module_t led_module;
#define MICROPY_PORT_BUILTIN_MODULES \
{ MP_ROM_QSTR(MP_QSTR_led), MP_ROM_PTR(&led_module) }, \通过编译之后, 下载firmware到电路板上, 复位后通过终端命令行交互, 能够成功识别led模块, 并且在板子上确实看到led灯受控亮灭了.
这句话顾名思义是向系统中注册可以识别的模块的. 同官方文档中的最后一步封装注册的操作MP_REGISTER_MODULE相似, 但貌似没起作用.
进一步追一下代码, 看到了MP_REGISTER_MODULE操作的定义, 忍不住爆了句粗口"娘…希…匹".
在源文件"py/obj.h"中, MP_REGISTER_MODULE仅仅操作了个寂寞.
这句话确实没用.
总结
官方开发文档的内容同实际代码有一定偏差, 完全照搬不能实现预期功能, 但已经指明了一个正确的和规范化的方向, 仍然有很重要的参考价值. 本例中, 我通过进一步的调试, 通过附加最后一步注册的操作, 最终实现了官方文档中预期的功能.
另一方面, 官方文档中讲述的方法仅仅适用于增加全局模块, 例如实现电路板复位或者系统延时之类的功能, 仍然木有介绍类似于新创建一个类实例的那种模块, 例如我期望类似于下面的这种用法:
led1 = led(1)
led1.on()
led1.off()在这种用法中, 首先从led类中实例化一个对象led1, 后续的操作都是针对对象led1进行展开.
所以, 到目前为止, micropython官方提供的参考开发文档仍未满足我的需求. 实际上, 我早年在ke18f上的移植中已将摸索出了这种开发模式, 但我仍希望看到官方开放相关的文档, 以描述一种规范的开发方式.
幸运的是, 我看到mimxrt的移植中呈现了我想要的这种实现的代码, 虽然没有专门的文档描述, 但mimxrt的移植相当简单, 几乎只有一个led类的实现, 那么, 通过对这份代码进行解析, 也可以间接地学习官方实现类模块的开发规范.
