Communication Library for Car2X projects

The code of this project was used for the communication in LUKAS and is now available as Open Source and licensed under MIT.

Repository Structure

This repository is a rust workspace and consists of multiple crates (~ modules / libraries) representing libraries, binaries, and other deployables. The following illustrates a general and simplified overview of the structure:

The main gist is that

• Internal library crates are prefixed with common-*.
• Binaries or more important crates (like messages, asn1rs, ...) are not prefixed.
• Binaries are usually very small crates around corresponding library crates which call into the library with parsed CLI and environment arguments as well as configured logger and tracer.
• External dependencies are often re-exported in the common-* crate they are introduced first to reduce the places a specific version of the external crate is mentioned in a Cargo.toml.

The following shows an illustration with a different focus. While it explicitly mentions Android and .aar files, the same packaging structure applies for Java and .jar files.

See also libconnector-android/libconnector-android/build.gradle Line 12, for the target configurations.

Crate messages and the protocol directory

The crate messages contains generated Rust types of the used ASN.1 protocol descirptions. It also contains small helper functions to (de-)serialize these types into/from uPER, Protobuf and JSON/BSON.

The directory protocol is a submodule containing the actual (asn) and generated message definitions as well as schema files and is structured like this:

├── asn
│   ├── cam-pdu-descriptions.asn
│   ├── cpm-pdu-descriptions.asn
│   └── ...
├── proto
│   ├── cam_pdu_descriptions.proto
│   ├── compiler_test.proto
│   └── ...
└── sql
    ├── cam_pdu_descriptions.sql
    ├── compiler_test.sql
    └── ...

The build script at messages/build.rs loads the *.asn files, creates *.proto definitions *.sql^1 and also writes to messages/src/ Rust data-structures, capable to be (de-)serialized from and to ASN.1 uPER and Protobuf:

^1: SQL bindings are deprecated / no longer used by LUKAS

How to build and run

A note on long compile times: Due to the profile.release configuration in the workspace Cargo.toml, the build takes extra long (mostly caused by the lto and maybe the codegen-units configuration), but should yield optimized binaries in release mode in return.

The generated binaries can then be found in $CARGO_TARGET_DIR/release/ (which often istarget/release).

The connector

cargo build -p connector --release

Binary: $CARGO_TARGET_DIR/release/libconnector.so (linux)

Release Process

Binaries are published and deployed through the CI. To trigger it, a new tag matching v\d+\.\d+\.\d+$ (e.g. v6.1.1) must be created and pushed. Pushing the tag will by itself trigger a CI run, therefore one can run a pre-deploy pipeline by pushing only the relevant commit and the tag afterwards, once the build succeeded.

The crate connector / libconnector is the externally used public interface for this workspace. Therefore, the file CHANGELOG.md is to be updated accordingly.

The current version must be reflected manually at:

• [workspace.package] version in ./Cargo.toml
• common-message-codec/../lib.rs: constant in pub mod protocol
• common-message-codec/../edge.rs: constant in impl EdgeMessageUperCodec

Tag the new release, which will trigger the pipeline to produce tagged docker-images and version-named archive files.

$ git commit -m "Update changelog for vA.B.C"
$ git push origin
#  ~~ once CI succeeds ~~
$ git tag vA.B.C
$ git push origin --tags
#  ~~ CI now builds special docker images and archives ~~

Rust

Interesting opinion on howto get started with rust.

• Rust book 2018 Edition
• Rust by Example
• Programming Rust

Follow the naming conventions

See guidelines, and this discussion.

Stick to it.

If the compiler complains about naming, fix it.

Styleguide

We are using rustfmt and follow its styleguide.

Clippy

"A collection of lints to catch common mistakes and improve your Rust code." See clippy

Use cargo clippy for hints (lints)

LICENSE

Unless mentioned otherwise, all content of this repository is licensed under [GPLv3].

The copyright of some protocol definitions in protocol/asn are hold by ETSI or ISO:

• cam-pdu-descriptions.asn: CAM EN 302 637-2, Copyright 2019 ETSI, src
• cpm-pdu-descriptions.asn: ETSI TR 103 562, ETSI WorkItem 46541
• denm-pdu-descriptions.asn: ETSI EN 302 637-3, Copyright 2019 ETSI, src
• dsrc-simplified-v2.asn: ISO TS 19091 (reduced due to technical limitations), ISO`s Copyright
• its-container.asn: ETSI TS 102 894-2, Copyright 2019 ETSI, src
• mcm-pdu-descriptions.asn: ETSI TR 103 563, ETSI Stable Draft
• vam-pdu-descriptions.asn: ETSI TS 103 300-2, Copyright 2020 ETSI, src
• vam-temp-imports.asn: ETSI TS 103 300-2 (prefixed with Temp due to technical limitations), Copyright 2020 ETSI, src
• vru-motorcyclist-special-container.asn: ETSI TS 103 300-3, Copyright 2020 ETSI, src

Note: Some ETSI protocols were altered to better suite the use cases of LUKAS.