一、先分清"线路"：两条物理路线

两块板子要说话，只有两条路：

路线 1：USB 线（本章一直用的，推荐）

树莓派 USB 口  ──USB 线──  Arduino USB 口

• 树莓派上看到的名字：/dev/ttyACM0（原厂板）或 /dev/ttyUSB0（CH340 兼容板）
• 好处：① 完全不用管电平（USB 协议自己处理，反正是数字信号）② 顺便供电 ③ 插上就能用
• 代价：多占一根线和两个 USB 口

路线 2：GPIO 的 UART 针（省一根线，但三个坑）

树莓派 GPIO14（物理针 8，TXD） ──→ Arduino 的 RX
树莓派 GPIO15（物理针 10，RXD）──→ Arduino 的 TX
树莓派 GND                    ──→ Arduino 的 GND   ← 必须接

注意 TX 接 RX、RX 接 TX，交叉着接（两边都在"说"的线要接到对方"听"的线上）。

sudo raspi-config
# → Interface Options → Serial Port
# → "要不要提供串口登录 shell？"       答 【No】
# → "要不要启用串口硬件？"            答 【Yes】

二、装 pyserial（两种装法，各有适用场合）

装法一（推荐，最省事）：

sudo apt install python3-serial

这就是 6-5 讲的那条正路——apt 装的 Python 库，系统里任何 Python 脚本都能 import，不需要进 venv。

装法二（走 venv）：

source ~/arduino-env/bin/activate     # 用 8-4 建的那个环境也行
pip install pyserial

两者区别（顺手复习 6-5 那条规矩）：

验证：

python3 -c "import serial; print(serial.__version__)"

看到版本号就算装好。

三、最小可用：让树莓派读到 Arduino 说的话

Arduino 端（serial_report.ino）：

void setup() {
  Serial.begin(9600);              // ⚠️ 记住这个数字
}

void loop() {
  Serial.println("hello from arduino");   // 发一行（println 自带换行）
  delay(1000);
}

上传之后立刻把串口监视器关掉（8-3 学的那条纪律）。

树莓派端（read_serial.py）：

import serial
import time

ser = serial.Serial('/dev/ttyACM0', 9600, timeout=2)
time.sleep(2)                  # ⚠️ 关键：等板子复位完成（下面解释）
ser.reset_input_buffer()       # 清掉开机那几秒的垃圾数据

try:
    while True:
        if ser.in_waiting > 0:
            line = ser.readline().decode('utf-8', errors='replace').rstrip()
            if line:
                print("收到：", line)
except KeyboardInterrupt:
    print("\n结束")
finally:
    ser.close()

time.sleep(2)                 # 等它复位完
ser.reset_input_buffer()      # 清掉复位期间的垃圾字节

看到什么算成功：

收到： hello from arduino
收到： hello from arduino
收到： hello from arduino

读结果：

四、反方向：让树莓派发命令给 Arduino

Arduino 端（serial_cmd.ino）：

void setup() {
  Serial.begin(9600);
  pinMode(LED_BUILTIN, OUTPUT);
  Serial.println("ready");
}

void loop() {
  if (Serial.available() > 0) {
    char c = Serial.read();
    if (c == '1') {
      digitalWrite(LED_BUILTIN, HIGH);
      Serial.println("LED ON");
    } else if (c == '0') {
      digitalWrite(LED_BUILTIN, LOW);
      Serial.println("LED OFF");
    }
  }
}

树莓派端（send_serial.py）：

import serial
import time

ser = serial.Serial('/dev/ttyACM0', 9600, timeout=2)
time.sleep(2)
ser.reset_input_buffer()

try:
    while True:
        cmd = input("输入 1 开灯 / 0 关灯 / q 退出：").strip()
        if cmd == 'q':
            break
        if cmd in ('0', '1'):
            ser.write(cmd.encode('utf-8'))    # ⚠️ 发的是字节，不是字符串
            ser.flush()
            time.sleep(0.2)                   # 给板子一点时间回话
            while ser.in_waiting > 0:
                print("板子回：", ser.readline().decode('utf-8', errors='replace').rstrip())
finally:
    ser.close()

看到什么算成功：

输入 1 开灯 / 0 关灯 / q 退出：1
板子回： LED ON
输入 1 开灯 / 0 关灯 / q 退出：0
板子回： LED OFF

并且板载灯真的跟着亮、灭。

读结果：

• Arduino 那三行（available / read / 判断）跟 8-3 第三步完全一样——只不过这次"敲键盘的人"换成了 Python 脚本
• ser.write(cmd.encode('utf-8'))：⚠️ 串口只能发字节，不能发字符串，必须先 .encode()
• 发完要 flush()：确保数据真的推出去了，而不是还躺在缓冲里

五、六个参数里，你只需要管一个

打开串口时可以配一堆参数，实际最常用的只有三个：

