skygrid documentation - read the docs · skygrid documentation, release 0 ... to get started,...

SkyGrid DocumentationRelease 0

SkyGrid

Apr 09, 2017

Contents

1 Concepts Guide 31.1 Introduction to SkyGrid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 SkyGrid Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.3 SkyGrid Domain Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.4 Device Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.5 API Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.6 Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2 Up and Running in 5 Minutes 92.1 Register a new account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.2 Create a new project and app user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.3 Create a schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102.4 Instantiate a Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.5 Turn on logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.6 Push some data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.7 Example: Simple application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3 Introduction to SkyGrid web apps 193.1 Deep dive: simple_app.html . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2 Using the REST API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.3 Example: Getting a list of Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

4 REST Guide 25

5 Javascript SDK Guide 27

6 Java SDK Guide 29

7 Device SDK Guide 31

8 Linking devices to SkyGrid using the SigFox network 338.1 Your first SigFox device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338.2 Adding SigFox devices to a SkyGrid project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

9 Connecting devices to the Things Network, via the LoRaWAN protocol 379.1 Hardware requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389.2 How the Things network integration works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

i

SkyGrid Documentation, Release 0

SkyGrid is a platform for handling projects that require connecting up thousands of devices to the cloud for centralizedmanagement with an API for the physical world. SkyGrid makes development for the real world easy.

Whilst you may be familiar with other Internet of Things (IoT) platforms, Skygrid is different, it’s more than just anIoT platform - it’s an entire backend for your project. User and device management, fine grained security controls,data storage, and more can be managed by Skygrid.

To get started, first check out the Concepts Guide. The Up and Running in 5 Minutes guide will then step you throughcreating a project, device and simple application all through the Skygrid platform.

Contents:

Contents 1


2 Contents

CHAPTER 1

Concepts Guide

This guide covers the basic concepts of the SkyGrid platform. To build IoT solutions in SkyGrid, it is important tounderstand how SkyGrid works.

Introduction to SkyGrid

SkyGrid is a platform for handling projects that require connecting up thousands of devices to the cloud for centralizedmanagement with an API for the physical world. SkyGrid makes development for the real world easy.

Whilst you may be familiar with other Internet of Things (IoT) platforms, Skygrid is different, it’s more than just anIoT platform - it’s an entire backend for your project. User and device management, fine grained security controls,data storage, and more can be managed by Skygrid.

SkyGrid provides the following:

• Device management, user management and security.

• Data visualization via the SkyGrid Data Explorer.

• A simple to use API for connecting devices, users and applications with the SkyGrid platform.

• Application SDK. A set of tools, libraries, relevant documentation, code samples that allow developers to createsoftware applications on the SkyGrid platform.

• Support for any hardware device capable of HTTPS.

• Certified hardware development kits and software libraries for easy integration to SkyGrid.

SkyGrid provides all the basic ingredients of an IoT project in a single environment, you can get started immediatelywithout having to subscribe to various other services. It provides the complete development environment required bydevelopers rolling out IoT solutions.

SkyGrid is a network agnostic platform and works over all network protocols including new LPWAN protocols suchas SigFox and LoRa, as well as traditional WiFi and cellular.

3


SkyGrid Concepts

First we will look at a typical IoT solution architecture, and the components involved. Then we describe the SkyGriddomain model.

Device

A device is the physical object which is connected to SkyGrid. The device pushes sensor data to the SkyGrid IoTplatform. Devices can vary from connected cars to connected light bulbs. SkyGrid supports all hardware devices thatcan push data using HTTPS.

Device SDK

SkyGrid provides open source software libraries for the following devices: Raspberry Pi, Arduino, ESP32, C.H.I.P.Install the software on your device and instantly get connected to SkyGrid. SkyGrid will continuously update thedevice SDK repository to support new devices as they are released.

SkyGrid IoT Platform

Developers use the SkyGrid IoT Platform to build and host IoT solutions. The SkyGrid IoT platform manages allthe devices in an IoT solution, via a simple to use administrative dashboard. It handles backend functionality, suchas data storage and security. It allows data to be visualized in charts and maps using the SkyGrid Data Explorer. Ithandles user management for app development. The platform maintains a representation of the device at all times in

4 Chapter 1. Concepts Guide


