sensors-software: firmware for the Luftdaten.Info air quality sensor

Firmware for a citizen air quality network

The repository is titled Software for Sensor.Community / Luftdaten.Info Sensor, and the repository description calls it the sourcecode for reading sensor data. The topic tags are arduino, iot, iot-device and sensor, and the primary language is C++.

The project that sits at the centre of the tree is airrohr-firmware, described as the maintained main firmware for the Sensor.Community / Luftdaten.Info Sensor. The prefix is the giveaway: these are the names of the open hardware sensor designs, and this repository is where the software for them lives.

That context matters for how you read the repository, because it is not a general-purpose firmware project. It is the software for one specific piece of citizen hardware, maintained by the people who run the network behind it, and much of what is in the tree exists to support that network rather than to be a reusable library.

The second project in the tree, airrohr-update-loader, is the more interesting one technically, and it is described in the README as a transitional firmware, which tells you its days are numbered.

The development section states plainly that the development is done in the beta branch, and the build badges at the top of the README track the firmware workflow for both the master and the beta branch, so the CI story is visible without opening the workflows.

The update loader replaces itself, or blinks forever

The airrohr-update-loader does one thing, and it does it in a way that is unusual enough to be worth describing precisely.

It is a transitional firmware which will look for a firmware file stored on SPIFFS to replace itself with for next reboot, or do an endless loop of panic LED blinking if this fails. So the sequence is: the loader boots, checks for the new firmware image on the SPI flash filesystem, and if it finds one it writes it and reboots into it, and if it does not find one, or the write fails, it blinks the panic LED indefinitely.

The reason this exists is the flash layout. The loader allows an over-the-air procedure on setups that have a 1M/3M split layout, rather the more modern 2M/2M, for firmwares larger than 512k, up to about 740k. On a device with a small application partition, a firmware image of that size will not fit alongside the updater in the same partition, so the update has to be staged in the other one and applied by something that is not the running firmware.

The panic LED loop is the failure mode of that design, and it is worth understanding before you flash anything. If the loader cannot complete the update, the device does not fall back to a working firmware, it sits there blinking. That is a deliberate choice, because a loader that silently returned to the old firmware would hide the failure, and a sensor that has not updated is a sensor reporting stale data without saying so.

The directory names are a history of the platform

The Directories section of the README is a list that doubles as a changelog of the hardware and its software, and the dates in it are the interesting part.

The `airrohr-...` directories hold the currently used versions, dated 2017-05-23 and later, and `airrohr-update-...` holds the versions currently used for OTA, from 2019-08-30. Those two dates mark the two moments when the firmware line changed shape: first the rewrite into the current naming, then the introduction of the over-the-air path.

Then there is `esp8266-lua`, described as nodemcu firmware code with lua scripts, and marked as not maintained after the change to arduino. That is the NodeMCU era of the sensor, when the firmware was written in Lua on top of the ESP8266's own scripting runtime, before the project moved to the Arduino toolchain. The code is still in the tree, which is useful if you own a sensor from that generation.

`esp8266-arduino` is the same hardware programmed with the arduino code and IDE, `arduino` holds native arduino code, and `BeginnersGuide` is a beginner's guide to ESP programming with Arduino code, which is the on-ramp for anyone arriving at the hardware for the first time.

`schematics` holds fritzing schematics and is marked as not updated, dated 2016-03-01, so the board drawings in the repository are ten years old and should not be trusted as the current hardware.

The surrounding directories are the data side of the network

The rest of the tree is the ecosystem around the sensor rather than the sensor itself, and this is where the description sourcecode for reading sensor data comes from.

`apiclients` holds clients for the dusti API and other APIs, which is the part that takes what a sensor measures and puts it where the network can see it. `r-scripts` holds sensor data analysis with R, so the data that comes out of the network can be worked on statistically, which is what turns a pile of measurements into a pollution record.

Then there are the directories that show how the sensor is deployed in the field. `MobileFeinstaub/` and `config-via-raspberry/` are named for the two obvious use cases, a mobile particulate sensor and a configuration path through a Raspberry Pi. `homeassistant/` points at the Home Assistant integration side, and `raspberry-serial/` and `perl-scripts/` are the serial and scripting pieces.

`utils/` holds the shared helpers and there is a `.gitmodules` file, so parts of the tree are pulled in from other repositories rather than vendored. There is also a `contributing.md` at the root, which is the natural place to look before opening a pull request against a project with this many separate concerns.

For a first-time reader, the sensible path is BeginnersGuide, then the firmware directory, then the API clients.

Development happens on beta, and master is what you run

The last line of the README is the operational instruction that matters most for anyone building a sensor: the development is done in the beta branch.

That implies a two-branch model where master is the stable line and beta is where changes land first. The build badges confirm it, with one workflow, airohr-firmware.yml, tracked separately for the master and the beta branch, so you can see at a glance whether the branch you care about is currently green.

The two-branch arrangement is a reasonable choice for a project where a broken build means a bricked sensor in someone's window, and where the people who merge are often the same people who flash their own units. It also means the branch naming has to be read carefully, because installing the wrong branch onto a device is easy to do and awkward to undo.

The version tags are less regular. The only listed release is NRZ-2020-133, from 2020-11-29, and the repository is not archived with the last push on 2026-08-25. So the work continues on the branches, and the tag history is not the place to look for a version of the firmware you can install.

What the README does not document is how a given unit is flashed, what the current release of the firmware is called, or how the update process is triggered from the device side, so those are the questions to ask before relying on this repository for a deployment.

An unstated licence, and a single 2020 tag

The licence is the one thing the repository does not settle. The licence is not identified in the repository listing, and there is no licence file among the top-level entries, which are the .github directory, .gitignore, .gitmodules, the project directories and the readme.

That matters more here than it would in a typical library, and the reason is the hardware. The firmware runs on a device the user bought or built, and the surrounding material includes schematics, configuration tools for Raspberry Pi and Home Assistant integration code. Someone shipping a commercial product with this firmware in it needs to know what they are allowed to do, and the answer is not in the repository.

The release history is the other gap. One tag, NRZ-2020-133 from 2020-11-29, and a repository that is not archived with the last push on 2026-08-25, means the continuity signal is the commit history and the branch state rather than the tags.

What the repository is very good at is telling you what the pieces are. The firmware, the update loader, the API clients, the analysis scripts, the deployment helpers, the beginner's guide and the schematics are all described, and the two project directories that matter are named and dated. Someone who already knows the Sensor.Community hardware and wants to modify or extend it will find everything in one place.

Editorial conclusion

sensors-software fits a maker with one of these sensors who wants to read, re-flash or extend the firmware, and fits a researcher who wants the data collection and analysis code that came with the network. It is the wrong choice for a team that wants a maintained general-purpose firmware platform, because the release history is a single 2020 tag and the licence is not identified in the repository listing. Verify first which branch your sensor is on, master or beta, and what the flash layout of your particular unit is, since the over-the-air path depends on whether it has the 1M/3M split or the newer 2M/2M layout.

Frequently asked questions

Official sources

1. Issues
2. opendata-stuttgart/sensors-software on GitHub
3. README
4. Releases