Contents

Contents

About Edge Insights for Industrial

Edge Insights for Industrial (EII) is a set of pre-validated ingredients for integrating video and time series data analytics on edge compute nodes. EII includes modules to enable data collection, storage, and analytics for both time series and video data.

Note

In this document, you will find labels of Edge Insights for Industrial (EII) for file names, paths, code snippets, and so on.

Minimum System Requirements

The following are the minimum system requirements to run EII:

System Requirement	Details
Processor	8th generation Intel® CoreTM processor onwards with Intel® HD Graphics or Intel® Xeon® processor
RAM	Minimum 16 GB
Hard drive	Minimum 128 GB and Recommended 256 GB
Operating system	Ubuntu 22.04

Note

To use EII, ensure that you are connected to the internet.
The recommended RAM capacity for the Video Analytics pipeline is 16 GB. The recommended RAM for the Time Series Analytics pipeline is 4 GB with Intel® Atom processors.
EII is validated on Ubuntu 22.04. You can install EII stack on other Linux distributions with support for docker-ce.

Install Edge Insights for Industrial from innersource github

Install Prerequisites

The pre_requisites.sh script automates the installation and configuration of all the prerequisites required for building and running the EII stack. The prerequisites are as follows:

docker daemon
docker client
Python packages

The pre-requisites.sh script performs the following:

Checks if docker is installed in the system. If required, it uninstalls the older version and installs the correct version of docker.
Configures the proxy settings for the docker client and docker daemon to connect to the internet.
Configures the proxy settings system-wide (/etc/environment) and for docker. If a system is running behind a proxy, then the script prompts users to enter the proxy address to configure the proxy settings.
Configures proxy setting for /etc/apt/apt.conf to enable apt updates and installations.
Removes the proxy configurations done if unable to connect to internet with proxy configurations.
Removes proxy configuration from the system.

Note

After modifying the docker-compose.yml file, refer to the Using the Builder script section. Before running the services using the docker compose up command or ./run.sh script, rerun the builder.py script.

Run the Prerequisites Script

To run the prerequisite script, execute the following commands:

cd [WORKDIR]/IEdgeInsights/build
sudo -E ./pre_requisites.sh --help
  Usage :: sudo -E ./pre_requisites.sh [OPTION...]
  List of available options...
  --proxy         proxies, required when the gateway/edge node running EII (or any of EII profile) is connected behind proxy
  --help / -h         display this help and exit

Note

If the –proxy option is not provided, then script will run without proxy and will remove the proxy configuration done on system. Different use cases are as follows:

Runs without proxy to remove the proxy setup done on system.
```
sudo -E ./pre_requisites.sh
```

Runs with proxy

sudo -E ./pre_requisites.sh --proxy="proxy.intel.com:891"

All the steps from link and below would be required to configure, build and deploy the services

Install Edge Insights for Industrial from Edge Software Hub (ESH) portal

During the installation, you will be prompted to enter your product key. This key is in the email you received from the Intel® Registration Center. Contact Support Forum if you do not have this email message.

The steps below explain how to:

Prepare your target system.
Copy the package.
Complete the installation steps.

NOTE The screenshots may show a package version number that is different from the current release.

Step 1: Prepare the Target System Ensure that your target system has a fresh installation of Ubuntu* Linux that corresponds to the version of Edge Insights for Industrial that you downloaded. To install Ubuntu* Linux, follow these steps:

Download Ubuntu* Linux* Desktop ISO file to your developer workstation.
Use an imaging application to create a bootable flash drive.
Power off your target system, insert the USB drive, and power on the system. If the target system does not boot from the USB drive, change the boot priority in the system BIOS.
Follow the prompts to install Ubuntu* Linux with the default configurations. For detailed instructions, see the Ubuntu guide.
Power down your target system and remove the USB drive.
Power up the target system. Ubuntu* Linux is now installed.
Log on as the root user: su root

Step 2: Download and Copy the Edge Insights for Industrial .zip File to the Target System In this step, you download the package and copy Edge Insights for Industrial to your target system.

Download the Edge Insights for Industrial package.
Copy edge_insights_industrial.zip from the developer workstation to the Home directory on your target system. You can use a USB flash drive to copy the file. The icon looks like this:

Step 3: Extract the Edge Insights for Industrial Software In this step, you extract edge_insights_industrial.zip. You must be on the target system to complete these steps.

Ensure that you have a working internet connection.
Open a new terminal.
Extract the package: unzip edge_insights_industrial.zip NOTE: If you download the file more than once, every download is appended by a number.
Optional - Use the link in the readme file to open this Get Started Guide on the target system for an easy way to copy and paste commands.

Step 4: Configure your Installation This is a mandatory step. You can use the config_install.yml file to configure the installation behavior of the components in your target system.

You can modify the config_install.yml per your requirements using the following information:

Edge Insights for Industrial

dev_mode: This key sets your installation mode. Set the key value as follows: true: This value enables the Production mode which is the default mode. Security and encryption are enabled in this mode and is commonly used for deployment. false: This value enables the Development mode. Security and encryption are disabled in this mode. This mode is commonly used during evaluation and development as it eases the integration and testing of User Defined Applications.
remove_previous_eii: Set this key value as ‘true’ if you want to remove the already existing containers of Edge Insights for Industrial previous installation.

