Skip to content

Smart Citizen Kit

A note about versions

The SCK 2.0 was the development version for the now commercially available SCK 2.1 sponsored thanks to the iSCAPE project under European Communityโ€™s H2020 Programme under Grant Agreement No. 689954

Quick links

๐ŸŽ Buy: seeedstudio.com

๐Ÿš€ Installation: start.smartcitizen.me

๐ŸŒ Platform: smartcitizen.me

๐Ÿ’ฌ Discuss: forum.smartcitizen.me

โ“ Support: support@smartcitizen.me

โœจ Something big?: info@smartcitizen.me

๐Ÿšจ Platform status: uptimerobot.com

What is it?

The Smart Citizen Kit is the core of what we call the Smart Citizen System: a complete set of modular hardware components aiming to provide tools for environmental monitoring, ranging from citizen science and educational activities to more advanced scientific research.

The system is designed in a extendable way, with a central data logger (the Data Board) with network connectivity to which the different components are branched. The system is based on the principle of reproducibility, also integrating non-hardware components such as a dedicated Storage platform and a Sensor analysis framework.

On top of that, the system is meant to serve as a base solution for more complex settings, not only related with air quality monitoring. For that purpose, in addition to the Urban Board, the system also provides off-the-shelf support for a wide variety of third party sensors, using the expansion bus as a common port. One example is what we call the Smart Citizen Station: a full solution for low cost air pollution monitoring.

The sensors

Have a look a the supported sensors in the Firmware!

๐Ÿ‘‚ Measurements

All the Smart Citizen Kit new sensors generation measure at least air temperature, relative humidity, noise level, ambient light, barometric pressure and particulate matter (PM).

SCK 2.1

Here is the table summarising the sensors:

Measurement Units Sensors
Air temperature ยบC Sensirion SHT-31
Relative Humidity % REL Sensirion SHT-31
Noise level dBA Invensense ICS-434342
Ambient light Lux Rohm BH1721FVC
Barometric pressure Pa NXP MPL3115A26
Equivalent Carbon Dioxide ppm AMS CCS811
Volatile Organic Compounds ppb AMS CCS811
Particulate Matter PM 1 / 2.5 / 10 ยตg/m3 Planttower PMS 5003

Sensor performance

Make sure you visit the sensor performance page for further information about the sensors.

๐Ÿ““ Installation instructions

The sensor comes mounted and almost ready to be used:

The first step is to connect the battery. The kit will light in red (configuration mode) and we will be able to configure it by following the instructions at start.smartcitizen.me.

Detailed guide

Have a look at this guide for a step-by-step installation.

After the configuration process, data will be available on the SmartCitizen platform. You can explore the data there or download it using the CSV Download option (you can check a more detailed guide here)

๐Ÿ”‹ Power management

Battery duration

The SCK comes with a 2000mAh LiPo battery. The battery is meant to be a complete power option for short-term measurements and a backup solution when the kit it is used for long periods. For long exposures, we recommend to permanently connect the USB to kit. The battery duration is dependent on which sensors are enabled or disabled.

You will note that the kit turns itself off while operating on battery. Actually, this is what we call sleep-mode, an operation mode implemented to reduce consumption while on battery operation. Check the operation modes section below.

PM Sensor management

If you want to save battery, the basic interval for the sensors shouldn't be below 30s. This is because the minimum stabilisation time the PM sensor requires to take stable readings is around 15-20s. For this reason, the minimum interval available without turning off the PM sensor between readings is 30s. If a lower interval is required, the PM sensor will be permanently ON and battery will drain faster.

Battery calculator

You can use the battery calculator to estimate how much your battery would last.

SCK Battery Calculator

WIP!

What's the SCK's Shell?

Learn how to use the powerful SCK Shell. Check the guide.

Battery charging

The SCK has a micro USB port and can be charged like any smartphone or tablet using a dedicated adapter or a computer USB port.

We recommend using an external USB power adaptor, instead of a computer USB port, for quicker charging. Autonomy can be extended by using a Power Bank, or a 5V PV Panel.

