ITS Awareness Service

The ITS Awareness Service is a C++ V2X communication module implementing both the Cooperative Awareness Service (CAS) and the VRU Awareness Service according to ETSI standards, including ETSI TS 103 300 and ETSI TS 103 300-3. It generates Cooperative Awareness Messages (CAMs) and VRU Awareness Messages (VAMs) so other ITS stations can be informed about the presence and dynamics of vehicles, vulnerable road users, and roadside units.

The service is designed as a modular microservice. External adapters collect data from sensors, simulators, vehicles, or infrastructure sources and publish normalized JSON data over MQTT. The ITS Awareness Service validates the received values, updates the current CAM or VAM state, and publishes the generated message to Vanetza.

Key Features

• ETSI-oriented CAM and VAM generation
• MQTT-based integration with external adapters and Vanetza
• Shared validation of accepted values, unavailable values, and enumerations
• Support for vehicle, VRU, and RSU-oriented deployments
• Thread-safe message-state updates
• Container-oriented deployment

Citation

If you find this code useful in your research, please consider citing:

@INPROCEEDINGS{Figueiredo2026,
    author={Andreia Figueiredo and Cláudio Asensio and António Almeida and João Amaral and Pedro Rito and Miguel Luís and Susana Sargento},
    booktitle={2026 IEEE Vehicular Networking Conference (VNC)},
    title={A Modular ETSI-Compliant Awareness Service for Unified CAM and VAM Generation}
}

Table of Contents

• Requirements
• Quick Start
• Architecture
• Message Formats
• Configuration
• Deployment
• Monitoring & Metrics
• Development Status
• Documentation & Examples
• Authors
• License

Requirements

The ITS Awareness Service expects the following runtime components:

Component	Purpose
MQTT broker	Transports adapter data and generated CAM/VAM messages. Mosquitto is commonly used.
Vanetza	Receives generated CAM/VAM messages and handles the V2X networking stack.
Docker / Docker Compose	Recommended deployment method for the service and adapters.
Adapter service	Publishes normalized JSON input data to the ITS Awareness Service.

Quick Start

1. Edit ITSAwarenessService/config.ini.

   Change the settings according to our use case

2. Start the service with Docker Compose:

   docker compose up

3. Publish a minimal adapter payload to the configured adapter topic:

   mosquitto_pub -h 127.0.0.1 -p 1883 -t messenger/adapters -m '{"latitude":40.07128,"longitude":-8.405,"speedValue":12.5,"headingValue":90.0}'

4. Confirm that generated messages are published to the configured Vanetza input topic, for example:

   • vanetza/in/cam
   • vanetza/in/vam

The default topics are configured in ITSAwarenessService/config.ini.

Architecture

The service is organized around three main flows:

1. Adapters collect data from external sources such as gpsd, Autoware VPI, fixed-path files, RSU configuration files.
2. The ITS Awareness Service Data Manager receives and validates data from the adapter MQTT topic, then updates the current CAM or VAM message state.
3. The ITS Awareness Service Message Generator publishes CAM/VAM messages to Vanetza when the message is available and the transmission rules allow publication.

The ITS Awareness Service does not read sensors directly. Sensor-specific parsing and source-specific logic belong in adapters. The core service centralizes message creation, accepted-value validation, freshness handling, and publication to Vanetza.

Repository layout:

cabasicservice/
  ITSAwarenessService/              Core ITS Awareness Service source and configuration
  adapters/
    autoware/                Adapter for data generated by Autoware VPI
    fixed-path/              Adapter that replays a fixed path from a file
    gps/                     Adapter that reads live data from gpsd
    rsu/                     Adapter that publishes static RSU position data
  docs/
    AcceptedValuesCam.md     CAM accepted fields, ranges, and unavailable values
    AcceptedValuesVam.md     VAM accepted fields, ranges, and unavailable values
    Enumerated.md            Enumeration meanings used by CAM and VAM fields
    images/                  Documentation images
  docker-compose.yml         Example Compose file

Message Formats

Adapters publish JSON payloads with field names accepted by the ITS Awareness Service. The service validates each field before using it.

Minimal payload:

{
  "latitude": 40.07128,
  "longitude": -8.405,
  "speedValue": 12.5,
  "headingValue": 90.0
}

Grouped fields are represented as nested objects:

{
  "longitudinalAcceleration": {
    "value": 0.4,
    "confidence": 0.1
  }
}

