Skip to main content
Hitachi Vantara Lumada and Pentaho Documentation

Install and provision an IIoT Gateway

Use the following requirements and instructions for installing and provisioning an IIoT Gateway and connecting the gateway to IIoT Core Services.

The IIoT Gateway is a small footprint software that provides data ingestion from automation and IIoT devices over various protocols and automatically tiers the data from the gateway to the IIoT Core Services software.

Process overview

Use the following process to install and provision the IIoT Gateway software.

  1. Install an IIoT Gateway image on a gateway device.
  2. Add a gateway to the device inventory in the IIoT Core Services UI.
  3. Use the command line interface (CLI) to provision the gateway.
  4. Verify the status of IIoT Gateway services in the IIoT Core Services UI.

Preparing for IIoT Gateway installation

Understand the requirements for installing an IIoT Gateway and perform the necessary installation steps.

IIoT Gateway hardware requirements

For gateway devices, IIoT Core supports hardware similar to the following, which has been validated with the IIoT Gateway software stack.

Hardware Description
NUC (i5)
  • Intel Core i5-8259U processor (2.3 GHz - 3.8 GHz, Quad Core, 6 MB Cache, 28W TDP)
  • 8 GB memory
  • 120 GB storage
  • Intel Iris Plus Graphics 655
  • 2 × 260Pin SO-DIMM DDR4 2400
NUC (i7)
  • Intel Core i7-8559U processor (2.7 GHz - 4.5 GHz, Quad Core, 8 MB Cache, 28W TDP)
  • 16 GB memory
  • 120 GB storage
  • Intel Iris Plus Graphics 655
  • 2 × 260Pin SO-DIMM DDR4 2400
POC-351VTC
  • Intel Atom E3950 processor (1.6 Ghz, Quad Core, 2 MB Cache, 9.5W TDP)
  • 8 GB RAM (DDR3L-1866 single SO-DIMM)
  • 128 GB storage
  • Integrated Intel® HD Graphics 505

IIoT Gateway installation prerequisites

The following prerequisites apply before installing the IIoT Gateway.

ComponentRequirement
OS and processors

IIoT Gateway services require Red Hat Enterprise Linux v8.2 and v8.4 or Ubuntu v20.04.

IIoT Gateway is supported on both AMD64- or ARM64-based gateway devices:

  • AMD64-based gateway: Tested with RHEL 8.4, RHEL 8.2, Ubuntu 20.04, and CentOS 7.8.
  • ARM64-based gateway: Tested with Ubuntu 20.04.

    Example: Raspberry Pi.

Docker

You must install Docker before installing the IIoT Gateway, regardless of the OS.

  • Docker support:
    • RHEL v8.2 and v8.4: Docker v20.10.
    • Ubuntu v20.04: Docker CE v20.10.
NetworkManager

NetworkManager must be active (running).

To run NetworkManager and verify its status, see Run NetworkManager on an IIoT Gateway.

Host namesThe Core and Gateway host names must be unique.
Gateway log fileIf the gateway log file becomes too large and consume the whole Docker volume, change the log file size and the number of log files retained in daemon.json. The log file size and number of log files can be configured in /etc/hiota/agent/config/configuration.yaml. For more information, see the Docker documentation.
Other settings

To keep the connection open between gateway containers, you must set FirewallBackend to iptables in /etc/firewalld/firewalld.conf.

By default, Docker containers run on the 172.16.0.0/16 subnet. Change this subnet if the existing network at the installation site already uses it.

Run NetworkManager on an IIoT Gateway

You must activate NetworkManager for the IIoT Gateway to work properly assuming that the operating system manages the network using NetworkManager.

Perform the following steps.

Procedure

  1. Log in as root user on the IIoT Gateway node.

  2. Check whether NetworkManager is active by running the command systemctl status NetworkManager.

  3. If NetworkManager is not active, run the command systemctl start NetworkManager.

  4. Run the command systemctl status NetworkManager again to verify that NetworkManager is active.

Port configuration requirements (Gateway)

The IIoT Gateway services provide two ways to collect data (MQTT messaging and Modbus adapter), and two ways to send data to IIoT Core Services (MQTT messaging and REST calls).

Check the following gateway message brokers and services to determine if your service requires the corresponding ports to be open.

