第 19.1.3 節

串口通信

0瀏覽次數0訪問次數--跳出率--平均停留

串口是机器人里最常见的通信方式之一：上位机 ROS2 / Linux 程序通过 USB-TTL、USB-CAN 转串口、CH340、CP2102、FT232 等设备和 STM32、ESP32、下位机控制板通信。

本节依旧遵循顺序：

先写普通 main() 里的同步示例
再写普通 main() 里的异步示例
最后写类封装版本

所有异步回调统一使用 std::bind。

Linux 下准备虚拟串口测试环境

如果你手里没有真实 STM32，可以用 socat 创建一对虚拟串口。

安装 socat

Ubuntu / Debian：

sudo apt install socat

Fedora：

sudo dnf install socat

创建一对虚拟串口

新开一个终端，运行：

socat -d -d pty,raw,echo=0 pty,raw,echo=0

你会看到类似输出：

2026/05/24 12:00:00 socat[12345] N PTY is /dev/pts/3
2026/05/24 12:00:00 socat[12345] N PTY is /dev/pts/4
2026/05/24 12:00:00 socat[12345] N starting data transfer loop with FDs [5,5] and [7,7]

这表示：

/dev/pts/3 和 /dev/pts/4 是一对互通的虚拟串口
程序写 /dev/pts/3，另一个终端读 /dev/pts/4 就能看到
程序读 /dev/pts/3，另一个终端写 /dev/pts/4 就能发给程序

下面示例都假设程序使用 /dev/pts/3，另一个终端使用 /dev/pts/4。你要按自己终端实际输出修改。

示例 1：普通 main() 里同步打开串口并发送一行

程序目标

程序打开串口 /dev/pts/3，设置波特率 115200，然后发送：

hello serial

另一个终端从 /dev/pts/4 读到这行数据。

完整代码

#include <boost/asio.hpp>
#include <boost/system/error_code.hpp>
#include <iostream>
#include <string>

int main(int argc, char* argv[])
{
    // 程序从 main 函数开始执行，argc/argv 用来接收命令行参数。
    std::string port_name = "/dev/pts/3";

    if (argc >= 2)
    {
        port_name = argv[1];
    }

    // io_context 是 Asio 的事件循环对象，异步任务需要靠它调度。
    boost::asio::io_context io;
    // serial_port 表示串口设备，后续读写都通过它完成。
    boost::asio::serial_port serial(io);
    boost::system::error_code ec;

    std::cout << "main：准备打开串口 " << port_name << std::endl;

    serial.open(port_name, ec);
    if (ec)
    {
        std::cout << "打开串口失败：" << ec.message() << std::endl;
        return 1;
    }

    serial.set_option(boost::asio::serial_port_base::baud_rate(115200));
    serial.set_option(boost::asio::serial_port_base::character_size(8));
    serial.set_option(boost::asio::serial_port_base::parity(
        boost::asio::serial_port_base::parity::none));
    serial.set_option(boost::asio::serial_port_base::stop_bits(
        boost::asio::serial_port_base::stop_bits::one));
    serial.set_option(boost::asio::serial_port_base::flow_control(
        boost::asio::serial_port_base::flow_control::none));

    std::string msg = "hello serial\n";

    // 把缓冲区中的数据写入连接。
    std::size_t n = boost::asio::write(serial, boost::asio::buffer(msg), ec);
    if (ec)
    {
        std::cout << "发送失败：" << ec.message() << std::endl;
        return 1;
    }

    std::cout << "main：发送成功，字节数 = " << n << std::endl;
    std::cout << "main：程序结束" << std::endl;

    return 0;
}

运行结果：见下方“运行输出与时间顺序”；如果示例涉及定时器、线程、网络或外部设备，具体时间和顺序可能会随环境略有变化。

编译运行

终端 1：创建虚拟串口。

socat -d -d pty,raw,echo=0 pty,raw,echo=0

终端 2：监听另一端。

cat /dev/pts/4

终端 3：编译运行程序。

g++ demo1_serial_write.cpp -o demo1_serial_write -std=c++17 -lboost_system -pthread
./demo1_serial_write /dev/pts/3

运行输出与时间顺序

程序终端输出：

main：准备打开串口 /dev/pts/3
main：发送成功，字节数 = 13
main：程序结束

