uPyPi 平台下载和上传驱动包使用说明
一、快速安装驱动包
如果你是第一次接触 MicroPython 和 uPyPi 平台，不用担心！这份说明会从最基础的准备工作 开始，一步步教你如何在树莓派 Pico2（无网络）和 Pico2W（有网络）上，从 uPyPi 平台下载并使用驱动包（以 bmp280_driver 气压温度传感器驱动为例）。同时也会简要介绍如何上传驱动包（方便有分享需求的使用者）。
1.1 零基础前置准备
在使用 uPyPi 之前，需要准备好硬件、软件，并完成基础设置，缺一不可。
1.1.1 硬件准备
| 硬件名称 | 用途 | 备注 |
|---|---|---|
| 任何支持mpy固件的单片机（如树莓派 Pico2 / Pico2W） | 运行 MicroPython 代码的核心硬件 | Pico2 无 WiFi 功能（需本地安装）；Pico2W 带 WiFi 功能（可远程安装） |
| USB-C 数据线 | 连接开发板与电脑，传输代码 / 供电 | 需支持数据传输（充电线不可用） |
| BMP280 气压温度传感器模块（可选）或其他常见电子模块 | 测试驱动包的硬件 | 用于验证安装的 bmp280_driver 是否可用 |
| 杜邦线（若干） | 连接开发板与传感器 | 需准备公对公 / 公对母杜邦线，根据接线需求选择 |
1.1.2 软件准备
- 安装 Thonny 编辑器：
Thonny 是最适合零基础的 MicroPython 开发工具，支持代码编写、开发板连接、文件管理。
- 下载地址：https://thonny.org/
- 安装方式：按系统提示下一步安装即可（默认设置无需修改）。
- 安装 mpremote 工具（电脑端）
这是电脑与 MicroPython 开发板通信的工具，用于本地安装驱动包 （不支持联网功能的单片机必备）。
打开电脑的「命令提示符（CMD）」或「PowerShell」，输入以下命令并回车：
bash
pip install mpremote提示「Successfully installed mpremote」即安装成功。
1.2 开发板基础设置（烧录 MicroPython 固件）
你需要首先给你的 MCU 烧录一个 mpy 固件，这里我们以树莓派 Pico2 / Pico2W 为例，出厂无 MicroPython 固件，需先烧录才能使用。
-
按住开发板上的 BOOTSEL 按键，同时用 USB-C 线将开发板连接到电脑，松开按键。
-
电脑会识别出一个名为「RPI-RP2」的 U 盘。
-
打开浏览器，下载对应固件：
- 树莓派 Pico2 固件：https://micropython.org/download/RPI_PICO2/
- 树莓派 Pico2W 固件：https://micropython.org/download/RPI_PICO2W/
-
将下载的
.uf2固件文件复制粘贴到「RPI-RP2」U 盘中。 -
复制完成后，开发板会自动重启，U 盘消失，此时固件烧录完成。
1.3 打开 uPyPi 平台搜索包和复制命令
uPyPi 平台是 MicroPython 驱动包的 "集散地"，我们可以在这里搜索、查看、下载需要的驱动包。
打开浏览器，访问 uPyPi 官网：https://upypi.net/
在页面顶部的搜索框 中输入 bmp280，点击右侧「搜索」按钮：
搜索结果会显示匹配的驱动包（如 bmp280_driver 1.0.0），点击即可：
进入驱动包详情页，可在页面左侧切换驱动包版本：
页面左侧会显示核心安装命令（本地安装 / 远程安装）：
3.4 下载并安装驱动包
根据开发板是否有网络，分为本地安装（Pico2） 和远程安装（Pico2W） 两种方式。
3.4.1 本地安装（适用于无 WiFi 的开发板）
通过 USB 连接电脑，用 mpremote 工具将 uPyPi 上的驱动包安装到开发板。
输入执行指令：
bash
mpremote mip install https://upypi.net/pkgs/bmp280_driver/1.0.0等待命令执行，终端出现以下内容，即安装成功：
我们也可以使用下面指令查看板内文件确认有没有下载成功：
bash
# 查看根文件目录
mpremote fs ls
# 查看'lib/'文件夹下目录
mpremote fs ls 'lib/'3.4.2 远程安装（适用于有 WiFi 的开发板）
先让开发板连接 WiFi，再直接在开发板的 REPL 终端中安装驱动包。
- 先用 USB 线将树莓派 Pico2W 连接到电脑，Thonny 自动识别后，点击底部「Shell」面板。
- 若 Shell 面板显示
>>>，表示已进入 MicroPython 的 REPL 交互模式；若显示其他内容，按「Ctrl + D」重启开发板，即可看到>>>。
在 Shell 面板的 >>> 后，逐行输入以下代码（替换为你的 WiFi 名称和密码），每输入一行按回车：
python
import network
wlan = network.WLAN(network.STA_IF)
wlan.active(True)
wlan.connect("你的WiFi名称", "你的WiFi密码")
# 等待连接成功
import time
while not wlan.isconnected():
print("Connecting to WIFI...")
time.sleep(1)
print("WIFI Connected! IP Address:", wlan.ifconfig()[0])若显示「WIFI Connected! IP Address: 192.168.xx.xx」，表示 WiFi 连接成功：
在 Shell 面板的 >>> 后，输入以下完整安装命令：
bash
import mip
mip.install("https://upypi.net/pkgs/bmp280_driver/1.0.0")执行完成后，显示如下即安装成功：
点击左侧「文件」面板中的「Raspberry Pi Pico2」，展开「lib」文件夹，若能看到 bmp280_float.py 文件，说明安装成功：
3.5 使用安装好的驱动包
安装完成后，我们用 BMP280 传感器测试驱动包是否能正常工作，这部分看下面的云文档就可以了：
https://freakstudio.cn/node/019ba20b-b702-7118-a3b3-c3fb7218fd61
四、上传驱动包（进阶：给想分享驱动的使用者）
如果你开发了自己的 MicroPython 驱动，想分享到 uPyPi 让其他人使用，可按以下步骤操作（以 bmp280_driver 为例）。
4.1 准备符合规范的驱动包文件
驱动包的文件目录必须遵循以下结构（参考图片 6-9），缺一不可：
bash
你的驱动包文件夹（如 bmp280_driver）/
├── code/ # 存放核心驱动代码的文件夹
│ ├── 驱动核心文件.py（如 bmp280_float.py）
│ └── 测试示例文件.py（如 main.py，可选）
├── package.json # 驱动包的"身份证"（必须文件）
├── README.md # 驱动使用说明（建议文件）
└── LICENSE # 开源协议文件（建议文件）package.json 是驱动包的核心配置，必须包含以下必填字段 ，可添加可选字段丰富信息：
json
{
"name": "bmp280_driver", // 包名，小写，用下划线分隔
"version": "1.0.0", // 版本号，遵循 主版本.次版本.修订号 规则
"urls": [ // 文件映射：["设备端文件名", "本地文件路径"]
["bmp280_float.py", "code/bmp280_float.py"]
],
"description": "控制 BMP280 气压温度传感器的 MicroPython 驱动", // 可选：功能描述
"author": "你的名字", // 可选：作者
"license": "MIT", // 可选：开源协议
"keywords": ["micropython", "bmp280", "传感器"] // 可选：搜索关键词
}4.2 上传驱动包到 uPyPi
确保你的项目根目录下包含以下文件（无嵌套文件夹，直接放在根目录）：
code/：驱动代码文件夹LICENSE：许可证文件package.json：包配置文件（必须包含 name 和 version 字段）README.md：包说明文档
⚠️ 关键要求：ZIP 包内不能嵌套额外文件夹，所有文件直接在压缩包根目录下（参考示例结构：
BH1750_driver.zip→ 直接包含code/、package.json等）。
接下来将库文件打包为 ZIP 压缩包：
-
选中项目根目录下的所有文件（
code/、LICENSE、package.json、README.md）。 -
右键 → 选择「7-Zip」→「添加到压缩包」（或直接选择「添加到 [包名].zip」）。
-
在压缩设置中：
- 压缩格式选择
zip - 文件名建议与包名一致（如
BH1750_driver.zip） - 确认路径模式为「相对路径」，避免生成嵌套目录
- 压缩格式选择
-
生成 ZIP 包后，检查内部结构：打开 ZIP 确认所有文件直接在根目录，无额外文件夹嵌套。
访问 uPyPi 官网，点击右上角「GitHub 登录」，用你的 GitHub 账号授权登录：
登录后，点击顶部「我的面板」，再点击「点击这里上传第一个包」：
进入上传页面，点击「选择文件」，选中刚才生成的 ZIP 包：
确认文件夹包含 package.json 后，点击「上传包」按钮，等待上传完成：
上传成功后，即可在 uPyPi 搜索到你的驱动包，其他使用者可直接安装。
4.3 常见问题-避免版本冲突与包名重复
在上传驱动包到 uPyPi 时，你可能会遇到像图片中这样的提示："包 bmp280_driver 版本 1.0.0 已存在"。这是因为 uPyPi 平台对包的管理有严格规则，确保每个包的版本和名称都是唯一的，方便用户准确安装和使用。
uPyPi 不允许同一个包名上传完全相同的版本号。这就像手机 App 的更新日志：
- 每次修复小 bug、优化代码，都需要更新版本号（比如从
1.0.0→1.0.1）。 - 如果版本号不变，平台会认为你在重复上传同一个包，从而拒绝操作。
版本号遵循 "主版本。次版本。修订号" 的规则（语义化版本），每次上传都要递增：
- 修订号（第三位） ：修复小 bug、优化代码细节，比如
1.0.0→1.0.1。 - 次版本（第二位） ：新增功能、兼容新硬件，比如
1.0.1→1.1.0。 - 主版本（第一位） ：大改版、不兼容旧代码，比如
1.1.0→2.0.0。
如果你的包名太宽泛（比如 sensor_driver），很容易和其他开发者的包重名，导致用户安装时混淆。建议遵循以下规则：
- 包名要具体 ：包含硬件型号或功能，比如
bmp280_driver（明确是 BMP280 传感器驱动），而不是sensor_driver。 - 格式要规范 ：全部小写，用下划线
_分隔单词，避免空格和特殊字符。 - 提前搜索验证：在 uPyPi 首页的搜索框中输入你想使用的包名，确认没有重名后再使用。
遇到 "版本已存在" 提示后的解决步骤：
- 打开驱动包的
package.json文件，修改version字段为新的版本号（比如1.0.1）。 - 保存文件，确保文件名和内容没有变化。
- 回到 uPyPi 上传页面，重新选择驱动包文件夹，点击「上传包」。
- 若提示 "上传成功"，则版本更新完成；若仍提示错误，检查包名是否重名，或版本号是否确实递增。