TCP

The TCP plugin allows communication between a generic TCP client application on a robot and the DroneDeploy Robotics Portal.

The TCP plugin is bidirectional; the TCP plugin operates as a TCP server: it will accept data from connected clients, and forward that data to the DroneDeploy Robotics Portal as upstream (telemetry) messages, and downstream (control) messages from the DroneDeploy Robotics Portal will be delivered to connected TCP clients.

Configuration

To use the TCP plugin, your agent will need a section in its agent-settings.json file which enables the tcp component, as shown below. For more information on how to configure the agent plugins, see Agent Configuration.

...
"components": [
...
  {
    "enabled": true,
    "id": "tcp",
    "settings": {
      "name": "tcp",
      "address": "127.0.0.1:9000",
      "definitionRequired": false,
      "logLevel": 4,
      "rawPktBytes": 20000,
      "rawPktTxTimeout": 2000,
      "rawPktRxTimeout": 100,
      "type": "RAW"
    }
  },
...
]

The TCP plugin understands the following configuration parameters:

Name	Description	Default	Unit
enabled	Whether to enable the TCP plugin or not.	false
name	How this instance of the TCP plugin should be named.	"tcp"
logLevel	The logging verbosity: 1 - very quiet, 6 - very talkative.	4
address	Required. The ip:port which the TCP plugin server should listen on.
type	The type of TCP data the plugin expects to receive: options are 'RAW', 'JSON' or 'ENVELOPED'.	"RAW"
definitionRequired	When operating in JSON mode, whether the plugin should expect that the first JSON object received should be the schema which subsequent received objects will match.	false
rawPktBytes	When operating in RAW mode, the maximum number of bytes which should be included in each upstream (telemetry) message.	16	B
rawPktRxTimeout	When operating in RAW mode, if this value is non-zero, then after receiving any number of bytes, the plugin will wait this long, then send an upstream (telemetry) message even if the number of bytes received yet is not equal to rawPktBytes.	0	ms
rawPktTxTimeout	When operating in RAW mode, if this value is non-zero, then the plugin will always send an upstream (telemetry) message this often, even if no TCP data has been received (in which case, it sends an empty message).	0	ms

Data Model

Raw Mode

When operating in Raw mode, the plugin treats the TCP data that it receives as a stream of unstructured bytes. The stream of bytes are packed together into discrete upstream (telemetry) messages and sent to the DroneDeploy Robotics Portal without any additional processing applied.

Received raw TCP data is posted to the topic: /tcp/raw

While TCP data can be treated as a continuous stream, the plugin provides some configuration options which control how the raw bytes are packed into discrete messages, which controls how the data appears when viewed in the Live Data Viewer on the DroneDeploy Robotics Portal:

If your TCP stream consists of packets with a fixed length, then setting the rawPktBytes configuration value to match this length will result in individual upstream messages which each contain one packet.

Warning

There is some processing overhead associated with sending each upstream message; if your TCP data stream consists of a high number of short messages, set the packetization configuration settings so the TCP data is aggregated into a smaller number of larger messages, otherwise the TCP component may be unable to packetize the incoming data rapidly enough, resulting in accumulation in the TCP receive buffer.

If your TCP stream consists of variable length packets of data, separated by some idle period, then setting rawPktRxTimeout to a value which will timeout during the idle period will result in individual upstream messages which each contain one packet.

If your TCP stream will consist of a variable amount of data, but you wish your server or UI side software to receive data to process in a periodic manner, then setting rawPktTxTimeout to a suitable value will ensure that messages are always sent to the platform on this schedule, regardless of how much TCP data is pending.

JSON Mode

When operating in JSON mode, the plugin expects that the TCP data it receives consists of JSON objects. The TCP data stream will be decomposed into discrete JSON objects, each of which is sent to the DroneDeploy Robotics Portal as a separate upstream (telemetry) message - the rate at which messages are posted to the Platform depends entirely on the rate at which valid JSON objects are received by the plugin.

Received JSON objects are posted to the topic: /tcp/json

Enveloped Mode

When operating in enveloped mode, the plugin expects that the TCP data it receives consists of JSON objects with the following specific format:

{
   "source": "/robot1/sensor",
   "payload": {
        "sensor": 123
   }	
}

In enveloped mode, the plugin will unpack each JSON envelope message, and post the payload contents to the data URI specified by source. For instance, the above example will display in the Live Data Viewer under the TCP component as:

/tcp/robot1/sensor

This allows you to send different data types to the TCP plugin and have them show up as separate topics in the DroneDeploy Robotics Portal.

Note

If the plugin is unable to decode the incoming TCP data according to the expected envelope format, it will instead fall back to posting that data to the default JSON data URI.