CSerialPort - 现代C++跨平台串口通信库

简介

CSerialPort 是一个使用现代 C++17 编写的跨平台串口通信库，支持 Windows 和 Linux 操作系统。本库提供了简洁易用的 API，支持同步和异步操作，以及回调机制。

特性

现代 C++17 - 使用最新的 C++ 特性，如 std::optional、std::variant、智能指针等
跨平台支持 - 同时支持 Windows 和 Linux
线程安全 - 内置互斥锁保护，原子操作统计信息，支持多线程环境
异步操作 - 支持 std::future 异步读写
回调机制 - 支持数据接收、事件和错误回调
RAII 资源管理 - 自动管理串口资源，防止泄漏
统计信息 - 线程安全的收发字节数和错误统计
灵活配置 - 支持各种波特率、数据位、停止位、校验位和流控制
控制线操作 - 支持 DTR/RTS 设置和 CTS/DSR/CD/RI 读取
Break 信号 - 支持发送 Break 信号

版本历史

版本	日期	说明
3.0.0	2026-01-01	使用现代C++17重写，支持跨平台
2.0.0	2014-01-10	添加串口枚举功能
1.0.0	1997-09-15	初始版本

快速开始

编译要求

C++17 兼容的编译器
- GCC 7+
- Clang 5+
- MSVC 2017+
CMake 3.14+
Windows: Windows SDK
Linux: 无额外依赖

编译

mkdir build && cd build
cmake .. -DCSERIALPORT_BUILD_EXAMPLES=ON -DCSERIALPORT_BUILD_TESTS=ON
cmake --build .

# 运行测试
cmake --build . --target run_tests

CMake 选项

选项	默认值	说明
`CSERIALPORT_BUILD_SHARED`	ON	构建动态库
`CSERIALPORT_BUILD_STATIC`	ON	构建静态库
`CSERIALPORT_BUILD_EXAMPLES`	ON	构建示例程序
`CSERIALPORT_BUILD_TESTS`	OFF	构建单元测试

基本使用

#include "SerialPort.h"
#include <iostream>

int main() {
    // 创建串口对象
    csp::SerialPort port;

    // 打开串口（Windows: "COM1", Linux: "/dev/ttyUSB0"）
    auto result = port.open("COM1", csp::SerialConfig::config_115200_8N1());

    if (!result) {
        std::cerr << "打开串口失败: " << result.errorMessage() << std::endl;
        return 1;
    }

    // 发送数据
    std::string message = "Hello, Serial Port!";
    auto writeResult = port.write(message);

    if (writeResult) {
        std::cout << "发送了 " << writeResult.value() << " 字节" << std::endl;
    }

    // 接收数据
    auto readResult = port.read(100);

    if (readResult) {
        auto& data = readResult.value();
        std::cout << "接收了 " << data.size() << " 字节" << std::endl;
    }

    // 串口会在析构时自动关闭
    return 0;
}

API 参考

命名空间

所有类型和函数都在 csp 命名空间中。

枚举类型

BaudRate - 波特率

enum class BaudRate : uint32_t {
    BR_110    = 110,
    BR_300    = 300,
    BR_600    = 600,
    BR_1200   = 1200,
    BR_2400   = 2400,
    BR_4800   = 4800,
    BR_9600   = 9600,
    BR_14400  = 14400,
    BR_19200  = 19200,
    BR_38400  = 38400,
    BR_57600  = 57600,
    BR_115200 = 115200,
    BR_230400 = 230400,
    BR_460800 = 460800,
    BR_921600 = 921600,
    Custom    = 0  // 自定义波特率
};

DataBits - 数据位

enum class DataBits : uint8_t {
    Five  = 5,
    Six   = 6,
    Seven = 7,
    Eight = 8
};

StopBits - 停止位

enum class StopBits : uint8_t {
    One     = 1,
    OneHalf = 2,  // 仅Windows支持
    Two     = 3
};

Parity - 校验位

