Sampling Routine

Sampling Configuration

This page explains how the sensor_sample script defined in config/sample.yaml orchestrates the SAMBA v2 firmware sampling cycle. It covers how the script flows, the configuration switches it responds to, and how you can adapt the actions for your own deployments.

Overview

sensor_sample is an ESPHome script that is invoked by the firmware to update all measurement components and optionally push the results to storage or remote services. The script runs in single mode to prevent overlapping executions. Every run performs a quick health check, refreshes sensor values, handles data publication, and gives visual feedback through the onboard LED.【F:config/sample.yaml†L8-L93】

Warm-up Guard

The first action updates the sys_uptime sensor and compares its value to a two-minute threshold. Until 120 seconds have elapsed the script only logs a "Warming up" message, avoiding premature sampling while sensors stabilise.【F:config/sample.yaml†L11-L92】

Active Sampling Phase

Once the warm-up completes the LED is softly enabled and the script updates each physical or virtual sensor component in sequence. Immediately afterwards it republishes the latest readings through template sensors so that Home Assistant and automations receive fresh data without waiting for polling intervals.【F:config/sample.yaml†L16-L65】

Upload and Persistence Hooks

Two conditional blocks control downstream integrations:

• InfluxDB uploads are triggered when the switch_influx switch is on. The script calls id(influx).publish_now() to push all metrics immediately; otherwise it logs that the upload was skipped.【F:config/sample.yaml†L67-L83】
• SD card logging depends on both the switch_sdcard switch and the card being mounted. When enabled it appends a CSV line with a timestamp and all key environmental metrics to the configured file. If either prerequisite is missing the firmware logs an informational message instead.【F:config/sample.yaml†L84-L114】

Finally, the LED fades out, marking the end of the cycle.【F:config/sample.yaml†L115-L117】

Configuration Knobs

Although sensor_sample is a script, its behaviour is shaped by several IDs and switches defined elsewhere in the firmware:

• switch_influx – toggles whether the cycle triggers an immediate InfluxDB batch publish.
• switch_sdcard and sd0 – together enable CSV persistence to the SD card.
• sd_filename – lambda that resolves to the active CSV path.
• samba_* sensors – template or hardware sensors whose IDs match the publish/update actions.
• samba_led – addressable LED used for user feedback.

Adjusting the referenced components allows you to change how and where the data flows without altering the script logic itself.

Customising Actions: Example Use Case

Suppose you want to add a notification whenever particulate matter (PM2.5) exceeds a critical threshold. You could extend the script after the sensor updates with an additional if block:

      - if:
          condition:
            lambda: 'return id(samba_pm25).state > 75;'
          then:
            - homeassistant.event:
                event: samba_high_pm
                data:
                  value: !lambda 'return id(samba_pm25).state;'

This addition leverages existing sensor IDs, responds to freshly updated values, and keeps the rest of the sampling cycle unchanged. Because the script already handles warm-up and LED signalling, your notification only fires when the system is in a stable, active sampling state.

Tips for Further Modifications

• Maintain the warm-up guard to avoid acting on stale sensor data.
• Reuse the provided switches (switch_influx, switch_sdcard) as templates when adding new opt-in behaviours.
• When appending new storage backends, follow the pattern of checking prerequisites and logging skipped operations to aid troubleshooting.

By understanding the structure described above, you can confidently tailor the SAMBA sampling workflow to match the needs of different deployments while keeping the firmware maintainable.