Ability™ Developer Portal
Try Sandbox for free
Get a month of free access to ABB Ability™ Platform to learn and experiment!
API Playground
Play with ABB Ability™ Platform APIs (no time limits)

# Edge Agent Release Notes

# 23.1

# 23.1.1

abbability.azurecr.io/edge/agent:23.1.1.1

Note

The naming convention for the image tag version from the release has been updated to align with cloud releases

Supported Stack:

  • Installer: 2.5.0 or higher
  • Edge Security: 3.2.8 or higher

# New Features

# [78482] Centralized Edge Log Streaming

# New Functionality

This feature adds the ability to stream logs from the Containers running on the edge to a centralized log aggregation server in the cloud for analysis and troubleshooting. These logs can be accessed using Kibana, which is hosted in the cloud. Log streaming will be available exclusively for Edge devices and not for devices behind the Edge.

To enable this feature, configure the log-agent module in the Edge Configuration Model's modules section. Enabling the "ENABLE BOOTSTRAP CENTRAL LOGGING" flag in the edge.env will allow you to stream logs from the bootstrap level if necessary.

# [105320] Edge Health/Performance Monitoring

# New Functionality

This feature covers the following:

  • Monitoring predefined health and performance parameters on the edge device
  • Enhanced Logging for better troubleshooting and diagnostics
  • View a monitoring dashboard locally on the edge
  • Auto heal a known list of recoverable failures identified by the Monitoring service

# [65640] Management of Edge Docker Registry Credentials on Docker Swarm

# New Functionality

This feature brings the following capabilities on the Edge:

  • Securely storing the Docker Registry Credentials on the Edge Device
  • Support to add new Docker Registry Credential/Update and existing Registry Credentials remotely using Edge Configuration Model
  • Support to remove an existing Docker Registry Credential remotely using Method Calls. To enable this feature, the user needs to set "SECURE_CREDENTIALS" = true in the edge.env

# Resolved Issues

# [123069] - The resolution of heartbeat from Edge Device is in 'seconds' instead of 'milliseconds'

To ensure backward compatibility with previous nodeJs edge-proxies, the heartbeat resolution from Edge Device is set to'milliseconds' rather than'seconds'.

# [120411] - Occasionally, Edge fails to connect to IoT Hub at startup on small form factor ARM devices due to AMQP connection failure

When the device returns to an Online state, the device client SDK on the Edge occasionally fails to make an AMQP connection to IotHub (i.e. no Internet available state to Internet available state). This issue has been resolved.

# [121156] - Addition of Environment Variables for Edge modules from the Configuration model fails occasionally

This issue has been fixed.

# 22.4

# 22.4.2

abbability.azurecr.io/edge/agent:22.4.2.1

# Resolved Issues

# [121151] - Edge in offline state (i.e. no internet available) is unable to buffer the telemetry data as per the thresholds configured in Edge Configuration Model on small form factor devices

The Edge can now locally retain telemetry data up to 100Mb (this limit will be expanded in future release) and send that data to the Cloud once connectivity has been restored.

# [121148] - C2D Messages are not delivered to the device as the messages are queued up in IoTHub

The issue arises when the device is unable to dequeue the IoTHub messages. This has been fixed.

# [116815] - Occasionally container Start and Running status are missing even though a new container is running or an existing container is updated

The Data Processing Pipeline in the Cloud would occasionally reject the telemetry since the container Start and Running status were occasionally sent with null objectId. As a result, the consuming applications cannot access this data via the Ability Cloud's Hot/Warm/Cold data channel. By ensuring that the telemetry is always transmitted with necessary information like the objectId included, this problem has now been resolved.

# Known Issue

# [120411] - Occasionally, Edge fails to connect to IoTHub at startup on small form factor ARM devices due to AMQP connection failure

When the device returns to an Online state, the device client SDK on the Edge occasionally fails to initiate an AMQP connection to IotHub (i.e. no Internet available state to Internet available state).

Work Around: Contact Ability Platform Operations Team to take recovery measures.

