# Systemstate

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](../../services/structure-of-commissioning-files/resources#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:](#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:

{% code lineNumbers="true" %}
```yaml
eventsConnection:
    type: Cybus::Connection
    properties:
        protocol: Systemstate
        connection: {}
```
{% endcode %}

#### `protocol` (required)

Must be `Systemstate`.

#### Related Links

[Connection Properties](systemstate/systemstateconnection)

## 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](../../services/structure-of-commissioning-files/resources#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](systemstate/systemstateendpoint)

## Examples

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:

{% code lineNumbers="true" %}
```yaml
{ 'state': 'enabling', 'resourceId': 'samplesystemstateservice-someEndpoint', 'timestamp': 1621256032226 }
```
{% endcode %}

When the endpoint is enabled:

{% code lineNumbers="true" %}
```yaml
{ 'state': 'enabled', 'resourceId': 'samplesystemstateservice-someEndpoint', 'timestamp': 1621256032233 }
```
{% endcode %}

When the initial subscribe operation was completed:

{% code lineNumbers="true" %}
```yaml
{ 'state': 'subscribed', 'resourceId': 'samplesystemstateservice-someConnection', 'timestamp': 1621256032230 }
```
{% endcode %}

### Sample Commissioning File

Download:

{% file src="https://950196595-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FwTih5dM9HKbgRlnp5wVj%2Fuploads%2Fgit-blob-c3876a8397426e45f8b376d2ae641d63e09f81c8%2Fsystemstate-example.yml?alt=media" %}

{% code lineNumbers="true" %}
```yaml
description: >
    Sample SystemState service commissioning file

metadata:
    name: Sample SystemState service
    provider: cybus
    homepage: https://www.cybus.io
    version: 1.0.0

resources:
    someConnection:
        type: Cybus::Connection
        properties:
            protocol: Systemstate
            connection: {}

    someEndpoint:
        type: Cybus::Endpoint
        properties:
            protocol: Systemstate
            connection: !ref someConnection
            subscribe:
                resourceId: !sub '${Cybus::ServiceId}-someConnection'

    anotherEndpoint:
        type: Cybus::Endpoint
        properties:
            protocol: Systemstate
            connection: !ref someConnection
            subscribe:
                resourceId: !sub '${Cybus::ServiceId}-someEndpoint'

    serviceEndpoint:
        type: Cybus::Endpoint
        properties:
            protocol: Systemstate
            connection: !ref someConnection
            subscribe:
                resourceId: !sub '${Cybus::ServiceId}'
```
{% endcode %}
