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](/Guides/getting%20started/Using%20the%20Shell/).
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 mode SD Card mode (offline) |
| 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.
Test plan
You can find the Test plan, in case you are producing the SCK here.