How to Control VeEX's Portable Test Sets and Probes Via (SCPI) Command Line Interface or Scripts?

The Command Line Interface (CLI) and Standard Commands for Programmable Instruments (SCPI) are intended for advanced users in need of writing test automation scripts.

This guide covers the basic concepts and procedures that apply to centralized probes (remote test units, RTU) and portable test platforms. Although the handheld/portable test sets are not meant to be used in permanent test automation applications, they do support SCPI commands meant for internal automating regression testing and their own final production tests. However, some of our customers can use the same commands to create their own scripts to automate their tests.

1. Introduction

This document is an introductory guide to the Session/Resouces management and typical SCPI commands, their structure, syntax, hierarchy, arguments, sequence, etc. It is not unintended to provide a comprehensive or up-to-date list of all the thousands of commands and arguments that can be constructed for all the continuously evolving Test Modes, link technologies and Applications. A complete list of all possible commands would be impractical to maintain, due to the constant evolution of our products and it would make it even more difficult for our users to search required commands. Instead, VeEX’s approach is to use a dynamic command generation tool called SCPI Remote & Command Reference Tool for PC. The SCPI tool is the recommended self-guided tool to identify all the commands, command sequences and arguments required for al basic configurations.

In contrast to the instruments’ standard graphical user interface (Local GUI), which imposes limits and helps with configuration choices depending on previous selections and settings as a mean of streamlining the configuration (for user friendliness) and helping inexperienced users, the command line interface relies on the expertise and awareness of users entering individual commands or writing scripts. Users must have sufficient knowledge and experience to figure out which commands are required, the right sequence of commands, dependencies, and the appropriate arguments and values to enter. It is recommended to use the Capture function on the SCPI Remote & Command Reference Tool, set the desired configuration, run the test and review the commands used.

The System and Administration commands (CLI) are not to be confused with the test modules’ SCPI-based test commands. This article focuses on the portable test sets’ initial settings for establishing Sessions, assigning test Resources and launching Test Modes (test applications). For application-specific test commands please refer to the SCPI Remote & Command Reference Tool or Contact Us to request the specific test mode CLI Commands Reference Guides.

It is likely that some newer commands may have been recently added and not documented in our written guide, as new commands and functions continue to be added to our products. To identify new or unlisted commands, use the help command, the SCPI Remote & Command Reference Tool. (PC license required. 30-day fully functional trial available upon installation.)

Although the concept applies to most VeEX products supporting SCPI commands, this article uses the TX300S (V300) test platform as an example.

1.1 Process Summary

1. Connect the test set's Management port to a LAN (Ethernet/IP).
2. Use a PC (controller) to establish an SSH or Telnet connection to the test set.
3. Use the System & Admin CLI commands to initiate a test Session.
4. Assign an available test Resource (Port Group) to the current session.
5. Start a Test Application supported by the selected test port group.
6. Let the Software, Firmware and/or FPGA code load, for the test application to be ready.
7. Upon confirmation, switch to the test application's SCPI commands to configure the test scenario, initiate the test and retrieve results, etc.
8. When finished, the script shall stop the test, exit the associated test applications, release the test resources (so they become available to others), terminate the session.

1.2 Supporting Test Platforms

The following families of test platforms support Telnet and SSH connections:

• Portable Test Platforms: V150, MTTplus family, TX300s family, RXT-1200 family, AT2500

• Centralized Probes: RTU-300, RTU-300+

The specific commands and feature support varies from product to product. Refer to the documentation and the SCPI Remote & Command Reference PC Tool.

2. How to Control VeEX Test sets

2.1 Establish a Connection with the Test Set

Follow this link to learn How To Establish a TELNET or SSH Connection with the test set. In summary:

C:\>telnet XXX.XXX.XXX.XXX 8023
TX300S CLI login:admin
Password:admin
TX300S>help
available commands list:
        session, used for session management
        resource, used for resource management
        info, used for query date|time|version|serial number
        reboot, used to reboot the system
        telnet, telnet services control
        timeout, set session time out (sec, default 86400 sec or 24 hours)
TX300S>

or

C:\Users\VeEX>ssh admin@XXX.XXX.XXX.XXX -p 8024
The authenticity of host '[XXX.XXX.XXX.XXX]:8024 ([XXX.XXX.XXX.XXX]:8024)' can't be established.
ED25519 key fingerprint is SHA256:BlRo+9v9z6yH+gHLrUeAexxg1jcMVu0M5iWAUuDKP5Q.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '[XXX.XXX.XXX.XXX]:8024' (ED25519) to the list of known hosts.
admin@XXX.XXX.XXX.XXX's password:admin