监听终端输出：

hello serial

这个示例基本没有明显延迟，发送完成后程序立刻结束。

本示例需要注意的点

这是同步写串口。boost::asio::write() 会阻塞，直到数据写完或发生错误。

关键函数说明

serial.open(port_name, ec)

作用：打开串口设备。

参数：

port_name

例如 /dev/ttyUSB0、/dev/ttyACM0、/dev/pts/3。

ec

用于接收错误信息。这样写不会抛异常，更适合教程和机器人工程。

serial.set_option(...)

作用：设置串口参数，例如波特率、数据位、校验位、停止位、流控。

boost::asio::write(serial, boost::asio::buffer(msg), ec)

作用：同步写数据。

返回值：实际写入的字节数。

示例 2：普通 main() 里同步读取一行串口数据

程序目标

程序打开串口并阻塞等待，直到收到 \n 为止。

完整代码

#include <boost/asio.hpp>
#include <boost/system/error_code.hpp>
#include <iostream>
#include <istream>
#include <string>

int main(int argc, char* argv[])
{
    // 程序从 main 函数开始执行，argc/argv 用来接收命令行参数。
    std::string port_name = "/dev/pts/3";

    if (argc >= 2)
    {
        port_name = argv[1];
    }

    // io_context 是 Asio 的事件循环对象，异步任务需要靠它调度。
    boost::asio::io_context io;
    // serial_port 表示串口设备，后续读写都通过它完成。
    boost::asio::serial_port serial(io);
    boost::system::error_code ec;

    serial.open(port_name, ec);
    if (ec)
    {
        std::cout << "打开串口失败：" << ec.message() << std::endl;
        return 1;
    }

    // 设置串口或 socket 参数，例如波特率、数据位或超时相关配置。
    serial.set_option(boost::asio::serial_port_base::baud_rate(115200));

    boost::asio::streambuf buffer;

    std::cout << "main：等待串口收到一行数据，以换行符结束" << std::endl;

    std::size_t n = boost::asio::read_until(serial, buffer, '\n', ec);
    if (ec)
    {
        std::cout << "读取失败：" << ec.message() << std::endl;
        return 1;
    }

    std::istream is(&buffer);
    std::string line;
    std::getline(is, line);

    std::cout << "main：读取到字节数 = " << n << std::endl;
    std::cout << "main：读取到一行 = " << line << std::endl;

    return 0;
}

运行结果：见下方“运行输出与时间顺序”；如果示例涉及定时器、线程、网络或外部设备，具体时间和顺序可能会随环境略有变化。

编译运行

终端 1：创建虚拟串口。

socat -d -d pty,raw,echo=0 pty,raw,echo=0

终端 2：运行程序。

g++ demo2_serial_read_line.cpp -o demo2_serial_read_line -std=c++17 -lboost_system -pthread
./demo2_serial_read_line /dev/pts/3

终端 3：向另一端写数据。

echo "stm32 ok" > /dev/pts/4

运行输出与时间顺序

程序启动后立刻输出：

main：等待串口收到一行数据，以换行符结束

然后程序阻塞。你在另一个终端执行：

echo "stm32 ok" > /dev/pts/4

程序继续输出：

main：读取到字节数 = 9
main：读取到一行 = stm32 ok

这里的等待时间取决于你什么时候发送数据。

本示例需要注意的点

read_until() 是同步阻塞函数。没有收到换行符之前，它会一直卡住。

如果你在 ROS2 回调里直接这样读串口，可能导致整个节点响应变慢。

关键函数说明

boost::asio::read_until(serial, buffer, '\n', ec)

作用：从串口读取数据，直到遇到换行符 \n。

返回值：至少读取到分隔符为止的字节数。

注意：streambuf 里可能还留有额外数据，后续读取时要注意处理。

示例 3：普通 main() 里异步读取一行串口数据

程序目标

把示例 2 改成异步版本：

  1. async_read_until() 注册读取任务；
  2. io.run() 开始等待；
  3. 另一端发送一行数据；
  4. 回调函数执行；
  5. io.run() 返回。

完整代码

#include <boost/asio.hpp>
#include <boost/system/error_code.hpp>
#include <functional>
#include <iostream>
#include <istream>
#include <string>