its database. When apps query the device, they are querying the SkyGrid database. Most importantly, the SkyGridplatform implements a simple to use REST API for both devices and applications to use.

Applications

The sensor data stored in SkyGrid is used to power IoT apps. Applications can range from consumer mobile apps,to enterprise integration servers. An example of a simple application setup is an app running on a mobile browser.Another example is a web application server. Applications access SkyGrid via its API.

Application SDK

To extend the range of the SkyGrid API, and make for easier and faster application development, a powerful JavaScriptSDK is provided. It includes support for web sockets, this means that SkyGrid powered apps can for example dynam-ically update data views, without requiring page reloads.

SkyGrid Domain Model

The SkyGrid domain model is based on the concept of projects, and it is important to understand how these areconfigured within SkyGrid.

SkyGrid Admin User

A SkyGrid Admin user is the developer who logs into the SkyGrid platform and manages the complete project. TheSkyGrid Admin user configures the projects, schemas, devices and project users.

1.3. SkyGrid Domain Model 5


Project

An IoT solution will typically have devices and app users. The easiest way to think of a project in SkyGrid, is that it isa way of grouping all these together. Devices and users are all configured on a per project basis in SkyGrid. Projectsare assigned a unique Project ID, which is required in some API requests.

Schemas

The way to think of schemas is that they define a type of device. Schemas are created to describe the physical objectthey represent in the SkyGrid database. The schema for a weather station could for example be Temperature, Humidityand Device Serial number. There is no limit to the kind of schemas and devices SkyGrid can support. The schemasthat define a device do not only have to reflect sensor data generated by that device, they can be used to tie other datato the device representation in SkyGrid. Schemas are assigned a Schema ID, which may be required in some APIrequests.

Devices

A device is created in SkyGrid by giving it a name, and a schema. Once a device is created in SkyGrid, it will beassigned a device key. The device must use this device key in any API requests towards SkyGrid (for example whenthe device is pushing sensor data to SkyGrid).

App User

A project can contain user details (email and password). These users are the end users of the IoT app. While they willnever log directly into the SkyGrid administrative GUI, their account details are stored in a SkyGrid project. An appuser is generally an end user for the created IoT app.

Device Permissions

A device has its own access control permissions. Create, Read and Delete permissions for each device can be config-ured. Device permissions can be configured per user. Different users can obtain different permissions on each device.A device could be accessed by all project users, some project users, or as is more often the case, a device is linked toone project user. By default, the SkyGrid Admin user can access all devices.

API Usage

The SkyGrid REST API is simple to use, here are some guidelines. API requests require a valid access token. Ob-taining an access token requires a username and password be provided in the initial API request. The username andpassword belong to either an App user, or the SkyGrid Admin user. The access token returned by SkyGrid is valid for24 hours. It is used in all subsequent API requests. There is an exception to this rule. When devices use the API toaccess SkyGrid, only a device key is required in the API request, and the initial authorization is not required. When thedevice is instantiated in SkyGrid a unique device key is created. The device should then use this key in API requests.

The following diagrams show the difference between Application API access, and device API access.

The REST API is a simple yet powerful tool to interact with Skygrid. More detailed information can be found in theREST API Documentation found here.



Fig. 1.1: Application (App User + SkyGrid Admin User) API Access

Fig. 1.2: Device API access

1.5. API Usage 7


Devices

SkyGrid can support any hardware device that can send HTTPS requests. SkyGrid provides software libraries for thefollowing devices to get you up and running quickly.

Arduino SDK C.H.I.P. SDK ESP32 SDK Raspberry Pi SDK


CHAPTER 2

Up and Running in 5 Minutes

This guide is intended to be a ‘hit the ground running’ guide on using SkyGrid. We recommend first reading theConcepts Guide.

Register a new account

First head across to https://dashboard.SkyGrid.io/, and select ‘Register a new account’ A confirmation email will besent to the email address you’ve provided. Click on the link provided in that email, which verifies your account. Afterverification, click to go back to the login page and log in to the dashboard with the registration email and passwordyou previously provided. Congratulations, you are now a SkyGrid Admin user.

Create a new project and app user

