1NCE Connectivity Suite

Documentation

Connectivity Suite - Functionality

General Informationen

The 1NCE IoT Connectivity Suite is an IoT Enablement Platform as an integrated part of the 1NCE IoT Flat Rate and free-of-charge for all 1NCE Customers.

We identified three significant challenges customers are facing while ramping up their IoT solutions.

 

  1. Device security and authentification

Unsecure device authentification in cloud and platform environments lead to time-consuming setup and bring very high complexity to solve them.

  1. Data protocol support

IoT platforms only offer limited support for IoT data protocols (e.g. only MQTT) and no support for low-data IoT protocols (e.g. CoAP).

  1. Device integration and management

First setup and configuration of devices require high efforts and is very difficult to handle especially for inexperienced users. Initial training is necessary and is driving cost.

 

Therefore, the 1NCE IoT Connectivity Suite is covering all three challenges and provides a true Plug & Play IoT experience.

The 1NCE IoT Connectivity Suite consists out of three main areas:

 

SIM-as-a-Identity

  • Our SIM-as-a-Identity allows a secure and reliable identification of devices based on the existing 1NCE SIM cards. Therefore customers are able to connect their own credential Providers (e.g. AWS) and 1NCE will map the identities to the individual IoT Devices using our SIM card securely. This will allow 1NCE the fully automated device onboarding for the AWS IoT Core. More details available at SIM as an Identity

Data Management

  • Our Data Broker is allowing customers to use various transport protocols supporting all IoT use cases equally. The 1NCE Data Broker is acting as a mediator between your IoT devices and your Enterprise Application (e.g. Analytics Solution, Mobile App etc.) to ensure fast and reliable data transformation. More details available at 1NCE Data Broker

Auto-Provisioning & Configuration

  • We provide a fully automated device provisioning for the AWS IoT Core where we automate all the required setup steps like Create Thing, Create Policy, Create Credentials and providing all the details to the desired IoT device. 1NCE is providing reference Blueprints and IoT device clients to seamlessly update different devices to use the service. More details available at 1NCE SDK
  • On top of the device provisioning, our Rules Engine allows easy and quick setup of processing flows to configure the Data Broker, enrich data with Cellular Connectivity Meta Data or basic data processing. More details available at 1NCE Rules Engine.

 

The Connectivity Suite can be used in conjunction with an AWS account.  All service regions of AWS are supported with the exemption of the following:

  • af-south-1 (Africa Cape Town) – IoT Policy not supported
  • ap-east-1 (Hong Kong) – Invalid parameter in the SQS policy
  • eu-south-1 (Europe (Milan)) – IoT Policy not supported
  • me-south-1 (São Paulo) – Invalid parameter in the SQS Policy

 

 SIM as an Identity

The SIM-as-an-Identity Solution is part of the 1NCE IoT Connectivity Suite and allows customers a seamless and fully automated device onboarding for the AWS IoT Core (other platforms will follow).

Customers who want to use this solution require an active AWS Account connection to be available in the 1NCE Customer portal. More detailed steps on how to set up and connect an AWS Account can be found in the 1NCE Rules Engine.

 

The Service will set up, create and configure device in the AWS IoT Core using a default Policy allowing devices to only connect to a device-specific topic using the 1NCE ICCID as ThingName in AWS.  A full example of the used Policy can be found below in the References. All Things are onboarding using the AWS Root CA.

The following picture shows a high-level flow of the Onboarding Flow:

 

Device API

The onboarding is triggered by each customer device by using our Device API during the device’s start-up/initialization phase.

A reference implementation for the service can be found at 1NCE SDK

 

API Documentation

Base URL: device.connectivity-suite.cloud

Protocol: HTTPS

 

/device-api/onboarding

GET

1. Parameters
Name Located in Description Required Schema
Accept header The Accept request HTTP header advertises which content types, expressed as MIME types, the client is able to understand.

Default: application/json
Other supported: txt/csv

No string
2. Responses
Code Description Schema
200 200 response Certificates
400 400 response BadRequestResponse
404 404 response NotFoundResponse
500 500 response ServerSideErrorResponse
503 503 response ERROR

 

3. Certificates

Certificates model

Name Type Description
certificate string Device Certificate for AWS IoT Core
privateKey string Device private Key for AWS IoT Core
amazonRootCaURL string URL to the AmazonRoot CA or the CA provided directly is Accept: text/csv
iotCoreEndpointURL string AWS Account region-specific AWS IoT Core Endpoint URL
ICCID string ICCID of the Device/SIM
4. ConflictResponse