void on_read_line(const boost::system::error_code& ec,
                  std::size_t bytes_transferred,
                  boost::asio::streambuf* buffer)
{
    if (ec)
    {
        std::cout << "on_read_line：读取失败：" << ec.message() << std::endl;
        return;
    }

    std::istream is(buffer);
    std::string line;
    std::getline(is, line);

    std::cout << "on_read_line：bytes_transferred = " << bytes_transferred << std::endl;
    std::cout << "on_read_line：收到一行 = " << line << std::endl;
}

int main(int argc, char* argv[])
{
    // 程序从 main 函数开始执行，argc/argv 用来接收命令行参数。
    std::string port_name = "/dev/pts/3";

    if (argc >= 2)
    {
        port_name = argv[1];
    }

    // io_context 是 Asio 的事件循环对象，异步任务需要靠它调度。
    boost::asio::io_context io;
    // serial_port 表示串口设备，后续读写都通过它完成。
    boost::asio::serial_port serial(io);
    boost::system::error_code ec;

    serial.open(port_name, ec);
    if (ec)
    {
        std::cout << "打开串口失败：" << ec.message() << std::endl;
        return 1;
    }

    serial.set_option(boost::asio::serial_port_base::baud_rate(115200));

    boost::asio::streambuf buffer;

    std::cout << "main：注册 async_read_until" << std::endl;

    boost::asio::async_read_until(serial,
                                  buffer,
                                  '\n',
                                  std::bind(on_read_line,
                                            std::placeholders::_1,
                                            std::placeholders::_2,
                                            &buffer));

    std::cout << "main：async_read_until 已返回，准备 io.run()" << std::endl;

    // 启动事件循环，前面注册的异步任务会在这里被调度执行。
    io.run();

    std::cout << "main：io.run() 返回" << std::endl;

    return 0;
}

运行结果：见下方“运行输出与时间顺序”；如果示例涉及定时器、线程、网络或外部设备，具体时间和顺序可能会随环境略有变化。

编译运行

终端 1：创建虚拟串口。

socat -d -d pty,raw,echo=0 pty,raw,echo=0

终端 2：运行程序。

g++ demo3_async_serial_read.cpp -o demo3_async_serial_read -std=c++17 -lboost_system -pthread
./demo3_async_serial_read /dev/pts/3

终端 3：发送数据。

echo "encoder 123" > /dev/pts/4

运行输出与时间顺序

程序立刻输出：

main：注册 async_read_until
main：async_read_until 已返回，准备 io.run()

程序卡在 io.run()。你发送数据后，程序输出：

on_read_line：bytes_transferred = 12
on_read_line：收到一行 = encoder 123
main：io.run() 返回

完整输出类似：

main：注册 async_read_until
main：async_read_until 已返回，准备 io.run()
on_read_line：bytes_transferred = 12
on_read_line：收到一行 = encoder 123
main：io.run() 返回

本示例需要注意的点

async_read_until() 不阻塞。它只是注册读取任务。

如果你不调用：

io.run();

回调函数永远不会执行。

回调参数说明

async_read_until() 的回调一般接收两个参数：

const boost::system::error_code& ec
std::size_t bytes_transferred

所以绑定时用：

std::placeholders::_1
std::placeholders::_2

我们额外传了：

&buffer

用于在回调里取出具体字符串。

示例 4：类里封装异步串口行读取

程序目标

把异步串口读取封装成类。这个结构更接近真实机器人项目。

程序会连续读取多行串口数据，每收到一行就打印，然后继续注册下一次读取。

完整代码

#include <boost/asio.hpp>
#include <boost/system/error_code.hpp>
#include <functional>
#include <iostream>
#include <istream>
#include <string>

class SerialLineReader
{
public:
    SerialLineReader(boost::asio::io_context& io, const std::string& port_name)
        : serial_(io)
    {
        boost::system::error_code ec;

        serial_.open(port_name, ec);
        if (ec)
        {
            std::cout << "打开串口失败：" << ec.message() << std::endl;
            return;
        }

        serial_.set_option(boost::asio::serial_port_base::baud_rate(115200));
        serial_.set_option(boost::asio::serial_port_base::character_size(8));
        serial_.set_option(boost::asio::serial_port_base::parity(
            boost::asio::serial_port_base::parity::none));
        serial_.set_option(boost::asio::serial_port_base::stop_bits(
            boost::asio::serial_port_base::stop_bits::one));
        serial_.set_option(boost::asio::serial_port_base::flow_control(
            boost::asio::serial_port_base::flow_control::none));

        std::cout << "SerialLineReader：串口打开成功，开始异步读取" << std::endl;

        start_read();
    }

private:
    void start_read()
    {
        boost::asio::async_read_until(serial_,
                                      buffer_,
                                      '\n',
                                      std::bind(&SerialLineReader::on_read,
                                                this,
                                                std::placeholders::_1,
                                                std::placeholders::_2));
    }

