Refactor node layout, enable clang checks, and format code

Author: mkassimi98

.github/workflows/ci.yml

@@ -0,0 +1,59 @@
+name: ros2-gst-video-bridge-ci
+
+on:
+  pull_request:
+  push:
+    branches: ["main", "ft/1stversion_w_srt"]
+  schedule:
+    - cron: "0 3 * * *"
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup ROS 2 Humble
+        uses: ros-tooling/setup-ros@v0.7
+        with:
+          required-ros-distributions: humble
+
+      - name: Build
+        run: |
+          source /opt/ros/humble/setup.bash
+          colcon build --event-handlers console_direct+
+
+      - name: Test
+        run: |
+          source /opt/ros/humble/setup.bash
+          colcon test --event-handlers console_direct+
+          colcon test-result --all --verbose
+
+  nightly-matrix:
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup ROS 2 Humble
+        uses: ros-tooling/setup-ros@v0.7
+        with:
+          required-ros-distributions: humble
+
+      - name: Build
+        run: |
+          source /opt/ros/humble/setup.bash
+          colcon build --event-handlers console_direct+
+
+      - name: Run matrix
+        run: |
+          chmod +x src/ros2_gst_video_bridge/scripts/run_transport_codec_matrix.zsh
+          src/ros2_gst_video_bridge/scripts/run_transport_codec_matrix.zsh "$PWD" /tmp/matrix.csv
+
+      - name: Upload report
+        uses: actions/upload-artifact@v4
+        with:
+          name: transport-codec-matrix-report
+          path: /tmp/matrix.csv

CMakeLists.txt

