Systemstate is a special type of protocol that lets you listen for state change events on all of the Connectware resources. For any object that can be addressed by a Resource ID, the current state can be queried by read or be subscribed by subscribe.

Commissioning File Specifics

The following describes the general format of the commissioning file you will need to assemble to configure this protocol.

You can find a fully working example below: Sample Commissioning file:

Connection Settings

The service using this protocol does not create a connection to somewhere outside of the Connectware but rather an internal connection that taps into the internal state of the Connectware. So you will need to configure the connection object the following way:

2  type: Cybus::Connection
3  properties:
4    protocol: Systemstate
5    connection: {}

Required. Must be Systemstate.

Connection Properties

Should be set to {} to confirm that there are not any properties.

Endpoint settings

Each connection can have multiple endpoints. These define the operations that are supported. For the Systemstate protocol, read and subscribe are available as operations.

You define an endpoint by adding a resource of type Cybus::Endpoint and protocol Systemstate.

The only property you need to configure for read or subscribe is a Resource ID that identifies the component you want to receive updates from. This Resource ID is constructed from the Service ID and the Resource ID, separated by a hyphen character (a minus character: -).

On a subscribe endpoint, a message with the state notification will be sent on each state change of the respective resource.

With a read endpoint, on the other hand, it is possible to query the current status by sending any message to the topic with suffix req, then receiving the response on the topic with the suffix res.

Endpoint Properties

resourceId (string, required)

The resource ID of which the state transitions should be listened to. You must use the full resource identifier that consists of serviceId and resourceId, like so: ‘myService-myConnection’

Example: "someService-someResource"


The examples are using the example commissioning file below. Thus, the MQTT topics might differ in your application but the payload needs to be the same (as long as no JSONata rules are being used).

The protocol produce the following output messages:

When enabling an endpoint:

  "state": "enabling",
  "resourceId": "samplesystemstateservice-someEndpoint",
  "timestamp": 1621256032226

When the endpoint is enabled:

  "state": "enabled",
  "resourceId": "samplesystemstateservice-someEndpoint",
  "timestamp": 1621256032233

When the initial subscribe operation was completed:

  "state": "subscribed",
  "resourceId": "samplesystemstateservice-someConnection",
  "timestamp": 1621256032230

Sample Commissioning file:

Download: systemstate-example.yml

 1description: >
 2  Sample SystemState service commissioning file
 5  name: Sample SystemState service
 6  provider: cybus
 7  homepage:
 8  version: 1.0.0
11  someConnection:
12    type: Cybus::Connection
13    properties:
14      protocol: Systemstate
15      connection: {}
17  someEndpoint:
18    type: Cybus::Endpoint
19    properties:
20      protocol: Systemstate
21      connection: !ref someConnection
22      subscribe:
23        resourceId: !sub '${Cybus::ServiceId}-someConnection'
25  anotherEndpoint:
26    type: Cybus::Endpoint
27    properties:
28      protocol: Systemstate
29      connection: !ref someConnection
30      subscribe:
31        resourceId: !sub '${Cybus::ServiceId}-someEndpoint'
33  serviceEndpoint:
34    type: Cybus::Endpoint
35    properties:
36      protocol: Systemstate
37      connection: !ref someConnection
38      subscribe:
39        resourceId: !sub '${Cybus::ServiceId}'