Features

Power management

SCK2.3 needs a battery

Due to the power needs of the SCK2.3 (and SCK2.2), it always needs a battery connected.

The Smart Citizen Kit features a micro USB slot and a LiPo Battery charger. The micro USB slot can be used with different power supplies: any USB-compatible power supply with 2A will do. Check the power supply section for more information.

Is the Kit turning itself off?

You will note that the kit seems to turn itself off. This is what we call sleep-mode, an operation mode implemented to reduce consumption. Check the operation modes section below. The Kit is still collecting data and functioning properly.

Battery duration

The Smart Citizen Kit has off-the-shelf support for LiPo batteries. If you got the Starter Kit, you should have already the 2000mAh battery that came with the Kit. The battery is meant to be a power option for short-term measurements (roughly 2-3 days) and a backup solution when the Kit is used for longer periods. If you want to take long-term measurements, we recommend permanently powering the kit via USB with a power supply.

The battery duration is dependent on which sensors are enabled, and how frequently you take measurements and send data to the platform. All these options can be configured with the shell.

Sensor and publication interval management

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

Battery calculator

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

SCK Battery Calculator

What's the SCK's Shell?

Learn how to use the powerful SCK Shell. Get more details in our 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. You can also use a power bank or a solar panel.

Power supply

The SCK needs 5V input via the micro USB connector. A normal 5V power charger can be used, as long as it's USB compatible, and provides 2A. For outdoor deployments, we recommend using a waterproof power supply. Optionally, you can use a solar panel.

Battery status

The SCK will display user feedback via a set of LEDs. To show the battery status, we use the STATUS LED. There are two more LEDs, one that shows if the Wi-Fi antenna is ON, or if data is being transmitted via USB.

If the STATUS LED is aggressively flashing in orange , it indicates that the battery must be charged. The default 2000mAh battery takes about 4 hours to fully charge. If you have the USB charger connected, you will notice that when the battery is charging, the LED will flash in orange , and when it's fully charged, it will flash in green .

Other colors

Remember that in addition to these colors, you will have the state color of the kit: setup, online, and offline modes. Check the operation modes section for more information.

User interfaces

The Data board features a set of LEDs that provide feedback to the user, as well as two buttons with different functionalities. The STATUS LED provides general feedback on the data board status, both on the operation mode and the battery status. Additionally, two buttons are provided for user action: a hardware RESET button, which literally does a full reset on the board, and an ON/OFF button, used to change the device's mode, turn on and off the device, and perform a factory reset. You can see both buttons below:

The ON/OFF 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 change mode between: Setup Wi-Fi mode (online) or SD-Card mode (offline)
FACTORY RESET	Push the button for 15 seconds to perform a full reset

Changing mode

When you change the mode, the SCK will switch between Setup mode, and whatever mode you have configured (online or offline).

For instance, if you configured your kit in online mode, clicking the ON/OFF button will switch the SCK to setup mode. Clicking it again will switch the SCK back to online mode.

You can see it in action below (remember, the SCK 2.X series share the same data board!):

The RESET button

This button is used for troubleshooting your kit, or to upgrade the firmware. Unless you are in any of these situations, you shouldn't need to touch this button! In any case, it's useful to know what it's for.

SCK 2.1/SCK2.2SCK 2.3

Using the button inside a box

If you are using an SCK2.1 or SCK2.2 inside a box, it may be tricky to access the RESET button. Check the enclosures page for more options.

On the SCK2.3, we made a little hole in the Urban Board to make it easier to access the reset button.

Local access point

A local access point (AP) is used to configure the SCK. You can connect to this AP with your Smartphone or computer, by connecting to a Wi-Fi network called "SmartCitizen[...]". To do so, make sure that the SCK is in Setup Mode.

In your phone, something like below should pop-up:

If nothing comes up

In some cases, your phone will be disconected from the WiFi as it doesn't have access to the internet. Stay connected to it!

If nothing pop-up in your phone, open your phone's web browser and navigate to sck.me

Operation modes

Setup mode

In this mode, the kit is ready to be configured for Wi-Fi mode or for SD-card mode.

LED color	Kit status
	Ready for setup
	Ready for setup but battery is low, charge the Kit
	Ready for setup, battery charging
	Ready for setup, battery charged

Wi-Fi mode

Wi-Fi mode (or online mode), is the most common mode for the Kit. In this mode, it will publish data to the Smart Citizen Platform. If there is a micro SD card in the Kit, data will be stored in it too.

LED color	Kit status
	Collecting data online
	Warning. Collecting data but not sending it online
	❌ Error. Not collecting data
	Collecting data online but the 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 which 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 (or working) at that precise moment, it will raise an error and will not collect data.

SD-card mode

SD-card mode (or offline mode), can be used if you do not have an internet connection available. In this case, the device will record the data on the micro SD card, in CSV format. You can take a look at this data in a spreadsheet, or upload it to the Smart Citizen Platform by using the CSV Upload option, or via the API.

LED color	Kit status
	Collecting data offline
	Warning. Collecting data but not storing it in SD card
	❌ Error. Not collecting data
	Collecting data offline but the battery is low, charge the Kit
	Collecting data offline, battery charging
	Collecting data offline, battery charged
	Sleep-mode. Collecting data offline and saving battery

Weird files?

The CSV files in the SD card have the following naming: YY-MM-DD.CSV. However, sometimes you may find some extra files:

