posted

0 Comments

This is a guest post written by Luis M. Valerio Castillo.

 

With the release of VMware Pulse™ IoT Center™ version 2.0 comes a number of improvements and changes over its previous version. One of the changes is how you set up and enroll device edges to the platform.

In this post, I’d like to walk you through the setup of a device edge with Pulse 2.0. This post is not meant to be an extensive installation guide. However, it should be useful as an overview of the steps required to set up a new device edge with Pulse IoT Center version 2.0.

In order to follow the steps in the next few sections, you must have a Pulse IoT Center 2.0 instance running. You also need to have a device edge or VM running a Linux operating system. As of the time of the writing of this post, Pulse IoT Center 2.0 does not yet support Windows device edges.

Note: In Pulse IoT Center 2.0, device edges are called Gateways. I’ll be using the two terms interchangeably moving forward.

Overview

When setting up device edges with Pulse 2.0, there are two high-level steps:

  • Install the Pulse agent on the device edge
  • Enroll the device edge into Pulse IoT Center

 

Pulse Agent Installation

To be able to manage a device edge with Pulse 2.0, the Pulse agent must be installed on it. The installation can be accomplished by downloading the agent tar file from Pulse IoT Center to the device edge and running the installation script. To begin, log in to the Pulse IoT Center UI. Find the link to download the Pulse agent by clicking on the gear icon on the top right-hand side of the page. A menu will appear as shown below in figure 1.

VMware Pulse IoT Center Menu - user interface

Figure 1. Pulse_download_menu

 

Click on the Downloads option. A pop-up page will appear where you can choose the type of agent you wish to download based on the processor you have running in your device edge. If you don’t know the processor architecture, you can find out by using the following command inside your device edge:

hostnamectl

The command will generate terminal output similar to the one below:

ubuntu@ubuntu_device_edge:~$ hostnamectl
    Static hostname: ubuntu_device_edge
          Icon name: computer-vm
            Chassis: vm
         Machine ID: 911ce052394d48018457bcbe6e74a39c
            Boot ID: f02733fddb744908ae4c5885842a0695
     Virtualization: vmware
   Operating System: Ubuntu 18.04.2 LTS
             Kernel: Linux 4.15.0-47-generic
       Architecture: x86-64

The Architecture key from that output tells you the type of processor that is running on the device edge which will match one of the download options for the Pulse agent.

After you figured out the correct agent to download, right-click on the Download link and select Copy link address. Now you have the download URL of the Pulse agent saved in your clipboard.

Next, if you haven’t already done it, log in using SSH to the device edge you want to install the Pulse agent on. Issue the following command to download the Pulse agent tar file and expand it:

curl -k https://192.168.100.106/api/iotc-agent/iotc-agent-x86_64-2.0.0.403.tar.gz | tar xvz

Note: Make sure to replace the URL with the Pulse agent download URL you copied to the clipboard from the Pulse IoT Center UI.

Once the command finishes execution, you will see a folder named iotc-agent. Run the install script inside that folder using the following commands:

cd iotc-agent/
 sudo ./install.sh

A sample of the Pulse agent install script output is found below:

ubuntu@ubuntu_device_edge:~/iotc-agent# sudo ./install.sh
 Mon May 13 20:03:03 UTC 2019 : Installing from /root/iotc-agent
 Mon May 13 20:03:03 UTC 2019 : User exists already.
 Mon May 13 20:03:03 UTC 2019 : iotc user id = 1001 group id = 1001
 Mon May 13 20:03:16 UTC 2019 : iotc-agent successfully installed at /opt/vmware/iotc-agent
 Mon May 13 20:03:16 UTC 2019 : Starting iotc-agent daemon
 Mon May 13 20:03:17 UTC 2019 : iotc-agent daemon running with pid = 19069

Another way to verify that the agent has been installed successfully is to look for the /opt/vmware/iotc-agent folder in the device edge filesystem. The folder contains all the files generated as part of the agent installation. Among some of the files is an agent uninstall script and a CLI binary that can be used to interact with Pulse IoT Center. You will be using the agent CLI to do the enrollment later on.

With the agent installed, the next step is to begin the enrollment process.

Device Edge Enrollment

