Improve Developers guide (#12)

intel · Jan 19, 2022 · 82f2aef · 82f2aef
1 parent c90aa5f
commit 82f2aef
Show file tree

Hide file tree

Showing 20 changed files with 237 additions and 220 deletions.
diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -19,3 +19,15 @@ Special thanks to all who worked on this project prior to the release to open so
  - Tejaswini Sirlapu (Intel)
  - Vinod Kulkarni (Intel)
  - Yeng Liong Wong (Intel)
+
+Validation Team
+ - Ahamedsha, Nur Syazwany Shah (Intel)
+ - Bin Samsudin, Safarin (Intel)
+ - Lim, Christine Xin Yi (Intel)
+ - Loh, Shao Boon (Intel)
+ - Mohd Affandi, Nurain (Intel)
+ - Pang, Jeff Jian Ye (Intel)
+ - Soo, Swee Kiong (Intel)
+ - Tan, Seng Howe (Intel)
+ - Tan, Siew Li (Intel)
+ - Thien, Kian Chung (Intel)
diff --git a/docs/In-Band Manageability Developer Guide.md b/docs/In-Band Manageability Developer Guide.md
diff --git a/docs/In-Band Manageability Installation Guide Ubuntu.md b/docs/In-Band Manageability Installation Guide Ubuntu.md
@@ -6,9 +6,9 @@
     1. [Purpose](#purpose)
     2. [Audience](#audience)
 2. [Installing INBM](#installing-INBM)
-    1. [OS Support](#supported-os)
+    1. [Supported OS](#supported-os)
     2. [Setting up checklist](#setting-up-checklist)
-    3. [Running Install script](#running-install-script)
+    3. [Run Install script](#run-install-script)
 
 ## Introduction
 ### Purpose

diff --git a/docs/In-Band Manageability User Guide - Azure.md b/docs/In-Band Manageability User Guide - Azure.md
@@ -1,15 +1,15 @@
 # In-Band Manageability Framework User Guide – Azure&reg;
 
-## Contents
+<details>
+<summary>Table of Contents</summary>
 
-1. [Contents](#contents)
-2. [Introduction](#introduction)
+1. [Introduction](#introduction)
     1. [Audience](#audience)
-3. [Azure&reg; Overview](#azure-overview)
-    1. [Getting Started with Azure&reg;](#getting-started-with-azure)
-        1. [Creating Azure&reg; portal account](#creating-azure-portal-account)
-        2. [Setting up an Azure&reg; IoT Central Application ](#setting-up-an-azure-iot-central-application-)
-        3. [Accessing Azure&reg;](#accessing-azure)
+3. [Azure&reg; Overview](#azurereg-overview)
+    1. [Getting Started with Azure&reg;](#getting-started-with-azurereg)
+        1. [Creating Azure&reg; portal account](#creating-azurereg-portal-account)
+        2. [Setting up an Azure&reg; IoT Central Application ](#setting-up-an-azurereg-iot-central-application)
+        3. [Accessing Azure&reg;](#accessing-azurereg)
         4. [Setting up the application for X509 based device enrollment](#setting-up-the-application-for-x509-based-device-enrollment)
     2. [Creating a Device and Obtaining Device Credentials](#creating-a-device-and-obtaining-device-credentials)
         1. [Shared Access Signature (SAS) authentication:](#shared-access-signature-sas-authentication)
@@ -22,15 +22,15 @@
     2. [Navigating the Device Interface](#navigating-the-device-interface)
 6. [Performing batch operations](#performing-batch-operations)
 7. [OTA Updates](#ota-updates)
-    1. [Trusted Repositories ](#trusted-repositories-)
+    1. [Trusted Repositories ](#trusted-repositories)
     2. [Preparing OTA Update Packages](#preparing-ota-update-packages)
         1. [Creating FOTA Package](#creating-fota-package)
         2. [Creating SOTA Package](#creating-sota-package)
         3. [Creating AOTA Package](#creating-aota-package)
         4. [Creating Configuration Load Package](#creating-configuration-load-package)
     3. [How to Generate Signature](#how-to-generate-signature)
 8. [OTA Commands](#ota-commands)
-    1. [Commands - Definitions and Usage](#commands-definitions-and-usage)
+    1. [Commands - Definitions and Usage](#commands---definitions-and-usage)
     2. [AOTA Updates](#aota-updates)
     3. [AOTA Docker-Compose Operations](#aota-docker-compose-operations)
         1. [Docker Compose Up](#docker-compose-up)
@@ -55,7 +55,6 @@
         2. [SOTA Update Via ‘Trigger SOTA’ Button Click (Mender)](#sota-update-via-trigger-sota-button-click-mender)
         3. [SOTA Update via Manifest](#sota-update-via-manifest)
     9. [Configuration Update ](#configuration-update)
-        1. [Default Configuration Parameters](#default-configuration-parameters)
     10. [Configuration Operation via Button Click](#configuration-operation-via-button-click)
         1. [Configuration Set](#configuration-set)
         2. [Configuration Get:](#configuration-get)
@@ -78,11 +77,13 @@
         1. [Static Telemetry:](#static-telemetry)
         2. [Dynamic Telemetry:](#dynamic-telemetry)
 10. [Issues and Troubleshooting](#issues-and-troubleshooting)
-    1. [Error viewing Devices on Azure&reg; Portal:](#error-viewing-devices-on-azure-portal)
+    1. [Error viewing Devices on Azure&reg; Portal:](#error-viewing-devices-on-azurereg-portal)
     2. [OTA Error Status](#ota-error-status)
     3. [Provisioning Unsuccessful or Device Not Connected to Cloud](#provisioning-unsuccessful-or-device-not-connected-to-cloud)
     4. [Acquiring Debug Messages from Agents](#acquiring-debug-messages-from-agents)
 
+</details>
+
 ## Introduction
 
 ### Audience

diff --git a/docs/In-Band Manageability User Guide - ThingsBoard.md b/docs/In-Band Manageability User Guide - ThingsBoard.md
@@ -1,65 +1,41 @@
 # User Guide – ThingsBoard&reg;
 
-## Table of Contents
+<details>
+<summary>Table of Contents</summary>
 
 1. [Introduction](#introduction)
     1. [Purpose](#purpose)
     2. [Audience](#audience)
-
-2. [ThingsBoard&reg; Overview](#thingsboard-overview)
-
-    1. [Getting Started with ThingsBoard&reg;](#getting-started-with-thingsboard)
-
+2. [ThingsBoard&reg; Overview](#thingsboardreg-overview)
+    1. [Getting Started with ThingsBoard&reg;](#getting-started-with-thingsboardreg)
     2. [Adding a Device](#adding-a-device)
-
     3. [Obtaining Device Credentials](#obtaining-device-credentials)
-
     4. [Creating a Device to Use X.509 Auth](#creating-a-device-to-use-x509-auth)
-
     5. [Provisioning a Device](#provisioning-a-device)
-
     6. [Setting up the Dashboards](#setting-up-the-dashboards)
-
-    7. [Getting Familiar with ThingsBoard&reg;](#getting-familiar-with-thingsboard)
-
+    7. [Getting Familiar with ThingsBoard&reg;](#getting-familiar-with-thingsboardreg)
     8. [Interacting with Individual Devices](#interacting-with-individual-devices)
-
     9. [Interacting with Multiple Devices](#interacting-with-multiple-devices)
-
     10. [Modifying and Working with Intel Manageability Widgets](#modifying-and-working-with-intel-manageability-widgets)
-
-3. [OTA commands](#ota-commands)
-
+3. [Commands](#commands)
     1. [Trusted Repositories](#trusted-repositories)
-
     2. [Preparing OTA Update Packages](#preparing-ota-update-packages)
-
     3. [OTA Updates](#ota-updates)
-
     3. [Configuration Update](#configuration-update)
-
     4. [Power Management](#power-management)
-
     5. [Decommission Command](#decommission-command)
-
     6. [Query Commands](#query-commands)
-
 4. [Telemetry Data](#telemetry-data)
-
     1. [Static Telemetry Data](#static-telemetry-data)
-
     2. [Dynamic Telemetry Data](#dynamic-telemetry-data)
-
     3. [Viewing Telemetry Data](#viewing-telemetry-data)
-
 5. [Issues and Troubleshooting](#issues-and-troubleshooting)
-
     1. [OTA Error Status](#ota-error-status)
-
     2. [Provisioning Unsuccessful or Device Not Connected to Cloud](#provisioning-unsuccessful-or-device-not-connected-to-cloud)
-
     3. [Acquiring Debug Messages from Agents](#acquiring-debug-messages-from-agents)
 
+</details>
+
 ## Introduction
 ### Purpose
 
@@ -579,7 +555,7 @@ limitation:
 - Device List is used to send a list of selected devices to OTA Form
     widgets for batch operations
 
-## OTA Updates
+## Commands
 
 After the In-Band Manageability Framework running on the Edge IoT Device
 is provisioned, it will establish a secure session with the ThingsBoard

diff --git a/docs/Terminology.md b/docs/Terminology.md
@@ -14,6 +14,7 @@
 | INBM   | Intel® In-Band Manageability Framework                                                                                                                                                                          |
 | IoT    | Internet of Things                                                                                                                                                                                              |
 | MQTT   | Message Queuing Telemetry Transport                                                                                                                                                                             |
+| MTLS   | Mutual Transport Layer Security                                                                                                                                                                                 |
 | OS     | Operating System                                                                                                                                                                                                |
 | OTA    | Over-the-air                                                                                                                                                                                                    |
 | PCIe   | Peripheral Component Interconnect Express                                                                                                                                                                       |
@@ -22,5 +23,6 @@
 | SMBIOS | System Management BIOS                                                                                                                                                                                          |
 | SoC    | System on a Chip                                                                                                                                                                                                |
 | SOTA   | Software Over the Air (OS update)                                                                                                                                                                               |
+| TPM    | Trusted Platform Module                                                                                                                                                                                         |
 | VPU    | Visual Processing Unit                                                                                                                                                                                          |
 | YAML   | Yet Another Markup Language                                                                                                                                                                                     |
diff --git a/docs/media/In-Band Manageability Developer Guide/media/image1.png b/docs/media/In-Band Manageability Developer Guide/media/image1.png
diff --git a/docs/media/In-Band Manageability Developer Guide/media/image3.png b/docs/media/In-Band Manageability Developer Guide/media/image3.png
diff --git a/docs/media/In-Band Manageability Developer Guide/media/image5.png b/docs/media/In-Band Manageability Developer Guide/media/image5.png
diff --git a/docs/media/In-Band Manageability Developer Guide/media/image6.png b/docs/media/In-Band Manageability Developer Guide/media/image6.png
diff --git a/docs/media/In-Band Manageability Developer Guide/media/image7.png b/docs/media/In-Band Manageability Developer Guide/media/image7.png
diff --git a/docs/media/In-Band Manageability Developer Guide/media/image8.png b/docs/media/In-Band Manageability Developer Guide/media/image8.png
diff --git a/inbm-vision/node-agent/node/broker.py b/inbm-vision/node-agent/node/broker.py
@@ -100,7 +100,7 @@ def _on_command(self, topic, payload, qos) -> None:
                          'request is in the correct format. {}'
                          .format(error))
 
-    def push_ota(self, manifest) -> None:
+    def push_ota(self, manifest: str) -> None:
         """push ota manifest to request channel
 
         @param manifest OTA manifest

diff --git a/inbm-vision/node-agent/node/command/command.py b/inbm-vision/node-agent/node/command/command.py
@@ -61,7 +61,8 @@ def execute(self):
 
 
 class RequestToDownloadCommand(Command):
-    """check system storage size to get the file download
+    """Check system storage size to determine if there is enough space
+       to download.  Send result back via xlink.
 
        @param nid : Node Device ID
        @param xlink_manager : Node Xlink Manager
@@ -79,7 +80,7 @@ def execute(self) -> None:
         self.xlink_manager.send(self._is_enough_space(self.download_size_kb))
 
     def _is_enough_space(self, download_size_kb) -> str:
-        # if it is flashless system, check free memory instead of storage
+        # if it is flash-less system, check free memory instead of storage
         free = get_free_memory() if is_flashless() else get_free_space()
         free_storage = free / 1024
         if free_storage > int(download_size_kb):

diff --git a/inbm-vision/node-agent/node/command/configuration_command.py b/inbm-vision/node-agent/node/command/configuration_command.py
@@ -51,7 +51,7 @@ def execute(self) -> None:
 
 
 class ConfigValuesCommand(Command):
-    """Call broker to publish get_config payload.
+    """Sends configuration result back to host via Xlink
 
        @param nid : id of the node
        @param xlink_manager : Node Xlink Manager
@@ -123,11 +123,11 @@ def execute(self):
 
 
 class LoadConfigCommand(Command):
-    """Call broker to publish get_config payload.
+    """Sends configuration load result back to host via Xlink
 
        @param nid : id of the node
        @param xlink_manager : Node Xlink Manager
-       @param config_mngr : Configuration Manager
+       @param config_mgr : Configuration Manager
        @param path: path to fetch the value from the conf file
     """
 

diff --git a/inbm-vision/node-agent/node/data_handler.py b/inbm-vision/node-agent/node/data_handler.py
@@ -71,7 +71,7 @@ def load_config_file(self) -> None:
         children = self._config.get_children(NODE)
         self.publish_config_value(children)
 
-    def receive_mqtt_message(self, payload) -> None:
+    def receive_mqtt_message(self, payload: str) -> None:
         """Publish message to vision-agent when receive message from EVENT_CHANNEL and TELEMETRY_CHANNEL"""
         command = SendTelemetryEventCommand(self._nid, self.node_callback.get_xlink(), payload)
         self._invoker.add(command)
@@ -309,7 +309,7 @@ def reset_heartbeat(self) -> None:
         self._heartbeat_interval = None
         self._retry_limit = 0
 
-    def downloaded_file(self, file_name, receive_status):
+    def downloaded_file(self, file_name, receive_status: bool) -> None:
         """Add Send_Download_Status_Name command into invoker if the OTA file exists
         @param file_name: relative filename from CACHE
         @param receive_status : File receive status

diff --git a/inbm-vision/node-agent/node/idata_handler.py b/inbm-vision/node-agent/node/idata_handler.py
@@ -18,12 +18,11 @@ class IDataHandler(ABC):
 
     @abstractmethod
     def register(self) -> None:
-        """Add register_command to invoker when node being initialize
+        """Add register_command to invoker when node is initialized
 
-        1. Called when Node being initialize  
+        1. Called when Node is initialized
         2. Create the RegisterCommand object
         4. Add the Command to Invoker
-
         """
 
         pass

diff --git a/inbm-vision/node-agent/node/inode.py b/inbm-vision/node-agent/node/inode.py
@@ -18,9 +18,7 @@
 
 
 class INode(ABC):
-    """Acts as the client in Node Pattern. It main function called when start node agent.
-    and initialize the broker, xlink_manager, data_handler and configuration_manager
-    """
+    """Interface for the Node class"""
 
     @abstractmethod
     def start(self) -> None:

diff --git a/inbm-vision/vision-agent/vision/node_communicator/ixlink_channel_connector.py b/inbm-vision/vision-agent/vision/node_communicator/ixlink_channel_connector.py
@@ -25,7 +25,7 @@ class IXlinkChannelConnector(ABC):
 
     @param data_handler: DataHandler object
     @param channel_list: List of private xlink channels
-    @params is_boot_device: True if boot device; otherwise, false
+    @param is_boot_device: True if boot device; otherwise, false
     """
 
     def __init__(self, data_handler: IDataHandler, channel_list: List[int], is_boot_device: bool) -> None:
@@ -136,7 +136,7 @@ class XlinkSimulatorConnector(IXlinkChannelConnector):
 
     @param data_handler: DataHandler object
     @param channel_list: List of private xlink channels
-    @params is_boot_device: True if boot device; otherwise, false
+    @param is_boot_device: True if boot device; otherwise, false
     """
 
     def __init__(self, data_handler: IDataHandler, channel_list: List[int], is_boot_device: bool) -> None:

diff --git a/inbm/trtl/README.md b/inbm/trtl/README.md
@@ -16,8 +16,8 @@ There are two ways to acquire trtl:
 
 * First method (recommended):
   * Set up ssh access to https://github.com/intel/intel-inb-manageability (see [Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh))
-  * Instruct your git to treat https urls to https://github.com/intel/intel-inb-manageability as ssh urls: 
-	  * run `git config --global url.ssh://[email protected]/intel/intel-inb-manageability insteadOf https://github.com/intel/intel-inb-manageability
+  * Instruct your git to treat https urls to https://github.com/intel/intel-inb-manageability as SSH urls: 
+	  * run `git config --global url.ssh://[email protected]/intel/intel-inb-manageability instead of https://github.com/intel/intel-inb-manageability
   * Acquire trtl: `go get -v intel-inb-manageability/inbm/trtl`
 
 * Second method: Go convention is to clone source into path matching repository.  
@@ -105,7 +105,7 @@ trtl [-type=docker] -cmd=commit -in=IMAGE_NAME -iv=IMAGE_VERSION
 ```
 ### Example
 ```
-Ex. trtl -cmd=commit -in=sample-container -iv=3
+trtl -cmd=commit -in=sample-container -iv=3
 ```
 
 ## ⚙️ ContainerCopy
@@ -199,11 +199,11 @@ trtl [-type=docker] -cmd=containerRemoveById
 
 ### Example
 #### Remove all container images with id=ABCD that are not running
-```
+```shell
 trtl -cmd=containerRemoveById -id=ABCD
 ```
 #### Remove all container images with id=ABCD (running or not)
-```
+```shell
 trtl -cmd=containerRemoveById -id=ABCD -f=true
 ```
 
@@ -212,7 +212,7 @@ trtl -cmd=containerRemoveById -id=ABCD -f=true
 Removes all container images. 
 
 ### Usage
-```
+```shell
 trtl [-type=docker] -cmd=containerRemoveAl} 
    [-f=FORCE (true | false); default=false] 
    [-in=IMAGE_NAME]