default_use_case: If you have downloaded the full Video Analytics + Time Series Edge Insights for Industrial package, you can set the type of use case you want to install using this key value as below:

* video-timeseries: Includes modules for video and timeseries, i.e., the full use-case.
* video: Includes only video modules and adds databases for storing images and metadata of analytics results.
* time-series: Includes modules for time-series data ingestion, storage and analytics.

etcdroot_password: Updates the etcdroot password credential.
influxdb_username: If the downloaded edgesoftware_configuration.xml file contains the InfluxDBConnector module. Set the username credential value. The following special characters are not allowed for the influxdbusername ~:’+[/@^{%(-“*|,&<`}.=}!>;?#$)
influxdb_password: If the downloaded edgesoftwareconfiguration xml file contains the InfluxDBConnector module. Set the password credential value. The following special characters are not allowed for the influxdb__password ~:’+[/@^{%(-“*|,&<`}.=}!>;?#$)
minio_access_key: If the downloaded edgesoftware_configuration.xml file contains ImageStore module. Set the access key credential value. The minio_access_key length must be a minimum of 8 characters.
minio_secret_key: If the downloaded edgesoftware_configuration.xml file contains ImageStore module. Set the secret key credential value. The minio_secret_key length must be a minimum of 8 characters.

Step 5: Install the Edge Insights for Industrial Software

NOTE: If you are running behind a proxy server, ensure that the proxy settings are configured correctly. The edge software tool uses these proxy settings to download and install the modules.

You will now run a script that will download components and install Edge Insights for Industrial on your target system. The software installation can take 1 to 3 hours depending on the package you chose. The completion time depends on your target system and Internet connection.

Run these commands: cd edge_insights_industrial/ chmod 775 edgesoftware ./edgesoftware install

NOTE: If you encounter any Docker* pull-related issues during the installation process, refer to the Troubleshooting section at the end of this document.

Type the product key at the prompt.

See the Edge Insights for Industrial based Reference Implementation (RI) tutorial requirements:

RI Tutorial: Defect Detection Demo
Applicable Use Case : Video Analytics or Video Analytics and Time series
Requirement: Download the installer package through the Download Recommended Configuration option by choosing one of the use cases in the Edge Insights for Industrial package.

Based on components selected and system configuration, you might be prompted for additional actions if you have not configured the config_install.yml file correctly. When the installation is complete, you see the message Installation of package complete and the installation status for each module.

NOTE: For Time series or Video Analytics and Time series use cases, the demo for time series does not start automatically, unlike the video use case. Follow the step below to see the time series demonstration:

Launch Grafana to see the time series visualization. For details, refer to Readme information.

Steps for Manual Installation of Manageability Module

NOTE: Manageability is downloaded by default, but not auto-installed.

Go to edge_insights_industrial/Edge_Insights_forIndustrial/manageability/ where indicates the downloaded version of Edge Insights for Industrial.
Refer to the steps in README.md for manual installation of manageability component.

If required, you can enable full security for production deployments. Ensure that the host machine and docker daemon are configured per the security recommendation. For more info, see build/docker_security_recommendation.md.
If required, you can enable log rotation for docker containers using any of the following methods:

Set the logging driver as part of the docker daemon. This applies to all the docker containers by default.

Configure the json-file driver as the default logging driver. For more info, see JSON File logging driver. The sample json-driver configuration that can be copied to /etc/docker/daemon.json is as follows:
```
  {
    "log-driver": "json-file",
    "log-opts": {
    "max-size": "10m",
    "max-file": "5"
    }
}
```
Run the following command to reload the docker daemon:
```
sudo systemctl daemon-reload
```
Run the following command to restart docker:
```
sudo systemctl restart docker
```

Set logging driver as part of docker compose which is container specific. This overwrites the first option (i.e /etc/docker/daemon.json). The following example shows how to enable the logging driver only for the video_ingestion service:

  ia_telegraf:
    ...
    ...
    logging:
      driver: json-file
      options:
      max-size: 10m
max-file: 5

After downloading EII from the release package or git, run the commands mentioned in this section from the [WORKDIR]/IEdgeInsights/build/ directory.

To run the builder.py script, complete the prerequisite by entering the values for the following keys in build/.env:

ETCDROOT_PASSWORD – The value for this key is required if you are using the ConfigMgrAgent service.
INFLUXDB_USERNAME, INFLUXDB_PASSWORD, MINIO_ACCESS_KEY, and MINIO_SECRETKEY – The values for these keys are required if you are using the Data Store service. Special characters such as “~:’+[/@^{%(-“*|,&<}.=}!>;?#$)" are not allowed for INFLUXDB_USERNAME and INFLUXDB_PASSWORD. The MINIO_ACCESS_KEY and the MINIO_SECRET_KEY length must be a minimum of 8 characters. If you enter wrong values or do not enter the values for the keys, the builder.py script prompts for corrections or values.

To use the builder.py script, run the following command:

python3 builder.py -h
usage: builder.py [-h] [-f YML_FILE] [-v VIDEO_PIPELINE_INSTANCES]
                    [-d OVERRIDE_DIRECTORY] [-s STANDALONE_MODE] [-r REMOTE_DEPLOYMENT_MODE]
optional arguments:
    -h, --help            show this help message and exit
    -f YML_FILE, --yml_file YML_FILE
                        Optional config file for list of services to include.
                        Eg: python3 builder.py -f video-streaming.yml (default: None)
    -v VIDEO_PIPELINE_INSTANCES, --video_pipeline_instances VIDEO_PIPELINE_INSTANCES
                        Optional number of video pipeline instances to be
                        created.
                        Eg: python3 builder.py -v 6 (default: 1)
    -d OVERRIDE_DIRECTORY, --override_directory OVERRIDE_DIRECTORY
                        Optional directory consisting of benchmarking
                        configs to be present in each app directory.
                        Eg: python3 builder.py -d benchmarking (default: None)
    -s STANDALONE_MODE, --standalone_mode STANDALONE_MODE
                        Standalone mode brings in changes to support independently
                        deployable services.
                        Eg: python3 builder.py -s True (default: False)
    -r REMOTE_DEPLOYMENT_MODE, --remote_deployment_mode REMOTE_DEPLOYMENT_MODE
                        Remote deployment mode brings in changes to support remote deployment
                        wherein builder does not auto-populate absolute paths of build
                        related variables in the generated docker-compose.yml
                        Eg: python3 builder.py -r True (default: False)

Using the Builder tool, EII auto-generates the configuration files that are required for deploying the EII services on a single node or multiple nodes. The Builder tool auto-generates the consolidated files by getting the relevant files from the EII service directories that are required for different EII use-cases. The Builder tool parses the top-level directories excluding EdgeVideoAnalyticsMicroservice under the IEdgeInsights directory to generate the consolidated files.

The following table shows the list of consolidated files and their details:

Table: Consolidated files

File Name	Description
docker-compose.yml	Consolidated `docker-compose.yml` file used to launch the EII docker containers in each single node using the `docker-compose` tool.
docker-compose.override.yml	Consolidated `docker-compose-dev.override.yml` of every app that is generated only in the DEV mode for the EII deployment on a given single node using the `docker-compose` tool.
eii_config.json	Consolidated `config.json` of every app that will be put into etcd during provisioning.
values.yaml	Consolidated `values.yaml` of every app inside the helm-eii/eii-deploy directory that is required to deploy the EII services via helm.
Template yaml files	Files copied from the helm/templates directory of every app to the helm-eii/eii-deploy/templates directory that is required to deploy EII services via helm.

Note

If you modify an individual EII app OR service directory file OR build/.env([WORK_DIR]/IEdgeInsights/build/.env) file, then ensure to rerun the builder.py script before running the EII stack to regenerate the updated consolidated files.
Manual editing of consolidated files is not recommended. Instead modify the respective files in the EII app or service directories and use the builder.py script to generate the consolidated files.
Enter the secret credentials in the # Service credentials section of the .env([WORK_DIR]/IEdgeInsights/build/.env) file if you are trying to run that EII app/service. If the required credentials are not present, the builder.py script would be prompting until all the required credentials are entered. Apply a file access mask to protect the .env([WORK_DIR]/IEdgeInsights/build/.env) file from being read by unauthorized users.
The builder_config.json([WORK_DIR]/IEdgeInsights/build/builder_config.json) is the config file for the builder.py script and it contains the following keys:
- subscriber_list: This key contains a list of services that act as a subscriber to the stream being published.
- publisher_list: This key contains a list of services that publishes a stream of data.
- include_services: This key contains the mandatory list of services. These services should be included when the Builder is run without the -f flag.
- exclude_services: This key contains the mandatory list of services. These services should be excluded when the Builder is run without the -f flag.
- increment_rtsp_port: This is a Boolean key. It increments the port number for the RTSP stream pipelines.

To generate the consolidated files, run the following command:

python3 builder.py

Builder uses a yml file for configuration. The config yml file consists of a list of services to include. You can mention the service name as the path relative to IEdgeInsights or full path to the service in the config yml file. To include only a certain number of services in the EII stack, you can add the -f or yml_file flag of builder.py. You can find the examples of yml files for different use cases as follows:

Azure([WORK_DIR]/IEdgeInsights/build/usecases/video-streaming-azure.yml)

The following example shows running Builder with the -f flag:
```
python3 builder.py -f usecases/video-streaming.yml
```
Main Use Cases

Use case	yaml file
Video + Time Series	build/usecases/video-timeseries.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/video-timeseries.yml`)
Video	build/usecases/video.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/video.yml`)
Time Series	build/usecases/time-series.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/time-series.yml`)

Video Pipeline Sub Use Cases

Use case	yaml file
Video streaming with EVAM	build/usecases/video-streaming-evam.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/video-streaming-evam.yml`)
Video streaming and historical	build/usecases/video-streaming-evam-datastore.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/video-streaming-evam-datastore.yml`)
Video streaming with AzureBridge	build/usecases/video-streaming-azure.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/ video-streaming-azure.yml`)
Video streaming with DataCollection	build/usecases/video-streaming-dcaas-evam-datastore.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/video-streaming-dcaas-evam-datastore.yml`)
Video streaming with ModelRegistry	build/usecases/evam-datastore-model-registry.yml(`[WORK_DIR]/IEdgeInsights/build/usecases/evam-datastore-model-registry.yml`)

When you run the multi-instance config, a build/multi_instance directory is created in the build directory. Based on the number of video_pipeline_instances specified, that many directories of EdgeVideoAnalyticsMicroservice are created in the build/multi_instance directory.

The following section provides an example for running the Builder to generate the multi-instance boiler plate config for 3 streams of video-streaming use case.

If required, you can generate the multi-instance docker-compose.yml and config.json files using the Builder. You can use the -v or video_pipeline_instances flag of the Builder to generate boiler plate config for the multiple-stream use cases. The -v or video_pipeline_instances flag creates the multi-stream boiler plate config for the docker-compose.yml and eii_config.json files.

The following example shows running builder to generate the multi-instance boiler plate config for 3 streams of video-streaming use case:

python3 builder.py -v 3 -f usecases/video-streaming-evam.yml

Using the previous command for 3 instances, the build/multi_instance directory consists of the following directories

EdgeVideoAnalyticsMicroservice1
EdgeVideoAnalyticsMicroservice2
EdgeVideoAnalyticsMicroservice3

Initially each directory will have the default config.json and the docker-compose.yml files that are present within the EdgeVideoAnalyticsMicroservice/eii directory.

      ./build/multi_instance/
      |-- EdgeVideoAnalyticsMicroservice1
      |   |-- config.json
      |   `-- docker-compose.yml
      |-- EdgeVideoAnalyticsMicroservice2
      |   |-- config.json
      |   `-- docker-compose.yml
      |-- EdgeVideoAnalyticsMicroservice3
      |   |-- config.json
      |   `-- docker-compose.yml

