Production Templates

Production Templates are a critical component in the lifecycle of of connected products. They are required to create and provision production devices.

This guide will teach you to create, configure, manage and provision Production Templates and it has the following content:

  1. Overview of Production Templates.
  2. Creating Production Templates.
  3. Production Templates Management and Properties Consoles.
  4. Configuring Things Properties, Security, Triggers and Applications.
  5. Configuring the Production Things Enroll Credentials.
  6. Provisioning Production Things.
  7. Deleting Production Templates.
  8. Creating Tokens for Programmable Generation of Serial Numbers and enroll credentials.

Overview

Production Templates are used to create and provision Production Things. A Production Template defines a class or model of a product. Based on that class, multiple similar Production Things can be provisioned and connected to CloudPlugs IoT.

A simple example would be that we want to create connected refrigerators. We create a Prototype called refrigerator. From it, we create Production Template and we call it White. So now we have a class of refrigerators called White. We will then produce 1,000 White refrigerators each of which will be a Production Thing. We could make a second Template from the same Prototype and call it Silver to produce and connect 2,000 Silver refrigerators.

Production Templates set the credentials (serial number or hardware ID, enroll password and an optional control password) required by Production Things to enroll in the platform.

Optionally, Production Templates can set properties, control permissions, triggers, control applications, SmartPlug Apps and Containers that will be automatically configured in the Template’s Production Things once they enroll into the platform. These can later be customized for individual Things if required.

Production Templates provide a simple way to provision configuration, triggers and applications to their Production Things before or after they have enrolled into CloudPlugs IoT. For example, if you develop a new control application, SmartPlug App or Container and you want to deploy them to all the Things belonging to a Template, you simply add them to the respective provisioning panel(s) of the Template and when you Save the Template, they will be automatically deployed to its Production Things.

Creating Production Templates

The Templates are created by using the Create Production Template () button of the Prototype management console, or the Create Production Template () button in the bottom ribbon of the Prototype Properties Console. When the Templates are created, the platform assigns to them a unique Plug-ID that always start with “mod-”.

Production Templates cannot be created by any means other than through their Prototypes.

When Production Templates are created, they inherit the following from their Prototypes:

  1. Name.
  2. Additional Properties.
  3. Triggers.
  4. SmartPlug Applications.
  5. Containers

The Name, Properties, Triggers, SmartPlug Applications and Containers can be edited and modified as required on the Template. In addition to these elements, Production Templates contain the list of all applications built with the Control Designer that use the Template. All or part of these elements can then be associated with the Template’s Production Things and, every time they are modified and saved, all the Template’s Production Things will be automatically updated with the changes.

Production Templates are managed through the Production Templates Management Console, and they are configured and modified through their Properties Console.

The next section describes the consoles in detail.

Back to Top

Production Template Consoles

This section describes:

  1. The Production Templates Management Console, and
  2. The Production Template Properties Console.

Production Templates Management Console

The Production Template’s Management console is opened by clicking on the Production Templates tile ( ) in the platform’s web desktop.
The console displays all Production Templates available and it allows operations to Open, Delete and Clone Templates as well as to navigate across pages when the number of Templates exceeds a single page.

  1. Open () opens the selected Template’s Properties Console.

  2. Delete () deletes the selected Template. Deleting a Template requires a few steps. For details on how to do this, please refer to the delete a Production Template section of this guide.

  3. Clone () duplicates the selected Template and it appends a #1, #2, etc. number to the Template’s name.

The Production Template Management Console shows the:

  • Template Name.
  • The Plug-ID of the Production Template.
  • Notes. Any notes that you have added to the template.
  • Re-enroll, which indicates whether the Template’s Production Things will be allowed to re-enroll or not.
  • SmartPlug Apps that will be, or have been deployed on the Template’s Production Things.
  • Triggers indicates how many triggers are programmed in the Template.
  • Serial Numbers indicates the number of serial numbers created and managed by the template.
  • Enrolled displays the number of serial numbers enrolled in the platform.
  • Secret Key indicates whether a Secret Key was used to generate the Production Thing’s Enroll and Control passwords.
  • Created indicates the date that the template was created.

The columns displayed can be set using the column filter accessible from the column drop down menus. Columns such as Created also allow filters to select specific date ranges.

Templates Management Console

Back to Top

Production Template Properties Console

