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

ConnectRequest Message

To initiate a new monitor connection, send a ConnectRequest message from the client application to Remote Manager. This is the first message sent upon connect and will authenticate and activate the monitor.

Header [6 Bytes] Type=0x0001

Payload:

ProtocolVersion: [2 Bytes] - indicates what version of push protocol is being used. The current version is 0x0001.
UserNameLen [2 Bytes] - length of UserName payload
UserName: [UTF-8 encoded byte array] - the username to authenticate connection
PasswordLen [2 Bytes] - length of Password payload
Password: [UTF-8 encoded byte array] - the password to authenticate connection
MonitorId: [4 Bytes] - the ID of the monitor for this connect

Example

Legend:

Type: 0x0001 Size: 0x00000013 ProtocolVersion: 0x0001 UsernameSize: 0x0005 Username: 0x7065707369 (pepsi) PasswordSize: 0x0004 Password: 0x636f6c61 (cola) MessageId: 0x00000104

ConnectResponse Message

The response to ConnectRequest, sent from Remote Manager to the client application, is a ConnectResponse message. This indicates to the client application the status of the web services request, as well as the protocol version that Remote Manager is speaking.

Header [6 Bytes] Type=0x0002

Payload:

Status Code: [2 Bytes]
ProtocolVersion: [2 Bytes] - indicates what version of push protocol is being used

Example:

Legend:

Type: 0x0002 Size: 0x00000004 Status: 0x0001 ProtocolVersion: 0x0001

PublishMessage Message

As monitored events occur, Remote Manager will send PublishMessage messages to the client application.

Header [6 Bytes] Type=0x0003 Payload:

DataBlockId: [2 Bytes] - rotating id that uniquely identifies the data block
Count: [2 Bytes] - number of messages in this batch
Compression: [1 Byte] - indicates what payload compression algorithm is being used (0x00=none, 0x01=zlib)
Format: [1 Byte] - indicates data format of payload (0x00=xml, 0x01=json)
PayloadSize: [4 Bytes] - indicates how many bytes of payload data follow
PayloadData: [n Bytes] - the actual Monitor event data (may be compressed & Base64 encoded)

Example:

Legend:

Type: 0x0003 Size: 0x00000215 DataBlockId: 0x01A7 Count: 0x0002 Compression: 0x00 Format: 0x00 PayloadSize: 0x00000205 PayloadData: 0x3C446F63756D656E74 … 6E743E

<Document>
    <Msg topic="3/DeviceCore/882/7" operation="update" timestamp="2010-12-03T13:34:00.001Z">
        <DeviceCore>...</DeviceCore>
    </Msg>
    <Msg topic="3/XbeeCore/00:13:A2:00:40:01:60:45/1/0/1794/256"operation="update" timestamp="2010-12-03T13:34:00.001Z">
        <XbeeCore>...</XbeeCore>
    </Msg>
</Document>

Publishmessagereceived Message

In response to a PublishMessage message, the client application will send a PublishMessageReceived to acknowledge the message was received and what its processing status is.

Header [6 Bytes] Type=0x0004 Payload:

DataBlockId: [2 Bytes] - corresponds to incoming DataBlockId
Status: [2 Bytes] 200 - indicates customer application successfully received and processed the data

Example:

Type: 0x0004 Size: 0x00000004 Status: 0x00C8