TCP (Client)
The TCP (Client) feed type in ArcGIS Velocity receives events from a TCP server through a TCP socket connection. The Handshake text parameter contains an optional message that the feed sends after connecting. Some servers require this message to authenticate the connection or select the data to send.
Examples
The following are example use cases for the feed:
A transportation agency uses a TCP (Client) feed in a real-time analytic to receive vehicle locations and speeds. The server sends JSON messages, and the analytic generates alerts when a vehicle exceeds 80 miles per hour (about 129 kilometers per hour).
An industrial facility receives equipment readings from a TCP server that requires a subscription message before sending data. The feed sends the configured handshake to begin receiving readings, and a real-time analytic identifies equipment operating outside normal temperature or pressure ranges.
Usage notes
Note the following when working with the feed:
Ensure the TCP server is listening before configuring the feed.
Supported data formats include XML, JSON, GeoJSON, Esri JSON, and delimited text. For delimited text, specify how fields and records are separated.
If the TCP server requires a message before sending data, enter it in Handshake text. Refer to the server's documentation or contact its administrator for the required message and format.
If the server requires
LOGIN demo-user demo-tokenfollowed by carriage return and line feed, enterLOGIN demo-user demo-token\r\nin Handshake text and set Use escape characters in handshake text to Yes. Replace the example command and credentials with those required by your TCP server.Enter escape sequences exactly as shown. For example, type
\r\nas four characters: backslash, r, backslash, n. With escape processing turned on, Velocity converts this text to carriage return and line feed. Do not substitute actual line breaks.Whenever Velocity opens a connection for Test Connection, sampling, or runtime, it sends the configured handshake once before reading event data. The feed sends the handshake again whenever it reconnects to the TCP server.
Velocity removes leading and trailing spaces and certain control characters, including tabs, carriage returns, line feeds, and NUL characters, before escape processing. This applies with either escape setting. Specifically, Velocity removes characters U+0000 through U+0020 but does not remove nonbreaking spaces.
Written escape sequences survive trimming. With escape processing turned on, Velocity converts them to the corresponding characters. With escape processing off, they remain literal backslashes and letters.
Content in the Handshake text parameter is encoded as UTF-8. Velocity does not automatically append a newline, NUL, or other delimiter.
A new feed with no handshake configured sends none. Text that becomes empty after trimming also sends no handshake.
Velocity supports the following escape sequences when Use escape characters in handshake text is set to Yes:
Entered text Character sent \0Null (NUL) \n,\r,\t,\b,\fLine feed, carriage return, tab, backspace, form feed \\Literal backslash \",\'Double quote, single quote \u0041,\101A, using Unicode or Java-style octal notationOctal escapes use up to three digits; three digits are allowed only when the first digit is 0 through 3. Escapes represent characters encoded as UTF-8, not arbitrary raw bytes. For example,
\377represents U+00FF. The\xNNhexadecimal-byte syntax is not supported.With escape processing turned on, Velocity removes the backslash from unknown escapes (
\qbecomesq) and removes an unmatched trailing backslash. Use\\for a literal backslash or disable escape processing. Malformed or incomplete unicode escapes return an error that does not include the handshake value.When editing a feed with a saved handshake, Stored handshake provides the following choices:
Keep stored handshake is chosen by default and preserves the saved value. An unchanged save does not require re-entry.
Replace handshake requires entering the replacement text.
Remove handshake clears the saved value. Do not use an empty replacement to remove it.
Changing Host, Port, or Use escape characters in handshake text, or requesting fresh sampling, can require re-entry. When prompted, choose Replace handshake and re-enter the value, or choose Remove handshake only if the TCP server no longer requires it. Unchanged saves can reuse cached connection and sampling results.
Parameters
The following table describes the parameters for the feed:
|
Parameter |
Description |
Data type |
|---|---|---|
|
Host |
The host name or IP address of the TCP server. |
String |
|
Port |
The port on which the TCP server is listening. |
Integer |
|
Handshake text (Optional) |
Initialization, authentication, or subscription text required by the server. The value is masked. The default is empty. |
String |
|
Use escape characters in handshake text |
Interpret escape sequences when set to Yes, including when omitted. Choose No to send backslashes literally. Leading and trailing trimming applies in either mode. The default is Yes. |
Boolean |
Considerations and limitations
Consider the following when using the feed:
Configuration testing, sampling, and runtime can use separate TCP connections. The client disconnects during configuration and opens a new connection when the feed starts. The TCP server must support these connections and reconnections.
If the server cannot support configuration-time sampling connections, you might need to define the schema manually.
A successful connection test confirms that Velocity can connect and send any configured handshake. It does not confirm that the server accepts the credentials or sends usable data. Use sampling to confirm that the server returns the expected data and that Velocity parses it correctly.
Velocity limits content in the Handshake text parameter to 1 MB (1,048,576 bytes), measured after trimming and again after escape processing. The limit is measured in bytes, not characters; some characters require multiple bytes.
This feed uses plain TCP, not TLS. Masking does not encrypt credentials on the network. Use an appropriately secured network or tunnel, and never include real credentials in examples, screenshots, or logs.