enum class Parity : uint8_t {
    None  = 0,
    Odd   = 1,
    Even  = 2,
    Mark  = 3,  // 仅Windows支持
    Space = 4   // 仅Windows支持
};

FlowControl - 流控制

enum class FlowControl : uint8_t {
    None     = 0,
    Hardware = 1,  // RTS/CTS
    Software = 2   // XON/XOFF
};

SerialConfig - 配置结构体

struct SerialConfig {
    BaudRate baudRate = BaudRate::BR_9600;
    DataBits dataBits = DataBits::Eight;
    StopBits stopBits = StopBits::One;
    Parity parity = Parity::None;
    FlowControl flowControl = FlowControl::None;
    uint32_t customBaudRate = 0;
    Duration readTimeout = Duration(1000);
    Duration writeTimeout = Duration(1000);
    size_t readBufferSize = 4096;
    size_t writeBufferSize = 4096;

    // 便捷工厂方法
    static SerialConfig defaultConfig();
    static SerialConfig config_9600_8N1();
    static SerialConfig config_115200_8N1();
};

SerialPort - 主类

构造函数

SerialPort();  // 默认构造

注意: 使用 open() 方法打开串口，构造函数不会自动打开串口。

静态方法

// 枚举系统中的所有串口
static std::vector<PortInfo> enumerate();

// 检查串口是否存在
static bool exists(const std::string& portName);

// 获取库版本
static std::string version();

打开/关闭

VoidResult open(const std::string& portName, const SerialConfig& config);
VoidResult close();
bool isOpen() const;

配置

SerialConfig config() const;
VoidResult setConfig(const SerialConfig& config);
VoidResult setBaudRate(BaudRate baudRate);
VoidResult setDataBits(DataBits dataBits);
VoidResult setStopBits(StopBits stopBits);
VoidResult setParity(Parity parity);
VoidResult setFlowControl(FlowControl flowControl);
VoidResult setReadTimeout(Duration timeout);
VoidResult setWriteTimeout(Duration timeout);

同步读取

// 读取最多 maxBytes 字节
Result<ByteBuffer> read(size_t maxBytes, std::optional<Duration> timeout = std::nullopt);

// 精确读取 exactBytes 字节
Result<ByteBuffer> readExact(size_t exactBytes, std::optional<Duration> timeout = std::nullopt);

// 读取直到遇到分隔符
Result<ByteBuffer> readUntil(Byte delimiter, size_t maxBytes = 4096,
                              std::optional<Duration> timeout = std::nullopt);

// 读取一行
Result<std::string> readLine(size_t maxBytes = 4096,
                              std::optional<Duration> timeout = std::nullopt);

同步写入

Result<size_t> write(const Byte* data, size_t size, std::optional<Duration> timeout = std::nullopt);
Result<size_t> write(const ByteBuffer& data, std::optional<Duration> timeout = std::nullopt);
Result<size_t> write(const std::string& str, std::optional<Duration> timeout = std::nullopt);
Result<size_t> writeLine(const std::string& line, std::optional<Duration> timeout = std::nullopt);

异步操作

std::future<Result<ByteBuffer>> readAsync(size_t maxBytes);
std::future<Result<size_t>> writeAsync(ByteBuffer data);
std::future<Result<size_t>> writeAsync(std::string str);

回调模式

void setDataCallback(DataCallback callback);
void setEventCallback(EventCallback callback);
void setErrorCallback(ErrorCallback callback);
VoidResult startAsyncReceive();
void stopAsyncReceive();
bool isAsyncReceiving() const;

缓冲区操作

Result<size_t> available() const;  // 获取可读字节数
VoidResult flushInput();           // 清空接收缓冲区
VoidResult flushOutput();          // 清空发送缓冲区
VoidResult flush();                // 清空所有缓冲区

控制线

// 设置控制线
VoidResult setDTR(bool state);
VoidResult setRTS(bool state);

// 读取控制线状态
Result<bool> getCTS() const;
Result<bool> getDSR() const;
Result<bool> getCD() const;
Result<bool> getRI() const;

