Install Device Manageability

Prerequisites

The following are the prerequisites to install Device Manageability:

1. Ubuntu 18.04 and Ubuntu 20.04.

2. Install the latest docker cli/docker daemon. Refer to the following sections:

   • Install using the repository and Install Docker Engine at https://docs.docker.com/install/linux/docker-ce/ubuntu/#install-docker-ce.

   • Also, follow the Manage Docker as a non-root user section at https://docs.docker.com/install/linux/linux-postinstall/ to run docker without sudo.

3. Follow the below steps only if the node or system on which the docker setup is tried out is running behind a HTTP proxy server otherwise, you can skip this step.

   1. Configure proxy settings for docker client to connect to internet and for containers to access internet. For more information, see https://docs.docker.com/network/proxy/.

   2. Configure proxy settings for docker daemon. For more information, see https://docs.docker.com/config/daemon/systemd/#httphttps-proxy.

4. Install docker-compose tool. For more information, see https://docs.docker.com/compose/install/#install-compose

All Device Manageability devices can be controlled using a cloud service application. To install Device Manageability, complete the following:

1. Install Device Manageability agent on the machine.

   1. Run below steps for installation from manageability folder:

      sudo chmod +755 install-tc.sh
      sudo ./install-tc.sh

      NOTE:

      Before you install a newer version of Device Manageability, check if the system has old version of Device Manageability. If an older version is installed then, uninstall the older version with the same version of the uninstall script.

   2. After reading all the licenses, press ‘q’ to finish.

   3. Enter ‘Y’ to accept the license.

      The following figure shows the terminal output you should expect to see after the installation is complete.

      

   4. After the Device Manageability has been installed successfully, set the following values in the /etc/intel_manageability.conf file.

      sudo vi /etc/intel_manageability.conf

   5. Under the <all> </all> section, change dbs ON to OFF. Refer to the following figures. DBS stands for Docker Bench Security, this feature of Device Manageability is not used for EII.

      

      

   6. Add the URL endpoint for the developer files to the TrustedRepositories as shown in the following figure

      <trustedRepositories>
      https://api-dev.devicewise.com
      </trustedRepositories>

   7. Save and exit. Restart the machine to apply the changes.

EII Provisioning and Deployment via Bundle Generation

EII deployment via bundle generation requires the use of the Docker* registry. The following section outlines some of the commands to create EII bundle

1. Set up the Docker registry URL, build, and push images.

   1. Update docker registry URL in DOCKER_REGISTRY variable <ip:port>. The example uses 10.221.40.65:5000/ as the Docker registry.

      sudo vi [WORK_DIR]/IEdgeInsights/build/.env

      

   2. In the same build repository, build the image using the following command:

      docker-compose -f docker-compose-build.yml build

      If the build is successful, you should see the following terminal output:

      

   3. Push the image to the registry:

      docker-compose -f docker-compose-push.yml push

Generating EII Bundle for Deployment

The following steps are used to generate the EII_bundle. This software will only work on Python* 3 and onwards.

1. Update config.json file to include the services that you need for the bundle. Ensure to exclude those services that you do not want with the bundle.

   $ sudo vi build/deploy/config.json
   
   
   {
   "docker_compose_file_version": "<docker_compose_file_version which is compose file version supported by deploying docker engine>",
   "exclude_services": [list of services which you want to exclude from your deployement]
   "include_services": [list of services needed in final deployment docker-compose.yml]
   }

   Note: Ensure that you have updated the DOCKER_REGISTRY in build/.env as mentioned in the EII deployment section.

2. Run the following script in the terminal to generate the eii_bundle.

   cd [WORK_DIR]/IEdgeInsights/build/deploy/
   sudo python3 generate_eii_bundle.py -gb

   The default value for bundle name is eii_bundle.tar.gz, while the tag name is eii_bundle.

   Using -t options can give you a custom tag name which will also be used for bundle generation.

   The default value for the docker-compose yml path is ../docker-compose.yml.

3. The file eii_bundle.tar.gz will be created in the same folder. Create the following two bundles for the deployment:

   • Bundle 1: Generate bundle named cfgmgr_bundle.tar.gz with only “ia_configmgr_agent” as included service.

   • Bundle 2: Generate bundle named eii_bundle.tar.gz with all the required included EII services.

Creating an HTTP Local Server

The generated EII bundle need to available via http server to perform AOTA fetching from the cloud services.

Prerequisites

Run sudo vi /etc/environment.

Under no_proxy variable, add the local http server (example, 10.221.40.65).

1. Run the following command on the ThingsBoard machine to create the HTTP server for sharing the eii_bundle:

   python3 -m http.server [any port number]

