YAML Specification#

Complete reference for the thread configuration file used by agnocast_cie_thread_configurator.

Top-level Structure#

hardware_info:       # Optional: validated at startup (auto-generated by the prerun mode)
  model_name: "..."
  cpu_family: "..."

rt_throttling:       # Optional: validated against kernel settings
  period_us: 1000000
  runtime_us: 950000

callback_groups:     # Required: list of CallbackGroup configurations
  - id: ...
    ...

non_ros_threads:     # Optional: list of non-ROS thread configurations
  - name: ...
    ...

callback_groups#

Each entry configures one CallbackGroup's thread:

Field	Required	Description
`id`	Yes	CallbackGroup identifier (auto-generated by the prerun mode)
`policy`	Yes	Scheduling policy
`priority`	Yes (except `SCHED_DEADLINE`)	Thread priority or nice value
`affinity`	No	List of CPU cores to pin the thread to
`domain_id`	No	ROS domain ID (defaults to the current domain)
`runtime`	`SCHED_DEADLINE` only	Maximum execution time per period (ns)
`period`	`SCHED_DEADLINE` only	Period length (ns)
`deadline`	`SCHED_DEADLINE` only	Relative deadline from start of period (ns)

CallbackGroup ID Format#

The id is auto-generated and composed of the node name followed by callback identifiers separated by @:

/<node_name>@<Callback1>@<Callback2>...

Callback identifiers include: Subscription(<topic>), Timer(<period_ns>), Service(<name>), Client(<name>).

Tip

Use the prerun mode to discover the exact IDs for your application rather than constructing them manually.

Warning

If a node has multiple CallbackGroups with timers of the same period, their auto-generated IDs will collide. To avoid this, slightly offset the timer periods (e.g., 100ms and 100ms + 1ns).

Scheduling Policies#

Policy	Priority	Description
`SCHED_FIFO`	1–99 (99 = highest)	Real-time, first-in-first-out
`SCHED_RR`	1–99 (99 = highest)	Real-time, round-robin
`SCHED_OTHER`	-20–19 (nice value)	Default Linux scheduler
`SCHED_BATCH`	-20–19 (nice value)	Batch processing
`SCHED_IDLE`	-20–19 (nice value)	Lowest priority (nice value has no practical effect)
`SCHED_DEADLINE`	N/A	Deadline-based (requires `runtime`, `period`, `deadline`)

SCHED_DEADLINE#

For SCHED_DEADLINE, specify runtime, period, and deadline (in nanoseconds) instead of priority:

callback_groups:
  - id: /my_node/my_deadline_group@Timer
    policy: SCHED_DEADLINE
    runtime: 1000000      # 1 ms
    period: 10000000       # 10 ms
    deadline: 10000000     # 10 ms
    affinity: [2]

Note

SCHED_DEADLINE uses cgroup cpuset for CPU affinity, which requires cgroup v1. See Kernel boot parameter for setup.

Note

SCHED_DEADLINE configuration is applied after all other CallbackGroups have been configured.

non_ros_threads#

Threads not managed by the executor can also be configured. See Non-ROS Threads for how to use this feature in your application.

Field	Required	Description
`name`	Yes	Thread name string
`policy`	Yes	Scheduling policy (same options as callback_groups)
`priority`	Yes (except `SCHED_DEADLINE`)	Thread priority or nice value
`affinity`	No	List of CPU cores

rt_throttling#

Optional section to validate that the kernel's RT throttling settings match expectations:

Field	Description
`period_us`	Expected value of `kernel.sched_rt_period_us`
`runtime_us`	Expected value of `kernel.sched_rt_runtime_us`

The configurator reports an error at startup if the current kernel values don't match. These values must be pre-configured via /etc/sysctl.d/ (see RT Throttling).

hardware_info#

Optional section for hardware validation. If present, the configurator compares these values against the current system (via lscpu) and reports an error on mismatch. The prerun mode automatically populates this section.

Field	Source (`lscpu` field)	Example
`model_name`	Model name	`"Intel(R) Core(TM) i9-12900K"`
`cpu_family`	CPU family	`"6"`
`model`	Model	`"151"`
`threads_per_core`	Thread(s) per core	`"2"`
`frequency_boost`	Frequency boost	`"enabled"` or `"disabled"` (not all CPUs)
`cpu_max_mhz`	CPU max MHz	`"5200.0000"`
`cpu_min_mhz`	CPU min MHz	`"800.0000"`

Full Example#

hardware_info:
  model_name: "Intel(R) Core(TM) i9-12900K"
  cpu_family: "6"
  model: "151"
  threads_per_core: "2"
  cpu_max_mhz: "5200.0000"
  cpu_min_mhz: "800.0000"

rt_throttling:
  period_us: 1000000
  runtime_us: 950000

callback_groups:
  - id: /camera_node/image_cb_group@Subscription(/camera/image)
    policy: SCHED_FIFO
    priority: 90
    affinity: [0, 1]

  - id: /lidar_node/pointcloud_cb_group@Subscription(/lidar/points)
    policy: SCHED_FIFO
    priority: 85
    affinity: [2, 3]

  - id: /planning_node/planner_cb_group@Timer(100000000)
    policy: SCHED_DEADLINE
    runtime: 5000000
    period: 100000000
    deadline: 50000000
    affinity: [4]

  - id: /logging_node/default_cb_group@Subscription(/rosout)
    policy: SCHED_OTHER
    priority: 10

non_ros_threads:
  - name: sensor_driver
    policy: SCHED_FIFO
    priority: 95
    affinity: [5]