serial.Serial(
    port='/dev/ttyACM0',   # 端口名        ← 必填
    baudrate=9600,         # 波特率        ← 必填
    timeout=2,             # 读超时（秒）   ← 强烈建议填
)

完整的六件套是：波特率、数据位（8）、校验位（无）、停止位（1）、流控（无）、超时。

后四个几乎永远是默认值，只有接老式工业设备才需要改。

六、自己订一份协议（本节的核心概念）

为什么不能"想发什么就发什么"？

因为串口是一条字节流，它自己不带边界。你发 123456，对面根本不知道这是"1、2、3、4、5、6"还是"12、345、6"还是"123456"。

所以要订三个约定：

一个完整的例子——Arduino 每秒发一行：

pot,512,2.50
pot,738,3.61
pot,1023,5.00

读法是：类型, 原始值, 电压。

Arduino 端代码：

void setup() {
  Serial.begin(9600);
}

void loop() {
  int raw = analogRead(A0);           // 0 ~ 1023
  float volt = raw * 5.0 / 1023.0;    // 换算成电压

  Serial.print("pot,");               // 不换行
  Serial.print(raw);
  Serial.print(",");
  Serial.println(volt, 2);            // 换行，保留两位小数

  delay(500);
}

树莓派端解析：

import serial
import time

ser = serial.Serial('/dev/ttyACM0', 9600, timeout=2)
time.sleep(2)
ser.reset_input_buffer()

try:
    while True:
        line = ser.readline().decode('utf-8', errors='replace').rstrip()
        if not line:
            continue

        parts = line.split(',')
        if len(parts) != 3 or parts[0] != 'pot':
            print("格式不认识，跳过：", line)      # ← 容错
            continue

        try:
            raw = int(parts[1])
            volt = float(parts[2])
        except ValueError:
            continue                              # ← 再一层容错

        print(f"原始值 {raw:4d}   电压 {volt:.2f} V")
except KeyboardInterrupt:
    print("\n结束")
finally:
    ser.close()

七、⚠️ 排障表（本节最值钱的一张）

手动测一把（比写脚本更快看清问题）：

python3 -m serial.tools.miniterm /dev/ttyACM0 9600
# 退出：Ctrl + ]

或者用 minicom：

sudo apt install minicom
minicom -D /dev/ttyACM0 -b 9600

排障的四步顺序（和 2-5 的网络四步法是同一种思路——从最底层往上查）：

① 设备在不在？（ls /dev/tty*）      ← 线、板子、供电
② 权限够不够？（groups 有没有 dialout）← 用户组
③ 端口被占了吗？（lsof）             ← 别的程序
④ 参数对吗？（波特率、有没有等复位） ← 最后才怀疑代码

八、动手 Demo：一个小项目——树莓派当"显示器"

目标：Arduino 读电位器，树莓派接过来显示；电压超过一半时，树莓派反过来命令 Arduino 点亮灯。

这是一条完整的双向闭环，本章学的所有东西都用上了。

硬件：电位器接 Arduino 的 A0（两端接 5V 与 GND，中间脚接 A0）。

Arduino 端（dial.ino）：

void setup() {
  Serial.begin(9600);
  pinMode(LED_BUILTIN, OUTPUT);
}

void loop() {
  // ① 有命令就先处理命令
  if (Serial.available() > 0) {
    char c = Serial.read();
    if (c == '1') digitalWrite(LED_BUILTIN, HIGH);
    else if (c == '0') digitalWrite(LED_BUILTIN, LOW);
  }

  // ② 每 500 毫秒报一次读数
  static unsigned long last = 0;
  if (millis() - last > 500) {
    last = millis();
    int raw = analogRead(A0);
    Serial.print("pot,");
    Serial.print(raw);
    Serial.print(",");
    Serial.println(raw * 5.0 / 1023.0, 2);
  }
}

树莓派端（dial.py）：

import serial
import time

ser = serial.Serial('/dev/ttyACM0', 9600, timeout=1)
time.sleep(2)
ser.reset_input_buffer()

led_on = False

try:
    print("转一转电位器（Ctrl+C 结束）")
    while True:
        line = ser.readline().decode('utf-8', errors='replace').rstrip()
        if not line:
            continue

        parts = line.split(',')
        if len(parts) != 3 or parts[0] != 'pot':
            continue
        try:
            raw = int(parts[1])
            volt = float(parts[2])
        except ValueError:
            continue

        print(f"原始值 {raw:4d}   电压 {volt:.2f} V")

        # 超过 2.5V 就命令 Arduino 亮灯，低于就灭
        want = volt > 2.5
        if want != led_on:
            ser.write(b'1' if want else b'0')
            ser.flush()
            led_on = want
            print("   → 已发指令：", "开灯" if want else "关灯")
except KeyboardInterrupt:
    print("\n结束")