The first page you are greeted to is the Projects page. Right now this is empty, so let’s fix that! In the top right cornerclick ‘Create New Project’ For this first example, let’s just call the project ‘Demo Project’ We need to create an AppUser for this project - App Users are different from SkyGrid Admin users. SkyGrid Admin users have access to theSkyGrid dashboard and can make administrative changes to all the projects in an account. App Users are the userswho will be using the IoT you create. For now just register an app user account using the same email you signed upwith (we recommend using a different password).

In the projects panel now you can see ‘Demo Project’ has been created. The ID for this project is on the left.

9

https://dashboard.SkyGrid.io/


Create a schema

The way to think of schemas is that they define a type of device. One simple example would be a weather station:it monitors temperature, humidity, and the serial number of the device (so that we have a string parameter we canmodify) Click ‘create a schema’ and fill in the name as ‘Weather station 1’. Click “Add new property” to add the firstparameter: temperature. Then add parameters that define humidity and the serial number.

10 Chapter 2. Up and Running in 5 Minutes


Instantiate a Device

In the left hand panel you can see your device types: click the one we just created ‘Weather station 1’ and it will takeyou to the schema description page. Let”s go ahead and make some weather stations! Click the “Add a new device”button below the schemas, and the following window will pop up.

2.4. Instantiate a Device 11


Go ahead and make a few different weather stations.

You can click on one of the devices listed in the sidebar, and it will take you to the information page for this device.

Take note of the device Key - we shall use it in the next section

Turn on logging

In the devices panel, turn on logging for this device



Push some data

Now we have created a device in SkyGrid, we can push data to SkyGrid. Normally, this would be done by codinga device. Instead, we are going to simulate the device pushing up data by using a program called Postman, which isused to interact with the REST API. More detail on how to construct queries can be found here - to perform just onedevice update though, set the following parameters:

• Copy the API endpoint into the PUT field https://api.SkyGrid.io/d/your_device_key_here

• In the Headers field, set one of the headers to Content-Type - application/json

• In the body of the request, choose ‘raw’ for encoding type and then copy paste the following JSON into the textblock

{"temperature": 327,"humidity": 12

}

2.6. Push some data 13

https://www.getpostman.com

https://api.SkyGrid.io/d/your_device_key_here


To see the data being pushed to SkyGrid, click on the corresponding device in the left hand panel under devices. TheCurrent State will be updated, as will the Event Log.

Try sending some different values from the device to SkyGrid. Then go to ‘Data explorer’ in the left menu bar. Select‘Weather station 1’ as the schema, the device which we are pushing data to, the fields we are updating and the timethat we wish to observe the data over (probably just the last few minutes).

Example: Simple application

The other side of your project is the webpage, software or application which needs to read and write SkyGrid data.There are obviously a hundred different ways this can be done: we shall be creating a simple webpage that pulls downand displays the data from your project.

Download this HTML file and open it in your favorite text editor. Note, save the page as type “Webpage,HTML Only” (and not as type “WebPage, Complete”).

On line 96 of the HTML file, edit the code to include your own project ID, and on line 98 put your device id. Both ofthese numbers are found through the SkyGrid dashboard.



// Create a new SkyGrid project object *** ADD YOUR PROJECT_ID HEREvar project = SkyGrid.project('aFFzyVKi');// Use the project object to fetch a device object *** ENTER YOUR DEVICE_ID HEREvar myDevice = project.device('').fetch().then((device) => {

Once that has been set, open the HTML file in your web browser and use Postman to push some new data to SkyGrid.

2.7. Example: Simple application 15


New data will appear in real time, and a satisfying little animation takes place. In this sample app, the app is configuredto listen to the “project”, so if any device in that project pushes data to SkyGrid, the animation will take place.

That’s it! In (hopefully) under 5 minutes you have created a simple but complete, end to end IoT application. Seefurther guides for more detailed information on using SkyGrid.

2.7. Example: Simple application 17

CHAPTER 3

Introduction to SkyGrid web apps

In this guide we shall go into the simple_app.html application with a bit more depth, explaining exactly what eachsection is doing.

Deep dive: simple_app.html

Above, we created a simple HTML page that displayed some data. In this section we will go through this basicexample in more detail.

Download this HTML file and open it in your favourite text editor

Let’s go through the code.

Lines 1-56 are related to the Stylesheet for the page, and including some Javascript libraries that we need. We won’tgo into too much detail about this, if you’re completely unfamiliar with HTML and CSS then perhaps this page maybe informative for you.