# 22.4.1

abbability.azurecr.io/edge/agent:22.4.1.1

Note

The naming convention for the image tag version from the release has been updated to align with cloud releases

Supported Stack:

  • Installer: 2.4.0 or higher
  • Edge Security: 3.2.8 or higher

# New Features

# [108294] Support for passing objectId & model with the method Invocation call

# New Functionality

To enable the addition of "objectId" and "model" with the method invocation call, the "methodRequestEnrichment" flag needs to be set to "true" on the Edge configuration model as shown below.

{
    "model": "abb.ability.configuration",
    "typeId": "abb.ability.configuration.edge.sample",
    "version": "1.0.0",
    "description": "Edge gateway configuration",
    "attributes": {...},
    "properties": {
        "systemModules": {
            "edge-proxy": {
                "image": {...},
                "configuration": {
                    "apiVersion": {
                        "description": "api version and mqtt topic version to be used, v1 or v2",
                        "dataType": "string",
                        "value": "v1"
                    },
                    "methodRequestEnrichment": {
                        "description": "A Boolean flag to control the addition of passing objectId with the method Invocation call while using apiVersion V1. If set to true, objectId  and model property would be added to the method invocation topic",
                        "dataType": "boolean",
                        "value": false,
                        "isMandatory": false
                    },
                  "feature": {
                        "EdgeSecrets": {
                            "dataType": "boolean",
                            "value": false,
                            "isMandatory": false
                        },
                        "BrokerAnalytics": {
                            "dataType": "boolean",
                            "value": false,
                            "isMandatory": false
                        }
                    }
                }
            },
            "edge-broker": {...}
        },
        "modules": {...}
    }
}

For any Edge configuration model that has "methodRequestEnrichment" set to true, the Module API topic where the module is notified, will have the "objectId" and "model" included in the topic structure as shown below.

Topic: "modules/{moduleName}/methods/req/{methodName}/{requestId}&objectId={objectId}&model={model}"

Payload:

{
    "input": {
        "samplePayloadProperty": "samplePayloadValue"
    }
}

# [109808] Support for publishing device and configuration models of Edge and Edge modules onto the system topic

# New Functionality

This feature would enable the capability of exposing the system topic to the Edge modules, which would contain the device and configuration models of all the Edge modules. The topic structure for the MQTT broker would be:

Topic Details:

system/<moduleName>/model/desired/abb.ability.device/<objectId>

system/<moduleName>/model/desired/abb.ability.configuration/<objectId>

To enable this feature, BrokerAnalytics flag in the Edge configuration model must be set to true.

{
    "model": "abb.ability.configuration",
    "typeId": "abb.ability.configuration.edge.sample",
    "version": "1.0.0",
    "description": "Edge gateway configuration",
    "attributes": {...},
    "properties": {
        "systemModules": {
            "edge-proxy": {
                "image": {...},
                "configuration": {
                    "apiVersion": {
                        "description": "api version and mqtt topic version to be used, v1 or v2",
                        "dataType": "string",
                        "value": "v1"
                    },
                    "methodRequestEnrichment": {
                        "description": "A Boolean flag to control the addition of passing objectId with the method Invocation call while using apiVersion V1. If set to true, objectId  and model property would be added to the method invocation topic",
                        "dataType": "boolean",
                        "value": false,
                        "isMandatory": false
                    },
                  "feature": {
                        "EdgeSecrets": {
                            "dataType": "boolean",
                            "value": false,
                            "isMandatory": false
                        },
                        "BrokerAnalytics": {
                            "dataType": "boolean",
                            "value": false,
                            "isMandatory": false
                        }
                    }
                }
            },
            "edge-broker": {...}
        },
        "modules": {...}
    }
}

# [107844] Support for publishing the accepted encoding formats by the Edge Device

# New Functionality

The Edge Device now has the capability of publishing the encoding formats that are supported for any communication with the Ability Platform.

This version of Agent requires a mandatory Edge Device Type Definition Update to include the accept-encoding property as shown below:

