Add a ROS 2 node example

[donald-heddesheimer]

An ament package under examples/ros2/: a timer-driven node whose callback runs a three-stage CUDA pipeline, publishes its own latency on ~/latency_ms, and holds itself to its timer period. Built with colcon against /opt/ros/humble and run on real hardware before shipping.

Deliberately outside the root CMakeLists.txt and outside CI — runners have no ROS 2, and a header-only library should not make every consumer care about a dependency they do not have. examples/CMakeLists.txt names its source explicitly, so the new subdirectory is inert to the existing build. Verified: root build and 4/4 tests unchanged.

The demo earns its defaults

The first version ran at 20 ms with the callback taking 449 µs — a deadline bar at 2%, which teaches nothing. Defaults are now 5 ms and 384 taps, so the pipeline uses about 40% of its period: a loop comfortably meeting a rate you can then take away from it.

And the run that came out of that is better than anything I would have staged. Eight seconds at the defaults:

  callback   host    1572  1.95ms  1.99ms  2.01ms  7.80ms  6.05ms  █          ▂
  normalize  device  1572  31.4µs  27.6µs  28.7µs  5.98ms  5.95ms  █          ▂
  detect     device  1572  1.87ms  1.91ms  1.92ms  1.93ms   252µs  ▃       ▂▂▃█

  MISSED    1571/1572 iterations inside budget (99.9%); worst 7.80ms at 156% of budget

  slowest iterations
    #270    7.80ms  normalize 28.7µs · detect 1.68ms · threshold 25.6µs
    #269    5.99ms  normalize 5.98ms · detect 1.69ms · threshold 25.6µs

Iteration #269 spent 5.98 ms in normalize, a stage whose median is 27.6 µs — 220x, on a kernel doing one multiply-add per element. The very next callback took 7.80 ms with every GPU stage at its normal duration, so that one was blocked before it ever reached the GPU. Two consecutive missed frames, one caused by the GPU and one not, and the report separates them. A dashboard averaging the topic would show 1.95 ms and nothing else.

The example README also documents -p period_ms:=2.0, which produces 92% met with p95 sitting exactly on the deadline — the case where a healthy mean hides a real problem.

Nothing is synthetic-slowdown theatre. The stages are arithmetic rather than a real detector, but they are real GPU work with real launch costs, and every number above came off the machine.

Two things worth flagging

A real bug this turned up, not fixed here. At period_ms:=2.5 the deadline line printed MISSED 3156/3157 iterations inside budget (100.0%) — the share is %.1f of 99.968%, which rounds up. A verdict reading MISSED beside 100.0% is exactly the confusion that line exists to prevent. The fix belongs in WriteBudget, which #8 already rewrites, so putting it here would conflict; I'll add it to #8 rather than leave it or duplicate it.

The maintainer email in package.xml is donald-heddesheimer@users.noreply.github.com rather than the address in your commits, since a package.xml gets scraped by ROS index tooling. Change it if you would rather it be the real one.

Build note for this machine

colcon build needed --cmake-args -DPython3_EXECUTABLE=/usr/bin/python3, because CMake found the miniforge python first and that one has no catkin_pkg. That is a local environment quirk rather than anything in the package, so it is not in the README.

[donald-heddesheimer]

Heads-up on merge order: this branch and #9 both add a paragraph to the Build and test section of the README, so whichever one you merge second will conflict there. Nothing else across the five open PRs conflicts — I test-merged every pair.

Merge them in whatever order suits you and tell me (or just merge); I'll rebase the loser rather than leave you to resolve it.