We’re only concerned with one line in this section, line 10. This line imports the SkyGrid Javascript SDK from ourserver. You can download and include this locally as well, but for now we’ll just import it from the internet.

<script src="https://cdn.SkyGrid.io/sdk/js/SkyGrid-latest.min.js"></script>

Lines 57 - 85 are normal HTML, they contain the actual content of the webpage. We can see on line 61 we’ve declaredthe Sun icon to exist. Below that is a span with an id=”temp” - we will update this field with some Javascript in abit. Line 76 has something similar, an element with id=”humidity” - again, we shall use the SkyGrid SDK to pull datafrom SkyGrid and update these fields with the values we pull down.

<body><center>

<h1 style="margin-top: 50px" style="margin-bottom: 50px">SkyGrid weather app</→˓h1>

<div class="details"><div class="container" style="margin-bottom: 50px"><i id="sun" class="fa fa-

→˓sun-o red big "></i></div>

19

https://www.khanacademy.org/computing/computer-programming/html-css

<span id="temp">...</span> °Cs</div>

<hr style="height: 40px; border: none;">

<div class="" style="margin-top: 50px"><table style="width: 550px;">

<tr><td>Humidity

</td></tr><tr><td><div class="sub_details" id="humidity">...</div>

</td></tr>

<tr><td colspan="2" style="height: 50px;"></td></tr>

</table></div>

</center>

All the Javascript code that interacts with SkyGrid is contained within lines 87 to 120

<script>function log(message) {

//element.innerHTML += message + '<br />';console.log(message);

}

// Create a new SkyGrid project objectvar project = SkyGrid.project('');// Use the project object to fetch a device objectvar myDevice = project.device('7VcOapOH').fetch().then((device) => {

// Apply a subscription to any changes (updated in real-time via websockets)device.subscribe(function(changes) {// When a change comes through, update the pageupdate(device);

});

// Apply first update to the pageupdate(device);

});

function update(device) {// Update$("#temp").text(device.get('temperature'));$("#sun").stop().animate({"font-size" : "260px"}).delay(50).animate({"font-size" :

→˓"240px"});

20 Chapter 3. Introduction to SkyGrid web apps


$("#humidity").text(device.get('humidity'));$("#serial").text(device.get('serial'));

};

This section contains all the Javascript running on the webpage. Let’s step through it in sections.

The first function in the script section is a simple logging function. Modern browsers all have a console that pages canwrite to using console.log(). You can see this console by right clicking a page and choosing ‘inspect’.

The next lines show how to set up a device subscription, so that when the data for a device changes (like when a devicein the field pushes an update) the webpage will automatically be updated. SkyGrid is organised around projects, sofirst we get the project object corresponding to a particular project id. The code to create new SkyGrid objects likethis was imported via the SDK at the top of the file. Objects like this are a convenient interface for the programmer tointeract with SkyGrid.

Devices are attached to projects, so we can expect to access devices via a project.

For example

// Create a new SkyGrid project objectvar project = SkyGrid.project('');// Use the project object to fetch a device objectvar myDevice = project.device('7VcOapOH').fetch().then((device) => {

// Apply a subscription to any changes (updated in real-time via websockets)device.subscribe(function(changes) {// When a change comes through, update the pageupdate(device);

});

NOTE: If your application doesn’t appear to be working, you can open up the debugging console and see if you’regetting any errors. In Chrome, you can open this with ‘Ctrl+Shift+I’, in Firefox it is ‘Ctrl+Shift”Q’. Click on ‘Console’and see if there is an error - if you are receiving the following error, then you have not successfully saved the HTMLfile with your correct project ID.

When subscribe is called, any time a piece of data in the project changes, the function that we pass it in as an argumentwill be called - you must pass subscribe a function with two arguments, device and changes.

The contents of the function we pass into subscribe will be called every time a piece of data in this project changes.This allows us to update all the values on the page, and trigger simple events such as the animation. This line:

$("#humidity").text(device.get('humidity'));

Is a call to the Javascript library called JQuery (which we also imported, you can see so at the top of the file). This linesearches the HTMl for the element with id=”humidity” and changes the text in this element to whatever we pass thatfunction. In this case, we wish to change the text to the latest value for humidity, which we get from SkyGrid usingthe function device.get(). The parameter we wish to use must match the parameters as described in the schema.

