Altair SmartCore Provisioning Use Case: Massive Registration

This document is focused on a specific provisioning use case: massive registration, which resumes the steps and needs to meet so that your devices can be registered within the Altair SmartCore Platform via automated processes.

Massive Registration Scenario

The scenario is the following: your company builds IoT devices which are provisioned in the Altair SmartCore Platform at the very same factory via automated processes.

  • Massive provisioning scenario

Automated Provisioning via the Altair SmartCore API

  • Provisioning via API scenario

In this use case, the simplest possible, your information system keeps tracked all the IoT devices being built at your factory. After running your quality control tests, the devices are ready to be provisioned into the Altair SmartCore Platform. In order to do this, your stuff connects to your server in charge of managing the Altair SmartCore API requests. In this server you must have a software routine that obtains all the devices information needed to be provisioned into the Altair SmartCore Platform and which is capable of requesting the devices provisioning to the Altair SmartCore API (one request per device).

Expand your manufacture process by using the Altair SmartCore API

By now, you should have created a Altair SmartCore account, located your Apikeys and be ready to develop the implementation for this solution.

Your devices manufacture process must be capable of keeping track of the devices information. This means all the devices info is stored, for example, in a DB server, and it can be accessed by a software program inside your information system. This software must be capable of executing a routine which can do REST web service requests to external APIs.

The automated provisioning of your devices into the Altair SmartCore Platform will be as simple as:

1.- Order the automated provisioning process to start: this can be programmed as a server task, with no human interaction needed. For example, after the quality control tests, 99% of your devices are marked as OK in your DB. You can add a SW routine, in your workflow, that checks if there are devices ready to be provisioned into the Altair SmartCore Platform after running the quality tests.

2.- Obtain the devices data from your DB server: the software routine requests the devices data to the DB server.

3.- Request the provisioning of each device via Altair SmartCore API (REST web service): The software routine must be developed to make REST requests to the Altair SmartCore API for device provisioning. See https://www.altairsmartworks.com/smartcore/developers/documentation/api/device_management#devices. If you download our Java SDK, you can also use the following lines of Java code to provision a device into the Altair SmartCore Platform, via the Altair SmartCore API:

The log printed by the previous code, in case the device provision was successful is:

The log printed by the previous code, in case the device provision was not successful, could be like this:

The reason why the provision was not made is printed in the log as the error message “details”.

In addition, the following lines can be used to confirm the device has been provisioned successfully (place them right below the line “newDevice.create();”):

Automated Provisioning via Data Streams + Listener

  • Provisioning via streams + listener scenario

In this use case, an evolution of the case explained in section 2.1.1, your information system keeps tracked all the IoT devices being built at your factory. After running your quality control tests, the devices are ready to be provisioned into the Altair SmartCore Platform. In order to do this, your stuff connects to your server in charge of managing the data deliveries to the Altair SmartCore Platform.

The big difference, comparing this solution to the previous one, is you can order the provision of several devices with one request. How can you achieve this? Simply by turning your devices information into a JSON and sending it as the payload of a Data Stream. This stream will be registered in the Altair SmartCore Platform and will trigger a Listener, programmed by you, which will be in charge of provisioning the devices into the Altair SmartCore Platform.

Expand your manufacture process by using Data Streams + Listener

As mentioned in previous section 2.1.1, the automated provisioning of your devices into the Altair SmartCore Platform will be as simple as:

1.- Order the automated provisioning process to start: Same step as described inside section "Expand your manufacture process by using the Altair SmartCore API".

2.- Obtain the devices data from your DB server: Same step as described inside section "Expand your manufacture process by using the Altair SmartCore API".

3.- Send Data Streams to Altair SmartCore: In this case, the software routine running in your server must be developed to package the devices information into one or several Data Streams. Due to the Data Stream size is limited (See Altair SmartCore pricing and look for ”Max. stream size”), this will depend on:

  • How many devices are being provisioned.
  • How much info they contain.

We recommend to use the HTTPS protocol to send your streams. In addition, the Data Stream being sent to Altair SmartCore must specify the Altair SmartCore Stream Protocol v3 (read "Protocols and checksums" documentation). We have developed a Java Agent to help with this task. In this agent there is a set of classes containing functions to send data streams to Altair SmartCore:

Generate your streams

The data in the data stream sent by the routine running in your server for this example should look like this:

So the whole data stream would be like this:

The data stream received by Altair SmartCore for this example should look like this:

Build a Listener to process your Data Streams

The streams are processed by entities called Listeners, so you can create a specific listener just for provisioning and only for that. See our tutorial "How to create a listener" for more information.

In this case, we recommend to include a [key,value] pair in the JSON object with the key, for example, called “operation” and the value “massiveRegistration”. Then, in your listener dedicated to massive provisioning tasks, you can check whether this key exists and if its value is “massiveRegistration”. Every listener must have a condition in order to be run, so this acts as a filter in order to this listener, and only this listener, runs the code needed for registering your devices into our platform.

A typical provisioning listener would contain:

  • Entity type: "Device"
  • id: "deafultDevice@exampleuser.exampleuser"
  • Event: "Event Sream Data Received"
  • If expression: "context.data.containsKey('operation')&&context.data.containsKey('massiveRegistration')"

In this case, we recommend to include a [key,value] pair in the JSON object with the key, for example, called “operation” and the value “massiveRegistration”. Then, in your listener dedicated to massive provisioning tasks, you can check whether this key exists and if its value is “massiveRegistration”. Every listener must have a condition in order to be run, so this acts as a filter in order to this listener, and only this listener, runs the code needed for registering your devices into our platform.

  • Then expression: The listener code, filled in the field “Then expression”, checks if the devices info is contained in the stream payload. If so, the listener uses a loop to iterate over the list of devices. Each device’s id must be checked in order to control we are not provisioning devices that were already registered in the platform. If so, an alarm is created; else, the listener fills a new Device object with the corresponding info and creates it:

The first time we send our provisioning data stream, the devices are created:

  • Devices created

If we try to create the devices again, by sending the same devices information, the alarms are created:

  • Alarms created

Provisioning Best Practices

Every device name must be unique. Our recommendation is using a device's attribute that makes it unique. Examples:

  • The device M.A.C. address (this can be obtained from the WIFI or the ethernet chip).
  • The ICCID (Integrated Circuit Card Identifier, that can be obtained from SIM the card, in case your device uses mobile technology).
  • The device serial number. This implies the device manufacturer must include this serial number in a file inside the firmware, so that the firmware can read it.
  • Any other mechanism that lets you dynamically read or compose a unique attribute which can act as a unique identifier.

Avoid using your Full Privileges Apikey inside your stream delivery routines. Use your Automatic Apikey Stream Only instead.

Download the Altair SmartCore Agent and use it as a base project for your firmware. This agent is prepared to subscribe to a Altair SmartCore MQTT topic and send data and status streams in a few steps, so you can focus on developing your firmware, saving integration time. If the agent is not available in your preferred programming language yet, you can still use it as a reference to implement your code.