@@ -14,7 +14,7 @@ option(ROS2_GST_VIDEO_BRIDGE_ENABLE_CLANG_FORMAT_CHECK "Enable clang-format chec
 option(ROS2_GST_VIDEO_BRIDGE_ENABLE_AMENT_LINT "Enable ament_lint_auto checks" OFF)
 
 if(ROS2_GST_VIDEO_BRIDGE_ENABLE_CLANG_TIDY)
-  find_program(CLANG_TIDY_EXE NAMES clang-tidy)
+  find_program(CLANG_TIDY_EXE NAMES clang-tidy clang-tidy-18 clang-tidy-17 clang-tidy-16 clang-tidy-15)
   if(CLANG_TIDY_EXE)
     set(CMAKE_CXX_CLANG_TIDY ${CLANG_TIDY_EXE})
     message(STATUS "clang-tidy enabled: ${CLANG_TIDY_EXE}")
@@ -27,11 +27,12 @@ find_package(ament_cmake REQUIRED)
 find_package(rclcpp REQUIRED)
 find_package(sensor_msgs REQUIRED)
 find_package(std_msgs REQUIRED)
+find_package(ros2_gst_video_bridge_msgs REQUIRED)
 find_package(PkgConfig REQUIRED)
 pkg_check_modules(GSTREAMER REQUIRED gstreamer-1.0 gstreamer-app-1.0)
 
 if(ROS2_GST_VIDEO_BRIDGE_ENABLE_CLANG_FORMAT_CHECK)
-  find_program(CLANG_FORMAT_EXE NAMES clang-format)
+  find_program(CLANG_FORMAT_EXE NAMES clang-format clang-format-18 clang-format-17 clang-format-16 clang-format-15)
   if(CLANG_FORMAT_EXE)
     file(GLOB_RECURSE ROS2_GST_VIDEO_BRIDGE_FORMAT_FILES CONFIGURE_DEPENDS
       "${CMAKE_CURRENT_SOURCE_DIR}/include/*.h"
@@ -52,6 +53,13 @@ endif()
 add_executable(gst_video_bridge_node
   src/main.cc
   src/gst_video_bridge_node.cc
+  src/node/core.cc
+  src/node/lifecycle.cc
+  src/node/modes.cc
+  src/node/streaming.cc
+  src/node/recovery.cc
+  src/node/fallback.cc
+  src/node/observability.cc
   src/core/config_loader.cc
   src/core/pipeline_builder.cc
   src/runtime/capability_probe.cc
@@ -76,6 +84,7 @@ ament_target_dependencies(gst_video_bridge_node
   rclcpp
   sensor_msgs
   std_msgs
+  ros2_gst_video_bridge_msgs
 )
 
 install(TARGETS gst_video_bridge_node

README.md

@@ -25,7 +25,7 @@ Generic ROS 2 video bridge that subscribes to a raw `sensor_msgs/Image` topic an
 	- `transport.reconnect.max_attempts`
 
 - Codec parameters:
-	- `codec.name` (`h264`, `h265`, `mjpeg`)
+	- `codec.name` (`auto`, `h264`, `h265`, `mjpeg`)
 	- `codec.profile`
 	- `codec.tune`
 	- `codec.rate_control`
@@ -119,6 +119,16 @@ ros2 launch ros2_gst_video_bridge gst_video_bridge_minimal.launch.py \
 	"sink_uri:=srt://0.0.0.0:9000?mode=listener"
 ```
 
+For Bayer cameras, enable optional debayer (color output before bridge):
+
+```bash
+ros2 launch ros2_gst_video_bridge gst_video_bridge_minimal.launch.py \
+	input_topic:=/camera_driver_uv_example/vis/image_raw \
+	enable_debayer:=true \
+	debayer_output_topic:=/camera_driver_uv_example/vis/image_color \
+	"sink_uri:=srt://0.0.0.0:9000?mode=listener"
+```
+
 ### 4) Launch SRT receiver as caller (Terminal C)
 
 ```bash
@@ -180,13 +190,101 @@ Under `config/profiles/`:
 
 ### Runtime metrics
 
-The node publishes runtime metrics on `~/runtime_metrics` (`std_msgs/msg/String`), including:
+The node publishes runtime metrics on `~/runtime_metrics` (`std_msgs/msg/String`) for backward compatibility, and typed control-plane topics via `ros2_gst_video_bridge_msgs`:
+
+- `~/runtime_status` (`ros2_gst_video_bridge_msgs/msg/RuntimeStatus`)
+- `~/runtime_events` (`ros2_gst_video_bridge_msgs/msg/RuntimeEvent`)
+- `~/set_streaming_profile` (`ros2_gst_video_bridge_msgs/srv/SetStreamingProfile`)
+
+Fields include:
 
 - state (`connecting|streaming|degraded|reconnecting|failed`)
 - `fps_in`, `fps_out`
 - dropped frame counters
 - reconnect counter
 - latency estimate in milliseconds
+- selected codec/encoder and fallback flags
+- adaptation profile and current adaptation level
+
+Operator runtime command example:
+
+```bash
+ros2 service call /gst_video_bridge/set_streaming_profile ros2_gst_video_bridge_msgs/srv/SetStreamingProfile "{adaptation_profile: balanced, reset_counters: false}"
+```
+
+First-failure snapshot:
+
+- On the first streaming failure in a session, the bridge publishes `FIRST_FAILURE_SNAPSHOT` on `~/runtime_events`.
+- Payload includes session/stream IDs, runtime state, selected codec/encoder, sink URI, fallback status, and effective pipeline string.
+
+### Automatic codec selection (`codec.name:=auto`)
+
+When `codec.name` is set to `auto`, the node inspects available encoder implementations via
+`gst-inspect-1.0` and resolves to the best codec for the selected machine profile.
+
+Selection order by machine profile:
+
+| Machine profile | Preferred implementation classes |
+|---|---|
+| `jetson` | `hw:nvidia-v4l2` -> `hw:nvidia` -> other HW (`v4l2`/`omx`/`vaapi`) -> `sw` |
+| `x86` | `hw:vaapi` -> `hw:v4l2` -> NVIDIA HW -> `sw` |
+| `raspi` | `hw:v4l2` -> `hw:omx` -> `sw` |
+| `generic` | `hw:vaapi` -> `hw:v4l2` -> NVIDIA HW -> `hw:omx` -> `sw` |
+
+Codec tie-break preference is stable: `h264` -> `h265` -> `mjpeg`.
+
+If `codec.name:=auto` picks a hardware encoder and runtime fails repeatedly while streaming,
+the bridge now falls back automatically to a software encoder for the same codec.
+This fallback is cross-platform (Jetson/x86/Raspberry/generic) and uses detected encoders from
+`gst-inspect-1.0`, not Jetson-only logic.
+
+Fallback sensitivity can be tuned with:
+
+```bash
+-p runtime.hw_fallback_failures:=3
+```
+
+Adaptive resilience controls:
+
+```bash
+-p runtime.adaptation.enabled:=true \
+-p runtime.adaptation.profile:=balanced \
+-p runtime.adaptation.interval_ms:=2000 \
+-p runtime.adaptation.cooldown_ms:=5000
+```
+
+Supported adaptation profiles:
+
+- `conservative`
+- `balanced`
+- `aggressive`
+
+### Validation automation
+
+Codec/transport matrix script:
+
+```bash
+chmod +x /home/ccu-001/ws_dev/src/ros2_gst_video_bridge/scripts/run_transport_codec_matrix.zsh
+/home/ccu-001/ws_dev/src/ros2_gst_video_bridge/scripts/run_transport_codec_matrix.zsh /home/ccu-001/ws_dev /tmp/matrix.csv
+```
+
+Soak run script:
+
+```bash
+chmod +x /home/ccu-001/ws_dev/src/ros2_gst_video_bridge/scripts/run_soak_profile.zsh
+/home/ccu-001/ws_dev/src/ros2_gst_video_bridge/scripts/run_soak_profile.zsh /home/ccu-001/ws_dev 1800 generic low_latency /camera/image_raw
+```
+
+Release/versioning policy documents:
+
+- `docs/VERSIONING.md`
+- `docs/RELEASE.md`
+
+Example:
+
+```bash
+ros2 run ros2_gst_video_bridge gst_video_bridge_node --ros-args -p codec.name:=auto
+```
 
 ### Discoverability modes (Phase 3)
 

docs/RELEASE.md

@@ -0,0 +1,25 @@
+# Release Gate
+
+## Required Gates
+
+1. PR gate
+- Build + unit tests + smoke tests must pass.
+
+2. Nightly gate
+- Transport/codec matrix script must run and generate report.
+
+3. Release gate
+- Soak run >= 30 minutes per target machine class (Jetson/x86/Raspi/generic as available).
+
+## KPIs
+
+Release candidate is blocked if any threshold regresses vs previous stable:
+- reconnects/hour
+- dropped frames ratio
+- startup success ratio
+- median and p95 latency estimate
+
+## Rollback
+
+- Keep previous release profile bundle and parameter files.
+- Revert to last stable tag and documented config migration pair.

docs/VERSIONING.md

@@ -0,0 +1,20 @@
+# Versioning Policy
+
+## Scope
+
+This policy applies to:
+- Runtime node behavior and parameters
+- Pipeline profile semantics
+- Interface contracts in ros2_gst_video_bridge_msgs
+
+## SemVer Rules
+
+- MAJOR: incompatible contract change (message field removals, parameter removals/renames without migration support).
+- MINOR: backward-compatible additions (new parameters with defaults, new message fields preserving old behavior).
+- PATCH: bug fixes and performance/stability improvements without contract break.
+
+## Contract Stability
+
+- `runtime_status` and `runtime_events` topics are versioned by package version.
+- Config schema is tracked as `v1alpha`, then `v1` on first production release.
+- Deprecated fields require at least one MINOR release overlap before removal.

include/ros2_gst_video_bridge/core/config_loader.hpp

@@ -11,21 +11,19 @@
 #include <string>
 #include <vector>
 
-namespace ros2_gst_video_bridge
-{
+namespace ros2_gst_video_bridge {
 
-class ConfigLoader
-{
+class ConfigLoader {
 public:
-  static GstBridgeConfig loadFromNode(rclcpp::Node & node);
-  static std::vector<std::string> validate(const GstBridgeConfig & config);
-  static std::string toDebugString(const GstBridgeConfig & config);
+  static GstBridgeConfig loadFromNode(rclcpp::Node& node);
+  static std::vector<std::string> validate(const GstBridgeConfig& config);
+  static std::string toDebugString(const GstBridgeConfig& config);
 
 private:
-  static void applyMachineProfileDefaults(GstBridgeConfig & config);
-  static void applyStreamProfileDefaults(GstBridgeConfig & config);
+  static void applyMachineProfileDefaults(GstBridgeConfig& config);
+  static void applyStreamProfileDefaults(GstBridgeConfig& config);
 };
 
-}  // namespace ros2_gst_video_bridge
+} // namespace ros2_gst_video_bridge
 
-#endif  // ROS2_GST_VIDEO_BRIDGE__CORE__CONFIG_LOADER_HPP_
+#endif // ROS2_GST_VIDEO_BRIDGE__CORE__CONFIG_LOADER_HPP_