Power Supply

The SCK needs 5V input via the micro USB connector. A normal 5V power charger can be used, although for outdoor developments we recommend using a waterproof power supply. Find more info in the power supply section.

User feedback

The LED serves as an indication of the battery status. If the LED is flashing orange it indicates that the battery must be charged. The battery takes about 4 hours to fully charge. When the battery is fully charged, the LED will change from orange to green .

Remember that in addition to these colors you will have the state color of the kit: configuration, network and sd.

More details

Find more details under the data board section

๐Ÿšฉ User interfaces

The data board features a set of user interfaces which provide feedback to the user, as well as two buttons with different functionalities. The main RGB LED provides general feedback of the data board status. Additionally, two buttons are provided for user action. A hardware reset button, which forces a power cut to the board, and a power button, used to change the device's mode, turn on and off the device, and to perform a factory reset. You can see both buttons below:

The button

The main button interaction is detailed below:

Function Button action
ON Push the button
OFF Push the button for 5 seconds
CHANGE MODE Push the button multiple times to choose: Setup Wi-Fi Pink
FACTORY RESET Push the button 15 seconds for a full reset

An example is shown below:

Troubleshooting

Have a look at the troubleshoothing section to check how you can use the buttons in case of problems with your SCK!

Operation modes

New WARNING feature

After release 0.9.8, a new warning feature was introduced. In an overall sense, this is the interpretation of each state:

  • Normal: no problem! Slow fading in the LED.
  • Warning: can take readings, but can't save them in the sdcard or can't send them to the platform (problem with network). Data is stored in the onboard Flash memory and will be saved after the problem is solved - either network comes back or the sdcard is OK. Partial blink in LED.
  • Error: can't take readings. Either there is "no time", or there is a big problem that prevents data to be read. Full fast blink in LED.

๐Ÿ’ก Remember, you can check your SCK firmware version quickly following this guide.

Setup mode

In this mode, the Kit is ready to be configured in network mode or SD card in start.smartcitizen.me.

LED color Kit status
๐Ÿ‘ Ready to be setup
๐Ÿ”‹ Ready to be setup but battery is low, charge the Kit
๐Ÿ”‹ Ready to be setup, battery charging
๐Ÿ”‹ Ready to be setup, battery charged

Wi-Fi mode

This is the standard mode for a network that requires a Wi-Fi connection. In this way, the device will publish the data every minute on the smartcitizen.me platform. If there is an inserted micro SD card, the data will be stored in it as well.

LED color Kit status
๐Ÿ‘ Collecting data online
โš ๏ธ Warning. Collecting data but not sending it online
โŒ Error. Not collecting data
๐Ÿ”‹ Collecting data online but battery is low, charge the Kit
๐Ÿ”‹ Collecting data online, battery charging
๐Ÿ”‹ Collecting data online, battery charged
๐Ÿ›๏ธ Sleep-mode. Collecting data online and saving battery

Warning

โœ… The kit supports Wi-Fi WEP, WPA/WPA2 and open networks that are common networks in domestic environments and small businesses.

โŽ But, it does not support WPA/WPA2 Enterprise networks such as EDUROAM or networks with captive portals such as those found in Airports and Hotels

Error in network mode

If you configure the SCK with a network that is not visible at the moment of configuring it, it will raise an error and it will not take data.

Flash memory

After firmware version 0.9.8, a new flash memory feature was implemented. That changed completely the arrangement of sensor readings vs publication/storage, and how errors are handled. From there on, data is always stored in flash memory before stored inย SD cardย or published over Wi-Fi. That means that data can be always recovered if there is a problem with theย SD cardย or the connection to the Internet fails, i.e. if we lose connection, the SCK will still store data and publish it in batch once the network is back!

Check and update your Kit software version

๐Ÿ’ก Remember, you can check your SCK firmware version quickly following this guide. Later, learn here how to update it.

Flash chip and sizes

