Arduino Language Reference-Functions-Serial-Functions

本篇文章均翻译自官方文档，为博主自用。方便博主提高英语水平。

必须注意的是，翻译不可能完全正确，若有矛盾之处或不能理解之处，需要查看原英文资料，并在comment中告知。

if(Serial)

if(Serial)

Description

指示指定的串行端口是否准备就绪。

在具有原生USB的板上，if (Serial)（或在Due上的if(SerialUSB)）表示USB CDC串行连接是否打开。对于所有其他板和非USB CDC端口，这将始终返回true。

Syntax

if (Serial)

Parameters

无

Returns

如果指定的串行端口可用，则返回true。如果在Leonardo的USB CDC串行连接准备就绪之前查询，这将只返回false。数据类型：bool。

Example Code

void setup() {
  //初始化串行并等待端口打开：
  Serial.begin(9600);
  while (!Serial) {
    ; // 等待串行端口连接。对于原生USB来说是必需的
  }
}

void loop() {
  //正常进行
}

Notes and Warnings

此函数增加了10ms的延迟，试图解决“打开但不完全”情况。不要在紧密循环中使用它。

Serial.available()

Serial.available()

Description

获取可从串行端口读取的字节数（字符）。这是已经到达并存储在串行接收缓冲区中的数据（该缓冲区容量为64字节）。

Serial.available() 继承自 Stream 实用程序类。

Syntax

Serial.available()

Parameters

Serial：串行端口对象。请参阅 Serial 主页上每个板的可用串行端口列表。

Returns

可读取的字节数。

Example Code

以下代码返回通过串行端口接收的字符。

int incomingByte = 0; // 用于接收串行数据

void setup() {
  Serial.begin(9600); // 打开串行端口，设置数据速率为9600 bps
}

void loop() {
  // 仅在接收到数据时回复：
  if (Serial.available() > 0) {
    // 读取接收到的字节：
    incomingByte = Serial.read();

    // 说出你收到了什么：
    Serial.print("I received: ");
    Serial.println(incomingByte, DEC);
  }
}

Arduino Mega 示例：
此代码将在Arduino Mega的一个串行端口接收到的数据发送到另一个串行端口。例如，这可以用来通过Arduino板将串行设备连接到计算机。

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

void loop() {
  // 从端口0读取，发送到端口1：
  if (Serial.available()) {
    int inByte = Serial.read();
    Serial1.print(inByte, DEC);
  }
  // 从端口1读取，发送到端口0：
  if (Serial1.available()) {
    int inByte = Serial1.read();
    Serial.print(inByte, DEC);
  }
}

See also

Serial.availableForWrite()

Serial.availableForWrite()

Description

获取可在不阻塞写操作的情况下写入串行缓冲区的字节数(字符数)。

Syntax

Serial.availableForWrite()

Parameters

Serial：串行端口对象。请参阅串行主页上每个电路板的可用串行端口列表。

Returns

可写入的字节数。

See also

Serial.begin()

Serial.begin()

Description

设置串行数据传输的数据速率（波特率），单位是每秒比特数。与串口监视器通信时，请确保使用其屏幕右下角菜单中列出的一个波特率。然而，您也可以指定其他速率 - 例如，与需要特定波特率的组件通过0和1脚进行通信。

一个可选的第二个参数用于配置数据位、奇偶校验位和停止位。默认配置是8个数据位，无奇偶校验，1个停止位。

Syntax

Serial.begin(speed)
Serial.begin(speed, config)

Parameters

Serial：串行端口对象。请参阅串行主页上每块板的可用串行端口列表。

speed：以每秒比特数（波特率）表示。允许的数据类型：long。

config：设置数据位、奇偶校验位和停止位。有效值包括：

SERIAL_5N1

SERIAL_6N1

SERIAL_7N1

SERIAL_8N1（默认值）

SERIAL_5N2

SERIAL_6N2

SERIAL_7N2

SERIAL_8N2

SERIAL_5E1：偶校验

SERIAL_6E1

