Overview

This project is a member of CommsChampion Ecosystem. It provides a code generator that produces C++11 code of a binary communication protocol, defined using CommsDSL schema files.

What's Inside

• commsdsl2comms - A code generator, that produces C++11 code for binary protocol definition out of CommsDSL schema files. The generated outcome is actually a CMake project that can be used to build and install multiple targets. For details on how to use the tool, please read the commsdsl2comms Manual wiki page. For details on the generated CMake project please read the Generated CMake Project Walkthrough wiki page.
• libcommsdsl - A C++11 library for parsing of CommsDSL schema files. It can be used to implement independent code generators, which can produce protocol definition code in other programming languages, bindings to the C++ classes generated by the commsdsl2comms, extra testing, etc... NOTE, that at this moment, the library is not documented. Please get in touch in case you need it. I'll let you know when it's going to be ready.

License

Code generated by commsdsl2comms has no license, the vendor is free to pick one. HOWEVER, the generated code uses COMMS library, which is provided under GPLv3 / Commercial dual licensing scheme. Unless commercial closed source license is obtained for the COMMS library, the generated code as well as integrating business logic must remain open source and the picked license be compatible with GPLv3.

The code of this project (libraries and tools it contains) is licensed under Apache v2.0 license.

Examples

There are multiple available examples of protocol definitions that use CommsDSL schema files and commsdsl2comms code generator to generate relevant code.

Synthetic Demo Protocols

• cc.demo1.commsdsl - Demo protocol to demonstrate definition of various fields as well as simple protocol framing.
• cc.demo2.commsdsl - Demo protocol to demonstrate protocol versioning, where every message reports protocol version in its transport frame.
• cc.demo3.commsdsl - Demo protocol to demonstrate protocol versioning, where one "connect" message reports protocol version for all the subsequent messages.

Real Life Open Protocols

• cc.mqtt311.commsdsl - Defines MQTT v3.1.1 protocol, where message ID shares the same byte with extra flags, that may define existence of the fields in message payload as well as influence how message needs to be processed. The protocol definition also contains snippets of custom code that are injected by the commsdsl2comms into the generated one.
• cc.mqtt5.commsdsl - Defines MQTT v5 protocol. Similar to v3.1.1, but also adds a heterogeneous list of various properties.
• cc.mqttsn.commsdsl - Defines MQTT-SN protocol, where field of remaining length of the message can have either 1 or 3 bytes length, depending on the value it contains.
• cc.ublox.commsdsl - Defines UBX protocol used by various u-blox GPS receivers. The protocol itself is quite complex with hundreds of messages. It uses custom checksum calculation algorithms and injects multiple code snippets to fix incorrect or incomplete functionality available by default.

How to Use Generated Code

Please refer to Generated CMake Project Walkthrough wiki page.

Versioning

This project will use Semantic Versioning, where MAJOR number will be equal to the latest DSL version (The first number of CommsDSL version) it supports. The MINOR number will indicate various improvements in the code of this repository, and PATCH number will indicate various bug fixes.

How to Build

This project uses CMake as its build system. Please open main CMakeLists.txt file and review available options as well as mentioned available parameters, which can be used in addition to standard ones provided by CMake itself, to modify the default build.

NOTE, that libcommsdsl uses libxml2 to parse XML schema files, and commsdsl2comms uses Boost to parse its command line parameters (Boost::program_options), perform filesystem operations (Boost::filesystem), and various string manipulation algorithms. In case Boost libraries are not installed in expected default location (mostly happens on Windows systems), use variables described in CMake documentation to help CMake find required libraries and headers. It is recommended to use -DBoost_USE_STATIC_LIBS=ON parameter to force linkage with static Boost libraries. Also on Windows systems there is no need to build libxml2 separately. The build process will check it out automatically and build static library itself. For example:

Linux Build

$> cd /source/of/this/project
$> mkdir build && cd build
$> cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install -DCOMMSDSL_NO_TESTS=ON ..
$> make install

Windows Build

$> cd C:\source\of\this\project
$> mkdir build
$> cd build
$> cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release \ 
    -DCMAKE_INSTALL_PREFIX=%cd%/install -DCOMMSDSL_NO_TESTS=ON \
    -DBOOST_ROOT="C:\Libraries\boost_1_65_1" -DBoost_USE_STATIC_LIBS=ON ..
$> nmake install

Supported Compilers

This project (the code generator and CommsDSL parsing library) is implemented using C++14 programming language. As the result, the supported compilers are:

• GCC: >=5
• Clang: >=3.9
• MSVC: >= 2015

The generated project however contains C++11 valid code and supports a bit earlier versions of the compilers:

• GCC: >=4.8
• Clang: >=3.8
• MSVC: >= 2015

Branching Model

This repository will follow the Successful Git Branching Model.

The master branch will always point to the latest release, the development is performed on develop branch. As the result it is safe to just clone the sources of this repository and use it without any extra manipulations of looking for the latest stable version among the tags and checking it out.

Contact Information

For bug reports, feature requests, or any other question you may open an issue here in github or e-mail me directly to: [email protected]. I usually respond within 24 hours.