Skip to content

Edit the firmware

The data board of your SmartSmart Citizen Kit is has two two microcontrollers:

The main one is an Atmel SAMD21, this chip is in charge of all the normal tasks like reading the sensors, saving data, interacting with the user, etc. For this chip we need two software components the bootloader and the main firmware.

For communications the SCK has an ESP8266 microcontroler with Wifi capabilities, this chip receives instructions from the SAMD21 via serial port and takes care of publishing the collected data through the network and takes care of serving the web pages for the setup mode configuration server.

Development enviroment

The SmartSmart Citizen Kit Firmware is on our repository on github so you will need git software installed.

To build the SmartCitizen Kit firmware you need a computer with platformio installed. You don't need the full IDE installation (Atom). You can follow this instructions to install only the console version.

For bootloader upload you also need OpenOCD somewhere in your PATH.

Getting the firmware

To get the firmware just run:

git clone --recursive

The bootloader and tools repositories are submodules of the main firmware so you must do a --recursive clone to get them.


I you download the code manually (with the clone or download button on github) you will not get the bootloader and tools submodules code. To be able to compile the firmware you need to download the tools submodule and place it in the proper folder.

SAMD21 bootloader

If your kit doesn't have the bootloader already flashed (all the kits that we ship come with it) you will need an ATMEL-ICE programmer. This process can also be done with a Raspberry Pi computer and the proper connector and cables, in this guide you will find informtaion on how to do this.

Connect the Atmel-ICE programmer to the 10 pin SWD connector and to your computer. Power the SCK via USB, you can use any USB charger or even your computer.

Open a terminal, go to the folder where you cloned the firmware repository and run:

cd smartcitizen-kit-21
./ boot

You will see a lot of output when compiling, the led on the SCK should breath in green and you should see an output similar to this:

You are ready for the next step, just remember to disconnect the Atmel-ICE programmer and connect the SCK to your computer with a USB cable.

SAMD21 firmware

The bootloader we just flashed allows a very simple way of uploading the SCK firmware based on the UF2 format, when you double-click the reset button of your kit it will expose a MSD interface to your computer and a new drive will popup where you can just drag the compiled firmware file (converted to UF2 format).

Reset button

Build script

You can use the same script used to flash the bootloader ( that will do everything for you: compile the firmware, convert the binary to UF2 format and upload it to the kit:

python3 build flash sam

If this is your first time building the software, platformio will take a while installing all the needed dependencies, be patient. If there are no errors you should see an output similar to this:

A copy of the compiled software in UF2 format called SAM_firmware.uf2 will remain in the bin folder. You can use this file to reflash your kit without compiling it again.


If you have any problem you can enable verbose output by calling script with the -v flag. There is a known issue that causes first compilation to fail, if this happens please just try again.

Manual install

If you want to install the firmware manually (or you had some problem with the build script) just follow this steps:

cd sam
pio run

After a lot of compilation messages you should see an output similar to this:

then to convert the binary firmware to UF2 format do:

cd ..
./tools/ -o SAM_firmware.uf2 sam/.pio/build/sck2/firmware.bin

you should see something like this:

Now double-click the reset button of your kit open your favorite file browser and drag the file you just created to the SCK-2.0 drive. The kit will reset and run the new firmware.


Keep in mind that if your computer is not configured to automount new drives you will need to mount your sck manually (as any other USB drive).

ESP8266 firmware

Just like the other parts of the process this is also covered by our script. So you can just do:

python3 build flash esp
As before, if this is the first time you do it, it will take a while on downloading dependecies and building the firmware.

In this case the upload process is different, since the ESP8266 chip is not connected to the USB interface the data must be uploadded through the SAMD21 chip. Our upload script takes care of searching for a SCK on the USB bus, sending a command to the kit so it put's himself in what we call bridge mode (white led) and uploading the firmware. This is the expected output:


Sometimes the ESP8266 and the uploader software don't get synced and the upload fails. Normally if you try again it will work. After first try you don't need to rebuild, you can just do python3 flash esp.