TimeSlave Configuration#

The behavior of the TimeSlave is controlled via a JSON configuration file. The schema is defined in score/time_slave/src/application/configuration/time_slave_config_schema.json and covers all runtime parameters: network interface, gPTP timing, PHC adjustment, shared-memory path, and platform-specific options.

Configuration file location#

The configuration file is resolved in the following order:

  1. --config <path> command-line argument.

  2. TIMESLAVE_CONFIG environment variable.

  3. ./etc/time_slave_config.json relative to the process working directory.

If no configuration file is found at the resolved path, TimeSlave uses built-in defaults (equivalent to the schema defaults) and logs an informational message.

For backwards compatibility, the GPTP_IFACE environment variable (when set) still overrides the iface_name field after the JSON config is loaded.

Command-Line Arguments#

The following command-line arguments are available to configure the TimeSlave at runtime:

--config <path>

Path to the JSON configuration file. When provided, it takes precedence over the TIMESLAVE_CONFIG environment variable and the default ./etc/time_slave_config.json path. See TimeSlave Configuration for the full resolution order.

Default Configuration (GptpEngineOptions)#

The following table lists all available options and their default values as defined in the source code. Currently, only iface_name can be changed without recompiling the application.

Table 3 GptpEngineOptions Default Values#

Option

Default Value

Description

iface_name

"emac0"

The network interface to use for gPTP traffic.

pdelay_req_interval_ms

1000

The interval in milliseconds for sending Peer-Delay measurement requests.

pdelay_warmup_ms

2000

The initial delay in milliseconds before the first Peer-Delay request is sent.

sync_timeout_ms

3300

The time in milliseconds without receiving a PTP Sync message before a timeout is declared and the clock is considered unreliable.

jump_future_threshold_ns

500'000'000

The threshold in nanoseconds (500 ms) for detecting a significant forward time jump.

domain_number

0

The gPTP domain number. The TimeSlave will only interact with a PTP master in the same domain.

phc_config

disabled

Configuration for hardware clock (PHC) adjustments. Disabled by default.

Validation#

time_slave_config_schema.json defines the type and range (minimum / maximum) of every option. The TimeSlave enforces these constraints when it loads the file. If any value has the wrong type (including a JSON boolean where an integer is expected), lies outside its allowed range, or if the file contains a key the schema does not define (matching "additionalProperties": false, for example a misspelled option name), the TimeSlave logs one error naming each offending field and refuses to start (initialization fails). The same happens if the file cannot be read or parsed. Values are never silently clamped or applied, so a typo such as "domain_number": 128 is reported at startup instead of causing every Sync message to be ignored.

The parser enforces the keys, types and ranges listed in config_schema_table.h; defaults come from the C++ config structs. A unit test (config_schema_consistency_test) compares both with time_slave_config_schema.json in both directions and fails if the schema uses a constraint the parser does not implement, so they cannot drift apart unnoticed. When changing the schema, update config_schema_table.h and the struct defaults accordingly.

PHC configuration#

To enable PTP Hardware Clock adjustment, set "phc"."enabled" to true. The device field identifies the network interface whose PTP clock is adjusted (e.g. "emac0" on QNX, "eth0" on Linux):

{
    "phc": {
        "enabled": true,
        "device": "emac0",
        "step_threshold_ns": 100000000
    }
}

When disabled (the default), gPTP runs in slave-only mode without disciplining a hardware clock.

QNX-specific fields#

The optional "qnx" section holds QNX-only settings (ignored on Linux):

{
    "qnx": {
        "bpf_device_path": "/dev/bpf",
        "see_sent": true
    }
}
bpf_device_path

Path to the BPF (Berkeley Packet Filter) clone device used for raw Ethernet frame capture. Defaults to /dev/bpf.

see_sent

When true, sent frames are also delivered to the RX BPF. This is required to capture TX hardware timestamps for Pdelay_Req T1 measurement. Defaults to false.

Example Invocation#

# Start the TimeSlave with a custom configuration file
./time_slave --config etc/time_slave_config.json

# Use a non-default interface without a config file (backwards compat)
GPTP_IFACE=emac1 ./time_slave

Example#

A representative QNX configuration:

{
    "iface_name": "emac0",
    "domain_number": 0,
    "pdelay_req_interval_ms": 1000,
    "pdelay_warmup_ms": 2000,
    "sync_timeout_ms": 3300,
    "jump_future_threshold_ns": 500000000,
    "shm_path": "/gptp_shmem",
    "phc": {
        "enabled": true,
        "device": "emac0",
        "step_threshold_ns": 100000000
    },
    "qnx": {
        "bpf_device_path": "/dev/bpf",
        "see_sent": true
    }
}