Start and stop capture on demand

Record data only during the moments you care about, such as a demonstration, a test run, or a production cycle, instead of capturing all the time. You start and stop recording with a command, and every component you list starts and stops together.

Use capture on demand to:

• Record sequences, time windows of data that you train on as one example. To create a sequence over data you already captured, see Sequences.
• Capture from several components together, only while something is happening.
• Turn on capture for a component that has no data capture configured.

To keep only camera frames where an ML model detects something, use a filtered camera instead. To control when captured data uploads, rather than what is captured, see Conditional sync.

Before you start

• A machine running the latest version of viam-server, with a data management service, such as data_manager/builtin, configured. The minimum versions are v0.116.0 for capture control sensors, v0.127.0 for sequences, and v0.130.0 for capturing components that have no data capture configured.
• The components you want to record, such as a camera and an arm, configured on the machine.

How capture on demand works

The data management service can read capture settings from a sensor on the machine, called a capture control sensor. It polls the sensor’s Readings method 10 times per second and applies what the sensor returns: which components to capture, how often, with which tags, and which sequences are open.

The capture-control module is a ready-made capture control sensor. You list the components it controls in its configuration, then send it DoCommand calls to start and stop recording.

While the sensor lists a component, the frequency it sets overrides that component’s capture frequency, and the tags it sets replace the data management service’s tags for that component. The two lists of tags aren’t merged. Your component configuration is left unchanged. When the sensor stops listing a component, the component returns to its own capture settings. If it has none, it stops capturing. If the data management service has capture_disabled set to true, it ignores the sensor.

1. Add the capture-control sensor to your machine

The sensor is the model viam:capture-control:capture-control-sensor. Configure it with the components and methods to record:

{
  "resources": [
    { "resource_name": "my-camera", "method": "GetImages" },
    { "resource_name": "my-sensor", "method": "Readings" }
  ],
  "default_tags": ["event"]
}

2. Point the data manager at the sensor

Tell the data management service which sensor to poll, and which key in its readings holds the capture settings. The capture-control module uses the key overrides.

Set capture_control_sensor on the data management service, with the sensor’s name and key. key is required, even if you only use the sensor to record sequences.

{
  "name": "data-manager",
  "api": "rdk:service:data_manager",
  "model": "rdk:builtin:builtin",
  "attributes": {
    "capture_control_sensor": {
      "name": "my-capture-sensor",
      "key": "overrides"
    }
  }
}

Within a moment, the service starts applying the sensor’s readings.

3. Start and stop recording

Send the sensor DoCommand calls. Each command is a key set to true, with optional arguments beside it:

frequency_hz and tags are optional on start_capture. If you leave out frequency_hz and default_capture_frequency_hz is 0, the sequence opens but nothing is captured. Send one command per call. A call with more than one command key set to true returns an error.

Sending start_capture or start_sequence again with different tags closes the open sequence and opens a new one. Sending it again with the same tags continues the same sequence.

The sensor forgets its state when its configuration changes. Changing its configuration, or restarting the module or viam-server, ends any recording in progress.

To check that recording started, look for log messages that begin capture control sensor enabling capture for, and for sequence started. If default_capture_frequency_hz is above 0, the capture message begins capture control sensor changing capture_frequency_hz for instead. Find them on the machine’s LOGS tab, or with viam machines part logs --part=$VIAM_PART_ID. After the next sync, the data appears on the DATA tab, and any sequences appear under SEQUENCES.

Capture components that have no data capture configured

You can list a component in resources even if it has no data capture configured. The data management service finds the component by name and starts capturing the method you name.

For this to work:

• Record at a frequency above 0, from frequency_hz or default_capture_frequency_hz. The component has no configured frequency to fall back on.
• Use a method that the component supports for data capture. See Supported resources.
• Don’t name a method that needs extra parameters. The board methods Analogs and Gpios need parameters, so a capture control sensor can’t enable them.

If the service can’t find the component, or the method isn’t capturable, it logs a warning and skips that entry.

Troubleshooting

• Nothing is captured. If the data management service can’t find the sensor, or capture_control_sensor has no key, it logs an error and ignores the sensor. It picks up a sensor that becomes available later, such as one from a module that starts slowly.
• A recording ended early or split into two sequences. If the sensor fails while you’re recording, capture can fall back to each component’s own settings and the open sequence can close. Look for warnings about the capture control sensor on the LOGS tab.

Advanced: write your own capture control sensor

The capture-control module covers most uses: something outside the machine, such as a person, a script, or a workflow step, decides when to record.

Write your own sensor only when you need one of these:

• The machine decides by itself, from another sensor’s readings, a vision detection, or a schedule, without a separate process sending commands.
• Different settings per component, such as a camera at 10 Hz and a sensor at 1 Hz, or different tags on each.
• More than one sequence open at the same time.

Your sensor’s Readings method returns two lists:

• Under a key you choose, a list of capture overrides. Each entry names a resource_name and method, and can set capture_frequency_hz and tags.
• Under the fixed key sequences, a list of open sequences. Each entry has a resources list and optional sequence_tags. A sequence opens the first time its entry appears, and closes when the entry disappears.

For every field, see Capture control sensor readings.

For more, see Build and deploy modules.

Next steps

• Sequences: what a sequence is, and how to view, edit, and train on the sequences you record.
• Sequences tutorial: record sequences with the capture-control module, then build and export a sequence dataset.
• Conditional sync: control when captured data uploads.