SERIAL_7E1

SERIAL_8E1

SERIAL_5E2

SERIAL_6E2

SERIAL_7E2

SERIAL_8E2

SERIAL_5O1：奇校验

SERIAL_6O1

SERIAL_7O1

SERIAL_8O1

SERIAL_5O2

SERIAL_6O2

SERIAL_7O2

SERIAL_8O2

Returns

无

Example Code

void setup() {
    Serial.begin(9600); // 打开串行端口，设置数据速率为9600 bps
}

void loop() {}

Arduino Mega 示例：

// Arduino Mega 使用它的所有四个串行端口
// （Serial, Serial1, Serial2, Serial3），
// 并使用不同的波特率：

void setup() {
  Serial.begin(9600);
  Serial1.begin(38400);
  Serial2.begin(19200);
  Serial3.begin(4800);

  Serial.println("Hello Computer");
  Serial1.println("Hello Serial 1");
  Serial2.println("Hello Serial 2");
  Serial3.println("Hello Serial 3");
}
void loop() {}

感谢Jeff Gray提供的mega示例

Notes and Warnings

对于USB CDC串行端口（例如Leonardo上的Serial），Serial.begin()是不相关的。您可以使用任何波特率和配置来进行串行通信。请参阅串行主页上每块板的可用串行端口列表。

对于Arduino Nano 33 BLE和Nano 33 BLE Sense板上的Serial1，唯一支持的config值是SERIAL_8N1。

Serial.end()

Serial.end()

Description

禁用串行通信,允许 RX 和 TX 引脚被用于一般输入和输出。要重新启用串行通信,请调用 Serial.begin()。

Syntax

Serial.end()

Parameters

Serial: 串行端口对象。请参阅串行主页上列出的每个板上可用的串行端口列表。

Returns

无

Serial.find()

Serial.find()

Description

Serial.find()从串行缓冲区读取数据,直到找到目标。如果找到目标,该函数返回true,如果超时则返回false。

Serial.find()继承自stream实用程序类。

Syntax

Serial.find(target)
Serial.find(target, length)

Parameters

Serial: 串行端口对象。请参阅每个板上可用串行端口的列表,详见Serial主页。
target: 要搜索的字符串。允许的数据类型: char。
length: 目标的长度。允许的数据类型: size_t。

Returns

数据类型: bool。

See also

Serial.findUntil()

Serial.findUntil()

Description

Serial.findUntil() 从串行缓冲区读取数据,直到找到给定长度的目标字符串或终止字符串。

如果找到目标字符串,该函数返回 true,如果超时则返回 false。

Serial.findUntil() 继承自 Stream 实用程序类。

Syntax

Serial.findUntil(target, terminal)

Parameters

Serial: 串行端口对象。请参阅 Serial主页 上每个板上可用串行端口的列表。
target: 要搜索的字符串。允许的数据类型: char。
terminal: 搜索中的终止字符串。允许的数据类型: char。

Returns

数据类型: bool。

See also

Serial.flush()

Serial.flush()

Description

等待传出串行数据传输完成。

flush() 继承自 Stream 实用程序类。

Syntax

Serial.flush()

Parameters

Serial：串行端口对象。请参阅每个开发板上可用串行端口的列表，详见 Serial 主页。

Returns

无

See also

Serial.parseFloat()

Serial.parseFloat()

Description

Serial.parseFloat() 从串行缓冲区返回第一个有效的浮点数。 parseFloat() 在遇到第一个非浮点数字符时终止。如果超时，该函数将终止（请参阅 Serial.setTimeout()）。

Serial.parseFloat() 继承自 Stream 实用程序类。

Syntax

Serial.parseFloat()
Serial.parseFloat(lookahead)
Serial.parseFloat(lookahead, ignore)

Parameters