finally:
    ser.close()

看到什么算成功：

转一转电位器（Ctrl+C 结束）
原始值  128   电压 0.63 V
原始值  376   电压 1.84 V
原始值  612   电压 2.99 V
   → 已发指令： 开灯
原始值  995   电压 4.86 V
原始值  243   电压 1.19 V
   → 已发指令： 关灯

读结果：

九、30 秒实验：把线拔了，看会发生什么

故意做一次故障：脚本跑着的时候，直接拔掉 Arduino 的 USB 线。

你会看到：脚本抛出一堆东西——SerialException、device disconnected 之类，然后带着一大段报错栈退出。

读结果：

• 真实项目里，线会松、板子会断电、会被人不小心拔。程序不应该因此崩掉。
• 加一层保护就优雅了：

try:
    while True:
        ...
except KeyboardInterrupt:
    print("\n用户结束")
except serial.SerialException as e:
    print("\n串口断了：", e)      # ← 只报一句，不抛一堆栈
finally:
    try:
        ser.close()
    except Exception:
        pass

十、常见误区

1. "串口设备名一定是 ttyACM0" —— 原厂板是 ttyACM0，CH340 兼容板是 ttyUSB0。养成"拔插对比 ls"的习惯，别背名字。

2. "报权限错就用 sudo 跑脚本" —— ❌ 会让脚本生成的配置文件归 root。正解是加 dialout 组并重启（8-2 五）。

3. "打开串口不会影响板子" —— ⚠️ Uno R3 会复位约 2 秒（DTR 那一下）。不 sleep(2) 就会读到一堆乱码。R4 没这个问题。

4. "readline() 一定能读到一整行" —— 不一定。超时会返回空（所以代码里要 if not line: continue），复位时可能读到半行。

5. "忘了 ser.close() 没关系" —— ❌ 端口会一直占着。下次跑脚本就报"端口忙"，而且你在 IDE 里也会连不上。用 finally 保证它一定执行。

6. "收到的数据一定格式正确" —— ❌ 现实里会有半行、空行、乱码、上一条的尾巴。必须写"解析不了就丢弃"的容错。

7. "串口可以双向同时高速通信" —— 串口是半双工式的一问一答通道（同一时刻主要朝一个方向流）。发完要留时间给对方回话（本例里那个 time.sleep(0.2) 就是这个意思）。

8. "用 delay 简单省事" —— ❌ delay 期间程序收不到任何命令（8-3 误区 7）。要"一边做别的一边随时能收命令"，就必须用 millis() 记时间戳——本节 Demo 示范了写法。

9. "GPIO 直连更简洁，还省一根线" —— ⚠️ 先看清三个代价：电平不匹配会烧树莓派、串口默认被控制台占着、老教程改的文件位置已搬走。初学一律走 USB。

10. "中文也能直接 print 给串口" —— 理论上能（只要两端编码一致），但调试时最容易出乱码。调试信息一律用英文和数字，要显示中文交给 Python 或网页去做（8-4 讲过同一条）。

• ☑ 第八章 完结 —— 教材这一章已读完五节：认清 Arduino 这块"没有操作系统的板子"、在树莓派上把开发环境装好、用 IDE 写出并上传第一个程序、用 Python 通过 Firmata 从外面指挥它，最后自己订一份串口协议把两块板子接成一条完整的双向回路
• ☑ 第九章 Raspberry Pi Pico 开发板与 MicroPython 语言 已完结：9-4 使用 MicroPython 控制 Raspberry Pi Pico 开发板（machine 三件兵器＋电位器调灯闭环）

相关笔记

• 认识 Raspberry Pi Pico 开发板 —— 下一章起点：家族里的另一块板，与 Uno 的对照表在这一节
• 使用 MicroPython 控制 Raspberry Pi Pico 开发板 —— 本节订的行协议三规矩，在 machine.UART 里原样适用
• 使用 Python 开发 Arduino 程序 —— 上一节：用现成协议（Firmata）指挥，本节是自己订协议
• 使用 Arduino IDE 建立 Arduino 程序 —— 本节 Arduino 端那三行"读命令控灯"，原型就在那里
• 在树莓派建立 Arduino 开发环境 —— dialout 组为什么必须加、端口名怎么确认
• 认识 Arduino Uno 开发板 —— 0／1 号脚为什么"不能接别的东西"，答案在这里揭晓
• Python 函数与模块 —— apt 装库为什么要带 python3- 前缀、import 时又去掉
• 模拟输入 —— 本项目里那颗电位器的接法，7-5 已练过一遍
• 网络连接与蓝牙装置 —— "四步排障法"的原始版本，本节那张串口排障表是同一个思路
• Linux 操作系统的目录结构 —— /boot/firmware 搬家的出处（GPIO 直连要改的配置文件在那儿）
• 🍓 树莓派 · 索引 —— 全课路线图