The exact accepted fields depend on whether the service is configured for CAM or VAM:

• CAM accepted values
• VAM accepted values
• Enumeration meanings

Values with the wrong type or outside the accepted range are ignored and logged. Values equal to an ETSI unavailable value are accepted when the field defines an unavailable value.

Configuration

Runtime configuration is loaded from ITSAwarenessService/config.ini.

Important sections:

Section	Key	Description
[message-configuration]	messageType	Message type to generate: CAM or VAM.
[message-configuration]	ignore_rules	When enabled, bypasses trigger-rule checks for debugging.
[message-configuration]	vamClustering	Enables VAM clustering support.
[message-configuration]	force_cluster_operation	Forces a VAM cluster operation for testing.
[station-info]	stationID	ITS station identifier.
[station-info]	stationType	ETSI station type.
[vehicle-characteristics]	vehicleLength	Vehicle length used by CAM.
[vehicle-characteristics]	vehicleWidth	Vehicle width used by CAM.
[vehicle-characteristics]	vehicleRole	Vehicle role used by CAM low-frequency data.
[vru-characteristics]	vruProfile	VRU profile used by VAM low-frequency data.
[mqtt-messageSender]	host, port	MQTT broker used for publishing generated messages to Vanetza.
[mqtt-messageSender]	topic_publish	Vanetza input topic, such as vanetza/in/cam or vanetza/in/vam.
[mqtt-dataReceiver]	host, port	MQTT broker used for adapter input data.
[mqtt-dataReceiver]	topic_subscribe	Topic where adapters publish normalized JSON data.
[mqtt-VRUcluster]	topic_subscribe	Topic used for VAM cluster data.
[messageSender]	performance_logs	Enables sender performance logging.
[spdlog]	level	Runtime log level.

Example message selection:

[message-configuration]
messageType = VAM
ignore_rules = false
vamClustering = 0

Example MQTT configuration:

[mqtt-messageSender]
host=127.0.0.1
port=1883
topic_publish = vanetza/in/vam

[mqtt-dataReceiver]
host=127.0.0.1
port=1883
topic_subscribe = messenger/adapters

Deployment

The repository includes an example Compose file:

docker compose up

The top-level docker-compose.yml mounts:

• ./ITSAwarenessService/config.ini as /config.ini
• ./logs as /logs

Adapters are deployed separately from their own folders when needed. Each adapter has its own configuration file and, where available, its own Compose file.

Adapter	Purpose	Documentation
GPS	Reads live position data from gpsd.	adapters/gps/README.MD
RSU	Publishes a fixed RSU position from info.ini.	adapters/rsu/README.MD
Fixed Path	Replays a predefined path from a file.	adapters/fixed-path/README.MD
Autoware	Bridges data generated by Autoware VPI into the service.	adapters/autoware/README.MD

Monitoring & Metrics

The service uses spdlog for runtime logs. The log level is configured with:

[spdlog]
level=debug

Useful log events include:

• MQTT connection status
• adapter payload reception
• field validation warnings
• CAM/VAM container availability
• generated message publication
• shutdown handling

Performance logging can be enabled with:

[messageSender]
performance_logs = true

When enabled, performance logs are written to the mounted /logs directory used by the container.

Development Status

Current supported message types:

• CAM
• VAM

Current limitations:

• VAM Motion Prediction Container is not supported yet.
• Adapter validation is intentionally lightweight; full accepted-value validation is centralized in the ITS Awareness Service.

Documentation

Core documentation:

• CAM accepted values
• VAM accepted values
• Enumerated values

Adapter documentation:

• Autoware adapter
• Fixed Path adapter
• GPS adapter
• RSU adapter

Input Examples

• docs/examples/inputITSAwarenessService.json — example of an input published to messenger/adapters

Output Examples

• docs/examples/CAMITSAwarenessService.json — example CAM generated by the ITS Awareness Service
• docs/examples/VAMITSAwarenessService.json — example VAM generated by the ITS Awareness Service

API Documentation (Doxygen)

This project provides automatically generated API documentation using Doxygen.

To generate the documentation locally:

doxygen Doxyfile

Authors

Development of the ITS Awareness Service is part of ongoing research work at Instituto de Telecomunicações' Network Architectures and Protocols Group.

Questions and bug reports:

• andreiagf@av.it.pt
• claudioasensio@av.it.pt

License

The ITS Awareness Service is intended to be released under LGPLv3. Add the final license file to the repository before publication.