MicroPython入门手册1. 项目概述MicroPython 是一种专为微控制器设计的 Python 3 解释器实现其核心目标是在资源受限的嵌入式系统中提供简洁、高效且可交互的开发体验。本手册并非通用编程教程而是一份面向硬件工程师与嵌入式开发者的技术实践指南聚焦于如何在真实硬件平台上完成 MicroPython 的部署、调试、外设驱动开发及工程化集成。内容覆盖从固件烧录、REPL 交互、GPIO 控制到 UART/SPI/I2C 总线通信、ADC/DAC 使用、定时器中断、低功耗管理等关键环节并结合典型硬件平台如 ESP32、STM32F4 系列、RP2040展开说明。所有示例均基于官方 MicroPython 固件micropython.org 发布版本不依赖第三方发行版或定制分支。硬件选型以主流开发板为基准ESP32-DevKitCESP32-WROOM-32、NUCLEO-F411RESTM32F411RET6、Pico WRP2040 WiFi/BT。所涉引脚定义、时钟配置、外设寄存器映射均严格对应各芯片数据手册Datasheet与 MicroPython 官方 port 文档避免抽象层误导。本手册适用于三类读者硬件工程师需快速验证电路功能、调试传感器接口、生成测试激励信号嵌入式开发者希望在 C/C 主框架中嵌入 MicroPython 脚本作为配置/诊断子系统电子爱好者以最小学习成本完成原型验证规避传统裸机开发中的启动文件、链接脚本、中断向量表等底层负担。其价值不在于替代 C 语言开发而在于构建“硬件-逻辑-交互”三层快速闭环硬件连通性验证 → 外设行为建模 → 用户指令响应。这种能力在产品预研、产线校准、现场故障复现等场景中具有不可替代性。2. 开发环境搭建2.1 工具链与固件获取MicroPython 不需要编译整个工具链但需明确区分两个层级宿主机工具与目标板固件。宿主机工具esptool.pyESP32 平台用于擦除 Flash、烧录固件、读取芯片信息。安装方式pip install esptool。stlink或openocdSTM32 平台STLINK-V2/V3 仿真器需配合st-flash命令行工具来自 stlink 项目完成固件写入OpenOCD 支持更广但配置复杂度高本手册默认采用st-flash。picotoolRP2040 平台Raspberry Pi 官方维护的命令行工具支持固件烧录、USB 设备枚举、UF2 格式转换。安装方式pip install picotool。固件获取所有固件均从 micropython.org/download 下载按芯片型号与发布日期组织。选择原则如下优先使用latest标签对应版本如esp32-20230918-v1.21.0.bin该版本已通过 CI 测试兼容主流外设驱动若项目涉及特定硬件如带 PSRAM 的 ESP32-WROVER须下载对应 variantesp32-20230918-v1.21.0-wrover.binSTM32 固件需匹配 board 类型NUCLEO_F411RE、DISCO_F407VG不可混用RP2040 固件分pico无无线与pico_w含 CYW43439 WiFi/BT 芯片后者需额外加载cyw43-firmware.bin到 Flash 特定地址0x101000此步骤由picotool自动处理。工程提示固件版本号如 v1.21.0与 Python 语法兼容性强相关。v1.19 引入asyncio模块完整支持v1.20 增加machine.Timer的callback参数类型检查v1.21 修复 RP2040 ADC 偏移误差。生产环境中应锁定固件哈希值SHA256而非仅依赖版本号。2.2 串口连接与 REPL 配置MicroPython 启动后自动启用 UART REPLRead-Eval-Print Loop这是最基础的交互通道。配置要点如下波特率默认为 115200部分 STM32 板卡如 NUCLEO-F411RE因 HSE 时钟精度问题在 921600 波特下误码率升高建议维持 115200串口设备识别Linux/dev/ttyUSB0CH340、/dev/ttyACM0CDC ACM 类设备如 Pico、ESP32-S2WindowsCOM3、COM4需确认设备管理器中端口号macOS/dev/cu.usbserial-*CP2102、/dev/cu.usbmodem*Pico终端工具选择推荐picocomLinux/macOS轻量、无缓冲、支持 CtrlA 发送 break命令picocom -b 115200 /dev/ttyUSB0Windows 推荐PuTTY或Tera Term禁用“本地回显”与“行编辑”确保原始字节流传输REPL 进入方式上电或复位后立即按下CtrlC可中断正在运行的main.py返回提示符若需强制进入安全模式跳过boot.py和main.py在启动瞬间按住CtrlD。关键现象识别正常启动日志以MicroPython v1.21.0 on 2023-09-18; ESP32 module with ESP32开头若出现OSError: [Errno 19] ENODEV表明 UART 驱动未正确加载或线缆接触不良若提示符无响应检查是否误将 TX/RX 反接常见于杜邦线颜色混淆。2.3 文件系统挂载与代码部署MicroPython 内置 FAT 文件系统LittleFS 用于部分 STM32 port支持通过uos模块操作。部署流程如下格式化 Flash首次使用或固件升级后import os os.VfsLfs2.mkfs(bdev) # STM32/LPC port # 或 os.VfsFat.mkfs(bdev) # ESP32/RP2040 port挂载文件系统import os bdev machine.SDCard() # 若外接 SD 卡 # 或直接使用内置 Flash os.mount(os.VfsFat(bdev), /flash) os.chdir(/flash)代码上传方式手动复制通过rshell推荐或ampy工具将.py文件推送到/flashrshell -p /dev/ttyUSB0 cp main.py /flash/main.pyWebREPLESP32/Pico W启用后通过浏览器访问http://microcontroller.local支持拖拽上传但需注意WebREPL 默认关闭需在 REPL 中执行import webrepl_setup启动向导传输速率受 WiFi 信道干扰影响大文件建议改用串口UF2 拖放RP2040按住 BOOTSEL 键上电设备显示为 U 盘直接复制.uf2固件或.py文件至根目录松手后自动重启加载。工程实践建议boot.py用于硬件初始化如设置 UART 波特率、配置 LED 引脚不应包含业务逻辑main.py为入口点应包含while True:主循环避免脚本退出导致板卡空闲所有外设驱动模块如ssd1306.py、bme280.py应置于/lib子目录并在main.py中通过sys.path.append(/lib)添加路径。3. 硬件外设控制实践3.1 GPIO 输入/输出与中断GPIO 是最基础的外设MicroPython 提供machine.Pin类封装。关键参数包括modePin.IN输入、Pin.OUT推挽输出、Pin.OPEN_DRAIN开漏pullPin.PULL_UP、Pin.PULL_DOWN内部上下拉非所有芯片支持value()读取/写入电平0/1。典型应用按键消抖与 LED 控制from machine import Pin import time led Pin(2, Pin.OUT) # ESP32 GPIO2 控制板载 LED button Pin(0, Pin.IN, Pin.PULL_UP) # GPIO0 接按键上拉 def toggle_led(pin): led.value(not led.value()) # 绑定外部中断下降沿触发 button.irq(triggerPin.IRQ_FALLING, handlertoggle_led) # 主循环仅作看门狗喂食可选 while True: time.sleep_ms(100)硬件设计关联说明Pin.PULL_UP依赖芯片内部电阻ESP32 典型值 45 kΩSTM32F4 为 30–50 kΩ若外部按键线路较长10 cm建议增加 10 kΩ 外部上拉以抑制干扰中断服务函数ISR必须轻量禁止调用time.sleep()、print()、uos.listdir()等阻塞或分配内存的操作RP2040 的Pin.irq()不支持Pin.IRQ_RISING_FALLING需通过软件边沿检测实现。3.2 UART 通信传感器数据采集UART 常用于连接温湿度传感器如 DHT22、GPS 模块UBLOX NEO-6M、AT 指令设备。MicroPython 使用machine.UART类需指定tx、rx引脚及波特率。示例读取 MAX30102 心率血氧传感器I2C 接口此处转为 UART 模拟实际中 MAX30102 为 I2C 设备但为演示 UART 流程假设某 UART 输出型心率模块from machine import UART, Pin import time uart UART(2, baudrate115200, txPin(17), rxPin(16)) # ESP32 UART2 uart.init(bits8, parityNone, stop1) # 显式初始化 def read_heart_rate(): uart.write(bGET_HR\n) # 发送查询指令 time.sleep_ms(50) data uart.read(16) # 读取最多 16 字节 if data: try: return int(data.decode().strip()) except ValueError: return None return None while True: hr read_heart_rate() if hr is not None: print(Heart Rate:, hr, BPM) time.sleep(2)电气与协议要点UART 电平需匹配3.3 V MCU 不可直连 5 V TTL 设备需电平转换芯片如 TXB0104uart.read()返回bytes对象非字符串decode()前需确认数据完整性建议添加帧头/校验高速 UART≥921600在长线传输时需终端匹配电阻120 Ω否则上升沿振铃导致误码。3.3 I2C 与 SPI传感器与显示屏驱动I2C 实践BME280 环境传感器BME280 支持 I2C地址 0x76 或 0x77与 SPII2C 更节省引脚。MicroPython 初始化from machine import I2C, Pin import bme280 # 需提前将 bme280.py 放入 /lib i2c I2C(0, sclPin(22), sdaPin(21), freq400000) # ESP32 I2C0 bme bme280.BME280(i2ci2c) while True: temp, pressure, humidity bme.values print(fTemp: {temp}, Pressure: {pressure}, Humidity: {humidity}) time.sleep(2)I2C 硬件约束SCL/SDA 线必须接 4.7 kΩ 上拉电阻VDD3.3 V多设备共用总线时地址冲突需通过硬件跳线如 BME280 的 SDO 引脚切换freq400000为标准模式上限若传感器响应慢如某些 EEPROM需降至 100 kHz。SPI 实践SSD1306 OLED 显示屏SSD1306 常用 4 线 SPIDC、RST、CS、SCK、MOSIRP2040 示例from machine import Pin, SPI import ssd1306 spi SPI(0, 10000000, polarity0, phase0, bits8, firstbitSPI.MSB, sckPin(18), mosiPin(19), misoPin(16)) # RP2040 SPI0 oled ssd1306.SSD1306_SPI(128, 64, spi, Pin(17), Pin(20), Pin(16)) oled.fill(0) oled.text(Hello MicroPython, 0, 0) oled.show()SPI 关键参数解释polarity0空闲时 SCK 为低电平phase0数据在第一个边沿采样firstbitSPI.MSB高位先传符合 SSD1306 协议RST 引脚用于硬件复位若省略则需软件复位序列发送 0xE2 指令。4. 高级功能定时器、ADC、低功耗4.1 定时器与 PWM 输出machine.Timer提供硬件定时器machine.PWM生成可变占空比方波。示例呼吸灯PWM 渐变from machine import PWM, Pin import time pwm PWM(Pin(2)) # ESP32 GPIO2 pwm.freq(1000) # 1 kHz 载波 def breathe(): for i in range(0, 1024, 8): # 0~1023 占空比 pwm.duty(i) time.sleep_ms(2) for i in range(1023, -1, -8): pwm.duty(i) time.sleep_ms(2) while True: breathe()PWM 硬件限制ESP32 支持 16 路通道但频率 1 MHz 时分辨率降至 8 bitSTM32F4 的machine.PWM实际映射到 TIMx_CHy需确保引脚复用功能已使能如 PA8 → TIM1_CH1RP2040 的 PWM 分辨率固定为 8 bit最大频率约 125 MHz / 256 ≈ 488 kHz。4.2 ADC 采集与校准ADC 用于读取模拟传感器电位器、光敏电阻、电池电压。MicroPython 中machine.ADC类提供read_u16()16-bit或read_uv()微伏需芯片支持。ESP32 ADC2 注意事项ADC2 与 WiFi 共享当启用 WiFi 时ADC2通道不可用。解决方案使用 ADC1 通道GPIO32–GPIO39或在 WiFi 初始化前完成 ADC 采集。from machine import ADC, Pin adc ADC(Pin(34)) # ESP32 GPIO34 (ADC1_CH6) adc.atten(ADC.ATTN_11DB) # 量程 0–3.3 V adc.width(ADC.WIDTH_12BIT) # 12-bit 分辨率 while True: val adc.read() # 返回 0–4095 voltage val * 3.3 / 4095 print(Voltage:, round(voltage, 2), V) time.sleep(1)ADC 精度提升措施外部参考电压Vref比内部更稳定ESP32 可通过adc.vref_to_pin()将 Vref 输出至 GPIO再用万用表校准多次采样取平均sum(adc.read() for _ in range(16)) // 16避免在 ADC 引脚附近布设高频数字走线如 USB、SDIO。4.3 低功耗模式Deep Sleep 与 Wake-upESP32 支持machine.deepsleep()电流可降至 10 μA。唤醒源包括定时器machine.deepsleep(time_ms)外部引脚machine.Pin.irq()配合wake参数ULP 协处理器需 C 代码配置MicroPython 不直接支持。from machine import Pin, RTC import time # 配置 GPIO13 为唤醒源低电平触发 wake1 Pin(13, modePin.IN, pullPin.PULL_UP) rtc RTC() rtc.wake_on_ext0(pinwake1, levelrtc.WAKEUP_ALL_LOW) print(Going to sleep...) machine.deepsleep(10000) # 10 秒后自动唤醒硬件配合要求Deep Sleep 期间 VDD3P3_RTC 电源必须持续供电通常由主电源或纽扣电池提供外部唤醒引脚需满足电压阈值ESP32 为 0.8×VDD建议串联 10 kΩ 限流电阻STM32F4 无原生 deepsleep需通过machine.lightsleep()停 CPU外设时钟保持或machine.deepsleep()需 patch HAL 库。5. 工程化建议与常见问题排查5.1 代码健壮性设计异常捕获传感器通信失败、文件不存在等应被try...except包裹避免main.py崩溃try: temp bme.temperature except OSError as e: print(BME280 read failed:, e) temp None看门狗WatchdogESP32 支持machine.WDT防止死循环锁死wdt machine.WDT(timeout8000) # 8 秒超时 while True: do_something() wdt.feed() # 重置计数器5.2 典型故障现象与定位现象可能原因排查步骤REPL 无响应UART 线序错误、波特率不匹配、供电不足用逻辑分析仪抓取 TX 波形确认起始位宽度测量 VCC 是否 ≥3.0 VImportError: no module named xxx模块未放入/lib或路径未添加在 REPL 中执行import sys; print(sys.path)确认/lib在列表中ADC 读数恒为 0 或 4095引脚悬空、硬件短路、ADC 通道被复用用万用表测引脚电压检查原理图中是否误接其他信号I2C 扫描不到设备i2c.scan()返回空列表上拉电阻缺失、SCL/SDA 反接、地址错误用示波器观察 SCL 是否有周期性波形确认传感器供电正常5.3 生产环境部署 checklist[ ] 固件版本固化记录 SHA256 值[ ]boot.py中禁用print()避免启动日志占用 UART[ ]main.py开头添加import gc; gc.collect()释放内存碎片[ ] 外设初始化失败时LED 快闪 3 次提示硬件异常[ ] 所有time.sleep()替换为time.sleep_ms()避免浮点运算开销[ ] 使用const()函数声明常量如from micropython import const; PIN_LED const(2)减少 RAM 占用。MicroPython 的价值在于将硬件工程师从寄存器配置的繁琐中解放使其专注信号链完整性、电源噪声抑制、PCB 布局对时序的影响等真正决定产品成败的底层问题。当一个machine.Pin(2, Pin.OUT).on()能在 100 ms 内点亮 LED背后是 BootROM 对 Flash 的映射、CPU 对 GPIO 外设的时钟使能、以及 IO 复用控制器对引脚功能的仲裁——这些细节无需亲手编写但必须了然于胸。