Ex: Background Noise Calibration

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

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.

Requires pip install voyant-api.

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

Python 3.9 or later
voyant-api installed:
```
pip install voyant-api
```
A Carbon sensor, or the bundled carbon_simulator running locally

Example Code

View the complete example on GitHub: background_noise_calibration_example.py

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).

Calibrating

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

client.wait_for_heartbeat()
client.ensure_idle_for_calibration()

if args.refine:
    # Cover the sensor window first — refinement assumes background noise only.
    client.refine_background_noise(args.iterations)
else:
    client.apply_default_background_noise()

Command Line Options

python background_noise_calibration_example.py --help

# Apply the default mask (fast)
python background_noise_calibration_example.py

# Refine from a covered-window capture (cover the window first!)
python background_noise_calibration_example.py --refine

# Load a JSON device config
python background_noise_calibration_example.py --config config/device_config.json

Expected Output

CarbonClient started.

# 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 Reference — full CarbonClient reference