This repository contains all the firmware files for SAMBA v2. The SAMBA system was developed by the IEQ Lab at The University of Sydney. The latest version runs on ESPHome, which is an active, open-source system designed for microcontrollers to do home automation tasks.
ESPHome devices are configured using YAML. YAML is commonly used for configuration files as it is human-readable and clearly structured. Settings are expressed as key-value pairs. There are many YAML guides online if you are unfamiliar with the syntax.
This repository is structured to allow modification of the configuration files using YAML. ESPHome config files are in config/. Individual config files typically serve a single component or function as summarised below.
├── config
| ├── adc.yaml # analog-to-digital converter
| ├── airspeed.yaml # anemometers
| ├── co2.yaml # CO2 sensor
| ├── diagnostics.yaml # device diagnostics
| ├── esp32.yaml # esp32 configuration
| ├── globals.yaml # global variables
| ├── homeassistant.yaml # Home Assistant API
| ├── illuminance.yaml # illuminance sensor
| ├── influx.yaml # InfluxDB connection
| ├── led.yaml # status LED
| ├── ota.yaml # over-the-air updates
| ├── pm25.yaml # PM2.5 sensor
| ├── rtc.yaml # clocks
| ├── sample.yaml # sampling loop
| ├── sd.yaml # SD card
| ├── spl.yaml # sound pressure level sensor
| ├── substitutions.yaml # substitutions
| ├── tair.yaml # air temperature and RH sensor
| ├── tglobe.yaml # globe temperature sensor
| ├── tvoc.yaml # TVOC and NOx sensor
| ├── wifi.yaml # wireless networking
| └── ...
The configuration of these components has been set-up for the reliable operation of SAMBA as per the requirements of the IEQ Lab. However, it is possible for someone to modify the way SAMBA works by editing these files. An example configuration for the temperature and humidity sensor is as follows:
sensor:
- platform: sht4x
temperature:
name: "Temperature"
humidity:
name: "Relative Humidity"
This is a basic configuration that will return temperature and relative humidity. The full set of configuration options are given on the SHT4X component page of ESPHome. Comments throughout the .yaml files point the interested user to the relevant documentation. Note that modifications are the responsibility of the user and are not supported by the IEQ Lab.
The components/ subdirectory is where ESPHome expects to find external components that provide additional functionality beyond what is offered natively in ESPHome. We are using four external components in SAMBA:
sound_level_meterfor calculating SPL (eq, dBA, dBC etc.).senseair_i2cto communicate with K30 CO2 sensor.influxdbfor uploading samples to an InfluxDB bucket.sd_spi_cardfor writing measurements to an SD card
The hope is to have these external components merged into esphome at some point so the broader community can use them.
SAMBA is equipped with sensors that are configured using .yaml files in config/. Most of the sensors are natively supported by ESPHome through what are known as 'components'. The chosen sensors are commonly used by the hobbyist and home automation communities for their reliability and support. The only sensor not directly supported by ESPHome is the CO2 sensor and sound pressure level, which uses the i2s and sound_level_meter external components.
| Parameter | Sensor | Config | Component |
|---|---|---|---|
| Temperature/RH | Sensirion SHT40 | tair.yaml | sht4x |
| Globe Temperature | NTC Thermistor | tglobe.yaml | ntc |
| Air Speed | Thermal Anemometer | airspeed.yaml | ads1115 |
| CO2 | CO2Meter K30 | co2.yaml | senseair_i2c |
| PM2.5 | Plantower PMS5003 | pm25.yaml | pmsx003 |
| VOC/NOx Index | Sensirion SGP40 | tvoc.yaml | sgp4x |
| Illuminance | TI OPT3001 | illuminance.yaml | opt3001 |
| Sound Pressure Level | ICS-43434 Microphone | spl.yaml | sound_level_meter |
A key part of the SAMBA configuration is the sampling routine. SAMBA is configured to constantly measure environmental parameters, periodically summarise those measurements using the median with a moving window, and then upload them at a set interval. The sampling routine is as follows:
- Each sensor is set to measure at a given frequency. This ranges from 500ms (for SPL) to 60s for VOC/NOx Index; see table below for summary.
- Simple quality assurance is done on the measurements. Sensors have a filter to remove obvious outliers (e.g. temperatures below -10°C and above 60°C) or NaN readings. Some have sensors have a linear calibration (implemented as a lambda function) e.g. converting voltage to airspeed. All sensors use a simple moving median.
- The sample loop is triggered every 5-minutes using a cron task on the RTC. The loop is a script component that executes a set of steps; details are given in sample.yaml in
config/. - The script first updates the template sensors to retrieve the latest measurement from the sensor (after the filters and moving median), and then publishes those data to Home Assistant, InfluxDB and/or an SD card. The LED will turn on for 2s with each upload.
The following table summarises the sampling and filters (ordered sequentially) used in the default SAMBA configuration. Again, users are free to modify this but no support will be offered by the IEQ Lab.
| Measure | Frequency | Filters |
|---|---|---|
| Air Temperature | 30s | clamp; moving median; linear calibration |
| Relative Humidity | 30s | clamp; moving median; linear calibration |
| Globe Temperature | 30s | clamp; moving median; linear calibration |
| Air Speed | 2s | clamp; moving median; multivariate calibration; clamp |
| CO2 | 15s | filter; clamp; moving median; linear calibration; clamp |
| PM2.5 | 1s | clamp; moving median |
| VOC Index | 30s | moving median |
| NOx Index | 30s | moving median |
| Illuminance | 10s | clamp; moving median; linear calibration; clamp |
| Sound Pressure Level | 500ms | sos; moving median |
The published measurements from SAMBA get sent every 5-minutes to a Home Assistant instance, an InfluxDB bucket, and/or an SD card.
Home Assistant is an open-source home automation platform that integrates thousands of consumer devices in a no-code environment. The advantage of Home Assistant is it is easy to use (especially for non-technical types). The disadvantage is that it requires another piece of hardware (e.g. Raspberry Pi) and it requires some tinkering to store raw data longer than 10 days. It is most beneficial if the research project involves other kinds of measurements e.g. energy monitoring or window/door openings. Communication between the SAMBA and Home Assistant is done using the native API Component in ESPHome.
InfluxDB is an open-source time series database. It has high-speed read and write that is optimised for real-time data in IoT applications. It can be deployed on most server environments for free, and InfluxData offer a hosted service that has a free and paid tiers (based on usage). The advantage is that it removes additional hardware layers. The disadvantage is that it requires the SAMBA device to have an active internet connection. It is most beneficial when the research project is deploying SAMBAs only e.g. a field study in office buildings. Communication between the SAMBA and InfluxDB is done using the external component in components/influxdb. By default, the InfluxDB tags used for all measurement uploads are the building, level, and zone IDs that are set as global variables on the SAMBA device. If you want to modify the InfluxDB configuration, we recommend familiarising yourself with key concepts of InfluxDB first, like measurement, tags, and fields. No support is given for InfluxDB buckets other than those maintained by the IEQ Lab.
The following section details how every SAMBA device is configured by the IEQ Lab. To begin, make sure the ESPHome Command Line Interface is installed. Instructions can be found on the ESPHome website. The minimum version of ESPHome is currently 2025.10.0.
SAMBAs are initially flashed with samba_setup.yaml in the root directory. This is a basic configuration that loads device-specific parameters (e.g. calibration coefficients), creates a wireless hotspot to configure WiFi networks, and then starts a web server that allows users to configure the device. Once done, the user can initiate the download of the latest production firmware from Github that has been compiled from samba.yaml in the root directory.
Access to the ESP32 is through the USB-C port on SAMBAs main PCB. There is a single bolt that holds the SAMBA housing together - use a 4mm hex key to undo the bolt on the bottom of the device. Slide the bolt out from the bottom to remove the housing and reveal the PCB. The USB-C port is located on the bottom right of the PCB. Note: this will not provide power to the SAMBA; power must be provided through the DC barrel jack. Once your device is connected and the SAMBA is powered on, follow these steps to flash the setup firmware:
- [Optional] Erase the ESP32 flash memory from earlier deployments:
esptool.py --chip esp32 erase_flash. - Clone the SAMBA Github Repository to your local device and open that directory.
- Open a terminal window and
cdto the working folder where the SAMBA Github repo was cloned. - The initial set-up script is
samba_setup.yaml. It contains placeholder calibration coefficients - these can be changed later. - Enter the following command to compile and upload the binary file to the SAMBA:
esphome run samba_setup.yaml. Note that you will need to select the serial device before uploading; alternatively, specify the serial connection e.g.esphome run setup.yaml --device /dev/cu.usbserial-10.
It should take about 30 seconds to flash the firmware. The LED should flash green and blue to indicate it is on but not connected to WiFi. If the SAMBA is being relocated, disconnect the USB-C cable once it is finished flashing, unplug the power, put the housing back on, and tighten the hex bolt. Place the SAMBA in its new location, power it on, and follow the below steps to configure the WiFi:
- Use another device (e.g. smartphone, laptop) to join the
samba_connectad-hoc WiFi and open the captive portal by navigating to http://192.168.4.1/ into your browser. - Select the available 2.4GHz network to join from the list and enter the password.
- SAMBA will connect to the network and then launch a web server to display the configuration settings and terminal window. This can be accessed through a browser at the IP address of the SAMBA on the local network e.g.
192.168.1.XXX. - Enter the location tags (building name, level/room number, and zone name) and the calibration coefficients. CO2, illuminance, air temperature, relative humidity, and globe temperature are linear calibrations (e.g. y = mx + b); the two air speed sensors are power regressions (e.g. y = a * x^b).
- Once the configuration is complete, click the 'Deploy SAMBA' button to attempt to download and flash the latest firmware stored in
firmware/on the IEQ Lab Github. Once that is done, the SAMBA will reboot and start sampling automatically. The status LED should blink green to indicate it is warming up; this will stop once it enters the sampling routine.
The IEQ Lab will actively maintain the SAMBA firmware and publish updates to the Github repository. This might involve performance improvements or additional features. In this case, the IEQ Lab will push new binaries to firmware/ which will be flashed remotely using OTA updates. For Lab staff wishing to update the firmware, follow these steps:
- [Required] Speak to Tom before doing anything 🤠
- Make the agreed modifications to the relevant .yaml files in
config/and test EXTENSIVELY. - Bump the project version in
esp32.yaml - Once the new firmware is confirmed stable, generate the compiled bin:
esphome compile samba.yaml - Move the compiled ota firmware to the firmware directory:
cp .esphome/build/samba/.pioenvs/samba/firmware.ota.bin firmware/samba_v2.XX.XX.bin - Generate a new md5 hash and print it to terminal:
md5 firmware/samba_v2.XX.XX.bin - Update the
manifest.jsonfile and thesamba_setup.yamlto include the new bin path and md5 hash. - Push the new .bin and updated manifest.json to the SAMBA Github repository.
SAMBAs will check for updates once per week (4 am on Mondays) and automatically flash anew update if available. As such, it's extremely important that firmware are extensively tested BEFORE being pushed to Github otherwise they could (worst case scenario) brick the entire SAMBA fleet.
Users are free to modify the SAMBA firmware to suit their needs. However, we strongly discourage people from doing this if they are not familiar with basic programming of microcontrollers and/or ESPHome. If you're feeling brave, follow these steps to customise the SAMBA firmware:
- Define your project-specific parameters in the secrets.yaml.
- Make whatever modifications to the relevant .yaml files in
config/.... - [Optional] There are two ways to update any calibration coefficients:
- Change the relevant lambda function in the template sensor to the new value. For example, changing the CO2 regression slope would mean modifying this line so that
id(calibration_co2_m)becomes the new coefficient value. - Modify the global variable that stores the calibration coefficient. This is more robust but requires a bit more work to get right - speak to Tom if needed.
- Change the relevant lambda function in the template sensor to the new value. For example, changing the CO2 regression slope would mean modifying this line so that
- Compile and upload the firmware to SAMBA via USB-C with
esphome run samba.yamlor wirelessly (if in the same WLAN) with the SAMBA IP addressesphome run samba.yaml --device 192.168.1.XXX.
The user is responsible for managing the device if the firmware is modified.
This is an active project to build an open research platform to help advance healthy, high-performance buildings. If you're interested in using SAMBA in your project or contributing to it's development, let's chat 😊 You can start a Github discussion thread or email Tom.