Application to Industrial Edge Device communication

This document provides a step-by-step guide for an application developer on how to use the IED API (auth, edge API). Using an application installed on the IED, the application developer can access the IED API (auth, edge).

Scope

The app developer can securely access all of the IED APIs with an SSL certificate.

Endpoint

The device API can be called through the proxy-redirect Docker network that is available on all Industrial Edge Devices. To use the proxy redirect network it must be added to the docker-compose.yaml as shown below:

version: '2.4'

service:
  networks:
    - edge-redirect
  ...

networks:
  edge-redirect:
    name: proxy-redirect
    external: true
  ...

The Industrial Edge Device APIs can be then reached through its DNS name which will be resolved by the Docker resolver: edge-iot-core.proxy-redirect

Certificate and IP file

Each application has a mount point that contains a JSON file which is populated with the self-signed certificate and IP address of the Industrial Edge Device to make the REST call. You can find it at "/var/run/devicemodel/edgedevice/certsips.json" and it has the following format:

{
  "auth-api-path": "<insert api path>",
  "cert-chain": "<insert cert-chain>",
  "edge-certificates": {
    "certificates-chain": "<insert certificate-chain>",
    "service-name": "edge-iot-core.proxy-redirect"
  },
  "edge-ips": "<insert ip>",
  "secure-storage-api-path": "<insert path>"
}

NOTICE

If the host changes the IP address or updates the certificate then the updated IP Address/ certificate would be reflected in the certsip.json. The correct error handling is required in this case and must be fetched from the certsip.json file again.

Example workflow

1. Configure your application to use the proxy-redirect network.
2. Read service-name or Industrial Edge Device IP(s) and certificate from certsips.json that is automatically mounted into your application.
3. Call IED API that is required for your purpose.

---

Backward Compatibility

App Version	IED Version	Comment
1(New)	1	Can Call with new route path
0(Old)	1	Can Not Call with new route path
0	0	Can Not Call with new route path
1	0	Can Not Call with new route path

---

Network requirements for UI and databus containers

The Industrial Edge Device uses an nginx reverse proxy to route requests to application containers. This routing relies on the proxy-redirect Docker network.

If the proxy-redirect network is defined in your docker-compose.yml, ensure that all of the following containers are attached to it:

• Containers that communicate with the databus to publish or subscribe to data.
• Containers that expose a UI and use Industrial Edge Device redirection via the device nginx.

Note: If proxy-redirect is not explicitly defined as a network in your docker-compose.yml, the Edge IoT Core automatically adds a default network called proxynet to your application containers. This network is an alias of proxy-redirect and provides the same connectivity. However, it is recommended to explicitly define and use the proxy-redirect network in your docker-compose.yml for clarity and full control over which containers are attached to it.

Example Usage

In the following example, an application consists of three containers:

• data-processor — performs internal computation and does not need to communicate with the Industrial Edge Device.
• databus-comm-app — publishes and subscribes to data on the databus.
• my-web-ui — exposes a UI that is accessible through the device nginx reverse proxy.

Since databus-comm-app communicates with the databus and my-web-ui uses device redirection, both must be attached to the proxy-redirect network. The data-processor container does not require it.

services:
  data-processor:
    image: my-app/data-processor:latest
    # No proxy-redirect network needed — runs in isolation

  databus-comm-app:
    image: my-app/databus-comm-app:latest
    networks:
      - proxy-redirect

  my-web-ui:
    image: my-app/my-web-ui:latest
    networks:
      - proxy-redirect

networks:
  proxy-redirect:
    name: proxy-redirect
    external: true