diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index 38d948e5b..8c22efcb6 100644 --- 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 index b6220e611..ebd5fec2a 100644 --- a/docs/In-Band Manageability Developer Guide.md +++ b/docs/In-Band Manageability Developer Guide.md @@ -1,24 +1,31 @@ # Developer Guide -## Table of Contents +
+Table of Contents 1. [Introduction](#introduction) 1. [Purpose](#purpose) 2. [Audience](#audience) -2. [Source Overview](#source-overview) - 1. [Agents Overview](#agents-overview) - 1. [CloudAdapter Agent](#cloudadapter-agent) - 2. [Configuration Agent](#configuration-agent) - 3. [Diagnostic Agent](#diagnostic-agent) - 4. [Dispatcher Agent](#dispatcher-agent) - 5. [Telemetry Agent](#telemetry-agent) - 6. [Vision Agent](#vision-agent) - 7. [Node Agent](#node-agent) - 2. [Run Agents via Source Code](#run-agents-via-source-code) -3. [Build instructions](#build-instructions) -4. [INBC](#INBC) -5. [Adding a New Configuration Parameter](#adding-a-new-configuration-parameter) -6. [Security](#security) +2. [Architecture](#architecture) + 1. [INB](#inb) + 1. [CloudAdapter Agent](#cloudadapter-agent) + 2. [Configuration Agent](#configuration-agent) + 3. [Diagnostic Agent](#diagnostic-agent) + 4. [Dispatcher Agent](#dispatcher-agent-dms) + 1. [OTA Update Class Diagram](#ota-update-class-diagram) + 5. [Telemetry Agent](#telemetry-agent) + 6. [TRTL](#trtl) + 2. [INBM Vision](#inbm-vision) + 1. [Vision Agent](#vision-agent) + 1. [Vision Agent Overall Class Diagram](#vision-agent-overall-class-diagram) + 2. [Vision Agent Registry Class Diagram](#vision-agent-registry-class-diagram) + 3. [Vision Agent Xlink Connectivity Class Diagram](#vision-agent-xlink-connectivity-class-diagram) + 2. [Node Agent](#node-agent) + 1. [Node Agent Class Diagram](#node-agent-class-diagram) + 3. [INBC](#inbc) +3. [Run Agents via Source Code](#run-agents-via-source-code) +6. [Add New Configuration Parameter](#add-new-configuration-parameter) +7. [Security](#security) 1. [OS Hardening](#os-hardening) 2. [INBM Hardening](#inbm-hardening) 1. [AppArmor Profiles](#apparmor-profiles) @@ -29,8 +36,8 @@ 6. [Manifest Schema Checks](#manifest-schema-checks) 7. [Docker Bench Security](#docker-bench-security) 8. [Platform TPM usage](#platform-tpm-usage) -7. [Enable Debug Logging](#enable-debug-logging) -8. [OTA Commands via Manifest](#ota-commands-via-manifest) +8. [Enable Debug Logging](#enable-debug-logging) +9. [OTA Commands via Manifest](#ota-commands-via-manifest) 1. [Manifest Rules](#manifest-rules) 2. [AOTA Updates](#aota-updates) 1. [AOTA Manifest Parameters](#aota-manifest-parameters) @@ -47,30 +54,28 @@ 7. [Power Management](#power-management) 1. [Restart via Manifest](#restart-via-manifest) 2. [Shutdown via Manifest](#shutdown-via-manifest) -9. [Extending FOTA support](#extending-fota-support) - 1. [Understanding FOTA Configuration File](#understanding-fota-configuration-file) - 2. [Firmware Configuration Parameter Values](#firmware-configuration-parameter-values) - 3. [Query command Manifest](#query-command-manifest) - 4. [AppArmor Permissions](#apparmor-permissions) -10. [Creating a New Agent](#creating-a-new-agent) -11. [Issues and Troubleshooting](#issues-and-troubleshooting) +10. [Extending FOTA support](#extending-fota-support) + 1. [Understanding FOTA Configuration File](#understanding-fota-configuration-file) + 2. [Firmware Configuration Parameter Values](#firmware-configuration-parameter-values) + 3. [Query command Manifest](#query-command-manifest) + 4. [AppArmor Permissions](#apparmor-permissions) +11. [Creating a New Agent](#creating-a-new-agent) +12. [Issues and Troubleshooting](#issues-and-troubleshooting) 1. [OTA Error Status](#ota-error-status) 2. [Dispatcher-Agent Not Receiving Messages](#dispatcher-agent-not-receiving-messages) - -Appendix -1. [Vision-agent Xlink Connectivity Class Diagram](#vision-agent-xlink-connectivity-class-diagram) +
## Introduction ### Purpose -This Developer Guide provides the reader instructions on how to navigate -and build the INBM source code. It also provides information that Manageability solution developers will find useful, for +It provides information that Manageability solution developers will find useful, for example: -- Configuration file composition -- How to enable logging -- Adding new Platform support for FW update capability -- Adding support to a new Cloud Backend and Communicating with the INBM framework +- Overall architecture +- Configuration file composition +- How to enable logging +- Adding new Platform support for FW update capability +- Adding support to a new Cloud Backend and Communicating with the INBM framework ### Audience @@ -79,81 +84,104 @@ This guide is intended for: - System Integrators administrating devices running the INBM Framework. | -## Source Overview +## Architecture + +The diagram below depicts the entire Intel Manageability Framework. There are three projects to the Framework. They can +either be used together or separately. The following are the 3 projects: +1. INB +2. INBM Vision (Only used on Intel Vision based HDDL solutions) +3. INBC (Optional command-line tool) + +P1189#yIS1 + +### INB +INB can be used in any of the three scenarios. + 1. Edge Device + 2. Host system of a Vision based HDDL solution + 3. SOC of a Flash-based Vision HDDL solution -INBM has seven different agents each with its own unique responsibility. +The diagram below depicts the overall architecture of INB. INB is one of the two projects within INBM. +It's responsibilities include: + - Communication with the Cloud + - Perform OTA updates (FOTA, SOTA, POTA, and AOTA) + - Diagnostic checks + - Telemetry (Static and Dynamic) -- Cloudadapter-agent +There are 5 Agents and 1 Binary associated with INB which all reside on the same system and communicate with one another via MQTT. +- Cloudadapter-agent (would not be used on SOC of a Vision based HDDL solution) - Configuration-agent - Diagnostic-agent - Dispatcher-agent - Telemetry-agent -- Vision (used with Intel Vision cards) -- Node (used with Intel Vision cards) +- TRTL (Binary Executable) -### Agents Overview - -The Vision and Node agents communicate with each other via Xlink. All other agents -communicate with the other agents using MQTT. +P1189#yIS1 #### ⚙️CloudAdapter Agent -The cloudadapter-agent relays the messages between the cloud and the dispatcher-agent via MQTT. +Relays MQTT messages between the cloud API and dispatcher-agent. #### ⚙️Configuration Agent -Configuration-agent publishes the config parameter values to all other agents. The parameters are stored in the ``/etc/intel_manageability.conf``` file. -The parameters and their descriptions can be found in the [Configuration Parameters](Configuration%20Parameters.md) reference. - - -The *broker.py* handles all config updates to be performed on the system. -The *configuration.py* starts the configuration agent. -The *xml_handler.py* contains the necessary functions required to -modify the XML conf file. -The *constants.py* contains all MQTT subscription and publishing -channels used by configuration-agent. +Publishes the configuration parameter values to all other agents. The parameters are stored in the ``/etc/intel_manageability.conf``` file. +The parameters and their descriptions can be found in the [Configuration Parameters](Configuration%20Parameters.md) reference. #### ⚙️Diagnostic Agent -Monitors and reports the state of critical components of the framework. This agent is responsible for performing all -diagnostic checks like system health checks. It requires software checks before installation, network checks, docker stats, docker-bench-security checks as such. These checks will be performed at timed intervals. These timed intervals can be altered by changing the interval seconds within the ```/etc/intel_manageability.conf``` file using configuration updates from cloud via button click or manifest update. Once the checks are completed, the result message is published to the cloud as telemetry. - -The *command_pattern.py* consists of all the commands/checks that are being handled by the diagnostic agent. -The *dispatch_command.py* dispatches correct command/checks based on the request. -The *docker_bench_security\_runner.py* runs the DockerBenchSecurity checks on the docker containers and images, while the *event\_watcher.py* watches for events from Docker. -The *repeating_timer.py* creates a timer that repeats for a given interval specified by the time-based checks. -The file *constants.py* contains all the MQTT subscription and publishing channels used by diagnostic-agent to communicate with other agents. -#### ⚙️Dispatcher Agent - -Dispatches and performs the received commands/operations from the cloud on the device. It is responsible for determining what kind of request is received from the cloud and invokes the respective commands/threads that would perform the desired operation. Once the operation is complete, the status of the operation will be published to the cloud by this agent. - -##### OTA update Class Diagram -When there is an OTA update, the Dispatcher class will call into an Abstract Factory pattern to create the correct concrete classes to perform the update. The update -can be for either a FOTA, SOTA, AOTA, or POTA. It will create the classes based on that. - -P1189#yIS1 +The Diagnostic-agent is responsible for the following: +- Perform diagnostic system health checks prior to an OTA install. +- Perform diagnostic check at timed intervals which can be altered by changing the interval seconds with the ```/etc/intel_manageability.conf``` file using configuration +updates. +- Publishing diagnostic results as Telemetry. + +The following checks may be performed: +- Network available +- Docker stats +- Docker-bench-security for container health +- Available memory +- Available storage +- Battery power (mobile systems) +- Required software installed + +#### ⚙️Dispatcher Agent (DMS) +The Dispatcher-agent is the central agent. It is responsible for the following: +- Dispatching and executing the received commands/operations from the cloud or INBC. Determines the type of request and invokes the respective commands/threads to perform the operation. +- Publishes the resulting status of the operation. + + ##### OTA Update Class Diagram + When there is an OTA update, the Dispatcher class will call into an [Abstract Factory pattern](https://en.wikipedia.org/wiki/Abstract_factory_pattern) to create the correct concrete classes to perform the update. The update + can be for either a FOTA, SOTA, AOTA, or POTA. It will create the classes based on that. + + P1189#yIS1 #### ⚙️Telemetry Agent -Publishes the system’s static and dynamic telemetry to the cloud. +The Telemetry-agent is responsible for the following: +- Collect and publish the system’s static telemetry information. +- Collect and publish dynamic telemetry information at configured intervals. -The broker.py initializes the agents publish/subscribe channels. +#### ⚙️TRTL +TRTL is a binary executable developed in Golang. It is a command-line tool which is also called internally in INB. It provides a wrapper around the API calls to Docker, Docker-Compose, and Snapper in order to provide the following: + - Uniform interface to install/rollback for back ends such as Docker, Docker-Compose, and Snapper. + - Ability to open a container to perform Docker-bench-security checks + - Container management + - Create + - Remove + - Snapshot + - Rollback + - List + - [List of Commands](https://github.com/intel/intel-inb-manageability/blob/develop/inbm/trtl/README.md) -The *container_usage.py* has code that gets the container stats on a -device. + #### TRTL High Level Class Diagram + TRTL parses the incoming command and then creates the concrete class based on the type of command (docker, compose, btrfs). It will then activate the designated command. + P1189#yIS1 -The *dynamic_attributes.py* contains functions that retrieve dynamic -telemetry information such as disk_usage, cpu percentage, network -telemetry, and available memory, +### INBM Vision -The *static_attributes.py* have function that gets the device’s static -telemetry information such as cpu_id, disk information, and total -physical memory, +The INBM Vision solution is only used in a Vision based HDDL solution. There are 2 Agents/Services associated with INBM Vision. Unlike INB these agents reside separately on different systems. +- Vision-agent (resides on the Host system only) +- Node-agent (resides on the SOC system only) -The *telemetry_handling.py* is responsible for calling the necessary -telemetry events upon time-intervals and then publishing the information -on to the cloud and other agents when needed. +Both agents use the [Command Design Pattern](https://en.wikipedia.org/wiki/Command_pattern) as their overall design. -The file *constants.py* contains all the MQTT subscription and -publishing channels used by telemetry-agent to communicate with other -agents. +The Vision and Node agents communicate with each other via Xlink. #### ⚙️Vision Agent The Vision-agent resides on the Host side of a system utilizing Intel Vision cards. It manages all communication with the individual vision cards. It is responsible for the following: @@ -161,22 +189,78 @@ The Vision-agent resides on the Host side of a system utilizing Intel Vision car - Manage the communication status of each Vision card. Try and reconnect if communication is lost. - Determine what Vision cards should receive the update if no targets are requested in the manifest. - Verify that a requested target is eligible for the requested OTA update. +- Push OTA files to targeted nodes. +- Push OTA manifest to targeted nodes. +- Parse Xlink messages from nodes +- Create Xlink messages for nodes +- Push configuration values to nodes via xlink - Publish Telemetry events and results received from Vision cards -The Xlink code used by the Vision-agent uses several classes and two Abstract Factory design patterns. The class diagram of how these classes interact -can be found in the [Appendix](#vision-agent-xlink-connectivity-class-diagram). +
+Vision Agent Class Diagrams + +##### Vision Agent Overall Class Diagram +The Vision Agent uses the [Command Design Pattern](https://en.wikipedia.org/wiki/Command_pattern) as the overall design with the following Participants: +- Command = Command class +- ConcreteCommand = Everything inheriting from the Command class +- Client = DataHandler classes +- Invoker = Invoker class +- Receiver = NodeConnector, Broker, RegistryManager, Updater + +P1189#yIS1 + +##### Vision-agent Registry Class Diagram +The Registry class used by the RegistryManager: + +P1189#yIS1 + +##### Vision-agent Xlink Connectivity Class Diagram + +The Vision Agent communicates with the Node Agent over PCIe using Xlink. The Xlink code uses several classes and two +Abstract Factory design patterns. The class diagram of how these classes interact is below: + +P1189#yIS1 + +
#### ⚙️Node Agent The Node-agent resides on each of the individual Intel Vision cards. It manages the communication of each vision card via Xlink. It is responsible for the following: - Registering with the Vision-agent on startup with its hardware, firmware, operating system, and security information - Sending a heartbeat to the Vision-agent at the set interval (received as a registration response message from the Vision-agent) -- Try and reconnect with Vision-agent if communication is lost. +- Reconnect with Vision-agent if communication is lost. - Download OTA update file via Xlink from Vision-agent - Download Configuration load file via Xlink from Vision-agent - Receive updated manifest from Vision-agent via Xlink and publish it to the Dispatcher-agent via MQTT for OTA updates and configuration requests. - Relay Telemetry events and results to the Vision-agent via Xlink -### Run Agents via Source Code +The Node Agent communicates with the Vision Agent over PCIe using Xlink. The Xlink code uses several classes and two Abstract Factory design patterns. The class diagram of how these classes interact +can be found in the [Appendix](#vision-agent-xlink-connectivity-class-diagram). + +##### Node Agent Class Diagram +The Vision Agent uses the [Command Design Pattern](https://en.wikipedia.org/wiki/Command_pattern) as the overall design with the following Participants: +- Command = Command class +- ConcreteCommand = Everything inheriting from the Command class +- Client = DataHandler classes +- Invoker = Invoker class +- Receiver = XLinkManager, Broker + +P1189#yIS1 + +### INBC + +INBC is a command-line based tool that can be used instead of the cloud to perform the following: +- OTA update +- View/Change Configuration settings +- Query system data +- Restart SOC + +INBC uses the Python 'argparse' library to parse the command-line arguments. Based on those arguments it will use +the Factory Design Pattern to create the correct concrete 'Command' class. + +P1189#yIS1 + + +## Run Agents via Source Code To run and test the agents after modifying the source code, the developer is required to run the script *dev-mode.sh* located under the **applications.manageability.inband-manageability.iotg-manageability/inbm** directory. @@ -214,57 +298,10 @@ the command make logging LEVEL=DEBUG ``` -or refer to [Section 5](#security) to enable logging prior to running +or refer to [Security](#security) to enable logging prior to running the INBM via source code. - -## Build instructions - -Developers can build INBM executables if source is provided as -part of the release package. - -To successfully build the INBM source code, the user would need to execute -the following commands, to make sure the scripts have the executable -access: -```shell -cd applications.manageability.inband-manageability.iotg-manageability/inbm - -find . -type f -iname configure -exec chmod +x {} \\; - -find . -type f -iname "\*.sh" -exec chmod +x {} \\; - -chmod -R 755 trtl/scripts/ -``` -The user should be able to build the source from the directory -**applications.manageability.inband-manageability.iotg-manageability/inbm** using the command. - -Docker needs to be installed on the system to build the code. - -```shell -./build.sh -``` - -or the following command can also be used for better build performance: - -```shell -DOCKER_BUILDKIT=1 ./build.sh -``` - -When the build is complete, the build output can be found in the -**turtlecreek/source/output** folder. - -## INBC - -INBC is a command-line tool that allows the user to perform OTA and configuration commands from the Edge or -Host (Intel Vision card solution) system instead of from the cloud. - -### INBC Class Diagram -INBC uses the Python 'argparse' library to parse the command-line arguments. Based on those arguments it will use -the Factory Design Pattern to create the correct concrete 'Command' class. - -P1189#yIS1 - -## Adding a New Configuration Parameter +## Add New Configuration Parameter There may be scenarios where new configurations are required to be added to extend the functionality of the INBM framework. For example, @@ -282,8 +319,7 @@ to accommodate this health check tag with a certain value by following these ste ~/inbm/configuration-agent/fpm-template/usr/share/configuration-agent/iotg_inb_schema.xsd ``` -3. (a) Test the changes by creating a new build using the build instructions mentioned in [Section - 3](#build-instructions). Uninstall and reinstall INBM from the output folder after the build is complete. +3. (a) Test the changes by creating a new build using the [build instructions](https://github.com/intel/intel-inb-manageability/blob/develop/README.md). Uninstall and reinstall INBM from the output folder after the build is complete. (Or) @@ -427,7 +463,7 @@ for each agent by changing **ERROR** to **DEBUG** with a text editor. These *lo #### Option 1 (single agent): 1. Open the logging file: ```shell -vi /etc/intel-manageability/public/\-agent/logging.ini +sudo vi /etc/intel-manageability/public/\-agent/logging.ini ``` 2. Change the value **ERROR** to **DEBUG** @@ -857,7 +893,7 @@ sudo systemctl stop mqtt ``` Step 2: -```sehell +```shell rm /var/lib/mosquitto/mosquitto.db ``` @@ -865,11 +901,3 @@ Step 3: ```shell sudo systemctl start mqtt ``` - -## Appendix - -### Vision-agent Xlink Connectivity Class Diagram - -Below is the class diagram showing how the different classes in the Vision-agent work together to send and receive communication with the individual node-agents. The xlink classes can be found in the source under both the *inbm-vision/vision-agent/vision/node_communicator* and */inbm-lib/inbm_vision_lib/xlink* directories. The classes under the inbm-lib are also used by the node-agent for xlink communication. Those classes are in green in the diagram below. - -P1189#yIS1 diff --git a/docs/In-Band Manageability Installation Guide Ubuntu.md b/docs/In-Band Manageability Installation Guide Ubuntu.md index 2e872c1e9..01fb501d4 100644 --- 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 index c8be75822..a82c16f25 100644 --- 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® -## Contents +
+Table of Contents -1. [Contents](#contents) -2. [Introduction](#introduction) +1. [Introduction](#introduction) 1. [Audience](#audience) -3. [Azure® Overview](#azure-overview) - 1. [Getting Started with Azure®](#getting-started-with-azure) - 1. [Creating Azure® portal account](#creating-azure-portal-account) - 2. [Setting up an Azure® IoT Central Application ](#setting-up-an-azure-iot-central-application-) - 3. [Accessing Azure®](#accessing-azure) +3. [Azure® Overview](#azurereg-overview) + 1. [Getting Started with Azure®](#getting-started-with-azurereg) + 1. [Creating Azure® portal account](#creating-azurereg-portal-account) + 2. [Setting up an Azure® IoT Central Application ](#setting-up-an-azurereg-iot-central-application) + 3. [Accessing Azure®](#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,7 +22,7 @@ 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) @@ -30,7 +30,7 @@ 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® Portal:](#error-viewing-devices-on-azure-portal) + 1. [Error viewing Devices on Azure® 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) +
+ ## Introduction ### Audience diff --git a/docs/In-Band Manageability User Guide - ThingsBoard.md b/docs/In-Band Manageability User Guide - ThingsBoard.md index 9dce22f3a..c8574667c 100644 --- 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® -## Table of Contents +
+Table of Contents 1. [Introduction](#introduction) 1. [Purpose](#purpose) 2. [Audience](#audience) - -2. [ThingsBoard® Overview](#thingsboard-overview) - - 1. [Getting Started with ThingsBoard®](#getting-started-with-thingsboard) - +2. [ThingsBoard® Overview](#thingsboardreg-overview) + 1. [Getting Started with ThingsBoard®](#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®](#getting-familiar-with-thingsboard) - + 7. [Getting Familiar with ThingsBoard®](#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) +
+ ## 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 index 70f6abb06..ddb6e7b05 100644 --- 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 new file mode 100644 index 000000000..ad63ae913 Binary files /dev/null and b/docs/media/In-Band Manageability Developer Guide/media/image1.png differ diff --git a/docs/media/In-Band Manageability Developer Guide/media/image3.png b/docs/media/In-Band Manageability Developer Guide/media/image3.png new file mode 100644 index 000000000..edaaad79e Binary files /dev/null and b/docs/media/In-Band Manageability Developer Guide/media/image3.png differ diff --git a/docs/media/In-Band Manageability Developer Guide/media/image5.png b/docs/media/In-Band Manageability Developer Guide/media/image5.png new file mode 100644 index 000000000..40ee7ea18 Binary files /dev/null and b/docs/media/In-Band Manageability Developer Guide/media/image5.png differ diff --git a/docs/media/In-Band Manageability Developer Guide/media/image6.png b/docs/media/In-Band Manageability Developer Guide/media/image6.png new file mode 100644 index 000000000..861a356c9 Binary files /dev/null and b/docs/media/In-Band Manageability Developer Guide/media/image6.png differ diff --git a/docs/media/In-Band Manageability Developer Guide/media/image7.png b/docs/media/In-Band Manageability Developer Guide/media/image7.png new file mode 100644 index 000000000..a328b9464 Binary files /dev/null and b/docs/media/In-Band Manageability Developer Guide/media/image7.png differ diff --git a/docs/media/In-Band Manageability Developer Guide/media/image8.png b/docs/media/In-Band Manageability Developer Guide/media/image8.png new file mode 100644 index 000000000..ff7bc15c5 Binary files /dev/null and b/docs/media/In-Band Manageability Developer Guide/media/image8.png differ diff --git a/inbm-vision/node-agent/node/broker.py b/inbm-vision/node-agent/node/broker.py index ce2a36335..dcfc72526 100644 --- 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 index bcae41e83..c004cccc6 100644 --- 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 index dd28b13a3..2d9130a3b 100644 --- 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 index af1fbc280..40daa7651 100644 --- 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 index 5370d044b..99a25d49b 100644 --- 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 index 676675589..0d700e7a8 100644 --- 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 index ae8d02871..21400c519 100644 --- 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 index 114e4b0e1..13660e052 100644 --- 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://git@github.com/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://git@github.com/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]