Get Started Guide

  • 3.0
  • 05/04/2022
  • Public

Device Manageability

Device Manageability enables software updates and deployment from cloud to device. This includes the following:
  • Software over the air (SOTA)
  • Firmware update over the air (FOTA)
  • Application over the air (AOTA) and system operations
The
AOTA
update enables cloud to edge manageability of application services running on the Edge Insights for Industrial (EII) enabled systems through Device Manageability.
For EII use case, only
AOTA
features from Device Manageability are validated and is supported through
Azure*
and
ThingsBoard*
cloud-based management front-end services. You can select either one of these options depending on preference.
The following section will walk you through the following:
  • Setting up
    Azure*
    and
    ThingsBoard*
  • Establishing connectivity with the target systems
  • Updating applications on systems
You can refer to the user guide in
docs
for more detailed reference.
Device Manageability was previously named Turtle Creek. Remnants of the previous name still exist in some components. The name replacement is ongoing and will be completed in future releases.

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:
  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:
This step is required only if you select cloud service
Azure*
and
ThingsBoard*
.
  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
      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.
      image0
    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.
      image1
      image2
    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
This step is required only if you select cloud service
Azure Portal*
and
ThingsBoard*
.
  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
      image3
    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:
      image4
    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

This step is required only for user that select cloud service Azure* or ThingsBoard* cloud services and for development purpose. During actual implementation, users need to have their own cloud http server to upload the EII bundle that being generated and use the URL to fetch the uploaded bundle on the AOTA step later.
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.
      image5
      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.
    image6
  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.
    image7
Obtaining Device Credentials
  1. To add a new device, on the side bar click the Devices tab, and then click add new device.
    image8
  2. Select real on the drop-down list, on the Create New Device form, click Create.
    image9
  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.
    image10
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:
    image11
    • Enter ‘Y’ to replace the existing configuration.
    • Select ‘2’ for cloud service option.
    image12
  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.
    image13
  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:
    image14
  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.
    image15
  10. You can get the additional details information for the specific hardware and the event logs on the Properties tab as follows:
    image16
  11. Following is an example of basic information that is shown on the Dashboard tab.
    image17
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
    .
    image18
  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.
    image19
  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.
    image20
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
    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.
    image21
  3. After executing the command, the user can browse the ThingsBoard server:
    <http://<host-ip>:9090>
  4. ThingsBoard login page should appear, as shown in the following figure:
    image22
  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:
    image23
  2. At the bottom-right, click the plus button to add a new tenant. Refer to the following figure:
    image24
  3. The Add Tenant form will appear as shown in the following figure. Complete the form, and then, click
    ADD
    .
    image25
  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.
    image26
  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
    .
    image27
  6. User activation link box will appear as shown in the following figure below. Click on the activation link.
    image28
  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:
    image29
  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:
    image30
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.
      image31
    2. At the bottom-right, click ‘plus’ and choose to ‘Add new device’.
      image32
    3. ‘Add device’ window will appear. Completed the fields, then click
      ADD
      .
      image33
    4. Newly added device will be shown on the devices page as shown in the following figure:
      image34
  2. Obtaining device credentials
    1. Click the manage credentials icon as shown in figure below.
      image35
    2. Device credentials window will appear as shown in figure below. Access token is required for provisioning purposes.
      image36
  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
      image37
    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
      .
      image38
    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
      .
      image39
    4. Both the newly added dashboards will be displayed.
      image40
    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.
image41
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
    .
    image42
  4. Select ThingsBoard as the cloud service by pressing
    3
    and
    [ENTER]
    .
    image43
  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.
    image44
  7. Provide the device token based on step 3b.
    image45
  8. Use 1884s for the port configuration.
    image46
  9. Prompts for ‘Configure TLS’ will appear, type ‘N’ for this.
    image47
  10. The following screen will appear if cloud provisioning has been completed successfully.
    image48
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
    .
    image49
  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
    .
    image50
  4. After the Trigger AOTA window opens, complete each field per the information below:
    image51
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:
image52
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.
image53
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.
    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

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.