K230 命令行开发指南

在立创·庐山派 CanMV-K230(基于嘉楠勘智双核 64 位 RISC-V 芯片)开发过程中,虽然官方提供了图形化 CanMV IDE,但在进行自动化批量部署、无桌面纯终端环境、持续集成(CI/CD)或大文件传输时,基于纯命令行的轻量工具链往往更加高效且不可替代。

很多开发者以为命令行开发就是“开串口敲敲命令”,实际上现代 MicroPython 生态已经演进出非常成熟的工具矩阵。本文系统整理跨平台(Windows / macOS / Linux)开发 K230 的全套实用技能:

  • 全平台板载 USB 虚拟串口快速识别、端口独占与 Linux 权限排错;
  • 现代 MicroPython 官方全能神器 mpremote 的全套实战技巧(自动探测、REPL 交互、内存直接运行、文件全量运维、本地目录挂载与包管理);
  • 经典工具 ampy 的免参数批处理与 CI 流水线集成;
  • 串口底层监视器(screen / miniterm)与“设备忙(Device Busy)”经典死锁急救;
  • ⚠️ K230 特有避坑点:USB 虚拟 U 盘与串口并发写入导致 SD 卡文件系统损坏的底层机理与解法。

💡 K230 系列开发联动:

  • 📝 代码编辑与智能补全篇:VSCode 配置 K230 开发环境(告别红色波浪线报错,激活 Pylance 毫秒级符号补全与跨平台存根部署)
  • 💻 终端运维与文件传输篇(本文):K230 命令行开发指南(掌握 mpremote、ampy 与原生串口纯命令行流)

一、环境准备与核心工具链安装

推荐在宿主机创建独立的 Python 虚拟环境,统一安装嵌入式 MicroPython 上位机工具链:

1
2
3
4
5
6
7
8
9
# 1. 创建并激活独立的虚拟环境
mkdir -p ~/k230_workspace && cd ~/k230_workspace
python3 -m venv venv
source venv/bin/activate # Windows 用户执行: venv\Scripts\activate

# 2. 一键安装核心通信工具
pip install mpremote # MicroPython 官方现代首选工具(全功能覆盖)
pip install adafruit-ampy # Adafruit 经典轻量级文件管理与批处理工具
pip install pyserial # 底层串口通信标准库(自带 miniterm 调试器)

核心工具分工全景图

flowchart TD
    A["上位机终端
(Win / Mac / Linux)"] -->|"USB CDC 虚拟串口"| B["K230 开发板 (CanMV)"] A -.->|"现代首选: 自动探测 / REPL / 虚拟挂载"| C["mpremote"] A -.->|"经典批处理: 自动化文件上传与备份"| D["ampy"] A -.->|"底层监视: 日志监控与内核会话"| E["miniterm / screen / PuTTY"] C --> B D --> B E --> B

二、识别 K230 板载串口设备与权限排错

用 Type-C 数据线连接 K230 开发板与电脑。板端固件启动后,芯片的 USB 控制器会向主机枚举出一个 USB CDC ACM 虚拟串口(以及一个虚拟 U 盘设备)。

1. Windows 系统

按 Win + X 打开“设备管理器”,展开 端口 (COM 和 LPT):

  • 设备名称通常显示为 USB 串行设备 (COMx) 或带有 CanMV / K230 标识;
  • 亦可在 PowerShell 终端中一条命令直接检索:
    1
    Get-CimInstance Win32_SerialPort | Select-Object DeviceID, Description

2. macOS 系统

在 macOS 下,CanMV 设备通常挂载在 /dev/ 下为 cu.usbmodem* 设备节点(推荐优先使用 cu.* 而非 tty.*,避免由于 DCD 握手信号导致打开串口时阻塞):

1
2
ls /dev/cu.usbmodem*
# 输出示例:/dev/cu.usbmodem0010000001

3. Linux 系统

在 Linux 下,设备通常识别为 ttyACM*:

1
2
ls /dev/ttyACM* /dev/ttyUSB*
# 输出示例:/dev/ttyACM0

📌 Linux 经典权限排错(Permission Denied):
默认非 root 用户没有读写 /dev/ttyACM* 串口节点的权限。执行以下命令将当前用户加入 dialout 组,然后注销重新登录终端即可免 sudo 正常通信:

1
sudo usermod -aG dialout $USER

三、现代 MicroPython 首选全能武器:mpremote

很多开发者只知道用 mpremote 安装 mip 包,实际上它是 MicroPython 官方团队主力维护的现代瑞士军刀,完全可以同时替代传统的 screen 和 ampy,而且最大的优势是:默认开启自动串口嗅探(Auto-detect),绝大部分场景下你根本不需要输入串口路径!

1. 免输串口直入交互式 REPL(替代 screen)

连接板卡后,终端直接敲入 mpremote 回车:

1
mpremote

终端瞬间自动连接板端 MicroPython REPL:

1
2
3
4
5
Connected to MicroPython at /dev/cu.usbmodem0010000001
Use Ctrl-] or Ctrl-x to exit this shell
>>> import os
>>> os.uname()
(sysname='canmv', nodename='canmv', release='1.2.2', version='v1.2.2-0-gf6ca68a0ed on 2024-05-20', machine='k230')

