从MicroPython迁移到CircuitPython先别急这5个坑我帮你踩过了附代码适配方案去年夏天当我第一次把ESP32开发板上的MicroPython固件替换成CircuitPython时满心期待能立即用上摄像头驱动和MP3解码功能。但现实给了我一记闷棍——原本运行良好的传感器采集代码突然报出machine module not found错误。这就像带着瑞士军刀去野外生存结果发现新买的升级版竟然连最基本的开瓶器都换了位置。如果你也正在考虑从MicroPython转向CircuitPython不妨先看看我在三个实际项目中总结的迁移经验。1. 基础模块的平行宇宙第一次导入machine模块失败时我盯着错误信息愣了半天。CircuitPython用完全不同的模块体系重构了底层硬件交互方式这就像Python 2到Python 3的转变表面相似却暗藏玄机。1.1 硬件控制模块的对应关系MicroPython的硬件控制集中在machine模块而CircuitPython将其拆分为多个专用模块功能类型MicroPython模块CircuitPython模块GPIO控制machine.Pindigitalio.DigitalInOut定时器machine.Timercountio.Counter模拟信号machine.ADCanalogio.AnalogIn系统控制machine.reset()supervisor.reload()最让人头疼的是引脚编号映射问题。在MicroPython中直接使用数字引脚号的方式在CircuitPython会引发灾难。这是我用来自动转换引脚对象的兼容层代码import sys CIRCUITPY (sys.implementation.name circuitpython) if CIRCUITPY: import microcontroller # 构建引脚映射字典 pin_map {int(name[3:]): pin for name, pin in ( (attr, getattr(microcontroller.pin, attr)) for attr in dir(microcontroller.pin) if isinstance(getattr(microcontroller.pin, attr), microcontroller.Pin) )} def get_pin(num): return pin_map.get(num, None) else: from machine import Pin get_pin Pin1.2 时间模块的微妙差异两个系统的时间处理也有不少坑。最典型的是localtime()返回的元组结构不同# MicroPython返回8元素元组 (year, month, day, hour, minute, second, weekday, yearday) # CircuitPython返回9元素元组 (year, month, day, hour, minute, second, weekday, yearday, isdst)为此我专门写了转换函数def compat_localtime(secsNone): if CIRCUITPY: t time.localtime(secs) return t[:-1] # 去掉最后的isdst else: return time.localtime(secs)2. 外设驱动接口的思维转换当我尝试迁移一个I2C传感器驱动时发现两个系统对总线协议的处理方式截然不同。MicroPython的machine.I2C是瑞士军刀式的多功能接口而CircuitPython的busio.I2C更像是专业工具套装。2.1 I2C通信的两种范式下表对比了关键操作的不同实现操作描述MicroPython实现CircuitPython实现初始化I2Ci2c machine.I2C(scl,sda)i2c busio.I2C(scl,sda)扫描设备i2c.scan()while not i2c.try_lock(): passdevices i2c.scan()i2c.unlock()写入寄存器i2c.writeto_mem(addr,reg,data)buf bytearray([reg]) datai2c.writeto(addr, buf)CircuitPython强制要求加锁的操作起初让我很不适应但这种设计确实避免了多线程下的总线冲突。这是我的兼容性封装class I2C_Adapter: def __init__(self, scl, sda, freq400000): if CIRCUITPY: import busio self.i2c busio.I2C(scl, sda, frequencyfreq) else: from machine import I2C self.i2c I2C(0, sclscl, sdasda, freqfreq) def write_reg(self, addr, reg, data): if CIRCUITPY: with self.i2c as i2c: i2c.write(bytes([reg]) data) else: self.i2c.writeto_mem(addr, reg, data)2.2 SPI设备的隐藏陷阱迁移SPI设备驱动时时钟极性(CPOL)和相位(CPHA)的设置差异差点让我抓狂。MicroPython用0/1组合表示模式而CircuitPython使用明确的常量# MicroPython模式设置 spi.init(baudrate1_000_000, polarity0, phase0) # 模式0 # CircuitPython等效设置 from busio import SPI spi SPI(clock, MOSI, MISO, baudrate1_000_000, polarity0, phase0)更麻烦的是某些CircuitPython板子的SPI实现对高频支持不稳定。我在ESP32-S3上测试时超过10MHz就会丢数据而同样的硬件在MicroPython下能稳定工作在20MHz。3. 中断处理的范式转移按键中断处理是我遇到的最大挑战之一。MicroPython的中断回调机制直接明了而CircuitPython的keypad模块采用了完全不同的事件队列模型。3.1 按键检测的两种哲学MicroPython的中断处理简单粗暴from machine import Pin def button_callback(pin): print(Button pressed!) button Pin(12, Pin.IN, Pin.PULL_UP) button.irq(button_callback, Pin.IRQ_FALLING)CircuitPython则需要更多基础设施import keypad import board keys keypad.Keys((board.BUTTON,), value_when_pressedFalse, pullTrue) while True: event keys.events.get() if event and event.pressed: print(Button pressed!)3.2 兼容层实现方案为了让代码跨平台运行我设计了这个混合方案class ButtonHandler: def __init__(self, pin): self.pin pin if CIRCUITPY: self.keys keypad.Keys((pin,), value_when_pressedFalse, pullTrue) else: from machine import Pin self.pin Pin(pin, Pin.IN, Pin.PULL_UP) self.pressed False self.pin.irq(handlerself._callback, triggerPin.IRQ_FALLING) def _callback(self, pin): self.pressed True def check_pressed(self): if CIRCUITPY: event self.keys.events.get() return event and event.pressed else: if self.pressed: self.pressed False return True return False4. 文件系统的权限陷阱项目中最惊险的时刻是当我发现CircuitPython默认以只读模式挂载文件系统。这意味着所有文件写操作都会静默失败没有任何错误提示4.1 存储挂载的默认行为MicroPython通常以读写模式挂载文件系统而CircuitPython基于安全考虑默认只读。需要显式调用import storage storage.remount(/, readonlyFalse)但要注意这个操作在部分开发板上会导致USB连接暂时断开。更好的做法是在boot.py中添加import usb_cdc usb_cdc.enable(consoleTrue, dataTrue) # 保持USB连接4.2 文件操作的兼容技巧处理文件路径时CircuitPython对根目录的表示更严格。这是我总结的路径处理最佳实践def get_path(filename): if CIRCUITPY: if not filename.startswith(/): return / filename return filename with open(get_path(config.json), r) as f: config json.load(f)5. 图形显示的兼容方案当我尝试移植一个OLED显示项目时发现两个系统的帧缓冲实现差异巨大。MicroPython的framebuf模块功能完整而CircuitPython的framebufferio还在发展中。5.1 图形API的功能对比功能MicroPython支持CircuitPython支持基本绘图原语是部分文本渲染是通过Label组件硬件加速否部分板卡支持5.2 跨平台图形解决方案最终我采用了显示驱动抽象层class DisplayAdapter: def __init__(self, width, height): if CIRCUITPY: import displayio self.display displayio.Display(...) self.group displayio.Group() self.display.show(self.group) else: import ssd1306 self.display ssd1306.SSD1306_I2C(width, height, i2c) def show_text(self, text, x, y): if CIRCUITPY: from adafruit_display_text import label text_area label.Label(font, texttext, xx, yy) self.group.append(text_area) else: self.display.text(text, x, y)移植过程中最耗时的部分是重新实现blit操作。CircuitPython的displayio采用完全不同的图块管理机制需要理解其Group-TileGrid的层级结构。
从MicroPython迁移到CircuitPython？先别急，这5个坑我帮你踩过了（附代码适配方案）
从MicroPython迁移到CircuitPython先别急这5个坑我帮你踩过了附代码适配方案去年夏天当我第一次把ESP32开发板上的MicroPython固件替换成CircuitPython时满心期待能立即用上摄像头驱动和MP3解码功能。但现实给了我一记闷棍——原本运行良好的传感器采集代码突然报出machine module not found错误。这就像带着瑞士军刀去野外生存结果发现新买的升级版竟然连最基本的开瓶器都换了位置。如果你也正在考虑从MicroPython转向CircuitPython不妨先看看我在三个实际项目中总结的迁移经验。1. 基础模块的平行宇宙第一次导入machine模块失败时我盯着错误信息愣了半天。CircuitPython用完全不同的模块体系重构了底层硬件交互方式这就像Python 2到Python 3的转变表面相似却暗藏玄机。1.1 硬件控制模块的对应关系MicroPython的硬件控制集中在machine模块而CircuitPython将其拆分为多个专用模块功能类型MicroPython模块CircuitPython模块GPIO控制machine.Pindigitalio.DigitalInOut定时器machine.Timercountio.Counter模拟信号machine.ADCanalogio.AnalogIn系统控制machine.reset()supervisor.reload()最让人头疼的是引脚编号映射问题。在MicroPython中直接使用数字引脚号的方式在CircuitPython会引发灾难。这是我用来自动转换引脚对象的兼容层代码import sys CIRCUITPY (sys.implementation.name circuitpython) if CIRCUITPY: import microcontroller # 构建引脚映射字典 pin_map {int(name[3:]): pin for name, pin in ( (attr, getattr(microcontroller.pin, attr)) for attr in dir(microcontroller.pin) if isinstance(getattr(microcontroller.pin, attr), microcontroller.Pin) )} def get_pin(num): return pin_map.get(num, None) else: from machine import Pin get_pin Pin1.2 时间模块的微妙差异两个系统的时间处理也有不少坑。最典型的是localtime()返回的元组结构不同# MicroPython返回8元素元组 (year, month, day, hour, minute, second, weekday, yearday) # CircuitPython返回9元素元组 (year, month, day, hour, minute, second, weekday, yearday, isdst)为此我专门写了转换函数def compat_localtime(secsNone): if CIRCUITPY: t time.localtime(secs) return t[:-1] # 去掉最后的isdst else: return time.localtime(secs)2. 外设驱动接口的思维转换当我尝试迁移一个I2C传感器驱动时发现两个系统对总线协议的处理方式截然不同。MicroPython的machine.I2C是瑞士军刀式的多功能接口而CircuitPython的busio.I2C更像是专业工具套装。2.1 I2C通信的两种范式下表对比了关键操作的不同实现操作描述MicroPython实现CircuitPython实现初始化I2Ci2c machine.I2C(scl,sda)i2c busio.I2C(scl,sda)扫描设备i2c.scan()while not i2c.try_lock(): passdevices i2c.scan()i2c.unlock()写入寄存器i2c.writeto_mem(addr,reg,data)buf bytearray([reg]) datai2c.writeto(addr, buf)CircuitPython强制要求加锁的操作起初让我很不适应但这种设计确实避免了多线程下的总线冲突。这是我的兼容性封装class I2C_Adapter: def __init__(self, scl, sda, freq400000): if CIRCUITPY: import busio self.i2c busio.I2C(scl, sda, frequencyfreq) else: from machine import I2C self.i2c I2C(0, sclscl, sdasda, freqfreq) def write_reg(self, addr, reg, data): if CIRCUITPY: with self.i2c as i2c: i2c.write(bytes([reg]) data) else: self.i2c.writeto_mem(addr, reg, data)2.2 SPI设备的隐藏陷阱迁移SPI设备驱动时时钟极性(CPOL)和相位(CPHA)的设置差异差点让我抓狂。MicroPython用0/1组合表示模式而CircuitPython使用明确的常量# MicroPython模式设置 spi.init(baudrate1_000_000, polarity0, phase0) # 模式0 # CircuitPython等效设置 from busio import SPI spi SPI(clock, MOSI, MISO, baudrate1_000_000, polarity0, phase0)更麻烦的是某些CircuitPython板子的SPI实现对高频支持不稳定。我在ESP32-S3上测试时超过10MHz就会丢数据而同样的硬件在MicroPython下能稳定工作在20MHz。3. 中断处理的范式转移按键中断处理是我遇到的最大挑战之一。MicroPython的中断回调机制直接明了而CircuitPython的keypad模块采用了完全不同的事件队列模型。3.1 按键检测的两种哲学MicroPython的中断处理简单粗暴from machine import Pin def button_callback(pin): print(Button pressed!) button Pin(12, Pin.IN, Pin.PULL_UP) button.irq(button_callback, Pin.IRQ_FALLING)CircuitPython则需要更多基础设施import keypad import board keys keypad.Keys((board.BUTTON,), value_when_pressedFalse, pullTrue) while True: event keys.events.get() if event and event.pressed: print(Button pressed!)3.2 兼容层实现方案为了让代码跨平台运行我设计了这个混合方案class ButtonHandler: def __init__(self, pin): self.pin pin if CIRCUITPY: self.keys keypad.Keys((pin,), value_when_pressedFalse, pullTrue) else: from machine import Pin self.pin Pin(pin, Pin.IN, Pin.PULL_UP) self.pressed False self.pin.irq(handlerself._callback, triggerPin.IRQ_FALLING) def _callback(self, pin): self.pressed True def check_pressed(self): if CIRCUITPY: event self.keys.events.get() return event and event.pressed else: if self.pressed: self.pressed False return True return False4. 文件系统的权限陷阱项目中最惊险的时刻是当我发现CircuitPython默认以只读模式挂载文件系统。这意味着所有文件写操作都会静默失败没有任何错误提示4.1 存储挂载的默认行为MicroPython通常以读写模式挂载文件系统而CircuitPython基于安全考虑默认只读。需要显式调用import storage storage.remount(/, readonlyFalse)但要注意这个操作在部分开发板上会导致USB连接暂时断开。更好的做法是在boot.py中添加import usb_cdc usb_cdc.enable(consoleTrue, dataTrue) # 保持USB连接4.2 文件操作的兼容技巧处理文件路径时CircuitPython对根目录的表示更严格。这是我总结的路径处理最佳实践def get_path(filename): if CIRCUITPY: if not filename.startswith(/): return / filename return filename with open(get_path(config.json), r) as f: config json.load(f)5. 图形显示的兼容方案当我尝试移植一个OLED显示项目时发现两个系统的帧缓冲实现差异巨大。MicroPython的framebuf模块功能完整而CircuitPython的framebufferio还在发展中。5.1 图形API的功能对比功能MicroPython支持CircuitPython支持基本绘图原语是部分文本渲染是通过Label组件硬件加速否部分板卡支持5.2 跨平台图形解决方案最终我采用了显示驱动抽象层class DisplayAdapter: def __init__(self, width, height): if CIRCUITPY: import displayio self.display displayio.Display(...) self.group displayio.Group() self.display.show(self.group) else: import ssd1306 self.display ssd1306.SSD1306_I2C(width, height, i2c) def show_text(self, text, x, y): if CIRCUITPY: from adafruit_display_text import label text_area label.Label(font, texttext, xx, yy) self.group.append(text_area) else: self.display.text(text, x, y)移植过程中最耗时的部分是重新实现blit操作。CircuitPython的displayio采用完全不同的图块管理机制需要理解其Group-TileGrid的层级结构。