Serial：串行端口对象。查看每个板上可用串行端口的列表，请参阅 Serial 主页。
lookahead：用于在流中查找浮点数的模式。允许的数据类型：LookaheadMode。lookahead 允许的值：

  • SKIP_ALL：在扫描流以查找浮点数时，除减号、小数点或数字外，所有其他字符都将被忽略。这是默认模式。
  • SKIP_NONE：不跳过任何字符，只有在第一个等待字符有效时才会对流进行操作。
  • SKIP_WHITESPACE：只跳过制表符、空格、换行符和回车符。

ignore：用于在搜索过程中跳过指定字符。例如，用于跳过千位分隔符。允许的数据类型：char

Returns

数据类型：float。

See also

Serial.parseInt()

Serial.parseInt()

Description

查找传入序列中的下一个有效整数。如果超时(参见 Serial.setTimeout())则函数终止。

Serial.parseInt() 继承自 Stream 实用程序类。

特别是:

  • 解析在配置的超时时间内没有读取任何字符或读取到非数字字符时停止;
  • 如果在超时(参见 Serial.setTimeout())发生时没有读取到有效数字,将返回0;

Syntax

Serial.parseInt()
Serial.parseInt(lookahead)
Serial.parseInt(lookahead, ignore)

Parameters

Serial: 串行端口对象。有关各个板上可用串行端口的列表,请参阅 Serial 主页。
lookahead: 用于在流中查找整数时使用的模式。允许的数据类型: LookaheadMode。允许的 lookahead 值:

  • SKIP_ALL: 在扫描流以查找整数时,将忽略除数字或减号以外的所有字符。这是默认模式。
  • SKIP_NONE: 不跳过任何内容,除非第一个待处理字符无效,否则不会触及流。
  • SKIP_WHITESPACE: 只跳过制表符、空格、换行符和回车。

ignore: 用于在搜索时跳过指定字符。例如用于跳过千位分隔符。允许的数据类型: char

Returns

下一个有效整数。数据类型: long。

See also

笔记：若从串口监视器中输入“123a”则不会有延时，而输入“123”则会有1秒的延迟，这是因为函数在等待新的输入，以防解析不全。

Serial.peek()

Serial.peek()

Description

返回传入的串行数据的下一个字节(字符)而不从内部串行缓冲区中移除它。也就是说,连续调用peek()将返回相同的字符,下一次调用read()也是如此。

Serial.peek()继承自Stream实用程序类。

Syntax

Serial.peek()

Parameters

Serial：串行端口对象。请参阅每个板上可用串行端口的列表串行主页面。

Returns

可用的传入串行数据的第一个字节(如果没有可用数据则返回-1)。数据类型：int。

See also

Serial.print()

Serial.print()

Description

将数据以人类可读的ASCII文本形式打印到串行端口。这个命令可以有多种形式。数字使用每个数字的ASCII字符打印。浮点数同样以ASCII数字打印，默认为两位小数。字节作为单个字符发送。字符和字符串按原样发送。例如：

  • Serial.print(78) 输出 "78"
  • Serial.print(1.23456) 输出 "1.23"
  • Serial.print('N') 输出 "N"
  • Serial.print("Hello world.") 输出 "Hello world."

一个可选的第二参数指定使用的基数（格式）；允许的值有 BIN(二进制，或基数2)，OCT(八进制，或基数8)，DEC(十进制，或基数10)，HEX(十六进制，或基数16)。对于浮点数，这个参数指定使用的小数位数。例如：

  • Serial.print(78, BIN) 输出 "1001110"
  • Serial.print(78, OCT) 输出 "116"
  • Serial.print(78, DEC) 输出 "78"
  • Serial.print(78, HEX) 输出 "4E"
  • Serial.print(1.23456, 0) 输出 "1"
  • Serial.print(1.23456, 2) 输出 "1.23"
  • Serial.print(1.23456, 4) 输出 "1.2346"

你可以通过用F()包装它们，将基于闪存的字符串传递给Serial.print()。例如：

Serial.print(F("Hello World"))

要发送数据而不转换为字符的表示形式，请使用Serial.write()。

Syntax

Serial.print(val)
Serial.print(val, format)

Parameters

