Merge pull request #1 from ika-rwth-aachen/feature/github-codegen-ci

Add GitHub CI and improve readme

.github/workflows/codegen.yml

@@ -0,0 +1,131 @@
+name: Code Generation
+
+on: push
+
+jobs:
+  reduce_asn1:
+    name: ASN1 Reduction
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        include:
+          - message: cam
+            script: ./utils/codegen/reduceAsn1ToTypeDependencies.py -t CAM -o asn1/reduced/cam asn1/raw/cam_en302637_2/CAM-PDU-Descriptions.asn asn1/raw/cam_en302637_2/cdd/ITS-Container.asn
+          - message: denm
+            script: ./utils/codegen/reduceAsn1ToTypeDependencies.py -t DENM -o asn1/reduced/denm asn1/raw/denm_en302637_3/DENM-PDU-Descriptions.asn asn1/raw/denm_en302637_3/cdd/ITS-Container.asn
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+      with:
+        submodules: recursive
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+    - name: Install Python dependencies
+      run: pip install -r utils/requirements.txt
+    - name: asn1_reduce_${{ matrix.message }}
+      run: |
+        ${{ matrix.script }}
+        if [[ ! -z "$(git status --porcelain)" ]]; then
+          echo "Code generation script resulted in changes to the repository"
+          exit 1
+        fi
+
+  etsi_its_coding:
+    name: ASN1C
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        include:
+          - message: cam
+            script: ./utils/codegen/asn1ToC.py asn1/reduced/cam/CAM-PDU-Descriptions.asn asn1/reduced/cam/ITS-Container.asn -o etsi_its_coding/etsi_its_cam_coding -td ${{ github.workspace }}/tmp
+          - message: denm
+            script: ./utils/codegen/asn1ToC.py asn1/reduced/denm/DENM-PDU-Descriptions.asn asn1/reduced/denm/ITS-Container.asn -o etsi_its_coding/etsi_its_denm_coding -td ${{ github.workspace }}/tmp
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+    - name: Install Python dependencies
+      run: pip install -r utils/requirements.txt
+    - name: Login to Docker registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ github.token }}
+
+    - name: etsi_its_${{ matrix.message }}_coding
+      run: |
+        ${{ matrix.script }}
+        rm -rf ${{ github.workspace }}/tmp
+        if [[ ! -z "$(git status --porcelain)" ]]; then
+          echo "Code generation script resulted in changes to the repository"
+          exit 1
+        fi
+
+  etsi_its_msgs:
+    name: ROS Messages
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        include:
+          - message: cam
+            script: ./utils/codegen/asn1ToRosMsg.py asn1/reduced/cam/CAM-PDU-Descriptions.asn asn1/reduced/cam/ITS-Container.asn -o etsi_its_msgs/etsi_its_cam_msgs/msg
+          - message: denm
+            script: ./utils/codegen/asn1ToRosMsg.py asn1/reduced/denm/DENM-PDU-Descriptions.asn asn1/reduced/denm/ITS-Container.asn -o etsi_its_msgs/etsi_its_denm_msgs/msg
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+    - name: Install Python dependencies
+      run: pip install -r utils/requirements.txt
+    - name: etsi_its_${{ matrix.message }}_msgs
+      run: |
+        ${{ matrix.script }}
+        if [[ ! -z "$(git status --porcelain)" ]]; then
+          echo "Code generation script resulted in changes to the repository"
+          exit 1
+        fi
+
+  etsi_its_conversion:
+    name: Conversion Headers
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        include:
+          - message: cam
+            script: ./utils/codegen/asn1ToConversionHeader.py asn1/reduced/cam/CAM-PDU-Descriptions.asn asn1/reduced/cam/ITS-Container.asn -t cam -o etsi_its_conversion/etsi_its_cam_conversion/include/etsi_its_cam_conversion
+          - message: denm
+            script: ./utils/codegen/asn1ToConversionHeader.py asn1/reduced/denm/DENM-PDU-Descriptions.asn asn1/reduced/denm/ITS-Container.asn -t denm -o etsi_its_conversion/etsi_its_denm_conversion/include/etsi_its_denm_conversion
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: 3.9
+    - name: Install Python dependencies
+      run: pip install -r utils/requirements.txt
+      working-directory: ${{ github.workspace }}
+    - name: etsi_its_${{ matrix.message }}_conversion
+      run: |
+        ${{ matrix.script }}
+        if [[ ! -z "$(git status --porcelain)" ]]; then
+          echo "Code generation script resulted in changes to the repository"
+          exit 1
+        fi

