{"id":24739471,"url":"https://github.com/bang-olufsen/hdlcpp","last_synced_at":"2025-06-17T07:32:49.927Z","repository":{"id":37468120,"uuid":"150698982","full_name":"bang-olufsen/hdlcpp","owner":"bang-olufsen","description":"A header-only C++11 framing protocol optimized for embedded communication","archived":false,"fork":false,"pushed_at":"2024-10-04T11:52:36.000Z","size":95,"stargazers_count":23,"open_issues_count":2,"forks_count":7,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-03T18:09:13.549Z","etag":null,"topics":["communication","cpp","cpp11","hdlc","protocol","python","serial"],"latest_commit_sha":null,"homepage":"","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/bang-olufsen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2018-09-28T07:00:11.000Z","updated_at":"2025-01-11T23:40:36.000Z","dependencies_parsed_at":"2024-07-10T11:38:10.809Z","dependency_job_id":null,"html_url":"https://github.com/bang-olufsen/hdlcpp","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"purl":"pkg:github/bang-olufsen/hdlcpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bang-olufsen%2Fhdlcpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bang-olufsen%2Fhdlcpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bang-olufsen%2Fhdlcpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bang-olufsen%2Fhdlcpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bang-olufsen","download_url":"https://codeload.github.com/bang-olufsen/hdlcpp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bang-olufsen%2Fhdlcpp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260313847,"owners_count":22990484,"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":["communication","cpp","cpp11","hdlc","protocol","python","serial"],"created_at":"2025-01-27T22:58:46.239Z","updated_at":"2025-06-17T07:32:49.879Z","avatar_url":"https://github.com/bang-olufsen.png","language":"C++","readme":"# hdlcpp\n![Github Build](https://github.com/bang-olufsen/hdlcpp/workflows/build/badge.svg) [![codecov](https://codecov.io/gh/bang-olufsen/hdlcpp/branch/master/graph/badge.svg)](https://codecov.io/gh/bang-olufsen/hdlcpp) [![License](https://img.shields.io/badge/license-MIT_License-blue.svg?style=flat)](LICENSE)\n\nHdlcpp is a header-only C++11 framing protocol optimized for embedded communication. It uses the [HDLC](https://en.wikipedia.org/wiki/High-Level_Data_Link_Control) asynchronous framing format for handling data integrity and retransmissions. Hdlcpp is the successor of the [yahdlc](https://github.com/bang-olufsen/yahdlc) implementation written in C.\n\n## Usage\n\nHdlcpp requires that a transport read and write function is supplied as e.g. a [lambda expression](https://en.cppreference.com/w/cpp/language/lambda) for the actual data transport. Hereby Hdlcpp can easily be integrated e.g. with different UART implementations. It requires a read and write buffer. The buffer type must to compatible with [std::span](https://en.cppreference.com/w/cpp/container/span), basically any contiguous sequence containers. The buffers can be size independent for encoding/decoding data, write timeout and number of write retries are also configurable when constructing the instance.\n\n```cpp\nhdlcpp = std::make_shared\u003cHdlcpp::Hdlcpp\u003e(\n    [this](std::span\u003cuint8_t\u003e buffer) { return serial-\u003eread(buffer); },\n    [this](const std::span\u003cconst uint8_t\u003e buffer) { return serial-\u003ewrite(buffer); },\n    readBuffer, writeBuffer, writeTimeout, writeRetries);\n```\n\nIn the case where the underlying transport layer does not support `std::span`, the pointer to the first element and the size can be extracted from the span like so.\n```cpp\nhdlcpp = std::make_shared\u003cHdlcpp::Hdlcpp\u003e(\n    [this](std::span\u003cuint8_t\u003e buffer) { return serial-\u003eread(buffer.data(), buffer.size()); },\n    [this](const std::span\u003cconst uint8_t\u003e buffer) { return serial-\u003ewrite(buffer.data(), buffer.size()); },\n    readBuffer, writeBuffer, writeTimeout, writeRetries);\n```\n\nTo read and write data using Hdlcpp the read and write functions are used. These could again e.g. be used as lambdas expressions to a protocol implementation (layered architecture). The protocol could e.g. be [nanopb](https://github.com/nanopb/nanopb).\n\n```cpp\nHdlcpp::TransportAddress address { 0x00 };\nprotocol = std::make_shared\u003cProtocol\u003e(\n    [this, address](std::span\u003cuint8_t\u003e buffer) { \n        const auto res = hdlcpp-\u003eread(buffer);\n        if (res.address == address || res.address == Hdlcpp::BroadcastAddress)\n            return res.size;\n        return 0;\n    },\n    [this](const std::span\u003cconst uint8_t\u003e buffer) { return hdlcpp-\u003ewrite(address, buffer); });\n```\n\n## Python binding\n\nA python binding made using [pybind11](https://github.com/pybind/pybind11) can be found under the [python](https://github.com/bang-olufsen/hdlcpp/tree/master/python) folder which can be used e.g. for automated testing.\n\n## HDLC implementation\n\nThe supported HDLC frames are limited to DATA (I-frame with Poll bit), ACK (S-frame Receive Ready with Final bit) and NACK (S-frame Reject with Final bit). All DATA frames are acknowledged or negative acknowledged. The Address and Control fields uses the 8-bit format which means that the highest sequence number is 7. The FCS field is 16-bit.\n\nAcknowledge of frame | Negative acknowledge of frame | Acknowledge of frame lost\n--- | --- | ---\n![](https://bang-olufsen.gravizo.com/svg?%3B%0A%40startuml%3B%0Ahide%20footbox%3B%0AA%20-%3E%20B:%20DATA%20[sequence%20number%20=%201]%3B%0AB%20-%3E%20A:%20DATA%20[sequence%20number%20=%204]%3B%0AB%20-%3E%20A:%20ACK%20[sequence%20number%20=%202]%3B%0AA%20-%3E%20B:%20ACK%20[sequence%20number%20=%205]%3B%0A%40enduml) | ![](https://bang-olufsen.gravizo.com/svg?%3B%0A%40startuml%3B%0Ahide%20footbox%3B%0AA%20-%3E%20B:%20DATA%20[sequence%20number%20=%201]%3B%0AB%20-%3E%20A:%20NACK%20[sequence%20number%20=%201]%3B%0AA%20-%3E%20B:%20DATA%20[sequence%20number%20=%201]%3B%0A%40enduml) | ![](https://bang-olufsen.gravizo.com/svg?%3B%0A%40startuml%3B%0Ahide%20footbox%3B%0AA%20-%3E%20B:%20DATA%20[sequence%20number%20=%201]%3B%0AB%20-%3Ex%20A:%20ACK%20[sequence%20number%20=%202]%3B%0A...%20Timeout%20...%3B%0AA%20-%3E%20B:%20DATA%20[sequence%20number%20=%201]%3B%0A%40enduml)\n\n### Limitations\n\nFrame addressing:\nAddresses are limited to 8bit resolution. Also using ControlEscape (0x7D) or FlagSequence (0x7E) value as address will not work (should be fixed in the future).\n\n## Build and run unit tests\n\nThe build setup is configured to be run from the given Docker Container. Tested with a PC running 64 bit Ubuntu. WSL will also work.\n\n* [Clone](https://docs.github.com/en/get-started/getting-started-with-git/about-remote-repositories) this repository.\n* Install Docker: `sudo apt install docker.io`. For WSL follow [this guide](https://docs.microsoft.com/en-us/windows/wsl/tutorials/wsl-containers).\n* Run `./build.sh -h` to see build options.\n\nNOTE: If using remote-containers for ie. VSCode you can open the folder in the container automatically (see `.devcontainer`).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbang-olufsen%2Fhdlcpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbang-olufsen%2Fhdlcpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbang-olufsen%2Fhdlcpp/lists"}