...

Write a set of values to the device connected to this south service.

PUT /fledge/south/setpoint

Request Payload

Example

Assume we have a device attached to the south service that rotates at a given speed for a given time as part of the process it executes. We change that speed and duration based on the current conditions. To do this we execute the following REST API call against the south service interface.

PUT /fledge/south

With the PayLoad

{
        "values" : [
                        "speed"    : "12500",
                        "duration" : "90"
                ]
}

This would set the speed to 12500 RPM and the duration at that speed to 90 seconds. The plugin would receive these values and convert them to whatever commands are required to be sent to the machine itself.

Operation API

PUT /fledge/south/operation

Request Payload

Response Payload

The response payload is a JSON structure.

Status Query

GET /fledge/south/operation/{id}

Return the status of a previously started operation.

...

The response payload is a JSON structure.

Plugin Write Entry Point

South plugins that support the ability to write data to a sensor or device will encode this by setting the flag PLUGIN_WRITABLE in the plugin_info return structure. If this flag is set then the plugin must also support the plugin_write entry point.

The plugin write entry point is defined as followsbool

     bool plugin_write(PLUGIN_HANDLE *handle, string name, string value)

Where the parameters are;

...

The plugin write operation entry point is defined as followsBool

    bool plugin_operation(PLUGIN_HANDLE *handle, string operation, int parameterCount, PLUGIN_PARAMETER parameters[])

Users of the South Service Interface

...

However more complex rules will be added, these will include the ability to dispatch a single control request to multiple destinations with operational rewriting of requests as they are dispatched. As with other aspects of Fledge the dispatcher rules will be added via plugins, allowing the user/developer to tune the the rules that will be used to determine how to route control messages both for set point calls and for operations. These dispatcher plugins will be available to be written in both C/C++ and Python.

The dispatcher will be able to route a single request to multiple destinations.

North Plugin Changes

Another source of control is the north plugin. In this case an external system with which Fledge is communicating requires an operation or a value to be written to a device via Fledge. The north plugin interface will be updated to allow north plugins to direct control messages to the dispatcher service and for the north plugin to receive notification of the status of those operations. 

...

A north plugin will dispatch control requests via a callback into the north service. The north plugin will request, via the flags in the plugin information structure that it requires these callbacks to be registered with the plugin. The callbacks take the form of C function pointers in a C plugin and a Python call for a Python based plugin.

Write Callback

The write callback is a function pointer with the signature

    bool write(char *name, char *value, ControlDestiantion destination, ...)

Where name is the name of the value to write, and value is the string representation of the value to write. The destination argument controls where the request will be routed and uses additional argument to qualify that routing.

...

The operation callback is a function pointer with the signature

    int operation(char *operation, int paramCount, char *parameters[], ControlDestination destination, ...)

Where name is the operation is the name of the operation to be executed, and paramCount is the number of parameters to be passed to that operation and parameters is an array string values that are the parameters themselves. The destination argument controls where the request will be routed and uses additional argument to qualify that routing.

...

A write operation to a named service, say the service called “Trans1” would look as follows

    write(“test”, “value”, DestServiceName, “Trans1”);

If the destination was a asset source, say the service that created the asset “Transformer1Temperature”, then the call would be

    write(“test”, “value”, DestAssetSource, “Transformer1Temperature”);

Security

The advent of control increases the need for strict security mechanisms within the system. However end to end security can not be achieved by simply adopting the security mechanism of the control message producer with that of the consumer, they may have different security models and a single producer may be communicating with multiple consumers, each with a different security model.

...

A set of access control lists tagged with an operation name that can be used to further restrict access to particular URL’s of the service interface. An example might be that the /fledge/south/operation URL is restricted to just the service called “IEC-104 North”.

...

The JSON ACL structure will be as follows

{
        "service" : [
                        {
                                "name" : "IEC-104 North"
                        },
                        {
                                "type" : "Notification"
                        }
                ],
        "URL" : [
                        {
                                "URL" : "/fledge/south/

...

operation",
                                "ACL" : [
                                                {
                                                        "type" : "Notification"
                                                }
                                        ]
                        }
                ]
}