The flash chip S25FL064L that we use is an 8ย MB SPI flash nonvolatile memory. The minimum erasable unit is a 4kb sector, the full memory contains 2,048 sectors with a total of 8,388,608 bytes or 8ย MB.

A normal reading group with the default urban board hardware installed is composed of 11 readings, hence we expect each reading to take 7 bytes: an average of 5 bytes for the reading itself plus 2 overhead bytes for SensorType and size. Each group should have a total of 77 bytes of readings, 2 bytes of size, 2 bytes of flags and 4 bytes of the time stamp. That means we can expect a normal group to be around 85 bytes. This means we can store almost 100,000 groups of readings, or around 70 days of readings with standard sensor hardware. This number can vary a little, though.

About flash memory lifespan, rounding numbers we can say we have enough space to store 2 months (60 days) of readings, according to the Flash memory datasheet we have at least 100,000 erase cycles: 2 months per cycle means 200,000 months, so we can expect more than 16k years!.

That can be very useful in many situations, for instance, where we cannot use permanent network connectivity, or we have intermittent electrical blackouts (standard battery required). Of course, everything has its limitations, and the flash memory follows a circular buffer, which means that when the flash memory is full, it will start overwriting data no matter if it was published or not. In a normal SCK, the flash memory will last for some weeks though, but it's better to always be on the safe side and not lose any data.

When the SCK loses connection, after three attempts to connect, it will enter warning mode (see here). After this, it will try again after 5 times the publication interval (by default 3'), which means, after the Internet connection is back the SCK will take a maximum of 15' to connect to it and start pushing data. The data publication is not immediate and will take some minutes. If you are in a hurry, click the user button twice (blue-red-blue mode) or reset the kit and data will start being posted right away.

Be careful!

Having a non-permanent WiFi connection means that we can also risk entering error mode if the SCK runs out of battery because it obtains the time from the internet (or from a phone during the SD card setup process). Losing the network connection and running out of battery means the device will lose the internal clock time, and the device will stop taking readings until it has power and can connect to the internet to sync, again.

Debugging commands

Check this guide for more debugging commands.

SD card mode (offline)

If we do not have an internet connection we can use the SD mode. In this case the device will record the data on the micro SD card. Later we can read the card using a card reader. The data can be visually spaced in a spreadsheet but also published on the smartcitizen.me platform using the UPLOAD CSV option.

LED color Kit status
๐Ÿ‘ Collecting data offline
โš ๏ธ Warning. Collecting data but not storing it in sdcard
โŒ Error. Not collecting data
๐Ÿ”‹ Collecting data offline but battery is low, charge the Kit
๐Ÿ”‹ Collecting data offline, battery charging
๐Ÿ”‹ Collecting data offline, battery charged
๐Ÿ›๏ธ Sleep-mode. Collecting data offline and saving battery

Guide

Check the guide on how to upload the sd card data here

Weird files?

The files in the sdcard have the following naming: YY-MM-DD.CSV, however, you will find in the some extra files (.01, .02...) These are data files that the sensor creates once there is a reset and, to avoid corruption, it creates a new file in the sd-card, by changing the file-extension.

A reset takes place every night at 3-4am with the purpose to avoid data loss because a problem. The SCK then stores the data in a file with a sequential name, and does so by changing the filename to YY-MM-DD.01, .02โ€ฆ etc depending on the amount of resets it sees during that day. You can see the data and work with it by changing the name from YY-MM-DD.01 to YY-MM-DD_01.CSV. Check the guide on how to organise your data to automatise this.

Especial status

You will see these colors in special moments, mostly when the kit is booting or being updated.

LED color Kit status
โณ Busy, please wait!
๐Ÿ”ง Software update going on!
๐Ÿ’ป Shell mode more info here

Software Updates

Sofware updates are release frequently in the Firmware repository. These updates will need to be applied periodically to the two main components of the SCK: the SAMD21 (main processor) and the ESP8266 (Wi-Fi module). Check the instructions under the Update the Firmware section for more information.

Smart Citizen Kits being tested at Fab Lab Barcelona

Test plan

You can find the Test plan, in case you are producing the SCK here.