Introduction to cube:its

cube:its is a comprehensive framework that brings ETSI-compliant V2X communication into the ROS 2 ecosystem. Built on Vanetza and integrated with cube:radio and cube:ubx, it transforms your cube:evk into a production-ready ITS station that speaks ROS 2.

ROS 2

ROS 2 (Robot Operating System 2) is a framework for building modular software systems. At its core, ROS 2 uses a publish-subscribe messaging pattern combined with service-based request-response communication:

Topics (Publish-Subscribe)

• Nodes are independent processes that perform specific tasks
• Topics are named channels where nodes exchange messages
• Publishers send messages to a topic
• Subscribers receive messages from a topic

Example: A camera node publishes images to /camera/image, while a perception node subscribes to receive them.

Services (Request-Response)

• Services enable synchronous communication between nodes
• A client sends a request and waits for a response
• A server processes the request and returns a result

Example: A navigation node calls the /plan_path service with start and goal positions, and receives a computed path as response.

Topics vs Services:

• Use topics for continuous data streams (sensor data, status updates)
• Use services for one-time operations (triggering actions, requesting information)

ROS 2 handles all the networking, serialization, and discovery automatically. That's really all you need to know to get started with cube:its.

Want to learn more? Check out the official ROS 2 documentation.

Docker

Docker is a containerization platform that packages applications with all their dependencies into isolated, portable units called containers.

Think of a container as a lightweight virtual machine:

• Self-contained – Includes everything the application needs (libraries, tools, runtime)
• Isolated – Runs independently without affecting the host system
• Portable – Works the same on any machine with Docker installed

cube:its runs as a Docker container on your cube:evk. This means:

• ✅ All dependencies are pre-configured
• ✅ Updates are as simple as pulling a new image
• ✅ Multiple versions can coexist
• ✅ Your host system stays clean

You interact with the container using standard Docker commands like docker run, docker exec, and docker logs. No complex installation—just start the container and you're ready to go.

New to Docker? The official Docker documentation is a great place to start.

Architecture Overview

The cube:its framework comprises multiple ROS 2 nodes that collaboratively handle GNSS data, vehicle kinematics, I/O operations, ITS facilities, and V2X communication:

Core Components

ROS 2 Interface

cube:its exposes a clean ROS 2 API through the ros_cube_msgs package:

Compatible ETSI Messages

cube:its incorporates the etsi_its_messages package for standardized V2X message definitions:

Supported Applications

cube:its includes pre-profiled applications specified by C-ITS platforms and consortia:

More applications are continuously being added. Custom application profiling is always possible by configuring message parameters and trigger conditions.

Node Discovery

ROS 2 provides flexible discovery mechanisms to control how nodes find and communicate with each other. By default, nodes discover each other on the same subnet using multicast.

Basic Configuration

To enable your ROS 2 nodes to discover and communicate with cube:its, ensure they share the same domain:

1
export ROS_DOMAIN_ID=42  # Default domain for cube:its

Advanced Discovery Configuration

For more control over node discovery, ROS 2 provides additional configuration parameters:

ROS_AUTOMATIC_DISCOVERY_RANGE

Controls how far ROS 2 nodes will try to discover each other:

Example:

1
export ROS_AUTOMATIC_DISCOVERY_RANGE=SUBNET

ROS_STATIC_PEERS

A semicolon-separated list of IP addresses where ROS 2 should look for nodes. Useful for connecting to specific machines when discovery range is limited.

Example:

1
export ROS_STATIC_PEERS="192.168.1.100;192.168.1.101"

This allows connecting to nodes on those specific machines, as long as their discovery range isn't set to OFF.

Conformance Validation

cube:its is validated using the ETSI conformance framework specified in ETSI TR 103 099 V1.5.1, ensuring compliance with ETSI ITS standards.

cube.ini — Core Configuration for cube:its

cube:its is configured through a simple INI file located at:

1
/etc/cube/cube.ini

This file defines which ITS features are enabled, how the device identifies itself as a station, and optional vehicle parameters used by CAM, DENM, CPM, and VAM facility layers.

Below is the default structure of the configuration file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
[features]
; enable CAN bus nodes
can_bus = False
; enable curvature calculation
curvature = False
; enable built-in CAM provider
cam_provider = True

[cube]
; running cube-its remotely
; address = 192.168.178.119

[its]
station_type = cyclist