{
    "model": "abb.ability.device",
    "typeId": "abb.ability.device.edge.device.agent.sample",
    "version": "1.0.0",
    "description": "Edge Device Model",
    "unique": [
        "deviceId"
    ],
    "properties": {
        "accept-encoding": {
            "description": "List of accepted device encodings ",
            "dataType": "array",
            "items": "string",
            "enum": [
                "utf-8",
                "gzip",
                "deflate"
            ]
        },
...
}

# [110120] Support for deletion of persisted device and configuration models in the MQTT Broker when a "model.delete" request is sent and successfully executed in the Cloud

# New Functionality

When a "model.delete" Device API v2 action is sent for the device model, this request deletes the requested device model and also deletes the implicit subscription for the configuration model; however, the "ObjectModel.Deleted" notification for the device model is no longer sent by the Cloud to the device. This feature enables the Edge to delete any persisted device and configuration models in the MQTT Broker after a "model.delete" request is sent and successfully executed in the Cloud.

# [109353] Support for fetching the Docker state using a method call

# New Functionality

Enable support in the Agent to fetch the state of the module and running image using a method call. Update the Edge Type Device Type to include the below method definition.

"methods": {
    "fetchModuleState": {
        "description": "Publishes the state of modules running on the edge device",
        "input": {
            "names": {
                "dataType": "array",
                "items": "string"
            }
        }
    }
}

# Resolved Issues

# [110397] - Large File Upload on low internet bandwidth edges are failing

This issue occurred as a result of a lower timeout setting for the file upload, which has been resolved now by setting a maximum timeout of 1 hour for a file upload.
This was verified by uploading a 249 MB file from an Edge on a 1 Mbps network, and the upload was completed in approximately 45 minutes.

# [112046] - Agent sends device request to Cloud when connectivityMode =connectondemand

Edge in connectondemand mode sends the deviceApi requests to the Cloud, while the expectation is to ignore the device actions. This issue is fixed now.

# [114219] - Content-encoding' for device actions are not defaulting to 'off' when an unsupported is set with apiVersion V1

The compression for device actions is only supported with apiVersion V2. It was observed that the compression header "content-encoding" is not defaulting to "utf-8" (which is equivalent to no compression) in apiVersion V1. This has now been fixed, and the "content-encoding" header would default to "utf-8" when apiVersion is V1.

# [114481] - Sensitive Information are not masked in the logs

Docker Registry Credential and MQTT Password, which get logged in plain text in the logs when the log level is trace or higher, have been masked now.

# [115024] - Device CPU & Memory Utilization Statistics Reported by Edge is Inaccurate

It was observed that the device CPU and memory utilization statistics reported by Edge did not match the actual statistics found on the Edge. This has now been fixed.

# [119989] - Occasionally Edge fails to boot after a firmware over the air (FOTA) update while switching from the predecessor nodeJS proxy to the new C# Agent

Edge fails to boot after a firmware over the air (FOTA) update while switching from the predecessor nodeJS proxy to the new C# Agent. During this period, the Edge remains offline for a period of time, and during this period, if there are any updates to the abb.ability.configuration model other than that of the Edge proxy itself, then the Edge would lock up after booting up. This has been resolved by including a bootstrap persist.db containing the specification of the Edge broker, which is necessary to prevent this lockup.

# [120003] - The telemetry transfer rate to Cloud is extremely slow on small form factor ARM devices (for example, 1 CPU and 1 GB RAM)

This has been resolved by optimizing the disk I/O on the device, thereby speeding up the telemetry transmission process.  The optimization also includes switching from a single dedicated client for telemetry to three different clients for reading variables, alarms, and events, respectively.

Limitation
Due to the introduction of this new design, batching all three types of telemetry, i.e., variables, alarms, and events, into a single telemetry message before publishing to the IotHub would not be possible; instead, each type of telemetry is batched independently as defined by the count, duration, and size constraints defined in the Edge configuration model.

# [120020] - Data accumulated in the Edge Broker during an offline window in over the configured limit

Data accumulation over the configured limit of Edge Broker is a limitation in Mosquitto. To resolve this, the business logic to fetch and transmit the telemetry to the Cloud has been redesigned so that the data will be moved to an intermediate persistent store that honors the limits set for the Mosquitto DB. When the Edge is back online, the data from the intermediate persistent store is dequeued and transmitted to the Cloud, after which the live telemetry from the Edge broker is transmitted. As a result, the telemetry data is never queued on the Edge broker, which prevents the Mosquitto DB growth.

# Known Limitations

# [117586] - Edge Agent doesn't support case-sensitive Docker Environment Variables

The environment variables set in properties.docker.env of the module configuration model as well as properties.globalEnvironmentVariables in the Edge configuration model are case-insensitive. For example, http_proxy and HTTP_PROXY are treated as duplicate keys, which will result in Docker service creation failure. More details regarding the management of configuration values in .NET are available here.

As a part of the upgrade to C# Agent, please ensure to update the following:

  1. Any configuration model for Edge modules where properties.docker.env contains a case-sensitive key-value pair needs to be cleaned up by the module owner to ensure only one instance of a case-insensitive key-value pair is retained.
  2. The configuration type with which the module was provisioned needs to be updated to ensure only one instance of a case-insensitive key-value pair is retained in the properties.docker.env so that new modules are not provisioned with such case-sensitive key-value pairs.

# [121039] - Edge Broker has accumulated data which never gets dequeued after switching from nodeJs proxy to the new C#Agent

This is due to a client_id change from the node.js proxy to the new C#Agent. The data associated with the old client_id would never get dequeued; instead, it would keep growing as the client is a persistent client with a validity of 1 year. 
Please contact the Ability Platform Operations team if this issue is observed.

# 22.1

# 22.1.1

abbability.azurecr.io/edge/agent:2.2.0

# New Features

# [75663] - Edge Device to Cloud (D2C) Message Compression

# New Functionality

This feature decreases the amount of data sent over the wire by compressing the device to cloud (D2C) messages. For more info about the compression, see the article Edge Device to Cloud (D2C) Message Compression.

# [95101] - Persistence of last known Edge Configuration locally

# New Functionality

This feature allows the edge to get the Edge Broker service up & running from a last known configuration of the edge stored locally on the device.

This local configuration will also honor the last known values of Compression & Batching properties when the Edge Agent Service restarts.

# [108871] - General Edge code refactoring

# New Functionality

This feature focused on general Edge improvements and revised the following:

[104545] Consistency improvements regarding the Topic Structure used for Method Implementation in Module API V2 when compared with the specification

Topic: SUB to/module/{module_id}/action/method/invoke

Expected: to/module/{module_id}/action/method/invoke&method={methodName}&requestId={request_id}&objectId={object_id}&model={model)

Actual: The implementation prior to this release followed the format shown below to/module/{module_id}/action/method/invoke/{methodName}/{request_id}

Topic: PUB from/module/{module_id}/ack/method/invoke

Expected: from/module/{module_id}/ack/method/invoke&statusCode={HttpStatusCode}&requestId={request_id}&method={methodName}&objectId={object_id}&model={model)

Actual: The implementation prior to this release followed the format shown below from/module/{module_id}/ack/method/invoke/{HttpStatusCode}/{request_id}

This has been addressed to match the expected format, as shown above.

[103860] Removal of the restrictions in sending additional properties with the Module API V2 Actions

Before this release, any additional property sent with the Module API V2 Actions like model.create, model.update, model.patch or type.create was discarded, and the request was forwarded without those additional properties.
For Example: Consider a type create request as shown below.

Topic: from/module/reference_module/action/type/create&model=abb.ability.device&ack=all

Payload sent by the reference_module to the Broker:

{ 
    "typeId": "abb.ability.device.referenceType",
    "model": "abb.ability.device",
    "version": "1.0.0",
    "isExtensible": true
}

Payload sent by theAgent to the Ability Platform:

{ 
    "typeId": "abb.ability.device.referenceType",
    "model": "abb.ability.device",
    "version": "1.0.0"
}

The property isExtensible is dropped before forwarding the request to the Ability Platform.
This has been addressed to ensure that the Edge does not drop the properties. Instead, let the Ability Platform validate the request and acknowledge it.

[105427] The default behavior for telemetry compression when the properties:telemetry:compression is configured with a value other than the accepted encoding formats, which are gzip and deflate

Before this release, there was no default behavior to handle the case where the encoding formats configured for properties:telemetry:compression is other than gzip or deflate.

This has been addressed to ensure the encoding format defaults to utf-8 (which is no compression enabled) if properties:telemetry:compression is configured to a value other than gzip or deflate.

# Resolved Issues

# [76579] - Deleted device configuration is not removed from MQTT retained messages

Before this release, when objects were deleted in V1, the device models were cleared while the configuration model persisted in the MQTT Broker.

This has been addressed to ensure that the configuration model of type abb.ability.configuration is removed from the MQTT Broker while deleting the device model.

# [98037] - Edge Agent fails to boot when the module configuration model is updated while the device is offline

It was impossible to send model updates for Edge modules/devices connected behind the modules from the Platform when the receiving Edge device was offline. It prevented Edge Agent from starting the broker and Edge modules after the device booted.

Before this release, there was a temporary workaround where the C2D updates sent during the offline period were discarded.

This issue has been addressed now. As a result, any C2D messages sent during the offline period are not discarded.

# [105725] - Custom permissions added for a few edge modules are missing in file.acl at startup

Edge Modules can be configured to allow additional permissions using properties:broker section in the edge module configuration model.

These permissions were reset during an upgrade of C#Agent.

This has been addressed to retain the permissions set before the upgrade.

# [106277] - Edge Agent restarts multiple times at startup before reaching a stable state

It has been observed that Edge Agent restarts a few times at startup before reaching a stable state.

The issue has been addressed, and no additional restarts occur now.

Note: While upgrading from nodeJS proxy to C#Agent, there will still be an additional restart due to the addition of new environment variables for Agent by design.

It is recommended to update the EDGEPROXYIMAGE in the edge.env to the Edge Agent Image before upgrading from nodeJS proxy to C#Agent to avoid this additional restart cycle.

# [106960] - Edge Agent prints a log statement at INFO log level for every telemetry sent

Before this release, Edge Agent printed a log statement at INFO log level for every telemetry sent.

This has been addressed, and telemetry logs are printed only at DEBUG log level.

# [108249] - Environment variables configured at an individual module level is lost when global environment variables are configured

Environment variables configured at an individual module level is lost when global environment variables are configured

Currently, it is possible to configure environment variables for an edge module using two ways:

  • by configuring key value pairs inside properties:docker:env section of the edge module configuration,
  • by configuring key value pairs inside properties:globalEnvironmentVariables section of the edge configuration, which is common for all edge modules.

It was observed that configuring environment variables using properties:globalEnvironmentVariables section of the edge configuration removed the environment variables inside the edge module containers configured using "properties:docker:env" section of the edge module configuration. This has been addressed to ensure that the environment variables are not lost while configuring globalEnvironmentVariables which are common across all edge modules.

# Known Issues

# [100706] - MQTT object persistence - inconsistent behavior between Device API V1 and V2

Both device and configuration models are deleted when objects are deleted in Edge running on apiVersion V1. However, in V2, any persisted models for the deleted objects are not cleared.

The expected behavior is to clear both device and configuration models for the deleted objects.

# [108905] - Edge Agent CPU load is significantly higher

The current CPU usage of Edge Agent is higher in comparison to Edge Proxy. For example, a telemetry load test of 500perSecond indicated that the CPU usage of Edge Agent is 1.4 times higher than Edge Proxy.

The performance will be improved in the upcoming releases.

# 21.4

# 21.4.2

abbability.azurecr.io/edge/agent:2.1.0

# New Features

# [75629] - Device Action Batching (Device API v2)

# New Functionality

This feature allows an edge module to send one or more actions (combined in a single list), which the Cloud processes in the supplied order.

# [99557] - Support for configuration-based addition of custom header for outgoing telemetries from a device to skip telemetry validation in the cloud

# New Functionality

This feature supports adding a custom header to all the outgoing telemetries from a given device based on a configuration flag in the Edge Configuration. It allows the data processing component in the cloud (DPP) to perform header-based checks to decide if a given piece of telemetry needs to be validated or not. The default value for this configuration would be false, indicating that the telemetries will undergo validation, which is the current behavior. The telemetry validation can be skipped by changing the configuration in Edge type at the location properties.telemetry.skipValidation as shown below:

"properties":{
   "telemetry":{
      "skipValidation":{
         "dataType":"boolean",
         "value":false,
         "isMandatory":false
      }
   }
}

# Resolved Issues

# [90051] - Edge Agent may stop receiving new C2D messages

The Agent stopped receiving new C2D messages sporadically. It didn't impact sending telemetry, files, or D2C actions from the device to the cloud.

The issue is now fixed.

# [96100] - Edge Agent does not recover from missing type on the first boot

The creation of Edge failed if the Edge Type was not available in the Cloud during the provisioning. This exception is now being handled, and Agent would recover automatically once the type is created in the Cloud.

# [97729] - IM Public Key topic is not listed in environment variables

A new environment variable topicsV2_platformevent=event/ is added if the apiVersion is set to V2.

# [100564] - Batched telemetry could exceed max IoT Hub limit

Assuming maxDeviceMessageSize is set to 256KB in the Edge Configuration, the batched telemetry could cross this limit if the telemetry batching condition is based on the size of the batched message.
This case has been addressed.

# [101611] - Topics have an extra parameter at the end of the topic

Topic names for sending acknowledgments in module API V2 have an additional parameter at the end of the topic, which is not part of the specification.

For example, the topic name for sending the ack for model create used to look like:

to/module/<module name>/ack/model/create/type=model.create, and the /type=model.create at the end of the topic is an additional parameter that was not part of the spec.

This specification discrepancy has been fixed by removing this from all the module API V2 responses.

# [104477] - "mqtt_url" Docker environment variable had an additional symbol at the end

Few MQTT clients were unable to connect to the edge broker due to their inability to handle the "/" at the end of the MQTT connection URL:

mqtt_url=mqtt://edge-broker:1883/

This has now been addressed by removing "/" at the end of the URL.

# [104539] - [V1] The topic name in the broker, where the references resulting out of model.query are published, is incorrect

The results of the Model Query where references were involved were getting written into the topic as shown below:

modules/<module name>/model/desired.

However, the expected topic to write the references was as below:

modules/<module name>/model/desired/<model id>/<objectId>

This has now been fixed to write the references into the expected topic as mentioned above.

# [104553] - Creating a module to container dictionary triggers an error when a large number of modules (~20) are added or updated simultaneously

The Edge setup, with a large number of modules (for example, 20 edge modules), used to trigger errors under rare circumstances. This exception is now handled, and the addition of a large number of modules will not trigger any conflicts resulting in an Edge reboot

# [107489] - Mismatch in the header property name used to pass the value of correlationId in Module API V2

The correlationId parameter for any V2 action is currently accepted by appending &id=<value> to the topic name. However, as per the specification, the expected format of passing the correlationId is &correlationId=<value>. This case has been addressed now.

Note: There is no change to the V1 Module API.

# Known Issues

# [76579][100706] - MQTT object persistence - inconsistent behavior between Device API V1 and V2

When objects are deleted in V1 (Proxy/Agent), the device models are cleared while the configuration model persists. However, in V2, any persisted models for the deleted objects are not cleared.

The expected behavior is to clear both device and configuration models for the deleted objects both in V1 and V2 API Version.

# [98037] - Edge Agent fails to boot when module configuration model is updated while the device is offline

Issue Description: It was not possible to send model updates for Edge modules from the Platform when the receiving Edge device was offline. This prevented Edge Agent from starting the broker and Edge modules after the device booted.

Workaround: A temporary workaround has been implemented where the C2D updates sent during the offline period are discarded. This limitation will be addressed in a future release to prevent the C2D updates from being lost.

# [104545] Topic Structure used for Method Implementation in Module API V2 has some deviations when compared with Spec

  1. Topic: SUB to/module/{module_id}/action/method/invoke

    Expected:
    to/module/{module_id}/action/method/invoke&method={methodName}&requestId={request_id}&objectId={object_id}&model={model)

    The actual implementation today follows the format shown below.

    Actual:
    to/module/{module_id}/action/method/invoke/{methodName}/{request_id}

  2. Topic: PUB from/module/{module_id}/ack/method/invoke

    Expected:
    from/module/{module_id}/ack/method/invoke&statusCode={HttpStatusCode}&requestId={request_id}&method={methodName}&objectId={object_id}&model={model)

    The actual implementation today follows the format shown below.

    Actual:
    from/module/{module_id}/ack/method/invoke/{HttpStatusCode}/{request_id}

    The mismatch will be addressed in the next release.

# [99717] - Edge Agent CPU load is significantly higher

The current CPU usage of Edge Agent is higher in comparison to Edge Proxy. For example, a telemetry load test of 500perSecond indicated that the CPU usage of Edge Agent is 1.5 times higher than Edge Proxy.

The performance will be improved in the upcoming releases.

# 21.4.1

abbability.azurecr.io/edge/agent:2.0.0

Important notes

  • Ability Edge Agent is a drop-in replacement to the Ability Edge Proxy component with apiVersion set to V1 (see details below). In the future, functional extensions will be only done for Ability Edge Agent, and it is planned to make Ability Edge Proxy obsolete by March 2022.

  • Ability Edge Agent is compatible with Ability Platform 20.10 and later.

  • It is recommended to use the latest Ability Edge Installer and Ability Edge Security packages.

  • This release is only for R&D activities. Please review the known issues section while evaluating this release.

# New Features

# [58158] Edge Module API V2 Support

# New Functionality

Allows Edge Modules to communicate with the cloud using Module & Device API V2.

Note that “apiVersion” is set to V1 by default. You can change this value to V2 using a configuration flag in the type definition of the configuration model. Ability Edge will only support either V1 or V2 at any given time - supporting both simultaneously is not possible.

The following is a list of the supported APIs which are a part of this feature:

  • Extensions
  • References
  • Types
  • Ownership
  • Models
  • Identity
  • Methods
  • Telemetry
  • Local
  • File Upload
# Limitations

The following Module APIs are currently not supported in this version:

  • Subscriptions
  • Device Action Batching

There are a few deviations in Module API V2 when compared with the specification which will be addressed in future releases.

Edge Device Module API V2 - Deviations

  • Module API V2 patch has not yet been implemented.
  • The correlationId parameter for any V2 device action is currently accepted by appending &id=<value> to the topic name. In the near future, we will release an update to accept ‘correlationId’ by appending &correlationId =<value> to the topic.
  • The module API V2 actions do not currently accept additional parameters in the payload due to strict serialization. We will allow additional parameters in the payload as per the specifications in a future release.
# Required Migrations

By default, apiVersion is set to v1. To enable support for V2 APIs, the apiVersion feature flag needs to be configured in the type definition of the configuration model of your Edge device. This should be done in the configuration section before setting up the Edge to enable V2 topics.

# [60053] - File Sharing between Edge Modules

# New Functionality

Edge modules can now share files with each other. This feature is only supported by API V2, so apiVersion must be set to v2.

# [62324] - Publishing and subscribing to messages

# New Functionality

This feature allows one Edge Module to publish a message and other Edge Modules to subscribe instead of a one-to-one communication over a topic. API V2 only supports this feature, so apiVersion must be set to v2.

# [62959] - Allowing Edge module to have shared memory greater than 64M

# New Functionality

We have removed the Edge capacity limit of 64 MB in running containers. This allows modules to mount a temporary file system and use it for Inter-process communication (IPC). This operation is well supported by the container mount option using the "tmpfs" type name. Consequently, programs running in each container will have unrestricted, private capacity for IPC.

The elimination of capacity restrictions allows BU to write memory-intense pieces of software like timeSeries calculators on the Edge.

# [76321][89072] - Support for Edge Secrets with module API V1 and API V2

# New Functionality

Edge modules can now store and manage secrets and keys for various purposes. These secrets can be secured both in transit and at rest, as per the minimum Cyber Security recommendations. Keys, connection strings, passwords, and other secrets through information models are now stored securely with this update.

Supported format:

  • RSA
  • With paddings: PKCS#1
  • Only 2048-bit keys are supported

The keys belonging to various modules are stored in Docker Secrets. Docker secrets persist at rest in raft logs. To ensure that they are protected by TPM (hardware root of Trust for MCSR compliance), the raft logs are protected using the Docker swarm auto-lock feature.

Edge Secrets feature is supported on both V1 and V2 Module API Version and it can be turned on by enabling edge secrets feature flag with apiVersion set to V1 or V2 while the platform version is 20.10.6 or higher

# Known Issues

# [90051] Edge Agent stops receiving new C2D messages

Issue Description: After running Edge Agent for a few weeks, we have observed that occasionally the Agent stops receiving new C2D messages. However, this doesn't impact sending telemetry, files, or D2C action from the device to the cloud. This issue has occurred on a few Ability Edge devices over the last few months.

Workaround: Restart the Edge Agent service to re-establish the connection with the IoT Hub.

# [96100] Edge Agent does not recover from missing type on first boot

Issue Description: The normal procedure is to have the Edge type created in the cloud before starting the Edge Agent for the first time. If the Edge type is not available in the cloud, the Edge Agent fails to boot.

Workaround: Create an Edge type in the cloud and restart the Edge Agent.

# [97880] – Edge Agent restarts multiple times in small form factor devices

Issue Description: We have observed that the Edge Agent restarts multiple times before reaching a stable state with small form factor ARM devices (for example, 1 CPU and 1 GB RAM).

We recommend using Edge Security Component version 3.2.3 or higher.

# [98037] Edge Agent fails to boot when module configuration model is updated while the device is offline

Issue Description: It was not possible to send model updates for Edge modules from the Platform when the receiving Edge device was offline. Doing so caused the Edge Agent to be unable to start the broker and Edge modules after the device booted.

Workaround: A temporary workaround has been implemented where the C2D updates sent during the offline period are discarded. We will address this limitation in a future release to prevent the C2D updates from being lost.

# [100564] Batched telemetry could exceed max IoT Hub limit

Issue Description: If maxDeviceMessageSize is set to 256KB in the Edge Configuration, the batched telemetry could cross this limit if the telemetry batching condition is based on the size of the batched message.

Workaround: We have set the maxDeviceMessageSizelimit to 180KB in the Edge Agent to prevent this issue from reoccurring.

# [100706] – Deleting devices connected to the Edge module does not clear object models from MQTT database

Issue Description: When objects are deleted in V1 (proxy/agent), the device models which persisted in the database are cleared. However, the device models in V2 remain. This results in the mosquito database growing until it equals the object model in size.

# [99717] - Edge Agent CPU load is significantly higher

The current CPU usage of Edge Agent is higher in comparison to Edge Proxy. For example, a telemetry load test of 500perSecond indicated that the CPU usage of Edge Agent is two times higher than Edge Proxy. Tests on ARM-based devices show that Edge Agent's CPU usage is up to three times higher.

The performance will be improved in the upcoming releases.

Last updated: 12/19/2022, 9:04:29 AM

← Edge Proxy →

Feedback