Getting Started with SigFox and PlatformIO

At ThingForward we're highly interested in IoT architectures and how to connect "the last mile", that is how to transport data from small devices to gateways and backends. They are a great many options to do so, mainly due to the availability of numerous RF technologies around. One way to send data over long distances is choosing one of the LPWAN (Low-power wide area networks) protocols/technologies around. In one of our lasts pasts we looked into the details of LoRaWAN and TheThingsNetwork. This post is going to be about SigFox, another player within the LPWAN game. So what exactly is SigFox?

SigFox

SIGFOX is a french company and the builder and operator of a wireless, cellular LPWAN for the Internet of Things. It can be used to connect small low-power devices to it and have these devices transfer sensor data to a backend. It utilizes radio frequencies within the ISM radio band, which is 868MHz in Europe and 902MHz in the United States. The data that a device can transfer is very limited, at least compared to other protocols that we're used to work with every day. A SigFox device may sent up to 140 uplink messages (meaning from device to backend) per day, which is about one message every 10 minutes. Furthermore, a message may contain up to 12 Bytes. Yes, that is not really much, but enough for a large number of IoT sensor use cases, where you'd measure things from the environment (i.e. like soil moisture for agricultural use cases) and transport this a small values to your backend application.

Compared to these uplink messages, a device may (upon request) receive a downlink message from the network. This may happen up to four times a day. You can image that this is not suitable for any TCP/IP related protocol families, but for simple devices with limited, essential functionalities this can be sufficient. We'd really encourage you to walk through this tutorial and try it out, BUT before you do please pay a visit to SigFox' coverage map and make sure that the area where you live or work does actually have coverage regarding the SigFox network! For the western part of Germany coverage is good, so we decided to give it a try, at best with hardware and a software toolchain we're already familiar with. So let's get started!

Hardware & Software

Luckily, SIGFOX' website has a partner section, where you can easily browse through a catalog of module and component vendors. Head to https://partners.sigfox.com/, select "Products" from the top-right menu, then "Dev Kits":

SigFox Partner DevKits Menu

This catalog is well-loaded with components, and there's an Arduino-Shield. But Arduino is offering a complete solution from themselves, the Arduino MKRFOX1200. This is a combination of an ARM Cortex M0+ and a SigFox transceiver module. It's cheaper than the Shield from the partner sections and offers a two-year plan instead of a 1-year plan for the shield.

Arduino MKRFOX1200 Arduino MKRFOX1200

The board comes with an 868MHz antenna which is necessary (unless you live next to a SIGFOX network mast :-) The MKRFOX1200 can be programmed with Arduino's IDE, but as we are fans of PlatformIO's capabilities, we gave it a try, and:

$ platformio boards mkrfox1200
Platform: atmelsam
----------------------------------------------------------------------------------------
ID MCU Frequency Flash RAM Name
----------------------------------------------------------------------------------------
mkrfox1200 SAMD21G18A 48Mhz 256kB 32kB Arduino MKRFox1200

Great, let's roll!

Setting up the project

Head to a new directory, run pio init. Or, if you have the IDE, open the PlatformIO Home Tab and create a project there.

$ mkdir pio-sigfox-demo
$ cd pio-sigfox-demo/
$ pio init -b mkrfox1200

Luckily, Arduino has a library at hand which makes the SigFox functionality accessible within the sketch, and PlatformIO included this library in their registry:

$ pio lib search mkrfox1200
Found 1 libraries:
Arduino SigFox for MKRFox1200
=============================
#ID: 1432
Helper library for MKRFox1200 board and ATAB8520E Sigfox module
Keywords: device, control
Compatible frameworks: Arduino
Compatible platforms: Atmel SAM
Authors: Arduino, Arduino LLC

We're going to install this one. This library requires additional libraries, the ArduinoLowPower and RTCZero. You'd find out when compiling and looking at the missing dependencies, but we already did and you can directly install all libs at once:

$ pio lib install 873 1577 1432
Library Storage: pio-sigfox-demo/.piolibdeps
LibraryManager: Installing id=873
Downloading [####################################] 100%
Unpacking [####################################] 100%
RTCZero @ 1.5.1 has been successfully installed!
LibraryManager: Installing id=1577
Downloading [####################################] 100%
Unpacking [####################################] 100%
Arduino Low Power @ 1.2.0 has been successfully installed!
LibraryManager: Installing id=1432
Downloading [####################################] 100%
Unpacking [####################################] 100%
Arduino SigFox for MKRFox1200 @ 1.0.2 has been successfully installed!

Ok, time to write the code. Each SigFox module has an ID, and an Authorization Code called "PAC". We need to find out these values first. Place a main.cpp in src/ with the following content:

#include <Arduino.h>
#include <ArduinoLowPower.h>
#include <SigFox.h>

void setup() {
  Serial.begin(9600);
  while(!Serial) {};

  if (!SigFox.begin()) {
    Serial.println("Shield error or not present!");
    return;
  }

  SigFox.debug();

  String version = SigFox.SigVersion();
  String ID = SigFox.ID();
  String PAC = SigFox.PAC();

  // Display module informations
  Serial.println("SigFox FW version " + version);
  Serial.println("ID = " + ID);
  Serial.println("PAC = " + PAC);
}

void loop() {
}

Connect MKRFOX1200 via USB, then:

$ pio run -t upload
(...)
Verify 28656 bytes of flash with checksum.
Verify successful
done in 0.024 seconds
CPU reset.
$ pio device monitor
--- Miniterm on /dev/cu.usbmodem1411 9600,8,N,1 ---
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
SigFox FW version 2.3
ID = <YOUR_ID>
PAC = <YOUR_PAC>

The serial monitor will display your ID and PAC.

Register your device

With the information above, you need to first register yourself at SigFox' Portal, then register your device. Here's how. Head to https://backend.sigfox.com/activate.

First you're asked to choose a kit provider from a logo-ish list of many providers. As the list of sorted, Ardunio ist the top-left-most one :-) Next: Pick your country/network operator, the enter your account details. You'd need to register with a valid email address. If you already registered at the SigFox portal, you can reuse that login. After successful registration you're asked to enter the ID/PAC combination from above. With this step, you're essentially claiming your device, so you're the only one who is able to view messages from the device.

After device registration you can look at the device meta data under the "Information" panel.

SigFox Dashboard Device Registration

Send data

Now it's time to send some data! Let's extend the main.cpp from above. As we did not attach any sensor or the like, we just send our own ID prefixed with some string. We do this within setup(), so that it is executed just one time. For a more realistic use case one would have to ensure that the device only wakes up every 10 minutes to send data. You may want to look at the ArduinoLowPower Library, or you implement it with a simple delay/sleep mechanism. Here we go with our simple main.cpp:

(...)
void setup() {
(...)
  Serial.println("ID = " + ID);
  Serial.println("PAC = " + PAC);
  // this is new:
  Serial.println("waiting to send...");
  delay(5000);
  Serial.println("sending...");
  String to_be_sent = "PIO-" + SigFox.ID();
  SigFox.beginPacket();
  SigFox.print(to_be_sent);
  int ret = SigFox.endPacket();
  // shut down module
  SigFox.end();
  Serial.print("ret="); Serial.println(ret);
}
void loop() {
  Serial.println("stopped.");
  while (1);
}

Let's try it out. And don't forget to connect your Antenna first :-)

$ pio run -t upload
$ pio device monitor
SigFox FW version 2.3
(...)
waiting to send...
sending...
ret=0

Ok, a return value of 0 looks not so bad, let's verify this on the:

SIGFOX Backend Dashboard

Point your browser to the SigFox Backend Dashboard, more specifically to the Device List. You should see your device message there!

SigFox Dashboard Device Overview SigFox Dashboard Device Info

Clicking on the device id you can look at all messages of the device, it's current state and statistics. Interesting as well: Click on Location on the left menu tab, you should see a map with a coverage overlay, roughly marked with where you're located at. At first i wasn't sure about the different meaning of light and dark blue areas and pixels, but @nlesconnec from SigFox helped out: Dark blue pixels show the overlap of receiving stations coverage, whereas light blue is API data.

That's it! We successfully connected our device to the SIGFOX network! But there's so much we did not cover yet:

  • We're able to configure device types with predefined settings, and attach devices to a type
  • We could request download messages, from the network to our device
  • We may define Events, where the network forwards incoming device message to a URL, or as an email.
  • And we'd be able to have a geolocation forwarded to us.

So there's still a lot to do, which we'll surely look at in one of the upcoming posts, so stay tuned :)

@aschmidt75