• API
cloze

Atmotube BLE API v.1.1

This document describes open Atmotube (atmotube.com) bluetooth low energy API.
Atmotube broadcast format is open and can be parsed with any BLE-enabled device.


Atmotube in Android nRf Master Control Panel

https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp

Atmotube in iOS nRf Master Control Panel

https://itunes.apple.com/us/app/nrf-master-control-panel-ble/id1054362403?mt=8

BLE advertising packet format

02010611079ecadc240ee5a9e093f3a3b50100406e08ffffff02941e1c41090941544d4f545542450bffffff96baca2342fc363700000000000000000000

Bytes Example Description
5 0201061107 info bytes
16 9ecadc240ee5a9e093f3a3b50100406e service UUID = 6e400001-b5a3-f393-e0a9-e50e24dcca9e
5 08ffffff info bytes
5 02941e1c41 Atmotube data - see format below
2 0909 info bytes
8 41544d4f54554245 device name ATMOTUBE
4 0bffffff info bytes
6 96baca2342fc MAC address FC:42:23:CA:BA:96
2 3637 firmware version. 3637->36 (hex) = “6” 37 (hex) = “7” -> version 67.

Atmotube data format

02941e1c41 -> 0294 1e 1c 41

Bytes Example Description
2 0294 VOC data 0294 (hex) -> 660 (int) / 100 = 6.60 ppm
1 1e humidity 1e -> 30%
1 1c temperature 1c -> 28℃
1 41 atmotube information 41(hex) -> 01000001 (bytes) - ASDFGHJK see format below
Bits Values Description
A 0/1 0 - 3 seconds more, 1 - 30 seconds mode
S 0/1 0 - device is calibrating after power on or mode switch, 1 – device is ready
DF n/a reserved
G 0/1 0 - device is not charging, 1 - device is charging
HJK 0 to 4 battery charging level

Java code sample for Android

public static void getDataFromBytes(byte[] scanRecord) {
    String vocStr = MiscUtils.toHexString(new byte[]{scanRecord[25]}) + MiscUtils.toHexString(new byte[]{scanRecord[26]});
    int voc = Integer.parseInt(vocStr, 16);
    float vocF = (float) voc / 100;
    int hum = ((int) scanRecord[27] & 0xFF);
    int temp = scanRecord[28];
    int info = (int) scanRecord[29];
    boolean isSlowMode = (info & 0x80) == 0x80;
    int batteryLevel = info & 0x7; // atmotube returns 0 to 4
    char char1 = (char) (scanRecord[50] & 0xFF);
    char char2 = (char) (scanRecord[51] & 0xFF);
    String fwVer = new String(new char[]{char1, char2});
    boolean isCalibrating = !((info & 0x40) == 0x40);
    boolean isCharging = (info & 0x8) == 0x8;
}

Atmotube Bluetooth Service (firmware v.70.03.05 and up)

UUID Description
db450001-8e9a-4818-add7-6ed94a328ab2 Atmotube service UUID
db450002-8e9a-4818-add7-6ed94a328ab2 VOC characteristic
db450003-8e9a-4818-add7-6ed94a328ab2 Humidity characteristic
db450004-8e9a-4818-add7-6ed94a328ab2 Temperature characteristic
db450005-8e9a-4818-add7-6ed94a328ab2 Status characteristic

For data format - see Atmotube data format table.

History API

To sync history you should be able to use UART interface: 6E400001-B5A3-F393-E0A9-E50E24DCCA9E

  1. To start sync - send HST (History) command with Unix timestamp parameter. It is recommended to send this command after 3 seconds after connection.
UART command, ASCII, 3 bytes Unix time, 4 bytes
HST xxxx

The device will send HOK (History OK) reply

UART command, ASCII, 3 bytes 1 byte
HOK 0
  1. If device has unsynced history data - it will continiously send data back to mobile device - HT packet, HD packet(s), HT packet …

HT is a history header that comes before one or several HD (history data) packets

UART command, ASCII, 2 bytes 1 byte Unix time, 4 bytes - first measurement time in packet Number of measurements in packet, 1 byte Size of 1 measurement, 1 byte
HT 0 xxxx x x
UART command, ASCII, 2 bytes 1 byte Seq No. of the last measurement in this packet, 1 byte Measurement No.1 - Measurement No.N
HD 0 x xxxx - xxxx

Each measurement contains the following data

N size, bytes Description
0 1 temperature
1 1 humidity
2 2 VOC
  1. After receiving all HD packets mobile device shall send HOK confirmation with the current time. After that Atmotube will send next HT (if any).
UART command, ASCII, 3 bytes 1 byte Unix time, 4 bytes
HOK 0 xxxx

The Atmotube is a personal air pollution monitor designed to assist you in monitoring the air quality to which you are exposed. You and your medical professionals remain in charge of your health and medical decisions — the Atmotube merely provides information for your consideration.Users should be aware that the Atmotube has certain limitations, including: The Atmotube is not a medical device, nor is it a treatment for any health condition. The Atmotube is not a professional measuring tool; it provides estimates only. The Atmotube must be used according to specifications and the user guide; it is not appropriate for any uses which are not set forth in the specifications and user guide. Several other limitations apply. Click here to learn more.