Skip to content
Measures and distributes readings for air quality
Scala Shell
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


This app periodically reads physically attached sensors (Serial/UART) and distributes readings to external services.

Currently supported sensors:

  • Particulates
    • SDS011
    • SDS021 (Not recommended for outdoor use)
  • CO2
    • MH-Z19 (B)

Currently supported external services:

  • Domoticz


Skip this section if you have a fijnstof_1.1_all.deb file ready to install.

Run this command to create a Debian package (.deb):

sbt debian:packageBin

The result will be this file:


echo "deb binary" > /etc/apt/sources.list.d/myrepo.list
apt-get update


This package is targeted at the Raspberry Pi running Raspbian, but the software runs without changes on any Linux or Mac with a sensor on a serial device. It may even run under Windows, please let me know if you get this working! sbt list should list the serial devices on Windows as well.

Raspberry Pi

Skip this section if you have a running Pi.

Following is a step by step guide to install a Raspberry Pi with (a local build) of fijnstof running:

  • Download the latest Raspbian, and extract it to get the .img
  • sudo fdisk -l to determine the block device of your SD card (compare sizes to what you inserted)
  • sudo dd if=yourimage.img of=/dev/mmcwherever bs=8M
  • sync
  • Eject and mount again on your running linux machine
  • Add an empty file called ssh in the boot partition. This will allow ssh to be enabled at first boot, so you don't need to attach keyboard or monitor.
  • Check your router for the assigned IP address, or try raspberrypi.local.
  • ssh pi@raspberrypi, replace raspberrypi with whatever hostname or IP address was assigned
  • On boot, run sudo raspi-config and configure at least the following:
    • password, something other than raspberrypi
    • hostname, from here, we will assume fijnstof
    • boot into CLI, without logging in
    • No splash screen
    • Wifi country, SSID and password (if you don't want/have an ethernet cable available)
    • Locale, keyboard layout
    • Interfaces -> Serial
      • Disable terminal over serial
      • Enable hardware device for serial
    • Expand filesystem, to take advantage of the entire SD card storage

Optional: Add authorized SSH key

Skip this section if you don't mind entering passwords.

To avoid having to enter your password for every ssh or scp, you can add an SSH public key to the pi.

First make sure you have a public key

ls -l ~/.ssh/

If no key exists, create one:

ssh-keygen -t rsa -b 4096 -C ""

Copy the public key (only) to the pi:

scp ~/.ssh/ pi@fijnstof.local:

On the pi, check if there is no existing authorized_keys file present:

ls -l ~/.ssh/authorized_keys

If not present, create and move:

mkdir ~/.ssh/
mv ~/ ~/.ssh/authorized_keys

Otherwise, just add the key:

cat ~/ >> ~/.ssh/authorized_keys

Debian package

The Debian package will mainly add startup on boot functionality, which will be harder to achieve otherwise.

From your host computer, copy the Debian package, using the chosen hostname from above:

scp target/fijnstof_1.1_all.deb pi@fijnstof.local:

Note the trailing colon above.

On the Pi, install the package

sudo dpkg -i fijnstof_1.1_all.deb

The installation will add a fijnstof user and a start script that will launch at boot. It should also add the fijnstof user to the group dialout, which is needed to gain access to the serial device. Please check if this is successful, or add it manually:

sudo usermod -a -G dialout fijnstof

List all available serial devices, and check if the one you expect to represent your device is among them:

fijnstof list

Take out the device, and see if it disappears from the list when running again. Then plug it back in.

Configuration is in:


It may be self-explanatory. If not, see the dedicated configuration documentation for more extensive information.

Set the serial device here. Enable blocks for Domoticz or Luftdaten, whichever you want to use. Make a test run:

fijnstof test

See if you get any errors. Write down the machine id, something like fijnstof-e123456e. You will need this number later.

Start the service

sudo service fijnstof start

Logging should appear in the daemon log

tail -f /var/log/daemon.log

Run from CLI during development

You can manually start the application from the command prompt. Without options, it will run as in daemon mode, indefinitely reading and outputting, until you press Ctrl-C.

sbt run

To get a list of available serial devices, enter

sbt "run list"

To test the setup with 1 measurement, enter

sbt "run test"

Note the difference with the regular command to run the software tests

sbt test


Domoticz is a system to automate your home. It supports a variety of protocols and devices, allowing you to control your home and respond to sensor values. Domoticz also keeps track of historic readings, and presents them in diagrams. We can send our particulate measurements to Domoticz to track the trends over time.

In Domoticz -> Settings -> Hardware, add new Dummy hardware

  • For the SDS011
    • On the Dummy hardware, create 2 virtual sensors, PM2.5 and PM10.
    • Sensor type: Custom sensor. Enter (copy/paste) µg/m³ for axis label.
  • For the MH-Z19
    • On the Dummy hardware, create 1 virtual sensor, CO2.
    • Sensor type: Air quality

Look up the assigned IDX values under Devices (order by IDX descending), and set them in the configuration file.

You can add the new devices to the Floor Plan if you have one, and drag them to the correct physical place in the right room.

Luftdaten is a Citizen Science project to collect as many particle sensor data as possible, and show it on a map. This project was specifically created with the idea in mind to make contribution as easy as possible. If the sensor is outside (nobody cares about your indoor readings), you may consider connecting to the API. Once you retrieved the machine ID of your sensor from the logging (or by running fijnstof test, something like fijnstof-e123456e). Use that to register at the bottom of their DIY page. After some time (days), you will get a confirmation, and you will see the measurements on the map on your specified location: (slightly off, for privacy reasons), but also anyone else interested in particle rates in their area or anywhere else.

You can’t perform that action at this time.