TX300S CLI login:admin
Password:admin
TX300S>help
available commands list:
        session, used for session management
        resource, used for resource management
        info, used for query date|time|version|serial number
        reboot, used to reboot the system
        telnet, telnet services control
        timeout, set session time out (sec, default 86400 sec or 24 hours)
TX300S>

Users can always type help to be reminded of the commands available at every level of the platform's CLI session management hierarchy (not applicable to test applications' SCPI commands).

2.2 Understanding Test Management Hierarchy

2.2.1 Sessions

Test Sessions are virtual connections used to allocate available test resources and manage the test set’s concurrent multi-test environment (if supported). Remote Users (controllers or scripts) need to start a new session or join an existing session before they can use a test port group (Resource).

• Remote Session IDs are initiated via TELNET or SSH connections and are numbered from 11 to 99.
• Local Session IDs are initiated by users sitting in front of the test set and operating it via its built-in touch screen or using the Web Remote feature. Local users don’t have to start a session since the GUI (Graphical User Interface) does it for them. Local sessions are numbed from 1 to 9. For this purpose, EZ-Remote™ users are also considered "local" users, since they operate the test set through screen mirroring.
• When a test Resource has not been assigned, it will display Session ID -1
• As an example, the TX340s with four test port groups, or the RXT-6402, can handle up to four simultaneous independent tests. Each test would need their own session, which the script could use to independently control all the active test engines being used. The test engines could also be used by different scripts, each with their own independent session(s).

TX300S>session list
+------------+---------+--------------+------------+
| Session ID | Res LOC | Local/Remote |  User Name |
+------------+---------+--------------+------------+

TX300S>session new
session 11>help
available commands list:
  resource, used to list/assign/release resource

Users can also specify the desired session number as the argument. The New argument assigns the next number available.

2.2.2 Resources

Depending on hardware configuration and licenses, VeEX’s portable test sets can host up to four (4) independent Test Port Groups and may have the capability of running up to four simultaneous tests. These capabilities are referred in this document as test Resources and they can be shared among two-to-four users (Sessions). These users or sessions are commonly automated scripts running on a PC.

Test Resources (or internal test engines) are labeled based on their Port Groups (P1 = Port 1, P2 = Port 2, P3 and P4). Products with multiple modules/blades also use M1= Module 1, M2 = Module 2, so they refer to the test resources as M1P1, M1P2, M2P1 and M2P2.

• Port Groups are usually labeled with white rounded squares, with the port number inside.
• Module Groups are usually labeled with orange rounded squares, with the module number inside.

session 11>resource help
resource command help:
resource list: list all resources
resource assign LOC: assign a resource LOCation (e.g. P1, P2. M1P1, M1P2) to this session. M1=Module 1, M2=Module 2, P1=Port 1, P2=Port 2.
resource release: release resource assigned to this session

session 11>resource list
+----+----------+-------------+------------+
|    | Location | Module Type | Session ID |
+----+----------+-------------+------------+
|  1 |       P1 |     TX300SM |         -1 |
+----+----------+-------------+------------+
|  2 |       P2 |     TX300SM |         -1 |
+----+----------+-------------+------------+

session 11>resource assign P1
OK

session 11>resource list
+----+----------+-------------+------------+
|    | Location | Module Type | Session ID |
+----+----------+-------------+------------+
|  1 |       P1 |     TX300SM |         11 |
+----+----------+-------------+------------+
|  2 |       P2 |     TX300SM |         -1 |
+----+----------+-------------+------------+

Test Resources must be assigned to a session before the session owner can use them (configure, run tests, manage results, etc.). Once finished, the session owner shall release the resources assigned, in order to make them available to other users.

2.2.3 Test Port Groups

As an example, up to four (4) Test Port Groups can be available in a TX300S portable test platform, loaded with two TX340sm modules (bottom-right picture). Each Group is identified (addressed) by its position or Location (LOC). The LOC argument (position) uses the P1 notation for Test Port Group 1 and P2 for Test Port Group 2. The notation M1P1 may also be used in the SCPI Command Reference Tool to refer to “Module 1, Port 1”, when more than one test module is loaded.

The TX300S may be used in some of the examples presented in these documents as most command structures are similar between products and test features. There may be some differences in the way ports are addressed, for example, based on the test engine architecture of each product (e.g., multi-module products maty refer to M1P1, M1P2, M2P1, M2P2 to refer to the module and port group numbers, while others with simpler architectures may just use P2 and P2). We recommend using the SCPI Remote & Command Reference PC Tool’s Capture function to identify the correct port addressing.