Just like Prototypes, Production Things and Controllers, the Production Templates have a console to view, edit and manage its features and parameters.

To view the Properties Console of a Template:

  1. Select a Template from the Management Console.
  2. Open the Template by Double-clicking on it, or with the Open (Open) button.

The main elements of the Properties Console are:

  1. General (General) which includes:
  1. Device Profile (Device Profile) features and settings.
  2. Triggers (Triggers), which allows the programming of triggers to be deployed on all the Production Things of the Template.
  1. **Ctrl Apps which are HMI’s or Dashboards built with the Control Designer and associated with the Production Template.
  1. SmartPlug Apps (SmartPlug Apps), which allows to provision SmartPlug and Container applications to be deployed on all the Production Things of the Template.
  2. Serial Numbers (Serial Number), which allows to input the Production Things serial numbers or hardware ids, and Enroll and Control passwords for the Production Things of the Template.

For details on each section, click on the respective links.

Back to Top

Configuring Properties, Security, Triggers and Applications with the Properties Console

Production Template properties are set through the Template’s Properties Console. This section describes how to configure:

  1. Properties, through the Production Template Profile (Device Profile) panel.
  2. Security through the Permissions panel of the Profile panel.
  3. Triggers through the General -> Triggers (Triggers) panel.
  4. Control Applications through the General -> Control Applications (Control Applications) panel.))
  5. SmartPlug Applications through the SmartPlug Apps (SmartPlug Apps) panel.
  6. Containers through the Containers (![Containers])(/kb/images/user_guide/general_images/containers-icon.png =28x)) panel.

As Production Things enroll, they will be configured with the parameters and applications programmed in their Production Template. Parameters and applications for individual Things can be modified after they enroll either through the Things Properties Console or through Bulk Actions.

Back to Top

Production Template Profile

The Production Template Profile includes 3 sections as shown in the image below:

  1. General Properties.
  2. Additional Properties which are inherited from the Template’s Prototype and can be modified.
  3. Permissions.
Prod Template Profile

The following sections describe the Production Template General Properties, Additional Properties and Permissions.

Back to Top

General Properties

The Production Template Template General Properties include:

  1. The image (optional) for the Production Things General Properties Console. It allows to load an image of your production devices. The image can be changed or cleared with the Change and Clear buttons. This image is inherited by all the Production Things belonging to the Template.
  2. Name, which by default is the name of the Template’s Prototype. It can be changed while there are no Production Things enrolled.
  3. Plug-ID. The Production Template’s unique identifier assigned to it by the platform. Template Plug-ID’s always start with mod- unlike Prototypes, Production Things and Controllers whose Plug-ID’s start with dev-.
  4. Notes. Any notes you want to add to your Production Template.

Here is an example of a Production Template before and after an image has been added.

Initial Template from Prototype CP-Demo Template CP-Demo with an image for its Things
Production Template Profile2 Production Template Profile1

Back to Top

Additional Properties

The Production Template inherits its Additional Properties from its Prototype. They can be modified and you can set any additional properties that will be relevant for the Template’s Production Things as indicated in the Additional Properties Guide. When Production Things are provisioned, they inherit the Template’s Additional Properties. Individual Thing Properties can be also modified using the Thing’s Properties Console once it has enrolled and connected to the platform.

Back to Top

Permissions

There are two types of permissions for Production Things that need to be set by the Production Templates:

  1. Re-enroll permissions, which indicate whether a Production Thing can be re-enrolled in case it ever loses its enrollment.
  2. Control Permissions which determine if Control applications will have:
    • No permissions to access the device’s data and metadata.
    • Read only permission which allows the controller to:
    • Read data published by a Thing.
    • Read the properties of a Thing.
    • Enable a Thing to access the data published by the controller.
    • Read/Write permission which allows the controller to:
    • Overwrite the properties of a Thing.
    • Modify data already published by a Thing.
    • Publish data as if it was a Thing.
    • Delete data published by a Thing.

The Permissions panel also allows to use Secret Keys to automatically generate Enroll and Control passwords as explained in the next section.

Back to Top

Secret Key

When there are lots of Things to be provisioned and, therefore, many enroll and control credentials to create and input, a Secret Key can be be used to have the platform generate enroll and control  passwords for Production Things in a Production Template.  Each Production Thing serial number entered will be automatically assigned enroll and control passwords.

