...

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

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.

...

...

Status Query

...

Example

Suppose we wish to run a calibration operation on a device. This operation requires no parameters.

PUT /fledge/south/operation

...

Return the status of a previously started operation.

Response Payload

The response payload is a JSON structure.

...

Name

...

Type

...

Description

...

Example

with payload

{
    "operation" : "calibrate"
}

Alternatively, if we wish to run an operation that takes parameters, say a calibration on a single axis

PUT /fledge/south/operation

with payload

{
    "operation" : "calibrate",
    "parameters" : {
                         "axis" : "x"
                   }
}

Status Query

GET /fledge/south/operation/{id}

Return the status of a previously started operation.

Response Payload

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 follows

     bool plugin_write

...

status

...

string

...

The status of the operation. This may be one of “Running”, “Complete” or “Failed”.

...

id

...

numeric

...

An id for this operation. This can be used to access the status of the operation.

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 follows

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

Where the parameters are;

• handle - the handle of the plugin instance
• name - the name of the item to be changed
• value - a string presentation of the new value to assign top the item

The return value defines if the write was successful or not. True is returned for a successful write.

Plugin Operation Entry Point

The plugin will support an operation entry point. This will execute the given operation synchronously, it is expected that this operation entry point will be called using a separate thread, therefore the plugin should implement operations in a thread safe environment.

The plugin write operation entry point is defined as follows

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

Users of the South Service Interface

The south service interface would not be exposed outside of the Fledge system, but rather consumed by other microservices within Fledge, such as the notification service in order to allow notifications to trigger updates of machines, from the new dispatcher or by a service that provided an interface to other systems such as an MES system.

We could offer access to this API via the public REST API of Fledge itself, however we should probably limit it to authenticated users only and we also would need to consider having user permissions within that API andthe associated GUI as general access to alter the behavior of the machine is a radical departure from the current Fledge/Fledge offering.

North interface access to write operations is something to be considered. It makes more sense for some north services but not all. OPCU-UA north would be an obvious candidate, as would GCP or other cloud IoT core based systems, however it should consider running that as a true north microservice rather than a task. PI systems, and data stores such as InfluxDB or HarperDB make less sense having a control route. 

Control Dispatcher Service

Rather than every end point knowing about every other end point and dispatching control updates and operations between service endpoints a new microservice, the control dispatcher will be introduced. This service will be responsible for dispatching control messages between the services, it will use rules to perform this function and these rules will be extensible.

Dispatching Rules

The operations and control updates will have a number of attributes that will be used by the dispatcher to route the control messages to the correct end points. 

The simplest of these rules will be name based, the control message names the service to which it is destined. 

A rule will also allow an operation or write event to be dispatched to an asset source. Asset tracker data will be used to determine the service that created the named asset and the control operation will be forwarded to that service by the dispatcher.

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. 

Control Callbacks

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.

Operation Callback

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.

Control Destination

The control destination is an enumerated type that is used to encode the dispatcher rules that will determine the destination of this operation. A number of arguments may follow the destination in order to further qualify the destination. 

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

...

string value)

Where the parameters are;

• handle - the handle of the plugin instance
• name - the name of the item to be changed
• value - a string presentation of the new value to assign top the item

The return value defines if the write was successful or not. True is returned for a successful write.

Plugin Operation Entry Point

The plugin will support an operation entry point. This will execute the given operation synchronously, it is expected that this operation entry point will be called using a separate thread, therefore the plugin should implement operations in a thread safe environment.

The plugin write operation entry point is defined as follows

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

Users of the South Service Interface

The south service interface would not be exposed outside of the Fledge system, but rather consumed by other microservices within Fledge, such as the notification service in order to allow notifications to trigger updates of machines, from the new dispatcher or by a service that provided an interface to other systems such as an MES system.

We could offer access to this API via the public REST API of Fledge itself, however we should probably limit it to authenticated users only and we also would need to consider having user permissions within that API andthe associated GUI as general access to alter the behavior of the machine is a radical departure from the current Fledge/Fledge offering.

North interface access to write operations is something to be considered. It makes more sense for some north services but not all. OPCU-UA north would be an obvious candidate, as would GCP or other cloud IoT core based systems, however it should consider running that as a true north microservice rather than a task. PI systems, and data stores such as InfluxDB or HarperDB make less sense having a control route. 

Control Dispatcher Service

Rather than every end point knowing about every other end point and dispatching control updates and operations between service endpoints a new microservice, the control dispatcher will be introduced. This service will be responsible for dispatching control messages between the services, it will use rules to perform this function and these rules will be extensible.

Dispatching Rules

The operations and control updates will have a number of attributes that will be used by the dispatcher to route the control messages to the correct end points. 

The simplest of these rules will be name based, the control message names the service to which it is destined. 

A rule will also allow an operation or write event to be dispatched to an asset source. Asset tracker data will be used to determine the service that created the named asset and the control operation will be forwarded to that service by the dispatcher.

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. 

Control Callbacks

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, ControlDestination 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.

Operation Callback

The operation callback is a function pointer with the signature

    int operation(char *operation, int paramCount, char *names[], 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 names is an array of the parameter names and parameters is an array of string values that are the parameters themselves. The length of the names and parameters arrays should both be paramCount. The destination argument controls where the request will be routed and uses additional argument to qualify that routing.

Control Destination

The control destination is an enumerated type that is used to encode the dispatcher rules that will determine the destination of this operation. A number of arguments may follow the destination in order to further qualify the destination. 

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”);

Callback Initialisation

A north plugin that implements control flow must signal to the north service that is loading the plugin that it implements the control flow and provide an entry point that will be used by the north service to pass the callback pointers to the north plugin. Note, north plugins that are run by a north task rather than as a service will not be able to use the control flow.

A north task signals that it supports the control flow by adding the flag SP_CONTROL to the flags field of the information structure that the plugin_info call returns.

When the north service detects that the plugin supports the control flow it will make a call to pass the callback function pointers to the plugin. This call is made after the call to plugin_init has completed.

    void plugin_register(PLUGIN_HANDLE handle, bool ( *write)(char *name, char value, ControlDestination destination, ...), 
                                     int (* operation)(char *operation, int paramCount, char *parameters[], ControlDestination destination, ...))

The plugin should retain these two function pointers for use when it wishes to invoke control operations.

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.

...