2.2.4 Starting Test Applications

Once a session has been established and a set of test resources (test engine) has been assigned to it, the next step is to start the desired test application. For example, after assigning a Test Group with an SFP+ port capable of 10G, the session manager may start an OTU2 or 10GE test application. The list of link technologies and rates available will depend on the selected test group itself. Products like the RXT-6402 has two port groups capable of running test from 25GE to 400GE and two multi-service port groups capable of running tests from 1.5M to 14G.

Here is an example of the different Test Application commands available for a TX340sm port group:

TX300S CLI login:admin
Password:admin
TX300S>session new
session 11>resource assign m1p1
OK
session 11>help
        1ge, 1G Ethernet Testing
        10ge, 10G Ethernet Testing
        sdh, OTU2/STM64/OC192 & Low Rate Testing
        fiber1248g, 1/2/4/8G Fiber Channel Testing
        fiber1016g, 10/16G Fiber Channel Testing
        c37_94, C37.94 Testing
        c37_94mon, C37.94 Monitor
        c37_94dual, C37.94 Pass-Through & Monitor
        otuxe, OTU-Xe(1e/2e) Testing
session 11>fiber1016g
Remote Control Enabled.
{From here on it is all application-specific SCPI commands}

E.g., use the fiber1016g command to launch the 10G-16G Fibre Channel test application. Once the command gets executed, the test set will show the Remote Control Enabled confirmation message and switch to SCPI commands mode. The controlling script must use the SCPI command structure applicable to the test application selected. For further details about SCPI commands libraries, refer to the SCPI Remote & Command Reference Tool.

Configuration (settings) commands' execution are acknowledged by OK or FAIL responses. Enquiry commands (?) return the status or value(s), followed by OK. There are also error messages for typos, out of sequence commands, wrong arguments, etc. Scripts must take those acknowledgements into account.

SCPI commands follow a hierarchical structure, with each level separated by a colon (:) and each structure ends with a semicolon (;). Uppercase or lowercase can be used for the commands.

2.2.5 System & Administration Commands Summary

The TX300S family (and other portable test sets) offer a simple multi-user and multi-test environment, that allows a session-based remote control operation. The user or controlling script must establish a session before test resources can be assigned and used.

The System and Administration Command Line Interface is structured in different levels (like sub-menus on a GUI) that provide different sets of related functions. Users must enter the desired level (or prompt) before typing commands related to that particular set of functions. As a reminder, the telnet terminal will display the current level as a prompt. Use the EXIT command to return to the previous function level (prompt).

The following structure is provided as an example only. Please use the help command while in the session management CLI for an updated list for each level and mode, or refer to VeEX’s SCPI Remote & Command Reference Tool.

TX300S>
  help                       List of main system commands
  session help               Lists session commands
    session XX               Enters (joins) the Session and Resources management. XX = 11 to 99
      session list           Lists active sessions, module slots, and local/remote users
      session new            Creates a new session and assigns the next available XX number
        session delete XX    Deletes session XX (stop test, release resources, before using Delete)
      resource               Enters the resource management level
        resource list        Lists active test port groups, location, and the sessions assigned
        resource assign LOC  Assigns resource to current session. LOC = Test port group position
        resource release     Releases resource (test port group) assigned to the current session
          1ge                Starts the 1G Ethernet test mode SCPI-based command line interface
          10ge               Starts the 10G Ethernet test mode SCPI-based command line interface
          sdh                Starts the OTN/SDH/SONET/PDH/DSn test mode SCPI-based command line interface. Includes TDM rates from 1.5M to 11Gbps.
          fiber124g          Starts the 1/2/4G Fibre Channel test mode SCPI-based command line interface
          fiber810g          Starts the 8/10G Fibre Channel test mode SCPI-based command line interface
          otuxe              Starts the OTU2e and OTU1e overclocked test mode SCPI-based command line interface
       help                  List of supported resource commands.
     exit                    Goes back to TX300S main prompt
  exit                       Closes the telnet connection (does not terminate the test sessions)

The TX300S> prompt is the System and Administration CLI root.

sdh2g5    {obsolete. Started the PDH/DSn/STM-16/OC-48/OTU1 test mode.}
sdh10g    {Obsolete. Started the PDH/DSn/STM-64/OC-192/OTU2 test mode.}

If you are new to CLI, or you are just starting to create scripts for VeEX test sets, it might be helpful to manually configure and verify the desired settings using the test set’s (local) touch screen GUI or VeEX’s SCPI Remote & Command Reference Tool and its command Capture function to guide you through all the individual commands and arguments required for each specific test configuration.

