實作模組

本章詳述如何在 MicroPython 中實作核心模組。MicroPython 模組可以是下列其中一種：

  • 內建模組：屬於 MicroPython 儲存庫一部分的一般模組。

  • 使用者模組：對您特定專案有用、由您在自己的儲存庫或私有程式碼庫中維護的模組。

  • 動態模組：可在執行階段部署並匯入到您裝置上的模組。

MicroPython 中的模組可以實作在下列其中一個位置：

  • py/：鏡像 CPython 核心功能的核心程式庫。

  • extmod/：可跨多個 port 共用、屬於 CPython 或 MicroPython 特有的模組。

  • ports/<port>/：特定 port 的模組。

備註

本章描述實作於 py/ 中的模組，亦即核心模組。關於實作外部模組的詳情，請參閱 以 C 語言擴充 MicroPython。關於特定 port 模組的詳情，請參閱 移植 MicroPython。

實作核心模組

與 CPython 一樣，MicroPython 也有可透過 import 陳述式存取的核心內建模組。記憶體管理 中討論的 gc 模組即為一例。

>>> import gc
>>> gc.enable()
>>>

MicroPython 還有其他幾個內建的標準／核心模組，例如 io、array 等。新增一個新的核心模組會涉及多項修改。

首先，在 py/ 目錄中建立 C 檔案。在本範例中，我們在 modsubsystem.c 檔案裡新增一個假設的新模組 subsystem：

#include "py/builtin.h"
#include "py/runtime.h"

#if MICROPY_PY_SUBSYSTEM

// info()
static mp_obj_t py_subsystem_info(void) {
    return MP_OBJ_NEW_SMALL_INT(42);
}
MP_DEFINE_CONST_FUN_OBJ_0(subsystem_info_obj, py_subsystem_info);

static const mp_rom_map_elem_t mp_module_subsystem_globals_table[] = {
    { MP_ROM_QSTR(MP_QSTR___name__), MP_ROM_QSTR(MP_QSTR_subsystem) },
    { MP_ROM_QSTR(MP_QSTR_info), MP_ROM_PTR(&subsystem_info_obj) },
};
static MP_DEFINE_CONST_DICT(mp_module_subsystem_globals, mp_module_subsystem_globals_table);

const mp_obj_module_t mp_module_subsystem = {
    .base = { &mp_type_module },
    .globals = (mp_obj_dict_t *)&mp_module_subsystem_globals,
};

MP_REGISTER_MODULE(MP_QSTR_subsystem, mp_module_subsystem);

#endif

此實作包含與該模組相關的所有函式的定義，並將這些函式新增至模組於 mp_module_subsystem_globals_table 中的全域表。它也透過 mp_module_subsystem 建立模組物件。接著，該模組會透過 MP_REGISTER_MODULE 巨集向更廣泛的系統註冊。

在建置並執行修改後的 MicroPython 之後，現在應該就能匯入該模組了：

>>> import subsystem
>>> subsystem.info()
42
>>>

我們的 info() 函式目前僅回傳單一數字，但可以擴充成執行任何功能。同樣地，也可以為這個新模組新增更多函式。