API error response when a conflict is found

Name Type Description
statusText string Http status text
errors [ object ] Detailed error information

 

5. NotFoundResponse

API response when the resource is not found

Name Type Description
statusText string Http status text
errors [ object ] Detailed error information
6. ServerSideErrorResponse

API response in case of server-side errors

Name Type Description
statusText string Http status text
errors [ object ] List of errors encountered while calling the API

Example

The following example is an output using a regular curl request from a device with a 1NCE SIM Card

Request: curl –i –v https://device.connectivitiy-suite.cloud/device-api/onboarding

HTTP/2 200

server: awselb/2.0

date: Mon, 22 Jun 2020 14:26:15 GMT

content-type: application/json; charset=utf-8

content-length: 3156

etag: W/”c54-l8hc4And5ODwW2GDRbihJtLzNrI”

access-control-allow-origin: *

 

{

    “certificate”: “—–BEGIN CERTIFICATE—–\HERE_WOULD_BE_CERTIFICATE\n—–END CERTIFICATE—–\n”,

    “privateKey”: “—–BEGIN RSA PRIVATE KEY—–\HERE_WOULD_BE_KEY\n—–END RSA PRIVATE KEY—–\n”,

    “amazonRootCaUrl”: “https://www.amazontrust.com/repository/AmazonRootCA1.pem”,

    “iotCoreEndpointUrl”: “a259hu9tuXXXXX-ats.iot.eu-central-1.amazonaws.com”,

    “ICCID”: “898828066600000XXXX”

}

Security

Security is the highest focus for our Onboarding Service, therefore, we paired the regular AWS IoT Core Authentification using a X.509 certificate with our 1NCE SIM Card.

 

X.509 certificates provide AWS IoT with the ability to authenticate client and device connections. Client certificates must be registered with AWS IoT before a client can communicate with AWS IoT. A client certificate can be registered in multiple AWS accounts in the same AWS Region to facilitate moving devices between your AWS accounts in the same region. More details available at https://docs.aws.amazon.com/iot/latest/developerguide/x509-client-certs.html

The Service is providing an X.509 certificate generated by AWS IoT to the device during the onboarding.

 

1NCE is ensuring that each X.509 certificate can only be used in combination with a specific IoT Device by leveraging the 1NCE SIM as a secure element and using the 1NCE Core Network identity. Each SIM Card is authenticated by our Core network using Unique identifiers like IMSI, MSISDN and IMEI (if the IMEI Lock is activated by the customer). Additionally, we are also using the Static private IP Addresses used in our Core Network to identify and check each Data Package processed by the 1NCE IoT Connectivity Suite to validate authentification of the device.

 

References

AWS IoT Thing Policy

