sample_messages
Inspect recent ROS 2 messages from a topic to debug or analyze data. Read-only, supports live and mock modes.
Instructions
ROS 2 graph only; on a DDS-only setup use list_endpoints (topics and wiring) or peek_dds_samples on DCPSPublication / DCPSSubscription (raw discovery records). Peek up to count recent ROS 2 messages from topic. count defaults to 5 and is silently clamped to 50. Returns a SampleResult {topic, count, samples, mode_effective, note} where count is the actual number of samples returned (may be 0) and mode_effective is live or mock. Live mode runs ros2 topic echo --csv --once with a short timeout, so the result is empty when no publisher is active and at most one message comes back. Arrays: by default ros2 topic echo cuts arrays at 128 elements (a 541-beam LaserScan loses beams 128 and up); the cut is listed under _truncated_after_columns in the sample payload and in note (cut strings and bytes are listed under _truncated_columns). Raise max_array_length (up to 65536, or null for no cut) to read more, or set arrays_summary_only to see only the non-array fields. A message over the 1 MiB size cap (TOPICFORGE_MAX_SAMPLE_BYTES) is dropped and note says so. samples[i].timestamp_ns is the message's header.stamp (publish time) when the message is Header-stamped, and 0 for headerless types (e.g. std_msgs/String). The live parser exposes fields as positional CSV columns under samples[i].payload keys col_0, col_1, ..., with the verbatim CSV row under the reserved _raw_text key. Mock mode returns structured samples for the fictional demo robot. Raises an MCP error when no ros2 CLI is available. Read-only; never publishes. Distinct from peek_dds_samples, which reads the raw DDS layer.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | Maximum number of recent messages to return. Defaults to 5; silently clamped to 50 (the hard cap that keeps tool output bounded; read it from `health_check.max_sample_count`). Negative values raise an error. The returned `SampleResult.count` reflects the actual number of samples produced: it can be lower than the request (empty topic, timeout, mock fixture shorter than requested). | |
| topic | Yes | Fully qualified ROS2 topic name starting with `/`, e.g. `/cmd_vel` or `/camera/image_raw`. Each `/`-separated segment must start with a letter or underscore and contain only letters, digits, and underscores; everything else (whitespace, quotes, shell metacharacters, `//`, trailing `/`) is rejected before reaching the `ros2` CLI. | |
| max_array_length | No | Longest array, string or bytes value to return in full, 1..65536; longer ones are cut. A cut array is listed in the sample's `_truncated_after_columns` (index of the last kept column); a cut string or bytes value is kept as its first N characters plus `...` and listed in `_truncated_columns`. Defaults to 128, the `ros2 topic echo` default, which cuts a 541-beam `LaserScan` after 128 ranges. Pass null to return everything in full (large for images and point clouds; a message over the server's size cap, 1 MiB by default, is dropped with a note, and a very large message may not print within the echo timeout). | |
| arrays_summary_only | No | When true, array fields are replaced by a short type and length summary instead of their elements. Use it to inspect the non-array fields of large messages (images, scans, point clouds). Defaults to false. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Why `samples` is empty or limited, when the cause is not obvious (for example payload decoding is disabled for DDS user topics). `None` when there is nothing to add. | |
| count | Yes | Number of samples actually returned. May be 0 (no publisher active in live mode, or empty mock fixture), less than the requested count (topic yielded fewer messages within the timeout), or capped by the the silent maximum of 50: request `count > 50` and you will receive at most 50 without warning. | |
| topic | Yes | Topic the samples were taken from, echoed from the request. | |
| samples | Yes | The sampled messages, ordered as received from the backend. | |
| mode_effective | Yes | Runtime mode the adapter served this response in: `live` (real ROS2 introspection) or `mock` (deterministic fixtures). Lets a caller tell a real graph from a demo one without calling `health_check`. |