Message broker
ServiceDescriptionDefault portOptional installDefault loginLinks
MQTT - MosquittoEnables messaging over MQTT30883NoadminDocumentation: https://mosquitto.org/
Provisioning service
ServiceDescriptionDefault portOptional installLinks
Hiota AgentProvisioning agent for the IIoT Gateway8443NoN/A

Install and configure Ubuntu

You can install the IIoT Gateway software for the ARM processor on the Ubuntu operating system using the following instructions.

Ubuntu v20.04 uses Netplan to manage the network, but the IIoT Gateway assumes the operating system manages the network using NetworkManager. You must therefore install NetworkManager as part of the process.

Before you begin

  • Note that currently, Ubuntu is only supported on the ARM architecture.
  • Check prerequisites for installing Ubuntu. See IIoT Gateway installation prerequisites.
  • Install Ubuntu v20.04 on a gateway device. View the installation documentation at ubuntu.com.

Procedure

  1. Log on to the IIoT Gateway as root.

  2. Download and install Docker CE v20.10.12 or later with secure SSL setup by entering the following commands.

    apt install apt-transport-https ca-certificates software-properties-commoncurl -fsSL https://download.docker.com/linux/ubuntu/gpg | apt-key add -
    add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
    apt update -y
    apt-cache policy docker-ce
    apt install -y docker-ce
    
  3. Enter the following commands to install NetworkManager:

    apt install network-manager ifupdown
    touch /etc/NetworkManager/conf.d/10-globally-managed-devices.conf
    
  4. Configure the interface that the sensor data is transmitting to by entering the following IP addresses.

    cat << MYNETCFG >> /etc/network/interfaces
    auto <interface_name>
      iface <interface_name> inet static
      address <interface_ip_address>
      netmask <netmask_ip_address>
      gateway <gateway_ip_address>
      dns-nameservers <name_server_1_ip_address> <name_server_2_ip_address>
    MYNETCFG
    
  5. Remove the Netplan configuration by opening the /etc/netplan/00-cloud-init.yaml file and commenting it out. Also comment out Netplan configuration information any other YAML interface configuration files.

  6. Set ifupdown to manage the network interfaces by modifying /etc/NetworkManager/NetworkManager.conf as follows.

    ...
    [ifupdown]managed=true
    ...
    
  7. Reboot the gateway for the changes to take effect.

  8. Verify that the command-line utility nmcli is available for controlling NetworkManager by entering the following commands:

    nmcli -t device
    nmcli -t connection
    
    Make sure the network interface used for connecting to the outside world (usually an Ethernet interface) shows as managed.

Results

Ubuntu is now configured. Proceed to install the IIoT Gateway.

Install an IIoT Gateway

Install IIoT Gateway on a gateway device.

Before you begin

  • Always reboot the gateway device before you start the IIoT Gateway installation process.
  • To download the IIoT Gateway software installation package, go to Hitachi Vantara Lumada and Pentaho Support Portal and log in.

    IIoT Gateway installation package: iiot-core-5.0.0-gateway.tar.gz

Procedure

  1. Log in as a root user on the gateway device.

  2. Download the IIoT Gateway installation package.

  3. Open the software package by running the following command.

    tar zxvf iiot-core-5.0.0-gateway.tar.gz
    A new folder is created: release-5.0.0.
  4. Navigate to the new folder by running the following command:

    cd release-5.0.0
  5. Run the IIoT Gateway installer:

    ./gateway-install.sh [<inventory id>]
    NoteAs a best practice, you should pass an Inventory ID to the installer. The Inventory ID that you provide in the installer must be identical to the one you provide when creating the corresponding gateway device in the device inventory in IIoT Core Services (see Add a gateway to the device inventory) so make sure to record it. After running the IIoT Gateway installer, the inventory ID resides in the /etc/hiota/agent/configs/configuration.yaml file. If you use a different one in the device inventory, modify the configuration.yaml file and restart hiota-agent using this command:
    systemctl restart hiota
    The IIoT Gateway is successfully installed if no error messages are displayed.

Add a gateway to the device inventory

You can add a gateway to the device inventory in the IIoT Core Services UI, so that data routes can be configured to collect data from the gateway device.