The SDK is very powerful, and can do much more than what we’ve talked about here. Check out the SkyGridJavascript SDK Guide for more information.

3.1. Deep dive: simple_app.html 21


Using the REST API

The REST API is the most basic way to interact with the SkyGrid platform. It is very flexible, as any language capableof creating HTTP requests can use the REST API. It is very simple and easy to get started. For a complete reference,see the REST Guide.

To use the REST API, most queries require an authentication token. The endpoint we use to aquire a token is theLogin endpoint. The following screenshots from Postman show how to set up the request:

The Content-Type will always be application/json. Simply change x-project-id to your project ID, which can be foundin the SkyGrid dashboard.

In the body section, replace the details above with the details of your project user details - these are not necessarilythe same that you use to log in to the SkyGrid dashboard! These are the details for a user which has been added to thisparticular project. Remember the SkyGrid dashboard user can be administering multiple projects, but project usersonly have access to that specific project.

If login is successful, you should get a response similar to that below, containing the authentication token.



This token is required for most queries performed through the REST API. Next up, we will use this token to query aSkyGrid project for a list of devices.

Example: Getting a list of Devices

We shall begin by querying to get a list of Schemas. This requires a project-ID, but does not require an authenticationtoken in the header. The URL is:

https://api.SkyGrid.io/schemas

With the project ID passed in via the header, with the header tag x-project-id

A JSON object containing all the information for schemas is returned. This can be parsed by any standard JSONparsing code library.

3.3. Example: Getting a list of Devices 23

https://api.SkyGrid.io/schemas


To get a list of devices in a project, we can use a different endpoint

https://api.SkyGrid.io/devices

With the project ID passed in via the header, with the header tag x-project-id

Once again, a JSON object is returned containing all the information from the request.

The REST API is a simple yet powerful tool to interact with SkyGrid. More detailed information can be found in theREST Guide.


https://api.SkyGrid.io/devices

CHAPTER 4

REST Guide

See REST API documentation.

25


26 Chapter 4. REST Guide

CHAPTER 5

Javascript SDK Guide

See Javascript API documentation.

27


28 Chapter 5. Javascript SDK Guide

CHAPTER 6

Java SDK Guide

See Java API documentation. Get the SDK here.

29

https://github.com/skygridio/skygrid-sdk-java


30 Chapter 6. Java SDK Guide

CHAPTER 7

Device SDK Guide

Coming soon

31


32 Chapter 7. Device SDK Guide

CHAPTER 8

Linking devices to SkyGrid using the SigFox network

Sigfox is a proprietary LPWAN solution with network operators building infrastructure around the globe. In this guide,we shall show how to connect to the SigFox network operated throughout New Zealand, Australia and Hong Kong -Thinxtra.

Your first SigFox device

This tutorial we shall use the SiPy development board. As the name suggest, SiPy can be programmed in Python. Itsupports SigFox, Wifi and BlueTooth network procols. PyCom provide extensive documentation on how to programthese boards. With up to 24 GPIO, 8 ADC inputs, UART, SPI, I2C etc. support, this module is targetted at enterpriseusers with large deployments, but it’s still very simple to use and is a good starting module.

After following the above guides, run this python script to get the SigFox ID and PAC, which you will need to registerthe device with Thinxtra. Once registered, sending data through the SigFox network requires a few lines of simplepython. Note that the sending code is commented out by default.

from network import Sigfoximport binasciiimport socket

#### init Sigfox for RCZ4 (Austrlia/NZ)##

sigfox = Sigfox(mode=Sigfox.SIGFOX, rcz=Sigfox.RCZ4)binascii.hexlify(sigfox.id())binascii.hexlify(sigfox.pac())

##

33

http://www.thinxtra.com/

https://www.pycom.io/product/sipy/

https://docs.pycom.io/pycom_esp32/index.html


## Send a Sigfox message##

# create a Sigfox socket#s = socket.socket(socket.AF_SIGFOX, socket.SOCK_RAW)

# make the socket blocking#s.setblocking(True)

# configure it as uplink only#s.setsockopt(socket.SOL_SIGFOX, socket.SO_RX, False)

# send some bytes#s.send(bytes([1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]))

