Login and Enroll

The CloudPlugs IoT platform enables access to devices that have connectivity credentials. First step is to establish connection

cp.connect(function(err){
	if (err)
		return console.error(err);			
	continue with operations
})

As an Alternative the connect method can be used with events (event names are connect and networkErr) and returns Promise thus can be called with await keyword.

If you ever need to close the connection use the cp.close() method which also is both callback(err) and Promise compliant.

Production Things and Controllers must login and enroll to the platform with their enroll credentials to get their permanent login credentials:

• PlugId their Plug-ID
• Auth their permanent login password

The enroll operation for Production Things and Controllers is orchestrated by invoking the function:

cp.login( authObject, cb)  

After connecting to the CloudPlugs IoT platform, cp.login() manages the enrollment and the subsequent automatic login to the platform.

The authObject contains the credentials necessary to login to the platform and complete the device’s enrollment process. The object’s structure differs from Production Things to Controllers as described in the sections below.

cb is a callback function whose operation varies depending on the type fo device being enrolled.

The sections below describe the respective procedures for enrolling a Production Thing and for enrolling a Controller.

Enrolling a Production Thing

In order to enroll a Production Thing, the AuthObject must have the following structure:

"model" ( String ):				the string "mod-xxx" with the Plug-ID of the Production Template of the Thing to be controlled

"hwid" ( String ):				the string with the "serial number" of the Thing to be controlled

"pass" ( String ):				enroll password string (min. 8 chars) assigned to the Thing in its Production Template
		
"name" ( optional, String ):		the optional name of the Production Thing

"role" ( iot_tg | iot_ctrl ):			the type of device, Production Thing or Controller

Once the enroll process is completed by the platform:

1. The enroll event is fired, and

2. The cp.login() callback’s first argument returns an object structured as follows:

    "id" ( String): 		the Plug-ID string of the Production Thing in the format dev-xxxxxx
    
    "pass" ( String ):	the connectivity/activation password string	
   

To execute the enroll procedure independently of the WebSocket connection, it is recommended to use the REST API as described in the EnrollNewThing documentation.

Back to top

Enrolling a Controller

Controllers are devices inside the CloudPlugs platform and they are created when a request to control a Production Thing is received by the platform. In this phase, the platform generates the Controller credentials and its permissions on the Production Thing it will control.

To enroll a Controller, the authObject must have the following structure:

	"model" ( String ):				the string "mod-xxx" with the Plug-ID of the Production Template of the Thing to be controlled

	"thingHwid" ( String ):			the string with the "serial number" of the Thing to be controlled
	
	"pass" ( String ):				enroll password string (min. 8 chars) assigned to the Thing in its Production Template

	"ctrlHwid" ( optional, String)		the optional serial number or hardware id string of the Controller device

	"name" ( optional, String ):		the optional name string of the Production Thing

	"user" ( String ):				Assigned user name string for the user that will login to use the Controller

	"userPass" ( String ):			Assigned password string for user to login to the Controller

Once the enroll process is completed by the platform, the callback is executed. The callback has the structure

cb(err, res)

The second argument of the callback contains an object with the structure:

	"id" ( String ): 		the Plug-ID string of the Production Thing in the format dev-xxxxxx
	
	"pass" ( String ):	the connectivity/activation password string

These credentials can be used with the cp.login method. An alternative way of logging in is to use user without knowing id. This can be done by passing it to cp.login with an authentication object such as:

"user" (String):  same as passed on enrollment

"name" (String):  same as passed on enrollment           

"pass" (String):  the userPass passed on enrollment

"provider" (String):  company's plug-id 

The role of the name field is to divide user names in different domains within the same company. You can build multiple applications and each can have its own accounts’ domain. For example, you will be able to have 2 different users called “frank” in different domains. In addition, you can have 2 applications sharing the same accounts just by passing the same string as domain (in the name property).

When the enroll process is finished:

1. The controlThing event is fired, and

2. The callback of the function cp.on(‘controlThing’, cbEv) has an object in its first argument which contains the information of the Production Thing controlled in the form:

    "id" ( String ): 				the Plug-ID string of the Production Thing in the format dev-xxxxxx
   
    "model" ( String ):			the string "mod-xxx" with the Plug-ID of the Production Template of the Thing to be controlled
   
    "hwid" ( String ):			the string with the "serial number" of the Thing to be controlled
   

The library then replaces the Controller’s original authObject login credentials with the id and pass obtained through the enroll procedure.

Back to top

Control other Things

A Controller can take control of multiple Production Things by:

1. Repeating the calls to the cp.controlThing(object, cb) method, and

2. Passing the additional Production Thing’s credentials in the object argument as follows:

    "model" ( String ):			the string "mod-xxx" with the Plug-ID of the Production Template of the Thing to be controlled
   
    "thingHwid" ( String ):			the string with the "serial number" of the Thing to be controlled
   
    "pass" ( String ):			enroll password string (min. 8 chars) assigned to the Thing in its Production Template
   

When the process to control the additional Thing is finished:

1. The specified cb function will be invoked with the structure cb(err, res)
2. The controlThing event is fired, with the information of the Thing being controlled.

To execute the enroll procedure independently of the WebSocket connection, it is recommended to use the REST API as described in the EnrollController documentation.

Back to top