Connection Messages

Messages used for client/server connection lifecycle, including handshake and disconnection.

---

RequestServerInfo

Description: Sent by the client to register itself with the server, and request info from the server.

Introduced In Spec Version: 0

Last Updated In Spec Version: 4 (See Deprecated Messages for older versions.)

Fields:

• Id (unsigned int): Message Id
• ClientName (string): Name of the client, for the server to use for UI if needed. Cannot be null.
• ProtocolVersionMajor (uint): Message spec major version of the client software.
• ProtocolVersionMinor (uint): Message spec minor version of the client software.

Expected Response:

• ServerInfo message on success.
• Error message on malformed message, null client name, server not able to use requested message spec version, or other error.

Flow Diagram:

Serialization Example:

[
  {
    "RequestServerInfo": {
      "Id": 1,
      "ClientName": "Test Client",
      "ProtocolVersionMajor": 4,
      "ProtocolVersionMinor": 0
    }
  }
]

---

ServerInfo

Description: Send by server to client, contains information about the server name (optional) and ping time expectations.

Introduced In Spec Version: 0

Last Updated In Spec Version: 4

Fields:

• Id (unsigned int): Message Id
• ServerName (string): Name of the server. Can be null (0-length, but field will still exist).
• MaxPingTime (uint): Maximum internal for pings from the client, in milliseconds. If a client takes to longer than this time between sending Ping messages, the server is expected to disconnect.
• ProtocolVersionMajor (uint): Message spec major version of the client software.
• ProtocolVersionMinor (uint): Message spec minor version of the client software.

Expected Response:

None. Server-To-Client message only.

Flow Diagram:

Serialization Example:

[
  {
    "ServerInfo": {
      "Id": 1,
      "ServerName": "Test Server",
      "MaxPingTime": 100,
      "ProtocolVersionMajor": 4,
      "ProtocolVersionMinor": 0
    }
  }
]

---

Disconnect

Description: Sent by the client to request a graceful disconnection from the server. Upon receiving this message, the server should stop all devices, clean up any subscriptions, and close the connection.

While WebSocket and other stateful transports handle disconnection at the transport level, this message is useful for stateless transports (such as UDP) where there is no inherent connection state. It also allows clients to explicitly signal intent to disconnect rather than relying on the ping timeout mechanism.

Introduced In Spec Version: 4

Last Updated In Spec Version: 4

Fields:

• Id (unsigned int): Message Id

Expected Response:

• Ok message with matching Id, followed by server closing the connection.
• The server may close the connection without sending Ok if the transport supports it.

Flow Diagram:

Serialization Example:

[
  {
    "Disconnect": {
      "Id": 1
    }
  }
]