Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt

Use this file to discover all available pages before exploring further.

​
MCAP capture reference

roboticks.mcap_capture is a context manager that records selected ROS2 topics to an MCAP file for the duration of a with block. For a tutorial introduction, see Testing → MCAP capture; this page is the API reference. 
from roboticks import mcap_capture
Requires the mcap extra. Install with pip install 'roboticks[mcap]'. The bare roboticks package does not pull in the mcap or mcap-ros2-support libraries.

​
Signature

def mcap_capture(
    *,
    topics: list[str] | None = None,
    path: str | Path | None = None,
    upload_on: Literal["failure", "always", "never"] = "failure",
    compression: Literal["zstd", "lz4", "none"] = "zstd",
    chunk_size_bytes: int = 1 << 20,
    qos: rclpy.qos.QoSProfile | None = None,
    node: rclpy.node.Node | None = None,
) -> ContextManager[McapHandle]: ...

​
Parameters

ParameterTypeDefaultBehaviour
topicslist[str] | None["*"]Allowlist. Wildcards * and ** per rosbag2 semantics. None is treated as ["*"].
pathstr | Path | Nonetest_results/<test_id>.mcapLocal write path. Parents are mkdir -p’d.
upload_onLiteral["failure", "always", "never"]"failure"When the runner uploads the bag to the platform.
compressionLiteral["zstd", "lz4", "none"]"zstd"Per-chunk compression.
chunk_size_bytesint1 MiBMCAP chunk size before flush.
qosQoSProfilerclpy defaultQoS for subscribed topics.
nodeNodeephemeralReuse an existing node.

​
Returns (as context value)

An McapHandle with:
AttributeDescription
pathFinal local path of the MCAP file.
bytes_writtenBytes written at context exit.
topic_countsdict[str, int] — messages captured per topic.
uploadedbool — set in the __exit__ after upload decision.
upload_urlstr | None — platform URL if uploaded.

​
Behaviour

​
Allowlist semantics

PatternMatches
/topicexact
/parent/*immediate children of /parent
/parent/**recursive descendants of /parent
*all topics, immediate root level
**all topics, any depth
Subscriptions are created on first-seen — the recorder subscribes when a publisher appears on a matching topic, not at context entry. This avoids hangs waiting for topics that won’t appear.

​
Upload behaviour

upload_onAfter context exit
"failure"Uploads iff the surrounding test failed. Default.
"always"Uploads unconditionally.
"never"Local file only. The runner does not upload; the file is part of the test artifacts collected per workspace policy.
The “test failed” signal is read from the pytest test status at session-end. For non-pytest contexts (e.g. raw scripts), "failure" is treated as "always".

​
Threading

The recorder runs in a background thread spun up at context entry. It uses a dedicated rclpy executor; subscriptions don’t interfere with the test’s main executor.

​
Compression

OptionWall-clock costFile sizeUse when
zstd~5% over uncompressed~30% of rawdefault; nearly free
lz4~2%~50% of rawvery high-rate topics where zstd CPU is noticeable
none0%100%only when re-compressing downstream

​
Examples

​
Default (allow-all, upload-on-failure)

with mcap_capture() as bag:
    run_test()
# bag.path, bag.bytes_written, bag.topic_counts, bag.uploaded available here

​
Explicit topic allowlist

with mcap_capture(
    topics=["/cmd_vel", "/safety/*", "/tf"],
    path="captures/estop.mcap",
) as bag:
    run_test()
print(bag.topic_counts)
# {'/cmd_vel': 142, '/safety/estop_engaged': 1, '/tf': 880}

​
Always upload

with mcap_capture(upload_on="always") as bag:
    run_test()
assert bag.uploaded
assert bag.upload_url.startswith("https://app.roboticks.io/runs/")

​
Pytest fixture for session-scoped recording

import pytest
from roboticks import mcap_capture

@pytest.fixture(scope="session")
def session_bag():
    with mcap_capture(
        topics=["**"],
        path="captures/session.mcap",
        upload_on="always",
    ) as bag:
        yield bag

​
Limits

LimitValueBehaviour
Max in-flight bytes256 MiBExcess buffered to disk-spill chunk.
Max bag file size4 GiBRecorder rolls into <path>.1.mcap, .2.mcap, …; upload includes all parts.
Max recorded topics1024More than 1024 distinct topics raises LimitExceeded.
Max concurrent captures per process4More than 4 nested mcap_capture blocks raises.

​
File layout

<test_results_dir>/
  <test_id>.mcap            # default per-test path
  captures/
    estop.mcap              # explicit path
  uploads.manifest.json     # what the runner uploaded, where
The uploads.manifest.json is read by rbtk when correlating local artifacts to a remote run.

​
Next

MCAP capture tutorial

Worked examples and storage-cost guidance.

LLM triage

How the platform reads your MCAP to explain failures.

Fault injection

Pair with mcap_capture for failure forensics.

Pricing

Hot and archive storage costs.