Serial：串行端口对象。每个板上可用的串行端口列表，请参见Serial主页。
val：要打印的值。允许的数据类型：任何数据类型。

Returns

print() 返回写入的字节数，尽管读取该数字是可选的。数据类型：size_t。

Example Code

/*
  使用for循环以各种格式打印数字。
*/
void setup() {
  Serial.begin(9600); // 以9600 bps打开串行端口：
}

void loop() {
  // 打印标签
  Serial.print("NO FORMAT");  // 打印一个标签
  Serial.print("\t");         // 打印一个制表符

  Serial.print("DEC");
  Serial.print("\t");

  Serial.print("HEX");
  Serial.print("\t");

  Serial.print("OCT");
  Serial.print("\t");

  Serial.print("BIN");
  Serial.println();        // 在最后一个标签之后换行

  for (int x = 0; x < 64; x++) { // 只是ASCII图表的一部分，根据需要更改
    // 以多种格式打印：
    Serial.print(x);       // 以ASCII编码的十进制打印 - 与"DEC"相同
    Serial.print("\t\t");  // 打印两个制表符以适应标签长度

    Serial.print(x, DEC);  // 以ASCII编码的十进制打印
    Serial.print("\t");    // 打印一个制表符

    Serial.print(x, HEX);  // 以ASCII编码的十六进制打印
    Serial.print("\t");    // 打印一个制表符

    Serial.print(x, OCT);  // 以ASCII编码的八进制打印
    Serial.print("\t");    // 打印一个制表符

    Serial.println(x, BIN);  // 以ASCII编码的二进制打印
    // 然后用"println"添加回车
    delay(200);            // 延迟200毫秒
  }
  Serial.println();        // 再次打印回车
}

Notes and Warnings

有关Serial.print()异步性的信息，请参阅Serial.write()参考页面的注释和警告部分。

See also

Serial.println()

Serial.println()

Description

将数据以人类可读的ASCII文本形式打印到串行端口，后跟一个回车字符（ASCII 13，或 '\r'）和一个换行字符（ASCII 10，或 '\n'）。这个命令采用与 Serial.print() 相同的形式。

Syntax

Serial.println(val)
Serial.println(val, format)

Parameters

Serial：串行端口对象。请参阅 Serial 主页 上每个板的可用串行端口列表。
val：要打印的值。允许的数据类型：任何数据类型。
format：指定数字基数（对于整型数据类型）或小数位数（对于浮点类型）。

Returns

println() 返回写入的字节数，尽管读取该数字是可选的。数据类型：size_t。

Example Code

/*
 Analog input reads an analog input on analog in 0, prints the value out.
 created 24 March 2006
 by Tom Igoe
 */

int analogValue = 0;    // 用于存储模拟值的变量

void setup() {
  // 以 9600 bps 打开串行端口：
  Serial.begin(9600);
}

void loop() {
  // 读取模拟输入针脚 0 上的模拟输入：
  analogValue = analogRead(0);

  // 以多种格式打印出来：
  Serial.println(analogValue);       // 以 ASCII 编码的十进制形式打印
  Serial.println(analogValue, DEC);  // 以 ASCII 编码的十进制形式打印
  Serial.println(analogValue, HEX);  // 以 ASCII 编码的十六进制形式打印
  Serial.println(analogValue, OCT);  // 以 ASCII 编码的八进制形式打印
  Serial.println(analogValue, BIN);  // 以 ASCII 编码的二进制形式打印

  // 在下一次读取之前延迟 10 毫秒：
  delay(10);
}

Notes and Warnings

有关 Serial.println() 的异步性信息，请参阅 Serial.write() 参考页面 的注释和警告部分。

Serial.read()

Serial.read()

Description

读取进来的串行数据。

Serial.read() 继承自 Stream 工具类。

Syntax

Serial.read()

Parameters

Serial：串行端口对象。各个板上可用的串行端口列表，请参见 Serial 主页。

Returns

返回可用的第一个串行数据字节（如果没有数据可用，则返回 -1）。数据类型：int。

Example Code