Procedure

  1. In the IIoT Core Services UI, select the Device tab.

  2. Click Add Device.

  3. Enter the following information:

    FieldDescription
    NameEnter a name for the device.
    Device TypeSpecify the type of device to be added. Gateway is currently the only option.
    Inventory IDSpecify the unique identifier for the device. It must match the Inventory ID that is set during the gateway installation.
    Location (Optional)Specify the location of the device.
    Description (Optional)Specify a description for the device.
    Additional Properties (Optional)Click Add Property to create additional fields to describe the device if necessary, such as an RFID, a boolean status, or a URL. You can add properties individually or import a set of properties from a JSON file. Then click Apply.
    Enable PollingSelect to enable polling on the management plane. Polling allows the gateway to periodically connect to the Core server and pull tasks for controlling and monitoring the device at certain time intervals instead of keeping connections open.
    NoteToggling the polling parameters does not affect data collection.
    Polling IntervalSet how frequently the gateway polls for new connect messages.
    Polling Retry IntervalSpecify the period of time between the end of the timeout period of the last retry and the next retry.
    Polling Max RetriesSpecify the maximum number of retries in one polling session.
    Endpoint Database Defragmentation ScheduleSelect a database defragmentation schedule to keep the database optimized:
    • Monthly
    • Weekly
    • Daily (Midnight)
    • Hourly
  4. Click Add to add the new device to the repository.

Results

The device is shown in the device list, with a Device State of 'Inventory' and a Status of N/A.

After the gateway device is created, you can configure it to receive data. By provisioning the gateway, you can create data routes to specify where the data flows to. See how to register and provision an IIoT Gateway in the IIoT Gateway installation section.

Registering and provisioning an IIoT Gateway using CLI

The Lumada Intelligence Tool (LIT) is a command line interface (CLI) application that lets you create and enroll devices using the command line.

Manage LIT installation on Linux or Mac

You can install, update, or uninstall the LIT application on Linux or Mac OS X. LIT provides all the commands needed to successfully register and provision an IIoT Gateway.

Install LIT on Linux or Mac

You can install LIT on Linux or Mac OS X using the following procedure.

Procedure

  1. Download the LIT application package from Hitachi Vantara Lumada and Pentaho Support Portal.

    • For Linux: lumada_edge_intelligence-cli-linux-5.0.0.tar.gz
    • For Mac: lumada_edge_intelligence-cli-mac-5.0.0.tar.gz
  2. Unarchive the tarball on the target device:

    Linux:
    cd <install_dir>/
    tar -zxf lumada_edge_intelligence-cli-linux-5.0.0.tar.gz
    Mac:
    cd <install_dir>/
    lumada_edge_intelligence-cli-mac-5.0.0.tar.gz
  3. If your cluster's Fully Qualified Domain Name (FQDN) cannot be resolved by DNS, set your target cluster FQDN to /etc/hosts on the node where you are running this CLI.

  4. Install LIT by running the installation script:

    cd <install dir>/cli-pkg-<os>/
    bash install.sh

Results

The LIT application is installed. Before using LIT, make sure to Verify the LIT installation on Linux and Mac.

Update LIT on Linux or Mac

You can update the LIT application to the latest version on Linux or Mac OS X by running the LIT update script .

NoteThe script only updates the binary, not the configuration files.

Procedure

  1. Navigate to the directory where the update script resides:

    cd <install dir>/cli-pkg-<os>/
    where <os> is your operating system, either mac or linux.
  2. Run the update script:

    sh update.sh

Results

Your LIT application is updated to the latest version.

Verify the LIT installation on Linux and Mac

After installing or updating the LIT application, you should verify that the operation was successful.

Procedure

  1. Verify that the application was installed to $HOME/.lit.

    Example:
    ```bash
    $ ls -l $HOME/.lit
    drwxr-xr-x 2 root root  17 Jan 15 03:31 bin
    drwxr-xr-x 2 root root 100 Jan 15 03:39 configs
    drwxr-xr-x 2 root root  21 Jan 15 03:34 logs
  2. Verify that the configuration was moved to $HOME/.lit/configs.

    Example:
    ```bash
    $ ls -l $HOME/.lit/configs/
    -rwxrwxr-- 1 root root 144 Mar 26 20:12 lit_app_current.json
    -rwxrwxr-- 1 root root 190 Mar 26 20:12 lit_app.json
    -rwxrwxr-- 1 root root  65 Mar 26 20:12 lit_gw_current.json
    -rwxrwxr-- 1 root root  93 Mar 26 20:12 lit_gw.json
  3. Verify that the binaries were moved and have execute permissions:

    ```bash
    $ ls -l $HOME/.lit/bin
    -rwxrwxr-- 1 root root 7698887 Mar 26 20:14 lit
    ```
  4. Check that LIT is properly installed by running this command:

    lit version

