jankae
commented
5 months ago Thank you very much for the detailed explanation. I didn't implement all these details because I didn't see much of a point - usually I just use the device-dependent commands to control my instruments. I guess the situation might be different if you have a mixture of GPIB and TCP SCPI instruments (I haven't used GPIB at all so far).
To be honest I don't see the point of some of the mandated commands (e.g. SRE). But adhering to a standard is always a good idea. Most things (like the status registers) should be pretty easy, only the WAI/OPC feature will get a little bit more complicated. Could you link me to some official SCPI syntax documentation? I could only find the SCPI Syntax & Style guide from 1999 (https://www.ivifoundation.org/downloads/SCPI/scpi-99.pdf) but for example this does not contain the DESE command you mentioned.
scott-guthridge
Summary
On my bench, I have several devices connected by GPIB (IEEE488) behind a National Instruments GPIB/ENET adapter. I also have a Tek scope that implements a SCPI interface through a TCP/IP socket. I have quite a few existing programs I use for automation. I found, though, that when using an existing program as a template for the LibreVNA, I had to make a lot more changes than usual when going between devices because the LibreVNA's SCPI interface deviates the most from standard SCPI semantics.
The usual flow for an automation program is first to send a lot of commands to set up the instrument. In this example, the Tek scope over TCP. [This example, interestingly, implements a low-frequency VNA using the scope to measure amplitude and phase difference vs. the reference signal.]
In this case, we sent sent 40 or 41 back-to-back commands (depending on the if/else above).
Next, check if anything so far generated an error:
The standard event status register bits are defined as:
Not all of these bits make sense for the LibreVNA. For example, it's not clear that the GUI knows when the device was powered on, so PON may not make sense to ever set. Maybe there is no need for URQ. On the other hand, the CME bit (syntax error in command) definitely makes sense. Clearly, RQC doesn't apply. OPC can be implemented for completeness, described further below.
If no errors, we trigger an acquisition and wait for the acquisition to complete.
The *WAI blocks command processing until the background acquisition we triggered completes. We need to synchronize with the acquisition because the next command we're going to send is a query to grab the acquired data, and we need to make sure the data is going to be there when we ask for it.
There are several alternatives to the WAI command. A very similar command is OPC?. The only difference between WAI and OPC? is that the former doesn't print any output while the later prints a "1" on a line by itself. Programmer will usually use WAI followed immediately by a :DATA...? or :CURVE...? if all they want is the data back. They'll use the OPC? method if they need to do some action in the program in response to the asynchronous command completing, for example, tell another device to do something. It's also possible to use OPC (which doesn't block command processing -- just arms a mechanism to set the OPC status flag next time all async events have completed) followed by either polling the OPC flag in the event status register, or causing the device to generate a "service request" to generate an interrupt on the host (which could be implemented over TCP/IP by sending an "urgent" message on the socket). In real IEEE 488, there is also serial poll and parallel poll, but those require having a control channel separate from the data channel [NI GPIB-ENET and Visa interfaces implement this by using multiple socket connections]. Of of all these, probably WAI and OPC? are the most useful when working with a single device over a single socket.
Finally, once we know the acquisition is complete, we can ask for the data:
In another issue, a comment mentioned that the OPC? command was interpreted to just wait for the previous command and not wait for asynchronous actions triggered by that command. That's not correct, though. The main purpose of WAI and OPC? are to wait for asynchronous commands, usually acquisition commands, to make data available. If the previous command's effect were synchronous (as opposed to triggering something), then of course it's finished when we get to this command. We could equally have just sent IDN? in this case since it doesn't really wait for anything. That isn't a very useful semantic for WAI/OPC?
There was also a question about what to do if acquisition averaging or continuous acquisition is enabled. Those semantics are well-defined in SCPI. In the averaging case, the operation should be considered complete after the specified number of acquisitions have been taken. In the continuous case, the operation should be considered complete when the next acquisition completes. In all of these, the main completion criterion is: when can the user send a :DATA....? command and be guaranteed there will be new output available.
The LibreVNA SCPI interface would be more useful and easier to adapt to if it didn't print responses to non-query commands, implemented WAI and OPC? to wait for acquisition complete / data available, and provided a basic implementation of the standard event status register and its related commands, at least: DESE, DESE?, ESR?, and if possible, the others: ESE, ESE?, STB?, SRE and SRE? for adherence and completeness. In the next section, I give suggestions on how to do this in a way that doesn't break existing compatibility.
Paths to implement it
Most SCPI scripts start out by sending a CLS command to clear any pending errors. This command isn't currently implemented by the LibreVNA. So a simple approach to avoid breaking existing compatibility would be to implement the CLS command and give it the side-effect of enabling standard SCPI semantics. This would disable output from non-query commands, including itself. A device-dependent command, e.g. :CONFigure:StrictSCPI OFF, could be provided to turn the responses back on if desired.
Next, the WAI command should be implemented and OPC? command modified so that both wait for data to become available. In VNA mode, these commands would block command processing until a :VNA:ACQ:FIN? would return TRUE; in SA mode, it would likewise wait for SA:ACQ:FIN? to become true. Errors shoud also wake it up. Having *OPC? wait for data doesn't really break existing programs since it only waits longer than before, but this behavior could also be conditional under :CONF:StrictSCPI as above, if desired.
A basic implementation of the standard event status register mechanism is pretty easy (actually, all of it is pretty easy). Figure 3-6 on page 894 of this Tek scope document is a better picture of the registers than those given in the SCPI or IEEE 488.2 documents. First, there is a single-byte register, device event status enable register (DESER), read with :DESE? and written with :DESE decimal-number that acts as a mask for which events should be reported. When an error/event is posted, the appropriate bit in sesr is set if it's also in the deser mask (see pseudocode below). The standard event status register (SESR) is read through ESR?, which also clears it back to zero. So at the top of the SCPI script, you'll see something like
DESE 60to enable reporting of errors CME|EXE|DDE|QYE. Then at important points, the program will use ESE? to check if any errors occurred (and clear them). These registers should be global for the device and not associated with the current TCP connection. The remaining error registers are described below.pseudo code...
If you want to generate individual event codes/messages and put them into a queue, you can, but it's not required. The standard SCPI method for reading events is documented in chapter 20, status subsystem in the SCPI command reference. That section is a little cumbersome, and I notice that Tek implements a simpler proprietary mechanism: EVQty? to get a count of the number of events in the queue, EVENT? to read and remove the next event as a numeric code, and EVMsg? to read and remove the next event as a numeric code followed by a string explanation, all one one line. These are described in the same Tek document I linked above.
The rest of the error registers are less useful in the context of one device over a TCP connection, but I would implement them anyway for completeness and conformance to the standard -- there's not a lot to them. The next register, "ESER" holds another mask. It is read through ESE? and set through ESE. Next is SBR, described in a moment. And then there is yet a third mask, SRER, read using SRE? and written using SRE. The SBR register is a status byte read through STB?. This query doesn't clear anything. SBR and the masks around it are a lot more useful in IEEE 488 where link commands and data are separate and it's possible to read the status byte through the serial poll mechanism without having to use a query command. Here, however, the only thing that reads SBR is the STB? query, and so it's simpler to just compute the value on the fly as part of the query than to actually store (and maintain) SBR in memory. Bit 5 (ESB) of SBR is true if the status register hasn't been reaped by an ESR? and has bits that are in the ESER mask set. Bit 4 (MAV) is supposed to indicate that some query command has printed output but host hasn't read it all. Over TCP/IP, it's not really possible to determine if this is true because the data could already be queued at the host, and the only way the user can see the answer, anyway, is by reading all the data so far printed (so there isn't any left now), then reading the output printed by the STB? query, so it's pretty easy to argue that MAV reported by this command should always be 0 since you have to clear out the data queue to see the answer. Bits 0-3 and bit 7 are application-specific condition flags -- you can put anything in them you want. All that's left is bit 6, MSS. Bit 6 is true iff the SBR so far computed bitwise anded with the SRER mask is not zero.
The *STB? query is useful mainly if application-specific condition bits (0-3, 7) are used. Otherwise, all it does is provide a way to check for errors without clearing them, and checks off a required command for SCPI. Code for it is pretty minimal.
Next SCPI required command is OPC (not the query). Unlike WAI and *OPC?, this command does not wait for commands to complete. Rather, all it does is change state flags. If there are no asynchronous commands running, then it posts an OPC event (setting bit 0 of sesr if enabled by the deser mask). If one of more asynchronous commands are running, then it sets a flag to cause an OPC event to be generated next time the number of active async commands goes to zero.
The way OPC is used is the following. A program starts one or more asynchronous commands such as triggering an acquisition. Then it sends OPC. The program can continue to send commands and queries to the device. These are not blocked, though it's recommended not to start further async commands until the earlier ones are finished. Otherwise, you can get a misleading OPC status bit while newly started async commands may still be active. Now, it's possible to poll for all background commands finished by simply doing an *ESR? query and checking bit 0.
Extra information
I can help with implementation if needed.