[vehicle]
; vehicle dimensions in meter
length = 1.9
width = 1.1

[features] — Enable or Disable Subsystems

This section controls optional cube:its modules.

You can safely disable features you do not need to reduce computation load.

[cube] — Remote Operation

cube:its can run on your workstation using ROS 2 Dev Containers while the V2X radio and GNSS remain on the cube device.

To enable this, uncomment and set:

1
2
[cube]
address = <cube-ip>

Example:

1
address = 192.168.8.101

This tells cube:its running on your host to connect to the cube’s local services (GNSS, radio, clock sync).

[its] — Station Type Configuration

The station type defines how your device identifies itself in V2X messages like CAM, CPM, and VAM. This value influences data fields and behavior in the facility layer.

1
2
[its]
station_type = cyclist

Supported station types:

• unknown
• pedestrian
• cyclist
• moped
• motorcycle
• passenger_car
• bus
• light truck
• heavy truck
• trailer
• special_vehicle / special_vehicles
• tram
• road side unit

This should match your actual deployment. For VRU or micro-mobility demonstrations, use:

1
station_type = cyclist

For vehicle prototypes:

1
station_type = passenger_car

For RSUs:

1
station_type = road_side_unit

[vehicle] — Vehicle Dimensions (Used in CAM, CPM, VAM)

When operating as a vehicle station, providing realistic dimensions is essential for accurate safety messages.

Example:

1
2
3
[vehicle]
length = 4.5
width = 2.0

These values affect:

• The CAM High Frequency Container
• CPM object relative positioning
• VAM safety envelopes for VRUs mounted on vehicles

Starting cube:its

The cube:evk includes a convenient start-its command to launch the cube:its Docker container with the right configuration. This script handles all the complexity of Docker parameters and ROS 2 environment setup.

Basic Usage

Simply run:

1
cube:~$ start-its

This starts cube:its with default settings: jazzy distribution and SUBNET discovery range.

Common Options

Choose ROS 2 Distribution

1
2
cube:~$ start-its --distro humble
cube:~$ start-its --distro jazzy    # Default

Available distributions: humble, jazzy, kilted

Control Discovery Scope

Local only (nodes only discover on the same machine):

1
cube:~$ start-its --local

Network-wide (nodes discover across your subnet):

1
cube:~$ start-its --remote

If neither --local nor --remote is specified, the container uses ROS 2 defaults.

Set Domain ID

1
cube:~$ start-its --domain-id 42

Default domain ID is 42 for cube:its.

Run as Daemon

Start cube:its in the background:

1
cube:~$ start-its --daemon

Without --daemon, the container runs interactively and you can see log output directly.

Advanced Usage

Custom Environment Variables

Pass additional environment variables to the container:

1
2
cube:~$ start-its -e ROS_STATIC_PEERS="192.168.1.100;192.168.1.101"
cube:~$ start-its -e MY_CUSTOM_VAR=value -e ANOTHER_VAR=123

Verbose Mode

See the exact Docker command being executed:

1
2
cube:~$ start-its --verbose
Starting ITS with: docker run --rm --network host --ipc host -v /etc/cube:/etc/cube -it -e ROS_DOMAIN_ID=42 ghcr.io/cubesys-gmbh/cube-its:jazzy

Useful for debugging or understanding what's happening under the hood.

Custom Image

Override the default image using environment variables:

1
cube:~$ START_ITS_IMAGE=my-registry/custom-its START_ITS_TAG=v1.0 start-its

Complete Examples

Start for local development:

1
cube:~$ start-its --local --distro jazzy

Start for network access with custom domain:

1
cube:~$ start-its --remote --domain-id 100

Start as daemon with static peers:

1
cube:~$ start-its --daemon --remote -e ROS_STATIC_PEERS="192.168.8.100"

Verbose startup with multiple options:

1
cube:~$ start-its --verbose --distro humble --domain-id 50 -e MY_VAR=test

Under the Hood

The start-its script automatically:

• ✅ Mounts cube for configuration persistence
• ✅ Uses host networking for optimal ROS 2 performance
• ✅ Handles distribution-specific quirks (e.g., file descriptor limits for Humble)
• ✅ Maps discovery flags to the correct environment variables for each distro

You don't need to remember complex Docker commands—start-its handles it all for you!

Now, head over to ITS Facilities and write your own applications.