// 发送 Break 信号
VoidResult sendBreak(Duration duration = Duration(250));

状态和统计

std::string portName() const;
PortStatistics statistics() const;
void resetStatistics();

PortStatistics - 统计信息（线程安全）

struct PortStatistics {
    std::atomic<uint64_t> bytesReceived{0};
    std::atomic<uint64_t> bytesSent{0};
    std::atomic<uint64_t> readErrors{0};
    std::atomic<uint64_t> writeErrors{0};

    // 便捷获取方法
    uint64_t getBytesReceived() const noexcept;
    uint64_t getBytesSent() const noexcept;
    uint64_t getReadErrors() const noexcept;
    uint64_t getWriteErrors() const noexcept;

    // 时间相关方法
    Duration getUptime() const noexcept;              // 获取运行时长
    Duration getLastActivityOffset() const noexcept;  // 获取最后活动时间偏移
    Duration getTimeSinceLastActivity() const noexcept; // 获取自最后活动以来的时间

    void reset() noexcept;
};

使用示例

示例1：枚举串口

#include "SerialPort.h"
#include <iostream>

int main() {
    auto ports = csp::SerialPort::enumerate();

    std::cout << "发现 " << ports.size() << " 个串口:" << std::endl;

    for (const auto& port : ports) {
        std::cout << "  " << port.portName;
        if (!port.description.empty()) {
            std::cout << " - " << port.description;
        }
        std::cout << (port.isAvailable ? " (可用)" : " (占用)") << std::endl;
    }

    return 0;
}

示例2：异步接收

#include "SerialPort.h"
#include <iostream>
#include <thread>
#include <chrono>

int main() {
    csp::SerialPort port;

    if (!port.open("COM1", csp::SerialConfig::config_115200_8N1())) {
        std::cerr << "打开串口失败" << std::endl;
        return 1;
    }

    // 设置数据接收回调
    port.setDataCallback([](const csp::Byte* data, size_t size) {
        std::cout << "收到 " << size << " 字节: ";
        for (size_t i = 0; i < size; ++i) {
            std::cout << std::hex << static_cast<int>(data[i]) << " ";
        }
        std::cout << std::endl;
    });

    // 设置错误回调
    port.setErrorCallback([](csp::ErrorCode error, const std::string& message) {
        std::cerr << "错误: " << message << std::endl;
    });

    // 启动异步接收
    port.startAsyncReceive();

    // 主线程等待
    std::cout << "按 Enter 键退出..." << std::endl;
    std::cin.get();

    // 停止异步接收
    port.stopAsyncReceive();

    return 0;
}

示例3：使用 Future 异步操作

#include "SerialPort.h"
#include <iostream>
#include <future>

int main() {
    csp::SerialPort port;

    if (!port.open("COM1", csp::SerialConfig::config_115200_8N1())) {
        return 1;
    }

    // 异步发送
    auto writeFuture = port.writeAsync("Hello, World!");

    // 异步接收
    auto readFuture = port.readAsync(100);

    // 等待发送完成
    auto writeResult = writeFuture.get();
    if (writeResult) {
        std::cout << "发送了 " << writeResult.value() << " 字节" << std::endl;
    }

    // 等待接收完成
    auto readResult = readFuture.get();
    if (readResult) {
        std::cout << "接收了 " << readResult.value().size() << " 字节" << std::endl;
    }

    return 0;
}

示例4：控制线操作

#include "SerialPort.h"
#include <iostream>

