Graceful Shutdown API

This document provides stepwise guidance to an app developer, demonstrating how to use shutdown API by an application. With the help of an application that is installed on the IED, the app developer can shut down the IED by accessing the API. Triggering the shutdown operation is currently only possible through UI. But in some cases the shutdown can be triggered by host system (like in the power loss case with UPS usage). These system services should be able to trigger shutdown operation as well.

Scope

The app developer can develop an application to shut down the IED by accessing the API.

Configurations

As the REST endpoint is running HTTPS, the endpoint and necessary trusted certificates are provided to the App via a mount point. For calling the shutdown APIs necessary basic token are provided to the App via a mount point.

Certificate and IP mount point

The mounting point contains the JSON File which is populated with the self-signed certificate and IP address of the host system to make the REST call. You find it at "/var/run/edgedevice/certsips.json".

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 proper error handling is needed in this case and needs to fetch again from the certsip.json file.

App secret mount point

The mounting point contains a JSON file which is populated with encrypted basic token. You find it at "/etc/edgeconfig/.apptoken".

Example workflow

1. Read IP(s) and certificate from certsips.json.
2. Read token from .apptoken.
3. Generate authtoken for accessing the API via auth-api-path + /token/permit with the apptoken as part of the body.
4. Call graceful shutdown API to force a device shutdown.