Adding SigFox devices to a SkyGrid project

The SIGFOX network allows your device to send up to 140 messages per day. Each message can be up to 12 bytes ofactual payload data. You can also transmit 4 messages to each device per day, these download messages can be up to8 bytes. For a device to receive messages, it must send a request to the Sigfox backend, which means that the devicemust be programmed to receive data at certain times, or when certain device conditions occur. The Sigfox protocolalso transmits the Sigfox device ID in the message, the 12 and 8 bytes represent the actual payload. Sigfox does notunderstand or transform your payload, only you know how it is structured. You can structure the payload as requiredby your application. 12 bytes easily covers the needs for devices that transmit data such as the location co-ordinates,other sensors measurements or alarm events. The downlink ability allows you to send 8 bytes of data to the device,which can be used as configuration data if needed. You can improve battery life by only using uplink, if you do notneed two-way communications.

How the sigfox integration works

Sigfox offers a callback service: every time a message is received by the network, you can set up the way you wantit to be forwarded to SkyGrid. This lets you take advantage of the SkyGrid features such as our powerful SDKs, datavisualization, integration to other systems, and all the other benefits that come with the SkyGrid IoT platform. In theSigfox backend, the configuration of callbacks is done per device type, and is configured within the device type page.When a device uploads a message to the Sigfox backend, it will trigger the callback towards SkyGrid. A callback hasa set of common variables: Device Id : device identifier (in hexadecimal – up to 8 characters - 4 bytes) Data : the userdata (in hexadecimal, max 12/8 bytes, upload/download) Others : time, duplicate, snr, station, avgSnr, lat, lng, rssi,seqNumber

1 Register the SkyGrid dev kit on the Sigfox backend

Select your country/operator (Australia and New Zealand use Thinxtra). Enter the SigFox ID and PAC you collectedfrom the Sigfox device at the start of the tutorial.

Enter some more information including name and email, you will then receive an email from Sigfox with your accountdetails. Use this to log into the Sigfox backend.

34 Chapter 8. Linking devices to SkyGrid using the SigFox network


2 Add a new schema in SkyGrid

The schema properties must align with how you will construct your payload on the device. You must specify thelength of each property for Sigfox properties within the schema. Total length of the Sigfox properties cannot exceed12 bytes.

3 Create a Sigfox device in SkyGrid

Create a new device, of the schema configured in the previous step. Select Sigfox for connectivity. Enter the PAC andID.

4 Get the callback URL

Once you have created a Sigfox device, click on the Sigfox Settings to get the callback information that you must useto configure the Sigfox backend. You will see the details below, for configuring the Sigfox backend in the next step.This URL only gets those values you have configured in SkyGrid. If you need other values like time, duplicate, snr,station, data, avgSnr, lat, lng, rssi and seqNumber; you must include a key value for each one at the url query. Formore information on how to configure custom calls see the sigfox documentation.

5 Configure the callback in the Sigfox backend

Go to the SkyGrid-Radiocrafts Device Type on the Sigfox back end, and click edit. Select Callback and click New.Click Custom Callback. Insert the values provided by SkyGrid in the previous step. Click OK to save the callbackUrl. 6 Upload data to Sigfox, and view in SkyGrid Push data from your device to the Sigfox backend, use SkyGriddata explorer to view the data.

8.2. Adding SigFox devices to a SkyGrid project 35

https://blog.sigfox.com/create-callback-sigfox-backend/


36 Chapter 8. Linking devices to SkyGrid using the SigFox network

CHAPTER 9

Connecting devices to the Things Network, via the LoRaWAN protocol

LoRaWAN™ is a Low Power Wide Area Network (LPWAN) specification intended for wireless battery operatedThings in a regional, national or global network. LoRaWAN targets key requirements of Internet of Things such assecure bi-directional communication, mobility and localization services. The LoRa specfication came from a collab-oration between over 15 large technology companies who created the LoRa Alliance organisation to promote LoRatechnology and encourage it’s adoption (all the member companies sell some piece of the LoRa ecosystem).

