Core Components

Many of the components listed in this section become relevant once your application is deployed on the edge. If it is desired to test the specific equipment in a lab, contact SLB to acquire a test gateway and instructions for setting up locally.

Generally, however, significant development can be done using the development tools provided in the SDK without having to use these component directly. For example, the Modbus Module can provide data at run-time, but you can simulate data message arriving in the system using DataIn messages from the CSV Reader application.

AEA-Broker

Agora Edge Applications communicate with one another via a message bus/broker. The broker used on the gateway is a custom MQTT broker based upon MQTTNetServer called the AEA-Broker. During development, any MQTT message broker such as Mosquitto or RabbitMQ can be used.

The AEA-Broker is not a generic message broker, which allows all messages to automatically flow between applications. Instead, messages are routed application to application using a routing table which, on the gateway, is configured by AgoraOps.

Routing prevents applications from imitating or even knowing about one another during development. At configuration time, routing can be configured in one location allowing the the operator to decide where message should be sent and handled at run-time.

Ops Agent

With a vision for AgoraOps personnel not being a full time developers it should be easy enough for them to change configuration or push configuration to edge apps running on gateway from outside or from any simple UI Interface.

In general, the Ops Agent watches for *.zip files in its FileIn folder. When files arrive, it starts a state machine to move the file to a working folder, unzip it, Update (more below), and the move to a Processed folder. If there are errors during any of this the agent will log that - and in the future, notify AgoraOps.

During Update there are several options. There are three behaviors supported in the config file: REPLACE, OVERLAY (default), and CLEANALL. To apply these commands to the configuration file, add a file of that name in the Root folder of the archive.

For example,

(AEABroker.zip)
    /REPLACE (file) <-- the command
    /AEABroker (folder) <-- the app folder
        /AEA.json
        /routes.json
        /keys (folder)

The Ops Agent expects to have a shared volume on the host with respective path for EdgeApp Receiving Configurations like shown below, it will push/Replace/recreate .zip files to the root /Configurations path

Config

Update Commands

REPLACE

Removes all files in every App folder and then moves the files from the zip file into the App folder. The config folder and config/keys folder are not removed, even if they don't exist in the *.zip file.

OVERLAY

Copies (and replaces) the files from the *.zip, but does not remove any existing files. This is useful if you only want to update a single file or key in the configuration.

CLEANALL

Cleans (removes all files in all apps). It does nothing with the rest of the zip file - even if it contains files... (that could be improved, but that is how it works today...)

OpsAgent

FileManager

With a vision for Agora Operations personnel not being a full-time developer it should be easy enough for them to change configuration or Push configuration to edge apps running on gateway from outside or from any simple UI Interface.

To be able to push configuration changes from cloud to Edge & Edge to Cloud where applications are running as container/s. These configurations essentially be an alternate configuration supported by EDGE SDK V2.0.

The Agora AEA2 File-Manager being core AEA component, handles file transfer for AEA2 applications to/from the cloud as well as hosts files for sharing at the edge. This AEA2 Edge app is built using C# Edge SDK 2.0 and it hosts a service within the container which has a listener for physical file/s on the host.

AEA2 Agora File TRansfer

Technical Design: Shared volume binding for file transfer across edge apps and cloud.

FileMgr

FileManager Deployment configuration

{
	"aea2filemgr": {
		"restartPolicy": "always",
		"settings": {
			"createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/var/FileManager/Files:/Files\",\"edge-share:/edge-share\"],\"Memory\":3145728000}}",
			"image": "{registryName}.azurecr.io/{ImageName}:{tagName}"
		},
		"status": "running",
		"type": "docker",
		"version": "1.0.1"
	}
}

AEA2 File Manager Supported Workflows

The File Manager takes advantage of IoN core module to move file/s to/from Gateway to Nimbus from Edge-Share. File Manager & other supporting Edge Apps like aea2-mqtt-borker, aea2-core-bridge etc. are supposed to deployed and proper routing needs to set up between them.

Request File Download (Agora Cloud to Edge Gateway)