Currently, there are two ways to enroll a new device edge into Pulse IoT Center:

  • Pre-registered Gateway enrollment
  • Unregistered Gateway enrollment

In this post, I will cover the unregistered gateway enrollment process. For information on the pre-registered gateway enrollment process, go to the Pulse 2.0 documentation.

The unregistered gateway enrollment uses basic auth when using the enroll command. This will require you to input the username and password of a Pulse user with permissions to enroll new devices. Before using the enroll command, the following needs to be present in Pulse IoT Center:

  • User with permissions to enroll new devices
  • Device template for the device edge

In case you already have the user and/or template, you can skip to the Basic Auth Enrollment section. Otherwise, you can create them by following the steps in the next few paragraphs.

To create a user that has permissions to enroll devices, you must create a group that has the Gateway Administrator role and assign that group to a new user. Follow the steps below to create the group:

  1. Log in to the Pulse IoT Center UI
  2. Click on the Identity and Access tab on the left-hand menu to expand it
  3. Click on the Groups option from the submenu. You should see something similar to figure 2 below.
VMware Pulse IoT Center Identity and Access tab

Figure 2. VMware Pulse IoT Center Identity and Access Groups

 

  1. Click on the Create button and fill out all the required fields on the wizard that appears then click Next
  2. Select the Gateway Administrator role from the drop-down menu and click Next
  3. Check the information is correct then click Save

With the group created, it is now time to create a user and assign it to that group. The steps below go over that process:

  1. Click on the Identity and Access tab on the left-hand menu to expand it if it is not already expanded
  2. Click on the Users option from the submenu
  3. Click on the Create button and fill out all the required fields on the wizard that appears then click Next
  4. Select the group you created earlier from the drop-down menu and click Next
  5. Check the information is correct then click Save

Next, the Pulse device template for the device edge needs to be created. To create the template, follow the steps below:

  1. Click on the Inventory tab on the left-hand menu to expand it
  2. Click on Device Templates from the submenu
  3. Click on the Create button. On the wizard that appears, give the template a name. I recommend to not use blank spaces or special characters in the name to avoid issues later on when using the enroll command. From the Select Device Type menu, pick Gateway then click Next
  4. Click Next on the rest of the pages of the wizard until you get to the final page then click Save. Optionally, you can modify any of the fields on any of the pages if you wish. For the purpose of this example, the defaults are fine.

 

Basic Auth Enrollment

Now that the device template has been created, the enroll command can be used. Log in to the device edge using SSH and issue the command:

  sudo sh /opt/vmware/iotc-agent/bin/iotc-agent-cli enroll --template=template_name --name=device_name --username=user_name@email.com

Note: Make sure to replace template_name with the name of the template you created and replace user_name@email.com with the user name of the account you created.

The terminal might ask you for the sudo password of the device edge. You will be prompted for the password of the Pulse user account you specified.

Once the command is executed successfully, you will see command line output similar to the one below:

ubuntu@ubuntu_device_edge:~$ sudo sh /opt/vmware/iotc-agent/bin/iotc-agent-cli enroll --template=test1 --name=device_name --username=user_name@email.com
Password:
Device Id: 1710f107-e8a4-4041-a3dc-b88f0755c302
Parent Device Id:
Status of enroll response: 0

To verify the device enrollment was successful, log in to the Pulse IoT Center UI. You should see the new device edge listed under Inventory -> Devices. It should look similar to figure 3 below.

VMware Pulse IoT Center Device Inventory

Figure 3. Pulse_install_script_output

 

Enroll Command Troubleshooting

In case the enrollment command is not working, set the following path variables and retry the enroll command:

export PATH=$PATH:/opt/vmware/iotc-agent/bin
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/vmware/iotc-agent/lib

 

Conclusion

At this point, the device edge is enrolled to Pulse IoT Center. In the next post, I’ll walk you through automating the agent installation and enrollment.

 

About the author:

Luis M. Valerio Castillo

Luis M. Valerio Castillo is a Solutions Development Consultant on the PS Engineering at VMware, focusing on IoT. Prior to this role, Luis worked in the field implementing solutions for customers, which included application deployment automation, third party system integrations, automated testing and documentation. His six years of experience started at Momentum SI, which was acquired by VMware in 2014. He holds a Bachelors of Science, with a major in Computer Science.