Perhaps the most exciting thing about LoRaWAN is that it is possible to buy a standalone gateway and set up a privateLPWAN network. Companies deploying LoRa claim it has a 2.5km radius. It is possible to “daisy-chain” LoRagateways together, although that is outside the scope of this guide. All over the world there are farmers, warehousesand field-service engineers (and many more) deploying private LoRa networks to improve their business operations..._Get in touch: www.skygrid.io to discuss your potential application.

The largest public network which utilizes LoRaWAN is the Things network. It is completely community driven- startups, companies and enthusiasts have voluntarily purchased and set up gateways around the world to try andbootstrap a completely free-to-access IoT network. Locations of gateways for specific countried are available - forexample Australia has 21 active gateways in the Things Network as of April 2017. There is a range of devicescurrently available around the world for LoRaWAN. Some regions are behind others, especially across different ITUregions.

In this guide we shall connect a device to the Things network, which is completely free for anyone to access - it has agrowing community of techno-buffs, enthusiasts, volunteers, first-timers and early adopters. There is likely a ThingsNetwork community near you already, if not you can start one! The crowdsourced nature of the things network is atthe heart of what they do. This is their mission statement:

The Internet was created by people that connected their networks to allow traffic from, to and over their servers andcables to pass for free. As a result, there was abundant data communication and exponential innovation.

The Things Network is doing the same for the Internet of Things by creating abundant data connectivity. So applica-tions and businesses can flourish.

37

https://www.lora-alliance.org/

https://www.iothub.com.au/news/meshed-brings-lorawan-to-brisbane-440136

https://www.thethingsnetwork.org/country/australia/

https://www.wikiwand.com/en/ITU_Region


Hardware requirements

The module that we use in this tutorial is the MultiTech mDot. This module can be deployed without any additionalhardware required. A tutorial on how to program the mDot is available here. The mDot can also be interfaced to othermodules, such as the RaspBerry Pi3. Our experience with using the things network at hackathons led us to develop araspberry pi compatible ‘hat’ that provided a simple way to connect these two modules. It also features an integratedAnalog to Digital converter, giving the Raspberry Pi 8 ADC interfaces.

Python libraries for interfacing with the mDot can be found in this SkyGrid github repo.

Please check out our affiliate vendors to aquire LoRaWAN modules or gateways in the Australia/NZregion:

• geowan

• meshed

How the Things network integration works

Devices push data to their local Things network LoRaWAN gate, using the LoRa radio protocol. At the gateway, themessage is sent via normal internet back to the Things network server. The server then further pushes the message toSkyGrid. The complete set up requires some simple configurations.

1 Register the device with the Things network

The best reference for connecting an mDot module to the Things network is their documentation.

2 Add a new schema in SkyGrid

The Things network passes a JSON object which contains not only the data payload from the device, but a lot ofmetadata about the current configuration of the Things network. To accept this data we must register a device inSkyGrid with this Schema.

Below is an example JSON payload received from the Things network.

First create a new schema in SkyGrid, and choose which of the above properties are of interest. To receive just thepayload, only a single property schema is required

38 Chapter 9. Connecting devices to the Things Network, via the LoRaWAN protocol

http://www.multitech.com/brands/multiconnect-mdot

https://www.thethingsnetwork.org/labs/story/getting-started-with-the-multitech-mdot

https://www.raspberrypi.org/products/raspberry-pi-3-model-b/

https://github.com/skygridio/sigfox-python

https://geowan.io

http://meshed.com.au/community-iot-networks/:http://meshed.com.au/community-iot-networks/

https://www.thethingsnetwork.org/docs/devices/


3 Create a Sigfox device in SkyGrid

Instantiate the SkyGrid device which is the virtual representation of your real-world hardware.

images/ttn_dev.png

4 Construct the callback URL from the deviceId

The REST ‘API documentation’__ demonstrates how to use the SkyGrid REST interface.

Replace deviceId in the above URL with the device ID of the object you created in SkyGrid.

5 Configure the callback in the Things network backend

Inside the Things network console click applications. Navigate to the ‘integrations’ menu. Select ‘add integration’and then choose ‘HTTP Integration’. Configure the HTTP integration as peer the following parameters:

9.2. How the Things network integration works 39

http://docs.skygrid.io/rest/

https://console.thethingsnetwork.org


40 Chapter 9. Connecting devices to the Things Network, via the LoRaWAN protocol

skygrid documentation - read the docs · skygrid documentation, release 0 ... to get started,...

Documents