LeCroy’s X-Stream based DSOs support various remote commands, including the newer automation methods, which allow remote applications to synchronize to acquisition and process complete events.
This Application Brief discusses the available commands and methods, explains their differences (which in some cases are subtle, but significant), and presents scenarios in which they would be used.
Understanding Timeouts
One of the most important concepts to understand when performing any kind of remote synchronization to a DSO’s activities is the timeout. It is also important to understand the difference between a timeout on the client side, and a timeout on the host (DSO) side.
Client Timeouts
The Client timeout is the amount of time that the client will wait for the DSO to respond to a question. In most cases, when simply setting up the DSO and querying various controls the timeout is not so important, the DSO will respond within a relatively short period of time so the default timeout that most client comms libraries use is sufficient. When the DSO is asked to perform a time-consuming operation, however, such as an Autosetup, or an acquisition with related processing, the timeout needs to be more carefully considered.
Taking the Autosetup operation as an example, consider the following sequence of remote commands and queries:
- Send AUTO_SETUP
- Send *OPC?
- Read response (DSO returns ‘1’ when Autosetup is complete)
Let’s assume that the default timeout of the communications library is 10 seconds. If the Autosetup operation is completed within 10 seconds, then the response to the *OPC? (operation complete) query will be received before the timeout occurs. If, however, the operation takes longer than 10 seconds, the query will time out, and an error flag will be set within the communications library. But these flags are rarely examined in most client applications. This generally results in a confused developer, wondering why his remote application didn’t wait for the operation to complete, and also why he didn’t receive the expected ‘1’ from his *OPC? query. Worse still would be the case where the operation generally sneaks in under the allotted time, but occasionally exceeds it, resulting in an application that works ‘most of the time.’
What’s important to learn here is that the timeout should be carefully considered, and it should be set to a value that is greater than the maximum time that an operation is expected to take, with a reasonable safety margin.
An example of how to correctly set timeouts when programming via GPIB is attached to this document.
Host Timeouts
Generally, in traditional GPIB instruments, the concept of the host timeout doesn’t exist. In X-Stream instruments, however, due to their support for ‘Automation’ methods and, in addition, due to the ability to execute these methods from a traditional remote interface, host timeouts need to be understood.
An example of an automation method that requires a timeout to be specified is WaitUntilIdle. This method accepts a single argument, which specifies a time, in seconds, after which the method will return control to the application. When it does return control it indicates whether the wait was successful or not by its return value.
When using these automation commands via the remote control interface (using the VBS command), it is important to ensure that the client timeout is greater than the host timeout.
Synchronization Using the Status Registers
There are two fundamental ways to synchronize a remote control application with the DSO.
The first is documented in this Lab Brief, and is arguably the simplest, and most common. This involves synchronous program flow, where after sending a command to the scope, the application sits and waits for its response, which indicates that the operation was completed.
The second method uses the status registers, along with Service Requests (SRQs) to allow asynchronous notification that pre-defined operations have been completed.
The basic idea is that the DSO’s multiple status registers are pre-configured so that an application is notified asynchronously. The advantage of such a method is that the remote application can continue to perform other operations while waiting for the DSO to complete an operation.
Since this method is documented in detail in the DSO’s Remote Control Manual it will not be expanded upon here.
The Synchronization Command/Queries, and Automation Methods
Following is a list of remote commands and queries, plus the automation methods, that are concerned with the synchronization of DSO acquisition and processing with remote control applications.
WAIT [] command
This remote command is useful only when the system is armed. It will wait for a user-specified, or infinite time, for a trigger.
In most cases it will also wait for all processing, dependent upon the trigger event, to be completed. Exceptions to this rule include waiting for processing initiated by loading a waveform into a memory via remote control, or changing a processing control, resulting in recalculation.
*OPC? query
This query waits for processing to be completed (or, more precisely, for the processing subsystem to become idle). It also waits for the acquisition system to complete an arm operation, which may take some time if calibration is required before the arm can be completed. For this reason it is not safe to rely upon *OPC? to wait for a trigger event if used after an ARM command. The WAIT command should be used instead.
Note that *OPC? will wait for an infinite time for processing to be complete. The client-side communications timeout should be used to limit the amount of time that the client will wait for its response. It’s good practice to check for timeout conditions when reading any response from the scope.
app.WaitUntilIdle([in] double timeoutSeconds) method
The WaitUntilIdle automation method performs a virtually identical function to *OPC?, documented above. The only differences being:
Note that there is no significant benefit in using VBS? ‘app.WaitUntilIdle(…)’ over a simple *OPC? query with appropriate client-side timeout.
app.Acquisition.Acquire([in] double timeoutSeconds, [in] long bForceTriggerOnTimeout) method
This automation method is probably the simplest way to take an acquisition and wait for the acquisition, and any dependent processing, to be completed. The first of the two arguments allows a timeout to be specified, which defines how long to wait for a trigger event. The second defines whether a trigger is forced after the specified time elapses.
Note: The total method execution time may be significantly longer than the specified timeout. This occurs for two reasons, the first is that a calibration may be required before the acquisition system may be armed, and the second is that the command also waits for dependent processing, which may take some time.
Typical Synchronization Scenarios The scenarios below cover the most common remote control synchronization cases. Note that Pseudo-code is used, since different communications libraries (NI GPIB-488, VISA, ActiveDSO, etc.) all use different names for the functions that set timeouts, send commands, read responses, etc.
- Single acquisition, with wait for trigger
This is probably the most common scenario: how to take a single acquisition and wait for the acquisition and any dependent processing to be completed. The client-side timeout should be set to a reasonable value, not too short so that the program execution continues before the trigger has been received, and not too long so that execution doesn’t stop, indefinitely waiting for a missing trigger.
Using ‘Legacy’ remote commands:
- Set remote timeout.
- Send TRMD SINGLE;WAIT timeout;*OPC?
- Read DSO response.
Using Automation methods app.Acquire(timeout, false)
- Autosetup, and wait for completion
Using ‘Legacy’ remote commands:
- Set remote timeout.
- Send ASET;*OPC?
- Read DSO response.
Using Automation methods app.AutoSetup
- Acquire, and read parameter value
Using ‘Legacy’ remote commands:
- Set remote timeout.
- Send TRMD SINGLE;WAIT timeout;C1:PAVA? AMPL
- Read DSO response.
Using Automation methods app.Acquire(timeout, false)
Concrete Examples
The following examples illustrate some of the techniques discussed above, using various programming languages and communications libraries.
