There are two types of message in the Sigfox network:
- Uplink message: The device sends a message to the network. This is the most frequent type of messages, used for sensor data, event status, GPS fix or even application data. There can be up to 6 uplink messages per hour.
- Downlink message: The device receives a message from the network. This is less likely to happen, but can be useful, for instance to trigger an action or sensor, to manage the device, or to update a parameter. There are 4 guaranteed downlink messages per day.
First, let's review the steps that an uplink message has to follow, from the device to your platform.
- The device has something to report. To send its message, it broadcasts radio signals.
- These signals get to the nearby base stations listening to the Sigfox frequency.
- The base station retrieves the message from the signals and checks that it is valid.
- The base station uploads the message to the Sigfox Cloud, which authenticates the sending device.
- The Sigfox Cloud sends the message to the device maker's server.
- The customer platform displays the data.
As for a downlink message, there's a major difference: customers cannot contact a device directly. The device itself initiates the downlink message request.
- The device requests a downlink message when sending a regular uplink message with a "Downlink" flag, through radio signals.
- That message follows the expected path of an uplink message: base stations, Sigfox Cloud, customer platform.
- The customer platform can reply to the uplink message with a downlink message.
- The downlink message travels from the platform server to the Sigfox Cloud.
- The Sigfox Cloud uploads the downlink message to the base stations that received the downlink request.
- Those base stations start broadcasting the message through radio signals on the Sigfox frequency.
- The device listens to the radio network at a specific frequency, which it indicated in the uplink message. It receives the downlink message and its content through radio signals from nearby base stations.
- The device then reacts to the message. That reaction depends on the device's configuration.
See the following videos for a more graphical perspective:
The overview above can give the impression that the Sigfox Cloud and the device's platform are tied in such a way that messages are automatically sent from one to the other. That is not quite the case.
In reality, platform makers can retrieve the collected messages using any of these three ways:
- Through the web browser, using the Sigfox Backend interface. This is mostly for testing or debugging.
- Through the Sigfox REST API, by triggering calls that retrieve the device's messages.
- Through event callbacks, by creating loops to have the Sigfox Backend regularly send messages to the platform server.
See this video summary:
In short, if you want to:
- Manually view messages online: Browse the Sigfox Backend website.
- Automatically retrieve messages (pull method): Use the Sigfox REST API.
- Automatically receive new messages (push method): Create event callbacks on the Sigfox Backend website.
Let's explore each.
Through the Web Browser
All the Sigfox Cloud features are available through Sigfox Backend website.To view messages from a given device:
- Log into http://backend.sigfox.com.
- Click the "Device" tab at the top.
- Find the device you want to explore, by entering the ID that should be printed on its casing or by browsing the presented device types.
- Once the device is found, open it and click its "Messages" tab on the left.
- If Sigfox Cloud has messages from this device stored in the database, they will be displayed on this page.
Through the Sigfox REST API
The Sigfox REST API can perform all common tasks needed for service delivery. Scripts can access the API and its data in "pull" mode. It is the perfect way to integrate some of the Sigfox Cloud features in a third-party platform. For example, device registration within an external platform.
However, the REST API is not the best way to retrieve data from Sigfox Cloud. Implementing a pulling mechanism means that the platform would poll the Sigfox Cloud for new messages over and over. This would be costly for both servers.
You should therefore only use the REST API for specific needs: device group creation, device registration, callback creation, etc.
Read the REST API doc here: https://support.sigfox.com/apidocs
NOTE: API evolution
As of this writing (May 2019), there are two versions of the Sigfox API that you can use:
- API v1, or Legacy API: This is the original version of the API. It is deprecated as of October 2018, and will not work after October 31st, 2019. It is therefore not recommended for new platforms, and old platforms should switch to API v2 as soon as possible.
- API v2, or New API: This is the second generation of the API. Its Beta phase started in October 2018 in order to gather real feedback, and it is currently evolving in order to better fit the needs of the community.
Through event callbacks
Event callbacks are the recommended way to retrieve data from the Sigfox Cloud. It allows platforms to receive new events in push mode: the Sigfox Cloud sends them any new data uploaded by base stations. If there is nothing new, then nothing is sent.
Only event-based data is eligible to event callbacks: new messages from devices, newly activated device, etc.
Read the callback doc here: https://backend.sigfox.com/apidocs/callback (you need to first connect to the Backend site)
Once your server receives new data, it is up to your platform to display it to its users in a useful way. The most expected feature from a platform is a data dashboard showing graphs and trends. Also, data management and analysis allow for advanced data handling.
Depending on your product and budget, you could build your own platform, or rely on a third-party platform. Jyse is one such white-label platform. See the next section for the "Buy or Make?" arguments.
Here is a dashboard example with the Sensit.io platform:
As always in any project, available time and planned budget drive most of the decisions. The final quality and selling price of your product depend on them, and so does its success
Hence, you must consider whether to make your platform from scratch, or to buy/rent one from a third-party platform provider. Consider your options wisely, as a lot will depend on your choice.
Advantages of making your own platform:
- You manage your customers' data directly.
- You can tailor the displayed information to the device's sensors or to its target industry (waste management is not the same as pool monitoring).
- You can add features whenever needed, and update the platform without delay.
- When your products are successful, you have total control of your scalability.
Disadvantages of making your own platform:
- It takes a long time to specify, develop, and test a custom-made online tool.
- Securing code is hard and ongoing work.
- Bugs are yours to fix.
- Scaling for success (storage, bandwidth, etc.) can be a challenge in itself.
Side note: "Making your own platform" doesn't have to mean that you must code it from scratch. There are many services that you can rely on, depending on your needs and budget. For instance, Amazon AWS or Google Cloud Platform can help you get results faster -- at the cost of having your customers' data going through their servers.
Advantages of buying/renting from a third-party:
- Available right away, or with little customization.
- Cheaper than hiring developers to do it.
- Since the platform is generic, you can use it for other devices and markets.
- Supposedly tested and secure.
- Supposedly able to scale massively.
Disadvantages of buying/renting from a third-party:
- You don't directly manage your users' data (unless the platform is hosted on your servers).
- You depend on the platform provider for any feature addition, bug fix, or scalability issue.
- The platform can look more generic than a tailor-made one.
- You might pay for features that your users will never need.
- Once you choose a platform, it can be hard to move to another one (or to your own).
While we cannot tell you which way to go, we must insist that you ask yourself those questions.
Let's say you decide to go the Buy/Rent way. There are more choices to make!
Indeed, there are several types of platform that you might have to choose from, depending on your project:
- PaaS, or Platform as Service. These are mostly very generic, are customizable, and work with several types of connections. They fit into any project, so are perfect for a first platform. Example: https://thethings.io/.
- Vertical platforms. These are built for a specific market, so provide more business data relevant analytics. Example: https://www.cleverfarm.org/.
- Horizontal platforms. These are built with specific features in mind, for instance
For more, browse Sigfox Partner Network: https://partners.sigfox.com/companies/platform-provider
You'd rather go the Make way? Great! If you have in-house developers, then you're set: browse the Sigfox API or event callbacks documentation, and you're good to go!
If you don't have in-house developers, you can hire freelancers or consultancy services. You can find a list on Sigfox Partner Network: https://partners.sigfox.com/companies/consulting-company
Now that we've learned a lot on the way a Sigfox platform should work, let's review the life of a Sigfox message in more details, with new information in bold:
- The device "wakes up" at most 6 times per hour. During that awakening, its sensor(s) activate and retrieve information. Therefore...
- The device has something to report. It creates a message. Sigfox allows for messages with a 12-byte payload (at most), itself wrapped into a 26-byte data frame (at most).
- To send its message, the device broadcasts radio signals. To do so, it transfers a small amount of energy on a random frequency, with no protocol overhead. The device sends every frame three times and on three random frequencies: this is "frequency hopping". It is one of Sigfox's security feature: it protects radio frames from sniffing because it is impossible to know where the device is going to send in the operation band. It also enables broadcasting diversity and transmission resilience.
- These signals get to the base stations listening to the Sigfox frequency. Sigfox base stations listen to the whole radio spectrum, and interpret all UNB signals they receive on the legal frequencies. The signals from Sigfox devices are therefore detected on-the-fly.
- The base station retrieves the message from the signal and checks that it is valid. Base stations demodulate the received signals in order to assert that there is indeed a message within.
- The base station uploads the message to the Sigfox Cloud.
- The Sigfox Cloud receives the messages and authenticates the sending object. Once it has asserted the sender's ID, Sigfox Cloud knows the action to perform with the message.
- The Sigfox Cloud sends the message to the device maker's server. Event callbacks created on the Sigfox Backend create a "push" procedure, which makes that Sigfox Cloud only contacts the remote server when there is a message to transmit. That remote server can of course be an integration with a major Cloud solution: Amazon AWS, Microsoft Azure, theThings.io, etc.
- Finally, the data is displayed on the customer platform.