int main() {
    csp::SerialPort port;

    if (!port.open("COM1", csp::SerialConfig::config_115200_8N1())) {
        return 1;
    }

    // 设置 DTR 和 RTS
    port.setDTR(true);
    port.setRTS(true);

    // 读取控制线状态
    auto cts = port.getCTS();
    auto dsr = port.getDSR();
    auto cd = port.getCD();
    auto ri = port.getRI();

    if (cts) std::cout << "CTS: " << (cts.value() ? "高" : "低") << std::endl;
    if (dsr) std::cout << "DSR: " << (dsr.value() ? "高" : "低") << std::endl;
    if (cd)  std::cout << "CD:  " << (cd.value() ? "高" : "低") << std::endl;
    if (ri)  std::cout << "RI:  " << (ri.value() ? "高" : "低") << std::endl;

    // 发送 Break 信号
    port.sendBreak(csp::Duration(500));  // 500ms

    return 0;
}

示例5：自定义配置

#include "SerialPort.h"

int main() {
    csp::SerialPort port;

    // 创建自定义配置
    csp::SerialConfig config;
    config.baudRate = csp::BaudRate::BR_38400;
    config.dataBits = csp::DataBits::Seven;
    config.stopBits = csp::StopBits::Two;
    config.parity = csp::Parity::Even;
    config.flowControl = csp::FlowControl::Hardware;
    config.readTimeout = csp::Duration(2000);  // 2秒超时
    config.writeTimeout = csp::Duration(2000);

    if (!port.open("COM1", config)) {
        return 1;
    }

    // 动态修改配置
    port.setBaudRate(csp::BaudRate::BR_115200);

    return 0;
}

错误处理

本库使用 Result<T> 类型进行错误处理，类似于 Rust 的 Result 或 C++23 的 std::expected。

auto result = port.read(100);

if (result) {
    // 成功
    auto& data = result.value();
    // 或使用 *result
} else {
    // 失败
    std::cerr << "错误码: " << static_cast<int>(result.error()) << std::endl;
    std::cerr << "错误信息: " << result.errorMessage() << std::endl;
}

// 使用 valueOr 提供默认值
auto data = result.valueOr(csp::ByteBuffer{});

错误码

错误码	说明
Success	成功
InvalidParameter	无效参数
NotOpen	串口未打开
AlreadyOpen	串口已打开
Timeout	操作超时
OpenFailed	打开失败
PortNotFound	串口不存在
PermissionDenied	权限不足
PortBusy	串口被占用
ConfigFailed	配置失败
ReadFailed	读取失败
WriteFailed	写入失败

平台特定说明

Windows

串口名称格式：COM1, COM2, ... COM256
支持 1.5 停止位
支持 Mark 和 Space 校验
使用 SetupAPI 高效枚举串口（获取设备描述和硬件ID）
使用 Overlapped I/O 实现异步操作

Linux

串口名称格式：/dev/ttyS0, /dev/ttyUSB0, /dev/ttyACM0 等
不支持 1.5 停止位（会返回 InvalidParameter 错误）
不支持 Mark 和 Space 校验（会返回 InvalidParameter 错误）
使用 select() 实现超时控制
自定义波特率需要系统支持

线程安全

所有公共方法都是线程安全的
可以在多个线程中同时调用读写方法
PortStatistics 使用原子操作，可安全地在多线程中访问
回调函数在内部线程中执行，请注意同步

示例程序

编译后的示例程序位于 build/bin/examples/ 目录：

# 基本使用示例
./example_basic [端口名] [波特率]
./example_basic COM1 115200

# 串口枚举示例
./example_enumerate [-v]

# 异步接收示例
./example_async [端口名] [波特率]

单元测试

# 构建测试
cmake .. -DCSERIALPORT_BUILD_TESTS=ON
cmake --build .

# 运行测试
cmake --build . --target run_tests
# 或
ctest --output-on-failure

许可证

本项目采用 MIT 许可证。详见 LICENSE 文件。

贡献

欢迎提交 Issue 和 Pull Request！

联系方式

作者：CSerialPort Team
博客：https://blog.csdn.net/liquanhai

Name		Name	Last commit message	Last commit date
cmake		cmake
examples		examples
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
CMakeLists.txt		CMakeLists.txt
README.md		README.md
SerialPort.cpp		SerialPort.cpp
SerialPort.h		SerialPort.h

Latest commit

History

Folders and files

Repository files navigation