MicroPython语言参考

本文引用的文件

产品概述

本参考面向需要在微控制器上编写MicroPython代码的开发者，聚焦以下目标：

  • 明确MicroPython的语言特性与实现范围（以Python 3.4为基准）

  • 梳理与CPython在标准库、类型和语言级功能上的差异要点

  • 提供术语表，统一理解“端口”“冻结模块”“qstr”“流对象”等概念

  • 给出在资源受限环境下的性能与内存优化建议，以及包管理与部署实践

该文档基于仓库中的官方中文参考文档整理，适用于ESP32/ESP32-S3系列mPython板型及同类MicroPython平台。

章节来源

核心业务流程

  • 学习路径

    • 从语法总览入手，了解MicroPython对Python 3.4的覆盖范围

    • 通过REPL快速验证语法与API行为

    • 结合“微控制器上的MicroPython”指南进行内存与性能调优

    • 使用upip进行包管理，必要时将第三方库冻结到固件中

  • 开发流程

    • 编写Python脚本或模块

    • 在Unix端口或目标设备上进行调试与测试

    • 针对资源受限场景进行冻结打包与部署

    • 运行后监控内存与GC行为，必要时调整阈值与调用时机

flowchart TD
A["开始"] --> B["阅读语法总览<br/>确认语言特性边界"]
B --> C["使用REPL交互式验证"]
C --> D{"是否涉及I/O或外设?"}
D -- 否 --> E["继续业务逻辑开发"]
D -- 是 --> F["查阅constrained指南<br/>优化内存与IO"]
F --> G["性能分析与调优"]
G --> H{"是否需要第三方库?"}
H -- 否 --> I["完成开发与测试"]
H -- 是 --> J["使用upip安装或交叉安装"]
J --> K{"是否低内存设备?"}
K -- 是 --> L["将依赖冻结为字节码"]
K -- 否 --> M["直接部署到文件系统"]
L --> N["构建并烧录固件"]
M --> N
N --> O["运行与监控(GC/内存)"]
O --> P["结束"]

[无图表来源；该图为概念性流程图]

功能模块清单

  • 语言与运行时

    • 语法与语义：遵循Python 3.4选择特性，大部分与CPython一致

    • REPL：自动缩进、自动补全、粘贴模式、软复位、原始模式、特殊变量_

    • 内存与GC：堆分配、碎片化、gc.collect()、阈值控制、micropython.mem_info()

    • 字符串与驻留：qstr机制、字符串比较优化、interned string

  • 性能与优化

    • const()常量替换、缓存对象引用、避免重复创建对象

    • 缓冲区与memoryview、数组与bytes/bytearray优先

    • 本地代码发射器(@micropython.native)、Viper代码发射器(@micropython.viper)

    • 直接访问硬件寄存器（如stm模块）

  • 包管理与部署

    • upip包管理器、跨平台交叉安装、冻结字节码

    • 应用资源访问（pkg_resources.resource_stream）

  • 术语与概念

    • baremetal/board/MCU/port/MicroPython Unix port/stream/upip等

章节来源

数据与状态

  • 内存模型

    • 对象分配自固定大小堆，垃圾回收自动触发并可手动调用gc.collect()

    • 可通过gc.threshold()调整触发阈值，减少长延迟与碎片化

  • 字符串与标识符

    • qstr驻留：多次出现的字符串仅存储一次，提升比较与查找效率

    • interned string：通过唯一标识引用而非地址进行比较，节省时间与空间

  • 冻结与资源

    • 冻结模块/字节码：将源码或字节码嵌入固件，降低RAM占用，无需文件系统

    • 应用资源：通过pkg_resources.resource_stream访问二进制资源，支持无文件系统场景

graph TB
subgraph "运行时"
GC["垃圾回收器"]
HEAP["堆(固定大小池)"]
QSTR["qstr驻留表"]
end
subgraph "编译/部署"
SRC["Python源码"]
BYTE["字节码(.mpy)"]
ROM["固件ROM/Flash"]
end
SRC --> BYTE
BYTE --> ROM
ROM --> QSTR
HEAP --> GC
QSTR --> |"字符串比较/查找"| 应用["应用程序"]
GC --> |"回收/阈值控制"| HEAP

[无图表来源；该图为概念性数据与状态关系图]

章节来源

关键约束与边界

  • 语言版本与特性

    • 以Python 3.4为基准，部分更高版本特性可能不可用

    • 差异主要集中于标准库、类型与少量语言级功能

  • 标准库差异示例

    • sys.implementation属性在MicroPython中仅实现必要最小集合

    • sys.path等属性在不同端口的可用性存在差异

  • 资源限制

    • RAM与闪存有限，需避免频繁创建对象与字符串拼接

    • 推荐使用预分配缓冲、bytes/bytearray、const常量、冻结模块

  • 包管理兼容性

    • upip与CPython pip不兼容；MicroPython包格式针对低内存优化

    • 低内存设备推荐交叉安装并冻结字节码，避免运行时编译与文件系统依赖

flowchart TD
Start(["开始"]) --> CheckLib["检查所需标准库"]
CheckLib --> Diff{"是否存在CPython差异?"}
Diff -- 是 --> Adapt["适配MicroPython实现<br/>或使用替代方案"]
Diff -- 否 --> Proceed["继续开发"]
Proceed --> MemCheck{"是否低内存设备?"}
MemCheck -- 是 --> Freeze["考虑冻结依赖/字节码"]
MemCheck -- 否 --> DeployFS["部署到文件系统"]
Freeze --> Build["构建固件并烧录"]
DeployFS --> Run["运行与测试"]
Build --> Run
Run --> End(["结束"])

[无图表来源；该图为概念性决策流程图]

章节来源

术语表

以下为仓库中已定义的关键术语（节选），便于统一理解：

  • baremetal：无完整操作系统的系统，如MCU；MicroPython通过REPL充当用户态OS

  • board：PCB板，常指特定MCU型号或MicroPython port对应的板型

  • callee-owned tuple：由内置函数返回的元组，生命周期受调用方控制，用于内存优化

  • CPython：Python参考实现，其他实现（含MicroPython）与其存在差异

  • GPIO/GPIO port：通用输入/输出及其端口分组

  • interned string：实习字符串，通过唯一标识引用，比较更高效

  • MCU：微控制器，资源受限但体积小功耗低

  • micropython-lib：独立于MicroPython核心的标准库子集项目

  • MicroPython port：针对不同系统/板型的移植实现

  • MicroPython Unix port：面向POSIX系统的端口，用于开发与测试

  • port：port或GPIO port的简称

  • stream：类文件对象，提供顺序读写接口

  • upip：MicroPython包管理器，功能较pip精简

章节来源