To go back to the Session and Administration CLI, from a SCPI test application session, without closing the telnet session, enter the EXIT command to exit the current level. This will take the controlling user back to the Session XX> prompt, so the script can release the assigned resource or log on to another test session (for multi-module scripts). Sending the EXIT command multiple times will take you back to the root TX300S> prompt and even close the telnet client.

Users have two ways to terminate the current test session, including closing the telnet connection:

1. Stop the current test, send the EXIT command, send RESOURCE RELEASE, send SESSION DELETE send EXIT (make sure to wait and validate each confirmation string or prompt).
2. Use the SESSION DELETE command, which is equivalent to closing the session, release test resource, and end the test application.

To terminate the telnet connection, without stopping the Test Application, the user or controlling script must send the EXIT command (multiple times), until it gets to the test set's root prompt (e.g., TX300S>). Then join the same test session later by issuing the session XX command and rejoining the same SCPI Remote Test Application session.

Although not recommended, the ^C (Ctrl+C) command could be used to abruptly terminate the telnet connection. This will also close the telnet session, if for some reason the system fails to respond. Note that test sessions, test applications and active tests will continue to run in the test set, unless they are stopped, terminated or released. To re-join a running test, users/scripts must re-establish a telnet connection, rejoin the active session(s), and re-enter the test application command. Once re-joined, users can stop tests, release resources and close active sessions, so the resources become available to others.

2.2.6 Examples

The following session example is presented to demonstrate the simplicity of the test sets' initial commands.

Commands entered by the user are presented in bold face for easier identification.

