【产出】 > 会配置 Arduino 串口和串口监视器(波特率、换行符),分清
available()、read()、readStringUntil()的用法和超时行为,最后写出一个不阻塞的按行命令解析器,在串口监视器里输入led on、pwm 128这类命令控制开发板。
【版本】 > 按 Arduino 官方语言参考(Serial、begin、available、read、readStringUntil、readBytesUntil、setTimeout)和内置示例 SerialEvent 编写,适用于 Arduino IDE 2.x 与 Arduino CLI。示例以 UNO R3 为例。
一、Arduino 的串口是什么
串口(UART / USART)是开发板和电脑或其他设备之间最常用的通信方式,所有 Arduino 板至少有一个。在 UNO R3 上,Serial 既连着板上的 USB 转串口芯片(接电脑),又引到了 0 号(RX)和 1 号(TX)引脚。
各板串口引脚(官方表格节选):
| 板子 | Serial | Serial1 | 其他 |
|---|---|---|---|
| UNO R3、经典 Nano | 0(RX)、1(TX) | ||
| UNO R4 Minima / WiFi | 仅 USB | 0(RX0)、1(TX0) | |
| Leonardo、Micro | 仅 USB | 0(RX)、1(TX) | |
| Mega 2560 Rev3 | 0(RX)、1(TX) | 19(RX1)、18(TX1) | Serial2:17、16;Serial3:15、14 |
| MKR 系列 | 仅 USB | 13(RX)、14(TX) | |
| Nano 33 IoT、Nano RP2040 Connect、Nano 33 BLE | 仅 USB | 0(RX0)、1(TX0) |
表中"仅 USB"表示该板的 Serial 走的是原生 USB 口,没有引到 0、1 号引脚,对应引脚上的是 Serial1。
【注意】 > 在 UNO、Nano、Mini、Mega 这些老板子上,0、1 号引脚和电脑通信共用。往这两个引脚上接东西会干扰通信,甚至导致上传失败。另外,TX/RX 是 TTL 电平(5 V 或 3.3 V,看板子),不能直接接电脑的 RS232 口,RS232 电平是 ±12 V,会损坏开发板。
二、Serial.begin():设置波特率
Serial.begin(speed);
Serial.begin(speed, config);
| 参数 | 说明 |
|---|---|
speed | 波特率,单位 bit/s,类型 long |
config | 数据位、校验位、停止位,默认 SERIAL_8N1(8 位数据、无校验、1 位停止) |
config 的取值格式是 SERIAL_ + 数据位(5–8)+ 校验(N 无 / E 偶 / O 奇)+ 停止位(1 或 2),例如 SERIAL_7E1。和电脑上的串口监视器通信时,用默认值即可;接某些工业设备时才需要改。
两边波特率必须一致。 代码里写 Serial.begin(9600),串口监视器右下角也要选 9600。不一致时看到的是乱码或什么都没有。
官方补充两点:
- Leonardo 这类原生 USB(USB CDC)的
Serial,begin()里的波特率不起作用,监视器选什么都能通信; - Nano 33 BLE / BLE Sense 的
Serial1只支持SERIAL_8N1。
三、串口监视器的换行符设置
串口监视器底部有一个下拉框,决定你按回车发送时,在文字末尾自动加什么:
| 选项 | 末尾追加的字节 |
|---|---|
| No Line Ending(无换行) | 什么都不加 |
| New Line(换行) | \n(十进制 10) |
| Carriage Return(回车) | \r(十进制 13) |
| Both NL & CR(换行和回车) | \r\n |
本文的解析程序以 \n 作为一行结束,并忽略 \r,所以选 New Line 或 Both NL & CR 都可以。选了 No Line Ending,程序永远等不到行尾,命令就不会被执行。
四、available() 和 read():一次一个字节
int n = Serial.available(); // 接收缓冲区里有多少字节可读
int c = Serial.read(); // 取出第一个字节;没有数据时返回 -1
串口收到的数据先存进一个接收缓冲区,官方文档说明这个缓冲区大小是 64 字节。available() 告诉你里面现在有几个字节,read() 取走一个。
read() 的返回值类型是 int,不是 char。这样它才能用 −1 表示"没有数据",和真实的字节值 0–255 区分开。
最基础的回显程序:
void setup() {
Serial.begin(9600);
}
void loop() {
if (Serial.available() > 0) {
int incomingByte = Serial.read();
Serial.print("I received: ");
Serial.println(incomingByte, DEC); // 打印十进制编码
}
}
在监视器里选 New Line,输入 A 回车,会看到两行:65(字母 A)和 10(换行符)。这能直观看到换行符确实被发送过来了。
【提示】 > 缓冲区满了以后,新到的数据会丢掉。所以
loop()要经常检查串口,及时把数据取走。loop()里如果有长时间的delay(),对方一次发来超过 64 字节就会丢数据。
五、readStringUntil() 与超时
一次读一整段更省事:
String line = Serial.readStringUntil('\n');
官方说明的行为:
| 情况 | 结果 |
|---|---|
| 找到结束符 | 返回结束符之前的全部字符;结束符从缓冲区里删除,不包含在结果中 |
| 超时还没找到结束符 | 函数结束返回;已读出的字符被丢弃 |
| 结束符前面没有数据 | 返回空结果 |
关键在于超时:它会一直等,直到收到结束符或等满超时时间。超时由 setTimeout() 设置:
Serial.setTimeout(time); // 单位毫秒,类型 long,默认 1000
这个超时值影响一组 Stream 函数:find()、findUntil()、parseInt()、parseFloat()、readBytes()、readBytesUntil()、readString()、readStringUntil()。
用 readStringUntil() 的简单写法:
void setup() {
Serial.begin(9600);
Serial.setTimeout(50); // 最多等 50 ms
}
void loop() {
if (Serial.available() > 0) {
String line = Serial.readStringUntil('\n');
line.trim(); // 去掉首尾空白,包括 '\r'
Serial.print("got: ");
Serial.println(line);
}
}
这种写法的问题:
- 会阻塞。数据只来了一半时,函数最多要等满超时时间,这段时间
loop()里别的事都做不了。 - 超时值不好定。设大了卡得久;设小了,如果对方发送一行的间隔比超时还长(比如人手慢慢敲、或低波特率下发送长行),一行会被拆成两半处理。
- 动态内存。
String在 UNO 这种只有 2 KB RAM 的芯片上反复拼接,可能造成内存碎片,长时间运行后出现怪问题。
对时间要求不高的小程序,用它没问题。需要一边收命令一边做其他事时,用下一节的方法。
还有一个类似的函数 readBytesUntil(character, buffer, length),读进字符数组、返回读到的字符数(size_t),避免了 String,但同样受超时控制、同样会阻塞。
六、非阻塞按行解析:字符缓冲区
思路:每次 loop() 把已经到达的字节取出来,放进自己的字符数组;遇到 \n 就说明一行收齐,交给处理函数,然后清空数组继续收。全程不等待。
官方 SerialEvent 示例用的也是"逐字节收、遇到换行设标志"的思路,只是存在 String 里。下面改成固定大小的 char 数组,并加上长度保护。
const byte LINE_MAX = 32; // 一行最多 31 个字符 + 结尾 '\0'
char lineBuf[LINE_MAX];
byte lineLen = 0;
bool lineOverflow = false;
const int ledPin = LED_BUILTIN;
const int pwmPin = 9; // UNO 上 9 号引脚支持 PWM
void handleLine(char *line);
void setup() {
Serial.begin(9600);
pinMode(ledPin, OUTPUT);
pinMode(pwmPin, OUTPUT);
Serial.println("ready. commands: led on | led off | pwm 0-255 | help");
}
void loop() {
pollSerial();
// 这里可以放其他任务,例如用 millis() 计时的闪灯、传感器采样
}
void pollSerial() {
while (Serial.available() > 0) {
char c = (char)Serial.read();
if (c == '\r') continue; // 兼容 "Both NL & CR"
if (c == '\n') {
if (lineOverflow) {
Serial.println("ERR line too long");
} else {
lineBuf[lineLen] = '\0';
handleLine(lineBuf);
}
lineLen = 0;
lineOverflow = false;
continue;
}
if (lineLen < LINE_MAX - 1) {
lineBuf[lineLen++] = c;
} else {
lineOverflow = true; // 丢弃本行剩余字符,等到 '\n' 再报错
}
}
}
void handleLine(char *line) {
char *cmd = strtok(line, " ");
char *arg = strtok(NULL, " ");
if (cmd == NULL) return; // 空行
if (strcmp(cmd, "led") == 0 && arg != NULL) {
if (strcmp(arg, "on") == 0) {
digitalWrite(ledPin, HIGH);
Serial.println("OK led on");
} else if (strcmp(arg, "off") == 0) {
digitalWrite(ledPin, LOW);
Serial.println("OK led off");
} else {
Serial.println("ERR led needs on/off");
}
} else if (strcmp(cmd, "pwm") == 0 && arg != NULL) {
char *end;
long v = strtol(arg, &end, 10);
if (*end != '\0' || v < 0 || v > 255) {
Serial.println("ERR pwm needs 0-255");
} else {
analogWrite(pwmPin, (int)v);
Serial.print("OK pwm ");
Serial.println(v);
}
} else if (strcmp(cmd, "help") == 0) {
Serial.println("led on | led off | pwm 0-255 | help");
} else {
Serial.print("ERR unknown: ");
Serial.println(cmd);
}
}
代码要点:
| 位置 | 作用 |
|---|---|
while (Serial.available() > 0) | 只处理已经到达的字节,没有数据就立刻返回 |
忽略 '\r' | 监视器选 New Line 或 Both NL & CR 都能用 |
LINE_MAX - 1 | 给结尾的 '\0' 留一个位置,防止写出数组边界 |
lineOverflow | 超长行整行丢弃并报错,不会把半截内容当成命令 |
strtok | 按空格切分成命令和参数 |
strtol + 检查 *end | 参数里混入非数字(如 pwm 12a)时报错,而不是悄悄当成 12 |
strcmp、strtok、strtol 是 C 标准库函数,Arduino 默认就能用,不需要额外 #include。
上传后打开串口监视器,波特率 9600,换行选 New Line,依次输入:
help
led on
pwm 128
pwm 300
abc
应该依次看到 OK、ERR 等回复。9 号引脚接一个串了 220 Ω 电阻的 LED,就能看到亮度变化。
【注意】 >
strtok会直接修改传入的字符串(把空格改成'\0'),并且内部保存状态,不能在两个地方交替使用。这里只在handleLine()里一次性切完,是安全的用法。
七、几种读法怎么选
| 方法 | 是否阻塞 | 内存 | 适合 |
|---|---|---|---|
available() + read() 逐字节 | 否 | 自己控制 | 需要同时处理其他任务的正式程序 |
readStringUntil() | 会,最长等超时时间 | 动态 String | 调试、快速验证 |
readBytesUntil() | 会,最长等超时时间 | 固定数组 | 内存紧张但能接受短暂等待 |
parseInt() / parseFloat() | 会 | 无 | 只需要读一个数字的简单场景 |
八、常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 监视器里全是乱码 | 波特率两边不一致 | 监视器选和 begin() 相同的值 |
| 命令发了没反应 | 监视器选了 No Line Ending | 改成 New Line |
命令比较 == "on" 总是失败 | 结果里带了 \r | 忽略 \r,或对 String 调用 trim() |
| 上传时报端口错误 | 0、1 号引脚接了外设,或监视器占用端口 | 断开 0、1 号引脚上的连线;关闭其他占用该端口的程序 |
| 大段数据丢字节 | loop() 被 delay() 卡住,64 字节缓冲区溢出 | 去掉长 delay(),及时读走数据 |
| Leonardo 开机打印的内容看不到 | 原生 USB 串口重新枚举,监视器还没连上 | 在 setup() 里加 while (!Serial) {} 等待连接(无电脑时运行会卡住,正式程序中去掉) |
参考资料
- Arduino 语言参考:Serial https://docs.arduino.cc/language-reference/en/functions/communication/serial/
- Serial.begin() https://docs.arduino.cc/language-reference/en/functions/communication/serial/begin/
- Serial.available() https://docs.arduino.cc/language-reference/en/functions/communication/serial/available/
- Serial.read() https://docs.arduino.cc/language-reference/en/functions/communication/serial/read/
- Serial.readStringUntil() https://docs.arduino.cc/language-reference/en/functions/communication/serial/readStringUntil/
- Serial.readBytesUntil() https://docs.arduino.cc/language-reference/en/functions/communication/serial/readBytesUntil/
- Serial.setTimeout() https://docs.arduino.cc/language-reference/en/functions/communication/serial/setTimeout/
- Arduino 内置示例:Serial Event https://docs.arduino.cc/built-in-examples/communication/SerialEvent/
- 示例源码:https://github.com/arduino/arduino-examples/blob/main/examples/04.Communication/SerialEvent/SerialEvent.ino
- 语言参考源文件:https://github.com/arduino/reference-en
评价 (0)