Editor: TCP External Integration
Description
This guide intends to walk through Transmission Control Protocol (TCP) based external integration. The inclusion of TCP connections allows for simulations to connect and exchange data with external hardware or software products. Before starting this guide, it is recommended that users are familiar with the Integrating External Hardware or Software guide and the fundamental principles of TCP.
Warning
The functionality for TCP may depend on a valid Internet connection and a valid port that can be opened. As such, the functionality of this feature may depend on the environment in which Nominal Editor is being run. Cloud deployments, for example, may not run TCP functions.
Connection and Configuration
The initial phase of any external integration is to configure and establish a connection. To enable user flexibility, Nominal Editor supports being a TCP client and server. Therefore, one simulation instance of Nominal Editor can have multiple TCP clients active whilst also acting as the TCP server. To add a TCP client to an existing simulation, the Construct Object From Class Blueprint function needs to be called, with the class set to TCP Client. The same approach is required when creating the TCP Server.
To start the TCP Server call the Start function, from the saved TCP server reference. The port parameter needs to be configured with the desired port for the server. A Restart function also exists for the TCP server that automatically uses the port used in the start function.
Once the TCP server has started, or if connecting to an external server, the Connect function for the TCP Client needs to be called. This function requires the IP for the TCP server and port. To use TCP in a localhost configuration, simply enter localhost as the Host parameter.
Warning
If connecting to a public TCP server, users are advised to not send any sensitive or confidential data over the connection. It is recommended to start by debugging using a local host server first.
The TCP server will also need to call the Accept Client function to complete the connection handshake. This function can be used behind a check of if the client is already connected if the client is connected the Blueprint code can branch into executing data flow nodes.
Bidirectional Data Flow
Once connections have been established, data can start flowing in and out of the simulation. Sending data over TCP is achieved by using one of the various Publish functions. To assist in publishing simulation data, TCP publish functions exist for Byte, Double, Float, Integer and String data types. Each type also has an associated array variant for publishing a set of data.
To receive data over TCP, matching Receive functions have been created for each of the TCP publish function types.
Note
All Receive functions have a timeout in milliseconds to limit the main thread from locking up if no data is available. It is also advised that the function call is preceded by a check if data is available by using the Is Data Available function.
Simulations can be structured to use the TCP Blueprint pure functions to trigger certain data flow events, such as reading and decoding messages or publishing to other TCP Clients.
Disconnecting TCP
Once a simulation is completed or if a TCP client needs to disconnect early, the TCP client Disconnect function can be used. It is recommended that the disconnect function is also called on Event End Play within the level blueprint to ensure the client is disconnected. Whilst this won’t close the connection cleanly in the event of a software crash, it will create a clean disconnect the majority of the time and is still advised as a backup if the client is meant to disconnect on a specific instruction received over TCP. The same Close function is also used by the TCP Server. However, before closing the connection of the Server, it is also advised that a packet is sent to represent the intent of disconnecting to the connected TCP client, so they are aware of the disconnect first.