Secret keys make the creation of large numbers of enroll and control passwords for Things easier.  For example, if you have 10,000 Things to enroll, it would be time consuming and prone to mistakes to manually enter the passwords for each one. A Secret Key will instruct the platform to generate the passwords for you in milliseconds.

The enroll passwords produced are unique for each Production Thing and are generated as a combination of the Secret Key and the individual Things serial numbers. The Control passwords generated use a different algorithm than the one used for enroll passwords for security reasons.  Therefore, each Secret Key produces a set of two different passwords for each serial number in a Production Template.

Secret Keys are not mandatory, but it is a best practice to use them to ensure secure enrollment of your Things.  They need to be at least 8 characters long.

IMPORTANT!

Secret Keys can be changed as long as there are no serial numbers enrolled. If the Key is changed, you must Save the Production Template for the change to become effective. In addition, any devices that have already been programmed with Enroll and Control passwords generated by that Key will need to be updated. If a single serial number is enrolled using the previous Secret Key, the Key is no longer modifiable.

CloudPlugs provides the hash algorithm to customers that want to automate the programming of enroll credentials in their devices. For example, if you have a production line that is automatically installing the OS and applications or firmware and configurations into your devices, the hash algorithm with the Secret Key used in their Production Template can be used to program the enroll and control passwords in your devices.

The following images show a Production Template’s Profile that uses a Secret Key, but has no Production Things enrolled yet, and one in which no Secret Key was used, but has enrolled serial numbers. Notice that in the one with enrolled Things, the Template’s Name is not editable and there is no longer an option to enter a Secret Key.

Secret Key used and no serial numbers enrolled No Secret Key used and at least one serial number enrolled
Production Template Profile2 Production Template Profile1

Back to Top

Production Template Triggers

Production Template triggers are configured in the exact same way as those for Prototypes, Production Things and Controllers. For details on how to configure triggers, refer to the Triggers Guide.

Back to Top

Production Template Control Applications

Production Templates allow to provision control applications built with the Control Designer to all their Production Things.

When an HMI or dashboard application is built with the Control Designer, it must have a Production Template associated with it. A Production Template will list as available Control Applications for deployment to its Things all the Control Designer applications that are associated with it. To provision Control Applications to the Things in a Production Template:

  1. Open the desired Production Template from the Production Template’s console.
  2. Select Ctrl Apps from the left panel menu under General.
  3. Select one or more control applications from the Control Apps for this Template list. To select more than one, simply Shift and Click the additional applications.
  4. Drag and Drop those applications into the Control Apps Provisioned to Things panel. If you want Viewer accounts to be able to see the control applications in the console of the Things that belong to the Template, also drag and drop them into the Allow “Viewer” Accounts to see these Control Apps panel.
  5. Save ( Save ) or Save and Close ( Save and Close ) the Production Template to initiate the provisioning of the control apps to its Production Things.

The example below displays a number of Control Designer applications associated with the Template CP-Demo with 2 applications for its Production Things and one for Things in Viewer accounts.

Control Apps

Note that the only way to remove inherited control applications from Production Things is to remove them from the Control Apps Provisioned to Things panel in the Production Template. Control apps removed in this way will be removed from all the Things that belong to the Template.

Back to Top

Production Template SmartPlug Apps

Production Templates can have any number of SmartPlug™ applications associated with them if their Production Things will be running a SmartPlug™ IoT agent. The SmartPlug Apps tab ( Apps ) which enables to associate application scripts with the Production Template Things is accessible on the side menu bar when SmartPlug is selected on the top ribbon of the Production Template Properties Console as shown below.

SmartPlug Apps 1

All the currently available applications in the SmartPlug App Store can be provisioned by the Production Templates. If the application list has been changed in the SmartPlug Apps store (SmartPlug Apps), the reload (Reload) command will refresh the list.

For details on how to provision applications on Templates, refer to the Provisioning SmartPlug Apps through a Production Template Guide.

All Production Things associated with the Production Template will automatically inherit the SmartPlug Apps configured in the Production Template.

Note that the only way to remove inherited SmartPlug Apps from Production Things is to remove them from the Production Template. SmartPlug Apps that are removed from the Production Template panel will then be removed from all the Production Things associated with the Template.

Clicking on Save ( Save ) or Save and Close ( Save and Close ) will deploy the Apps on all the Production Things with SmartPlugs associated with the Template.