2. Add the fileserver endpoint to the configuration file on the node that you will access via the local HTTP server.

   In the example, the steps below must be done on the new node. The new node will access the local HTTP server to fetch the eii_bundle that is being created.

   1. Open the configuration file.

      sudo vi /etc/intel_manageability.conf

   2. Under trustedRepositories, add the bundle hosting server endpoint on a new line. http://xx.xxx.xxx.xx as used above.

      

      NOTE:

      The above example is running local HTTP server at 10.221.40.65:8000

Cloud Service: Azure Server Setup

You can connect and control the Device Manageability devices from the Azure* portal. Create an Azure* account from the following link: https://azure.microsoft.com/en-us/free/

To create an account, select start free, and create the account.

Setting up an Azure IoT Central Application

1. To generate a premade Device Manageability (Intel Manageability) IoT Central application get the link from /usr/share/cloudadapter-agent/azure_template_link.txt file on Device Manageability machine.

2. Copy and paste the link in the browser, you will be redirected to the Azure* UI as shown below.

   

3. For the pricing plan, select Free (trial version). Enter the contact information and click create account.

4. After provisioning, the IoT Central application with premade device templates and dashboards will appear. As noted before, this can be accessed at https://apps.azureiotcentral.com or through the Azure portal.

   

Obtaining Device Credentials

1. To add a new device, on the side bar click the Devices tab, and then click add new device.

   

2. Select real on the drop-down list, on the Create New Device form, click Create.

   

3. The new added device will appear on the list of the devices page. To connect the device, click on that specific device and at the top-right bar, click Connect.

4. Device connection information form will appear as follows.

   

Provisioning a device

Prerequisites : To perform this step, the Device Manageability device needs to be installed according to the instructions in the Installation Device Manageability section.

1. Provisioning can be done with or without TPM security by setting ‘PROVISION_TPM’. ‘PROVISION_TPM’ can be set to the Device Manageability device, users need to run these commands:

   • auto: use TPM if present; disable if not present; do not prompt

   • disable: do not use TPM.

   • enable: use TPM; return error code if TPM not detected.

   • (unset): default behavior; use TPM if present, prompt if not

2. On the Device Manageability device, run the following command:

   • To run provisioning with detecting automatically TPM is present or not:

     sudo PROVISION_TPM=auto provision-tc

   • To run without TPM security:

     sudo PROVISION_TPM=disable provision-tc

3. If the device has been already being configured, it will prompt as follows:

   

   • Enter ‘Y’ to replace the existing configuration.

   • Select ‘2’ for cloud service option.

   

4. A prompt for Device provision type appears; select the type of device authentication preferred: Choose 1 for SAS key authentication. If you choose option 2 - Refer to secton [2.5 - Provisoning a Device ] at ./docs/In-Band_Manageability_UserGuide_Azure.pdf for further steps.

5. All the device credentials from obtaining device credentials will be used here. Enter the following information accordingly.

   

6. The script will then start the Intel Manageability services; when the script finishes, the device should be able to interact with its associated IoT Central Application. To verify connectivity:

   a. Check to see if telemetry/events are appearing. If the information is not seen, use the systemctl restart cloudadapter telemetry command to restart the two agents. Allow few seconds for the information to be populated and then refresh the page. b. Alternatively, you can trigger a command like Reboot.

7. Run the provisioning script again, if you want to change or update the cloud service configuration.

8. On the Azure portal, the device status should change from ‘Registered’ to ‘Provisioned’ as follows:

   

9. The following is an example of telemetry data of the connected devices that is available to be view on the measurement tab by the user using Azure portal.

   

10. You can get the additional details information for the specific hardware and the event logs on the Properties tab as follows:

    

11. Following is an example of basic information that is shown on the Dashboard tab.

    

Performing AOTA Updates Through the Azure Portal

Prerequisites: To perform this step, EII bundle need to be generated as mentioned in section Generating EII Bundle for deployment. For testing, you can run the local http server as mentioned in the Creating an HTTP Local Server [ONLY FOR DEVELOPMENT] section. For the actual implementation, you are expected have your own http server or any cloud services that can provide valid URL to fetch the EII bundle.

1. Open the Azure portal, select for the specific device that user will trigger the AOTA.

2. On the menu bar, select Commands.

   

3. On the list command, enter the details in the Trigger AOTA form as follows. To perform this step, generate the EII bundle. For more information, see the Generating EII Bundle for Deployment section.

   

