API 6 Overview For Experts¶
API 6 is a revolutionary firmware concept that enables incredible flexibility and ease of use. Its versatility allows us to use the API 6 in almost all our newer devices (except the new CheckFox 2.0). Every new revision is compatible with older ones, which means that if something was implemented in an older version, the new version will have it implemented as well (except for bugs of course).
The API 6 is built around modes (device applications), which are defined by mode-specific events (sent uplink messages) and can be fine-tuned through downlink registers (configuration settings).
This article is an in-depth description of the firmware with a lot of links to other relevant pages, but if you’re looking for a basic introduction, please read this article first.
Please note we are using hexadecimal values for all numbers in the API 6. When parsing uplink payload or creating a downlink one, always leave out the 0x prefix when you work with API 6 data.
User modes are applications that control how different sensors inputs are measured, evaluated, encoded and reported. Every user mode could be considered to be a different device that will report different data - this is why the API 6 is revolutionary. As of now, we have 50+ user modes available and we are adding more in order to fit as many use cases as possible.
Every parameter in every mode can be further fine-tuned by values in downlink registers (think sensor sensitivity, adjusting time periods of e.g. regular heartbeat messages et cetera). All downlink register have a certain factory default value, but some modes have values different from register default values in their default settings - these we call mode deltas.
We currently support four types of user modes - Standard, WiFi, WiFi Atlas and WiFi Precise. Every user mode type has its benefits and possible use case scenarios - user mode is chosen after you know what you want reported and how.
Modes can be changed by downlink. If you’re an integrator, your end-users should never switch between modes. If the user modes is reported in an uplink message, it’s always the first byte of the payload.
Events (and uplink messages in general)¶
Almost all messages you can receive from your device are called events. Events are numbered and the respective numbers are always predefined - which means you can always decode the received data. Event is always the second byte of the payload (in the standard uplink message format - see below).
There are many ways to categorize events - based on the trigger (sensor-triggered, time-triggered etc), based on the event number (events 0x00-0x7F can be sent with appended payload, others cannot) and more.
Uplink messages can have three formats:
Standard (first byte is always mode, second byte is always event, the rest of the payload is optional but is always either appended payload mask followed by appended payload or other data if event >0x7F - MAC addresses, vibration data, accelerometer data and more)
WiFi payload (one single uplink message containing 2 MAC addresses in 12 bytes total, no mode or event bytes are sent)
Empty payload (only in Stupid mode 2, nothing but Sigfox metadata is sent to save the battery)
Downlink registers (configuration settings)¶
The device contains 255 one-byte registers. The register always contains a pointer (address) and a value. Currently 100+ registers are used and you can find description of all the registers here.
You can overwrite (change) the value of any register by sending a downlink message to the device. The downlink payload needs to contain the pointer and the desired value. One single downlink payload is limited to 8 bytes, which means up to 4 downlink registers can be changed in one downlink.
You can find everything about downlink in one pleace in the Downlink Information article.
You can read the value of any of the register by sendling a downlink containing the hex 0xFE and 5 pointers of the registers whose values you want to read. The device will then send you a message where the first byte will be the mode, the second will be the event 0xFE followed by a register pointer byte and then the value byte of the respective register - up to 5 register pointers and values can be sent in one uplink.
Downlink register are preconfigured with so called register default values. You can find these and much more info in the Downlink registers article. Register default values are valid for all modes, but some modes have different values in default and these are called deltas (we already mentioned this above).
You can find the deltas in the in-depth description of every mode.