Note: From June 1, 2019, Sigfox backend will no longer send certain variables like snr, station, rssi and others. To avoid disruption in your service, you must update the callback function as shown in this document.

Sigfox is a relatively new low-cost wireless network technology that requires low power to connect, and that is implemented by lost cost hardware modules. Although they are limited in terms of the size of messages (12 bytes maximum) and the frequency that the devices can send out data (140 times a day), several new applications can be achieved with Sigfox. More information about how Sigfox works can be found here.

TagoIO is ready to receive from and send data to Sigfox devices. There are three types of interface methods used between Tago and Sigfox services. Uplink is the process to send data from the modules to Tago. The Downlink is used to send data back to the module every time it checks in – the data to be sent down should be ready prior to the check-in. And the last method is the Error, that informs when there is a communication loss for any Sigfox module.

Adding your own Sigfox module to TagoIO is very easily accomplished; just follow the steps described below to setup the configurations at the Sigfox Backend and at TagoIO.

Uplink

You need to prepare the uplink in order to send data from your Sigfox module to Tago. The uplink configuration will be separated into two parts: TagoIO configuration, and Sigfox configuration using the Sigfox Backend Portal.

1. TagoIO setup

In your account, you will need to create a Device and a Device-Token to receive data from the Sigfox portal. By selecting the device type: Sigfox and entering the information below, the device-token will be automatically created.

Sign into your account at TagoIO, and then follow these steps:

1. Click on the Device button;
2. Click on the "Add Device" button;
3. Look for "Sigfox" and select it;
4a. In the field "Device Name", add any name to your device;
4b. In the field "Sigfox Device ID", add your Sigfox Device ID;
4c. [Optional] In the Verification-code field, enter any secret text. What you type here should be the same as what you will enter in the Sigfox callback header field.
5. Click on the Create Device button.

The Verification Code field is not required, but it adds security to your integration. If you add text here, you will need to use the same text in the Verification code field inside your Sigfox callback function.

2. Sigfox Setup

On the Sigfox Backend Portal, you will need to create a callback type uplink.

Sign into your Sigfox account, and then follow these steps

1. Click on the Device Type;
2. After clicking the Device type, the list of your devices will appear, choose one;
3. Click on the Callback button;
4. Click the New button;
5. Select the option Custom callback;
6. Configure the uplink with the instructions below.


Callback Setup - Data Uplink

If your contract doesn't allow you to send information like RSSI, SNR, STATION, you may prefer to use the common uplink for Sigfox.

How to Setup:
- Type:  DATA & UPLINK
- Channel: URL
- URL: https://sigfox.middleware.tago.io/uplink
- Use HTTP Method: POST
- Send SNI: Check the box "Send SNI".
- Headers: Add two rows in the Headers section inside the header and value fields:

 header value
 device  {device}Required. Enter text exactly as shown.
 verification-codeyour_secret_code_here

[Optional] Use the same text input during the device creation at TagoIO.

- Content-type: application/json
- Body: Copy and paste the JSON text below into the body field. This JSON will take care of the parse to prepare the data coming from your Sigfox module to TagoIO.

[{
    "variable": "device",
    "value": "{device}",
    "serie": "{time}"
},{
    "variable": "data",
    "value": "{data}",
    "serie": "{time}"
},{
    "variable": "seqNumber",
    "value": "{seqNumber}",
    "serie": "{time}"
}]

You can use the option Data service for Uplink. For example, if you want to use advanced_data service, you just need to maintain the TagoIO JSON structure.


Callback Setup - Advanced Data

Advanced data allows you to get additional information like SNR, RSSI, STATION, and others. 

NOTE: Some information may NOT be available - it depends on your contract with Sigfox.


- Type:  SERVICE & ADVANCED_DATA
- Channel: URL
- URL: https://sigfox.middleware.tago.io/uplink
- Use HTTP Method: POST
- Send SNI: Check the box "Send SNI".
- Headers: Add two rows in the Headers section inside the header and value fields:

 header value
 device  {device}Required. Enter text exactly as shown.
 verification-codeyour_secret_code_here

[Optional] Use the same text input during the device creation at TagoIO.

- Content-type: application/json
- Body: Copy and paste the JSON text below into the body field. This JSON will take care of the parse to prepare the data coming from your Sigfox module to TagoIO.

[  
  {  
    "variable":"device",
    "value":"{device}",
    "serie":"{time}"
  },
  {  
    "variable":"duplicates",
    "value":"{duplicates}",
    "serie":"{time}"
  },
  {  
    "variable":"data",
    "value":"{data}",
    "serie":"{time}"
  },
  {  
    "variable":"seqNumber",
    "value":"{seqNumber}",
    "serie":"{time}"
  },
  {  
    "variable":"location",
   "location":"{computedLocation}",
    "serie":"{time}" 
  }
]

Your uplink integration is now complete!

Information about Downlink setup can be found here.

You can create parse scripts for your device that extracts variables from the payload. The complete payload parser documentation is here.