How to use StringTheory
Software Introduction
Many ETC products use UDP or RS-232 to communicate to other ETC products, as well as many non-ETC products. Several common examples are using an AMX or Crestron processor to communicate to Paradigm, UDP strings between Paradigm and Mosaic, or UDP/TCP communication from Paradigm to an Eos family console. When the communication breaks down it can be difficult to determine where the failure is. ETC has developed a testing tool, called StringTheory, which can test sending and receiving Ethernet UDP, Ethernet TCP, RS232 Serial, and ETC IO Gateway (only in v2.5.1.0 and lower) communication.
StringTheory can be downloaded by anyone through our ETC Labs Github, but is not officially released ETC software, and is therefore provided as-is without warranty or support from ETC Technical Support. That said ETC Technical Support will often use StringTheory as a troubleshooting tool in ETC systems, so you may be asked to download and install it as part of a conversation with them.
Below you will find instructions for using the program, complete with screenshots.
Software Layout
Along the top of the program is the toolbar, which allow you to clear the history, save the history to a .txt file, enable/disable info, sent, or received messages, and information about the program.
The section outlined in RED is where you configure the connection type.
The section outlined in GREEN is where you format strings to be sent from your computer to the receiving device.
The section outlined in BLUE is a running log of info and sent/received strings, any of which can be toggled on or off at the toolbar. Additionally you can clear this log, or save the log to a .txt file using buttons on the toolbar.
Configuring Connections
Ethernet UDP
Ethernet UDP is used to send a string directly to the IPv4 address and port of a single networked device. Your computer must be connected to a common network with another device to be able to send/receive UDP strings.
To send/receive UDP strings you must choose from a list of NICs on your computer (but you must configure the NIC via the Settings in your OS), and the port number which the other device is sending to. In order to send UDP strings StringTheory provides a blank field which you can type in a Destination IP Address, and port number which the other device is listening to. StringTheory will provide a green check mark to the right of the IP address if it's a valid IP detected on the network, or a red X if the IP cannot be reached. Keep in mind the Receive and Send To port can be the same integer.
Ethernet TCP
Ethernet TCP is also used to send a string directly to the IPv4 address and port of a networked device, however TCP is guaranteed delivery whereas UDP is not, and the receiving device must support TCP.
To send/receive TCP strings, simply choose the appropriate local NIC IP, the local port number it's listening on, and the termination character it will split the strings at. Remote IP is the device to which StringTheory will send strings to. Define the remote port, and click "Connect" to begin the session. NOTE: If you define a remote IP address the Local Port option will grey out and change to the ephemeral port (59120 in this example) selected by the network stack at connection time.
If you just want to listen to a specific port (4703 in this example) you can enter the integer into the Local Port field and leave the Remote IP field blank. Once the remote host connects to your PC the Remote IP will show the device that connected and its ephemeral port (34335 in this example).
RS232 Serial
RS232 is used to send a string directly to a single device over a hardline RS232 serial cable. Your computer will need a serial port, or a USB to RS232 adapter to send/receive RS232 serial signals. Depending on your adapter or RS232 cable, a null modem adapter may be required as well.
First you must select the COM Port which StringTheory will communicate through, and next properly set the Baud Rate, Data Bits, Parity, and Stop Bits. These settings will generally be dictated by the other device and must match otherwise you will see no data, or garbled data. Lastly you must choose an end of line character in the "Split At" field which is used when receiving strings. "Char 13" is a carriage return, and "Char 10" is a line feed. If you would like more information on how to represent a data byte in different formats visit www.asciitable.com.
ETC IO Gateway
The ETC IO Gateway option is only available in StringTheory v2.5.1.0 or lower, and allows you to send or receive RS232 strings through the Gateway. Your computer must be connected to a common network with an IO Gateway to be able to send/receive strings.
First you must "Select a valid NIC to start ACN" in the "ACN NIC to Use:" field, after which this field will grey out, ACN will start, and StringTheory will populate a list of IO Gateways to choose from. It automatically shows you the Gateway's IP address, software version, group ID, Baud Rate/Data Bits/Parity/Stop Bits, if send and receive are enabled, and the Flow Control setting. In order to change these settings you must close StringTheory and use Net3 Concert or GCE (Gateway Configuration Editor).
Formatting Strings
There are five string formats - all of which are usable on each connection type - however the format that should be used is incumbent upon the setup of the receiving device. After typing a string, StringTheory will additionally convert the string for you as you switch between formats. The program defaults to "Basic Text", but all options are outlined below. Once the string is properly typed, click "Send" or press "Enter" on your keyboard, and as long as all message types are enabled you'll see log steps in the bottom of StringTheory when the message is sent, and any responses received back.
Basic Text
This option allows you to enter ASCII text, and choose the terminating character without having to type it in the string. StringTheory will automatically enter the character you define. 'Char 13' is a carriage return (CR) and 'Char 10' is a line feed (LF). It is not possible using the basic text option to use CR+LF, but can be done using other options below.
Basic text example:
ETC is great! would send 'ETC is great!' to the receiving device.
Escaped Text
This option is similar to Basic Text, in that you type the string in ASCII, but you must define the terminating character using an escape character, defined by a '\' here. '\r' is a carriage return and '\n' is a line feed. Both can be used (\r\n) to send 'CR+LF' termination.
Escaped text example:
ETC is great!\n would send 'ETC is great!' to the receiving device using a line feed.
Escaped Hex
In Escaped Hex the terminating character is defined in hexadecimal preceded by an escape character, and other character types like a space, !, ?, etc. also are defined by an escaped hex character. The escape character can be defined by the user, but is defaulted to '$'. '$0d' is a carriage return and '$0a' is a line feed. Both can be used to send 'CR+LF' termination.
Escaped hex example:
ETC$20is$20great$21$0d$0a would send 'ETC is great!' to the receiving device using a carriage return+line feed.
Congo Trigger Format
Congo trigger format is used by Congo/Cobalt consoles to trigger Action Macros, and can have ASCII and hexadecimal characters mixed within a string. They also require a space between each data byte, and an actual space uses the hex character '20'. Carriage return is defined as '0d' and line feed is defined as '0a'.
Congo trigger format example:
E T C 20 i s 20 g r e a t ! 0a would send 'ETC is great!' to the receiving device using a carriage return.
Raw Hexidecimal
This format type requires each character/data byte to be formatted as raw hexadecimal. CR+LF would be defined by using '0d 0a' at the end of your string.
Raw hexadecimal example:
45 54 43 20 69 73 20 67 72 65 61 74 21 0d would send 'ETC is great!' to the receiving device using a carriage return.
