Introduction to Arduino MKRFox1200 – Part 1

Arduino MkrFox1200 sounds like Arduino for Maker using Sigfox. This board is an official Arduino product, looking like Arduino Nano series (but not pin-compatible, longer and larger)

It is composed of a SAM D21E MCU (Microchip ARM Cortex M0) operating at 48MHz. It includes 256K flash memory and 32K of SRAM. We can consider this as an Arduino under steroid.

The Sigfox radio layer is composed by an ATA8520. This is a Microchip Sigfox module based on AVR MCU. This module is communicating with the SAM D21E module with a SPI bus. The radio module is supporting RCZ1 zone (Europe).

This board can be found in many eShop places for a price around 45€ including an antenna and 2 year of Sigfox network access.

In this Post we will see how to get started with this board and how start programming with it.

Step 1 : configure the environment

The first step is to configure the development environment : You can use the Arduino Online editor platform (in this case you do not have to install anything on the desktop other than the plugin allowing to program your Arduino MKR1200).

I’ll detail the traditional way of working with the Arduino Desktop editor. You need to download the Arduino Software (IDE) if you do not already have it. Install it then run it. This tutorial has been made with version 1.8.5.

Once started, you need to install the drivers for the Arduino MKR1200 Sigfox board. For this go to Tools menu, then Boards and last Boards Manager. Like this screen capture (just for frenchy).

The next step is to select the right package: Select Arduino SAMD Boards (32-bits ARM Cortex-M0+) by Arduino. Select the last version ( actually we are on version 1.6.18). And click on Install button.

Now we need to install the Arduino MRK1200 Sigfox library to be able to communicate with the Sigfox module:

  • Download the Arduino RTCZero library
  • Go to Sketch >> Include Library >> Manage Library menu and select the downloaded zip file.
  • Download the Arduino Low-Power library
  • Go to Sketch >> Include Library >> Manage Library menu and select the downloaded zip file.
  • Download the Arduino Sigfox library
  • Go to Sketch >> Include Library >> Manage Library menu and select the downloaded zip file.

Step 2 : Connect the MKR1200 board and get information to register it

Once we have the development environnement ready we can make our first sketch to get the information requiers to register the board on Sigfox backend and access the communication service.

Connect the MKRFox1200 board to the USB port. Open Arduino Software IDE and create a new sketch.

  • In Tool >> Board menu select Arduino MKR Fox 1200.
  • In Tool >> Port menu select something like /dev/…. (Arduino MKRFox 1200)

Once done, you can Compile and Download an empty sketch (with the setup and loop function empty) and check it works.

Now to create a Sigfox account, we need to have two information:

  • The Sigfox ID is a uniq identifier own by each of Sigfox device. It is like a MAC address for a Sigfox Device. They are basically incremental and limited to 32 bits.
  • The device PAC key is a key associated with the Sigfox ID. This key is used to ensure you are the owner of the device when you register with the Sigfox ID. The PAK is a long Hex string randomly generated. Each time you register a device in the backend the PAC key is changed for a new one.

The Arduino MKR Fox 1200 Sigfox board is storing the ID and PAC into the Sigfox module memory so we need to create a short sketch to extract these information and create our Sigfox account.

#include <RTCZero.h>
#include <ArduinoLowPower.h>
#include <SigFox.h>
void setup() {
  Serial.begin(9600);
  while (!Serial);
  SigFox.begin();
  Serial.print("ID= ");
  Serial.println(SigFox.ID());
  Serial.print("PAC= ");
  Serial.println(SigFox.PAC());
}

You can compile/download this sketch to the board and click on the Serial Monitor to see the result. You should see something like (X are for ofuscation, you should have Hex number instead):

ID= 0018XXXX
PAC= 4C428E0D30CXXXXX

You are now ready to register the board on the Sigfox backend. For this follow these steps:

  • Go to Sigfox activation website
  • Select your country by searching it and clicking it. Then click on next button
  • Provide your ID and PAC number
  • Follow the procedure.

This will create a Sigfox Account attached to your email. Then you will receive an email invite to set your password in the Sigfox backend and you will able to connect and access your device.

Step 3 : Run your first Arduino program using Sigfox

Now, we are going to make our first Sigfox program with the MKR1200Fox board. This program will report the temperature every 10 minutes to the Sigfox backend. Why are we doing a 10 minute refresh ? It is due to the Duty Cycle on the 868Mhz band. To get more information you can read this post on European regulation on 868Mhz frequency band. Basically we are allowed to communicate 1% of during during 1 rolling hour. So with Sigfox technology it is corresponding to a transmission every 10 minutes.

The way to get the temperature is simple thanks to the Arduino SigFox library:

float t = SigFox.internalTemperature();

Transmitting a data over Sigfox network is also a simple thing ; most of the module use a Serial interface and AT command for doing this. Arduino MKRFox 1200 is working differently as the Microchip Sigfox module is not using a Serial communication but a SPI communication. Due to this the AT command are not relevant and the communication uses a lower level way.

Sigfox communication is pre-formated 1 to 12 bytes raw messages. we have to create an hex string corresponding to each of the byte we want to transmit. This is done the following way:

int8_t = (int8_t)SigFox.internalTemperature();
SigFox.beginPacket();
SigFox.write(t);
SigFox.endPacket(false);
SigFox.end();

This code is transmitting the temperature in a 1 byte Sigfox frame (over the air the frame contains 4 byte long data field). You can consult my post about Sigfox radio protocol for details.

As you can see the data transmitted is not really readable in your code so we can improve this by using a structure:

typedef struct __attribute__ ((packed)) sigfox_message {
    int8_t temp;
} SigfoxMessage;