{

  “Version”: “2012-10-17”,

  “Statement”: [

    {

      “Action”: [

        “iot:Connect”

      ],

      “Resource”: [

        “arn:aws:iot:eu-central-1:954159388440:client/${iot:Connection.Thing.ThingName}”

      ],

      “Effect”: “Allow”

    },

    {

      “Action”: [

        “iot:Publish”,

        “iot:Receive”

      ],

      “Resource”: [

        “arn:aws:iot:eu-central-1:954159388440:topic/${iot:Connection.Thing.ThingName}/*”

      ],

      “Effect”: “Allow”

    },

    {

      “Action”: [

        “iot:Subscribe”

      ],

      “Resource”: [

        “arn:aws:iot:eu-central-1:954159388440:topicfilter/${iot:Connection.Thing.ThingName}/*”

      ],

      “Effect”: “Allow”

    },

    {

      “Action”: [

        “iot:Receive”

      ],

      “Resource”: [

        “arn:aws:iot:eu-central-1:954159388440:topic/${iot:Connection.Thing.ThingName}/*”

      ],

      “Effect”: “Allow”

    }

  ]

}

1NCE Data Broker

The core of the 1NCE IoT Connectivity Suite is a highly scalable Data Broker designed to process millions of messages in parallel extended by a range of Device Gateways to support different transport protocols.

Management and configuration of the Data Broker are handled via the Rules Engine in the 1NCE Customer Portal.

The main goal of the Data Broker is a to provide a range of Endpoints for different Data Protocols and be able to translate data to be able to forward it to Cloud Platforms like the AWS IoT Core.

 

Overview of Device Endpoints

The 1NCE Data Broker offers multiple Gateways and each customer device needs to be compatible with at least one of the following protocols to leverage all benefits:

Transport Protocol Endpoint Address Description
UDP udp://udp.connectiviy-suite.cloud:4445 Receive UDP packets from a device and process it for forwarding them to the specified cloud service
CoAP coap://coap.connectiviy-suite.cloud Receive UDP packets from a device and process it for forwarding them to the specified cloud service. Using CoAP default Port 5683

Further protocols (e.g. LwM2M) are in development and will follow soon.

UDP Endpoint

The UDP Endpoint receives packets sent by customers IoT devices, enriches them with identifier data form the Core Network and forwards data to the customers configured Backend Application via the Data Broker.

 

The Endpoint is listening on part 4445 by default. A simple script to send UDP packets to the server will look like this (generic example in NodeJS):

const dgram = require(‘dgram’);

const message = Buffer.from(‘Hello World’);

const client = dgram.createSocket(‘udp4’);

client.send(message, process.env.UDP_PORT_TEST || 4445, ‘127.0.0.1’, (err) => {

if (err) console.err(err);

client.close();

return ‘done’;

});

Alle aktiven SIMs einer Organisation mit einem angeschlossenen AWS-Konto können Nachrichten erfolgreich über den UDP-Endpunkt veröffentlichen.

Die eingehende Nachricht wird mit Kernnetzwerk-IDs angereichert und in eine JSON-Nachricht mit diesem Format umgewandelt:

{

“payload”: “incoming_udp_message_string”,

“timestamp”: “2020-02-19T12:33:00.000Z”,

“IMSI”: “123456789009876”,

“ICCID”: “34567895678967”,

“IP_Adress”: “100.91.200.5”

}

 

UDP Support for Binary Conversion

The 1NCE Data Broker offers Binary Conversion support based on the AllThings Talk Binary Conversion Language (ABCL). More details on the general conversion language available at https://docs.allthingstalk.com/dl/AllThingsTalk_Binary_Conversion_Language_1_0_0.pdf

The Binary Conversion allows customers to simply format Binary payloads and build also more complex logic into the conversion templates. Templates are provided via the 1NCE Rules Engine and applied to the desired Devices.

Let’s take the following example for a simple IoT Device with 2 Sensors one Input. A UDP Payload would look like this: 01 07 02 2b 00

As this is not readable let’s apply the following Conversion Template to the message:

{

“sense”: [

{

“asset”: “Temperature”,

“value”: {

“byte”: 0,

“bytelength”: 2,

“type”: “integer”,

“signed”: true,

“calculation”: “val/10”

}

},

{

“asset”: “Humidity”,

“value”: {

“byte”: 2,

“bytelength”: 2,

“type”: “integer”,

“calculation”: “val/10”

}

},

{

“asset”: “Switch”,

“value”: {

“byte”: 4,

“type”: “boolean”

}

}

]

}

 

This will result in a nicely formatted JSON message which is also human-readable:

{

“Temperature”: 26.3,

“Humidity”: 55.5,

“Switch”: false

}

 

Example Implementation for UDP Endpoint

The following example is based on our Blueprint for the PyCom GPy and uses MicroPython:

# -*- coding: utf-8 -*-

import usocket as socket

import config

from lib import logging

logging.basic_config(level=logging.INFO)

logger = logging.get_logger(“__main__”)

if __name__ == ‘__main__’:

message = “Hello, UDP. Can you hear me?”.encode()

logger.info(“Opening UDP Socket”)

s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)

addr = (config.UDP_ENDPOINT_IP, config.UDP_ENDPOINT_PORT)

logger.info(

“Sending UDP message to {}:{} with body {}”.format(

config.UDP_ENDPOINT_IP,

config.UDP_ENDPOINT_PORT,

message))

s.sendto(message, addr)

logger.info(“Sent UDP Message to the UDP Broker”)

 

UDP is the most lightweight transport protocol and can easily be based on a simple Socket connection as shown in the previous example.

 

Binary Conversion Language (BCL)

The goal of BCL is to provide an easy way of defining a schema for decoding freeform third-party binary payloads. A set of mappings in BCL specific to a device type is called a Conversion. Conversions are encoded as JSON objects

Example: Home alarm system

{

“name”: “alarm”,

“comment”: “Home alarm system”,

“version”: “1.0.0”,

“sense”: [

{

“asset”: “motion”,

“value”: {

“byte”: 0,

“bytelength”: 1,

“type”: “boolean”

}

}

]

}

In this example, we declare a Conversion used with a home alarm system device. When the device senses motion it sends one byte to <UDP endpoint>. This simple template converts one byte sent by the device into a JSON object with a boolean field motion.

When the device with enabled binary translation, sends 0x01 the byte gets translated into true resulting in the following object:

{

“motion”: true

}

Top-level fields

A Conversion MUST have a list field named sense, which contains statements that need to be evaluated during sensing – when de-serializing binary payloads into JSON objects.A Conversion MAY have a string field named comment, provided for human-readable description of the conversion.

Statements

Statements are JSON objects that describe a single operation that needs to be performed in a conversion. A statement MUST be either a mapping statement, a control statement, or a comment statement. Statements appear in statement blocks.

Statement blocks

Statement blocks are JSON lists whose elements are statements or statement blocks that need to be performed in order to complete the conversion. A statement block MAY contain no elements. Making a statement block empty is the same as omitting it altogether – no statements get executed. This can be useful in code generation.

There are two types of statement blocks: sense and do. sense statement blocks are executed when sensing (receiving data), and they are present in the home alarm example. do is used wherever embedding a statement block – usually within control structures – is needed.

Sense block

Sense block MAY contain mapping statements and control statements.

Mapping statements in sense block MUST contain a string field asset, whose value is a string that uses JSON dot-notation to identify the path to the field in resulting object.

Mapping statements in sense block MUST contain a field value, whose value is a selector that identifies the data that will be stored as the new value of the asset.

Mapping statements in sense block MAY have a string field named comment, provided for human-readable description of the given mapping.

Mapping statements

Mapping statements are used for de-serializing values and metadata from specific parts of binary payloads, special values, variables and constants into fields in the resulting JSON. Statement contains two fields:

asset – Path to resulting field using JSON dot notation

value – Constant or payload selector

Examples:

Inject a string field using constant selector.

{

“sense”: [

{

“asset”: “sensor”,

“value”: “motion”

}

]

}

Result:

{

“sensor”: “motion”

}

Convert 4 bytes into a 32-bit floating-point number using payload selector. Longitude from GPS beacon.

{

“sense”: [

{

“asset”: “longitude”,

“value”: {

“byte”: 0,

“bytelength”: 4,

“type”: “float”

}

}

]

}

Data: – 42 4b bc f9
Result:

{

“longitude”: 50.9345

}

 

Control statements

Control statements MUST have a JSON object field named switch that specifies payload selector that’s going to be evaluated, and its value tested in cases.

Control statements MUST have a JSON array field named on that contains a list of cases that switch value will be tested on.

Control statements are used for executing control logic that MAY lead to executing more statements. Switch is the only available control statement in this version of BCL.

Control statement MAY have a string field named comment, provided for human-readable description of the conversion.

Control statement on list MAY contain zero or more case statements.

Control statement on list MAY contain a comment statement.

 

Case statements

Case statement MUST have a JSON object field named case, whose value is a selector whose value is tested with the switch selector’s value in outer switch control statement. If its equal, do statement block is executed.

Case statement MUST have a JSON list field named do, whose value is a statement block that is executed if case and switch match.

Example

In this example payload’s first byte is a 8-bit integer that defines message type. Message type 0 is positional data

about the vehicle, and message type 1 is maintenance data.

Message type 0 has the following structure:

+——————————-+—————————-+——————–+

|            4 bytes           |         4 bytes          |     2 bytes    |

+——————————-+—————————-+——————–+

| Longitude (float) | Latitude (float)  | Speed (int) |

+——————————-+—————————-+——————–+

Let’s initialize the switch statement and create the condition for message type 0

{

“sense”: [

{

“switch”: {

“byte”: 0,

“bytelength”: 1,

“type”: “int”

},

“on”: [

{

“case”: 0,

“comment”: “Positional data”,

“do”: [

{

“asset”: “gps.lat”,

“value”: {

“byte”: 1,

“bytelength”: 4,

“type”: “float”

}

},

{

“asset”: “gps.lon”,

“value”: {

“byte”: 4,

“bytelength”: 4,

“type”: “float”

}

},

{

“asset”: “speed”,

“value”: {

“byte”: 8,

“bytelength”: 2,

“type”: “int”

}

}

]

}

]

}

]

}

Device sends the following data 00 42 4b bc f9 40 de 98 1c 40 5e

First byte 00 determines that this message contains positional data. The message will result in the
following object:

{

“gps”: {

“lat”: 50.934543,

“lon”: 6.95607

},

“speed”: 120

}

 

Selectors

Selectors are JSON values. They are used to “select” data from a given location type or “select” data used in a control statement.

Selectors MAY have a string field named comment, provided for human-readable description of the conversion

Constant selector

Constant selector is a string

 

Example

“foo”

 

Payload selector

Payload selector is a JSON object

Payload selector MUST have an integer field named byte, whose value represents the starting

byte from which the chunk is going to be selected.

Payload selector MAY have an integer field named bytelength, whose value represents the

length of the chunk in bytes, starting from and including the byte indexed by byte field. It

defaults to 1

Payload selector MUST have an integer field named type, which defined data type to which bytes should be converted.

Example

Select 16-bit integer

{

“byte”: 1,

“bytelength”: 2,

“type”: “int”

}

 

Supported data types

Numeric

bytelength is required

always use Big Endian endianness

int – signed integer. Can have bytelength 1, 2, 4, 8 which are 8-bit to 64-bit integers respectively. Defaults to 1

uint – unsigned integer. Same constraints as int

int and uint value ranges

uint8  : 0 to 255

uint16 : 0 to 65535

uint32 : 0 to 4294967295

uint64 : 0 to 18446744073709551615

int8   : -128 to 127

int16  : -32768 to 32767

int32  : -2147483648 to 2147483647

int64  : -9223372036854775808 to 9223372036854775807

float – floating-point number. Can have bytelength 4 and 8 which are 32-bit floating-point number and 64-bit double

percision floating-point number.

Boolean

boolean – boolean. 0x00 will be tread as false.

String

string – UTF-8 encoded string

 

Full example

Let’s now fully expand all the pieces that we’ve talked about in this document.

{

“sense”: [

{

“asset”: “message_code”,

“value”: {

“byte”: 0,

“bytelength”: 1,

“type”: “uint”

}

},

{

“switch”: {

“byte”: 0,

“bytelength”: 1,

“type”: “int”

},

“on”: [

{

“case”: 0,

“comment”: “Positional data”,

“do”: [

{

“asset”: “data_type”,

“value”: “Position”

},

{

“asset”: “gps.lat”,

“value”: {

“byte”: 1,

“bytelength”: 4,

“type”: “float”

}

},

{

“asset”: “gps.lon”,

“value”: {

“byte”: 4,

“bytelength”: 4,

“type”: “float”

}

},

{

“asset”: “speed”,

“value”: {

“byte”: 8,

“bytelength”: 2,

“type”: “int”

}

}

]

},

{

“case”: 1,

“comment”: “Maintenance data”,

“do”: [

{

“asset”: “data_type”,

“value”: “Maintenance”

},

{

“asset”: “on”,

“value”: {

“byte”: 1,

“type”: “boolean”

}

},

{

“asset”: “fuel”,

“value”: {

“byte”: 2,

“bytelength”: 4,

“type”: “uint”

}

},

{

“asset”: “driver”,

“value”: {

“byte”: 6,

“bytelength”: 4,

“type”: “string”

}

}

]

}

]

}

]

}

As before, this template parses two types of messages indicated by the first byte. In the beginning though there is a new mapping statement that adds message type to the resulting JSON. In the switch block a new statement is added to parse maintenance data.

Data: 01 01 00 00 05 8c 6f 6c 65 67

First byte is always mapped to message_code.

Field data_type is a constant selector that will be evaluated to Maintenance

0x01 -> 1

Message therefore should be parsed as mainenance data. We have already tried parsing Postitional data, the example can be found above.

Let’s explore how the switch statement will work in this case

Byte at position 1 is parsed as a boolean and mapped to on, which determines if the vehicle is powered on

0x01 -> true

Next, fuel level is parsed from four bytes starting at position 2 and mapped to field fuel. Fuel will be parsed as uint,

which is an unsigned integer, because fuel can’t drop below 0. Since 4 bytes is selected, the number will be parsed into 32-bit uint.

0x0000058c -> 1420

Driver name is then parsed as a string. Name is parsed from 4 bytes starting from position 6.

0x6f6c6567 -> “oleg”

We get the following result

{

“message_code”: 1,

“data_type”: “Maintenance”,

“on”: true,

“fuel”: 1420,

“driver”: “oleg”

}

1NCE Rules Engine

The Rules Engine as part of the 1NCE IoT Connectivity Suite allows customers seamless management of all settings and flawless configuration in the existing 1NCE Customer Portal.

 

The Rules Engine combines all administration task which need to be done one-time or updated. Possible configurations include:

 

  • Dashboard => Providing a simple overview of the Status of the 1NCE IoT Connectivity Suite and Onboarding Guides
  • Rules Engine => Creating and managing Actions to process data and connect with available Backend Applications
  • Account Connection => Managing Cloud Platform connections and SaaS Applications to deliver data and act as identity providers for the Onboarding Service.
  • Downloads => Overview of 1NCE provided software, SDK and Device Blueprints for use by the customer.
  • Documentation => Link to this documentation on the 1NCE Website.

 

Dashboard

The 1NCE IoT Connectivity Suite is part of the 1NCE IoT Flat Rate and fully free-of-charge, but it requires an additional Data Processing Agreement to be checked off by the customer. Therefore, the first screen which is shown when navigating to the Connectivity Suite in the Customer Portal is the Agreement Screen where an Owner or Admin of the Account needs to read and check the Data Processing Agreement.

The following screen shows how the page is looking:

After Accepting the agreement, the Connectivity Suite will be available for all other Users in the same Customer Organisation without any other checks.

 

The starting Page contains statistics and insights into the functions of the 1NCE IoT Connectivity Suite as well as an Onboarding Tour for new users to get familiar with the platform.

The Onboarding Tour can be started when clicking on “Take the Tour” and will guide through all required steps to get started.

 

Rules Engine

The Rules Engine allows the creation of different Actions to manage data flows. As part of the first Release, a limited amount of actions are available which can be activated and take effect for the whole Customer Organisation. Each action is listed in the Rules Engine and shows the Current Status. A new action can be added by clicking the “Create” button on the Page.

The menu for creating a new Rule is opening and a desired action can be selected. Depending on the action different settings are shown. In the example below an AWS Account need to be selected to create an action with the type “MQTT Bridge”. The AWS Accounts first need to be successfully added and connected in the Account Connection Page to be available for selection.

After saving the Action it will show up in the List of Rules and the Current Status is visible. Each Action can be deleted if it should not be running anymore.

The Rules Engine will get more active over time in order to support various processing steps for the data and be able to integrate into further Cloud Platforms as well as SaaS Solutions.

 

Account Connection

The Account Connection pages enable Customers to connect new Cloud Platforms to the 1NCE IoT Connectivity Page. Added an AWS Account is the first step to get started when using the Connectivity Suite. Securely connecting an AWS Account is simple and leverages an AWS CloudFormation Template to automatically set up all required resources and the cross-account connection to the 1NCE AWS Account. First, the name of the account needs to be added to be able to reference the connected account again. After naming the Account press “Connect” to start the connection process.

For ensuring the connection is desired a pop-up will ask for the confirmation and when clicking “Proceed” the AWS Console will open in a new Tag. Before clicking “Proceed” you should already be logged into AWS in the same Browser Session to allow a seamless forwarding.

After clicking “Proceed” the following page will open in a new tab showing the AWS Console with all Parameters prefilled. Proceed by clicking “Next” on the bottom right.

Additional optional configurations for the CloudFormation template will be shown. No changes are necessary but adding of Tags or other Notifications are possible. Continue to the last page by clicking “Next” on the bottom right.

On the last Screen of the CloudFormation Stack, you will be asked to acknowledge that the AWS CloudFormation Template might create IAM resource. All details on the Stack and the full code which is executed in the customer AWS Account is available on GitHub here https://github.com/1NCE-GmbH/customer-cloudformation-stack (- Connect to preview). Customers are able to check all the resources created by the Template also during the creation when the rollout out is finalized. Start the execution and connection by clicking “Create stack” on the bottom right of the page. After that customers can head back to the 1NCE Customer Portal. The connection will take a few minutes until fully done.

In the Account Connection page, you can use the “Refresh List” page to check the status of the connection. Sometimes it can take multiple minutes until fully done therefore allow up to 10 minutes until retrying again. As soon as the connection is successful you will see a new Account in the list with the label “new”.

AWS Accounts can also be added via the CLI for more advanced users. The required AWS CLI command is shown in the Portal when selection “via CLI”. Please enter a name for the account first and then copy and execute the provided command via an active AWS CLI session. A connected account will show up in the Account list after a few minutes.

All “Connected” Accounts are ready for further usage in the Rules Engine and the main Account with the Connection Type “Full integration” will be used to onboard all SIMs when successfully connected.

Downloads

The Downloads Page contains all available Resources a customer can use on his IoT Device or for manually connecting an AWS Account. Each listed Download has a small Description available and will link to the download itself. As seen in the Screenshot below the Downloads also contain the Device Blueprints or SDKs available for customers.

1NCE SDK

1NCE offers different Blueprints and SDKs to allow customers a seamless setup and use of all features as part of the 1NCE IoT Connectivity Suite.

Blueprints

PyCom

The Pycom onboarding blueprint enables a PySense, in combination with GPy, to communicate with the AWS IoT Core. This enables the functionality to subscribe and publish messages on the IoT Core, by making use of the SIM (IoT Device) specific certificates and keys.

All referenced Code is available on GitHub: https://github.com/1NCE-GmbH/blueprint-pycom

(- Connect to preview)

 

Prerequisites

Firmware

Before executing the onboarding blueprint on your PyCom device it is needed to upgrade the device to the newest firmware version. The firmware can be upgraded by following the steps below:

 

1NCE SIM

An activated SIM Card is needed before it is possible to execute the onboarding blueprint on your device. This is required to load in the needed certificates and keys to set up the connection to the AWS IoT Core on the device.

 

Configuration

The onboarding script configuration can be found in config.py in the root folder of the blueprint.

  • Onboarding Configuration
    • ON_BOARDING_URL: URL used to perform the onboarding call
    • API_GATEWAY_IDENTIFIER: Identifier used to route the request to the correct endpoint
  • IoT Core Configuration
    • CONN_DISCONNECTION_TIMEOUT: Connection disconnection timeout in seconds
    • MQTT_OPERATION_TIMEOUT: Connection time out to the MQTT IoT Core broker in seconds
  • File location Configuration
    • ROOT_CA_PATH: Root CA file path
    • PRIVATE_KEY_PATH: Private key file path
    • CERTIFICATE_PATH: Certificate file path

“”””

On boarding Configuration

“””

ON_BOARDING_URL = “https://<Address>/<stage>/devices/certificates/ip”

API_GATEWAY_IDENTIFIER = “<Gateway-ID>”

 

“”””

Iot Core Configuration

“””

CONN_DISCONNECTION_TIMEOUT = 10

MQTT_OPERATION_TIMEOUT = 5

 

“”””

File location configuration

“””

PRIVATE_KEY_PATH = ‘/flash/client.private.key’

CERTIFICATE_PATH = ‘/flash/client.cert.pem’

ROOT_CA_PATH = ‘/flash/root-CA.crt’

 

Examples

The blueprint consists of multiple example scripts for different use-cases, like publishing a message to the IoT Core. To run the chosen script on the device, the script needs to be renamed to main.py and located within the root directory of the /flash on the device.

 

The following test scripts are available:

  • Publish a message to an IoT Core Topic
  • Subscribe to an IoT Core Topic

 

Publish example (main.py)

Within the publish example script the following steps are executed:

  • Load in the configuration variables
  • Starts onboarding process
    • Retrieves device-specific configuration (Certificates, etc.)
    • Download the Root CA based on the given URL
    • Saves all keys and certificates to the local file system
  • Connect to the IoT Core with the given certificate, private key and Root CA certificate
  • Publish a Hello-world message on the <ICCID>/hello-world topic

 

Subscribe example (main_subscribe.py)

Within the publish example script the following steps are executed:

  • Load in the configuration variables
  • Starts onboarding process
    • Retrieves device-specific configuration (Certificates, etc.)
    • Download the Root CA based on the given URL
    • Saves all keys and certificates to the local file system
  • Connect to the IoT Core with the given certificate, private key and Root CA certificate
  • Subscribe on the <ICCID>/hello-world topic

 

Code

Network connector (network_connector.py)

Functions

Attach (_attach)

Attaches to the LTE network (1nce.iot.net)

Connect (connect)

First attaches and then connects to the LTE network

Disconnect (disconnect)

Disconnects from the LTE network,

Get reception (get_reception)

Gets the current reception to the LTE network.

 

Onboard Service (onboard_service.py)

Variables

  • endpoint: Onboard service endpoint URL, like https://<Address>/<stage>/devices/certificates/ip
  • api_gateway_id: Unique identifier for the API gateway
  • private_key_path: Private key file path
  • certificate_pem_path: Client certificate file path
  • root_ca_crt_path: Root CA certificate file path

 

Functions

Onboard (on_board)

Onboards the device by getting the needed variables to connect to the IoT Core.

Get device information (_get_device_information)

Gets the device information from the onboarding endpoint.

Save data (_save_data)

Saves the data (certificates & keys) to the local file storage.

Save private key (_save_private_key)

Saves the private key to the local file storage.

Save certificate (_save_certificate_pem)

Saves the client certificate to the local file storage.

Save Root CA certificate(_save_root_ca_crt)

Saves the root CA certificate to the local file storage.

 

Root CA Certificate Downloader (download_root_ca.py)

Variables

root_ca_url: Root CA URL, like https://www.amazontrust.com/repository/AmazonRootCA1.pem.

 

Functions

Download (download)

Downloads the Root CA.

 

AWS IoT Controller (aws_iot_controller.py)

Variables

  • endpoint: Endpoint URL to the IoT Core, like:<IoT_Core_ID>.<AWS_region>.amazonaws.com
  • client_certificate: Client certificate path (.pem).
  • private_key: Client private key path (.key)
  • root_ca: Root CA path (.crt)
  • client_id: Client identifier for the IoT Core, this is the ICCID of the used SIM.
  • conn_disconnect_timeout: Connection disconnect time-out, in seconds, to the IoT Core.
  • mqtt_oper_timeout: Time-out for operations to the IoT Core MQTT broker

 

Functions

Initialize (initialize)

Initialize and connect to the IoT Core. The following steps are executed within this method:

  • Configure the endpoint URL
  • Configure the credentials, based on the set certificates and keys
  • Configure the different timeouts
  • Connect to the IoT Core

Subscribe (subscribe)

Subscribe to an IoT Core Topic. Received messages will then be logged to the console via the _on_message_received method.

Publish (publish)

Publish a message to an IoT Core Topic, these topics have the following structure: <ICCID>/*, where * is the topic name that was passed to the method.

Disconnect (disconnect)

Disconnect the device from the IoT Core.

On message received (_on_message_received)

Handler to process message(s) that are received on a specific topic. It processes incoming messages and logs them to the console.

 

STM32 with Quectel BG96

FreeRTOS cellular is an implementation of Amazon FreeRTOS with cellular connectivity using BG96 modem.

Required Hardware

To install our project you will need:

  • B-L475E-IOT01A2 STM32 Discovery kit IoT node connected to BG96 (LTE Cat M1/Cat NB1/EGPRS modem) through X-NUCLEO-STMODA1 expansion board

Required Software

 

Prerequisites

  • Upgrade the modem BG96 to the latest firmware. (see the upgrade tutorial in GitLab)
  • Create an IoT thing in AWS IoT core and download the client key and certificate in addition to the root certificate.

 

Modem Setup

  • two USB connection are required, one to the board and another one to the modem.
  • The board will appear in the devices manager as follows.

  • Run QCOM and connect to the Quectel USB AT Port

  • Select the certificate file and check the size in bytes (!!!! be careful about this !!!)

  • execute the following AT command:

AT+QFUPL=<” filename”>, <size in bytes>, <timeout>

The modem should reply with “CONNECT”, then click “Send File” to upload the certificate.

  • Repeat the same steps for the client certificate and client key.
  • Make sure that the certificates are uploaded with the command AT+QFLST

 

STM32 Setup

  • Import the project

Choose the Existing project into Workspace and click Next.

Click browse and select the folder FreeRTOS cellular, a project with the title “aws_demos“ should be listed, then click Finish.

  • Edit the following parameter in config_files/demo_config.h :
    • clientcredentialMQTT_BROKER_ENDPOINT[] = “url of end point”;
    • clientcredentialIOT_THING_NAME “name of the thing in AWS IoT Core”
    • clientcredentialMQTT_BROKER_PORT “MQTT Port”
  •  Debug the code.

  • Open a console on MPU Serial Device.