int incomingByte = 0; // 用于接收串行数据

void setup() {
  Serial.begin(9600); // 打开串行端口，设置数据速率为 9600 bps
}

void loop() {
  // 仅当你接收到数据时发送数据：
  if (Serial.available() > 0) {
    // 读取进来的字节：
    incomingByte = Serial.read();

    // 说出你收到了什么：
    Serial.print("I received: ");
    Serial.println(incomingByte, DEC);
  }
}

Serial.readBytes()

Serial.readBytes()

Description

Serial.readBytes() 从串行端口读取字符到缓冲区。如果已读取确定的长度或超时(参见 Serial.setTimeout())，函数将终止。

Serial.readBytes() 返回放入缓冲区的字符数。0 表示没有找到有效数据。

Serial.readBytes() 继承自 Stream 工具类。

Syntax

Serial.readBytes(buffer, length)

Parameters

Serial：串行端口对象。请参阅每个板上可用串行端口的列表串行主页。
buffer：存储字节的缓冲区。允许的数据类型：char 或 byte 数组。
length：要读取的字节数。允许的数据类型：int。

Returns

放入缓冲区的字节数。数据类型：size_t。

See also

Serial.readBytesUntil()

Serial.readBytesUntil()

Description

Serial.readBytesUntil() 从串行缓冲区读取字符到一个数组中。该函数在以下情况下终止（按此顺序检查）：读取了确定的长度、超时(参见 Serial.setTimeout())或检测到终止符字符(在这种情况下,函数返回直到最后一个字符之前的字符,前提是该字符位于提供的终止符之前)。终止符本身不会返回在缓冲区中。

Serial.readBytesUntil() 返回读入缓冲区的字符数。0 意味着 length 参数 <= 0,发生超时之前没有任何其他输入,或在任何其他输入之前发现了终止字符。

Serial.readBytesUntil() 继承自 Stream 实用程序类。

Syntax

Serial.readBytesUntil(character, buffer, length)

Parameters

Serial: 串行端口对象。请参阅 Serial 主页上每个板上可用的串行端口列表。
character: 要搜索的字符。允许的数据类型: char。
buffer: 用于存储字节的缓冲区。允许的数据类型: char 或 byte 数组。
length: 要读取的字节数。允许的数据类型: int。

Returns

数据类型: size_t。

Notes and Warnings

除非读取和复制到缓冲区的字符数等于 length,否则终止符字符将从串行缓冲区中丢弃。

See also

笔记：

在使用 Serial.readBytesUntil() 函数时，终止字符会从串行缓冲区中读取并丢弃。这意味着终止字符不会再保留在串行缓冲区中。一旦 Serial.readBytesUntil() 遇到终止字符，它就会停止读取并返回，同时从缓冲区中移除这个终止字符。

这种行为使得处理连续数据流时更加方便，因为你不需要担心处理上一次读取留下的终止字符。每次调用 Serial.readBytesUntil() 都会从接收到的位置开始，直到下一个终止字符，无需额外的缓冲区管理或数据清理。

Serial.readString()

Serial.readString()

Description

Serial.readString() 从串行缓冲区中将字符读入一个字符串。如果超时(参见 setTimeout())，该函数将终止。

Serial.readString() 继承自 Stream 实用程序类。

Syntax

Serial.readString()

Parameters

Serial：串行端口对象。在 Serial主页 上可以看到每个板上可用的串行端口列表。

Returns

从串行缓冲区读取的 String

Example Code

演示 Serial.readString()

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

void loop() {
  Serial.println("输入数据:");
  while (Serial.available() == 0) {}     //等待数据可用
  String teststr = Serial.readString();  //读取直到超时
  teststr.trim();                        // 删除字符串末尾的任何 \r \n 空白字符
  if (teststr == "red") {
    Serial.println("一种主要颜色");
  } else {
    Serial.println("其他东西");
  }
}

Notes and Warnings

如果数据包含行结束字符，该函数不会提前终止。返回的 String 可能包含回车和/或换行符(如果它们被接收到的话)。

