The Network Command String (NCS) block allows bidirectional communication between a Tesira server-class device and other network-based devices. This communication can be configured as needed for the application and is commonly used for control based interactions with non-Tesira devices.
The capabilities of this block are enhanced in the following ways in Tesira version 3.15 and later:
- Expected response strings can trigger logic events within the Tesira file and/or generate specific response strings.
- Detailed connection status plus real-time view and logging of string exchanges are provided for troubleshooting.
Once the Network Command String block is added to a Tesira layout, the Properties window allows entry of the destination's network parameters:
Refer to the documentation for the target device for the correct settings to apply in this section:
- The Protocol type TCP/UDP should be pre-defined or configurable depending on the device you intend to communicate with.
- The Server Address is the target IP or hostname of the 3rd party network device the block will be communicating with. Note that DNS must be supported on the network for the hostname resolution to occur.
- The Remote Port is the target port at the defined Server Address target IP that will be used.
- In this screen capture, port 2202 has been pre-defined by the device manufacturer for communications.
- Note that port 23 is the default as it is the default port for Telnet communications. References are available that define common ports and protocols for TCP/UDP.
- Auto Connect, when enabled, will attempt connection or reconnection every 3 seconds until successful.
- Connection Sequence (formerly Expected List) is a definable list that will be used to open communications with the target device once the network connection is active. The user defines the strings Expected from the target device followed by the appropriate Response strings. This Connection Sequence must step through in sequential order with exact string matches or it will fail.
Now that the Network Command String (NCS) block has been added to the file and configured with the proper network connection information, the block can be opened for functional configuration. Double-click on the block to open it.
- The Command String Edit button allows the user to define command strings to be sent from the Tesira device.
- The buttons in the Command Id column allow the strings to be sent manually.
- The Input numbers align with the logic input nodes on the top of the NCS block. When a logic high is received on a logic input, the associated Command String will be sent.
- The Expected Response section allows the user to define character strings that, when matched, will trigger an associated Command Id String and/or an associated Logic Output. More in-depth details will be covered below.
- The Connection Log displays the character strings sent and received by Tesira. These are only visible while connected to a live system.
Response string pattern matching
Response String Patterns can be comprised of ordinary characters, hexadecimal escapes (a tilde character followed by two hexadecimal digits), question mark and asterisk. The following table describes the valid Response String Patterns.
|ASCII||These are case sensitive and most commonly alphanumeric and human-readable characters.||Power_On|
|Escape Character||The tilde (~) is a character used to indicate that the following two characters will be hexadecimal digits. This is generally used for unprintable characters like carriage returns, line feeds, or for devices that use hex codes instead of human-readable ASCII characters.||~0A|
|?||A question mark (?) is a wildcard that will match any single printable character (including space but excluding carriage return, line feed or newline) in the input.||Power_On?|
|*||An asterisk (*) in the pattern matches zero or more printable characters (including space) in the input. The asterisk matches as few characters as are necessary to find a match in the input.||Pow*On|
When the NCS block receives input from the remote device, it attempts to match the received data (including any previously received but unmatched data already in the input buffer) against each of the Response Patterns, in order (i.e. first-match, not longest-match.)
- When the first part of the input matches a pattern, the block removes the matching bytes from the input, then sends the selected Command String (if any) and pulses the selected Logic Output (if any). Any unmatched bytes remain in the receive buffer for future matches.
- When the entire input matches the initial portion of any pattern, but not the complete pattern, the block waits indefinitely for additional input.
- If the input cannot match any pattern, the block discards the first byte of the input and tries again to match the remaining input.
Note that both the order and content of the patterns are important. The following guidelines are recommended:
- Response Patterns should start with a definite character or at least a definite count of characters. Response Patterns starting with “*” or “?*” can cause the block to quit responding while it waits for additional input.
- Response patterns should explicitly include trailing New Line (~0A), Carriage Return (~0D) or CR-LF (~0D~0A).
- Response patterns cannot end with an asterisk (*).
Application & Sandbox
The following example details the Network Command String block controlling a common microphone array:
- The block has been configured with the desired logic inputs and outputs:
- The microphone array utilizes TCP protocol on port 2202 at the IP 172.30.3.3. The Properties of the Network Command String block have been configured accordingly:
- The Auto Connect value is set to True so the Network Command String (NCS) block will attempt connection every 3 seconds. If for some reason the network switch loses power, the NCS block will also persistently attempt re-connection every 3 seconds.
- Connection Sequence is not needed.
- The microphone API documentation provides all the necessary commands and response strings. This information is entered appropriately in the NCS configuration:
- The Tesira configuration file is compiled and loaded. The auto-connect establishes communications with the microphone array. The following video shows the communication strings being sent and received.
- The Tesira Processing Library allows importing and exporting user-defined and custom blocks. The following Processing Library file includes some of the blocks we developed during feature testing and documentation (drafting this article). It is intended to be a sandbox or reference of blocks to help get Tesira users started with basic NCS control.
Helpful troubleshooting tools include:
- The Connection Log within the NCS block.
- When connected to a live system, this Connection Log window will display strings that are sent and received in real-time.
- API documentation for the device that you are attempting to control. If necessary, contact the manufacturer of said product for further device-specific questions.
- When the NCS block is configured for TCP, the Tesira NCS block acts as a client in a client-server relationship. This means that the client initiates communication with the server device and requests services or resources. If the Tesira NCS block is attempting to communicate with another client device, communications will not be successful. This will be visible in a Wireshark capture.
- When the NCS block is configured for UDP, the remote port is an important detail. The target device must send UDP packets from the defined port, else Tesira NCS block will filter the traffic.