Uninstall LIT on Linux or Mac

You can uninstall the LIT application on Linux or Mac OS X by running the LIT uninstall script:

Procedure

  1. Navigate to the LIT application directory:

    cd <install dir>/cli-pkg-<os>/
    
    where <os> is your operating system, either mac or linux.
  2. Run the LIT uninstall script:

    sh uninstall.sh

Results

The LIT application is removed from your node.

Manage LIT installation on Windows

You can install, update, or uninstall the LIT application on Windows. LIT provides all the commands needed to successfully register and provision an IIoT Gateway.

Install LIT on Windows

Use th following steps to install LIT on Windows.

Procedure

  1. Download the LIT application package from Hitachi Vantara Lumada and Pentaho Support Portal:

    lumada_edge_intelligence-cli-windows-5.0.0.zip
  2. Unarchive the ZIP file in the installation directory of the target device:

    cd <install_dir>/
    <your preferred unzip utility> lumada_edge_intelligence-cli-windows-5.0.0.zip
  3. Install LIT by running the installation script or by double-clicking the file install.bat:

    cd <install dir>/cli-pkg-windows/
    install
    If you are running install.bat as a non-admin user, adding the binary path to the PATH environment value fails. In this case, take one of the following actions:
    • Use the LIT application in %HOMEPATH%/.lit/bin.
    • Manually add %HOMEPATH%/.lit/bin to the PATH environment value.
    • Retry the installation as an admin user.

Results

The LIT application is installed. Before using LIT, make sure to Verify the LIT installation on Windows.

You can view available LIT commands by running this command:

lit -help

Update LIT on Windows

You can update the LIT application to the latest version on Windows by running the LIT update script.

NoteThe script only updates the binary, not the configuration files.

Procedure

  1. Navigate to the directory where the update script resides:

    cd <install dir>/cli-pkg-windows/
  2. Run the update script (update.bat):

    update

Results

Your LIT application is updated to the latest version.

Verify the LIT installation on Windows

After installing or updating the LIT application, verify that the operation was successful.

Procedure

  1. Verify that the application was installed to %HOMEPATH%/.lit.

    Example:
    dir
    04/20/2021  02:32 PM    <DIR>          bin
    04/20/2021  02:32 PM    <DIR>          configs
    04/23/2021  01:55 PM    <DIR>          logs
  2. Verify that the configuration was moved to %HOMEPATH%/.lit/configs.

    Example:
    cd %HOMEPATH%/.lit/configs
    dir
    04/06/2021  03:25 PM                 2 lit_app.json
    04/06/2021  03:25 PM                 2 lit_app_current.json
    04/06/2021  03:25 PM                 2 lit_gw.json
    04/06/2021  03:25 PM                 2 lit_gw_current.json
  3. Verify that the binaries were moved and have execute permissions:

    cd %HOMEPATH%/.lit/bin
    dir /Q
    04/06/2021  03:25 PM         7,811,072 HDS\user_name           lit.exe
  4. Check that LIT is properly installed by running this command:

    lit version

Uninstall LIT on Windows

You can uninstall the LIT application on Windows by running the LIT uninstall script:

Procedure

  1. Navigate to the LIT application directory:

    cd <install dir>/cli-pkg-windows/
    
  2. Run the LIT uninstall script (uninstall.bat):

    uninstall
  3. Remove %HOMEPATH%.lit\bin from the PATH environment value.

    This removal is necessary because the uninstall script does not delete the CLI path from the PATH environment variable.

Results

The LIT application is removed from your node.

LIT command options

The following code list provides information for all available CLI command options.

$ lit -help
  
Lumada Intelligence Tool (lit) version 1.0.0 (2)

