{"id":15047552,"url":"https://github.com/gbmhunter/cpplinuxserial","last_synced_at":"2025-04-04T18:09:15.211Z","repository":{"id":17042062,"uuid":"19806399","full_name":"gbmhunter/CppLinuxSerial","owner":"gbmhunter","description":"Serial port library written in C++.","archived":false,"fork":false,"pushed_at":"2024-06-02T08:32:40.000Z","size":114,"stargazers_count":378,"open_issues_count":11,"forks_count":122,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-29T21:01:38.869Z","etag":null,"topics":["baud-rate","c-plus-plus","com-port","cpp","cpp14","linux","serial-ports","tty"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gbmhunter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-05-15T04:40:38.000Z","updated_at":"2024-10-25T01:26:25.000Z","dependencies_parsed_at":"2023-01-13T19:07:40.949Z","dependency_job_id":"24a0eb32-fbd7-4f11-876b-d080236afd59","html_url":"https://github.com/gbmhunter/CppLinuxSerial","commit_stats":{"total_commits":67,"total_committers":16,"mean_commits":4.1875,"dds":0.5522388059701493,"last_synced_commit":"4bd338e378823e280c84020c0f34a4ab8dbcee96"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbmhunter%2FCppLinuxSerial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbmhunter%2FCppLinuxSerial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbmhunter%2FCppLinuxSerial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gbmhunter%2FCppLinuxSerial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gbmhunter","download_url":"https://codeload.github.com/gbmhunter/CppLinuxSerial/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247226215,"owners_count":20904465,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["baud-rate","c-plus-plus","com-port","cpp","cpp14","linux","serial-ports","tty"],"created_at":"2024-09-24T21:00:04.618Z","updated_at":"2025-04-04T18:09:15.176Z","avatar_url":"https://github.com/gbmhunter.png","language":"C++","readme":"# CppLinuxSerial\r\n\r\nLinux serial port library written in C++.\r\n\r\n[![CMake](https://github.com/gbmhunter/CppLinuxSerial/actions/workflows/cmake.yml/badge.svg)](https://github.com/gbmhunter/CppLinuxSerial/actions/workflows/cmake.yml)\r\n\r\n## Description\r\n\r\nLibrary for communicating with COM ports on a Linux system.\r\n\r\n* Simple API\r\n* Supports custom baud rates\r\n* `cmake` based build system\r\n\r\n## Installation\r\n\r\n### Linux, MacOS, Windows\r\n\r\n1. Make sure you have `cmake` installed.\r\n\r\n1. Clone the git repo onto your local storage.\r\n\r\n1. Change into root repo directory:\r\n\r\n\t```\r\n\t$ cd CppLinuxSerial\r\n\t```\r\n\r\n1. Create a new build directory and change into it:\r\n\r\n\t```bash\r\n\t$ mkdir build\r\n\t$ cd build\r\n\t```\r\n\r\n1. Run cmake on the parent directory to generate makefile:\r\n\r\n\t```bash\r\n\t$ cmake ..\r\n\t```\r\n\r\n1. Run make on the generated makefile to generate the static library `libCppLinuxSerial.a` and an unit test executable:\r\n\r\n\t```bash\r\n\t$ make\r\n\t```\r\n\r\n1. To install the headers on your system:\r\n\r\n\t```bash\r\n\t$ sudo make install\r\n\t```\r\n\r\n1. To run the unit tests:\r\n\r\n\t```bash\r\n\t$ make run_unit_tests\r\n\t```\r\n\r\n\tNOTE: The unit tests used to use virtual serial ports via `stty` on Linux to do more thorough testing. I ran into permission problems running stty on TravisCI after they did an update and had to remove tests (leaving almost no tests remaining). If anyone wants to add better unit tests, it is greatly welcomed! \r\n\r\n## Using This Project As A CMake Dependency\r\n\r\nThis project uses CMake and the export feature, so in a downstream CMake project that uses CppLinuxSerial as a dependency you should just be able to do this (thanks to https://github.com/borgmanJeremy for this contribution):\r\n\r\n```cmake\r\nfind_package(CppLinuxSerial REQUIRED)\r\n...\r\n...\r\ntarget_link_libraries(target CppLinuxSerial::CppLinuxSerial)\r\n```\r\n\r\n## Examples\r\n\r\n```c++\r\n#include \u003cCppLinuxSerial/SerialPort.hpp\u003e\r\n\r\nusing namespace mn::CppLinuxSerial;\r\n\r\nint main() {\r\n\t// Create serial port object and open serial port at 57600 baud, 8 data bits, no parity bit, one stop bit (8n1),\r\n\t// and no flow control\r\n\tSerialPort serialPort(\"/dev/ttyUSB0\", BaudRate::B_57600, NumDataBits::EIGHT, Parity::NONE, NumStopBits::ONE);\r\n\t// Use SerialPort serialPort(\"/dev/ttyACM0\", 13000); instead if you want to provide a custom baud rate\r\n\tserialPort.SetTimeout(100); // Block for up to 100ms to receive data\r\n\tserialPort.Open();\r\n\r\n\t// WARNING: If using the Arduino Uno or similar, you may want to delay here, as opening the serial port causes\r\n\t// the micro to reset!\r\n\r\n\t// Write some ASCII data\r\n\tserialPort.Write(\"Hello\");\r\n\r\n\t// Read some data back (will block for up to 100ms due to the SetTimeout(100) call above)\r\n\tstd::string readData;\r\n\tserialPort.Read(readData);\r\n\tstd::cout \u003c\u003c \"Read data = \\\"\" \u003c\u003c readData \u003c\u003c \"\\\"\" \u003c\u003c std::endl;\r\n\r\n\t// Close the serial port\r\n\tserialPort.Close();\r\n}\r\n```\r\n\r\nIf the above code was in a file called `main.cpp` and you had installed `CppLinuxSerial` following the instructions above, on a Linux system you should be able to compile the example application with:\r\n\r\n```bash\r\ng++ main.cpp -lCppLinuxSerial\r\n```\r\n\r\nIf you wanted to enable flow control (hardware or software flow control), you can add it onto the end of the constructor as shown below. If you don't set them, they both default to OFF (the most common setting).\r\n\r\n```c++\r\n// Enabling hardware flow control\r\nSerialPort serialPort(\"/dev/ttyUSB0\", BaudRate::B_57600, NumDataBits::EIGHT, Parity::NONE, NumStopBits::ONE, HardwareFlowControl::ON, SoftwareFlowControl::OFF);\r\n```\r\n\r\nIf you want to read and write binary rather than strings, you can use `WriteBinary()` and `ReadBinary()` which take vectors of bytes rather than `std::string`:\r\n\r\n```c++\r\nserialPort.WriteBinary(const std::vector\u003cuint8_t\u003e\u0026 data);\r\nserialPort.ReadBinary(std::vector\u003cuint8_t\u003e\u0026 data);\r\n```\r\n\r\nFor more examples, see the files in `test/`.\r\n\r\n## Issues\r\n\r\nSee GitHub Issues.\r\n\t\r\n## FAQ\r\n\r\n1. I get the error `Could not open device \"/dev/ttyACM0\". Is the device name correct and do you have read/write permissions?`, but the device is definitely there. You typically have to add your user to the `dialout` group before you can access `tty` devices.\r\n\r\n1. My code stalls when calling functions like `SerialPort::Read()`. This is probably because the library is set up to do a blocking read, and not enough characters have been received to allow `SerialPort::Read()` to return. Call `SerialPort::SetTimeout(0)` before the serial port is open to set a non-blocking mode.\r\n\r\n## WSL\r\n\r\nIf you want to use this library in WSL, you'll have to use usbipd to pass-through the USB device.\r\n\r\n```\r\nusbipd wsl list\r\n```\r\n\r\n```powershell\r\n$ usbipd wsl list\r\nBUSID  VID:PID    DEVICE                                                        STATE\r\n1-1    046d:c332  USB Input Device                                              Not attached\r\n1-4    13d3:5666  USB2.0 HD UVC WebCam                                          Not attached\r\n1-5    2341:0043  Arduino Uno (COM4)                                            Not attached\r\n1-6    046d:0a9c  Logitech G432 Gaming Headset, USB Input Device                Not attached\r\n1-8    0b05:1837  USB Input Device                                              Not attached\r\n1-9    8087:0a2a  Intel(R) Wireless Bluetooth(R)                                Not attached\r\n```\r\n\r\nAttaching the Arduino Uno (need to be done with Admin priviliges the first time around):\r\n\r\n```\r\nusbipd wsl attach --busid=1-5\r\n```\r\n\r\n`/dev/ttyACM0` now appears inside WSL, and you can use `CppLinuxSerial` with this device like usual.\r\n\r\nNOTE: Sometimes `/dev/ttyACM0` is not part of the dialout group, so even with your user being part of that group, you will get permission denied errors when trying to access the serial port. Sometimes using `chmod` to change the permissions works:\r\n\r\n```\r\nsudo chmod 666 /dev/ttyACM0 \r\n```\r\n\r\n## Tests\r\n\r\nSerial port testing cannot really be done easily on cloud-based CICD platforms, as serial ports and devices connected to these ports are not readily available (nor configurable). `CppLinuxSerial` relies on running tests manually on your local Linux OS, alongside a connected Arduino Uno configured to echo serial data back (at a later data this could be reconfigured to cycle through tests at different baud rates, parity settings, e.t.c).\r\n\r\n### Prerequisites\r\n\r\nYou will need:\r\n\r\n* Arduino Uno (or equivalent) dev kit.\r\n* Linux OS.\r\n\r\nInstall the arduino-cli as per https://arduino.github.io/arduino-cli/0.21/installation/ on your local Linux machine.\r\n\r\nInstall the `arduino:avr` platform:\r\n\r\n```\r\n$ arduino-cli core install arduino:avr\r\n```\r\n\r\nMake sure Arduino board is detected with:\r\n\r\n```\r\n$ arduino-cli board list\r\n```\r\n\r\n### Running\r\n\r\nRun the following bash script:\r\n\r\n```\r\n./test/arduino/run.sh \r\n```\r\n\r\nThis script will:\r\n\r\n1. Build and install `CppLinuxSerial` onto your local Linux OS.\r\n1. Build and upload the test Arduino firmware to the connected Arduino Uno (it assumes it's connected to `/dev/ttyACM0`).\r\n1. Build and run the test C++ application. This sends serial data to the Uno via CppLinuxSerial and expects the data to be echoed back.\r\n\r\n## Changelog\r\n\r\nSee CHANGELOG.md.\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbmhunter%2Fcpplinuxserial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgbmhunter%2Fcpplinuxserial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgbmhunter%2Fcpplinuxserial/lists"}