★ FEATURED ARTICLE 如果你捣鼓过 MicroPython大概率经历过这样的痛想用某个传感器驱动先得在 GitHub 上翻仓库找到匹配你固件版本的源文件手动下载再用串口工具一个一个传进板子的 flash要是这个驱动还依赖别人写的库那得层层递归地手动补齐。一旦板子固件升级、或者换一块开发板所有依赖可能又要重来一遍。我自己早期踩过无数坑之后才算彻底理解了“包管理”这三个字在嵌入式微控制器世界里有多重要。而 uPyPi 这个工具就是用来把这一整套繁琐流程收拢成几条命令行指令的。这篇文章我会把从零开始用 uPyPi 安装驱动到自己打包驱动分享出来的完整路径都走一遍全程保姆级注释保证你照着敲就能跑通。先说清楚 uPyPi 是什么、能做什么、适合谁。uPyPi 是一个面向 MicroPython 的包管理和发布工具你可以把它理解成嵌入式世界的 “pip” 或 “npm”但它专门服务于资源受限的微控制器。它解决的最核心问题有三个第一驱动与依赖的一键安装第二包版本的统一管理第三让开发者能够把自己的驱动或工具包发布出来供别人直接安装使用。适合所有使用 MicroPython 开发的人无论你是刚点亮第一块 LED 的完全新手还是已经在做复杂物联网项目的进阶玩家搞懂这套流程都能省下大量时间。1. 为什么 MicroPython 生态需要 uPyPi 这样的工具1.1 手动管理驱动包的痛苦我亲身踩过先聊聊没有 uPyPi 之前的日子因为这决定了你愿不愿意花十分钟学习它。MicroPython 官方其实提供了一个内置的包下载工具叫 upip命令行风格类似 pip但它有两个很明显的短板一是它默认依赖 MicroPython 官方维护的软件源而官方源里的驱动数量有限更新速度也慢二是它只管安装不管怎么准确匹配开发板的硬件版本和固件特性因为 MicroPython 在不同芯片上的差异太大了。于是大多数开发者回到纯手工模式。举个例子我当时做一个温湿度监控项目用到了一个 OLED 显示驱动本身只有一个文件看着很简单但它的代码里又 import 了另一个字体库模块。我又得去找字体库字体库又依赖一个图像缓冲模块。等全部找齐一共五个文件每个文件还得用串口工具通过webrepl或者ampy逐个推送。好不容易装完跑起来报错说某个函数不支持一查才知道固件版本太旧驱动作者用了新 API。我那时候心想这要是有个 pip 该多好。1.2 uPyPi 到底解决了哪些具体问题uPyPi 针对上述场景做了三件很实在的事情统一索引它维护了一个包含大量 MicroPython 驱动和工具的软件源把散落在各个地方的开源驱动收拢到一个可搜索的仓库里。你只需要记住一个命令就能找到想要的库。依赖解析安装一个包时uPyPi 会自动读取这个包声明的依赖关系然后把依赖的依赖一起拉下来。这一步省掉的不只是手动下载的时间更重要的是避免了“文件残缺”造成的运行时报错。版本与目标板适配每个包可以声明它兼容的 MicroPython 版本和开发板平台。安装的时候uPyPi 会检查你板子上的固件信息选择更合适的版本这一点对于 ESP32、RP2040、STM32 这些不同架构的板子特别重要。所以它本质上不是把现有的文件复制粘贴到板子上而是替你完成了整个决策链从“该装哪个版本”到“装完怎么处理依赖”再到“能不能正常运行”。2. 环境准备和 uPyPi 基础安装2.1 在电脑上装好 uPyPi 命令行工具uPyPi 本身是运行在桌面电脑上的 Python 程序不是跑在板子里的。它通过串口或网络协议和你的 MicroPython 设备通信。因此电脑上需要有 Python 环境建议 Python 3.8 以上然后一条命令就能安装python -m pip install upypi装完后验证一下upypi --version能看到版本号就算成功。如果你的电脑上装了多个 Python 版本记得保证命令和 pip 的对应关系正确。我自己用 Windows WSL 和 macOS 都试过注意别用系统自带的 Python那种环境通常不好控制推荐用 pyenv 或 virtualenv 建一个干净的虚拟环境再装避免污染系统环境也避免权限问题。2.2 准备一块 MicroPython 开发板并检查连接你需要一块已经烧录好 MicroPython 固件的开发板比较常用的是 ESP32 系列、树莓派 Pico 系列或者 ESP8266。把开发板通过 USB 线连接到电脑先确认驱动正常。Windows 里可能在设备管理器看到 COM 口macOS/Linux 一般是/dev/ttyUSB0或/dev/ttyACM0。然后装一个辅助工具来测试连接我习惯用mpremotepython -m pip install mpremote运行mpremote connect /dev/ttyUSB0 info如果打印出板子的型号、固件版本、唯一 ID说明通信没问题。如果你一时不知道串口是哪个也可以让mpremote自动探测mpremote connect auto info这一步很关键因为 uPyPi 后续所有操作都建立在正确的连接之上。连接好之后先用mpremote做一次简单测试能少踩很多后期莫名其妙的坑。2.3 uPyPi 首次启动需要做的配置uPyPi 安装完成后建议先运行一次配置向导upypi init这个命令会生成一个配置文件里面有默认的包下载目录通常是当前目录下的lib文件夹和设备连接参数。真正需要手动改的只有两点设备端口地址比如/dev/cu.usbserial-0001或COM3。目标板类型比如esp32、rp2、esp8266等。配置好之后可以通过upypi config list查看最终结果。我建议把这步做好因为后面每次安装都要用到正确的设备信息与其每次敲一串参数不如初始化时固定住。3. 保姆级实操从检索到安装一条龙3.1 搜索可用的驱动包要安装软件包第一步是搜索。驱动包的名字如果不够明确可能搜出来的结果很多。uPyPi 的搜索支持模糊匹配upypi search oled这会返回一堆和 OLED 相关的包每一条都有包名、简介、版本和作者信息。比如某一条显示ssd1306-2.1.0说明是一个驱动 SSD1306 控制器的库。你还可以加--filter esp32来只看支持 ESP32 的包upypi search oled --filter esp32这么做的好处是普通模糊搜索把不同平台的包都混在一起对于不熟悉生态的新手来说容易把只支持 AVR 的包装到 RP2040 上。加过滤条件以后结果更贴近你的开发板。3.2 安装第一个驱动包只写一条命令搜索到目标包以后安装极其直观upypi install ssd1306执行后uPyPi 会先检查设备然后把包文件传输到开发板的/lib目录。终端的输出会显示每一步状态收到Package installed successfully就是装好了。如果当前目录下也有一份lib文件夹你可能会疑惑装到哪了。默认情况下uPyPi 会优先把包安装到设备板载存储除非你指定--target参数。还有一种情况是板子的 flash 空间不够官方默认固件经常会遇到这种问题。这时候可以使用upypi install ssd1306 --target ./lib这样会先下载到电脑本地的lib目录你再通过mpremote cp或者webdav方式传过去。我一般在开发调试阶段都这么干本地有一份文件副本出错时排查方便设备刷机后也能快速批量恢复。3.3 批量安装依赖requirements 文件一个项目需要安装多个包时逐个输入命令太累。uPyPi 支持requirements.txt形式的文件。新建一个文本文件内容ssd1306 umqtt.simple onewire然后执行upypi install -r requirements.txt它会按顺序全部装完并且会识别这些包之间的依赖关系。如果一个包 A 依赖 B而 requirements 里没写 BuPyPi 也会自动把 B 拉进来。这解决了我在文章开头说的那个“装 A 结果依赖 B 找不到”的经典难题。3.4 管理已安装的包安装只是起点日常管理同样重要。几个常用命令# 列出设备上已安装的包 upypi list # 更新某个包到最新版本 upypi update ssd1306 # 卸载某个包 upypi uninstall ssd1306需要注意upypi list显示的是通过 uPyPi 安装并有记录的包如果你之前是手动拷贝进去的文件它是不会显示的。不过 uPyPi 也支持扫描/lib目录来发现没有记录的包命令是upypi scan扫描以后会把识别到的模块名也加入列表方便统一管理。这个功能对常年在不同机器之间切换开发环境的工程师来说很友好能快速了解到当前板子上的“隐藏资产”。4. 把你自己写的驱动发布到 uPyPi详细拆解4.1 理解 MicroPython 包的结构要求发布分享的前提是你有一个规范的包结构。MicroPython 的包通常有两种形式单文件模块比如bh1750.py适合几 KB 的轻量驱动。多文件包一个目录下包含多个模块目录名就是导入名适合稍复杂的功能或带示例代码的项目。推荐用第二种因为便于后续扩展。一个发布到 uPyPi 的包需要具备以下内容mydriver/ ├── manifest.py ├── mydriver │ ├── __init__.py │ ├── core.py │ └── helper.py └── README.mdmanifest.py是 MicroPython 打包逻辑的文件它定义了哪些文件会被安装到设备上。但 uPyPi 还需要额外的元信息比如包名、版本、描述、依赖等。这里我通常用一个独立的pyproject.toml或upypi.toml来描述。uPyPi 当前主要识别pyproject.toml里的[project]表。4.2 一步步构建自己的驱动程序示例假设我要分享一个驱动 I2C 接口光照传感器的库命名为mylight_i2c。我的目录结构是这样mylight_i2c/ ├── manifest.py ├── pyproject.toml ├── mylight_i2c │ ├── __init__.py │ └── sensor.py └── README.mdpyproject.toml核心内容[project] name mylight_i2c version 1.0.0 description An I2C light sensor driver for MicroPython authors [YourName] dependencies [mylogger0.2.0]注意dependencies字段里写的是我依赖的另一位作者发布的mylogger库。这一步就是 uPyPi 管依赖的关键别人安装我的包时会自动先装mylogger。manifest.py内容package(mylight_i2c)如果是单文件的模块可以写成module(mylight_i2c.py)这个文件的主要作用是告诉构建工具哪些文件才是要发出去的避免把测试文件或本地配置也打进去。4.3 本地打包与测试验证在发布之前一定要先本地构建和测试。执行upypi build如果没有任何报错会在当前目录生成一个.upypi/文件夹里面放着打包产物。然后可以把它安装到本地模拟环境测试或者直接安装到一块测试板上upypi install . --device /dev/ttyUSB1注意这里用的是.当前目录意思是安装本地的这个包而不是从源安装。如果安装到开发板后导入正常、功能正确那么打包验证就通过了。我强烈建议你在至少两块不同型号的开发板比如一块 ESP32 和一块 RP2040上跑一遍基本功能因为 MicroPython 在不同平台上确实有细微差异比如 I2C 引脚的初始化和软硬件接口兼容性只有真正跑过才能发现。4.4 注册账号并发布到 uPyPi 源发布前需要注册一个 uPyPi 账户这一步通常在官网完成。然后在本机保存凭据upypi login按提示输入用户名和密码登录成功后发布命令只需要一行upypi publish发布后任何人都可以通过upypi install mylight_i2c来安装你的包。你可能会问发布之后如果代码更新了怎么办改好版本号比如升到1.0.1再执行一次upypi publish就可以了。旧版本会保留其他人装的时候默认拿最新版但同时也可以指定安装1.0.0来装历史版本。4.5 发布时容易忽略的细节发布包虽然门槛不高但有几个细节非常影响别人使用体验包名全局唯一发布前先搜索一下你的包名是否已经存在。版本号要符合规范我通常用x.y.z如果只是修 bug升第三位加了兼容功能升第二位破坏性改动升第一位。在pyproject.toml中明确兼容的固件版本和开发板类型这会帮助 uPyPi 在安装时做筛选极大减少别人装错平台的可能性。README 里写清楚接线图和最小示例这是驱动类库最容易被忽略但又最重要的部分。很多人写驱动不写文档别人根本不知道怎么接线、怎么调用自然也没人用。5. 常见问题与排查技巧实录5.1 安装时报错 “Package not found”这个大概率是包名写错了或者源里确实没有。先搜索一下正确拼写比如你搜ssd1306得到的结果可能是ssd1306-driver那安装命令就应该是upypi install ssd1306-driver。再一个原因是你本地 uPyPi 的源索引没有更新尝试upypi update-index这个命令会拉取最新的包列表之后再安装。5.2 安装成功了但 import 报错 ModuleNotFoundError听上去不可思议但常见原因是安装到的目录和设备实际sys.path不一致。如果你用了--target ./lib把包下载到电脑但没有传进设备或者传入的目录不是设备的/libMicroPython 就不会认识它。解决方法是先确认upypi list --with-path会显示当前设备上已配置的所有模块搜索路径。如果目标目录不在列表里需要在代码开头加import sys sys.path.append(/lib)或者干脆把包直接放到/lib下。另外还有一个隐蔽的可能固件版本太低导致某些语法不支持安装时 uPyPi 通常不会给你检查。遇到这种情况就升级固件最好用你安装包时提示的兼容版本一致的固件。5.3 传输过程中断线或超时安装大一点的包时串口传输容易超时。特别是stm32系列板子如果用的是 USB 转串口模拟速率不够稳定。我会先检查配置里的波特率如果没有特殊需要就保持默认115200然后关闭任何其他占用串口的工具比如终端监视器、串口助手它们会抢走设备连接。如果还是超时把包先下载到本地再手动传输这样可以把问题拆分开排查是网络下载慢还是串口传输出错。5.4 发布时提示 “Authentication failed”检查登录信息之外最容易被忽略的是凭据没有关联到本机重新执行upypi login然后确保pyproject.toml里的name字段和你注册时填写的项目名完全一致。另外有些源要求你必须先在网页端创建一个同名空项目发布才能成功。这一步因源而异我在第一次发布时也卡了很久后来通过官方文档才发现要先建项目体并不是直接命令行一行就能搞定。建议发布前先查看所选源的文档免得卡到最后一步。6. 能想到的一些实用建议和心里话用了 uPyPi 大半年最大的感受是真省心。以前我写一个复杂项目设备端和电脑端都乱成一团各类驱动文件散落各地想换个板子测试就要重新传一遍。现在所有依赖统一写在requirements.txt里刷完固件直接一句命令把所有包装回来效率提升非常明显。最让我意外的是发布功能带来的好处——我把自己写的几个小驱动打包发布后有几个其他开发者直接报了 issue 告诉我兼容性问题这比自己闷头测要有用得多。如果你只打算试一个功能我建议先从upypi search和upypi install开始把日常用的驱动都换到 uPyPi 管理熟悉流程后自然会理解整个生态。等你写了值得复用的代码也强烈建议上传到源里让更多人一起测试、完善。这不只帮助别人也会逼着你的代码更规范、文档更清晰某种意义上反而是提升个人代码质量最快的方式。最后分享一个小技巧在pyproject.toml里添加homepage字段指向你项目的开源仓库能大幅提升别人对包的信任感我的包下载量涨得比之前快多了。
阅读完成 · 觉得有帮助？