loop() {
   SigfoxMessage msg;
   SigFox.begin();

   msg.temp = (int8_t)SigFox.internalTemperature();

   SigFox.beginPacket();
   SigFox.write((uint8_t*)&msg,sizeof(msg));
   SigFox.endPacket(false);
   SigFox.end();
}

Now let’s take a look to the whole exemple. You may note that I switch the Arduino Sigfox library in debug mode. This is basically needed because of a bug in non debugging mode. For real in non debugging mode the SAMD chip is switched to sleep mode waiting for Sigfox communication to terminate. But it never come back from this state. Sound like a bug in the Arduino LowPower library once your have made an USB sketch upload it seems the LowPower.sleep() function never come back. The “solution” to use LowPower is to power off/power on the board after programming.

#include <RTCZero.h>
#include <ArduinoLowPower.h>
#include <SigFox.h>
#define LED 6         // This is the built_in led
void setup() {
   pinMode(LED,OUTPUT);
   digitalWrite(LED,LOW);
   Serial.begin(9600);
   while (!Serial);
   if ( ! SigFox.begin() ) {
     Serial.println("Error ... rebooting");
     NVIC_SystemReset();
     while(1);
   }
   SigFox.reset();
   delay(100);
   SigFox.debug();
   SigFox.end();

   // We need to have to time to program the Arduino after a reset
   // Otherwise it does not respond when in low-power mode
   Serial.println("Booting...");
   digitalWrite(LED,HIGH);
   delay(5000);
   digitalWrite(LED,LOW);
}

typedef struct __attribute__ ((packed)) sigfox_message {
int8_t temp;
} SigfoxMessage;

void loop() {
   // put your main code here, to run repeatedly:
   SigFox.begin();

   SigFox.status();
   SigfoxMessage msg;
   msg.temp = (int8_t)SigFox.internalTemperature();

   SigFox.beginPacket();
   SigFox.write((uint8_t*)&msg,sizeof(msg));
   SigFox.endPacket(false);
   SigFox.end();

   // Wait for 10 minutes.
   // Low Power version - be carefull of bug
   //   LowPower.sleep(10*60*1000);
   // Normal version
   delay(10*60*1000);
}

Watch the result in the Sigfox backend

Now we have data regularly sent to Sigfox network. The data are running over the air to the basestation (antennas) around you. The base station analyses the radio signal and decode your message. This message is then pushed to the Sigfox Backend where you can see it.

You can click on this link to access the Sigfox Backend.

In the Device list you can see your device like this:

Your can click on the device Id and go to the device details. You have in the left menu a Message choice where you can click to see the message details and watch what you sent over the network.

Here you see the temperature in hexadecimal 13 means 1*16+3 = 19°C

Display information for being human readable

The backend can be customized to show human readable information : by configuration we can request backend to transform this 0x13 into something like temperature : 19.

This is a setting made at the Device Type. A Device Type is a group of devices corresponding to the same service or application. So they are all sending the same type of information with the same frame format. So instead of configuring each device the same way we are configuring a Device Type and associate all these devices to the same device type.

So to access this configuration, you need to click on the Device Type header entry and select the device type corresponding to your device. Then click on Information then on the right side of the page, click on edit button.

Once done you can see the following part Payload display:

Select Custom grammar, now you can define your own data frame formatting. Basically, in our case we only have 1 field temperature, it starts on byte 0, it is a signed integer value of 8 bits. The corresponding definition is:

Temperature:0:int:8

Once saved we can take a look to the Device Messages and check the result:

The temperature is displayed in decimal under the raw data.

Experiment bi-directional communication

Sigfox is a bi-directional network. You can have up to 4 downlink per day from the network. This is the minimum you can expect from network but basically you can request much more. If the basestation did not run out of its duty-cycle it will answer to your downlink request.

We are going to start a default downlink response in the Sigfox backend. This is a setting of the Device Type. (Device-Type is a configuration applied to a group of devices).

For this, you need to click on the Device Type header entry and select the device type corresponding to your device. Then click on Information then on the right side of the page, click on edit button.

Now we can edit the downlink, setting DIRECT mode (the value is calculated by the Sigfox backend). Here we have chosen to return the timestamp (4 bytes) followed by 4 bytes at 0 to have the 8 byte expected message.

We now have to modify the Arduino code to add the downlink taken into account:

For this we just need to add the endPacket parameter set with true. Like the following

...
SigFox.write((uint8_t*)&msg,sizeof(msg));
int ret = SigFox.endPacket(true);
SigFox.end();
...

That way the Sigfox library will send the message, then wait for a downlink response.

To capture this response at the sketch level, we will have to add some extra lines of code the part in RED is added/changed to the previous code:

SigFox.beginPacket();
SigFox.write((uint8_t*)&msg,sizeof(msg));
int ret = SigFox.endPacket(true);

if (SigFox.parsePacket()) {
   Serial.println("Response from sigfox backend:");
   while (SigFox.available()) {
      Serial.print("0x");
      Serial.println(SigFox.read(), HEX);
   }
} else {
   Serial.println("No response from Sigfox backend");
}

SigFox.end();

Once you upload the sketch, you will see led blinking a longer time during the transmission : after the 5-7 seconds of data transmission, the led will continue to blink until the Sigfox network has sent a downlink response. This can take up to 30 seconds.

Normally in the console you should see information like the following:

Booting...
Temperature :19
Response from sigfox backend:
0x5B
0x1D
0x7E
0xEA
0x0
0x0
0x0
0x0

We can also look at the Messages in the Sigfox backend and see the downlink transmission status:

By clicking on the green Callback arrow the Downlink status is displayed with the Data send to the device.

Next step

In the coming part 2 of this tutorial we will see how to manage a callback to send the data outside of Sigfox server and graph the temperature.

 

This entry was posted in IoT, sigfox and tagged , . Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.