4. Above example assumes that the http server is running at http://10.221.40.65:8000/eii_bundle.tar.gz and the EII bundle is generated using the default tag. Leave all other sections empty and click Run.

   The sample PCB demo example of the EII Visualizer application should appear on the new node. If the visualizer does not appear, run the following command in the new node terminal:

   xhost +

   You can also check that EII has been successfully deployed on the new node by checking the list of running containers using the following command:

   docker ps

   This action should yield the following terminal output listing the running EII containers

   By repeating the AOTA method, you can also stop EII from running on the new node. Instead of passing command up parameter, you can pass command down parameter and the correct eii_bundle tag. To check if EII has stopped, check the list of running containers.

   

Verifying Triggered AOTA in Event

After an AOTA event is triggered, you can verify the log of the triggered call. This can be one of the verification during development phase.

1. Go to the Device Manageability machine and run the following command to output the log of commands:

   journalctl -fu dispatcher & journalctl -fu cloudadapter

2. Note the event logs on the Azure portal server showing which commands have been run

   NOTE:

   If the event log does not appear, follow the steps below.

   Change settings from ERROR to DEBUG everywhere in below files.
   (Only for Development Purpose)
   /etc/intel-manageability/public/dispatcher-agent/logging.ini
   /etc/intel-manageability/public/cloudadapter-agent/logging.ini

3. Run the following commands

   sudo systemctl restart dispatcher
   sudo systemctl restart cloudadapter
   sudo systemctl restart diagnostic

Cloud Service: ThingsBoard* Setup

All Device Manageability devices can be added into ThingsBoard to provision or enable the AOTA updates.

Starting ThingsBoard* as Docker [macOS*/Linux*]

1. Choose an edge device to run as the ThingsBoard server. The edge devices for ThingsBoard machine can be either within the cluster setup or any other edge devices.

2. Run the following command to start ThingsBoard on the ThingsBoard machine.

   docker run -it -p 9090:9090 -p 1884:2883 -p 5683:5683/udp -v ~/.mytb-data:/data -v ~/.mytb-logs:/var/log/thingsboard -e MQTT_BIND_PORT=2883 -name mytb -restart always thingsboard/tb-postgres:2.5.0

   Assuming that ThingsBoard has started correctly, you should expect to see the terminal output as shown in figure below.

   

3. After executing the command, the user can browse the ThingsBoard server:

   <http://<host-ip>:9090>

   Example: http://10.221.40.48:9090

4. ThingsBoard login page should appear, as shown in the following figure:

   

5. Enter the default username and password to access the ThingsBoard home.

   Username: sysadmin@thingsboard.org

   Password: sysadmin

Creating a ThingsBoard* Account

1. On the homepage, click Tenant management, as shown in the following figure:

   

2. At the bottom-right, click the plus button to add a new tenant. Refer to the following figure:

   

3. The Add Tenant form will appear as shown in the following figure. Complete the form, and then, click ADD.

   

4. New tenant entry will appear in the tenant section as shown in the followig figure. Click Manage tenant admins to create a new user sign-in username and password.

   

5. Add User form will appear as shown in figure below. Complete the form accordingly. For the Activation Method, click display activation link, then click ADD.

   

6. User activation link box will appear as shown in the following figure below. Click on the activation link.

   

7. You will be redirected to create a new sign-in password. Click CREATE PASSWORD to create the new password as shown in the following figure:

   

8. You can now sign in using the tenant username and password. After which you will be redirected to the ThingsBoard dashboard page as shown in the following figure:

   

Adding Device Manageability Device to ThingsBoard*

1. Add the new Device Manageability device on ThingsBoard.

   1. Log in to the ThingsBoard page. On the left sidebar, click Devices as shown in figure below.

      

   2. At the bottom-right, click ‘plus’ and choose to ‘Add new device’.

      

   3. ‘Add device’ window will appear. Completed the fields, then click ADD.

      

   4. Newly added device will be shown on the devices page as shown in the following figure:

      

2. Obtaining device credentials

   1. Click the manage credentials icon as shown in figure below.

      

   2. Device credentials window will appear as shown in figure below. Access token is required for provisioning purposes.

      

3. Setting up the dashboard

   1. Some files need to be copied from the Device Manageability machine to ThingsBoard page in the next step. These files can be found in the directory below.

      cd /usr/share/cloudadapter-agent/thingboard

      

   2. On the left side bar menu, click Widget Library, then, click Add new widget at the bottom right, and then Import widgets bundle. Drag the intel_manageability_widget.json file into the box provided and then, click IMPORT.

      

   3. On the left sidebar menu, click Dashboard, then at the bottom right click Add new dashboard. Drag intel_manageability_devices.json into the box provided and then, click Import. Repeat this step for intel_manageability_batch.json.

      

   4. Both the newly added dashboards will be displayed.

      

   5. To access the dashboard, click Dashboard on the left sidebar, then on Intel Manageability Devices. Basic information about added devices is available here.

