波仔
🍓 第八章 当树莓派遇到 Arduino 开发板
📄 一句话概括

在树莓派上装 Arduino 开发环境有三条路（图形界面的 IDE／命令行的 CLI／仓库里的旧版），选哪条只取决于一件事——你这台树莓派有没有桌面。而这一步真正的难点不是"装"，是让普通用户有权碰串口。

📝 本节和前面几节的关系

8-1 认清了两块板子的分工，但板子还只是"插在树莓派上的一个零件"。本节把它变成能写程序、能上传代码的开发对象。 本节用到的两个老熟人：apt 装包（4-5 学的）和把用户加进设备组（7-2 为 GPIO 加 gpio 组时学的，本节要加 dialout 组——同一个套路）。 装好之后，8-3 写第一个程序、8-4 用 Python 指挥它、8-5 打通串口通信——全都靠本节这套环境。

一、先想清楚：装在哪台机器上

很多教程默认你在 Windows 上装 Arduino IDE。但这门课的场景不一样，先把三个选项摆清楚：

装在哪 好处 坏处
树莓派上 一台机器全搞定，不用来回插拔；能和树莓派上的 Python、摄像头、网络直接联动（这才是本章的重点） 编译比 Windows 慢一些
Windows 上 快、界面流畅 板子得插在 Windows 上；树莓派和 Arduino 的联动实验做不了
两边都装 最优解：日常用 Windows 写，联动实验在树莓派上做 占两份空间

本课以【装在树莓派上】为主线——因为这一章要学的是"两块板子怎么配合"，它们必须插在一起。

二、三条安装路：按你的情况选一条

你的情况 选哪条 为什么
有桌面（接了显示器，或用 VNC 看画面） 路线 A：Arduino IDE 2.x 有图形界面，跟书本、视频教程的截图对得上
SSH 无头（本课的常规场景） 路线 B：arduino-cli 纯命令行、不占内存、更适合无头
想一条命令完事、不在意版本旧 路线 C：apt install arduino 装的是 1.8.19（2017 年的界面）
⚠️ 动手之前先确认一件事：系统是 64 位

Arduino IDE 2.x 只提供 64 位版本。如果这台树莓派装的是 32 位系统，装不上。 查法（2-3 学过）：

uname -m

输出 aarch64 ＝ 64 位 ✅；输出 armv7l ＝ 32 位，得重装系统。

💡 三条路可以共存，而且互相帮忙

IDE 和 CLI 共用同一套目录（~/.arduino15 放核心包和库、~/Arduino 放你写的程序）。 所以：先用 CLI 装好核心，之后装 IDE 就不必再下一遍几百 MB 的编译器。 也可以照 3-3 讲的老路——图形界面的「推荐软件（Recommended Software）」里就能勾选 arduino，但那也是 1.8.x 旧版。

三、路线 A：图形界面，装 Arduino IDE 2.x

3.1 为什么不用 apt 装

apt install arduino 装到的是 1.8.19——一整套 2017 年的界面。它还能用，但：

官方给 Linux ARM64 提供的是 AppImage 格式（一个文件，双击就能跑，不用安装）。

3.2 四步装上

# ① 先装一个关键依赖（⚠️ 最容易漏的一步，见下方警告框）
sudo apt update
sudo apt install -y libfuse2

# ② 建个目录，把 AppImage 下进去
mkdir -p ~/Applications && cd ~/Applications
wget https://downloads.arduino.cc/arduino-ide/arduino-ide_2.3.2_Linux_ARM64.AppImage

# ③ 给它执行权限
chmod +x arduino-ide_2.3.2_Linux_ARM64.AppImage

# ④ 运行
./arduino-ide_2.3.2_Linux_ARM64.AppImage

文件名里的版本号会变（写这篇时是 2.3.2）——以官网 downloads 页最新的为准，把下载链接换掉即可。

⚠️ ⚠️ 第一个大坑：`libfuse2`