C:\>telnet 192.168.31.175 8023
TX300S CLI login:admin
Password:admin
TX300S>help
available commands list:
        session, used for session management
        resource, used for resource management
        info, used for query date|time|version|serial number
        reboot, used for reboot the system
        telnet, telnet services control
        timeout, set session time out (sec, default 86400 sec or 24 hours

TX300S>session help
session command help:
        session list: list all sessions
        session new: alloc a new session, and enter the new session
        session delete XX: delete a existing session (Session ID XX)
        session XX: enter a exist session (ranged from 11 ~ 99)

TX300S>session list
+------------+---------+--------------+------------+
| Session ID | Res LOC | Local/Remote |  User Name |
+------------+---------+--------------+------------+

TX300S>session new

session 11>help
available commands list:
        resource, used to list/assign/release resource

session 11>resource help
resource command help:
        resource list: list all resources
        resource assign LOC: assign a resource LOCation (e.g. P1, P2. M1P1, M1P2) to this session. M1=Module 1, M2=Module 2, P1=Port 1, P2=Port 2.
        resource release: release resource assigned to this session

session 11>resource list
+----+----------+-------------+------------+
|    | Location | Module Type | Session ID |
+----+----------+-------------+------------+
|  1 |       P1 |     TX300SM |         -1 |
+----+----------+-------------+------------+
|  2 |       P2 |     TX300SM |         -1 |
+----+----------+-------------+------------+

session 11>resource assign P1
OK

session 11>resource list
+----+----------+-------------+------------+
|    | Location | Module Type | Session ID |
+----+----------+-------------+------------+
|  1 |       P1 |     TX300SM |         11 |
+----+----------+-------------+------------+
|  2 |       P2 |     TX300SM |         -1 |
+----+----------+-------------+------------+

session 11>help          {Lists the available Test Applications}
available commands list:
        resource, used to list/assign/release resource
        1ge, 1G Ethernet Testing
        10ge, 10G Ethernet Testing
        1ge_10ge, 1G & 10G Ethernet Testing
        sdh, OTN/SDH/SONET, PDH/DSn Testing
        fiber124g, 1/2/4G Fiber Channel Testing
        fiber810g, 8/10G Fiber Channel Testing
        otuxe, OTU-Xe(1e/2e) Testing

session 11>sdh            {Launches the Test Application}
Remote Control Enabled    {Confirms the test application is up and ready}

:status ?;                {From here on, refer to the function-specific SCPI commands}
0;
OK

Test ports can also be identified with the following notation: M1P1 (Module 1, Port 1). This helps when managing multiple ports in a test scenario.

2.2.7 Re-joining an Active Test Session

Users or controlling scripts may need to re-join an ongoing test after losing connection (on purpose, by accident, network issues or managing multiple sessions), to continue a test or batch of tests. For example, the controller may have disconnected during a long-term test and needs to go back to read the results, or the controller talks to one module at a time and needs to reestablish the connection to each of the modules.

Here is the process to re-join an ongoing test session:

1. Log in (establish an SSH or Telnet connection with the test set).
2. Re-join the desired session by issuing the session command (e.g., session 11)
3. In certain test sets, using the help command after joining an ongoing test session, would provide information to confirm the test application that is currently running. For example, session 11>help would return "sdh, OTU2/STM64/OC192 & Low Rate Testing". The script can use this information to rejoin the test session.
4. Enter the test mode command used for that particular session (e.g., sdh). A "Remote Control Enabled" confirmation may be received, to confirm that the session is back on SCPI command mode.
5. Check the current test status (e.g., :P1:status ?; and its response should be RUNNING;)
6. Check the current test results (e.g., :P1:results ?;)

Below is an example of the command sequence required to re-join an existing test.

telnet xxx.xxx.xxx.xxx 8023
TX300S CLI login:admin 
Password:admin
TX300S>session list
+------------+---------+--------------+------------+
| Session ID | Res LOC | Local/Remote |  User Name |
+------------+---------+--------------+------------+
|         11 |    M1P1 |       Remote |      admin |
+------------+---------+--------------+------------+
|         12 |    M1P2 |       Remote |      admin |
+------------+---------+--------------+------------+

TX300S>session 12
session 12>help
        sdh, OTU2/STM64/OC192 & Low Rate Testing
session 12>sdh
Remote Control Enabled.
:tx:laser ?;
TRUE;
OK

2.2.8 Session Timeout

This is a new feature (2023) that may not be available in all test sets (Get the latest platform and modules' version and try to see if available). There have been some recurring issues with some script programmers who keep initiating new telnet sessions on their scripts, without properly closing previous ones. Over time, this creates a large amount of abandoned, but active, session in the test set that slow down the system, which eventually stops responding, requiring undesired hard reboots. 

To address those cases, a watchdog was added to monitor idle sessions and terminate them after certain timeout period. By default, such period is 86400 seconds (24 hours), to allow for long-term test. If a long-term test needs to be let alone for longer periods, programmers have two choices:

• Program the controlling script to poll the instrument regularly (e.g., every hour) with commands such as :STATUS ?; or :RESULTS ?; command, to keep the session alive. After all, the script application may need to display some progress information.
• Use the timeout command, on the system prompt (e.g., TX300S>) followed with the time in seconds, to modify the watchdog with the preferred period.

TX300S>timeout 10            
Session time out is changed to 10 sec

Warning: Your session timed out due to inactivity and will be terminated!
Connection closed by foreign host.

3. Numeric Formats Supported

3.1 Decimal, Hex, and Binary

Although all the examples provided in this document are presented with values in decimal representation, some commands may accept different formats for binary arguments, by appending the 0x prefix for hexadecimal or 0b for binary notations, for example:

• Decimal format:             255
• Hexadecimal Format:     0xFF
• Binary format:               0b11111111

3.2 Boolean Values

Boolean values are also presented in decimal format (0 or 1), nonetheless the instrument’s CLI parser will also accept the following strings:

• FALSE  same as             0
• TRUE    same as            1

Boolean values are reported as TRUE or FALSE. In some cases, True = ON and False = OFF.

4. Troubleshooting Tips

4.1 Rebooting a Remote Test Sets

Only if instructed by a Customer Support representative, a remote user could force the portable test set to reboot. Keep in mind that a forced reboot does not perform a graceful shut down, so any setting, tests, results or tasks will be lost. This task should only be performed to test sets that are set to use STATIC IP address in LAN environments, so they reconnect automatically (especially important at unmanned points-of-presence, where it may not be easy to get local help).

reboot          This command makes the test set shut down and reboot.

Application-Specific SCPI Command Sample References

To download a copy of the VeEX SCPI Remote & Command Reference Tool installer package for Windows PC (30-day trial included) and SCPI Commands Getting Started Guide samples for applications such as Ethernet, OTN/SDH/SONET/PDH/DSn, etc., scan (or click on) the QR code below. In the event that the downloaded ZIP file is flagged as an "Uncommon Download" or "can't be downloaded securely", click on the warning message, open the options, and select Keep and Keep Anyway. However, we take security very seriously, so we recommend not to download these files from sources different than the www.veexinc.com domain and to follow your organization's IT security policies. Please Contact Us if you encounter any issues.

www.veexinc.com/SecureFile/VeEX_SCPI-Remote_Package.zip

The SCPI Commands Sample Guides are offered as visual references with examples of some common/typical commands structures, syntax, but not meant to provide a complete list of all available commands. For the actual command reference, VeEX offers the self-guided SCPI Remote & Command Reference Tool as the main documentation for script developers.