.github/workflows/docker-ros.yml

@@ -28,4 +28,4 @@ jobs:
           platform: amd64,arm64
           target: dev,run
           enable-push-as-latest: 'true'
-          enable-recursive-vcs-import: 'false'
+          enable-recursive-vcs-import: 'false'

README.md

@@ -13,38 +13,56 @@
 
 The *etsi_its_messages* package stack allows to use standardized ETSI ITS messages for V2X communication in ROS / ROS 2 systems. Apart from the definition of ROS message equivalents to the ETSI ITS standards, this package stack also includes a conversion node for serializing the messages to and from a UDP payload, as well as RViz plugins for visualization (ROS 2 only).
 
+All message definitions and conversion functions are automatically generated based on the [ASN.1 definitions](https://forge.etsi.org/rep/ITS/asn1) of the standardized ETSI ITS messages.
+
 > [!IMPORTANT]  
 > This repository is open-sourced and maintained by the [**Institute for Automotive Engineering (ika) at RWTH Aachen University**](https://www.ika.rwth-aachen.de/).  
 > **V2X Communication** is one of many research topics within our [*Vehicle Intelligence & Automated Driving*](https://www.ika.rwth-aachen.de/en/competences/fields-of-research/vehicle-intelligence-automated-driving.html) domain.  
 > If you would like to learn more about how we can support your advanced driver assistance and automated driving efforts, feel free to reach out to us!  
->    *Timo Woopen - Manager Research Area Vehicle Intelligence & Automated Driving*  
->    *+49 241 80 23549*  
->    *[email protected]*  
-
-- [Concept](#concept)
-- [Supported ETSI ITS Messages](#supported-etsi-its-messages)
-- [Packages](#packages)
-  - [`etsi_its_msgs`](#etsi-its-msgs)
-  - [`etsi_its_coding`](#etsi-its-coding)
-  - [`etsi_its_conversion`](#etsi-its-conversion)
-- [Installation](#installation)
-  - [docker-ros](#docker-ros)
+>      *Timo Woopen - Manager Research Area Vehicle Intelligence & Automated Driving*  
+>      *+49 241 80 23549*  
+>      *[email protected]*  
+
+- [etsi\_its\_messages](#etsi_its_messages)
+  - [Concept](#concept)
+  - [Supported ETSI ITS Messages](#supported-etsi-its-messages)
+  - [Packages](#packages)
+    - [`etsi_its_msgs`](#etsi_its_msgs)
+      - [Automated Generation](#automated-generation)
+    - [`etsi_its_coding`](#etsi_its_coding)
+      - [Automated Generation](#automated-generation-1)
+    - [`etsi_its_conversion`](#etsi_its_conversion)
+      - [Usage](#usage)
+        - [Subscribed Topics](#subscribed-topics)
+        - [Published Topics](#published-topics)
+        - [Parameters](#parameters)
+      - [Automated Generation](#automated-generation-2)
+  - [Installation](#installation)
+    - [docker-ros](#docker-ros)
+  - [Acknowledgements](#acknowledgements)
+  - [Notice](#notice)
 
 
 ## Concept
 
 ![Framework](assets/framework.png)
 
+The core concept of the *etsi_its_messages* is to automatically generate the ROS support code based on the [ASN.1 definitions](https://forge.etsi.org/rep/ITS/asn1) of the standardized ETSI ITS messages *(CodeGen)*. The ROS support then allows ROS applications to not only natively use corresponding ETSI ITS message types, but to also exchange encoded ETSI ITS message payloads with the world outside of ROS *(Runtime)*.
+
+A given ASN.1 definition is used to generate corresponding C-structures, ROS message definitions, as well as conversion functions between those two formats.
+
+During runtime, the `etsi_its_conversion` ROS node converts incoming UDP payloads into corresponding ROS messages and vice versa. The ROS equivalents of the ETSI ITS messages can be used in any downstream ROS applications or visualized using the provided RViz plugins.
+
 
 ## Supported ETSI ITS Messages
 
-| Status | Acronym | Name | Version | Definition |
-| --- | --- | --- | --- | --- |
-| :white_check_mark: | CAM | Cooperative Awareness Message | 1.4.1 | [Link](https://www.etsi.org/deliver/etsi_en/302600_302699/30263702/01.04.01_60/en_30263702v010401p.pdf) |
-| :white_check_mark: | DENM | Decentralized Environmental Notification Message | 1.3.1 | [Link](https://www.etsi.org/deliver/etsi_en/302600_302699/30263703/01.03.01_60/en_30263703v010301p.pdf) |
-| :soon: | MAPEM | Map Extended Message | - | - |
-| :soon: | SPATEM | Signal Phase and Timing Extended Message | - | - |
-| :soon: | CPM | Collective Perception Message | - | - |
+| Status | Acronym | Name | Version | Definition | Repository |
+| --- | --- | --- | --- | --- | --- |
+| :white_check_mark: | CAM | Cooperative Awareness Message | 1.4.1 | [Link](https://www.etsi.org/deliver/etsi_en/302600_302699/30263702/01.04.01_60/en_30263702v010401p.pdf) | [Link](https://forge.etsi.org/rep/ITS/asn1/cam_en302637_2) |
+| :white_check_mark: | DENM | Decentralized Environmental Notification Message | 1.3.1 | [Link](https://www.etsi.org/deliver/etsi_en/302600_302699/30263703/01.03.01_60/en_30263703v010301p.pdf) | [Link](https://forge.etsi.org/rep/ITS/asn1/denm_en302637_3) |
+| :soon: | MAPEM | Map Extended Message | - | - | - |
+| :soon: | SPATEM | Signal Phase and Timing Extended Message | - | - | - |
+| :soon: | CPM | Collective Perception Message | - | - | - |
 
 
 ## Packages
@@ -54,7 +72,7 @@ etsi_its_messages
 ├── etsi_its_coding
 │   ├── etsi_its_coding         # metapackage including all coding packages
 │   ├── etsi_its_cam_coding
-│   └── etsi_its_cam_coding
+│   └── etsi_its_denm_coding
 ├── etsi_its_conversion
 │   ├── etsi_its_conversion     # conversion node depending on all conversion packages
 │   ├── etsi_its_cam_conversion
@@ -76,7 +94,7 @@ In addition, the `etsi_its_msgs` contains header-only libraries providing helpfu
 
 #### Automated Generation
 
-The ROS message files are auto-generated based on the ASN.1 definition of the ETSI ITS message standards.
+The ROS message files are auto-generated based on the [ASN.1 definitions](https://forge.etsi.org/rep/ITS/asn1) of the ETSI ITS message standards. Note that the ASN.1 definitions are preprocessed to only include types relevant for the particular message type.
 
 ```bash
 # etsi_its_messages$
@@ -92,7 +110,7 @@ The `etsi_its_coding` metapackage includes one dedicated package for each ETSI I
 
 #### Automated Generation
 
-The C/C++ implementation of the message types is auto-generated based on the ASN.1 definition of the ETSI ITS message standards, using the [ASN.1 Compiler asn1c](https://github.com/vlm/asn1c).
+The C/C++ implementation of the message types is auto-generated based on the [ASN.1 definitions](https://forge.etsi.org/rep/ITS/asn1) of the ETSI ITS message standards, using the [ASN.1 Compiler asn1c](https://github.com/vlm/asn1c). Note that the ASN.1 definitions are preprocessed to only include types relevant for the particular message type.
 
 ```bash
 # etsi_its_messages$
@@ -149,7 +167,7 @@ rosrun nodelet nodelet standalone etsi_its_conversion/Converter _etsi_type:=auto
 
 #### Automated Generation
 
-The C++ conversion functions are auto-generated based on the ASN.1 definition of the ETSI ITS message standards.
+The C++ conversion functions are auto-generated based on the [ASN.1 definitions](https://forge.etsi.org/rep/ITS/asn1) of the ETSI ITS message standards. Note that the ASN.1 definitions are preprocessed to only include types relevant for the particular message type.
 
 ```bash
 # etsi_its_messages$
@@ -203,4 +221,44 @@ docker run --rm ghcr.io/ika-rwth-aachen/etsi_its_messages:ros
 
 ## Acknowledgements
 
-This work is accomplished within the projects 6GEM (FKZ 16KISK036K), AUTOtech.agil (FKZ 01IS22088A), and AIthena (101076754). We acknowledge the financial support for the projects by the Federal Ministry of Education and Research of Germany (BMBF) :de:. Moreover this work has received funding from the European Union’s Horizon Europe Research and Innovation Programme :eu: under Grant Agreement No 101076754 - AIthena project.
+This work is accomplished within the projects AIthena, 6GEM and AUTOtech.*agil*. We acknowledge the financial support for the projects by
+- the *European Union’s Horizon Europe Research and Innovation Programme* :eu: under Grant Agreement No 101076754 for AIthena,
+- and the *Federal Ministry of Education and Research of Germany (BMBF)* :de: for 6GEM (FKZ 16KISK036K) and AUTOtech.*agil* (FKZ 01IS22088A).
+
+## Notice
+
+This repository is not endorsed by or otherwise affiliated with [ETSI](https://www.etsi.org).
+
+This repository uses the following software. For full license details, please refer to the specific license files of the respective software.
+
+- [asn1c](https://github.com/vlm/asn1c)
+    ```
+    BSD 2-Clause License
+    Copyright (c) 2003-2017  Lev Walkin <[email protected]> and contributors.
+    All rights reserved.
+    ```
+- [asn1tools](https://github.com/eerimoq/asn1tools)
+    ```
+    MIT License
+    Copyright (c) 2017-2019 Erik Moqvist
+    ```
+- [ETSI ITS ASN1](https://forge.etsi.org/rep/ITS/asn1)
+    ```
+    BSD 3-Clause License
+    Copyright (c) ETSI
+    ```
+- [GeographicLib](https://github.com/geographiclib/geographiclib)
+    ```
+    MIT License
+    Copyright (c) 2008-2023, Charles Karney
+    ```
+- [ROS](https://www.ros.org/)
+    ```
+    BSD 3-Clause License
+    All rights reserved.
+    ```
+- [ROS 2](https://www.ros2.org/)
+    ```
+    Apache 2.0 License
+    All rights reserved.
+    ```

asn1/reduced/cam/LICENSE

@@ -0,0 +1,23 @@
+Copyright 2019 ETSI
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright notice, 
+   this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, 
+   this list of conditions and the following disclaimer in the documentation 
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors 
+   may be used to endorse or promote products derived from this software without 
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 
+OF THE POSSIBILITY OF SUCH DAMAGE.

asn1/reduced/denm/LICENSE

@@ -0,0 +1,23 @@
+Copyright 2019 ETSI
+
+Redistribution and use in source and binary forms, with or without 
+modification, are permitted provided that the following conditions are met:
+1. Redistributions of source code must retain the above copyright notice, 
+   this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice, 
+   this list of conditions and the following disclaimer in the documentation 
+   and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors 
+   may be used to endorse or promote products derived from this software without 
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 
+OF THE POSSIBILITY OF SUCH DAMAGE.

utils/codegen/asn1ToC.py

@@ -47,7 +47,7 @@ def parseCli():
     parser.add_argument("files", type=str, nargs="+", help="ASN1 files")
     parser.add_argument("-o", "--output-dir", type=str, required=True, help="output package directory")
     parser.add_argument("-td", "--temp-dir", type=str, default=None, help="temporary directory for mounting files to container; uses tempfile by default")
-    parser.add_argument("-di", "--docker-image", type=str, default="gitlab.ika.rwth-aachen.de:5050/fb-fi/definitions/etsi_its_messages/asn1c:latest", help="asn1c Docker image")
+    parser.add_argument("-di", "--docker-image", type=str, default="ghcr.io/ika-rwth-aachen/etsi_its_messages:asn1c", help="asn1c Docker image")
 
     args = parser.parse_args()
 

utils/codegen/docker/asn1c.Dockerfile

@@ -1,4 +1,4 @@
-# docker build -t gitlab.ika.rwth-aachen.de:5050/fb-fi/definitions/etsi_its_messages/asn1c:latest .
+# docker build -t ghcr.io/ika-rwth-aachen/etsi_its_messages:asn1c .
 
 FROM ubuntu:18.04