AppImage 这个格式要靠 FUSE 2 才能挂载自己。 而新版 Raspberry Pi OS 默认装的是 FUSE 3，两个大版本不兼容。 不装 libfuse2 的后果：双击没反应、或者报一句 error while loading shared libraries: libfuse.so.2。 很多人这时候会以为"下载的文件坏了、重新下一遍"——其实只是缺这一个包。

3.3 让它出现在开始菜单里（可选）

不想每次都去终端敲命令，就建个菜单项：

mkdir -p ~/.local/share/applications
nano ~/.local/share/applications/arduino-ide.desktop

写入（把路径换成你自己的）：

[Desktop Entry]
Name=Arduino IDE
Exec=/home/你的用户名/Applications/arduino-ide_2.3.2_Linux_ARM64.AppImage
Icon=arduino
Type=Application
Categories=Development;
Terminal=false

存盘退出（Ctrl+O→回车→Ctrl+X），再去开始菜单里找 Arduino IDE。

💡 更省事的做法

装一个叫 AppImageLauncher 的小工具，之后双击任何 AppImage 它都会问你要不要整合进菜单，自动搞定，不用手写 .desktop。

3.4 如果窗口起不来：一句话补丁

本课桌面是 Wayland ＋ labwc（3-1 讲过）。某些 Electron 程序在 Wayland 下会闪烁或不显示窗口。如果遇到，先试这个：

export GDK_BACKEND=x11
./arduino-ide_2.3.2_Linux_ARM64.AppImage

再不行就重启一次——IDE 首次启动时要下载编译器核心，中途被打断会导致状态异常。

3.5 首次启动为什么那么慢

Arduino IDE 2.x 第一次启动会自动下载 AVR 编译器核心（几百 MB）。树莓派上可能要等好几分钟。

屏幕上会显示进度条，等它跑完就好。 这一次之后，以后的启动都是几秒钟。

四、路线 B：无头模式，用 arduino-cli

如果你的树莓派是通过 SSH 连的（没有图形界面），这是最舒服的一条路。

它是官方出的命令行工具，Arduino IDE 2.x 内部用的就是它，所以功能一点不少。

4.1 安装

curl -fsSL https://raw.githubusercontent.com/arduino/arduino-cli/master/install.sh | sh

它会装到 ~/bin/arduino-cli。让命令随处可用：

echo 'export PATH=$PATH:$HOME/bin' >> ~/.bashrc
source ~/.bashrc
arduino-cli version

看到版本号就算装好。

⚠️ 别用 `apt install arduino-cli`

仓库里的版本通常落后很多，而且 apt 里那个 arduino 包是 1.8.x 的老 IDE，不是 CLI。 官方安装脚本才是正路。

4.2 初始化，并装上 Uno 的"支持包"

Arduino 支持几千种板子，靠的是按需下载"核心包"（core）。AVR 系（Uno／Nano／Mega）的核心叫 arduino:avr。

arduino-cli config init            # 生成配置文件
arduino-cli core update-index      # 更新"有哪些核心可以装"的清单
arduino-cli core install arduino:avr

第三行会下载一两百 MB，树莓派上要等一会儿。

验证：

arduino-cli core list

输出里应该能看到 arduino:avr 和版本号。

4.3 认出插在身边的板子

arduino-cli board list

输出像这样：

Port         Protocol Type              Board Name  FQBN            Core
/dev/ttyACM0 serial   Serial Port (USB) Arduino Uno arduino:avr:uno arduino:avr

这一行信息量很大，请记住三样：

看到的 意思
/dev/ttyACM0 端口名（下面三条命令都要用它）
arduino:avr:uno FQBN，全名就是把"厂商:架构:板子"拼起来
arduino:avr 它属于哪个核心包
💡 FQBN 是什么

Fully Qualified Board Name，直译"完整限定的板子名称"。 arduino:avr:uno ＝ 厂商 arduino ：架构 avr ：板子 uno。 这块板子换成 Nano 就是 arduino:avr:nano，换 ESP32 就是 esp32:esp32:...。 它是"你手上是哪块板子"的机器可读写法，编译时必须告诉编译器。

4.4 编译与上传

# 建一个新程序（会自动生成 .ino 骨架文件）
arduino-cli sketch new ~/Arduino/Hello