💡 关键快捷键技巧:

  • 优雅退出:敲 Ctrl + ](或者 Ctrl + X),瞬间断开连接并释放串口资源;
  • 软复位(Soft Reset):敲 Ctrl + D,软重启板端 MicroPython 虚拟机并重新运行 boot.py;
  • 中断死循环:敲 Ctrl + C,强行跳出当前运行的死循环或推流进程;
  • 多设备显式指定:如果电脑同时连接了多个串口设备,可通过 connect 显式指定:
    1
    2
    3
    mpremote connect /dev/cu.usbmodem0010000001 repl
    # Windows 下:
    mpremote connect COM3 repl

2. 单行代码免交互执行(版本嗅探与状态查询)

在前篇 VSCode 配置 K230 开发环境 中,我们利用 mpremote exec 秒级提取板载固件 Commit,就是利用了该特性:

1
2
# 执行远端代码并直接回显输出(无需进入交互 REPL,脚本友好)
mpremote exec "import os; print(os.uname().version)"

3. 本地脚本免上传、直接在板端 RAM 中运行

如果你写了一个 test_camera.py,不想频繁烧写 SD 卡造成寿命磨损,只想在开发板内存中临时跑一次看结果:

1
mpremote run test_camera.py

mpremote 会通过 Raw REPL 模式将该脚本发送到板载 RAM 中立即执行,终端实时同步打印 print() 日志与错误堆栈。

4. 强大的文件系统管理(mpremote fs)

mpremote 自带一套文件系统指令,板端路径统一使用 : 前缀表示:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1. 浏览板端根目录与 SD 卡文件列表
mpremote fs ls
mpremote fs ls /sdcard

# 2. 将本地文件上传到开发板(覆盖开机自启入口)
mpremote fs cp main.py :main.py

# 3. 将本地神经网络模型推送到板载 SD 卡
mpremote fs cp yolov8n.kmodel :/sdcard/models/yolov8n.kmodel

# 4. 从开发板下载文件到电脑本地备份
mpremote fs cp :main.py backup_main.py

# 5. 直接查看板端文件内容
mpremote fs cat :main.py

# 6. 删除板端冗余文件
mpremote fs rm :/sdcard/temp.txt

5. 进阶黑科技:本地开发目录实时挂载(mpremote mount)

这是微控制器开发中最强悍的工作流之一!无需反复执行复制指令,直接把电脑上的本地文件夹“虚拟挂载”进 K230 文件系统中:

1
2
# 将当前电脑工作目录挂载为开发板的 /remote 路径并进入 REPL
mpremote mount .

在板端执行:

1
2
3
>>> import os
>>> os.listdir('/remote') # 直接读取你电脑上的当前代码目录!
['main.py', 'sensor_test.py', 'model.kmodel']

你在电脑 VSCode 中保存修改,板端敲 import 即可立即加载最新代码,开发效率翻倍提升!

⚠️ 性能边界提醒:
mount 挂载基于串口 Raw REPL 分块传输,适合 Python 源代码脚本与小型 JSON 配置文件的实时调试;切勿试图通过挂载路径直接读取 20MB+ 的 .kmodel 权重模型,否则受串口物理带宽限制,模型加载耗时会极其漫长。大文件请务必使用 mpremote fs cp 预先拷入板载物理 SD 卡。

6. 第三方拓展包管理(mip)

MicroPython 官方提供了类 pip 的包管理系统 mip:

1
2
# 将第三方库安装到板载 SD 卡的 libs 目录
mpremote mip --target="/sdcard/libs" install aioespnow

四、经典工具:ampy 批量与自动化脚本流

尽管 mpremote 极为强大,但老牌工具 ampy(Adafruit MicroPython Tool)语法简洁固定,非常适合编写自动化批处理脚本(如 CI/CD 流水线或产线固件批量烧录)。

1. 配置免输入串口配置文件 .ampy

在工程根目录下放置 .ampy 配置文件,之后执行 ampy 时无需每次输入 -p 参数:

1
2
3
AMPY_PORT=/dev/cu.usbmodem0010000001
AMPY_BAUD=115200
AMPY_DELAY=0.5

2. 高频命令示例

1
2
3
4
5
6
7
8
9
10
11
# 1. 上传本地主程序为开机自启
ampy put main.py

