Tcp Transport Protocol

This section details standard TCP/IP and SSL socket connections between a client application and Remote Manager. Because authentication messages flow across the socket, we strongly recommend using SSL. Use standard TCP/IP connections for debugging and troubleshooting only.

Monitor configuration options for TCP

The Monitor API provides two TCP-specific elements:

monTransportType: (Required) Sets the transport type, TCP or HTTP. For TCP, set the transport type to TCP.

monAckOption: (Optional) Specifies acknowledge options for sent messages.

  • explicit: Client must explicitly acknowledge TCP push events.
  • off: Remote Manager automatically acknowledges events when sent.

The default is off.

The following example shows how to create a TCP monitor:

<Monitor>
   <monTopic>DeviceCore,XbeeCore</monTopic>
   <monTransportType>tcp</monTransportType>
   <monFormatType>json</monFormatType>
   <monBatchSize>100</monBatchSize>
   <monCompression>none</monCompression>
   <monBatchDuration>10</monBatchDuration>
   <monAckOption>explicit</monAckOption>
   <monAutoReplayOnConnect>true</monAutoReplayOnConnect>
</Monitor>

Protocol

When a monitor is created through the Web Services API, a Monitor ID is assigned and returned to the caller. If the monitor is configured to use the TCP transport the customer application can activate the monitor by establishing a TCP socket connection back to the Remote Managerserver. SSL monitor sockets should be made to port 3201 while unsecure TCP sockets should be made to port 3200.

Once Remote Manager makes the socket connection, the customer application must send a ConnectRequest message through that connection to the Remote Manager server. The server will authenticate the request and send back a response. Once the connect request succeeds, the server will begin sending PublishMessages to the customer application as events matching the monitor configuration occur. There are two options on how the customer application can acknowledge the PublishMessages: explicit and off. The acknowledgment option is configured using the monAckOption in the Monitor web service. If not specified, the monAckOption defaults to off.

Explicit means that the customer application will acknowledge the receipt of PublishMessages using the PublishMessageReceived message. The dataBlockId in the PublishMessageReceived indicates that all events up to and including that dataBlockId were successfully received, i.e. one PublishMessageReceive message can acknowledge multiple PublishMessages. If the customer application detects a missing dataBlockId or cannot process a PublishMessage, it should disconnect the TCP socket. On the next reconnect, the replay will start with the unacknowledged push event. (Note that monAutoReplayOnConnect needs to be enabled.)

The off option means that Remote Manager will treat the push event as acknowledged when it is written to the TCP socket. Any PublishMessageReceived messages will be ignored by Remote Manager if the monitor is configured with monAckOption set to off.

As long as the monitor socket connection remains open, monitor events will flow from the server to the customer application per the requirements established in the monitor configuration. If the socket is closed for any reason, the monitor will be deactivated and monitor events will stop flowing to the customer application. When the monitor is deactivated, the monitor’s status will be marked as SUSPENDED (for monitors configured for auto replay of missed events using monAutoReplayOnConnect), otherwise INACTIVE. The customer application can reactivate the monitor socket in the same manner as the initial connection.

Conventions

In this protocol, all multi-byte numeric fields must be transmitted in big endian format. All text data must be transmitted as UTF-8 characters. See RFC 2279 as a reference for this format.

Framing

All messages between the client application and the Remote Manager server are framed as follows:

  • Header [6 Bytes]
    • Type: [2 Bytes] - indicates the type of message being exchanged
    • Length: [4 Bytes] - indicating size of the framed message payload
  • Payload [n Bytes] - the wrapped message