Ex: Background Noise Calibration

Calibrate a Carbon sensor’s background-noise mask with C++.

This example demonstrates how to calibrate a Carbon sensor’s background-noise mask. Both operations require the sensor to be in the Idle state; the box is identified automatically from its heartbeat.

What You’ll Learn

• How to drive the sensor to Idle for calibration
• How to apply the compiled-in default noise mask (fast)
• How to refine the mask from a covered-window capture

Prerequisites

• Voyant SDK installed (see Installation)
• A Carbon sensor, or the bundled carbon_simulator running locally (pass --sim)

Example Code

View the complete example on GitHub: background_noise_calibration.cpp

Key Concepts

Two Operations

• Apply Default — write the compiled-in default mask for the box. Fast, no capture needed.
• Refine (--refine) — refine the mask from a covered-window capture (~10–20 s). The sensor window must be covered first, because the capture assumes background noise only.

Both calls block until done and leave the sensor in Idle (they do not resume streaming).

Getting to Idle

Wait for a heartbeat (for the box serial), then drive the sensor to Idle before calibrating:

if (!client.waitForHeartbeat())
{
    std::cerr << "Timed out waiting for a sensor heartbeat." << std::endl;
    return 1;
}
if (!client.ensureIdleForCalibration())
{
    std::cerr << "Could not drive the sensor to Idle; aborting." << std::endl;
    return 1;
}

Calibrating

bool ok;
if (refine)
{
    // Cover the sensor window first — refinement assumes background noise only.
    ok = client.refineBackgroundNoise();
}
else
{
    ok = client.applyDefaultBackgroundNoise();
}

Building and Running

# Build the examples
mkdir build && cd build
cmake ..
make

# Apply the default mask (fast)
./bin/background_noise_calibration

# Refine from a covered-window capture (cover the window first!)
./bin/background_noise_calibration --refine

# Add --sim to target a local carbon_simulator
./bin/background_noise_calibration --sim

Expected Output

# Default
Default background-noise calibration applied.

# Refine
Cover the sensor window now — refinement assumes background noise only. Running refinement (~10-20 s)...
Background-noise refinement complete.

Next Steps

• Live Client — stream frames after calibrating
• API Documentation — full CarbonClient reference