ITS Time API Developer Guide

V2X messages need time, but not "PC time" and not plain UTC. They need ETSI ITS time: a TAI-based time scale starting at 2004-01-01 00:00:00 UTC and used in ETSI ITS-G5 / C-ITS messages (see ETSI TS 102 894-2).

On the cube:evk, ITS time is derived from GNSS → chrony → system clock → cube:time. Applications read it through either the C API or the C++ API.

This chapter covers:

1. What ITS time is and why we use it
2. How to check if the cube is synchronized
3. How to read the current ITS timestamp (C and C++)
4. How to get the current TAI–UTC offset

1. Background: ITS time on cube:evk

As described in the Time Synchronization chapter, the device runs chrony and locks the system clock to the GNSS PPS. This provides:

• A stable TAI time base
• A known TAI–UTC offset (leap seconds)
• A correct ITS time (TAI seconds since 2004-01-01)

The CLI tool:

1
cube-timectl show

shows the same information that is available from code:

• Current ITS timestamp
• Whether the system time is synchronized
• Current TAI–UTC offset
• Leap second status

The library cube:time is the programmatic way to access this.

2. C API (time.h)

For C or simple C++ code, use the two helper functions from time.h:

1
2
3
4
5
6
7
8
9
10
11
/**
 * \brief get current ITS timestamp in milliseconds
 * \return milliseconds since ITS epoch start (-1 if not synchronized)
 */
int64_t cube_time_now_ms();

/**
 * \brief get current ITS timestamp in microseconds
 * \return microseconds since ITS epoch start (-1 if not synchronized)
 */
int64_t cube_time_now_us();

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
#include <cube/time.h>
#include <stdio.h>

int main(void)
{
    int64_t its_ms = cube_time_now_ms();
    if (its_ms < 0) {
        printf("ITS time not synchronized yet\n");
        return 1;
    }

    printf("ITS time: %lld ms since 2004-01-01T00:00:00Z\n", (long long)its_ms);
    return 0;
}

Key points:

• Return value < 0: not synchronized (GNSS / chrony not locked yet)
• Value is since ITS epoch (2004-01-01), not the UNIX epoch (1970-01-01)
• Suitable for filling ITS timestamps in messages from pure C

3. C++ API (clock.hpp)

For C++ code, a clock type is provided that behaves like a standard C++ clock:

1
2
3
4
5
6
7
struct cube::time::EtsiItsClock {
    static time_point now();
    static std::optional<time_point> maybe_now();
    static bool is_synchronized();
    static duration utc_offset() noexcept;
    static time_point from_system_clock(std::chrono::system_clock::time_point);
};

It provides:

• now(): ITS time (assumes synchronized)
• maybe_now(): ITS time only if synchronized
• is_synchronized(): boolean check
• utc_offset(): current offset between ITS and UTC
• from_system_clock(...): convert a system_clock::time_point to ITS

Example: check and print ITS time

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
#include <cube/time/clock.hpp>
#include <chrono>
#include <iostream>

int main()
{
    using namespace std::chrono;

    if (!cube::time::EtsiItsClock::is_synchronized()) {
        std::cout << "ITS clock is NOT synchronized yet\n";
        return 0;
    }

    auto now_its = cube::time::EtsiItsClock::now();
    auto since_epoch = duration_cast<milliseconds>(now_its.time_since_epoch());
    std::cout << "ITS time: " << since_epoch.count()
              << " ms since 2004-01-01T00:00:00Z (TAI)\n";

    return 0;
}

Example: safe access (no crash when unsynced)

1
2
3
4
5
6
7
8
if (auto maybe_its = cube::time::EtsiItsClock::maybe_now()) {
    using std::chrono::duration_cast;
    using std::chrono::seconds;
    auto its_s = duration_cast<seconds>(maybe_its->time_since_epoch()).count();
    std::cout << "ITS time: " << its_s << " s\n";
} else {
    std::cout << "ITS time not available (not synchronized)\n";
}

4. Getting the TAI–UTC Offset

Some V2X stacks (such as cube-tiny-stack) need the current TAI–UTC offset (leap seconds) to format or validate timestamps.

A C++ helper is provided:

1
2
3
4
5
6
7
8
9
10
11
#include <cube/time/tai.hpp>
#include <chrono>
#include <iostream>

int main()
{
    auto offset = cube::time::tai_utc_offset();
    std::cout << "Current TAI-UTC offset: "
              << offset.count()
              << " seconds\n";
}

This should match what you see in:

1
cube-timectl show

and what chrony currently believes.

5. Converting from system_clock

If you already have a timestamp in std::chrono::system_clock (for example, a log entry or sensor timestamp), you can convert it to ITS directly:

1
2
auto sys_now = std::chrono::system_clock::now();
auto its_now = cube::time::EtsiItsClock::from_system_clock(sys_now);

This applies the current ITS–UTC offset and returns an ITS time point.

6. Notes

• The ITS epoch is 2004-01-01, not 1970-01-01
• ITS uses TAI seconds; UTC has leap seconds, TAI does not
• This is why TAI–UTC is tracked explicitly
• If PPS/GNSS disappears, the clock may temporarily stay synchronized. Verify with cube-timectl show.