You can edit the config of each of these streams within the ``build/multi_instance`` directory. To generate the consolidated ``docker compose`` and ``eii_config.json`` file, rerun the ``builder.py`` command.

Note

The multi-instance feature support of Builder works only for the video pipeline that is the usecases/video-streaming.yml and video-streaming-evam.yml use case and not with any other use case yml files like usecases/video-streaming-storage.yml and so on. Also, it doesn’t work for cases without the -f switch. The previous example will work with any positive number for -v.
If you are running the multi-instance config for the first time, it is recommended not to change the default config.json file and the docker-compose.yml file in the EdgeVideoAnalyticsMicroservice/eii directory.
If you are not running the multi-instance config for the first time, the existing config.json and docker-compose.yml files in the build/multi_instance directory will be used to generate the consolidated eii-config.json and docker-compose files. If you want to use config.json and docker-compose.yml files from EdgeVideoAnalyticsMicroservice/eii directory then delete the build/multi_instance directory.
The docker-compose.yml files present within the build/multi_instance directory will have the following:
- the updated service_name, container_name, hostname, AppName, ports and secrets for that respective instance.
The config.json file in the build/multi_instance directory will have the following:
- the updated Name, Type, Topics, Endpoint, PublisherAppname, ServerAppName, and AllowedClients for the interfaces section.
- the incremented RTSP port number for the config section of that respective instance.
Ensure that all containers are down before running the multi-instance configuration. Run the docker compose down -v command or before running the builder.py script for the multi-instance configuration.

