Almabike Sensors User Manual¶
Welcome to the Almabike Project User Manual. This page includes all necessary information to get started with the sensor kit.
In addition, further information and graphic material is available in the Annexes of this manual.
Some items in this user manual are a work-in-progress. You will find a banner in the sections with a WIP marker and a summary of all Known issues which will be fixed in future firmware versions.
The delivered sensor pack is comprised of these components:
The SCK and GPS are assembled with a 3D-printed Clip:
The enclosure is made out of a modified saddle bag. Find more details in enclosure:
All the software used in this (product/prototype/design), unless otherwise stated, is released under GNU GPL v3.0. Likewise, the hardware design files for the Smart Citizen Kit are released under CERN OHL v1.2. Please refer to the corresponding license for details regarding permissions, limitations, and conditions of use. This paragraph only applies to this section and the enclosure customization, and not to the rest of components such as the GPS or antenna.
The sensors are based on the Smart Citizen Kit, with the following components.
|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|
The selected NEO-M8U GPS Breakout from Sparkfun is a high quality GPS board. The NEO-M8U takes advantage of u-blox's Untethered Dead Reckoning (UDR) technology. The NEO-M8U module is a 72-channel u-blox M8 engine GNSS receiver, meaning it can receive signals from the GPS, GLONASS, Galileo, and BeiDou constellations with ~2.5 meter accuracy. The module supports concurrent reception of three GNSS systems. The combination of GNSS and integrated 3D sensor measurements on the NEO-M8U provide accurate, real-time positioning rates of up to 30Hz.
Compared to other GPS modules, this breakout maximizes position accuracy in dense cities or covered areas. Even under poor signal conditions, continuous positioning is provided in urban environments and is also available during complete signal loss (e.g. short tunnels and parking garages). Lock time is further reduced with on-board rechargeable battery; there is a backup power enabling the GPS to get a hot lock within seconds.
The SparkFun NEO-M8U GPS Breakout1 is also equipped with an on-board rechargeable battery that provides power to the RTC on the NEO-M8U. This reduces the time-to-first fix from a cold start (~26s) to a hot start (~1.5s). The battery will maintain RTC and GNSS orbit data without being connected to power for plenty of time.
The GPS uses a ceramic patch antenna2 with the following features:
The U.FL antenna connector does not need to be unplugged from the board, specially never when the board is being powered in order to avoid damaging the circuitry:
The enclosure is made out of a modified generic Saddle Bag from Vaude - (Vaude Race Light L).
Enclosure images by Vaude
The enclosure was specifically chosen because:
- It is a widely available enclosure by a well stablished bike equipment manufacturer
- Size and materials
- Low weight and flexible outter fitting for low vibrations and transmissibility
The sensors are internally suspended by a polypropilene folding and the air intakes are made out of PLA in a 3D printer.
The sensors are enclosed in the saddle bag in order to avoid dirt and water spills. The measurement method in the enclosure ensures there is: 1. sufficient air flow parallel to the sensor's surface, 2. a limited gas speed across the sensors and minimum gas residence time to ensure sensitivity. The placement of the sensors was tested and compared with different options. Results are shown in the Test section. The images below show the measurement principle and a functional diagram for the sensor’s enclosure.
Please, ensure both intakes and exhaust are not covered and that air can flow freely between both.
This will be improved with new Firmware Features. Current battery duration is 1 day with 2-3 short bicycle trips of 30' each. This will improve with upcoming firmware updates.
The SCK comes with a 2000mAh LiPo battery to provide autonomy while measuring in the city. The battery is meant to be a complete power option for short-term measurements (approximatively 1-2 days). The battery duration is dependent on which sensors are enabled or disabled, and the amount of time the dynamic measurement interval is active.
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.
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. A cable is provided and does not need to be disconnected from the device. The cable can be stored in the saddle’s bag back compartment.
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.
Find more details about power management under the data board section of the documentation
Data can be recorded offline or published online to the Smart Citizen Platform. The SCK owner needs to configure how the data is going to be stored in the Setup process, either in the SD card or via network connectivity (WiFi) to the platform.
When the SCK is configured in sdcard mode, it will store the data at the requested interval* in the SD card.
In the case of network connectivity, in normal conditions, the device will send data over to the Smart Citizen Platform via WiFi (WPA2 Personal or WEP). Additionally, when configured to send data over WiFi, if there is a SD card present, it will also store the data in it as a backup. Finally, in the special case of mobile sensors, where network connectivity is not always present, the data can be recorded offline on its internal dedicated flash memory of 8MB and later publish this over WiFi connectivity. Data is published using MQTT messages to the Smart Citizen Platform. NTP is used for syncing the built-in RTC.
In order to understand the reading and publication intervals, it is important to describe how the structure of the measurements is done:
- Overall reading interval: base period for the SCK to take a measurement
- Individual sensor reading interval: period for each sensor to take a measurement. It is defined as N times the Overall reading interval
- Publication interval: time for the SCK to publish to the Smart Citizen Platform, independent of the reading interval.
Each of the sensors can be configured independently, with a reading interval N times the overall reading interval. For the Almabike project, all the sensors are read every 60s if the sensors are static. When a GPS movement is detected, the reading interval goes down to 5s.
In the case of the Almabike project, the sensors store data internally in the Flash memory during the bicycle trips and publish it in batch when the configured WiFi network is visible. Data is also stored in the SD card for later use in CSV file format.
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 main button interaction is detailed below:
|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|
Have a look at the troubleshoothing for more information.
This will be improved with new Firmware Features.
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|
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 duplicate.
|LED color||Kit status|
|Collecting data online|
|Error while collecting data|
|Collecting data online but battery is low, charge the Kit|
|Collecting data online, battery charging|
|Collecting data online, battery charged|
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
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|
|Error while collecting data|
|Collecting data offline but battery is low, charge the Kit|
|Collecting data offline, battery charging|
|Collecting data offline, battery charged|
Check the guide on how to upload the sd card data here
The files in the sdcard have the following naming: YYYY-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 complete 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 YYYY-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 YYYY-MM-DD.01 to YYYY-MM-DD_01.CSV
|LED color||Kit status|
|Busy, please wait!|
|Software update going on!|
Accessing the data¶
Data from the sensors can be accessed in four ways:
- Using the SD card. Follow this guide to understand the data formats
- Downloading data from Smart Citizen Platform, following this guide
- Using the API calls, with information here
- Using Python to interact directly with the API. There is a python package available here and an example on how to do so here
Data from the sensors is timestamped in ISO8601 format with the following metrics:
|BATT||%||Device battery status|
|CCS811_VOCS||ppb||total Volatile Organics Compounds|
|GPS_DIL||n/a||GPS Horizontal Dilution of Position|
|GPS_FIX_QUALITY||n/a||GPS Fix Quality|
|GPS_SAT_N||n/a||GPS Number Tracked Satellites|
|GPS_SPEED||m/s||GPS Horizontal Speed|
|HUM||% RH||Urban board humidity|
|LIGHT||lux||Urban board ambient light|
|NOISE_A||dBA||Noise measurement in A scale|
|PM_1||ug/m3||PM 1 measurement from PMS5003|
|PM_25||ug/m3||PM 2.5 measurement from PMS5003|
|PM_10||ug/m3||PM 10 measurement from PMS5003|
|TEMP||degC||Urban board temperature|
Notes about data:
- Non valid data is shown in CSV as
- There is no correction in the data
- The minimum refresh interval for the PM sensor is 1s (it won't change faster than that)
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.
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 (guide here)
Make sure data is recorded
For the Almabike project, it is important to follow the steps below in order to select the correct kit blueprint while registering the sensor:
Click the 🛠️ icon in the bottom right corner
Choose the blueprint of the device you want to setup, in this case:
Click save and continue the process as usually
Due to privacy concerns, all geolocated data for the Almabike project will remain private unless the user choses to release it. When you set up your user profile, please, contact "email@example.com" to request your if your user can be upgraded from
This will allow to visit any of your devices and select the option "Make private" under the "Open Data" settings:
Before going on a trip¶
Before starting to pedal, make sure that this checklist is all fine:
- The kit is either in SD card or network mode
- The kit has enough battery (check the status of the LED)
- The GPS is being powered. The GPS might take some time to retrieve a valid location. This can be assessed by checking that the GPS Blue LED is blinking. If you want to make sure the complete trip is recorded, make sure the GPS can receive a clear view of the sky
- The kit is well placed inside the enclosure and the cable does not obstruct the exhaust
What is the GPS fix?
The GPS fix is the term used for describing whether or not the GPS has successfully received a valid location
Below, there is a list of known issues with the
0.9.8 version of the Firmware. These will be fixed soon.
Currently, the SCK does not report errors permanently and only during 10s. This is shown as a fast led blinking ().
Under certain conditions, the dynamic interval is not instantly recovered after a quick stop, and it might take 1' to restart
Under certain sky visibility conditions, the GPS does not report a valid fix. It is normally fixed with a clear sky view. For this, follow the instructions in Before going on a trip
Updating the firmware
Once there is a firmware release with these updates, refer to this guide for instructions on how to update it in your kit
Additional graphic material¶
GPS NEO-M8U Specification: https://cdn.sparkfun.com/assets/6/d/7/c/6/NEO-M8U_DataSheet__UBX-15015679_.pdf ↩
Ceramic Patch Antenna Specification: https://www.molex.com/pdm_docs/as/2066400001-AS.pdf ↩