Actions

The actions specification details how a device’s features can be acted on.

Many features support being changed. For example the brightness of a lightbulb can be adjusted, or the colour, or the volume of a speaker. To do so topics can be constructed by combining the root attribute of a device with the feature name to allow toggling its value.

Two topics need to be available in order to be able to complete a request-response flow.

Table of contents

1. Current state
2. Desired state
3. Changing state
4. Read-only features
5. Building the topic name

Current state

The current topic represents the current value or state of this feature.

Actors MUST NOT publish to a current topic. An ACL MAY be put in place to enforce this. The current topic is read-only for an actor. Actors SHOULD subscribe to the current topic if they wish to know the current state and/or be notified of completed state changes. They SHOULD do so before initiating a state change in order to be able to determine if the state change happened.

Providers MUST publish to the current topic whenever the state of one of their features changes. Providers MUST ignore any changes to the current topic and therefore SHOULD NOT subscribe to it. The current topic is write-only for a provider. An ACL MAY be put in place to enforce this.

Desired state

The desired topic is used to initiate a transition to a new state.

Actors MAY subscribe to the desired topic if they wish to become aware of other actors initiating state transitions. The desired topic is considered read-write for an actor though in most cases an actor SHOULD limit itself to treating the desired topic as write-only. By subscribing to the current topic it will already be aware of succesful state changes.

Providers MUST subscribe to the desired topics of all their features unless the feature is read-only. Providers MUST NOT publish to the desired topics. The desired topic is read-only for a provider and an ACL MAY be put in place to enforce this.

Changing state

When publishing to a desired topic the value MUST be encoded as a string, so "255" not 255 as a byte. Anyone consuming the value from the desired topic MUST use the type specified for this feature when converting it to a native type.

The boolean value true is encoded as "1", false as "0". Any other value is considered invalid and MUST NOT trigger a state change.

Read-only features

When a feature has the readOnly attribute set to true only the current topic will be available.

Publishing to the desired topic has no effect. It is like screaming into the void. The actor SHOULD take note of the readOnly attribute of the device and act accordingly.

An ACL MAY be put in place preventing the act of publishing to the desired topic for a read-only feature. The actor MUST be able to handle this gracefully.

Building the topic name

In order to make applying ACLs simpler, current and desired are prefixed to the root topic.

• Let the device root topic be: <owner>/lightbulb/1
• Let the feature we want to control be: on

This means that:

• current: current/<owner>/lightbulb/1/on
• desired: desired/<owner>/lightbulb/1/on

See the Devices specification for what the <owner> value can be.