lit

	version (-version, -v) - print version

	help (-help, -h) - print usage

	configuration (configuration, cfg, c) - Config options
		appliance (app, a)
			list (l) - list the configuration options
			select (s) - select a configuration option
				-name=<config_name> - Select the current configuration (req)
			current (c) - current configuration
			add (a) - add configuration
				-name=<config_name> - Name of the new configuration (req)
				-desc=<config_desc> - Description of the new configuration (req)
				-ip=<config_ip> - IP of the new configuration (req)
				-user=<config_user> - Username of the new configuration (req)
				-pwd=<config_pwd> - Password of the new configuration (req)
				-keycloak_pwd=<config_keycloak_pwd> - Keycloak Password of the new configuration (req)
			delete (d) - delete configuration
				-name=<config_name> - Name of the new configuration (req)
		gateway (gw, g)
			list (l) - list the configuration options
			select (s) - select a configuration option
				-name=<config_name> - Select the current configuration (req)
			current (c) - current configuration
			add (a) - add configuration
				-name=<config_name> - Name of the new configuration (req)
				-desc=<config_desc> - Description of the new configuration (req)
				-ip=<config_ip> - IP of the new configuration (req)
			delete (d) - delete configuration
				-name=<config_name> - Name of the new configuration (req)

	device (d) - Device commands
		list (l) - list all the devices
		get (g) - get a devices
			-id=<device_id> - Device ID to query (req)
		create (c) - create a devices
			-name=<device_name> - Device name (req)
			-inventory_id=<device_inventory_id> - Unique inventory Id (req)
			-device_type={appliance|gateway} - Device type (req)
			-desc=<description> - Device description
			-location=<location_description> - Device location description
		delete (d) - delete a devices
			-id=<device_id> - Device ID to delete (req)

	gateway (gw, g) - Gateway commands
		state (s) - Get the gateway state
			-id=<inventory_id> - Inventory id to log into the gateway
		enroll (e) - Enroll a devices
			-id=<device_id> - Device ID to enroll (req)

Configure and enroll an IIoT Gateway device using LIT

To enroll an IIoT Gateway, you need to update the configuration, so LIT knows how to connect to Core and Gateway devices.

Add or update a Core configuration using LIT

To set up the connection between LIT and IIoT Core Services, first update the IIoT Core Services configuration:

Procedure

  1. Add your IIoT Core Services configuration:

    lit cfg app add -name=<core_name> -desc=<core_description> 
    -domain=<cluster_fqdn> -ip=<core_ip/loadbalancer_ip> 
    -user=<core_admin_username> -pwd=<core_admin_password> 
    -keycloak_pwd=<core_keycloak_password>

    Use the following table to edit the LIT parameters as needed:

    ParameterDescription
    nameUnique name of IIoT Core Services.
    descDescription of IIoT Core Services.
    domainCore/load balancer Fully Qualified Domain Name (FQDN) of the cluster.
    ipCore/load balancer IP address.
    userAdmin username created during installation of IIoT Core Services.
    pwdAdmin password created during installation of IIoT Core Services.
    keycloak_pwdKeycloak password created during installation of IIoT Core Services.
    NoteThe added core connection information is saved in .lit/configs/lit_app.json. Multiple sets of core connection information can be created.
  2. List the configurations available to LIT:

    lit cfg app list
    Sample command output:
    $ lit cfg app list
    Appliance Config Options:
        Name: <core_name>
        Desc: <description>
        IP Address: <cluster_ip_address>
        Cluster FQDN: <cluster_fqdn>
  3. Select the Core configuration you want to connect to:

    lit cfg app select -name=<core_name>
    Note<core_name> has to be identical to <core_name> in the previous step.
    The selected core connection information is saved in the following location: .lit/configs/lit_current_app.jsonTo verify that LIT is connecting to the correct Core device, run the following command:
    lit cfg app current
  4. Test the connection.

    Use the lit device list command to verify that LIT can access and talk to the IIoT Core Services platform by listing all currently connected devices. The command output should show at least the auto-created core device.
    $ lit device list
        Device list:
        Device Info:
            AssetId:            <asset_id>
            Name:               <name>
            Hostname:           <hostname>
            InventoryId:        <inventory_id>
            Description:        Auto-created Appliance Device
            LocationDescription:
            ImageMimeType:
            DeviceType:         appliance
            DateCreated:        2020-04-16T23:48:41Z
            State:              ready

