Back to

Sensors readings from a DIY kit! How to integrate into SmartCitizen?

Hi everybody,
I’m working in a FabLab and we are working in a project together with a high school in collecting data about environment.
We’d like to “put” the data in the SmartCitizen platform, but as far as I understood we need to ask for a token!

This is our hw setup, based on ESP32!
MH-Z16 CO2 sensor
BMP280 Temperature and Pressure
MTK3339 Gps (optional)
Microphone with MAX9814 amplifier
SDS011 PM2.5 and PM10 sensor
DHT22 Humidity (and temperature) sensor

Is it possible with these sensors, to upload the data through API to the platform?
Which are the next steps?


1 Like

Hi Mirco,

Thank you for the post! So to post data via the REST API (I saw you don’t want to go via MQTT) you would need to post against the <device>/readings endpoint, which is documented here. You would need to have a few things beforehand:

  1. A blueprint for the kit, which will give us a kit_id. This one we create based on your sensor description. It will be used to define which sensors you have in each device_id
  2. An ID for each sensor you are going to send, which we create too. This will be used to identify the reading, and it will be only be accepted if the sensor_id is in the definition of the kit_id above
  3. A device_id, which you can get via the onboarding process or by posting to the REST API here with a random 6-digit hex token, including the kit_id from above. The API will give you back the device_id

An example of how to construct the json with python is here (not the same of course), but at least you can see the resulting json.

So next steps, is that we will create the sensors, then the blueprint, and put them here. Then you can request the device_id and start sending data.

Will be back with the ids soon!

Hi guys!
Thank you so much for the support and the explanation, I think I’ve understood everything :slight_smile:
I’ve already gave a look at the REST API too.

Looking forward to proceed !

Hi again!

So, we need some extra information from these sensors:

MH-Z16 CO2 sensor
BMP280 Temperature and Pressure
MTK3339 Gps (optional)
Microphone with MAX9814 amplifier
SDS011 PM2.5 and PM10 sensor
DHT22 Humidity (and temperature) sensor

In particular, for each of them, we need the units they will collect data in and if there is any other metric in case the sensor gives you other data. I am assuming the following:

MH-Z16 CO2 sensor (CO2 - ppm)
BMP280 Temperature and Pressure (T - degC, P - kPa)
MTK3339 Gps (optional) (See below)
Microphone with MAX9814 amplifier (See below)
SDS011 PM2.5 and PM10 sensor (PM2.5 - ug/m3, PM10 - ug/m3)
DHT22 Humidity (and temperature) sensor (RH - %rh, T - degC)

For the microphone, if the readings are in a particular scale or simply dB. Also, the name of the microphone you are using.

Regarding GPS, we follow this format: GPS - Smart Citizen Docs
In general you don’t have to send all the readings in case you don’t have them, but the ones you have, should go with that format.

And finally: the Kit name and description you would like. Something like name: “DIY Sensor Kit <…>” and description: “DIY Sensor Kit <…> with Air Quality sensors and GPS”

Almost there!

I’ve verified all the sensors and you are right 100%, so I confirm:

We are using this mic: “Electret Microphone Amplifier - MAX9814 with Auto Gain Control” (by Adafruit) but now I’m in doubt… Is this thing of the autogain a problem in measuring the dB?

For the GPS format ok, we need only a few conversion in order to match your standard!

Last but not least, the name.
I’d say “DIY Sensor Kit PCTO @ LD22”
(PCTO is a kind of stage for students, and LD stands for LinuxDay 22, during which we started working on the sw and the hw together with the FabLab Castelfranco Veneto and the Linux User Group in Pordenone!)
Description: “DIY Sensor Kit PCTO started during LD22 with PnLUG and FabLab CFV, with Air Quality & Environment sensors and optional GPS”
(if it’s ok)

Thanks again!

Hi there!

So here it is! I had to shorten a bit the description of the kit (see below for how I compensate). The kit_id is 40 and each sensor_id goes specified in the list below. Since you have two temperature readings, I added the DHT22 as an “external” temperature sensor.

## DIY Sensor Kit PCTO @ LD22 (DIY Sensor Kit PCTO for air quality, environment and GPS readings) [40]
* 172 Winsen MH-Z16 - CO2 (ppm)
* 174 Bosch BMP280 - Temperature (ºC)
* 175 Bosch BMP280 - Pressure (kPa)
* 177 Electret Microphone - Noise (dB)
* 179 NovaFitness SDS011 - PM2.5 (ug/m3)
* 180 NovaFitness SDS011 - PM10 (ug/m3)
* 125 Latitude (deg.)
* 126 Longitude (deg.)
* 127 Altitude (meters)
* 128 Fix (fix code)
* 129 Horizontal Speed (m/s)
* 130 Satellite Number (number)
* 131 Horizontal Dilution ( )
* 4 DHT22 - Temperature (ºC)
* 5 DHT22 - Humidity (%)
Total: 15 sensor are enabled.

With regards to the microphone, I think you would need to compensate the gain from the amplifier after you calculate RMS, and then you can calculate dB based on maximum readings of the microphone (overload point).

Now, with regards to the description, instead of adding a long description to the kit itself that includes that info about the project, I created a tag that can be used for it, which you can find here:

Finally, when you register your devices (if you use the onboarding), remember to use the advanced kit selection:

1 Like

Thank you so much!

I’ll try ASAP the API and the hw!
I’ll keep you posted.


is it possible to post via MQTT as well?
Because it would be the easiest way!
In the meanwhile we’re working on the code for the REST API!



Yes, you can of course. Here is how to do it (from our own firmware): smartcitizen-kit-21/SckESP.cpp at master · fablabbcn/smartcitizen-kit-21 · GitHub

If you want to do the whole onboarding, in the same file you have the hello message process: smartcitizen-kit-21/SckESP.cpp at master · fablabbcn/smartcitizen-kit-21 · GitHub



Hi Oscar, tanks!
Very cool, I’ll give a try later on!


Just to complete a bit more the answer:

We also accept readings in JSON format

To register your device and obtain a token you can the onboarding methods or directly the device one

Hope it helps!