If you have more than one device, then you can choose which device to view by clicking the highlighted button on the top-right.

Buttons are also available in the lower part of the screen to view the entire event log, to search for specific event logs, or to expand the window to full screen.

Provisioning a Device

Prerequisites: To perform this step, Device Manageability needs to be installed following the instructions in the Installation - Device Manageability section.

You must provision the Device Manageability device for it to connect to ThingsBoard.

1. Provisioning can be done with or without TPM security by setting ‘PROVISION_TPM’. ‘PROVISION_TPM’ can be set to the Device Manageability device, user needs to run these commands:

   • auto: use TPM if present; disable if not present; do not prompt

   • disable: do not use TPM.

   • enable: use TPM; return error code if TPM not detected.

   • (unset): default behavior; use TPM if present, prompt if not

2. On the Device Manageability device, run the following command, and change the bold parameter accordingly as mentioned above.

   sudo PROVISION_TPM=auto provision

   Read though the license and press Y to accept.

3. If the device was previously provisioned, the following message will appear. To override the previous cloud configuration, press Y.

   

4. Select ThingsBoard as the cloud service by pressing 3 and [ENTER].

   

5. A prompt for Device provision type appears; select the type of device authentication preferred: Choose 1 for Token authentication. If you choose option2 - Refer secton [2.5 - Provisoning a Device ] at ./docs/In-Band_Manageability_UserGuide_ThingsBoard.pdf for further steps.

6. Provide the IP address of the server running ThingsBoard.

   

7. Provide the device token based on step 3b.

   

8. Use 1884s for the port configuration.

   

9. Prompts for ‘Configure TLS’ will appear, type ‘N’ for this.

   

10. The following screen will appear if cloud provisioning has been completed successfully.

    

The script will then start the Intel® Manageability Services. When the script finishes, you should be able to interact with the device via the ThingsBoard dashboard.

If at any time the cloud service configuration needs to be changed or updated, run this provisioning script again.

To add more than one device, repeat each of the previous steps, except for step 4 (Setting Up the Dashboard).

Performing AOTA Updates Through the ThingsBoard* Page

Prerequisites: To perform this step, generate the EII bundle as mentioned in the Generating EII Bundle for Deployment section and local http server (for development) need to be run as mentioned in Creating an HTTP Local Server [ONLY FOR DEVELOPMENT].

1. Open the ThingsBoard page, then click the “Dashboard” page. Select Intel Manageability Devices.

   

2. Select one of the previously added Device Manageability devices. In this case, you can select the new node (node 2) in which you want to deploy the eii_bundle.

3. Click Trigger AOTA.

   

4. After the Trigger AOTA window opens, complete each field per the information below:

   

For the fetch information, provide the local HTTP server being set up in section Creating an HTTP Local Server [ONLY FOR DEVELOPMENT]. The example uses http://10.221.40.48:9000/eii_bundle.tar.gz in this case.

Leave the other section empty and then, click Send.

In the previous step, the new node will access the primary node through the local HTTP server that is being set up to fetch the eii_bundle.

In the ThingsBoard log, you can see that the eii_bundle is fetched from the local server and is deployed successfully:

The sample PCB demo example of the EII Visualizer application should appear on the new node. If the visualizer does not appear, run the following command on the new node terminal.

xhost +

You can also verify that EII has been successfully deployed on the new node by checking the list of running containers using the following command:

docker ps

This command will list the EII containers that are running in the terminal output.

You can also stop EII from running on the new node by repeating the AOTA method. Instead of passing command up parameter, You can pass the command down parameter and the correct eii_bundle tag. You can verify that EII has stopped by checking on the list of running containers.

Verifying Triggered AOTA in Event

Once an AOTA event is triggered, you can verify the log of the triggered call. This can be one of the verification done during development phase.

1. Go to the Device Manageability machine and run the following command to output the log of commands:

   journalctl -fu dispatcher & journalctl -fu cloudadapter

2. Note the event logs on the ThingsBoard server shows the commands that have been run.

   NOTE:

   If the event log does not appear, follow the steps below.

   Change settings from ERROR to DEBUG everywhere in below files.
   (Only for Development Purpose)
   /etc/intel-manageability/public/dispatcher-agent/logging.ini
   /etc/intel-manageability/public/cloudadapter-agent/logging.ini

3. Run the following commands:

   sudo systemctl restart dispatcher
   sudo systemctl restart cloudadapter