    void on_read(const boost::system::error_code& ec, std::size_t bytes_transferred)
    {
        if (ec)
        {
            std::cout << "SerialLineReader::on_read 错误：" << ec.message() << std::endl;
            return;
        }

        std::istream is(&buffer_);
        std::string line;
        std::getline(is, line);

        std::cout << "收到串口行，bytes = " << bytes_transferred
                  << "，内容 = " << line << std::endl;

        start_read();
    }

private:
    // serial_port 表示串口设备，后续读写都通过它完成。
    boost::asio::serial_port serial_;
    boost::asio::streambuf buffer_;
};

int main(int argc, char* argv[])
{
    // 程序从 main 函数开始执行，argc/argv 用来接收命令行参数。
    std::string port_name = "/dev/pts/3";

    if (argc >= 2)
    {
        port_name = argv[1];
    }

    // io_context 是 Asio 的事件循环对象，异步任务需要靠它调度。
    boost::asio::io_context io;
    SerialLineReader reader(io, port_name);

    std::cout << "main：调用 io.run()，按 Ctrl+C 退出" << std::endl;

    // 启动事件循环，前面注册的异步任务会在这里被调度执行。
    io.run();

    std::cout << "main：io.run() 返回" << std::endl;

    return 0;
}

运行结果：见下方“运行输出与时间顺序”；如果示例涉及定时器、线程、网络或外部设备，具体时间和顺序可能会随环境略有变化。

编译运行

终端 1：创建虚拟串口。

socat -d -d pty,raw,echo=0 pty,raw,echo=0

终端 2：运行程序。

g++ demo4_serial_class_reader.cpp -o demo4_serial_class_reader -std=c++17 -lboost_system -pthread
./demo4_serial_class_reader /dev/pts/3

终端 3：连续发送数据。

echo "imu 1 2 3" > /dev/pts/4
echo "odom 0.1 0.2" > /dev/pts/4
echo "battery 24.1" > /dev/pts/4

运行输出与时间顺序

程序启动后输出：

SerialLineReader：串口打开成功，开始异步读取
main：调用 io.run()，按 Ctrl+C 退出

每发送一行，程序打印一行：

收到串口行，bytes = 10，内容 = imu 1 2 3
收到串口行，bytes = 13，内容 = odom 0.1 0.2
收到串口行，bytes = 13，内容 = battery 24.1

程序不会自动退出，因为每次收到一行后都会重新调用 start_read()。

本示例需要注意的点

这一句是连续读取的关键：

start_read();

它在 on_read() 的最后再次注册下一次异步读取。

如果没有这句，程序只会读一行，然后 io.run() 就会返回。

类成员变量生命周期说明

boost::asio::serial_port serial_;
boost::asio::streambuf buffer_;

它们是类成员变量，生命周期和 SerialLineReader reader 一样长。

这比在局部函数里创建临时 buffer 更安全。

成员函数绑定说明

std::bind(&SerialLineReader::on_read,
          this,
          std::placeholders::_1,
          std::placeholders::_2)

表示异步读取完成后调用：

this->on_read(ec, bytes_transferred);

示例 5：类里封装异步串口写队列

程序目标

真实机器人上位机经常需要连续给下位机发命令，例如：

cmd_vel 0.2 0.0
cmd_vel 0.2 0.1
cmd_vel 0.0 0.0

异步写时不能随便多个 async_write() 同时写同一个串口。更稳的做法是写队列：

如果当前没有写操作，就开始写
如果正在写，就先放入队列
当前写完后，再写下一条

完整代码

#include <boost/asio.hpp>
#include <boost/system/error_code.hpp>
#include <deque>
#include <functional>
#include <iostream>
#include <string>

