The Thingy firmware is built on top of nRF5 Software Development Kit (SDK) v13.1.0 and utilizes many of its components, such as SDK peripheral drivers, SDK HAL, and the SoftDevice.

Thingy firmware architecture framework

Thingy adds the following modules on top of the nRF5 SDK:

Sensor drivers - Thingy uses the SDK peripheral drivers and Hardware Access Layers (HALs) and implements its own sensor drivers on top of them. These drivers are used to perform any operations on the sensors, such as enabling or disabling them, changing their configuration, or fetching sensor data.
BLE handler - Handles all Bluetooth communication and dispatches events to the processes.
Flash storage - Flash storage of configuration parameters.
BLE services - Layer containing all the custom BLE services used by the Thingy modules. These services are discussed in detail in the BLE services section.
Thingy modules - Layer containing high level functionality and features. Controlls both the sensor drivers and the corresponding BLE services. Responsible for handling persistent storage of configuration and the default configuration.
Thingy application

BLE services

This section focuses on the custom services used in the Thingy firmware together with their configuration parameters.

Thingy configuration service

The Thingy configuration service is responsible for handling all general configuration parameters that are not related to a particular module.

Name	UUID	Type	Data	Description
Base UUID	EF68xxxx-9B35-4933-9B10-52FFA9740042
Thingy configuration service	0100
Device name characteristic	0101	Write/Read	max 10 bytes	Device name as ASCII string.
Advertising param characteristic	0102	Write/Read	3 bytes	Advertising parameters (in units): uint16_t - Adv interval in ms (unit 0.625 ms). min 32 -> 20 ms max 8000 -> 5 s uint8_t - Adv timeout in s (unit 1 s). min 0 -> 0 s max 180 s -> 3 min
Connection param characteristic	0104	Write/Read	8 bytes	Connection parameters: uint16_t - Min connection interval (unit 1.25 ms). min 6 -> 7.5 ms max 3200 -> 4 s uint16_t - Max connection interval (unit 1.25 ms). Same as above. uint16_t - Slave latency (number of connection events). Range 0-499 uint16_t - Supervision timeout (unit 10 ms). Min 10 -> 100 ms Max 3200 -> 32 s The following constraint applies: conn_sup_timeout * 4 > (1 + slave_latency) * max_conn_interval that corresponds to the following Bluetooth Spec requirement: The Supervision_Timeout in milliseconds must be larger than (1 + Conn_Latency) * Conn_Interval_Max * 2, where Conn_Interval_Max is given in milliseconds.
Eddystone URL	0105	Write/Read	3-17 bytes	Eddystone URL. Data format: Byte 0: URL Scheme Prefix Bytes 1+: The rest of the URL using Eddystone URL encoding Write 0 bytes to disable Eddystone advertising. See Eddystone-URL for more information.
Cloud token	0106	Write/Read	max 250 bytes	Cloud token to be used for identification against cloud services.
FW version	0107	Read	3 bytes	uint8_t - major uint8_t - minor uint8_t - patch
MTU request	0108	Write/Read req	3 bytes	MTU request. Not retained. uint8_t - Peripheral exchange request 0x00 - Peripheral does not send an MTU exchange request. (Default behavior) 0x01 - Peripheral sends an MTU exchange request, when written to 0x01. uint16_t - MTU size requested (23 - 276 bytes).
NFC Tag content characteristic	0109	Write/Read	max 247 bytes	Content of NFC tag.

Environment service

The environment module is responsible for reading the temperature, pressure, humidity, air quality/gas, and light intensity/color sensors, as well as for sending data and configuration. It is running on top of the environment BLE service (ble_tes), the environment sensor drivers, and the environment flash storage with base UUID EF68xxxx-9B35-4933-9B10-52FFA9740042. The configuration is stored in flash. To turn on sensor reading, enable notifications from the desired characteristic by writing 0x0001 to the Client Characteristic Configuration Descriptor (CCCD) for that characteristic.

Name	UUID	Type	Data	Description
Base UUID	EF68xxxx-9B35-4933-9B10-52FFA9740042
Weather station service	0200
Temperature characteristic	0201	Notify	2 bytes	Temperature in Celsius int8_t - integer uint8_t - decimal
Pressure characteristic	0202	Notify	5 bytes	Pressure in hPa int32_t - integer uint8_t - decimal
Humidity characteristic	0203	Notify	1 bytes	Relative humidity in % uint8_t - RH
Gas (Air quality) characteristic	0204	Notify	4 bytes	uint16_t - eCO2 ppm uint16_t - TVOC ppb
Color characteristic	0205	Notify	8 bytes	uint16_t - Red uint16_t - Green uint16_t - Blue uint16_t - Clear
Configuration characteristic	0206	Write/Read	12 bytes	uint16_t - Temperature interval in ms (100 ms - 60 s). uint16_t - Pressure interval in ms (50 ms - 60 s). uint16_t - Humidity interval in ms (100 ms - 60 s). uint16_t - Color interval in ms (200 ms - 60 s). uint8_t - Gas mode 1 = 1 s interval 2 = 10 s interval 3 = 60 s interval Color sensor LED calibration: uint8_t - Red intensity [0 - 255] uint8_t - Green intensity [0 - 255] uint8_t - Blue intensity [0 - 255]

User interface service

The UI module handles the onboard LEDs, buttons, and other potential UI components like a quadrature decoder, touchscreen etc. The UI module runs on top of the UI BLE Service (ble_uis), the LED and button drivers, and the UI flash storage with base UUID EF68xxxx-9B35-4933-9B10-52FFA9740042. This module enables RGB LED value setting and button event notifications via BLE. Button notification is enabled by writing 0x0001 to the CCCD of the button characteristic.

Name	UUID	Type	Data	Description
Base UUID	EF68xxxx-9B35-4933-9B10-52FFA9740042
UI service	0300
LED characteristic	0301	Write req/Read	Max 5 bytes	RGB Value: uint8_t - Mode (retained for BLE connected and disconnected): 0 = Off 1 = Constant 2 = Breathe 3 = One Shot Constant mode (retained for BLE connected): uint8_t - R intensity (0 - 255) uint8_t - G intensity (0 - 255) uint8_t - B intensity (0 - 255) Breathe mode (retained for BLE connected): uint8_t - color: 0x01 - RED 0x02 - GREEN 0x03 - YELLOW 0x04 - BLUE 0x05 - PURPLE 0x06 - CYAN 0x07 - WHITE uint8_t - intensity (1-100) [%] uint16_t - delay [ms] (50 ms - 10 s) One shot mode (retained for BLE connected): uint8_t - color: 0x01 - RED 0x02 - GREEN 0x03 - YELLOW 0x04 - BLUE 0x05 - PURPLE 0x06 - CYAN 0x07 - WHITE uint8_t - intensity (1-100) [%] Default connected behavior: Mode: Breathe Color: CYAN Intensity: 20% Delay: 3500 ms
Button characteristic	0302	Notify	1 byte	Boolean button state: 0: Button released 1: Button pressed
EXT pin characteristic	0303	Write req/Read	4 bytes	External pin control. Range 0 - 255. 0 is off, 255 is on. PWM is not implemented. So either 0 or 255. uint8_t - MOS_1 uint8_t - MOS_2 uint8_t - MOS_3 uint8_t - MOS_4

Motion service

The motion module is responsible for reading the 9-axis motion sensor and the low power accelerometer, as well as for sending the data and flash storage of the configuration parameters for this module. It is running on top of the motion BLE service (ble_tms) with base UUID EF68xxxx-9B35-4933-9B10-52FFA9740042. The configuration is stored in flash memory. To turn on sensor reading, enable notifications from the desired characteristic by writing 0x0001 to the Client Characteristic Configuration Descriptor (CCCD) for that characteristic.

Name	UUID	Type	Data	Description
Base UUID	EF68xxxx-9B35-4933-9B10-52FFA9740042
Thingy motion service	0400
Config characteristic	0401	Write/Read	9 bytes	Motion configuration: uint16_t - Step counter interval in ms (100 ms - 5 s). uint16_t - Temperature compensation interval in ms (100 ms - 5 s). uint16_t - Magnetometer compensation interval in ms (100 ms - 1 s). uint16_t - Motion processing unit frequency in Hz (5 - 200 Hz). uint8_t - Wake-on-motion 0x00 = Off 0x01 = On
Tap characteristic	0402	Notify	2 bytes	Direction and count of taps: uint8_t - Direction: 0x01 = TAP_X_UP 0x02 = TAP_X_DOWN 0x03 = TAP_Y_UP 0x04 = TAP_Y_DOWN 0x05 = TAP_Z_UP 0x06 = TAP_Z_DOWN uint8_t - Count Number of taps in the given direction
Orientation characteristic	0403	Notify	1 byte	uint8_t - Orientation 0x00 = Portrait 0x01 = Landscape 0x02 = Reverse portrait 0x03 = Reverse landscape
Quaternion characteristic	0404	Notify	16 bytes	Attitude represented with quaternions (2Q30 fixed point): int32_t - w int32_t - x int32_t - y int32_t - z
Step counter characteristic	0405	Notify	8 bytes	Step counter: uint32_t - Steps uint32_t - Time [ms]
Raw data characteristic	0406	Notify	18 bytes	Motion sensor raw data: Accelerometer int16_t - x [G] (6Q10 fixed point) int16_t - y [G] (6Q10 fixed point) int16_t - z [G] (6Q10 fixed point) Gyroscope int16_t - x [deg/s] (11Q5 fixed point) int16_t - y [deg/s] (11Q5 fixed point) int16_t - z [deg/s] (11Q5 fixed point) Compass int16_t - x [µT] (12Q4 fixed point) int16_t - y [µT] (12Q4 fixed point) int16_t - z [µT] (12Q4 fixed point)
Euler characteristic	0407	Notify	12 bytes	Attitude represented in Euler angles (16Q16 fixed point) int32_t - roll [degrees] int32_t - pitch [degrees] int32_t - yaw [degrees]
Rotation matrix char	0408	Notify	18 bytes	Attitude in rotation matrix (2Q14 fixed point) int16_t [9] - 3 x 3 matrix
Heading characteristic	0409	Notify	4 bytes	Heading (16Q16 fixed point) int32_t - Heading [degrees]
Gravity vector	040A	Notify	12 bytes	Attitude represented by a gravity vector: float - x float - y float - z

Sound service

The sound module is responsible for handling both the speaker and the microphone. The sound module is built on top of the sound BLE service (ble_tss) with base UUID EF68xxxx-9B35-4933-9B10-52FFA9740042. The configuration is stored in flash.

Name	UUID	Type	Data	Description
Base UUID	EF68xxxx-9B35-4933-9B10-52FFA9740042
Thingy sound service	0500
Config characteristic	0501	Write/Read	2 bytes	Sound configuration uint8_t - Speaker mode: 0x01 - Frequency and duration. 0x02 - 8-bit PCM 0x03 - Sample uint8_t - Microphone mode 0x01 - ADPCM 0x02 - SPL
Speaker data characteristic	0502	Write without resp	Max 273 bytes	In frequency mode: uint16_t - Frequency in Hz (0 - stop forever). uint16_t - Duration in ms (0 = forever). uint8_t - Volume in % (0-100). In PCM mode: uint8_t [20 - 273] 8-bit PCM samples In sample mode: uint8_t - sample ID (0x00 - 0x08) 0 Collect_Point_00.wav 1 Collect_Point_01.wav 2 Explosion_02.wav 3 Explosion_04.wav 4 Hit_00.wav 5 Pickup_01.wav 6 Pickup_03.wav 7 Shoot_00.wav 8 Shoot_01.wav
Speaker status characteristic	0503	Notify	1 byte	Speaker status uint8_t - 0x00 - Finished uint8_t - 0x01 - Buffer warning uint8_t - 0x02 - Buffer ready uint8_t - 0x10 - Packet disregarded uint8_t - 0x11 - Invalid command
Microphone characteristic	0504	Notify	Max 273 bytes	ADCPM mode ADPCM frame

Battery service

This module is responsible for handling battery level information.

Name	UUID	Type	Data	Description
UUID	180F	Notify/Read	1 byte	uint8_t State of charge [%] (0-100) Uses a lookup table to convert from battery voltage to state of charge (SoC). Due to the ADC configuration and battery model, certain percentage values are skipped. Will only update/notify if there is a change in remaining battery level.

DFU service

This module is responsible for running Device Firmware Updates on Thingy.

Name

UUID

Type

Data

Description

Secure DFU Service

FE59

Base UUID

0000xxxx-0000-1000-8000-00805f9b34fb

DFU Control Point characteristic

8EC90001-F315-4F60-9FB8-838830DAEA50

Notify/Write

1 byte

Steps to put Thingy into Buttonless DFU mode:

Enable notifications for the DFU Control point characteristic
Write 0x01 to the characteristic

Firmware components

This firmware consists of the following components. Follow the links for their API documentation.

BLE services

Thingy Configuration Service Service that handles various configuration characteristics.
Thingy Environment Service GATT-based service with multiple characteristics for reading environment sensor data and configuring the sensors.
Thingy Motion Service GATT-based service with multiple characteristics for reading motion sensor data and configuring the sensors.
Thingy Sound service GATT-based service that handles the Thingy microphone and speaker.
Thingy User interface service Service that handles the Thingy RGB LED and button.

Drivers

Accelerometer driver Accelerometer driver API, including the LIS3DH accelerometer.
Color sensor Digital color sensor API, including the BH1745 color sensor.
GPIO extender GPIO extender API.
Gas sensor Digital gas sensor API, including the CCS811 gas sensor.
Humidity sensor Humidity sensor API, including the HTS221 sensor.
Microphone Microphone driver API.
Motion sensor Motion sensor API.
NFC driver Near Field Communnication (NFC) driver API.
Pressure sensor Pressure sensor API, including the LPS22HB sensor.
Speaker Speaker driver API.

Thingy modules

BLE handling BLE handling module API, including its flash configuration.
Battery measurement Battery measurement module API, including its flash configuration.
Environment Environment module API, including its flash configuration.
Motion Motion module API, including its flash configuration.
Sound Sound module API.
User interface User interface module API, including its flash configuration.

Utilities

Common macros A set of useful macros.
Eddystone beacon A set of APIs related to Eddystone beacon advertising.
Sx150x LED driver registers Settings for all LED driver registers on the Sx150x.
Sx150x LED driver register calculation Sx150x LED driver register calculation API.
Support functions Support functions.