Getting Started with Sigfox

This guide teaches you how to get started using Sigfox with Atmosphere. This includes creating an NXP Rapid IoT project, setting up a Sigfox click element, connecting the Sigfox Portal to Atmosphere Cloud, and then viewing Sigfox data in Atmosphere.

This guide demonstrates a simple project that reads temperature and sends the current floating point temperature value to Atmosphere via Sigfox.

Prerequisite: You should already have both an Atmosphere account and a Sigfox Portal account.

It's highly recommended to have a moderate understanding of the Sigfox Portal backend before enabling Atmosphere and other third party services to communicate to your Sigfox account.

Hardware Requirements

  • NXP Rapid IoT Kit
  • Tablet or smartphone mobile device
  • MikroElektronika Sigfox Click board (Sigfox 2 Click board if in North America)
  • Optional: Sigfox Network Emulator if you aren’t within a Sigfox coverage area

For the purposes of this guide, we used the NXP Rapid IoT Kit, but any Atmosphere-supported development board that can use the Sigfox Click board will work.

Software Requirements

  • Atmosphere IoT app. The mobile app allows you to view your registered devices and display and run the project’s interface. You can download the Atmosphere IoT app from its downloads page or through the Apple App Store or Google Play Store.
  • Atmosphere IoT Agent. The Atmosphere IoT Agent is a local application that runs in the system tray and acts as an intermediary between the computer’s connectivity protocol drivers and the browser running Atmosphere, used to assist in programming your device. You can download the Atmosphere IoT Agent from its downloads page.
    • The Atmosphere IoT Agent is only needed if you don’t use an NXP Rapid IoT Kit while going through this guide, as it doesn’t require it for programming firmware.
  • Ensure Bluetooth is enabled on the mobile device you’ll use to interact with the NXP Rapid IoT Kit.
  • Established device type created within the Sigfox Portal for your Sigfox Click board.

Step 1 of 8: Connecting the Sigfox Portal to Atmosphere Cloud

Before a Sigfox device can be used in Atmosphere, the Sigfox Portal must be configured to forward data to Atmosphere. This involves generating an API token in Atmosphere, and creating a callback in Sigfox using the token for your device.

  1. To generate an API token, open the account menu from the navigation bar and click Security.
  2. In the Security section’s Authentication Tokens area, click the Generate Token button to make a new API token. This will be the token you use to provide the Sigfox Portal the ability to send data to your Atmosphere account.

With an API token created, it now has to be applied to your Sigfox account by creating a callback function for your device type.

  1. Login to the Sigfox Portal, and navigate to the Device Type page. On the page, select the device type containing your Sigfox Click.
  2. Within the device type, navigate to the Callbacks tab, then click New to create a new callback. On the callback creation screen, select the Custom Callback type. This will create a callback between Sigfox and Atmosphere.
  3. The first few fields can remain unchanged. In the URL Pattern field, enter the following text:
     https://platform.atmosphereiot.com/user/things/protocols/sigfox/hook/null/null/null
    

    NOTE: If you’re using an Atmosphere server other than the primary Atmosphere platform, replace platform.atmosphereiot.com in the URL with the server you’re building your project on. For example, if you’re using the NXP Rapid IoT Studio, your url would be:

     https://rapid-iot-studio.nxp.com/user/things/protocols/sigfox/hook/null/null/null
    
  4. In the Use HTTP Method field, change the method to POST.
  5. In the Header field, enter a new header with the header name api_auth_token, then paste your Atmosphere API token into the value field.
  6. In the Content Type field, change the type to application/json. Within the content type’s Body field, enter the following text:
     {
     "device" : "{device}",
     "data" : "{data}",
     "time" : {time}
     }
    
  7. When finished setting up the callback, click Ok.

Your callback configuration should resemble the following:

Sigfox Callback Configuration

With the callback created on the Sigfox Portal, you can go into Atmosphere.

Step 2 of 8: Create a New Project

Navigate to Atmosphere Studio from the side menu. When you visit Studio for the first time in a session, you are brought to the Studio Projects screen.

  1. Click the New Project button. This displays a New Project window.
  2. Select the Rapid IoT project type (or whichever project type you’re using) and give the project a name, then click Create.

This opens a new project in Studio.

This guide walks through the step-by-step process to perform actions in Studio, but doesn't cover the in-depth aspects of Studio itself. To learn more about using Studio, its areas and features, and Studio elements, visit the Atmosphere Studio section.

Step 3 of 8: Create the Project’s Embedded Firmware