# 编译（只编译，不上传）
arduino-cli compile --fqbn arduino:avr:uno ~/Arduino/Hello

# 上传到板子上
arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:uno ~/Arduino/Hello

看到什么算成功：

Sketch uses 928 bytes (2%) of program storage space. Maximum is 32256 bytes.
Global variables use 9 bytes (0%) of dynamic memory, leaving 2039 bytes for local variables. Maximum is 2048 bytes.

读结果：这两行是 Arduino 最典型的两行输出，值得逐字读一遍：

五、⚠️ 本节真正的难点：让普通用户能碰串口

上面两条路线你都装好了，接下来大概率会撞上这个错误：

avrdude: ser_open(): can't open device "/dev/ttyACM0": Permission denied

或者 IDE 里"端口"那一栏是灰的、点不开。

原因：串口设备文件在 Linux 里属于 root 用户和 dialout 组，而你的普通用户不在这个组里。

5.1 正解：把自己的用户加进 dialout 组

sudo usermod -aG dialout $USER

然后必须做一件事：

sudo reboot

或者至少完整注销、重新登录一次。

⚠️ 改完立刻试，是没用的

用户的组成员身份在登录时就确定了，存在系统会话里。 加完组不重登，groups 命令甚至可能已经显示有 dialout，但新开的程序仍然拿不到权限。 这一条每次都会坑到人——"我明明加进组了啊"，多半就是没重启。

验证：

groups

输出里必须出现 dialout，才算生效。

5.2 ⚠️ 不要用 sudo 去跑 Arduino IDE

看到权限错误，很多人的第一反应是 sudo ./arduino-ide...。在 Arduino 这件事上，这是错的：

加组才是正路——一次性解决，之后所有程序（IDE、CLI、Python 脚本、minicom）全都受益。

💡 这个套路你在第七章已经见过一次

7-2 讲过：GPIO 属于 root:gpio，所以要 usermod -aG gpio $USER ＋ 重启。 本节是同一件事，只是设备换成了串口、组名换成了 dialout。 记住这个通用套路：Linux 里凡是"普通用户碰不了某个硬件"，答案几乎都是"把用户加进那个设备的组，然后重登"。

5.3 老教程在这里已经失效了

老资料里这一行通常写成：

sudo usermod -aG dialout pi      # ❌ 老写法

问题在于 pi 这个用户现在不存在了（2-2 讲过：当前系统早就不再有默认的 pi/raspberry 账号）。

一律写 $USER——它会被自动替换成你当前登录的用户名，无论你叫什么名字都对：

sudo usermod -aG dialout $USER  # ✅ 照这个写

六、动手 Demo：装完就地验五件事

环境装完不要急着写代码，先把这五项验完，后面一路都会顺。

验收 1 · 工具本身在不在

arduino-cli version

看到什么算成功：输出类似 arduino-cli Version: 1.x.x Commit: ...

用 IDE 的就把窗口打开。

验收 2 · Uno 的核心包装上了没

arduino-cli core list

看到什么算成功：输出里有一行 arduino:avr。

验收 3 · 板子被认到了没

插上 Arduino（USB 线接到树莓派），然后：

arduino-cli board list

看到什么算成功：出现带 Arduino Uno 与 arduino:avr:uno 的行，并且端口名不是空的。

没出现怎么办：拔掉板子、再跑一次这条命令、对比两次输出。多出来的那个就是你的板子。

验收 4 · 你的用户在不在 dialout 组

groups

看到什么算成功：输出里包含 dialout。

验收 5 · 真的上传一次（最关键的一步）

不写代码，直接上传一个空程序：

arduino-cli upload -p /dev/ttyACM0 --fqbn arduino:avr:uno ~/Arduino/Hello

看到什么算成功：出现 avrdude 的日志、最后没有 error，并且板上 L 灯不再一闪一闪（因为空程序什么都不做）。

读结果：验收 1~4 全是"准备"，只有验收 5 才是真正证明"我写的代码能进到芯片里"。它跑通了，8-3 才有意义。

五项对照表：