To provide a different set of docker-compose.yml and config.json files than those found in each service directory, use the -d or the override directory flag. The -d flag instructs the program to look in the specified directory for the necessary set of files.

For example, to pick files from a directory named benchmarking, you can run the following command:

python3 builder.py -d benchmarking

Note

If you use the override directory feature of the builder then include all the 3 files mentioned in the previous example. If you do not include a file in the override directory, then the Builder will omit that service in the final config that is generated.
Adding the AppName of the subscriber container or client container in the subscriber_list of builder_config.json allows you to spawn a single subscriber container or client container that is subscribing or receiving on multiple publishers or server containers.
Multiple containers specified by the -v flag is spawned for services that are not mentioned in the subscriber_list. For example, if you run Builder with –v 3 option and Visualizer is not added in the subscriber_list of builder_config.json then 3 instances of Visualizer are spawned. Each instance subscribes to 3 VideoAnalytics services. If Visualizer is added in the subscriber_list of builder_config.json, a single Visualizer instance subscribing to 3 multiple VideoAnalytics is spawned.

Note

For running the EII services in the IPC mode, ensure that the same user is mentioned in the publisher services and subscriber services.
If the publisher service is running as root such as EVAM, then the subscriber service should also run as root. For example, in the docker-compose.ymlfile, if you have specified user: ${EII_UID} in the publisher service, then specify the same user: ${EII_UID} in the subscriber service. If you have not specified a user in the publisher service, then don’t specify the user in the subscriber service.
If services need to be running in multiple nodes in the TCP mode of communication, msgbus subscribers, and clients of AppName are required to configure the EndPoint in config.json with the HOST_IP and the PORT under Subscribers/Publishers or Clients/Servers interfaces section.
Ensure that the port is being exposed in the docker-compose.yml of the respective AppName. For example, if the "EndPoint": <HOST_IP>:65012 is configured in the config.json file, then expose the port 65012 in the docker-compose.yml file of the ia_edge_video_analytics_microservice service.

