Flows

Setpoint Flows

Write Setpoint Flow

The setpoint flow defines the type and order of messages for writing a single setpoint.

The usual flow without any errors proceeds as follows (square brackets mark optional steps).

  1. The user posts the parameters for the new setpoint to the API, i.e., the issuer in SWOP.
  2. The issuer validates the request, optionally creates internal state for this operation, then requests the setpoint write by sending a NEWSPT (new setpoint) message to the edge device, the receiver in SWOP.
  3. The edge device receives and validates the NEWSPT message, then writes the setpoint.
  4. If the setpoint must be acked (acknowledge flag), the edge device acknowledges success or error and additional state to the issuer in an ACKSPT message.
  5. The issuer receives the optional ACKSPT and updates its internal state of this setpoint operation accordingly.

If the receiver does not require and acknowledgement, Steps 4 and 5 are omitted.

Handling lost NewSetpoint messages

The receiver may be temporarily unreachable, or, more generally, the NEWSPT message may be lost in transit, e.g., when a non-direct transport such as MQTT is used between issuer and receiver. To handle this case, the issuer may choose to repeat his NEWSPT message after an appropriate timeout. It is, however, left to the application logic whether the write operation should be retried in this way or aborted altogether. Note that this is thus not a message or object field but must be a parameter of the API call (which is outside these protocol specifications).

Handling lost AcknowledgeSetpoint messages

The issuer may be temporarily unreachable, or, more generally, the ACKSPT message may be lost in transit, e.g., when a non-direct transport such as MQTT is used between issuer and receiver. The receiver knows its acknowledgement has been lost if it receives a duplicate NEWSPT message from the issuer. It then reacts by sending a copy of the lost ACKSPT to the issuer.

Schedule Flows

Create Schedule Flow

The Create Schedule Flow defines the type and order of messages for creating a new schedule and initializing it on the edge device.

The usual flow without any errors proceeds as follows.

  1. The user posts the parameters for the new schedule to the API, i.e., the issuer in SWOP.
  2. The issuer validates the request, creates internal state for this operation, then initiates the create schedule flow by sending a NEWSCHD (new schedule) message to the edge device, the receiver in SWOP.
  3. The edge device receives and validates the NEWSCHD message, then initiates the schedule.
  4. The edge device acknowledges success or error and additional state to the issuer in an ACKSCHD message.
  5. The issuer receives the acknowledgement and updates its internal state of this schedule operation accordingly.

Update Schedule Flow

The Update Schedule Flow defines the type and order of messages for updating an active schedule.

The usual flow without any errors proceeds as follows.

  1. The user posts the reference of the target schedule and the parameters for the update to the issuer.
  2. The issuer validates the request, updates internal state for this operation, then initiates the update schedule flow by sending a UPSCHD (update schedule) message to the receiver.
  3. The edge device receives and validates the UPSCHD message, then updates the schedule.
  4. The edge device acknowledges success or error and additional state to the issuer in an ACKSCHD message.
  5. The issuer receives the acknowledgement and may again update its internal state of this schedule operation accordingly.

Acknowledge Schedule Flow

The Acknowledge Schedule Flow defines the type and order of messages for acknowledging progress of the execution of a schedule from the receiver towards the issuer of the schedule. It is left to the SWOP implementation to decide which aspects of the execution of a schedule are acknowledged from the receiver to the issuer. We recommend to acknowledge success or failure of the execution of each setpoint defined in the schedule.

The usual flow without any errors proceeds as follows.

  1. An event occurs on the receiver side, e.g., a setpoint is written.
  2. The receiver acknowledges success or error and additional state about the ocurred event to the issuer in an ACKSCHD message.
  3. The issuer receives the acknowledgement and may again update its internal state of this schedule operation accordingly.

Delete Schedule Flow

The Delete Schedule Flow defines the type and order of messages for stopping an active schedule and deleting it on the receiver site. The schedule is marked as stopped on the issuer side but it's state should be kept for auditing purposes.

The usual flow without any errors proceeds as follows.

  1. The user posts the reference of the schedule to delete to the issuer in SWOP.
  2. The issuer validates the request, marks the schedule for deletion in the internal state, then initiates the delete schedule flow by sending a DELSCHD (delete schedule) message to the receiver.
  3. The edge device receives and validates the DELSCHD message, then stops and deletes the schedule.
  4. The edge device acknowledges success or error and additional state to the issuer in an ACKSCHD message.
  5. The issuer receives the acknowledgement and may again update its internal state of this schedule operation accordingly.