THINaer is an IoT based company that offers an API that provides proximity and environmental information based on deployed “iris” (AKA Beacons) and it’s “Cirrus” (an IoT Gateway). The iris devices are movable or static based on use case and the Cirrus is always static in a fixed location. iris transmits it’s signal at a set interval along with any other sensor data the iris may have, this can include; internal chip temperature on the “ii12”, external temperature and relative humidity on the “ii18e”, and finaly movement detection using an accelerometer on the “ii18a”.

iris from THINaer

The Hardware Technologie

THINaer is using the latest in BLE 4.1 technologie to transmit its packet over a custom protocol. This protocol can be picked up by any BLE device that can read device packets, tho because this is a custom proprietary protocol designed by the team and myself some development work will need to be done to decode the packets.

THINaer Protocol Breakdown

Each [ ] represents each byte in the packet and its position.

ii12
  • [0] 0x00 (Device Model)
  • [1] 0x5d (Internal Temp Channel)
  • [2] 0x00 (Internal Temp Value 1)
  • [3] 0xfa (Internal Temp Value 2)

Internal temp is represented as a 16-bit unsigned number in fixed point format. In the example above 0x00fa is 250 in decimal which represents 25.0C. To calculate temp you will first need to convert the hex to decimal then use: decimalValue * 0.1.

ii18e
  • [0] 0x01 (Device Model)
  • [1] 0x44 (Temp Channel)
  • [2] 0x68 (Temp Value 1)
  • [3] 0xac (Temp Value 2)
  • [4] 0x45 (RH Channel)
  • [5] 0x49 (RH Value 1)
  • [6] 0xba (RH Value 2)

The ii18e has a more sensitive temperature chip on board and provides a much more accurate reading. And is still represented in two bites but the calculation changes. (175.72 * decimalValue) / 65536 - 46.85

ii18a
  • [0] 0x02 (Device Model)
  • [1] 0x5d (Internal Temp Channel)
  • [2] 0x00 (Internal Temp Value 1)
  • [3] 0xfa (Internal Temp Value 2)
  • [4] 0x09 (Motion Channel)
  • [5] 0x00 (Motion Value)

The ii18a also have an internal temperature output but its primary focus is motion. Motion can be detected by watching the motion channel, anything greater than 0x00 is movement.

The REST API

In just a few days the company will be releasing a new version of the API (v2), so everything that follows will talk about using the latest version. The THINaer API provides near-real time access to proximity and environmental information. It also provides historical movement information, this is used for asset tracking use cases, we will talk more about that later. The API also provides a two way look, meaning I can see what a Cirrus can see or I can look from the perspective of an iris.

Something special with this API is that it allows a developer to organize it’s devices based on “clients” and “venues”. This comes into play when you are building a multi tenant application using the API. You can then have many “clients” that belong to your application and assign devices to the client as you see fit, providing some separation for your customers. Within the “client” you can then further organize to “venues”, this often relates to physical locations but are really just groups and can be used anyway you see fit.

Getting started - Authentication

Before you can make any requests to get data, you need to authenticate with the API. Below is an example using CURL.

curl --request POST \
  --url /api/v2/application/token \
  --header 'content-type: application/json' \
  --header 'secret: cf2aca10-9355-11e6-8b95-7932558ded9d' \
  --header 'uid: 7345ccf0-fa43-4ad2-a5c0-d26a172c2acd'

The UID and Secret are provided by THINaer at first setup. This token request will return just that, a token that should be saved and will expire in 24 hours.

Let’s get the iris and Cirrus devices assigned to your account!

Now that you have authenticated lets looks the the devices assigned to your account. Using the token you just received we will request all devices by type. See below:

iris Devices by application

curl --request GET \
  --url /api/v2/application/iris \
  --header 'content-type: application/json' \
  --header 'token: 876tyui3ol387ui3o93ikejui893eoieku19oke0'

Cirrus Devices by application

curl --request GET \
  --url /api/v2/application/cirrus \
  --header 'content-type: application/json' \
  --header 'token: 876tyui3ol387ui3o93ikejui893eoieku19oke0'

The two objects returned will display all devices assigned to your account, you can save that data locally or make this request as often as you like. When you buy new devices they will always show under your account and this request will update the moment they are added.

Going forward

If you come back, I will cover some simple use cases and how to get the data out of THINaer! Now that you have a basic understanding of how to authenticate and make your first request using the new version 2 THINaer API going forward the requests will be much of the same style just with select ID’s sent in as headers or GET params.