UDP2CT is an extensible application for capturing and parsing UDP packets and storing their content in CloudTurbine format.  One use of this application is to output data for participating in the CT/Unity CTrollaball Mixed-Reality test framework.  Support for parsing different data packet formats can be added to the application.  The example above shows UDP2CT capturing and parsing UDP packets from X-Plane (a flight simulator developed by Laminar Research); in this scenario, the user controlling the airplane in X-Plane can at the same time participate in a CTrollaball session!

UDP2CT currently supports parsing UDP data packets from X-Plane and CTmousetrack; details are provided below.

CTudp is a related application which focuses on parsing CSV strings from captured UDP packets.  Since there is some feature overlap between CTudp and UDP2CT, we are considering consolidating these applications.

Usage information is provided in the table below.

Command line option Description
-bps <blocks per seg> Number of blocks per segment.  Without this option (or if you specify “-bps 0”) the segment layer is not used in the CloudTurbine folder hierarchy.
-d <delta-Time> Assign the specified fixed time interval (msec) between received frames.  This option is useful when it is known that the channel data has a set sampling period.  Data will be time-stamped using increments of this period instead of wall clock arrival time.  Wall clock arrival time is used if no “-d” option is specified or if “-d 0” is used.
-f <autoFlush> Period (sec) of data flushing to the output CloudTurbine source.  Data is saved in ZIP files, and thus this flag specifies how much data is stored in each ZIP file and how frequently the ZIP files are flushed to disk.  Default value is 1.0 sec.
-h Print command line usage.
-host <host[:port]> Specify the host and port when writing CT data to FTP, HTTP or HTTPS server.
-m <multicast address> Multicast address for receiving multicast UDP messages (224.0.0.1 to 239.255.255.255).
-mc <model color> Color of the model (avatar) to be used in Unity; must be one of: Red, Blue, Green, Yellow; default = Blue.
-mt <model type> Type of model (avatar) to represent the player in Unity; must be one of: Primplane, Ball, Biplane; default = Biplane.
-o <base output dir> Location of the “CTdata” directory.  Used when writing CT data to a local folder (i.e., “-w LOCAL”).  Output source data will be saved under this base CloudTurbine data directory.  Default = “./CTdata”.
-p <UDP port> Port number to listen for packets on.  Not to be used with the “-udpserver” option.  Default = 4445.
-session <session name> Specify an optional “Session” level source folder whose name is prefixed to the standard output source names.
-source <CT source name> This field doubles as the CloudTurbine source name and the CT/Unity player ID.  If not specified, the source name and player ID defaults to the model color that has been specified.
-t <trim-Time> Only maintain the specified amount of data (seconds) in the CloudTurbine source; older data is deleted automatically.  Used when writing CT data to a local folder (i.e., “-w LOCAL”).  Specify 0 for indefinite; default = 0.0.
-u <username,password> Comma-delimited username and password, used when writing CT data via FTP or HTTPS (not used when write mode is LOCAL or HTTP).
-udpserver <IP,port,period_msec> Periodically send a short keep-alive/heartbeat message via UDP to a UDP server.  For details, see description on the CTudp app page.
-w <write mode> Specifies how to write out CT data; one of LOCAL, FTP, HTTP, HTTPS; default = LOCAL..  Data can be directly written to a local folder or to a local or remote server (ftp, http, https).  For saving data via http or https, use CTweb server.
-x, –debug Turn on CloudTurbine debugging.
-xpack Don’t pack blocks of CloudTurbine data in the Sensors output source (the default is to pack this output source). When a source is packed, each block (i.e., each ZIP file) will contain a single file per channel; all of the data for a channel over the time range of the block will be stored in this single file. Timestamps are interpolated over the data block (i.e., individual point times are not stored), thus packed data can save considerable storage space. In addition to storage space savings, CloudTurbine access to packed channel data is very efficient. Since individual point times are not saved with the data, packing is most optimal for periodically sampled data with regular “delta-T” time steps between samples.
-xs,–no_sensors_out Don’t save parsed UDP packet details to the output “Sensors” source.
-xu,–udp_debug Turn on UDP packet parsing debug output.

Command line example