1. Pushing Configuration/s or Alt Configuration/s Targeting AgoraOpsAgent

Agora File Manager works with Ops Agent to push file/s to an Edge app running on the gateway that could be anything (configuration files, alt configuration files or any other supporting files). The Edge App deployed on gateway needs to be commissioned as a virtual device from IOT-Admin Portal (Agora Ops) with a shard volume binding.

For example:

{
  "aea2edgeApp": {
    "restartPolicy": "always",
    "settings": {
      "createOptions": "{\"HostConfig\":{\"Binds\":[ \"/home/var/FileManager/Files/250/FileIn:/FileIn\",\"/home/var/FileManager/Files/250/FileOut:/FileOut\",\"/home/var/Configurations/EdgeAppNAme:/config\"],\"Memory\":3145728000}}",
      "image": "{registryName}.azurecr.io/{ImageName}:{tagName}"
    },
    "status": "running",
    "type": "docker",
    "version": "1.0.1"
  }
}
Note

"/home/var/FileManager/Files/250/FileIn:/FileIn" - Here 250 is the virtual device id comissioned on IOT admin portal.

To push alternate configuration below are the pre-requisites:

  1. Configuration files needs to be zipped & named same as that of EdgeAppName used in shared volume binding as highlighted above.
  2. On the gateway Agora Edge App AEA2 OpsAgent must be deployed. This Edge App needs to be also commissioned on Agora Ops Portal with a Virtual Device-ID. Sample container create option for AgoraOpsAgent. Here in this case a virtual Device ID 256 is used.
Note

{registryName}.azurecr.io/{ImageName}:{tagName}. Internal/Private Container Images are available on Agora Private Container Registry.

{
  "aea2opsagent": {
    "restartPolicy": "always",
    "settings": {
      "createOptions": "{\"HostConfig\":{\"Binds\":[\"/home/var/FileManager/Files/256/FileIn:/FileIn\",\"/home/var/Configurations/:/Configurations\",\"/home/var/Processed/:/Processed\"],\"Memory\":3145728000}}",
      "image": "{registryName}.azurecr.io/{ImageName}:{tagName}"
    },
    "status": "running",
    "type": "docker",
    "version": "1.0.1"
  }
}

For more info on Agora AEA2 OpsAgent refer to OpsAgent.

  1. On the gateway a Modbus-Module with below sample container create option should be deployed.
{
  "modbus-module": {
    "env": {
      "GATEWAY_MODULE": {
        "value": "enabled"
      }
    },
    "restartPolicy": "always",
    "settings": {
      "image": "{registryName}.azurecr.io/{ImageName}:{tagName}",
      "createOptions": "{\"HostConfig\":{\"Binds\":[\"/tmp:/tmp\",\"modbus-module-volume:/nv-data\",\"edge-share:/edge-share\",\"/home/var/FileManager/Files:/Files\"],\"PortBindings\":{\"19105/tcp\":[{\"HostPort\":\"19105\"}]},\"Memory\":52428800}}"
    },
    "status": "running",
    "type": "docker"
  }
}
  1. Finally initiate file transfer from Agora Ops Portal targeting virtual device commissioned for AgoraOpsAgent.

2. Publishing a File Targeting to an Edge App

In Agora AEA2 world, each application built using Edge SDK 2.0 expects to have host binding for

a. /FileIn --> This location should be used by application to expect any file from Nimbus.

b. /FileOut --> This location should be used by application to push any file to Nimbus.

c. /LocalShare --> This location should be used by application to store files locally & these files can be exposed via an HMI. With this HMI user will be able to locate, view, browse & download file locally.

d. /Config --> This location should be used by application to expect any alternate configuration to be used by Edge App from Nimbus for making a file transfer to an Edge App running on the gateway.

  • A host binding should be created for /FileIn that will be used by File-Manager.
  • A file transfer needs to be initiated from AgorOps Portal targeting a virtual Device-Id commissioned for that Edge App on Ops Portal.

A high-level sequence of activities that takes place when a file transfer has been initiated from Agora Ops Portal.

Note

