Sensor Configuration

Sensor Configuration

SAMBA combines raw hardware integrations with template sensors that publish calibrated metrics on demand. Each physical sensor is configured to collect data at an appropriate cadence, apply quality filters, and store the result internally. Template sensors with update_interval: never act as placeholders; the sensor_sample script updates them just before publishing so downstream systems receive synchronised snapshots. This page summarises the configuration for every measurement channel.

Air Temperature and Humidity (SHT40)

• Platform: sht4x on I²C address 0x44 sampling every 30 seconds with the onboard heater disabled.
• Filters: Reject nan, clamp to -10 – 60 °C and 0 – 100 % RH, then apply a moving median window of 10 samples.
• Template outputs: samba_temperature and samba_humidity apply linear calibration coefficients to the filtered temperature and humidity states before publishing.

Globe and Mean Radiant Temperature (NTC Thermistor)

• Upstream ADC: The shared ADS1115 exposes the thermistor as ads_ntc, sampled every 30 seconds.
• Resistance conversion: A resistance sensor defines the divider characteristics (10 kΩ resistor, 4.096 V reference) before an ntc platform applies the Steinhart–Hart constants.
• Filters: Invalid readings are dropped, clamped to -10 – 60 °C, and smoothed with a 10-sample median.
• Template outputs: samba_globe calibrates the derived temperature, while samba_mrt computes mean radiant temperature using the globe, air temperature, and air speed template states.

Air Speed (Dual Thermal Anemometers)

• Raw inputs: Two ADS1115 channels (ads_as1, ads_as2) capture voltages every two seconds.
• Derived copies: Internal copy sensors clamp voltages to 0 – 5 V, smooth with a 150-sample median window, then apply a temperature-compensated power regression using calibration constants and the latest SHT40 temperature.
• Template output: samba_airspeed publishes the higher of the two calibrated channels to represent the dominant air speed.

Carbon Dioxide (Senseair K30)

• Platform: senseair_i2c on bus bus_a at address 0x69, sampling every ~14.7 seconds with automatic background calibration every 180 hours.
• Filters: Remove nan, clamp to 380 – 10 000 ppm, then apply a 20-sample median (report every third sample).
• Template output: samba_co2 applies linear calibration coefficients before publishing.

Particulate Matter (Plantower PMS5003)

• Platform: pmsx003 on uart_pm, exposing PM2.5, onboard temperature, and humidity channels.
• Filters: PM2.5 readings drop nan, clamp to 0 – 1000 µg/m³, and use a 300-sample median (every 30th sample). Humidity readings clamp to 0 – 100 % with the same median window.
• Template output: samba_pm25 implements the US EPA humidity correction curve, blending multiple linear regimes depending on particulate concentration.

Illuminance (TI OPT3001)

• Platform: opt3001 on address 0x45, updating every 20 seconds.
• Filters: Discard nan, clamp to 0 – 20 000 lx, and average with a 15-sample median (every third sample).
• Template output: samba_lux scales readings via linear calibration coefficients.

Volatile Organic Compounds and NOx (Sensirion SGP40)

• Platform: sgp4x updating every 30 seconds.
• Compensation: Temperature and humidity compensation use the SHT40 template IDs to feed the onboard algorithm.
• Filters: Both VOC and NOx indices reject nan values and apply a 10-sample median filter (every second sample).
• Template outputs: samba_tvoc converts the VOC index to calibrated ppb, while samba_nox republishes the NOx index directly.

Sound Pressure Level (ICS-43434 Microphone)

• Audio front-end: An i2s_audio microphone feeds the sound_level_meter external component with 48 kHz, 32-bit samples.
• Digital signal processing: Chain of SOS filters includes microphone equalisation plus A- and C-weighting curves. LAeq uses a 600-sample median; LAmin/LAmax compute min/max over 1-second windows with five-sample smoothing.
• Template outputs: samba_laeq, samba_lamin, and samba_lamax expose the A-weighted sound levels for publishing.

Template Sensors in the Sampling Loop

All template sensors are configured with update_interval: never, so they serve as on-demand caches. During each five-minute cycle the sensor_sample script updates the template components, publishes their current state, and hands it off to upload integrations and storage backends. This guarantees that Home Assistant, InfluxDB, and SD card logs all receive the same calibrated snapshot from every sensor.