docs(hardware): add ros2 integration guidance (#1874)

2026-02-26 04:57:37 -05:00
parent 035b19ffba
commit e2f23f45eb
1 changed files with 48 additions and 0 deletions
@@ -0,0 +1,48 @@
+# ROS2 Integration Guidance
+
+This note captures the recommended integration shape for ROS2/ROS1 environments.
+It is intentionally architecture-focused and keeps ZeroClaw core boundaries stable.
+
+## Recommendation
+
+Use the plugin/adapter route first.
+
+- Keep robotics transport in an integration crate or module that bridges ROS topics/services/actions to ZeroClaw tools/channels/runtime adapters.
+- Keep high-frequency control loops in ROS-native execution contexts.
+- Use ZeroClaw for planning, orchestration, policy, and guarded action dispatch.
+
+Deep core coupling should be a last resort and only justified by measured latency limits that cannot be met with a bridge.
+
+## Why This Is The Default
+
+- Upgrade safety: trait-based adapters survive upstream changes better than core patches.
+- Blast-radius control: transport details stay outside security/runtime core modules.
+- Reproducibility: integration behavior is easier to test and rollback when isolated.
+- Security posture: approval, policy, and gating remain centralized in existing ZeroClaw paths.
+
+## Real-Time Boundary Rule
+
+Do not route hard real-time motor/safety loops through LLM turn latency.
+
+- ROS node graph handles tight-loop control and watchdogs.
+- ZeroClaw emits intent-level commands and receives summarized state.
+- Safety-critical stop paths stay local to robot runtime regardless of agent health.
+
+## Suggested Baseline Architecture
+
+1. ROS2 bridge node subscribes to high-rate sensor topics.
+2. Bridge performs local reduction/windowing and forwards compact summaries to ZeroClaw.
+3. ZeroClaw decides intent/tool calls under existing policy and approval constraints.
+4. Bridge translates approved intents into ROS commands with bounded command-rate limits.
+5. Telemetry and fault states flow back into ZeroClaw for reasoning and auditability.
+
+## Escalation Criteria For Core Integration
+
+Consider deeper ZeroClaw runtime integration only when all are true:
+
+- Measured bridge overhead is a validated bottleneck under production-like load.
+- Required latency/jitter budgets are written and reproducible.
+- The proposed core change has clear rollback and subsystem ownership.
+- Security and policy guarantees remain equivalent or stronger.
+
+If those conditions are not met, stay with adapter/plugin integration.