Commands
The Commands Component offers a mechanism for clients to request Sparkplug command (NCMD/DCMD) messages be issued to other clients, given appropriate authorisation. The Sparkplug specification indicates that only the Primary Application is responsible for transmitting commands, but the precise methodology and timing for this process are not explicitly defined. It is inferred that applications must interface with the Primary Application to request commands and as such the Commands Component provides the implementation for this specific aspect of the Primary Application's functionality.
ACS Commands Component
Overview
MQTT Interface
Command requests via the Sparkplug interface are authenticated on the basis of the Node address they are sent from. The address is looked up in the Configuration Store, and the UUID of the entry is treated as the principal to authorise. This relies utterly on the MQTT ACLs being set up appropriately (e.g. if Node A has permission to publish to the DDATA/NDATA topics of Device B then it could imitate a command request).
Specification
- The Commands component MUST listen to all DATA topics
- Any DATA packet containing a metric named
Execute_Remote_Command(at the top level) MUST be treated as a command escalation request - Any Node that wishes to publish the
Execute_Remote_Commandmetric MUST advertise it in its birth certificate - DATA packets MUST NOT use aliases
- Requests MUST be sent entirely in a single Sparkplug packet
Requests
The metric MUST be of Template type. The Commands component SHOULD NOT check the templateRef or version fields. The template MUST have the following fields:
| Name | Type | Value |
|---|---|---|
Receivers_Group_ID | String | Group ID to send a command to |
Receivers_Edge_Node_ID | String | Node ID to send a command to |
Receivers_Device_ID | String | Device ID to send a command to, or an empty string |
Tag_Path | String | Metric name to send in the command |
Tag_Value | String | Stringified metric value to send |
Command_Timestamp | DateTime | Timestamp the request was sent |
Publishing the Command_Timestamp metric should be considered the point at which the request is actually submitted; i.e. the timestamp metric should be sent last.
Results
The command is authorised on the basis of the Node address it was received from. The principal of the command requester MUST be looked up in the Configuration Store under the
Sparkplug Address application (8e32801b-f35a-4cbf-a5c3-2af64d3debd7) and the resulting UUID sent to the Authorisation component as a principal.
- If the command is authorised then a Sparkplug
CMDMUST be sent to the requested device - The ACL entry MUST include a type
- The Commands component MUST issue a
CMDto the requester updating the metricsRemote_Command_Response.
Remote_Command_Response
A Template type, with a templateRef of Command_Response_Template and the following fields:
| Name | Type | Value |
|---|---|---|
Receivers_Group_ID | String | Group ID of the requested command |
Receivers_Edge_Node_ID | String | Node ID of the requested command |
Receivers_Device_ID | String | Device ID of the requested command, or an empty string |
Tag_Path | String | Metric name of the requested command |
Response | String | Response message |
- The
Responsefield MUST beOKif a command was successfully sent. Other values forResponseMUST NOT be depended on.
Limitations
The Sparkplug interface of the Commands component has the following known limitations:
- The component will not notice or care if the requesting Node has not advertised the request or response metrics in its birth certificate
- The component will not notice or care if the receiving device is offline or if it has not advertised the requested metric
HTTP Interface
Except for the /ping endpoint, all endpoints for the Configuration Store component are located under the /v1 path to allow for forwards compatibility.
Authentication
All requests MUST supply HTTP authentication; the following mechanisms are supported:
| Mechanism | Authentication info required |
|---|---|
| Negotiate | A Kerberos GSSAPI token. |
| Basic | Username and password for a password-based Kerberos principal. |
| Bearer | A token from the /token endpoint. |
Specification
Well-Known UUIDs
These well-known UUIDs are part of the core framework and all MUST to be registered with the Configuration Store Component under the appropriate classes.
Identity
Permission Groups
This well-known UUID represents the list of permissions the Command Component will request from the Authorisation component. It is important that any permission UUIDs created to grant rights to request particular commands are added to this group.
Permissions
The Commands component supports an expandable set of permissions, where each permission represents a particular set of metrics that can be authorised. The target of the permission in every case is the device receiving the command.
All permissions for the Commands Component MUST be members of the above Commands permission group. Each permission MUST have an entry in the Configuration Store under the Commands application. This entry defines the metrics which are permitted, and consists of an array of objects with name and type fields. The name is required, and gives the metric name. The type is optional, and should be specified as one of the type names defined in the Sparkplug specification.
If the type is not specified, any type may be sent. It is up to the receiving device to decide what to do if the type is not correct. Escalation requests not specifying a type (including all received via MQTT) will default to Boolean if no type is specified in the ACL entry.
This well-known permission grants access to request a rebirth from a Sparkplug Node or Device. This needs to be created with a Command Escalation Configuration Store entry as follows:
[
{
"name": "Node Control/Rebirth",
"type": "Boolean"
},
{
"name": "Device Control/Rebirth",
"type": "Boolean"
}
]
This well-known permission grants access to request an edge agent to reload its configuration, usually because the configuration has changed. This needs to be created with a Command Escalation Configuration Store entry as follows:
[
{
"name": "Node Control/Reload Edge Agent Config",
"type": "Boolean"
}
]
Roles
The Commands role MUST be granted to the Commands Service Account (23d4e8f9-76c0-49d5-addc-00b6ac05ee58) and have the following Permissions:
| Permission | UUID |
|---|---|
| Subscribe & Read Whole Namespace | 81833dbb-1150-4078-b1db-978c646ba73e |
| Issue Global Commands | 50f1e694-7e18-4930-aa59-97cc90a6a1ec |
Applications
UUIDs created to grant Commands permissions require a Configuration Store entry of this type to define the meaning of the permission. All such permissions MUST be added to the Commands permission group defined above or the Commands component will not see the ACEs.
Entries MUST take the form of a JSON array of objects. Each entry in the array specifies a particular Sparkplug metric which may be updated by the client granted the permission. The object for each metric may have the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The full metric name |
type | string | No | The Sparkplug type of the metric |
The type is represented as one of the names used for metric types in the Sparkplug specification. If the type is omitted, any type may be sent.
The target of an ACE will be looked up in the Configuration Store under this application. This means static entries will need to be created for
Sparkplug Devices intended as Commands targets.
This application is documented more fully in the Configuration Store documentation.