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
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.
Downlink is always applied to the current mode (or if the dowlink contains mode switch command, the mode switch is executed first and all values are applied to this new mode).
If mode is switched, the device loads factory default default and mode specific deltas and previous user specific downlink configuration is overwritten.
The device can be shipped in some cases in customer specific configuration.
If a mode is switched the default default factory values and mode specific deltas are applied.
Any customer specific configuration is lost.
Even after the return to original mode no customer specific settings are applied and must be applied by downlink.
By mode switch you always get factory “fresh” configuration.
Value that is not overwritten in mode change is RCZ-radio zone.
API, firmware versions and HW configuration can be read but cannot be overwritten.
REGISTER CONTENTS
The register can contain various information. Time, intervals, temperatures, MAC address, bit settings and device control commands.
Please study carefully what the register value contains.
In normal operation you shouldn't have to change lot of settings.
Some of the values are encoded in various formats.
For interval encoding we use simpleTIME - time intervals are encoded into 1 Byte using a system enabling us to define and use time intervals between 1 second and 64 days using just Byte see explanation here
simpleTEMP - temperature is reported with half °C precision using just 1 Byte see the explanation here
The same encoding is used in uplink messages to report the values.
STATE OF THE DEVICE
DISARMED-ARMING-ARMED-DISARMED
With the exception of PRESS ME mode all modes go through these stages.
It is similar to your home alarm system.
In the Disarmed state the device is not totally switched off. It reacts to button presses(leak detector in the case of simpleLeak and accelerometer in the case of simpeTemp)
Also a heartbeat can be sent if configured so.
Start of Arming can be triggered by
Short press (leak detector in the case of simpleLeak and accelerometer in the case of simpeTemp)
Sending a downlink message setting Bit7 ON in the register 0x40 (Device control)
Auto arm - setting a non zero value in register 0x10 (Auto-arm time)
Start of arming can be reported by message by setting the register 0x0F Bit 1 ON. Device can send start of arming event 0x10.
Arming is indicated by double blink and lasts for value in register 0x02.
In case of auto-arm and Force arm by downlink the arming is immediate.
End of arming/Start of Armed can be indicated by a blink pattern of A in Morse code .-
End of arming/start of Armed can be reported by message by setting the register 0x0F Bit 2 ON
Device can send End of Arming/start of Armed event
0x11 (human action Arming- short press or leak detection) or
0x12 (autoarm) or
0x17 (forced arm by downlink)
Armed
Normal mode operation starts
Disarming can be triggered
Long press - longer than 2 secs and shorter than 6 secs (upside down position for 10 secs in the case of simpleLeak) if allowed by setting the register to value
Sending a downlink message setting Bit6 ON in the register 0x40 (Device control)
Alerts (specific kinds of events) can trigger disarming - see Alerts section
Disarmed is indicated by a blink pattern of D in Morse code ==..
Disarm is immediate and can be reported in a message by setting the value of register Bit to ON
Device can send Disarmed event
0x13 (disarm by Alert)
0x14 (disarm by human action long press/upside down with simpleLeak)
0x18 (forced disarm by downlink)
ALERTS
Alerts are mode specific events, defined for each mode.
There can be up to 3 Alerts per mode.
With alerts you can define what happens when the device records an event that is critical to be reported (movement, temperature, water leak etc.)
For each Alert you can define many parameters such as number of immediate repetitions, number of total repetitions and spacing between them, whether to rigger downlink request or whether to disarm the device.
Registers are 0x23 till 0x2E Please read the detailed description in API 6 definition.
ONE FRAME/THREE FRAME SENDING
Traditionally Sigfox uses 3 frames/repetitions for sending any message in order to avoid interference and improve probability of delivery. You can decide to use only one frame when you have very good coverage. Advantage is twofold. You increase number of messages per battery capacity three times and instead of being legally limited to 6 messages per hour you can send 18 messages per hour.
HEARTBEATS
Heartbeat is mode independent event triggered by time. You can have two independent heartbeats and you can configure at each a lot of parameters.at registers 0x07 till 0x0C.
You can define:
period (from 1 second till 64 days),
whether to send heartbeat in constant periods or whether the time is counted only after any event in order to save the battery
Whether to send heartbeat all the time or only in armed mode
Whether to trigger downlink
Whether to request downlink with world time in order ty sync internal clock (to be utilized in the next FW revisione.g. to limit so mode measurements only to working days/hours)
One or three frames sending
Appended payload (see Appended payload for description)
APPENDED PAYLOAD
Sometimes you want to add some information (temperature, voltage, position etc) to the event independent of the mode. For events 0x02 till 0xTF you can define what kind of payload is appended.by setting the mask in register 0x0D.
Appended payloads for the Heartbeat1 and Heartbeat2 can have independent appended payloads using the same logic.
The format of the event for 0X00 till 0xTF is always
1st Byte Mode
2nd Byte Event
If you encounter 3rd Byte it is a mask and d according to this mask you can parse and decode actual Appended payload in 4th till 12th Bytes
For mask description please see API 6.
You cannot append payload to events 0x80 till 0xFF as those events have event payload definition already predefined and are event specific.
simpleTIME
In order to save bits and bytes we use for all time definitions (with the exemption of few registers using msec - time format is given in API6) a system of simpleTime enabling us to go from 1 sec to 63 days using just one byte.
The first two bits indicate what time unit is used (seconds, minutes, hours, days) and the remaining 6 bits is 63 values.
So you can have either up to 63 seconds or 63 minutes or 63 hours or 63 days period.
simpleTEMP
In order to save bits and bytes we use for all temperature encoding a system starting at -40°C, using half °C increments and going up to 87,5 °C.
For mapping please see API 6.
voltage BCD encoding
In order to save bits and bytes we use for all voltage encoding a system enabling us to report Voltage from 0 till 9,9 V using one Byte.
Bits 0 till bit 3 contain the decimal value of voltage, Bits 4 till 7 contain the whole number of voltage.
See detailed explanation in API 6.
API, Firmware and HW versions
You can read the API, FW and HW revisions either by pressing Extra long press or by requesting their values by downlink request 0xFE.
They are at registers 0xD0 til 0xD4. You cannot overwrite these registers.
We aim not change API6 in foreseeable future and to use it in all our future devices. API 6 is forward and backward compatible.
Major FW revision indicates feature set implemented. We will add more sensors, modes and logic into the next major FW revision. In this release e.g. local MAC zoning, world time sync, end to end encryption, real time RCZ switching and Monarch support are postponed for the next revision.
Minor FW fixes bugs or documentation inaccuracies or adds features not having major API definition impact
HW version enables you to read which sensors are on the device.
We currently dont send any error code if you try to use sensor that is not in your device. We ignore it.
Radio zone setting
In the future you will be able to change the radio zone of the device either by motion pattern, time lapse or Sigfox Monarch.
Currently you can only read the value.of register 0x47.
We do have two types of devices/PCB. One supports RC1/ RC3.
The other adds power amplifier and supports all RCs.
Power amplifier adds to the cost and has little bit worse performance in RC1 and RC3, therefore we have two versions. You can tell by reading the HW register.
RF Transceiver power
By lowering the value of the register 0x55 from default 0x72 to 0x30 you can lower the transmission power where you have excellent coverage. By lowering the transceiver power you can save battery.
Global switches
There are global switches at register 0x0E.
Please use them carefully in order not to brick the device.
Global LED light switch
Global Beeper switch
Global button switch
Please see API6 for details.
Sigfox coverage confirmation
In order to confirm that the device is operating in Sigfox covered location the device can indicate on its own whether the coverage is ok by requesting a downlink on arming and beeping/blinking nicely if the coverage is ok and beeping/blinking franatically if no downlink received.
Prerequisites are:
Proper bit settings at register 0x0F
Any payload ready for the device (no downlink is executed when no payload is prepared)
Downlink support in Sigfox tariff.
Informing customers they need to wait 40 secs after arming and distinguish proper blinking/beeping pattern.
Last updated