ia_edge_video_analytics_microservice:
  ...
  ports:
    - 65012:65012

Run all the following EII build and commands from the [WORKDIR]/IEdgeInsights/build/ directory. EII supports the following use cases to run the services mentioned in the docker_compose.yml file. Refer to the Task 2 to generate the docker_compose.yml file for a specific use case. For more information and configuration, refer to the [WORK_DIR]/IEdgeInsights/README.md file.

All the EII services are aligning with the Microservice architecture principles of being Independently buildable and deployable.
Independently buildable and deployable feature is useful in allowing users to pick and choose only one service to build or deploy.
If one wants to run two or more microservices, we recommend to use the use-case driven approach as mentioned in Generate Consolidated Files for a Subset of Edge Insights for Industrial Services.

The Independently buildable and deployable feature allows the users to build the individual service at the directory level and also allows the users to deploy the service in either of the two ways:

Without ConfigMgrAgent dependency:

- Deployment without ConfigMgrAgent dependency is only available in DEV mode where we make use of the ConfigMgr library config file APIs, by setting the `READ_CONFIG_FROM_FILE_ENV` value to `true` in the .env(`[WORK_DIR]/IEdgeInsights/build/.env`) file.

NOTE: We recommend the users to follow this simpler docker compose deployment approach while adding in new services or debugging the existing service.

With ConfigMgrAgent dependency:

- Deployment with ConfigMgrAgent dependency is available in both DEV and PROD mode where we set the `READ_CONFIG_FROM_FILE_ENV` value to `false` in the .env(`[WORK_DIR]/IEdgeInsights/build/.env`) file and make use of the ConfigMgrAgent(`[WORK_DIR]/IEdgeInsights/ConfigMgrAgent/docker-compose.yml`) and the builder.py(`[WORK_DIR]/IEdgeInsights/build/builder.py`) to deploy the service.

NOTE: We recommend the users to follow the earlier use-case driven approach mentioned in Generate Consolidated Files for a Subset of Edge Insights for Industrial Services, when they want to deploy more than one microservice.

Note

This is an optional step, if you want to use the EII pre-built container images and not build from source. For more details, refer to List of Distributed EII Services

To see the build progress set the following env variable by running below command.

export BUILDKIT_PROGRESS=plain

Run the following command to build all EII services in the build/docker-compose.yml along with the base EII services.

docker compose build
  or
./run.sh --build| -b

If any of the services fails during the build, then run the following command to build the service again:

docker compose build --no-cache <service name>
  or
./run.sh --clean| -c

Note

Ensure to run docker compose down -v or ./run.sh --remove_vols|-v script from the build([WORK_DIR]/IEdgeInsights/build) directory before you bring up the EII stack. This helps to remove running containers and avoid any sync issues where other services have come up before ia_configmgr_agent container has completed the provisioning step. If the images tagged with the EII_VERSION label, as in the build/.env([WORK_DIR]/IEdgeInsights/build/.env) do not exist locally in the system but are available in the Docker Hub, then the images will be pulled during the docker compose upcommand or ./run.sh --start|-s or ./run.sh script.

The EII provisioning is taken care by the ia_configmgr_agent service that gets launched as part of the EII stack. For more details on the ConfigMgr Agent component, refer to the Readme.

Note

By default, EII is provisioned in the secure mode.
It is recommended not to use EII in the Dev mode in a production environment. In the Dev mode, all security features, communication to and from the etcd server over the gRPC protocol, and the communication between the EII services/apps over the ZMQ protocol are disabled.
By default, the EII empty certificates folder Certificates([WORK_DIR]/IEdgeInsights/Certificates]) will be created in the DEV mode. This happens because of docker bind mounts but it is not an issue.
The EII_INSTALL_PATH in the build/.env([WORK_DIR]/IEdgeInsights/build/.env) remains protected both in the DEV and the PROD mode with the Linux group permissions.

Starting EII in the Dev mode eases the development phase for System Integrators (SI). In the Dev mode, all components communicate over non-encrypted channels. To enable the Dev mode, set the environment variable DEV_MODE to true in the [WORK_DIR]/IEdgeInsights/build/.env file. The default value of this variable is false.

To provision EII in the developer mode, complete the following steps:

Update DEV_MODE=true in [WORK_DIR]/IEdgeInsights/build/.env.
Rerun the build/builder.py to regenerate the consolidated files.

The Profiling mode is used for collecting the performance statistics in EII. In this mode, each EII component makes a record of the time needed for processing any single frame. These statistics are collected in the visualizer where System Integrators (SIs) can see the end-to-end processing time and the end-to-end average time for individual frames.

To enable the Profiling mode, in the [WORK_DIR]/IEdgeInsights/build/.env file, set the environment variable PROFILING to true.

Note

:

