NB-IoT overview

What is NB-IoT?

NB-IoT (Narrowband-IoT) is a narrowband radio technology based on 4G for Internet of Things (IoT) devices and applications providing improved indoor coverage and support for an important amount of low throughput devices. All this at lower power consumption and costs.

NB-IoT applications are a solution for small data volume amounts to be infrequently transmitted indoor with focus on following aspects:

• Lower power usage: will decrease project costs in case battery powered hardware is used that require to work for a long time without a battery replacement.
• Better indoor/underground penetration capabilities: A NB-IoT base station cell can support thousands of devices using an NB-IoT connection. This is for example particularly interesting for smart building management where many smart meters are installed in a basement.
• Improved security: As CoAP uses an UDP protocol rather than a TCP protocol, encryption is most commonly accomplished using Datagram Transport Layer Security (DTLS). The DTLS protocol provides communication privacy for datagram protocols which allows client/server applications to communicate in a way to prevent eavesdropping, tampering or message forgery.

More information about Proximus Narrowband-IoT is available on our corporate website.

What can you do with the NB-IoT API and CloudEngine?

The NB-IoT API allows you to send downlink messages to the NB-IoT devices. When the NB-IoT device data is send to CloudEngine then you can use the Powerful scripting capabilities, a variety of inbound and outbound endpoints and make use of the other Proximus API assets. This will allow you to create any kind of IoT application.

More information about CloudEngine is available via this link Proximus API website.

How to subscribe to the NB-IoT API?

Important prerequisite

Activation of a subscription can be requested via the "pricing" tab below.

We will come back to you to complete the registration process.

What are the options that Proximus offers for NB-IoT?

As a customer there are 3 ways to use NB-IoT.

• 1. Via CloudEngine (described here on this documentation page).
• 2. Connectivity only via Proximus M2M. You require a Proximus M2M account and a public or private APN that sends the NB-IoT data directly to your endpoint / application. Please contact info.m2m@proximus.com if you want more information.
• 3. Via an IoT solution. Please contact iot@proximus.com if you want more information.

Getting started

Prerequisites

Before setting up a NB-IoT flow, the following is needed:

• A Proximus M2M account where you can order 4G enabled M2M SIM cards. These SIM cards need to be provisionned with the APN: iot.prx.be and in the activated state with an MSISDN assigned (note: that iot.prx.be APN is not availble by default and should be requested to Proximus during the account setup). The MSISDN (Mobile Station Integrated Services Digital Network) of a SIM card is needed because a mapping between the MSISDN (phone number) and the IP address of the NB-IOT device(s).
• A Proximus API account with an active subscription on NB-IoT, on CloudEngine and optionally also on SMS if some information needs to be sent via SMS
• At least one NB-IoT device having the ability to connect using the User Datagram Protocol ( UDP )
• And for the downlink API you need to have an application that can work with the OAuth2 access token from the API Solutions account.

Proximus M2M Account

When you have an account on the Proximus Machine-to-machine (M2M) platform you will be able to order M2M SIM cards and manage them (activate, deactivate, …).

In order to get access or to get more information, please contact following mailbox: info.m2m@proximus.com

Proximus API Account

When you have an account on the Proximus API you also need to activate the CloudEngine subscription here.

Downlink

The downlink endpoint will allow you to send messages to an NB-IoT device.

When a message is sent, the downlink adapter will:

• 1. Check whether the caller owns the specified MSISDN
• 2. Look up the IP address for that MSISDN
• 3. Decode the provided hex payload
• 4. Send the payload to the device in binary format

Downlink will only work if a device is known on the radius (if it has an active connection to the network). When the downlink API is invoked with an MSISDN for which no active session is recorded in the radius DB; the application won't send the message. The network will cache downlink packets if a device is in sleep mode; if it can't be delivered it is lost.

Sample request

POST https://api.enco.io/nbiot/1.0.0/downlink
{
    "msisdn": "string", The MSISDN of the IoT device
    "payload": "string", The hex-formatted payload to send to the device
    "port": "integer", The port number to send to
}

An http 200 OK is returned if the message was delivered.

Uplink

The endpoints for CloudEngine UDP or COAP data were split up based on IP and ports in the same subnet; leaving only a single APN to be used: iot.prx.be.

CloudEngine

CloudEngine is a scripting language making it possible to design event flows. These events can be ingested from various sources such as HTTP, MQTT, LoRaWAN, SMS and the processed data rerouted through HTTP, MQTT, SMS, Mail & SMTP, etc.

All necessary information on how to set up basic CloudEngine flows can be found at this place.

An example on how to integrate with NB-IoT can be found in chapter NB-IoT CloudEngine flow.

The CloudEngine flow

The messages sent to CloudEngine are triggering a script using following tag structure:

• DATA: a static tag identifying the origin of the event.
• ip address: the IP address of the device sending the data packet
• msisdn: the MSISDN of the device sending the data packet

Data packets sent are using following data objects:

• PAYLOAD: binary "the RAW UDP Packet"
• timestamp: integer "the timestamp the packet was received in milliseconds since epoch"
• msisdn: string "the msisdn of the device sending the packet"
• coapParams: JsonObject "the CoAP parameters of the received CoAP message. This will be empty when this message was not a Coap message"

NB-IoT CloudEngine flow

Messages sent by NB-IoT devices can be used to trigger CloudEngine scripts.

Below an example of a device sending messages to CloudEngine triggering a specific script using the corresponding tags.

It could be used for example to forward some information on humidity levels via our SMS API.

More details on the CloudEngine platform can be found in chapter Getting started.

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" \
-H "Content-Type: application/x-www-form-urlencoded"

Response payload

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

The field access_token in the response contains your token. The field expires_in 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" dashboard 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 POST \
-H "content-type:application/json" \
-H "Authorization: Bearer <active-access-token>" \
-d '{"msisdn": "<string>","payload": "<string>","port": "<integer>"}'  \
'https://api.enco.io/nbiot/1.0.0/downlink'