• Before 0.9.9 firmware version: the files are YY-MM-DD.01, YY-MM-DD.02...
• After 0.9.9 firmware version: the files are YY-MM-DD_01.CSV, YY-MM-DD_02.CSV...

These are data files that the sensor creates when it reboots, to avoid file corruption. It does so by creating a new file on the SD card. In older firmware versions, it's normal to have some additional files, especially because of the sanity reset. Note that after the 0.9.9 firmware version you should only get one file per day, even with the sanity reset. If you have more than one, the kit has reset.

Warning and error levels

After firmware version 0.9.8, a new WARNING mode was introduced. This feature gives feedback to the user in case something not too bad has happened, and the kit is able to still collect data, but not store it on the micro SD card or send it to the platform. This WARNING mode is a new addition to existing NORMAL and ERROR modes.

Below we explain what each mode does:

• NORMAL: no problem! The STATUS LED is slowly breathing and readings are being collected normally.
• WARNING: the SCK can take readings, but can't save them to the micro SD card (either it doesn't find it or there is a problem with it) or send them to the platform (problem with network). Data is stored in the onboard Flash memory and will be stored on the SD card or sent to the platform after the problem is solved: either because the network comes back or the SD card is reinserted (or fixed). The STATUS LED is partially blinking in this situation.
• ERROR: can't take readings. Either there is "no time", or there is a big problem that prevents data to be read. The STATUS LED is agressively blinking.

Info

Remember, you can check your SCK firmware version quickly following this guide.

Special status

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

LED color	Kit status
	Busy, please wait!
	Software update is ongoing!
	Shell mode more info here

Permanently in one color?

That's not normal, so either reset your kit or write us on the forum.

Auxiliary connector

The Data Board features a standard Grove Connector to connect external sensor modules. The connector supports an independent I2C bus by default, but with software, it can be configured to support other uses (GPIO, I2C, and UART). It can supply power up to 750mA, and it can be enabled or disabled by software to save energy.

There is a lot more to it!

The Smart Citizen Kit is designed with a modular approach in mind. This means that the Urban Board is only a selection of low-cost sensors for air quality, but the hardware itself can be expanded for other use cases such as a more advanced air quality monitoring setup, soil monitoring, or water quality. Check out our sensor library and our guide on how to use them.

Software Updates

Sofware updates are released in the firmware repository. These updates will need to be applied periodically to the two main microcontrollers of the Data Board: the Atmel SAMD21 (main processor) and the Espressif ESP8266 (Wi-Fi module). Check the instructions in the firmware upgrade guide for more information.

Special features

Internal memory

After firmware version 0.9.8, a new flash memory feature was implemented. The flash memory feature is used to store data internally before publishing it to the Smart Citizen Platform or storing it into the micro SD card. This allows us to still collect data when there is no Wi-Fi, when the SD card is not present or corrupt, or to recover data in general. This feature is very useful in many situations, for instance, whenever we cannot use permanent network connection, or you are using the SCK while moving around in the city. The flash memory feature changes completely how readings are handled, separating sensor readings and the publication or storage process. This also affects how errors are handled, allowing for the introduction of a new WARNING mode.

Check and upgrade the firmware version

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

Of course, everything has its limitations: the flash memory follows a circular buffer, which means that whenever 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 (more details in the flash memory section), but it's better to always be on the safe side and to avoid losing any data, make sure to check the STATUS LED for any warnings or errors.

In the particular case of the Wi-Fi mode, two possible things can happen:

• If the SCK has time but it doesn't have a stable network connection, it will attempt three times to connect to the network. If all 3 attempts fail, it will enter WARNING mode (see here for more information). After these initial attempts, by default, it will try again after 15' (or 5 times the publication interval, in case you changed it). This allows us to avoid wasting energy by trying to connect to an unexisting or unstable network, but it also has a side effect: after the network connection is back, the next attempt to connnect will take some time, and it will take a maximum of 15' to connect to it and start pushing data. If you are in a hurry, click the ON/OFF button twice (blue->red->blue mode) or RESET the kit and data will start being posted right away.
• On the contrary, if the SCK doesn't have time, then it will always be in ERROR mode until it manages to connect to the network and get the time from it. It will keep trying to connect forever.

Be aware of the time

Having a non-permanent Wi-Fi connection means that we can also risk entering error mode if the SCK runs out of battery. This is because the SCK 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.

Sanity reset

The kit will force reboot itself every night at 00:00 UTC. We call this sanity reset and it's done to prevent simple issues to build up. Until firmware 0.9.8, the sanity reset took place at 2am UTC, but it was changed on 0.9.9 to 00:00 UTC to avoid creating unnecessary CSV files in the SD card because of this reset.

You can disable this

This reset will cut all power to internal and external sensors, and potentially affect their readings. You can disable this feature using-the-shell.

Massive storage mode

The Massive storage mode is mostly used to upgrade the SAMD21 firmware, by a simple drag-and-drop. However it also has interesting files:

CURRENT.UF2
INDEX.HTM
INFO_UF2.TXT

• CURRENT.UF2: your current firmware binary file
• INDEX.HTM: a link to the firmware current releases page

• INFO_UF2.TXT: information about the bootloader version, hardware model and board:

  UF2 Bootloader v2.0.0-adafruit.5-3-g6402020-dirty SFHWRO
  Model: Smartcitizen Kit 2.0
  Board-ID: SAMD21G18A-sck2-v2
  

SD card access

You can access files from the SD card using-the-shell. This is described in the Data - SD card Section.