After the EII services starts, you can use the Etcd UI web interface to make the changes to the EII service configs or interfaces keys.
in the DEV and the PROD mode, if the EII services come before the Config Manager Agent service, then they would be in the restarting mode with error logs such as Config Manager initialization failed.... This is due to the single step deployment to support the independent deployment of the EII services, where services can come in a random order and start working when the dependent service comes up later. In one to two minutes, all the EII services should show the status as running when Config Manager Agent service starts up.
To build the common libs and generate needed artifacts from source and use it for building the EII services, refer common/README.md.
The run.sh([WORK_DIR]/IEdgeInsights/build/run.sh) script is used to bring up the ia_configmgr_agent service first and then the rest of the EII services.

# run.sh has following options
# --timeout|-t = timeout (in seconds) as parametent to come up, defaults to 180 seconds
# --clean|-c = to build the container images w/ --no-cache
# --build|-b = to build the container images
# --down|-d = to bring down the containers
# --remove_vols|-v = to remove volumes
# --start|-s = to bring up the containers
./run.sh --timeout=<timeout-in-seconds>|-t=<timeout-in-seconds> --build|-b or --clean|-c or --down|-d or --remove_vols|-v or --start|-s

Note

Below are different ways to run ./run.sh script

./run.sh w/o arguments is equivalent to ./run.sh -s
./run.sh -b will incrementally build the containers
./run.sh -c will freshly build (–no-cache) the containers
./run.sh -d -s will bring down containers and start up containers
./run.sh -v -s will bring down containers, remove volumes and start up containers

On successful run, you can open the web visualizer in the Chrome browser at https://:3000. The HOST_IP corresponds to the IP of the system on which the visualization service is running.

Note

By default, the EII Certificates, configs and secrets (etcd certs, zmq keys, pem/der certs) will not be regenerated upon container restarts and if one has to force this recreation, then you have to delete the docker volume by either running docker compose down -v or ./run.sh --remove_vols|-v script or docker volume rm edgeinsightssoftware_vol_cma_status_file
If you see any Messagebus authentication failure issues like in multi-stream use case where you are trying to bring up multiple EVAM instances, it is recommended to bring up the EII stack in 2 steps instead of single step:
```
docker compose up -d ia_configmgr_agent # provisioning container
docker compose up -d
or
`./run.sh --down|-d`  # bring up the rest of the stack
```

The other workaround is to restart the publisher service if you want to continue using the single step approach. Eg: If multimodal-data-visualization-streaming is throwing the Authentication failed error, then please restart the EVAM service to fix this issue.

Push the Required Edge Insights for Industrial Images to Docker Registry

Note

By default, if DOCKER_REGISTRY is empty in build/.env([WORK_DIR]/IEdgeInsights/build/.env) then the images are published to hub.docker.com. Ensure to remove edgeinsights/ org from the image names while pushing to Docker Hub. Repository names or image names with multiple slashes are not supported. This limitation doesn’t exist in other docker registries like the Azure Container Registry (ACR), Harbor registry, and so on.

Run the following command to push all the EII service docker images in the build/docker-compose.yml. Ensure to update the DOCKER_REGISTRY value in the .env([WORK_DIR]/IEdgeInsights/build/.env) file.

docker compose push

List of EII Services

Based on requirement, you can include or exclude the following EII services in the [WORKDIR]/IEdgeInsights/build/docker-compose.yml file:

Provisioning Service - This service is a prerequisite and cannot be excluded from the docker-compose.yml file.
- ConfigMgrAgent
Common EII services for Video and Timeseries Analytics pipeline services
- DataStore
- Visualizer
Video Analytics pipeline services
Timeseries Analytics pipeline services
- Telegraf
- Kapacitor

Adding New Services to EII Stack

This section provides information about adding a service, subscribing to the EdgeVideoAnalyticsMicroservice([WORK_DIR]/IEdgeInsights/EdgeVideoAnalyticsMicroservice), and publishing it on a new port. Add a service to the EII stack as a new directory in the IEdgeInsights([WORK_DIR]/IEdgeInsights/) directory. The Builder registers and runs any service present in its own directory in the IEdgeInsights([WORK_DIR]/IEdgeInsights/) directory. The directory should contain the following:

A docker-compose.yml file to deploy the service as a docker container. The AppName is present in the environment section in the docker-compose.yml file. Before adding the AppName to the main build/eii_config.json, it is appended to the config and interfaces as /AppName/config and /AppName/interfaces.
A config.json file that contains the required config for the service to run after it is deployed. The config.json consists of the following:
- A config section, which includes the configuration-related parameters that are required to run the application.
- An interfaces section, which includes the configuration of how the service interacts with other services of the EII stack.

Note

For more information on adding new EII services, refer to the EII sample apps at Samples written in C++, Python, and Golang using the EII core libraries.

The following example shows:

How to write the config.json for any new service
Subscribe to EdgeVideoAnalyticsMicroservice
Publish on a new port

