API


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