没通过的项 常见原因 去哪一节查
验收 5 报 Permission denied 加组没重启 本节五
验收 3 端口是空的 USB 线是充电线／板子没插好 8-1 误区 6
验收 3 端口名是 ttyUSB0（不是 ACM0） 兼容板的 CH340 芯片，正常 8-1 四
验收 2 报找不到 核心没装成功，重跑 core install 本节 4.2
上传卡住不动 串口被别的程序占着（IDE 的串口监视器还开着） 8-5 排障

七、30 秒实验：看看这一套东西都装在哪

du -sh ~/.arduino15 ~/Arduino 2>/dev/null
ls ~/.arduino15
echo "--- 配置文件 ---"
cat ~/.arduino15/arduino-cli.yaml 2>/dev/null | head -20

你会看到类似：

602M    /home/你的用户名/.arduino15
4.0K    /home/你的用户名/Arduino
arduino-cli.yaml
packages
...

读结果：

💡 这件事的实用价值

① 备份/换机器时，搬这两样就是搬整个环境。 ② IDE 和 CLI 共用这两个目录——所以先装 CLI 再装 IDE，不会重复下载 600MB。 ③ 树莓派的 SD 卡容量紧张时，~/.arduino15 是最占地方的那一块（8-2 之前 4-2 学的 du 这时候派上用场）。

八、常见误区

  1. "apt install arduino 就够了" —— 装到的是 1.8.19，2017 年的界面。能用，但你照着新版教程会找不到按钮。要用新版就走 AppImage 或 CLI。

  2. "装完了就能上传" —— 中间还差一步：加 dialout 组并重启。这是本节最容易卡住的地方。

  3. "报权限错就用 sudo 跑 IDE" —— ❌ 别。会把配置文件全变成 root 所有，后面到处报错。正解是加组。

  4. "AppImage 双击没反应＝文件坏了" —— 多半是缺 libfuse2。装上就好，不用重新下载。

  5. "32 位系统也能装 IDE 2.x" —— 不行。IDE 2.x 只有 64 位版本。先 uname -m 确认是 aarch64。

  6. "老教程说 usermod -aG dialout pi" —— 当前系统没有 pi 这个用户了。写 $USER。

  7. "树莓派编译太慢，还是得用 Windows" —— 对 Uno 这种小程序，编译只要几秒到十几秒（点灯程序总共才 900 多字节）。慢的是那种要下几百 MB 工具链的板子（ESP32 之类）。为了方便联动，值得在树莓派上装一套。

  8. "IDE 和 CLI 装两套会冲突" —— 不冲突，它们共用同一套核心包和库目录，而且互相受益（比如可以用 CLI 编译、用 IDE 看串口）。

自测三问（点开对答案） 1. 树莓派上装 Arduino 开发环境有三条路，怎么选？ **参考答案**：看**有没有桌面**。**有桌面**（接显示器或用 VNC）→ 装 **Arduino IDE 2.x 的 ARM64 AppImage**（图形界面，跟教程对得上）；**SSH 无头** → 用 **arduino-cli**（命令行，不占资源）；只想一条命令完事、不在意旧 → `apt install arduino`（**但那是 1.8.19 旧版**）。前提都是**64 位系统**（`uname -m` 得是 `aarch64`）。 2. 装 AppImage 之前必须补哪个包？为什么？ **参考答案**：**`libfuse2`**。因为 AppImage 靠 **FUSE 2** 挂载自己，而新版 Raspberry Pi OS **默认只有 FUSE 3**，两个大版本不兼容。不装的症状是"双击没反应"或报 `libfuse.so.2` 找不到——**不是文件坏了**。 3. 上传时报 `Permission denied`，正确的解决方式是什么？为什么不能用 `sudo` 绕过？ **参考答案**：正解是 **`sudo usermod -aG dialout $USER`，然后必须重启（或完整注销重登）**——因为成员身份在登录时就固定了，不重登不生效；验证用 `groups`。**不能用 `sudo` 跑 IDE**：那会让它生成的配置文件、下载的核心包全归 root 所有，之后用普通用户跑就到处报写权限错误，清理起来很麻烦。

相关笔记