{
    "config": {
        "paramOne": "Value",
        "paramTwo": [1, 2, 3],
        "paramThree": 4000,
        "paramFour": true
    },
    "interfaces": {
        "Subscribers": [
            {
                "Name": "default",
                "Type": "zmq_tcp",
                "EndPoint": "127.0.0.1:65114",
                "PublisherAppName": "EdgeVideoAnalyticsMicroservice",
                "Topics": [
                    "edge_video_analytics_results"
                ]
            }
        ],
        "Publishers": [
            {
                "Name": "default",
                "Type": "zmq_tcp",
                "EndPoint": "127.0.0.1:65113",
                "Topics": [
                    "publish_stream"
                ],
                "AllowedClients": [
                    "ClientOne",
                    "ClientTwo",
                    "ClientThree"
                ]
            }
        ]
    }
}

The config.json file consists of the following key and values:

value of the config key is the config required by the service to run.
value of the interfaces key is the config required by the service to interact with other services of EII stack over the Message Bus.
the Subscribers value in the interfaces section denotes that this service should act as a subscriber to the stream being published by the value specified by PublisherAppName on the endpoint mentioned in value specified by EndPoint on topics specified in value of Topic key.
the Publishers value in the interfaces section denotes that this service publishes a stream of data after obtaining and processing it from EdgeVideoAnalyticsMicroservice. The stream is published on the endpoint mentioned in value of EndPoint key on topics mentioned in the value of Topics key.
the services mentioned in the value of AllowedClients are the only clients that can subscribe to the published stream, if it is published securely over the Message Bus.

Note

Like the interface keys, EII services can also have Servers and Clients interface keys.
For more information on the interfaces key responsible for the Message Bus endpoint configuration, refer to common/libs/ConfigMgr/README.md#interfaces.
For the etcd secrets configuration, in the new EII service or app docker-compose.yml file, add the following volume mounts with the right AppName env value:

...
 volumes:
   - ./Certificates/[AppName]:/run/secrets/[AppName]:ro
   - ./Certificates/rootca/cacert.pem:/run/secrets/rootca/cacert.pem:ro

Video Pipeline Analytics

This section provides more information about working with the video pipeline.

The Edge Video Analytics Microservice supports different types of cameras. For more details about camera configurations, refer the README.

You can integrate any python UDF with the Edge Video Analytics Microservice using the volume mount method. For more details about python UDF integration, refer the README

Edge Video Analytics Microservice supports running inference on CPU and GPU devices by accepting the device value (“CPU”|”GPU”), part of the udf object configuration in the udfs key. The device field in the UDF config of udfs key in the EdgeVideoAnalyticsMicroservice configs needs to be updated. Refer these steps for running Edge Video Analytics Microservice on a GPU device.

Time Series Analytics

For time series data, a sample analytics flow uses Telegraf for ingestion, Influx DB for storage, and Kapacitor for classification. This is demonstrated with an MQTT-based ingestion of sample temperature sensor data and analytics with a Kapacitor UDF that detects threshold for the input values. The services mentioned in the build/usecases/time-series.yml([WORK_DIR]/IEdgeInsights/build/usecases/time-series.yml) file will be available in the consolidated docker-compose.yml and consolidated build/eii_config.json of the EII stack for the time series use case when built via builder.py as called out in previous steps. This will enable building of the Telegraf and the Kapacitor based analytics containers. For more details on enabling this mode, refer to the Kapacitor/README.md The sample temperature sensor can be simulated using the MQTT publisher. For more information, refer to the tools/mqtt/README.md.

Time Series Python UDFs Development

In the DEV mode, the Python UDFs are volume mounted in the Kapacitor container image as seen in its docker-compose-dev.override.yml file. You can update the UDFs on the host machine and see the changes in Kapacitor. You can do this by restarting the Kapactior container. Rebuilding the Kapacitor container image is not required.

Note

: To enable the DEV mode, in the [WORK_DIR]/IEdgeInsights/build/.env set DEV_MODE=true.

Edge Insights for Industrial Multi-node Cluster Deployment

With K8s Orchestrator

You can use any of the following options to deploy EII on a multi-node cluster:

[Recommended] For deploying through ansible playbook on multiple nodes automatically, refer to build/ansible/README.md
For information about using helm charts to provision the node and deploy the EII services, refer to build/helm-eii/README.md

Edge Insights for Industrial Tools

The EII stack consists of the following set of tools that also run as containers:

Edge Insights for Industrial Uninstaller

The EII uninstaller script automatically removes all the EII Docker configuration that is installed on a system. The uninstaller performs the following tasks:

Stops and removes all the EII running and stopped containers.
Removes all the EII docker volumes.
Removes all the EII docker images [Optional]
Removes all EII install directory

To run the uninstaller script, run the following command from the [WORKDIR]/IEdgeInsights/build/ directory:

./eii_uninstaller.sh -h

Usage: ./eii_uninstaller.sh [-h] [-d] This script uninstalls the previous EII version. Where:

-h show the help -d triggers the deletion of docker images (by default it will not trigger)

Example:

Run the following command to delete the EII containers and volumes:
```
./eii_uninstaller.sh
```
Run the following command to delete the EII containers, volumes, and images:
```
./eii_uninstaller.sh -d
```

The commands in the example will delete the version 2.4 EII containers, volumes, and all the docker images.

WebVision GUI

WebVision GUI microservice provides a graphical interface to register the cameras, configure the User Defined Functions (UDFs), create and start the vision pipeline and preview the output on a single node supporting multiple user personas like Subject Matter Expert (SME) and Operator.