The image below shows the Template CP-Demo’s SmartPlug Apps panel with three apps and a library provisioned.

SmartPlug Apps 2

Back to Top

Production Template Containers

You can associate a number of Containers with a Production Template. Containers are only accessible by devices that run a SmartPlug™ IoT agent. The Containers tab ( Apps ) is available on the side menu bar when SmartPlug is selected on the top ribbon of the Production Template Properties Console as shown below.

Containers 1

All the Containers available in the CloudPlugs IoT registry of your account will be displayed on the list and can be provisioned to Things by the Production Templates. If while working on the Production Template more Containers have been added to the registry, the reload (Reload) command will refresh the list.

All Production Things associated with the Production Template will automatically inherit the Containers configured in the Production Template.

Note that the only way to remove inherited Containers from Production Things is to remove them from the Production Template. Containers that are removed from the Production Template panel will then be removed from all the Production Things associated with the Template.

Clicking on Save ( Save ) or Save and Close ( Save and Close ) will deploy the Apps on all the Production Things with SmartPlugs associated with the Template.

The image below shows the Template CP-Demo’s Containers panel with three Containers provisioned.

Containers2

Back to Top

Configuring the Production Things Enroll Credentials

In order for Production Things to enroll in the platform, they must be provisioned by their Production Template with their individual enrollment credentials.  Those credentials are:

  1. A serial number or hardware ID (required). This is a user defined unique identifier for each Production Thing. You cannot have two Production Things belonging to the same Production Template with the same serial number.
  2. An Enroll password (required). User defined password that the platform uses once along with the serial number to generate the device's Plug-ID and connectivity/activation password.
  3. A Control password (optional). User defined password that a Controller needs to control the Production Thing.

When there is a large number of devices that need to be provisioned and it is impractical to enter the device serial numbers, Enroll and Control passwords manually, they can be uploaded from a .CSV (Comma Separated Values) file. The following is an example of a valid CSV file with three serial numbers and their respective enroll and control passwords.

rpi-001,enroll_pasword,control_password
edison-003,enroll_password
BBB-384-A,enroll_password,control_password

Enroll and Control passwords may also be generated by the platform using a Secret Key. In addition, Production Templates allow the creation of tokens, which can be used by external applications to make REST request calls to CloudPlugs IoT to generate credentials. For more details, please refer to the Creating Tokens for Programmatic Generation of Serial Numbers section of this guide.

A Production Template’s Production Thing serial numbers, Enroll and Control passwords are entered using the Serial Numbers panel accessible through the Serial Numbers tab (Serial Numbers).

It consists of two panels:

  1. The main panel that allows to issue commands and lists the serial numbers.
  2. The Activations panel which shows how many and what percent of the devices with serial numbers saved in the Template are currently enrolled.
Serial Numbers

Back to Top

Serial Number Main Panel

The main panel allows you to:

  1. Add (New) a new serial number, which opens the credential input window shown below, and once it is saved (Save) produces the results shown on the image to the right.
Add a New Serial Number and Credentials List displays the Serial Number and status of its enrollment and credentials
New Serial Number 1 New Serial Number 2

IMPORTANT!

Enroll and Control passwords can be changed and saved only before their Thing is enrolled. Once the Thing is enrolled, they cannot be modified. The only way to change them is for the Thing to become un-enrolled, which is equivalent to deleting the Thing from the platform.

  1. Open (Open) an existing serial number.
  2. Delete (Delete) an existing serial number.
  3. Perform Bulk Actions (Bulk Actions). Bulk actions allow to perform single command actions across a large number of serial numbers. Some of these actions are:
  1. Add the items in a .CSV (Comma Separated Values) file. The file may contain rows with a serial number, enroll password and control password, or simply serial numbers. You can define the type of separator used for the .CSV file. It can be a comma (,), a semicolon (;) or a tab (ASCII 09).
  2. Delete the items in a .CSV file. All serial numbers in the Template matching the serial numbers in the .CSV file will be deleted.
  3. Delete all Enrollment Credentials and Things will delete all the serial numbers in the Template. If there are Things that have already being enrolled, they will also be deleted and will lose their enrollment.
  1. Clicking OK will execute the Bulk Action programmed.

The example below shows an action to upload serail numbers from a CSV file.

Bulk Actions

The result is the upload of 1,099 serial numbers without enroll or control passwords. If defined in the CSV file, they would have been uploaded as well.

