Skip to main content
Chat with Biamp tech support
Biamp Cornerstone

Using the Network Command String block

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.

Tesira setup

Network configuration

Once the Network Command String block is added to a Tesira layout, the Properties window allows entry of the destination's network parameters:

 Block Init Dialogue.png   NCS Block 3x2.png  

 Network Command String protocol and IP.png

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. Once configured, the block will behave as follows:
    • IF Expected string1 is received, THEN Response string1 will be sent. IF Expected string2 is received, THEN Response string2 will be sent.
    • This Connection Sequence behaves in a very linear or serial manner.



Functional Configuration

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.

NCS - Offline view for functional configuration with number bubbles.jpg

  1. The Command String Edit button allows the user to define command strings to be sent from the Tesira device.
  2. The buttons in the Command Id column allow the strings to be sent manually.
  3. 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.
  4. 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.
  5. 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.

Character Details Example
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.)

  1. 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.
  2. When the entire input matches the initial portion of any pattern, but not the complete pattern, the block waits indefinitely for additional input.
  3. 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:

  1. 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.
  2. Response patterns should explicitly include trailing New Line (~0A), Carriage Return (~0D) or CR-LF (~0D~0A).
  3. Response patterns cannot end with an asterisk  (*).

Application and control string examples

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:

NCS - Application Block Drop.png

  • The microphone array utilizes TCP protocol on port 2202 at the IP The Properties of the Network Command String block have been configured accordingly:

Network Command String block Properties 3.15.png

  • 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:

NCS - Offline LED Configuration.png


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.
    • If AutoConnect is enabled on the NCS block, the block will attempt re-connection every 3 seconds. If the connection state appears to be "flapping" at the same 3-second rate, you may be experiencing attempted client-client communications. This will likely never succeed and UDP is a suggested next step.
    • A Wireshark capture will help provide visibility of this scenario.
  • 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.
    • A Wireshark capture showing ICMP "Destination unreachable" is a clue that the Tesira device is refusing the packet.
      • clipboard_e0b9156cdfb88d66a964c720b90ce1f50.png
      • The packet is refused because the port does not match the port defined in the NCS UDP block.
      • The UDP receive port can be corrected in the NCS block.
        • Some target devices allow their transmit port to be defined.
        • Some devices use random (ephemeral) ports for UDP transmission. Be sure to set the port and/or test the device after reboots to verify connectivity.
  • When the NCS block is configured for UDP, the local port definition is also important.
    • The local port is the port from which the NCS block will send commands. It is also the port that will be open to receive UDP responses from other devices.
    • If more than one NCS block is set to UDP, unique local ports must be used for each block.
    • If the local port is set to 65535, the block will use a random port in the ephemeral range. The randomly selected port will receive responses on the same port.
  • Testing tools and freeware resources: