Nordic Thingy:52
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Firmware architecture

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

thingy_firmware_arch.png
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. Controlling both the sensor drivers and the corresponding BLE services. Also, 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.
    • Range 0-499

  • uint16_t - Supervision timeout.

    • 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 max 17 bytes Eddystone URL. Data format:
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).

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.

NameUUIDTypeDataDescription
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 - 5000 ms).
  • uint16_t - Pressure interval in ms (50 ms - 5000 ms).
  • uint16_t - Humidity interval in ms (100 ms - 5000 ms).
  • uint16_t - Color interval in ms (200 ms - 5000 ms).
  • 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 0x1000 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] (1 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 - 5 s).
  • uint16_t - Motion processing unit frequency in Hz (1 - 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 4 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.
  • 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

DFU service

This module is responsible for running Device Firmware Updates on the 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 the 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

Drivers

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.
  • User interface User interface module API, including its flash configuration.
  • Motion Motion module API, including its flash configuration.
  • Sound Sound module API.

Utilities