.. _iotedge:

How to deploy *ogamma* Visual Logger for OPC as Azure IoT Edge Module
========================================================================================

If you have an Azure IoT Edge Device, you can install *ogamma* Visual Logger for OPC in it remotely via Microsoft Azure Portal, as an Azure IoT Edge Module. This section describes, how industrial PC box with Ubuntu 18.04 operating system can be turned into IoT Edge device, and steps on installing of the *ogamma* Visual Logger for OPC in it. Further below we will refer to this PC as a ``device``.

Install Azure IoT Edge runtime in the device.
----------------------------------------------

Installation of the Azure IoT Edge runtime in the device is descibed in detail at Microsoft web site here: https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge?view=iotedge-2018-06

For convenience, they are descibed here too. Before proceeding, add an IoT Edge device in Microsoft Azure portal. It will represent like a ``twin`` in the Azure Portal, mirroring real device. After creating it in the Azure Portal, find the option ``Primary Connection String`` in device setting - you will need it to initialize the IoT Edge runtime in the device. You can follow tutorial from this page: https://docs.microsoft.com/en-us/azure/iot-edge/how-to-register-device?view=iotedge-2020-11&tabs=azure-portal (Option 1: Register with symmetric keys).
 
Next steps need to be performed in the device:

Install prerequisites.
^^^^^^^^^^^^^^^^^^^^^^

Utility program ``curl`` and ``moby`` Docker engine should be installed in the device.

Open command line terminal and run the following commands:

.. code-block:: console

  sudo apt-get update
  sudo apt-get install curl
  curl https://packages.microsoft.com/config/ubuntu/18.04/multiarch/prod.list > ./microsoft-prod.list
  sudo cp ./microsoft-prod.list /etc/apt/sources.list.d/
  curl https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > microsoft.gpg
  sudo cp ./microsoft.gpg /etc/apt/trusted.gpg.d/
  sudo apt-get update
  sudo apt-get install moby-engine

Install Azure IoT Edge runtime
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Open command line terminal and run the following commands:

.. code-block:: console

  sudo apt-get update
  sudo apt-get install iotedge


To install specific version of the IoT Edge runtime, for example, 1.1.1-1, run:

.. code-block:: console
  
  sudo apt-get install iotedge=1.1.1-1 libiothsm-std=1.1.1-1


Provision IoT Edge device with its cloud identity (using symmetric key).
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This provisioning step maps, or binds this device to its ``twin`` IoT Edge device added in Azure Portal.

Open IoT Edge configuration file for editing:

.. code-block:: console

  sudo nano /etc/iotedge/config.yaml

Find section ``Manual provisioning with an IoT Hub connection string`` in the file and uncomment the ``provisioning`` section.

  provisioning:

    source: "manual"

    device_connection_string: "<ADD DEVICE CONNECTION STRING HERE>"

Update the value of the option ``device_connection_string`` with the value of the ``Primary Connection String`` option from your IoT Edge device at Azure Portal. Make sure that any other provisioning sections are commented out. Make sure the ``provisioning:`` line has no preceding whitespace and that nested items are indented by two spaces.

Save and close the file: CTRL + X, Y, Enter

Restart IoT Edge runtime.
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: console

  sudo systemctl restart iotedge

To check status of the IoT Edge daemon, use command:

.. code-block:: console

  sudo systemctl status iotedge


Verify in the Azure Portal page for the device, that IoT Edge system modules ``$edgeAgent`` and ``$edgeHub`` have runtime status ``running``. It might take some time to update the status.

Deploy *ogamma* Visual Logger for OPC
------------------------------------------------------------------------------

Once Azure IoT Edge runtime is installed in the device and provisioned, you can install *ogamma* Visual Logger for OPC in it remotely using Azure Portal.

In the device page, click on the ``Set Modules`` tab page. In the ``IoT Edge Modules`` section, click on the ``Add`` button. In the dropdown list select ``IoT Edge Module``. As a result, ``Add IoT Edge Module`` page should be opened.

Here, in the ``Module Settings`` tab, enter the following fields:

  * ``IoT Edge Module Name`` - arbitrary name of the module.
  * ``Image URI`` - set to the full URL of the Docker container image: ``registry.hub.docker.com/ogamma/logger-dev``. 

In the ``Container Create Options`` tab, enter the following settings:

.. code-block:: JSON

  {
      "Hostname": "ovl",
      "Volumes": {
          "/home/ogamma/logger/data": {}
      },
      "WorkingDir": "/home/ogamma/logger",
      "NetworkDisabled": false,
      "ExposedPorts": {
          "4880/tcp": {}
      },
      "HostConfig": {
          "PortBindings": {
              "4880/tcp": [
                  {
                      "HostPort": "4880"
                  }
              ]
          },
          "Binds": [
            "/var/ogamma-logger-data:/home/ogamma/logger/data"
          ]
      }
  }


Click on the ``Add`` button. The new module entry should be added to the list of modules.

Click on the ``Review + create`` button to complete the module deployment.