These activities sequence is applicable to both of the workflows explained above, however Device-Id needs to be a Device-Id commissioned for Ops Agent Edge App on Ops Portal for Alt configuration File/s push.

FileMgr

Request File Upload (Edge Gateway to Agora Cloud)

Agora File Manager can push a file from Gateway to Nimbus. Module generating files needs to share volume with File Manager. File Manager will detect the files and push it to the Nimbus. The complete workflow is as shown below.

In Agora AEA2 world, each application built using Edge SDK 2.0 expects to have host binding for

a. /FileOut --> This location should be used by application to push any file to Nimbus.

FileMgr

Passthrough Handler

Introduction

IoDataReportPassThrough is a special type of message that is only recognized by Nimbus-adapter module. Nimbus-adapter module treats these type of messages separately & passes it to Nimbus.

For any Edge App to send passthrough messages to Nimbus, Passthrough-Handler Edge App makes it easy by extracting out all the logic to make any message an IoDataReportPassThroughMsg and send it to NImbus.

How it Works

IoDataReportPassThroughMsg:- It is a special type that Passthrough-Handler Edge App use to construct a passthrough message.

Currenly, Passthrough-Handler Edge App supports the below schema types to be converted to IoDatReportPassThroughMsg.

  • Event
  • Request
  • IODataReport
  • FileUpload

Passthrough-Handler Edge App expects the message sent to it as serialized version (equivalent Json String) of the above message type on a custom topic (topic name should have one of the above type names at the end).

Supported End points/Topics

Any message should be sent to the Passthrough-Handler Edge App over these topics depending on the above type of message.

  • PassThrough/Event,
  • PassThrough/Request,
  • PassThrough/IODataReport,
  • PassThrough/FileUpload.

FIle-Upload:- The Sender Edge App is expected to send the content of the file to be wrapped in json. For example:

{
  "File": "File Content"
}

Message Format

After receiving messages over these topics, Passthrough-Handler Edge App converts it to an IoDataReportPassThroughMsg payload.

Message --> This is test passthrough event.

IODataPassThroughTelemetry

Passthrough-Handler{ .img-thumbnail }

IODataReportPassThroughMsg

Passthrough-Handler{ .img-thumbnail }

Such payload is sent to ION as IODataReportPassthrough message type which indicates Nimbus to forward message to Onesite, Onesite can decode the protobuf message and show data.

Data Flow

Passthrough-Handler{ .img-thumbnail }

Network Module

The Network Module controls the network interfaces of the gateway, it makes available a User Interface (NMTUI) that can be accessed by an user who has access to the host machine's console.

Network Application

The network application is an HTTP wrapper that bridges the communication between the containers (applications) and the Network Module. It runs as a hosted application exposing the HTTP server on port 5000 of the docker0 interface, so it is inaccessible to the external devices and only available to the docker containers and the host. With the applications, you can query for the network information as well as gps data. The modules can also change network configuration and select different media as northbound connectivity.

Security Module

The Security Module provides endpoint visibility into security posture management and threat detection. It is integrated with SLB Cybersecurity Operation Center for 24/7 security monitoring and incident response.

Pipesim Module


This is a Place Holder for pipesim Module.

Redis Server

Redis is an advanced key-value store that can function as a NoSQL database or as a momery-cache store to improve performance when serving data that is stored in system momory.

Currently Redis Server is an integral part of Hermes base core release. It is used as an intermediate module by edm-app and edge_device_mgmt module on the gateway. It is also used as a continuous backend data store for Edge API Gateway Module which is a webapp hosted on gateway.

It is deployed with below container create options.

Data Store: Continuous with below named shared volume binding.

[
    {
        "CreatedAt": "2023-05-22T08:47:15Z",
        "Driver": "local",
        "Labels": null,
        "Mountpoint": "/storage/var/lib/docker/volumes/redis-volume/_data",
        "Name": "redis-volume",
        "Options": null,
        "Scope": "local"
    }
]

To connect the Redis Server Edge SDK provides a full-fledged RedisClient.

AEA Unit Converter

This is a Place Holder for AEA Unit Converter



































```Text