教程:VENTUNO Q/刷写 Ubuntu 镜像
概述
在本教程中，你将学习如何使用 Arduino Flasher CLI 工具，将全新的 Ubuntu® 操作系统镜像刷写到你的 Arduino® VENTUNO™ Q 上。
刷写新的 Linux® 镜像可用于安装干净的操作系统、执行系统升级，或在文件系统损坏时恢复开发板。
硬件与软件要求
硬件要求
- Arduino® VENTUNO™ Q（1 块）
- Arduino USB-C® Power Supply (65 W)，含 DC 圆口适配器（或外部 7–24 V、≥ 3 A 电源）
- Arduino USB Type-C® Cable 2in1（或标准 USB-C 数据线）
- 跳线帽或母对母跳线（1 根）
软件要求
- Arduino Flasher CLI（版本 0.5.4 或更高）
- （可选） 本地已下载的 Ubuntu 镜像压缩包（
.tar.zst或.tar.xz）
步骤 1：将开发板设为引导加载程序（EDL）模式
要刷写开发板，Qualcomm® Dragonwing™ IQ8（QCS8275）处理器必须进入 Emergency Download Mode（EDL）。
警告：
重要： 请先桥接引导加载程序引脚并为开发板供电，然后再将 USB-C 线缆连接到电脑。否则刷写工具可能无法检测到设备。
- 断开 USB-C 线缆，并从 VENTUNO Q 拔掉电源。
- 找到开发板上的 10 针（2×5）JCTL（MPU Remote Debug）排针。
- 使用跳线帽或母对母跳线桥接 Pin 1（
GND） 与 Pin 2（FORCED_USB_BOOT_N）。
- 将外部电源连接到圆口或螺丝端子。
- 在开发板已供电且跳线就位的情况下，将 USB-C 数据线连接到电脑。
说明：
提示： 开发板在 EDL 模式下已供电并连接到电脑后，可以安全地取下跳线。开发板将保持在引导加载程序模式，直到重新上电。
步骤 2：下载并准备 Arduino Flasher CLI
从 Arduino Software 页面或 GitHub Releases 页面 下载最新的 Arduino Flasher CLI 发行版。选择与你的操作系统和架构对应的软件包：
| 操作系统 | 软件包 |
|---|---|
| macOS | Apple Silicon（darwin-arm64）或 Intel（darwin-amd64）
|
| Linux | 64 位 x86（linux-amd64）或 ARM64（linux-arm64）
|
| Windows | 64 位（windows-amd64.zip）
|
解压归档文件，然后打开终端或命令提示符，进入解压后的目录。
说明：
macOS 提示： 使用 Archive Utility 以保留可执行权限。
说明：
Linux 用户： 为厂商 ID 为
05c6的 Qualcomm 设备配置udev规则，并将你的用户添加到dialout组。请按照 Linux 设置指南 操作。
步骤 3：刷写 Ubuntu 镜像
Arduino Flasher CLI 0.5.4 新增了 ventunoq 开发板标识符，用于下载并刷写最新的官方 Ubuntu 镜像。
警告：
刷写 VENTUNO Q 会擦除现有系统和用户数据。继续操作前请备份重要文件。
自动下载并刷写最新镜像
根据你的操作系统运行相应命令：
macOS / Linux：
./arduino-flasher-cli flash ventunoq
Windows：
.\arduino-flasher-cli.exe flash ventunoq
出现确认提示时，输入 y 并按 Enter。该工具会查找最新的官方 VENTUNO Q Ubuntu 镜像，下载、校验校验和，然后刷写到开发板。
提示： 使用 list 列出可用版本，然后使用 --version 刷写指定版本。将 VERSION 替换为 list 命令显示的某个版本。
./arduino-flasher-cli list ventunoq # this lists the available image versions
./arduino-flasher-cli flash ventunoq --version VERSION # this flashes the specified version
说明：
在 Windows 上，将
./arduino-flasher-cli替换为.\arduino-flasher-cli.exe。
步骤 4：完成、重启并验证
当 CLI 显示消息 The board has been successfully flashed 后：
- 断开 USB-C 线缆，并从 VENTUNO Q 拔掉电源。
- 如果尚未取下，请从 JCTL Pin 1 和 Pin 2 上移除跳线。
- 将电源重新连接到圆口或螺丝端子。然后按需重新连接 USB-C 数据线、显示器或网线。
- 让开发板完成首次进入 Ubuntu 的启动过程。
验证已刷写的镜像
- 在开发板上打开终端，或从电脑通过 ADB 连接。有关 ADB 设置说明，请参阅 VENTUNO Q 用户手册。
adb shell
- 检查系统构建信息：
cat /etc/buildinfo
- 确认构建信息与你刷写的镜像版本一致。
故障排除
Waiting for EDL Device
如果工具停在 Waiting for EDL device 消息：
- 跳线接触不良： 确保跳线牢固地将 JCTL 排针上的 Pin 1（
GND）与 Pin 2（FORCED_USB_BOOT_N）短接。 - 上电顺序： 先通过圆口或螺丝端子连接外部电源，再将 USB-C 数据线连接到电脑。
- Linux 权限： 为厂商 ID
05c6配置udev规则，并将你的用户添加到dialout组。参见 Linux 设置指南。
通信错误 / USB 断开
- 避免使用无供电的 USB 集线器或键盘透传端口。将 USB-C 线缆直接连接到电脑的原生 USB 端口。
- 使用高质量的 USB-C 数据线。
临时磁盘空间不足
下载并解压镜像可能需要最多 12 GiB 的可用空间。使用 --temp-dir 选择容量足够的位置：
macOS / Linux：
./arduino-flasher-cli flash ventunoq --temp-dir /path/to/large/disk
Windows：
.\arduino-flasher-cli.exe flash ventunoq --temp-dir D:\path\to\large\disk
原文：https://docs.arduino.cc/tutorials/ventuno-q/flash-image/ 本页为 Arduino 官方教程的中文翻译，供内部查阅。命令与代码保持原文。
