API 6 Overview For Beginners¶
API 6 is our current universal firmware that controls the SimplePack, SimplePack Plus and SimpleLeak devices. The API is programmed in a way that makes it easy to use for integrators who do not want to spend too much time configuring the devices and at the same time offers an endless amount of possibilities and behavior customization so even the most complex use cases can be covered.
If you’d like to become an expert integrator, expect a little learning curve.
Before integrating API 6 devices¶
Back to the basics, if you’re thinking about implementing our devices, into your processes, it’s necessary to understand the following principles before anything else:
Our primary aim is the B2B2C model (and the API reflects this) Simple Hardware devices are intended to be used for data collection by integrators in their projects and are sold this way. It’s important to know what advantage you will gain by using our devices before attempting to actually use them. The devices can be shipped to you with individual settings or you can fine-tune them via downlink if necessary. The API is written to cover as many use cases as possible as efficiently as possible with a heavy emphasis on the cost-benefit ratio.
Sigfox training by your local Sigfox operator is a must for mass deployment. This should cover both Sigfox as a technology in general and Sigfox backend in-depth (you should be familiar with groups, device types, callbacks and connectivity tokens at the very least).
IoT platforms that support the API 6 can be used for general testing purposes instead of the Sigfox backend if you just want to try the devices out. We heartily recommend the IOFrog.com platform as it’s easy to use, the complex API 6 is well explained there and we’re closely working with the dev team.
API 6 basic overview¶
This is just a very basic overview of what the firmware architecture looks like and what it can or cannot do. If you’d like a more in-depth guide to the API 6 or any of its parts, check out API 6 Overview For Experts.
Data can be sent either from the device to the Sigfox backend or vice versa. Uplink is data sent from the device to the Sigfox backend. Uplink payload is limited to 12 bytes. Downlink is data sent from the backend to the device. Downlink payload is limited to 8 bytes.
The main feature of API 6 are the multiple different operating modes. Every operating mode is an application that has a predefined set of behaviors that can be adjusted to better fit your use case. Think of a mode as of a completely unique and different device (but of course, some modes share similarities). Each mode uses some of the predefined events - uplink messages (event hex symbol always means the same in every mode). Device behavior is controlled by downlink register values - the first and most important downlink register is the operating mode. Everything else is there just for fine-tuning the behavior of the device.
End users should never change operating modes - only integrators should configure the devices!
Arming and disarming¶
The devices go through a cycle of different device states. They allow you to arm (activate) the device when you need it to monitor its environment and gather data and disarm (deactivate) them when they are not needed to save the battery. Check out the API 6 Basic Operations With SimpleHw Devices guide!
Uplink payload parsing¶
API 6 has a predefined way of reporting data. There are exceptions of course (covered in the expert guide), but generally, the first two bytes of the payload are always the operating mode and an event. There are two ways to parse the remaining ten bytes - if the hex symbol of the event is from 0x00 to 0x7F, the additional data is appended payload (various data can be appended regardless of event). Events from 0x80 and up will mostly be sent with MAC addresses or mode-specific data that is unique to the received event.
In order to save space and battery life, some complex data is encoded into one or more bytes - you can find a list of encoding used in the API 6 here so you know what’s what.
Downlink register settings¶
Downlink registers are set up via downlink. The payload has to always include a register pointer and its respective value to change one setting - this means 4 register values can be changed with one downlink. Register pointers are predefined and the first one is the operating mode - in order to change it, the first byte has to be 0x01 and the following one has to be the hex symbol of the mode you’d like to use.
In default settings, downlink is triggered by an extra long press of the button (6+seconds) for both SimplePack versions and by arming (activating) the device for the SimpleLeak.