Here’s an example which streams packets containing mouse position from CTmousetrack to UDP2CT:

In this example, CTmousetrack writes a UDP packet containing an x,y mouse position approximately every 100 milliseconds to “localhost:4567”.  UDP2CT captures these packets at port 4567, parses the mouse position and writes it as CloudTurbine data via HTTP to the CTweb server running at “localhost:8000”.  Data is flushed to the CTweb server every 0.1 seconds; this server will save data under the Session folder name “CTrollaball”.  A running CTrollaball game using that same Session folder will display the mouse position as a green ball.

Output CT source data

UDP2CT writes CloudTurbine data to one or two output sources: (1) GamePlay, which contains the CT player data used by CTrollaball; and (2) [optionally] Sensors, which contains “raw” parsed content from the UDP packet.  The example below shows X-Plane data which UDP2CT has captured, parsed and saved.  To save data under the “Xplane” session folder, the “-session Xplane” flag has been used.  The channels written to the Sensors source are specific to the parser class being employed; use the “-xs” command line option to prevent data being saved to this Sensors source.

Parser classes

UDP2CT has been developed as an extensible framework to which different parser classes may be added.  When a UDP packet is captured, the program determines what type of packet it is; this packet is then handed off to the appropriate parser class to parse the packet and (optionally) save data to the Sensors output source.  The parser class also contains a method to write an updated CT/Unity packet to the output GamePlay source.  Although the program can support numerous parser class implementations, each running instance of UDP2CT will typically handle one type of UDP packet (i.e., typically, only one type of parser will be utilized).

An example of a JSON-formatted GamePlay output sample for the “X-Plane” parser is shown below.  In this case, the player’s avatar is a blue biplane.

A description of the currently supported parser classes are included below.

X-Plane parser class

X-Plane includes an extensive user-selectable list of data output categories, where each category may specify one or more data channels.  Data for each selected category is combined and output as a UDP packet at a specified rate to a specified IP address and port.  To represent an X-Plane aircraft in CTrollaball, select the “Latitude, longitude, & altitude” and “Pitch, roll, & headings” data categories in X-Plane, which will provide the position and orientation of the aircraft.  When launching UDP2CT, make sure the “-p” port number matches the port number specified in X-Plane.

UDP packets from X-Plane are identified by a “DATA*” packet header.  Packet data is parsed and (as long as the “-xs” command line option is not specified) saved to the Sensors output source.  The X-Plane parser class is capable of parsing data from any of the X-Plane data output categories, however we are particularly interested in the position and orientation packets.  The figure below shows the list of CT channels (viewed in a browser using the WebScan application) produced from parsing a UDP packet containing position and orientation data.  The “data.bin” channel stores a copy of the original binary packets and “data.txt” contains a CSV-formatted string of the packet data.

After parsing the binary packet, the main UDP2CT program calls a method in the X-Plane parser class to produce the GamePlay output data used to represent a player in CTrollaball.  The airplane’s latitude and longitude are mapped to a flat surface and (along with altitude) scaled to fit within the CTrollaball game area.  The figures below show an example of an X-Plane player in CTrollaball and a selection of UDP2CT output GamePlay and Sensors channels viewed in WebScan.

CTmousetrack parser class

CTmousetrack includes support for writing out data packets via UDP.  Each packet contains a 5 byte header (“MOUSE”), a long integer containing the epoch timestamp (in milliseconds) and single-precision floating point values for x and y mouse position.  UDP2CT captures and parses these packets and (as long as the “-xs” command line option is not specified) saves the data to the Sensors output source.  The figure below shows the list of CT channels (viewed in a browser using the WebScan application) produced from parsing a CTmousetrack UDP packet.  The “data.bin” channel stores a copy of the original binary packets and “data.txt” contains a CSV-formatted string of the packet data.

After parsing the binary packet, the main UDP2CT program calls a method in the mouse parser class to produce the GamePlay output data used to represent a player in CTrollaball.  Mouse x,y position is scaled to fit within the CTrollaball game area.  The figures below show an example of a multiplayer CTrollaball game including a mouse player (blue) and UDP2CT output GamePlay and Sensors channels viewed in WebScan.