The first aspect of building this sample project is adding elements to the Embedded tab to create the project’s embedded firmware. This involves setting an interval to read embedded data, and to tell the interval to read the onboard temperature sensor of the NXP Rapid IoT Kit.

  1. Add the following elements to the canvas by clicking them in the Element Toolbox:
    • Interval Element Interval element: The interval element sets the project to run at the time set in the element’s properties, which by default is set to once per second (1000 ms). Change the Interval property to 300000 (5 minutes). The Sigfox network is designed for infrequent, small packets of data; sending data any more frequently than 5 minutes is not recommended. Sigfox only allows your device 144 messages per day. See https://build.sigfox.com/steps/study for more information about rate limits.
    • AMS ENS210 AMS ENS210 element: The ENS210 element reads the Rapid IoT’s onboard temperature sensor.
  2. Click the Add Element button in the Embedded tab’s Element Toolbox to display the catalog of importable elements. In the window, enable the MikroElektronika Sigfox Click to add it to your Element Toolbox, then add the Sigfox Click Element Sigfox click element to your canvas. The Sigfox click element communicates with the MikroElektronika Sigfox Click board and sends data over the Sigfox network.
    • The element’s default properties will be sufficient if you’re connected to the Sigfox network within the United States. If you’re not within the United States, set the Network Standard appropriately.
    • If you’re connected to a Sigfox emulator, enable the Use Public Key property.
    • The Sigfox click element is configured by default for the click board to be inserted into slot 3 of the docking station. If it’s inserted in a different slot, adjust the pin properties accordingly.
  3. Connect the interval element to the ENS210 element. This creates an event between them, which can be seen in either the interval element’s properties, or by clicking the connector’s Configuration Button button. The event added is within the Interval trigger, with the ENS210 ability Read Temperature (C). This means that when the interval element is triggered (which is every 5 minutes), it will read the current temperature.
  4. Connect the ENS210 element to the Sigfox click element. Ensure that the trigger for the ENS210 element is Temperature Read and the ability to be executed on the Sigfox click element is Send Payload. This means that whenever the temperature is read from the ENS210 element, that temperature will be sent as a payload over the Sigfox network.

That’s all for work in the Embedded tab. The Embedded tab’s canvas should resemble the following image:

Sigfox Demo Canvas

Step 4 of 8: Enable the Project’s Cloud Connectivity

The third aspect of building this sample project is enabling it for cloud connectivity. When a Sigfox click element is added to the Embedded tab’s canvas, a coupled Sigfox click element is added to the Cloud tab. This allows the user to retrieve data sent from the Sigfox Portal and use it within Atmosphere.

  1. Click the Cloud tab to move to the cloud area of the project. Notice how the Element Toolbox has changed, and that the coupled Sigfox click element is displayed on the canvas.
  2. Add a Cloud Storage Element cloud storage element to the canvas, and connect the cloud storage element to the Sigfox click element. This allows Atmosphere to store data sent to it from the connected Sigfox click element.

That’s all for creating the project! With the added cloud connectivity, the project will send the temperature to the Sigfox Portal every 30 seconds. The Sigfox Portal will then send this data to Atmosphere where it will be stored.

The final canvas for the Cloud tab should resemble the following:

Sigfox Demo Cloud Canvas

Step 5 of 8: Compile the Project

Once the project is finished, it needs to be compiled. Compiling readies the entire project’s source code for deployment.

  1. From any tab, click the Compile button in the project options menu on the top-right of the screen. You’ll receive a notification when the project is compiled.

Step 6 of 8: Program Firmware into the Device

With the project compiled, your NXP Rapid IoT Kit can be programmed with the project’s embedded firmware.

  1. Ensure the NXP Rapid IoT Kit is connected to the computer via USB and in programming mode (blinking green LED).
    • If it’s not in programming mode, simultaneously hold the top-left and bottom-right side buttons for five seconds until the screen goes black. Continue holding the buttons while the screen goes black. The kit’s green LED will turn on and start blinking, indicating the device is now in programming mode. The side buttons can be released. While in programming mode, the NXP Rapid IoT displays as a mass storage USB device on your computer.
  2. From the Embedded tab, click the Program Firmware button from the tab’s toolbar. This downloads a .bin file containing the project’s compiled firmware.
  3. Locate the downloaded file on your computer, and move it into the Rapid IoT mass storage device. This initiates programming of the Rapid IoT, which is represented by a series of blinking lights on the device.

Step 7 of 8: Register the Device

With firmware installed, the device can now be recognized and connected to Atmosphere. From here, open the Atmosphere IoT app on your mobile device, which we’ll use to register the device.

To register a device:

  1. Navigate to the Devices page, and click the Register Device button in the top-right to display the Register Devices window. When the window opens it will automatically begin scanning for available devices within range.
    • Ensure your NXP Rapid IoT Kit is within range from the device running the Atmosphere IoT app you are attempting to register from, otherwise it may not appear.
  2. The list of available devices appears. Select the NXP Rapid IoT you just programmed and click Register.

The device is registered to Atmosphere and displayed on your Devices page.

Step 8 of 8: View Device Data

Now that the device’s data is sent to Atmosphere, let’s view it through one of the many device dashboard widgets available. In this guide we’ll use a data table to chart the temperature reading.

  1. To add a widget to the device’s dashboard, click the Configuration button on the side of the page. This displays the menu of available widgets. Select the Data Table data table widget to add a table to the dashboard.
  2. Give the data table a name, and then select the CloudStorage for the table’s data. This populates the data table with the values of the temperature as time progresses. Click Save when finished.

This populates the data table with the temperature values from the NXP Rapid IoT, sent over from the Sigfox Portal.

Congratulations, you just finished a complete project sending data between the Sigfox Portal and Atmosphere!