Altair SmartWorks 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 SmartWorks Platform via automated processes.
- Massive Registration Scenario
- Automated Provisioning via the Altair SmartWorks API
- Expand your manufacture process by using the Altair SmartWorks API
- Automated Provisioning via Data Streams + Listener
- Expand your manufacture process by using Data Streams + Listener
- Generate your streams
- Build a Listener to process your Data Streams
- Provisioning Best Practices
The scenario is the following: your company builds IoT devices which are provisioned in the Altair SmartWorks Platform at the very same factory via automated processes.
- Massive provisioning scenario
- 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 SmartWorks Platform. In order to do this, your stuff connects to your server in charge of managing the Altair SmartWorks API requests. In this server you must have a software routine that obtains all the devices information needed to be provisioned into the Altair SmartWorks Platform and which is capable of requesting the devices provisioning to the Altair SmartWorks API (one request per device).
By now, you should have created a Altair SmartWorks 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 SmartWorks 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 SmartWorks 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 SmartWorks API (REST web service): The software routine must be developed to make REST requests to the Altair SmartWorks API for device provisioning. See https://www.altairsmartworks.com/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 SmartWorks Platform, via the Altair SmartWorks 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();”):
- 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 SmartWorks Platform. In order to do this, your stuff connects to your server in charge of managing the data deliveries to the Altair SmartWorks 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 SmartWorks Platform and will trigger a Listener, programmed by you, which will be in charge of provisioning the devices into the Altair SmartWorks Platform.
As mentioned in previous section 2.1.1, the automated provisioning of your devices into the Altair SmartWorks 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 SmartWorks API".
2.- Obtain the devices data from your DB server: Same step as described inside section "Expand your manufacture process by using the Altair SmartWorks API".
3.- Send Data Streams to Altair SmartWorks: 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 SmartWorks 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 SmartWorks must specify the Altair SmartWorks 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 SmartWorks:
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 SmartWorks for this example should look like this:
We have enhanced the listener creation process with our Flow Tool.
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"
Switch node: the first node would be a "switch" node configured with the if expression:
(As our devices send provisioning streams cointaining those two keys)
- Switch node
- Function node: The Groovy or Java code to be included in the function node 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:
- Function node + connections
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
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 SmartWorks Agent and use it as a base project for your firmware. This agent is prepared to subscribe to a Altair SmartWorks 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.