Robot diagnostics with MCP

Wendy exposes ROS 2 diagnostics to AI assistants over the active direct or cloud device connection. These tools help distinguish missing capabilities, failed subscriptions, and topics that produced no readings during an observation.

Inspect a sensor

1. Call wendy_status, then connect using device_connect with a selector from device_list. Call wendy_tools with {"groups":["robotics"]} to list the ROS 2 tools used below.
2. Call ros2_topics to discover topic names, message types, and middleware.
3. Call ros2_topic_info with the selected topic to inspect publisher counts and verbose endpoint information, including QoS.
4. For PointCloud2 or LaserScan, call ros2_lidar_summary for device-side decoding, directional distances, and bounded XYZ samples. For other types, call ros2_topic_sample for decoded messages, or ros2_topic_hz for rate measurements from a subscription on the device.

For example, after discovering an odometry topic named /odom, request:

{
  "topic": "/odom",
  "count": 3,
  "duration_seconds": 10,
  "max_bytes": 32000
}

Use these arguments with ros2_topic_sample. The same bounded observation parameters are available on ros2_topic_hz. The optional domain_id selects a DDS domain; otherwise the agent uses its ROS 2 app configuration. Inspect the tool schema for defaults and limits.

The default scope: "app" uses Wendy's existing ROS 2 app sidecar and preserves its network isolation. See Wendy for ROS 2 for app configuration, discovery scope, and middleware setup. Custom messages need compatible typesupport in the sidecar. A topic can appear in discovery even when its message cannot be decoded.

Inspect robot sensors without a ROS 2 app

Robot firmware and host services can publish DDS sensor data while no Wendy ROS 2 app is running. Explicitly choose scope: "host" and the robot's known domain_id to inspect that graph. For example, if the robot uses domain 0:

{ "scope": "host", "domain_id": 0, "duration_seconds": 60 }

Pass these arguments to ros2_topics, then keep the same scope and domain on ros2_topic_info, ros2_topic_sample, ros2_topic_hz, and ros2_lidar_summary. A domain override by itself continues to inspect the app graph; it never enables host inspection.

Host inspection uses a separate stock ROS Humble/FastRTPS inspector on the device's host network. First use may download ros:humble-ros-base; retry if image preparation exceeds the bounded request. The inspector runs without root privileges or Linux capabilities, with its own IPC namespace, a read-only root, and UDP-only DDS. It does not expose host shared memory, alter an app's entitlements, or deploy an app. An idle inspector is retained for later requests; topic discovery runs without a persistent ROS daemon and subscriptions end with their request.

Results include inspection_scope, inspection_domain_id, inspection_rmw, and inspection_distro. The client requires the agent to acknowledge host scope; an older agent cannot silently return app-scoped observations. Host inspection is limited to topic discovery, endpoint information, samples, rates, and LiDAR summaries. Service calls, actions, parameter changes, and raw ROS execution cannot select this scope.

Standard ROS sensor/navigation types can be inspected when the publisher is reachable and its DDS/QoS settings interoperate. Custom Unitree message types are not bundled with the stock image: use an app image containing their typesupport or a robot adapter for decoded samples. No topics or readings still means unknown; check the domain, network interface/routing, middleware and publisher QoS.

Interpret the result

• Discovered means a topic was found in the ROS graph. It does not prove that samples are arriving. Topic lists omit publisher counts; use the targeted info tool to inspect them.
• Observed means the subscription returned messages or rate measurements within the bounded request. Inspect the stop reason and any error as well.
• Unknown means the request did not establish usable observations. It must not be interpreted as clear space or a working sensor.
• Source freshness needs a known clock. A generic topic tool reception timestamp is measured at the MCP client and cannot establish acquisition age. LiDAR summaries include source timestamps and device-side clock diagnostics; source_age_seconds is a signed offset against clock_basis and does not prove synchronization. Freshness remains unverified without a known clock relationship. Do not compare sensor timestamps to the chat session clock.

Observation stops at its count, duration, or output limit. Partial observations can therefore contain fewer samples than requested. Large images and raw point clouds can exceed the output budget. Use ros2_lidar_summary for standard LiDAR messages; it decodes and summarizes them on the device using sensor-compatible QoS. Its directions are in the reported output frame. Request a verified robot body frame with target_frame before interpreting sectors as robot-relative; the tool resolves TF at the source timestamp. Filtering, bounded point counts, and missing returns can leave coverage incomplete. See Inspect LiDAR in Wendy Chat for examples and clock handling. Other large messages need a smaller diagnostic topic or an app that summarizes them locally. Topic info reports endpoint QoS; generic sampling and rate tools use the sidecar defaults and do not accept QoS overrides.

With an updated Wendy agent, unsuccessful echo and hz processes return their exit failure and a bounded stderr tail, including decoding errors. Older agents may still turn these failures into empty streams; an empty observation continues to mean unknown.

Discover robot app capabilities

A deployed app can expose its own MCP server with an entitlement:

{ "type": "mcp", "port": 3000 }

Wendy prefixes each tool with the app name and refreshes app tools after device connection changes and as running apps change. An app deployed after the MCP session starts can therefore become available without restarting the session. Discovery is asynchronous; clients receive tool-list change notifications and can list tools again. wendy_status and wendy://diagnostics report proxy discovery failures.

From diagnostics to navigation

ROS 2 observations support diagnosis. A robot's local runtime must establish readiness and maintain it throughout motion. That runtime needs sensor freshness and coverage, pose and measured velocity, valid coordinate transforms, a robot footprint, and tested stopping behavior.

The repository's Examples/RobotNavigation app implements this layer with Nav2, a separate velocity guard, a motor watchdog, and persistent goal supervision. It exposes robot_status, navigation_goal, navigation_status, navigation_renew, navigation_cancel, and robot_stop through its app MCP entitlement. Tools appear under the app-name prefix after deployment. Defaults disable motor output and report the inputs and commissioning checks still needed.

Use robot_status before submitting a goal. Goal acceptance does not establish arrival. navigation_status does not renew the finite supervision lease; renewal must be explicit. Cancellation inhibits velocity immediately, and remains stopping until Nav2's action has ended and fresh odometry confirms rest. Restarted goals are abandoned, never automatically resumed. Device speed, footprint, clearance, braking and watchdog configuration cannot be raised through MCP.

For person approach, the app's robot_observe returns a matching annotated RGB frame and expiring target IDs. approach_person uses synchronized calibrated depth and capture-time TF to choose a standoff endpoint for the local planner. Missing depth/calibration or a stale/ambiguous target blocks submission. Target loss or excess motion cancels the goal without switching identity. The baseline HOG detector can miss seated people and cannot exclude mirrors; deployments need an appropriate detector and a commissioned environment.

The app requires standard scan/odometry/IMU and calibrated RGB-D inputs. A host diagnostic topic or ordinary camera snapshot is not a substitute for those interfaces. The generic diagnostic tools do not perform navigation or provide a hardware emergency stop. See Examples/RobotNavigation/README.md for the isolated ROS simulation test, input contracts and device commissioning requirements.