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/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