See also

Serial.readStringUntil()

Serial.readStringUntil()

Description

readStringUntil() 从串行缓冲区读取字符到一个字符串中。如果超时(参见 setTimeout())，函数将终止。

Serial.readStringUntil() 继承自 Stream 实用工具类。

Syntax

Serial.readStringUntil(terminator)

Parameters

Serial：串行端口对象。请参阅 Serial 主页上每个板上可用的串行端口列表。
terminator：要搜索的字符。允许的数据类型：char。

Returns

从串行缓冲区读取的整个 String，直到终止字符。如果找不到终止字符，或者在终止字符之前没有数据，它将返回 NULL。

Notes and Warnings

终止字符从串行缓冲区中被丢弃。如果找不到终止字符，所有读取的字符都将被丢弃。

See also

Serial.setTimeout()

Serial.setTimeout()

Description

Serial.setTimeout() 设置等待串行数据的最大毫秒数。默认值为 1000 毫秒。

Serial.setTimeout() 继承自 Stream 实用程序类。

Syntax

Serial.setTimeout(time)

Parameters

Serial：串行端口对象。请参阅 Serial 主页 上每个板上可用的串行端口列表。
time：超时持续时间（以毫秒为单位）。允许的数据类型：long。

Returns

无

Notes and Warnings

使用 Serial.setTimeout() 设置的超时值的串行功能：

  • Serial.find()
  • Serial.findUntil()
  • Serial.parseInt()
  • Serial.parseFloat()
  • Serial.readBytes()
  • Serial.readBytesUntil()
  • Serial.readString()
  • Serial.readStringUntil()

See also

Serial.write()

Serial.write()

Description

向串行端口写入二进制数据。这些数据作为一个字节或一系列字节发送；要发送表示数字各位的字符，请改用 print() 函数。

Syntax

Serial.write(val)
Serial.write(str)
Serial.write(buf, len)

Parameters

Serial：串行端口对象。请参阅 Serial 主页 上每个板的可用串行端口列表。
val：作为单个字节发送的值。
str：作为一系列字节发送的字符串。
buf：作为一系列字节发送的数组。
len：要从数组中发送的字节数。

Returns

write() 将返回写入的字节数，尽管读取该数字是可选的。数据类型：size_t。

Example Code

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

void loop() {
  Serial.write(45); // 发送一个值为 45 的字节

  int bytesSent = Serial.write("hello");  // 发送字符串 "hello" 并返回字符串的长度。
}

Notes and Warnings

串行传输是异步的。如果传输缓冲区中有足够的空间，Serial.write() 将在任何字符通过串行传输之前返回。如果传输缓冲区已满，则 Serial.write() 将阻塞，直到缓冲区中有足够的空间。为了避免调用 Serial.write() 时阻塞，您可以首先使用 availableForWrite() 检查传输缓冲区中的空闲空间量。

serialEvent()

serialEvent()

Description

当在 loop() 结尾处有数据可用时调用。使用 Serial.read() 来获取这些数据。

请注意: 大多数现代板卡不支持此方法。请参阅本文下面的 "注意事项和警告"。

Syntax

void serialEvent() {
  //语句
}

Mega 2560 R3 和 Due 板卡有额外的串行端口可以通过在函数名末尾添加相应的数字来访问。

void serialEvent1() {
  //语句
}

void serialEvent2() {
  //语句
}

void serialEvent3() {
  //语句
}

Parameters

语句: 任何有效的语句

Returns

无

Notes and Warnings

请注意，serialEvent() 在任何现代 Arduino 板卡上都无法工作。截至 2023/12/06，被认可支持该功能的板卡只有 UNO R3、Nano、Mega 2560 R3 和 Due。

相反，你可以使用 available() 方法。本页面的示例演示了如何在只有串行数据可用时读取，类似于 Serial.event() 的实现。

See also

最后修改：2024 年 04 月 29 日
© 允许规范转载
如果觉得我的文章对你有用，请随意赞赏