Contents


Overview

Skill Level: Any Skill Level

Medium : JavaScript, HTTPs, NodeRed, binary numbers

IoT devices can be connected to the Sigfox network and take benefit from long-range broadcast capabilities. This recipe explains how to connect a single Sigfox device to IBM Watson IoT Platform.

Ingredients

A physical device registered and connected to the Sigfox backend is required. Access to Sigfox backend is used to setup the link towards IBM.

Step-by-step

  1. Introduction

    IoT devices can be connected to the Sigfox network and take benefit from long-range broadcast capabilities. This recipe explains how to use Sigfox devices from IBM Watson IoT to perform Analytics for example or connect them with many API exposed by IBM Bluemix. This can be achieved by connecting the Sigfox backend to IBM Watson IoT Cloud and align a common view for a device.

    This tutorial explains how to:

    • create and setup an IoT device into IBM Watson IoT : this makes a device available into IBM IoT world,
    • create an IoT flow : this is where the logic is, to handle device activities into IBM IoT side,
    • configure Sigfox backend to IBM Watson IoT : this makes a link between the Sigfox Backend and IBM IoT Cloud,
    • complete an IoT Flow : this section explains how to read the content of Sigfox messages.

     

    The starting step of this recipe supposes that your Sigfox device is already registered and connected to the Sigfox network. Pushing a message from your Sigfox device is vendor-dependent and therefore is not documented here. The scope focuses on all additional steps required to extend your Sigfox experience to IBM IoT capabilities.

  2. Create a Watson IoT device

    This section describes how to create an IoT device into Watson IoT and generates associated API keys for future access.

    • If you do not have yet an Organization created for “Internet Of Things”, you first have to connect to Bluemix and reach the “Internet of Things” services section in the Catalog : https://bluemix.net
      • Select “Internet of Things Platform” and then select¬†the Free pricing plan if it is appropriate for your usage, populate the name and credential fields; press Create.

    0-create-an-Orga
    Create IoT Service

    set service name

     

    • If you have just created your “IoT” service with the previous step, you should be automatically connected to IBM Watson IoT Platform when selecting “Launch the dashboard”. If you already had one, please connect now to Watson IoT https://internetofthings.ibmcloud.com.

    Launch IoT Dashboard

    • Select your Organisation

    1-organization

    • Open the “Devices” section

    • Press “+Add Device” button

    • Create a “Device Type” (if needed)
      • Create device type
        • Name : SigfoxDevice
        • Description : A Sigfox Device
      • Press Next and optionally select attributes (Serial number, Manufacturer, … ). If not needed, leave empty.
      • Press Next
      • Press Next to submit information
      • Declare optional metadata. If not needed, leave empty.
      • Press Create

    Create a device type

    Create a device type

    Create a device type

     

    • The “SigfoxDevice” type should be available into the selectable list

    Create a device type

    • Select “SigfoxDevice” type and DO NOT press “Create device type” but press Next at theh bottom right of the page
    • Populate your “DeviceID” with the Sigfox ID for example as a unique Identifier (aka MAC address). As a naming convention, I prefixe with “SFX_” but you can write whatever you want.

    Create a device

    • Declare optional metadata. If not needed, leave empty
    • Press Next
    • Security : Press “Next” to auto-generate your authentification token
    • Press “Add”

    Create a device type

    • Save your device information (This is very important to copy&paste these information carefully into place where you can retrieve them later on)
      • Organization ID¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† 5cqv8q
      • Device Type¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬†SigfoxDevice
      • Device ID¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬† ¬†SFX_73ED4
      • Authentication Method ¬† ¬† token
      • Authentication Token¬† ¬† ¬† ¬†qo?g!Dskcym9xNrlqP
    • Close the window, your device is ready for IBM side.

    Create a device

     

    Now, an API key needs to be generated for future access:

    • Select “APPS” from the left side menu

    API Key

    • Click on “api keys” tab
    • Click “+ Generate API keys”
    • Populate “Comment” : Sigfox access API Keys
    • Copy&Paste the “API Key” and “Authentification token” for later on

    API Keys

    • Press Finish
  3. Create your IoT flow

    This section describes how to create the flow that will drive the integration logic.

    Create a flow:

    • Connect to IBM Bluemix : https://console.ng.bluemix.net
    • Go to CATALOG on to top menu bar
    • Select “node-red” to filter the offering
    • Select “Node-Red Starter”

    Node-Red

    • Populate your Application section and press “Create”

    3-NodeRed-2

    • After a while, the Node-Red service should be up and running

    Node-Red

    • View¬†your App using the following Menu and selecting your App URL

    3-NodeRed-4b

    • Click on “Go To your Node-RED flow Editor”

     

     

    Now, it is time to build the integration flow:

    • Drag&drop an “IBM IoT” node and configure as follow
      • Select “API Key” for Authentication
      • Use the Pen to declare an¬†API Key using the one your created before
      • Populate API Key and API Token fields
      • Press Add button

    NodeRed

    • Change the Name with “Sigfox IoT” for example
    • Press Done

     

    Complete the flow

    • Drag&drop a “Debug” node and link it

    Node Red debug

    • Click on “Deploy”
    • In the flow, “Debug” should be ON¬†(green) and “Sigfox IoT” should be connected (green). If there is an issue, check you API Key params.
    • Click on “Debug” tab on the right side to display future log info
  4. Configure Sigfox backend to IBM IoT Watson

    This section describes how to create a Callback as a link between Sigfox backend and Watson IoT. This procedure is attached to a Sigfox device type. Each Sigfox device is linked to a device type. HTTPS basic authentification is used to secure the connection.

    4-Sigfox-Device-Type

    • Press “New” button at the top right on the page to create a Device Type

    Device Type NEW

    • Select your group
    • Populate your device type:
      • Name :¬†CDR_DevType
      • Description :¬†This is a CDR_DevType
      • Alert email : xxx.yyy@zzz.com
    • Press the “Ok” button
    • Click on “Callbacks” menu from left side
    • Click on “New” button to create a new callback associated to your device type
    • Select “Custom Callback”

    • Open a terminal and execute Python with the following commands (replace all $variable with your context):
      • >>> import base64
      • >>> base64.b64encode(“use-token-auth:” + $(your device Authentication Token))
      • for example :¬†base64.b64encode(“use-token-auth:” + “qo?g!Dskcym9xNrlqP”)
      • the output should be your basic authentification key :¬†'dXNlLXRva2VuLWF1dGg6cW8/ZyFEc2tjeW05eE5ybHFQ'
    • Configure as follow (replace all $variable with your context)
      • Type : Data Uplink
      • Channel : URL
      • Url pattern : https://$(IBM organisation).messaging.internetofthings.ibmcloud.com:8883/api/v0002/device/types/$(IBM device type)/devices/$(IBM device ID)/events/$(Topic)
      • example : https://5cqv8q.messaging.internetofthings.ibmcloud.com:8883/api/v0002/device/types/SigfoxDevice/devices/SFX_73ED4/events/helloSigfox
      • Use HTTP Method : POST
        • Headers : Authorization : Basic $(your basic authentification key)
      • Content Type : application/json
      • Body : {
        “time” : “{time}”,
        “device” : “{device}”,
        “duplicate” : “{duplicate}”,
        “snr” : “{snr}”,
        “rssi” : “{rssi}”,
        “avgSnr” : “{avgSnr}”,
        “station” : “{station}”,
        “lat” : “{lat}”,
        “lng” : “{lng}”,
        “seqNumber” : “{seqNumber}”,
        “data” : “{data}”
        }
    • It should be displayed as follow

    Sigfox Callback

    • Click “Ok”
    • Check that the Callback is selected as “Enable” in Sigfox list

    4-Sigfox-Device-active

     

    • Select the “Device” tab from top menu

    Sigfox Device

    • Click on your device Id from the “Id” column on the appropriate line of the list of devices
    • Press the “Edit” button on top right of the page
    • Associate your device with your device type using “CDR_DevType” as your Type

    4-Sigfox-Associate

    • Press Ok¬†Button
  5. Complete the IoT flow

    This section describes how to read information from the received Sigfox messages.

    • Go back to your Node-Red graphical flow editor
    • Check the “Debug” tab is selected on the right side
    • Open the “Debug” node and select for Output : “complete msg object”

    • Push a message from your Sigfox device towards the Sigfox network
    • A debug message should be displayed into the debug tab
      • iot-2/type/SigfoxDevice/id/SFX_73ED4/evt/helloSigfox/fmt/json : msg : Object
        { “topic”: “iot-2/type/SigfoxDevice/id/SFX_73ED4/evt/helloSigfox/fmt/json”, “payload”: { “time”: “1480717528”, “device”: “1965D3”, “duplicate”: “false”, “snr”: “18.53”, “rssi”: “-123.00”, “avgSnr”: “32.50”, “station”: “0DF1”, “lat”: “49.0”, “lng”: “3.0”, “seqNumber”: “31”, “data”: “1234” }, “deviceId”: “SFX_73ED4”, “deviceType”: “SigfoxDevice”, “eventType”: “helloSigfox”, “format”: “json”, “_msgid”: “34a89b9d.cb5764” }
    • Business information are stored into “data” field. For example “1234” in the previous line.

     

    The flow works from the device to the Sigfox backend and is now received in IBM Watson IoT. Next steps explain how to read the content of the Sigfox message from the Node-Red flow.

    • Drag&drop a “function” node
    • Connect the function node in the middle of your flow

    • Rename it and double click onto it to append the following code

    • Because the data are stored as a String into a 12 byte long array, the script decodes for example the first byte as base 16 number from a String towards an integer. Little and big indian encoding impact should be considered carefully for multi-bytes storage.
    • Press “Deploy”
    • Push a new message from the Sigfox device
    • Read from debug tab
      • iot-2/type/SigfoxDevice/id/SFX_73ED4/evt/helloSigfox/fmt/json : msg : Object
        { “topic”: “iot-2/type/SigfoxDevice/id/SFX_73ED4/evt/helloSigfox/fmt/json”, “payload”: { “time”: “1480717528”, “device”: “1965D3”, “duplicate”: “false”, “snr”: “18.53”, “rssi”: “-123.00”, “avgSnr”: “32.50”, “station”: “0DF1”, “lat”: “49.0”, “lng”: “3.0”, “seqNumber”: “31”, “01ec09a00f3000”: “1234”,¬†“msgType”: 1 }, “deviceId”: “SFX_73ED4”, “deviceType”: “SigfoxDevice”, “eventType”: “helloSigfox”, “format”: “json”, “_msgid”: “34a89b9d.cb5764” }
    • Check that msgType is available and set with 1

    This illustrated that the first information from the message (called “data”) is decoded and stored into a separate variable (called “msgType”).

  6. Conclusion

    This recipe described all required steps to push messages from Sigfox backend towards IBM Watson IoT and how to decode their contents. Recent updates of both IBM and Sigfox websites can slightly impact the screen captures in the future.

  7. Versions

    11-April-2016   First version

    14-Nov-2016    URL updated

    14-Nov-2016    Basic Auth method updated

    02-Dec-2016    Refresh with new GUI; clarifications for Authentication encryption

2 comments on"Sigfox (Part 1) : Connecting a device"

  1. Hello,

    Thank you for this very useful tutorial that learned me a lot. Following the callback configuration in Sigfox backend, you are authenticating the callback for all devices of a particular type with the same Authorization header that matches only one device in Watson iot. Finally, imo, this conf is working fine for only one device. I’m really interested in having informations to manage several Sigfox devices with a same callback in a secure way.

    Best regards,

    • ChristopheDidier May 18, 2016

      Sorry for late feedback, I was not notified by your comment. Two comments, first, in Sigfox, a callback is linked to a device type. Many devices can share the same device type. Second, you can use IBM Gateway integration to facilitate multiple devices registrations and communications through a single “channel”. Hope this help you – Christophe.

Join The Discussion