LoRa4Makers usage

LoRa4Makers is made available for the sole purpose of allowing makers, testers and academics to test the LoRaWAN technology and LoRaWAN network of Proximus at no charge for a limited period of time.

For any commercial or long term usage of our LoRaWAN network, we recommend you make use of the Proximus MyThings solution , or if any of the following features are important to you:

• Broad range of payload decoders for professional devices
• Support for ABP and OTAA devices
• Support for downlink messages

Please note that the Proximus MyThings APIs on this platform require that you have an existing and active Proximus MyThings contract with Proximus. Customers looking to subscribe to MyThings can send their enquiry to iot@proximus.com.

Managing devices

Activating your device

Even if your device is sending messages to the Proximus LoRa network, they will not flow into the EnCo platform until the device is activated here. To activate it:

• Sign in using your EnCo account
• Make sure you are already subscribed to LoRa4Makers
• Create a Lora device in LoRa4Makers microsite.

The following types of LoRa devices are supported:

• Generic LoRa devices: any generic ABP LoRa-capable device, which can be activated on the Proximus LoRa network, except for AllThingsTalk devices.
• AllThingsTalk Rapid Development Kits created by AllThingsTalk, for which LoRa4Makers will decode the payload, as long as these are sent from the ATT kits as "CONTAINERS" (#define CONTAINERS in your project file)

The general device activation flow is as follows:

1. Subscribe to the LoRa4Makers asset on the Proximus API Solutions marketplace (EnCo) if you haven't already
2. Open the LoRa4Makers microsite
3. Click on + button to create a new device
4. Provide a unique device ID (name) and device Unique Identifier.
5. Associate at least one tag to the device. Press enter or tab after typing a tag name.
6. Choose the device type
7. Click Add

A confirmation windows will appear with all data you may need to configure your hardware device, namely:

• Device address
• Application Session Key
• Network Session Key

Modifying and deleting devices

The LoRa4Makers microsite further allows you to:

• View your device data - in case you need to copy again the address and keys
• Edit your device - to change its name or associated tags
• Delete your device

Retrieving device data

Introduction

Once your device has been created and your hardware properly configured, you are ready to start receiving your messages. The LoRa4Makers microsite will show a count of messages received during the day for each created device.

All messages are forwarded to the CloudEngine. Make sure you are subscribed to CloudEngine in our marketplace. The free plan lets you reach 1500 free executions per day, enough to process 288 messages coming from 5 devices.

CloudEngine inbound endpoint

Your device data is available in CloudEngine via the new LoRa4Makers inbound endpoint.

Message filtering

After adding the LoRa4Makers inbound endpoint to your CloudEngine script or flow, you can define filters on incoming data by clicking on this endpoint and adding tags. The following filters are supported:

• DevEUI : filtering on specific device mac addresses (wildcards are not supported)
• device ID : filtering based on the name of your device (wildcards are not supported)
• device tags : based on the tags you associated to your device when creating it

Data format

The message data is accessible in your CloudEngine flow or script in a data array:

Common data fields

Generic device data fields

For generic LoRa devices created with LoRa4Makers, the following data field will always be added to the common data fields:

Exemple of a data array for a generic LoRa device:

[LrrSNR=9.0, Lrrid=004A059B, SpFact=9, SubBand=G3, FPort=1, Channel=LC6, 
PAYLOAD=1010/9002,20/153,0, FCntUp=809, Time=1571840484578, DevEUI=000012340020CC61, 
LrrRSSI=-67.0, DeviceAddress=06060606, FCntDn=101, DevLrrCnt=2, 
Tags=["VERSASENSE"], DeviceName=VERSA-3C61]

AllThingsTalk LoRa RDK fields

For AllThingsTalk LoRa RDK devices created with LoRa4Makers, any of the following field will be added to the common data fields depending on the scenario you have implemented on your board.

Exemple of a data array for a generic LoRa device:

[LrrSNR=5.0, Lrrid=004A022E, SpFact=7, SubBand=G1, FPort=1, 
Channel=LC2, FCntUp=3, z_motion=0.0, Time=1571818673131, 
DevEUI=000012340020CC61, LrrRSSI=-94.0, y_motion=1.0, 
x_motion=-19.0, DeviceAddress=06060606, stream_id=8, 
FCntDn=2, DevLrrCnt=2, Tags=["ATT","DEMO"], DeviceName=ATTPORT2]

Decoding messages from generic devices

Decoding your raw binary message is best done using CloudEngine in script mode. Refer to the CloudEngine documentation to learn more about scripting mode.

Sample CloudEngine scripts can be found in our GitHub.

AllThingsTalk LoRaWAN RDK tutorial

If you have acquired an AllThingsTalk LoRaWAN RDK, we created a step by step tutorial to onboard this device on the Proximus LoRaWAN network using LoRa4Makers and using CloudEngine to retrieve your messages. The new tutorial can be accessed here.

API authentication

API Solutions uses OAuth2 to protect API resources. The OAuth2 specification has become the predominant standard for securing RESTful APIs and identity delegation.

In order to gain access to the resources exposed by your API assets, you will need to pass along a valid OAuth2 bearer access token. Here is how you can generate such a token.

Obtaining your OAuth2 Application Keys

Each project you create through the API Solutions Market will result in the creation of a unique pair of OAuth2 application keys. To retrieve your keys, proceed as follows:

• First, log in and visit your dashboard on the portal. Click the "TOKEN" menu.
• This will result in your application keys to be shown. These keys can be used to access API resources exposed by any API asset to which you subscribed, within the scope of the selected project.

Your application keys are sensitive information; keep them private at all time!

Make sure to store your application keys in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case your application keys would become compromised, contact us through support and we'll revoke them to block access, and provide you with a new pair. This is also the reason why all API traffic should pass through secured HTTP, and why we do not support plain HTTP.

Generating a fresh bearer access token

A bearer access token is a self-contained unique identifier through which you can gain access to API resources. Before elaborating on how you can obtain such type of token, please note that these tokens are valid for a limited time span of 1 hour (or less, if explicitly revoked).

You can obtain a new token by issuing the following request against the server https://api.enco.io :

/token POST

Issue a request to https://api.enco.io/token, adding the following headers and body:

Request

curl -X POST \
  'https://api.enco.io/token?grant_type=client_credentials&scope=openid&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&Accept=application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' 

Response payload

{ 
  "scope": "openid", 
  "token_type": "Bearer", 
  "expires_in": {number}, 
  "access_token": {string}
}

The field accesstoken in the response contains your token. The field expiresin will show you the remaining validity of your token, in seconds.

Single active access token
Within the context of a single application, you will only have a single active access token at any time. If you would request a new token using the above request message while the previously issued token has not yet expired, you will get back the previous token. To obtain a new one, revoke the old token; then generate a new one.

Code Samples
To help you getting started on implementing this authentication in your code, you can find some samples on our Github.

Revoking an access token

This procedure should be used when your token has been compromised (leaked, stolen, etc.), or if you want to generate another token, but your old token is still valid.

/revoke POST

Issue a request to https://api.enco.io/revoke, adding the following headers and payload:

Request payload

token=<old-access-token-to-be-revoked>&client_id=<app-consumer-key>&client_secret=<app-consumer-secret>

Creating permanent token

You can create permanent tokens from the "TOKEN" menu of your profile's dashboard. Just click on "Add a new token" to create a new permanent token. Several permanent tokens can be created for the same account.

Your permanent token is sensitive information; keep it private at all time!

Make sure to store your permanent tokens in a safe way, avoiding them to leak or be stolen by an unintended audience. They are quite sensitive, in that anyone obtaining them will be able to gain access to your assets. In case a permanent token would become compromised or not needed anymore, delete this token from your "TOKEN" dashbload by clicking on the red cross next to it.

All set to call your API!

Once a valid access token has been generated, it should be added to request messages. The token should be passed in an HTTP header named Authorization, which should be assigned the value of Bearer, followed by a single space, and immediately followed by the access token. Note the single space between ‘Bearer’ and the token.

curl -i -X GET -H "Accept:application/json" -H "Authorization: Bearer <active-access-token>" https://api.enco.io/lora4maker/0.0.1/device