Add or update an Gateway configuration using LIT

To set up the connection between LIT and IIoT Core Services, you need to update the IIoT Gateway configuration.

Procedure

  1. Add your IIoT Gateway configuration:

    lit cfg gw add -name=<gw_name> -desc=<gw_description> -ip=<gw_ip_addr>
    NoteThe added IIoT Gateway connection information is saved in the following location: .lit/configs/lit_gw.json. LIT can be used to enroll multiple gateways by adding multiple IIoT Gateway configurations.
    ParameterDescription
    nameUnique name of the gateway device.
    descDescription of the gateway device.
    ipIP address of the gateway device.
  2. List and select the configuration to be used:

    lit cfg gw list
    Sample command output:
    $ lit cfg gw list
    Gateway Config Options:
    Name: p2rhgw16
        Desc: p2rhgw16
        URL: <gw_ip_addr>
  3. Select the IIoT Gateway configuration for the gateway you want to connect to:

    lit cfg gw select -name=<gw_name>
    The selected gateway connection information is saved in the following location: .lit/configs/lit_current_app.jsonTo verify that LIT is connecting to and enrolling the correct IIoT Gateway, use the following command:
    lit cfg app current

Create and enroll a Gateway using LIT

Before enrolling a gateway with IIoT Core Services, you need to create an IIoT Gateway.

There are two ways to create an IIoT Gateway:

  • From the IIoT Core Services user interface.
  • Using the LIT command to create an IIoT Gateway from the CLI.

Procedure

  1. Check which Core device the gateway will be created on to understand which one LIT will connect to:

    lit c a c
  2. Create the IIoT Gateway:

    lit d c -name=<gateway_name> -inventory_id=<gateway_inventory_id> 
    -device_type=gateway
    For inventory_id, make sure to use the same unique inventory ID that was set on the gateway device during installation.Example:
    $ lit d c -name=p2rhgw16 -inventory_id=p2rhgw16 -device_type=gateway
    
    SUCCESSFULLY Created Device
    
    Device Info:
    	DeviceId: 		   <device_id>
    	Name: 			   <device_name>
    	Hostname:
    	InventoryId: 		<inventory_id>
    	Description:
    	LocationDescription:
    	ImageMimeType:
    	DeviceType: 		 gateway
    	DateCreated: 		2021-04-02T21:45:14Z
    	State: 			  inventory
  3. Enroll the created device.

    After the device is created, LIT shows the newly created DeviceId. This id will be passed on to the enrollment command.
    lit g e -id=<gateway_device_id>
    If you do not know the DeviceId, use the following command to get all gateway device information from IIoT Core Services:
    lit d l

Results

The gateway device is now enrolled with IIoT Core Services. In the device repository in the IIoT Core Services UI, the device should now have a status of Online and a device state of Ready.

Delete and unenroll a Gateway using LIT

After the device is created, LIT displays the newly created DeviceID. This ID is passed on to the enrollment command. If you delete a device that has been enrolled, it automatically goes through the unenrollment process: first resetting the device, then deleting the asset metadata of the device.

Procedure

  1. Log in to the gateway as a root user using SSH.

  2. Delete the device with the relevant device ID.

    lit delete device -id=<gateway_device_id>

Results

The device is deleted and unenrolled from the device repository.

Verify IIoT Gateway services in IIoT Core Services

You can verify that Gateway services are running in the Core Services software by performing the following steps.

Procedure

  1. On the Device tab in IIoT Core Services, select the name of the gateway device.

  2. Select the Software tab.

  3. On the namespace list, select Hiota Gateway.

  4. Review the status for each software service. All services must be running.

Uninstall an IIoT Core Services gateway

Perform the following steps to uninstall gateway software from a gateway device.

Procedure

  1. Connect to the gateway device through SSH.

  2. Log in as a root user on the gateway.

  3. Navigate to the product installation folder:

    cd release-5.0.0
  4. Run the uninstall script:

    ./gateway-uninstall.sh
  5. Enter y when prompted to uninstall.

    If no errors display when the process completes, the gateway has been successfully uninstalled.