Bulk Actions
  1. Search the serial number list.

The bottom ribbon allows you to navigate through the list of available serial numbers and to reload the list if needed.

Back to Top

Activations Panel

The Activations panel shows a pie chart with the percent of devices with serial numbers in the Template are currently enrolled. It also lists the number of devices enrolled and the total number of devices that the Template has.

Here are the images of the Serial Number panels of two templates. The Template CP-Demo has 5 serial numbers for which Enroll and Control passwords have been provided manually and 4 of its devices have been enrolled. The Template Test1 has 1,000 serial numbers with Enroll and Control passwords generated by the platform using a Secret Key. None of the devices with those serial numbers have enrolled into the platform.

Serial Activation 1 Serial Activation 2

Back to Top

Creating Tokens for Programmatic Generation of Serial Numbers

Companies that need to produce a large number of devices to be connected to CloudPlugs IoT may want to use an application external to CloudPlugs IoT to generate the enrollment credentials for their devices. CloudPlugs IoT allows to make REST request calls using tokens to automatically generate serial numbers and enrollment credentials for each individual device. Each token also specifies the maximum number of serial numbers that can be created with it.

These tokens are created using the Production Template’s Serial Number Tokens tab.

To create a new token:

  1. Click on the New Token ( ) to open the token configuration panel.
  2. Enter an alphanumeric Prefix for the serial numbers to be generated (e.g., CPI10).
  3. Enter the Length or number of digits to be generated after the prefix. A length of 6 will result in serial numbers such as -123456.
  4. Enter the Expiration date of the token in number of days.
  5. Enter the Quota or maximum number of sequential serial numbers that can be generated by REST calls using the token.
  6. If SmartPlugs are going to be used, the (smartplug.conf) configuration files with the enrollment credentials can also be generated. Simply enter the configuration parameters in the SmartPlug config panel.
  7. Save and Close ( Save & Close ) the new token.

The following example shows how to create a token valid for 90 days to generate enrollment credentials with serial numbers of the form ACME-100 for up to 1,000 SmartPlug™ driven devices with a configuration file such as:

connect= api.myiot_cloud.global
enroll_target = thing
enroll_model={model}
enroll_thing={hwid}
js_shell = true
fm_perms = r
New Token

The resulting token looks as follows:

New Token

Tokens may also be opened and edited, deleted and copied to the system’s clipboard to then paste it into the REST call in the application used to generate the serial numbers.

Editing a Serial Number Token

Once a token is created, only its SmartPlug configuration can be edited.

To edit an existing token:

  1. Click on the target token to select it.
  2. Either click on the Open ( Open ) button, or double click on the token.
  3. Edit the SmartPlug configuration.
Edit token
  1. Save and Close ( Save & Close ) the token.
Edited token

Provisioning Production Things

To provision your Production Things:

  1. Save ( Save ) or Save and Close ( Save & Close ) the Production Template.
  2. Click on the Provision (Provision) button to the right of the lower ribbon of the General -> Template Profile panel.

Once the Production Things are provisioned in CloudPlugs, your devices can connect to the platform using a SmartPlug™ or a connection library. The devices must be programmed with the enroll credentials set in the Production Template.

As devices enroll, the platform automatically assigns a Plug-ID (AUTH_PLUGID) and a secret activation/connection password (AUTH_PASS) to the Things that have enrolled successfully. The activation/connection password, alongside the Plug-ID and serial number or hardware ID are used by the Production Things to connect to the platform.

For details on connecting a Production Thing, refer to the Connecting a device as a Production Thing Guide.

Back to Top

Deleting a Production Template

To delete a Production Template, there must be no serial numbers associated with the Template.

If a Template has serial numbers and you need to delete it, you must make sure that:

  1. Any Production Things with serial numbers that belong to the Template and that are currently enrolled in CloudPlugs IoT must be deleted. This can be achieved from the Things Management Console.. Serial numbers associated with Things that are enrolled cannot be deleted.

  2. Once 1 above is done, open the Production Temaplate.

  3. Open the Enroll Credentials ( Enroll Credentials ) panel.

  4. Delete all the serial numbers present in the Template.

  5. Save ( Save ) or Save and Close ( Save and Close ) the Template.

  6. Select and delete ( ) the Template from the Production Template management Console.

Still need help? Get in touch!
Last updated on 23rd May 2019