CommandsAndResponses.md

Commands and Responses Overview

As described previously, STTP is implemented using a command channel that is used to reliably negotiate session specific required communication, state and protocol parameters. Command channel functionality includes establishing communications with other STTP implementations, exchanging metadata on available data points and the ability to request data points for subscription. Any messages, such as commands, transmitted with the expectation of receiving a response will only be sent over the command channel, as such this functionality requires a reliable transmission protocol, e.g., TCP.

This section describes the available commands and responses that define the functionality of STTP.

Message Formats

Commands and responses are defined as simple binary message structure that also may include a payload. The details for the payload of the message will depend on the specific command or response code.

Message Payloads

Payloads in STTP are defined as a byte arrays prefixed by an unsigned 16-bit integer representing the array length. Implementations of STTP should make target payload sizes configurable, but all payloads delivered by STTP must have a fixed maximum upper length of 2^16, i.e., 65,535, less 3 bytes for the packet overhead.

  uint8[] payload;

It is permitted to send an empty payload if the command code does not require a payload.

Command Structure

Commands are used to manage primary STTP functionality. The following defines the binary format of a Command, see Figure 5 for an example:

struct {
  uint8 commandCode;
  uint16 length;
  uint8[] payload;
}
Command;

• The commandCode field defines the command code value for the command message, see defined command codes.
• The length field defines the length of the entire packet in bytes.
• The payload field is a byte array representing the serialized payload associated with the commandCode.

Example Command Structure for a DataPointPacket

^{Figure 5}

Response Structure

Some form of response exists for every command. Responses take the same format as commands but are distinguished with a different command code. Sometimes, successful responses are implied and not expressly stated. However, in these cases, it's still permitted to send a successful response in addition to the command. Responses for most commands will be either Succeeded or Failed. The following structure defines the binary format of a Response:

struct {
  uint8 responseCode;
  uint16 length;
  uint8[] payload;
}
Response;

• The responseCode field defines the response code value for the response message, see defined response codes.
• The length field defines the length of the entire packet in bytes.
• The payload field is a byte array representing the serialized payload associated with the responseCode.