class SerialWriter
{
public:
    SerialWriter(boost::asio::io_context& io, const std::string& port_name)
        : serial_(io)
    {
        boost::system::error_code ec;
        serial_.open(port_name, ec);
        if (ec)
        {
            std::cout << "打开串口失败：" << ec.message() << std::endl;
            return;
        }

        serial_.set_option(boost::asio::serial_port_base::baud_rate(115200));
        std::cout << "SerialWriter：串口打开成功" << std::endl;
    }

    void async_send(const std::string& msg)
    {
        bool writing = !write_queue_.empty();

        write_queue_.push_back(msg);

        std::cout << "加入发送队列：" << msg;

        if (!writing)
        {
            do_write();
        }
    }

private:
    void do_write()
    {
        // 注册异步写入，写完后由回调通知结果。
        boost::asio::async_write(serial_,
                                 boost::asio::buffer(write_queue_.front()),
                                 std::bind(&SerialWriter::on_write,
                                           this,
                                           std::placeholders::_1,
                                           std::placeholders::_2));
    }

    void on_write(const boost::system::error_code& ec, std::size_t bytes_transferred)
    {
        if (ec)
        {
            std::cout << "发送失败：" << ec.message() << std::endl;
            return;
        }

        std::cout << "发送完成，字节数 = " << bytes_transferred << std::endl;

        write_queue_.pop_front();

        if (!write_queue_.empty())
        {
            do_write();
        }
    }

private:
    boost::asio::serial_port serial_;
    std::deque<std::string> write_queue_;
};

int main(int argc, char* argv[])
{
    // 程序从 main 函数开始执行，argc/argv 用来接收命令行参数。
    std::string port_name = "/dev/pts/3";

    if (argc >= 2)
    {
        port_name = argv[1];
    }

    // io_context 是 Asio 的事件循环对象，异步任务需要靠它调度。
    boost::asio::io_context io;
    SerialWriter writer(io, port_name);

    writer.async_send("cmd_vel 0.2 0.0\n");
    writer.async_send("cmd_vel 0.2 0.1\n");
    writer.async_send("cmd_vel 0.0 0.0\n");

    // 启动事件循环，前面注册的异步任务会在这里被调度执行。
    io.run();

    std::cout << "main：发送队列清空，程序结束" << std::endl;

    return 0;
}

运行结果：见下方“运行输出与时间顺序”；如果示例涉及定时器、线程、网络或外部设备，具体时间和顺序可能会随环境略有变化。

编译运行

终端 1：创建虚拟串口。

socat -d -d pty,raw,echo=0 pty,raw,echo=0

终端 2：监听另一端。

cat /dev/pts/4

终端 3：运行程序。

g++ demo5_serial_write_queue.cpp -o demo5_serial_write_queue -std=c++17 -lboost_system -pthread
./demo5_serial_write_queue /dev/pts/3

运行输出与时间顺序

程序终端输出类似：

SerialWriter：串口打开成功
加入发送队列：cmd_vel 0.2 0.0
加入发送队列：cmd_vel 0.2 0.1
加入发送队列：cmd_vel 0.0 0.0
发送完成，字节数 = 16
发送完成，字节数 = 16
发送完成，字节数 = 16
main：发送队列清空，程序结束

监听终端输出：

cmd_vel 0.2 0.0
cmd_vel 0.2 0.1
cmd_vel 0.0 0.0

本示例需要注意的点

这里不能把 msg 做成临时局部变量后立刻异步写，因为异步写可能还没完成，数据已经销毁。

本例用：

std::deque<std::string> write_queue_;

保存待发送数据，保证 buffer 指向的字符串在写完成之前一直存在。

async_write() 说明

boost::asio::async_write(serial_, buffer, handler);

作用：异步写完整个 buffer。

回调参数：

const boost::system::error_code& ec
std::size_t bytes_transferred

返回值：void。

本节总结

  1. 同步串口读写简单，但会阻塞。
  2. 异步串口读写需要 io.run() 驱动。
  3. async_read_until() 适合读取以换行结尾的文本协议。
  4. 二进制协议更适合 async_read_some() 加自己的帧解析器。
  5. 异步写必须注意 buffer 生命周期。
  6. 工程里推荐把串口读写封装成类，并用队列管理发送数据。
音乐页