# 2. 上传模型到 SD 卡
ampy put yolov8n.kmodel /sdcard/yolov8n.kmodel

# 3. 拉取板端最新代码到本地
ampy get main.py > backup.py

# 4. 查看板端目录
ampy ls /sdcard

五、串口终端调试与“设备占用 (Busy)”排错

如果你需要长时间监控串口日志或调试 C 级内核输出,原生终端工具是底层排查的必备手段。

1. 终端调试工具选择

  • macOS / Linux:使用系统自带的 screen;
  • 全平台标准库自带:无需安装第三方 GUI,Python 自带的 miniterm 最轻量干净:
    1
    2
    3
    python -m serial.tools.miniterm /dev/cu.usbmodem0010000001 115200
    # Windows 示例:
    python -m serial.tools.miniterm COM3 115200
    (退出快捷键:Ctrl + ])

2. 退出 screen 的正确姿势

若使用 screen:

1
screen /dev/cu.usbmodem0010000001 115200

⚠️ 千万不要直接关闭终端标签页! 否则 screen 会作为孤儿守护进程在后台持续独占串口,导致之后 mpremote 或 ampy 报错 Device or resource busy。

  • 安全退出快捷键:按 Ctrl + A,松开后敲 K,终端提示 Really kill this window [y/n],输入 y 确认退出并注销会话。

3. 串口被锁死排错指南(Device Busy)

如果在执行任何命令时遇到:

1
serial.serialutil.SerialException: [Errno 16] could not open port: [Errno 16] Resource busy

Linux / macOS 排查与强制释放:

1
2
3
4
5
6
7
8
# 1. 查找占用该串口的进程 PID
lsof | grep usbmodem # macOS
lsof /dev/ttyACM0 # Linux

# 2. 强行终止卡在后台的 screen 进程
killall screen
# 或根据查到的 PID 强制结束
kill -9 <PID>

Windows 排查:

  • 确认后台未开启其他串口监视软件(如串口调试助手、CanMV IDE、Arduino IDE、PuTTY 等);
  • 在任务管理器中结束残留的 Python 进程,或重新拔插一次 USB 数据线。

六、💡 核心避坑:USB 虚拟 U 盘与串口并发写入的文件系统冲突

这是一个 90% 的 K230 新手都会踩中的严重暗坑:

K230 CanMV 固件默认开启了 USB Mass Storage(虚拟 U 盘) 功能,当开发板连上电脑后,主机会自动挂载板载 TF/SD 卡的分区为一个移动磁盘。

致命隐患:FAT32 双端并发写入损坏

FAT32 文件系统设计之初就不支持双机并发写入!

  • 宿主机操作系统(Windows 资源管理器 / macOS Finder)会对 U 盘进行深层元数据缓存与延迟写回;
  • 如果你一边在电脑上往该 U 盘里拖拽或修改文件,另一边又在终端通过 ampy、mpremote 或板端 Python 脚本调用 open(..., 'w') 写入 SD 卡: 两端的 FAT 分区表与分配簇链表将产生严重冲突,瞬间导致 SD 卡文件系统损坏(FAT Corrupted)、文件变为 0 字节、甚至板端内核 Panic 挂死!

正确的运维避坑原则

  1. 优先通过串口工具维护:日常写代码、传模型,统一使用 mpremote fs cp 或 ampy put 走串口通道操作;
  2. 需要批量拷贝海量文件时:
    • 先通过 mpremote 将板端执行暂停;
    • 在电脑操作系统中正常向 U 盘写入数据;
    • 写入完毕后,务必在电脑上右键选择“弹出 / 推出磁盘 (Eject)”,等待系统将缓存彻底刷入物理介质,再使用串口重启运行代码。

七、常用高频命令速查对比表

开发操作需求mpremote 命令(推荐首选)ampy 命令(备用)特性差异与建议
交互式终端mpremote不支持自动探测端口,Ctrl+] 安全退出
开机自启部署mpremote fs cp main.py :main.pyampy put main.py均可实现,mpremote 免配串口
内存免烧录运行mpremote run test.pyampy run test.py临时验证算法逻辑,保护 Flash
固件版本嗅探mpremote exec "import os; print(os.uname().version)"ampy run - <<< "..."秒级返回 Commit SHA,无交互挂起
本地目录挂载mpremote mount .不支持本地修改代码,板端免传即刻加载
第三方库安装mpremote mip install <pkg>不支持自动化拉取 MicroPython 官方生态库

八、相关参考链接与文档

1. 官方平台与最新文档中心

2. 本站系列实战联动


K230 命令行开发指南
https://bubao.github.io/posts/228fa1ed.html
作者
一念
发布于
2025年1月9日
许可协议