For more details, please refer: WebVision ReadMe

Debugging Options

Perform the following steps for debugging:

Run the following command to check if all the EII images are built successfully:
```
docker images|grep ia
```
You can view all the dependency containers and the EII containers that are up and running. Run the following command to check if all containers are running:
```
docker ps
```
Ensure that the proxy settings are correctly configured and restart the docker service if the build fails due to no internet connectivity.
Run the docker ps command to list all the enabled containers that are included in the docker-compose.yml file.
From edge video analytics microservice>visualizer, check if the default video pipeline with EII is working fine.
The /opt/intel/eii root directory gets created - This is the installation path for EII:
- data/ - stores the backup data for persistent imagestore and influxdb
- sockets/ - stores the IPC ZMQ socket files

The following table displays useful docker compose and docker commands:

Command	Description
`docker compose build`	Builds all the service containers
`docker compose build [serv_cont_name]`	Builds a single service container
`docker compose down`	Stops and removes the service containers
`docker compose up -d`	Brings up the service containers by picking the changes done in the `docker-compose.yml` file
`docker ps`	Checks the running containers
`docker ps -a`	Checks the running and stopped containers
`docker stop $(docker ps -a -q)`	Stops all the containers
`docker rm $(docker ps -a -q)`	Removes all the containers. This is useful when you run into issue of already container is in use
`[docker compose cli]`	For more information refer to the docker documentation
`[docker compose reference]`	For more information refer to the docker documentation
`[docker cli]`	For more information refer to the docker documentation
`docker compose run --no-deps [service_cont_name]`	To run the docker images separately or one by one. For example: `docker compose run --name ia_edge_video_analytics_microservice --no-deps ia_edge_video_analytics_microservice` to run the EdgeVideoAnalyticsMicroservice container and the switch `--no-deps` will not bring up its dependencies mentioned in the `docker-compose` file. If the container does not launch, there could be some issue with the entrypoint program. You can override by providing the extra switch `--entrypoint /bin/bash` before the service container name in the `docker compose run` command. This will let you access the container and run the actual entrypoint program from the container’s terminal to root cause the issue. If the container is running and you want to access it then, run the command: `docker compose exec [service_cont_name] /bin/bash` or `docker exec -it [cont_name] /bin/bash`
`docker logs -f [cont_name]`	Use this command to check logs of containers
`docker compose logs -f`	To see all the docker compose service container logs at once

Troubleshooting Guide

For any troubleshooting tips related to the EII configuration and installation, refer to the TROUBLESHOOT.md guide.
Since all the EII services are independently buildable and deployable when we do a docker compose up for all EII microservices, the order in which they come up is not controlled. Having said this, there are many publishers and subscriber microservices in EII middleware, hence, its possible that publisher comes up before subscriber or there can be a slght time overlap wherein the subscriber can come up just after publisher comes up. Hence, in these scenarios its a possibility that the data published by publisher can be lost as subscriber would not be up to receive all the published data. So, the solution to address this is to restart the publisher after we are sure that the intended subscriber is up.
If you observe any issues with the installation of the Python package, then as a workaround you can manually install the Python packages by running the following commands:
```
cd [WORKDIR]/IEdgeInsights/build
# Install requirements for builder.py
pip3 install -r requirements.txt
```
Note: To avoid any changes to the Python installation on the system, it is recommended that you use a Python virtual environment to install the Python packages. For more information on setting up and using the Python virtual environment, refer to Python virtual environment.
- Make sure you have an active internet connection during the installation. If you lose Internet connectivity at any time, the installation might fail.
- If the eii installer component fails to install after running the ./edgesoftware install command, check the running containers list using docker ps command and check the logs of the failing containers to find out why they are failing. Mostly services like InfluxDBConnector, Grafana, Imagestore, etc., fail if the port is already used by other process on the host m/c as EII uses docker host network. Please make sure to free up that port and re-run the ./edgesoftware install command or follow the steps below:
  - Go to edge_insights_industrial/Edge_Insights_forIndustrial/IEdgeInsights/build where indicates the downloaded version of Edge Insights for Industrial.
  - Run sudo sg docker -c docker compose up -d command or ./run.sh --remove_vols|-v script to relaunch services.
Restart Mode: The following services may be in restart mode after successful installation. Refer to the respective README.md files to troubleshoot, where indicates the downloaded version of Edge Insights for Industrial:
- Visualizer: edge_insights_industrial/Edge_Insights_forIndustrial/IEdgeInsights/Visualizer/README.md
Docker Image Pull Issue: This issue can be because of the latest pull rate limitations introduced by Docker hub.
- Please check this Docker article to help determine the exact pull limit that’s applicable on the system where you are trying to pull the publicly available Docker hub images, such as Docker, Python, etc. NOTE: This limit is only applicable for the 6-hour window.
- If you see this issue with an anonymous user (pull limit of 100), i.e., without Docker login, you can create an account and try to do the build after running the command: docker login -u -p . The alternative is to use a paid subscription.

If you’re unable to resolve your issues, go to the Support Forum.