Environment Setup

The ABB Ability™ Edge uses secure protocols to setup and transmit data to and from the Ability Platform. Edge nodes run on Linux based operating systems and use a combination of ABB provided and custom Docker containers to enable connectivity between devices and the Ability Platform. This guide provides the necessary steps to setup, develop, test and deploy a custom Edge module.

Many factors must be considered when creating an edge application. This document will cover key areas that should be considered during development of a custom application.

Once a suitable Edge environment is selected, use the following steps to install and configure the Edge.

• Access to the ABB Ability™ Platform Admin Portal and DPS Scope ID for your instance.
• Proper configuration of an Ability Solution that will allow devices to be registered.
• Identify and acquire the necessary software based on selected hardware.
• Install the Edge software after the operating systems has been installed on supported hardware.
• Configure the Edge to run against an Ability Platform with a specific Edge Type.

The steps above provide the simplest path to deploying an Edge. Advanced configuration options are available and the following information can be used to additionally customize the Edge.

• Advanced Edge Configuration.

Edge Hardware and Network Connectivity

The following three topics should be evaluated when planning Edge deployment.

• Edge Hardware - almost any type of hardware can be used to develop software for an Edge. However, all production and testing Edge hardware must include TPM hardware to insure end-to-end security for the product. Windows Hyper-V Gen 2 hardware can be used for testing as it supports a virtual TPM 2.0.
• Edge Hardware Specifications - each application is different. Hardware must have enough resources to run your application. If the hardware is fixed, then the application must be designed to run within the resource limits of the hardware.
• Edge Bandwidth - network bandwidth is independent of the hardware selected. Most hardware comes with 1000BT network connectivity. However, if the internet connection is limited by a site internet connection or cellular phone data bandwidth, the application will need to keep the telemetry under those limits. Conversely, if the application bandwidth is a known requirement at the beginning of the project, then appropriate bandwidth connections can be configured when the product is deployed.

Secure Edge Connectivity to the Ability Platform

Ability Platform can only accept connections from devices with a valid X.509 certificates issued by Ability PKI Trusted Authority in the production environment. For development and test purposes prior to the production, Ability PKI offers test and pre-production environments.

Ability PKI

Ability Public Key Infrastructure offers services including Certificate enrollment, renewal, revocation etc. Ability Edge provides configuration place holders to be updated by the developers depending upon the purpose (dev/test/production), when updated Ability Edge autonomously enroll itself with the Ability PKI based on the configuration. The certificates rooted in the Ability ROOT CA are used for authentication of the devices connecting to the Ability Platform. To learn more about Ability PKI, refer to the PKI Overiew page. For development and testing, refer to the instructions detailed for PKI Developers.

Persistence

Each module container has mounted directory files with rw access which allow the module to store any files that need to be persisted between restarts. All files in other directories will be lost on container restart.

A module should not attempt to store its configuration model, instead either relying on the MQTT subscription to the models topic (in case of a persistent session) or requesting its model on startup (see the "Sending Device-to-Cloud Messages" section, model message type, below).

Connecting to MQTT Broker

Each module is injected with an MQTT server URL in the environment variable {mqtt_url}. The password file location is injected as {mqtt_password_file}.

Use {module_id} as a username and {mqtt_client_id} as a clientId if you wish to maintain a persistent session.

NOTE

If your module is configured with more than one replica, you must use a different client ID for each of the replicas, or the broker will disconnect the previous client upon the connection of the new one with the same client ID.

The default QoS level for messages published by a proxy is at least once (all incoming messages except for {topics_local_in}).

since it is up to the publishing module in that case). This means that modules must be able to handle duplicate messages (idempotent method implementations are highly recommended).

It is up to the module to define QoS for outgoing messages. Each module is entitled only to a set of topics that is injected with environment variables. Any topic ending with _in_ represents a read-only access, and _out_ represents a write-only access.

NOTE

Denial of access does not constitute an error, rather it means that if a client subscribes to a topic and is denied, the client doesn’t know it has been denied as it receives a positive acknowledgement. The same applies to publishing, i.e. if a client publishes to a topic and is denied, again the client doesn’t know it has been denied as it receives a positive acknowledgement.

Acknowledgement Messages

NOTE

For a complete list of acknowledgement messages, see Acknowledgement Handling in the Device API section.

Modules have the capability to ask for acknowledgements for certain types of messages sent to the cloud. Messages that are sent to {topics_messages_out} and {topics_model_out} are the two current supported types of messages which will propagate an acknowledgement back to the module. Ask for such acknowledgements by adding the "ack" property to the property bag of the respective message, with the property bag being the URL-encoded key/value pairs of message properties. There are four types of supported "ack" values:

• none: No acknowledgement will be sent back.
• positive: Only successful acknowledgements will be sent back.
• negative: Only failed acknowledgements will be sent back.
• all: An acknowledgement will be sent back regardless of the success status.

If the module does not set the "ack" property, the proxy will set it to "none" in the corresponding message.

To receive the acknowledgement, you must subscribe to {topics_messages_in}.

The "ack" message is relayed directly from the DCS, with the properties converted to the key/value pair in the message's topic and the payload relayed as is. Please refer to the respective documentation regarding the properties present in the incoming "ack" message.

Additional Topics

Quick Start

If you are unfamiliar with the Ability Edge environment, a pre-built environment is available. Navigate to the Getting Started section for step by step instructions to setup and run simple edge

Development Languages

Select the supported development language you are planning to use and prepare one or more environments for runtime and development. If you have already set up an environment and are ready for development, explore the supported languages.

Supported Languages

Ability Edge modules can be created in any programming language. Have a look at examples of modules prepared in .NET C#

Edge Module Memory Allocation

A generic Docker container is allotted 64MB of shared memory for Interprocess communication (IPC), represented as mount point /dev/shm. The capacity limit offered by the Docker container for IPC is insufficient for a software solution, such as cpmPlus History.

A temporary filesystem (tmpfs) mount, a Docker feature, increases container memory limit capacity. A tmpfs mount gives container access to the data without writing it anywhere permanently, only stored in the host machine’s memory (or swap, if memory is low). When the container stops, the tmpfs mount is removed. If a container is committed, the tmpfs mount is not saved.

Edge removes the arbitrarily chosen capacity limit of 64 MB to running containers and offers an unrestricted amount of memory-backed file system to all containers running on Edge; tmpfs container mount option supports such
operation. This means, at the runtime, each container module gets an additional bind mount of type tmpfs at target /dev/shm in addition to their 64MB allocation. As a result, programs running in each container will have far more capacity available for IPC, which also remains isolated from other containers using the same IPC mechanism.
On the container host, memory usage will not increase if the offered capacity limit remains unused.

NOTE

This feature is applicable for both Edge Proxy and Edge Agent (future replacement of Edge Proxy - work in progress). It supports Edge Proxy version 2.4.12 and above.

This elimination of capacity restrictions allows businesses to write memory intensive software like time series calculators on the Edge.