JOSS paper: support of TCPIP resources

[MatthieuDartiailh]

While following my comments during the pre-review the text has been amended in the "current limitation and future work" section I still find the beginning of the paper misleading. Since the paper should target not specialist, one could specify that VISA supports several protocols over TCPIP (corresponding to different resource class INSTR vs SOCKET) and stress the SwiftVISASwift only support raw sockets connections.

Overall the paper could be more readable to people familiar with VISA if it used the standard interface type/resource class reference: GPIB::INSTR (GPIB:INTFC also exists), USB::INSTR (NI also has a concept of USB::RAW that is not VISA compliant), etc

Line 57 is the first line where I believe some clarification would be welcome.

openjournals/joss-reviews#4752

[OHildreth]

Authors’ Response to Reviewer Comment
Thank you for the suggestion to clarify VISA. I’ve added a VISA Overview section to describe VISA in more detail.

Added Text

VISA Overview

This section provides a brief overview of VISA to better understand the purpose of this project and some of the key terminology used throughout this publication.[@GH_VISA_Background, @GH_VISA_Terminology_Resource] VISA was originally standardized through the VXIplug&play alliance and is currently maintained by the IVI Foundation.[@wiki_VISA] The purpose of the VISA API is to provide a set of standard, consistent architecture to communicate with Test and Measurement (T&M) instruments that is reasonably independent of the interface bus and is consistent across devices of similar types. For example, a programmer would be able to write should be able use the same code to control multimeters made by different manufacturers (assuming the instruments' capabilities are the same). Additionally, even if the capabilities are different, the API to control similar aspects of different instruments is often the same. One nice aspect of the API is that many the VISA Commands use to control instruments consist of simple text strings passed using a standard communication interface (USB, TCP/IP, etc.).

It is important to understand some of VISA's Resource terminology.[@GH_VISA_Terminology_Resource] A Resource is an instrument connected to your system and the Resource provides a complete description of the set of capabilities for the instrument. There are several types of VISA resources: INSTR, MEMACC, INTFC, BACKPLANE, SERVANT, SOCKET, and RAW. According to the National Instruments VISA Resources page, most VISA applications and instrument drivers use only the INSTR resource.[@GH_VISA_Terminology_Resource] The Resource's Interface is often describe a concatenation of the communication protocol with the Resource Type. For example, a resource communicating over USB using the Instrument Type would be called a USB::INSTR. Communicating over TCP/IP using a Socket type would be TCPIP::SOCKET.
While the VISA API provides a simple programming interface to control various T&M instruments, a set of frameworks and drivers are necessary to handle communication between the devices and the computer. This is often handled using the pre-compiled National Instruments VISA framework, NI-VISA. This C-based framework can communicate with a broad range of instrument types using a broad range of communication protocols. Overall, NI-VISA is a good starting place when writing T&M instrument control software. However, writing GUI-based software in C is harder than using more modern programming languages, such as python, C++, Swift, etc. As a result, there is a large community of programmers and scientists writing wrappers around the NI-VISA framework[@pyvisa, @GH_SwiftVISA, @GH_GOwrapper, @GH_JuliaWrapper] or writing their own VISA implementation[@GH_pyVISApy, @GH_SwiftVISASwift] in their preferred language.

[MatthieuDartiailh]

I have two issues with the added text:

• the first paragraph seem to conflate the goal of IVI drivers (consistency across devices of similar types) or SCPI and of VISA itself which does not prescribe the way the instrument operate only the communication protocol. (except for IEEE 488.2 command string that can be equivalent to low level VISA operations CLS and TRG)
• the second paragraph sounds to National Instrument centered to me. The VISA specification is implemented by several large manufacturers besides NI: Keysight, R&S, Tektronik and they all share the same API and ABI allowing for seamless use of any implementation through FFI.

[OHildreth]

Thank you for the suggestion to clarify IVI and SCPI and VISA. We’ve updated the text to make this section clearer.

Updated Text
This section provides a brief overview of VISA to better understand the purpose of this project and some of the key terminology used throughout this publication.[@GH_VISA_Background, @GH_VISA_Terminology_Resource] VISA is a Test and Measurement (T&M) communication protocol originally standardized through the VXIplug&play alliance and is currently maintained by the IVI Foundation.[@wiki_VISA] This specification is implemented by a number of large T&M equipment manufacturers, including National Instruments (NI), Keysight, Tektronik, and Rohde & Schwarz (R&S) to name a few. It provides a standard architecture to control instruments that is reasonably independent of manufacturer, interface bus, and is consistent across devices of similar types. For example, a programmer should be able use the same, or at least similar, code to control multimeters made by different manufacturers (assuming the instruments' capabilities are the same). Additionally, even if the capabilities are different, the API to control similar aspects of different instruments is often the same.

It is important to understand some of VISA's Resource terminology since SwiftVISA and SwiftVISASwift don't support all the capabilities specificied in the VISA protocol.[@GH_VISA_Terminology_Resource]A Resource is an instrument connected to your system and the Resource provides a complete description of the set of capabilities for the instrument. There are several types of VISA resources: INSTR, MEMACC, INTFC, BACKPLANE, SERVANT, SOCKET, and RAW. According to the National Instruments VISA Resources page, most VISA applications and instrument drivers use only the INSTR resource.[@GH_VISA_Terminology_Resource] The Resource's Interface often describes a concatenation of the communication protocol with the Resource Type. For example, a resource communicating over USB using the Instrument Type would be called a USB::INSTR. Communicating over TCP/IP using a Socket type would be TCPIP::SOCKET.

While the VISA API provides a simple programming interface to control various T&M instruments, a set of frameworks and drivers are necessary to handle communication between the devices and the computer. This is often handled using a pre-compiled framework, such as the ones supplied by the National Instruments NI-VISA Framework[@NI-VISA_download] and Rohde & Schwarz R&S VISA framework[@GH_RS-VISA]. These C-based frameworks can communicate with a wide range of instrument types using a number of communication protocols. However, writing GUI-based software in C is harder than using more modern programming languages, such as python, C++, Swift, etc. As a result, there is a large community of programmers and scientists writing wrappers around the NI-VISA framework[@pyvisa, @GH_SwiftVISA; @GH_GOwrapper; @GH_JuliaWrapper] or writing their own VISA implementation[@GH_PyVISApy; @GH_SwiftVISASwift] in their preferred language. This allows developers to write instrumentation control software using a modern language with access modern GUI and system-level APIs.

[MatthieuDartiailh]

Sorry for being annoying here but there are still some imprecision that bother me.

It provides a standard architecture to control instruments that is reasonably independent of manufacturer, interface bus, and is consistent across devices of similar types. For example, a programmer should be able use the same, or at least similar, code to control multimeters made by different manufacturers (assuming the instruments' capabilities are the same). Additionally, even if the capabilities are different, the API to control similar aspects of different instruments is often the same.

VISA does not mandate any uniformity in the commands. You could maybe rephrase this along the following lines:

It provides a standard which allows to abstract in most cases the interface bus used to interface with the instrument. Also while this is not part of the VISA standard, the interface provided for devices of similar types is often close. For example ...

It is important to understand some of VISA's Resource terminology since SwiftVISA and SwiftVISASwift don't support all the capabilities specificied in the VISA protocol.[@GH_VISA_Terminology_Resource]A Resource is an instrument connected to your system and the Resource provides a complete description of the set of capabilities for the instrument. There are several types of VISA resources: INSTR, MEMACC, INTFC, BACKPLANE, SERVANT, SOCKET, and RAW.

Technically RAW is NI specific and not part of VISA

While the VISA API provides a simple programming interface to control various T&M instruments, a set of frameworks and drivers are necessary to handle communication between the devices and the computer. This is often handled using a pre-compiled framework, such as the ones supplied by the National Instruments NI-VISA Framework[@NI-VISA_download] and Rohde & Schwarz R&S VISA framework[@GH_RS-VISA]. These C-based frameworks can communicate with a wide range of instrument types using a number of communication protocols.

This is the most confusing part to me. VISA is a standard for a library allowing to communicate with instruments. So what you need is not a framework (I feel your MacOS experience shows here, on Windows I would never refer to VISA as a framework) but an implementation of the standard. The standard is based on C so manufacturer exposes a C interface which I agree is often not what we need or want. I am not sure how to re-phrase that part though.

[OHildreth]

Sorry for being annoying here but there are still some imprecision that bother me.

VISA does not mandate any uniformity in the commands. You could maybe rephrase this along the following lines:
It provides a standard which allows to abstract in most cases the interface bus used to interface with the instrument. Also while this is not part of the VISA standard, the interface provided for devices of similar types is often close. For example ...

Author Response
Thanks for helping with the language/terminology. Below is the original and updated text with the updated sections in italics.

Original Text
It provides a standard architecture to control instruments that is reasonably independent of manufacturer, interface bus, and is consistent across devices of similar types. For example, a programmer should be able use the same, or at least similar, code to control multimeters made by different manufacturers (assuming the instruments' capabilities are the same). Additionally, even if the capabilities are different, the API to control similar aspects of different instruments is often the same.

Updated Text
It provides a standard which allows to abstract, in most cases, the interface bus used to interface with the instrument. Also while this is not part of the VISA standard, the interface provided for devices of similar types is often close. For example, a programmer should be able use the same, or at least similar, code to control multimeters made by different manufacturers (assuming the instruments' capabilities are the same). Additionally, even if the capabilities are different, the API to control similar aspects of different instruments is often the same.

[OHildreth]

Technically RAW is NI specific and not part of VISA

Author Response:
Thanks for noticing that. I got a good amount of my VISA background information from the NI-VISA information pages. I've remove the referenced to RAW. Changes are listed under Updated Text in italics.

Original Text
It is important to understand some of VISA's Resource terminology since SwiftVISA and SwiftVISASwift don't support all the capabilities specificied in the VISA protocol.[@GH_VISA_Terminology_Resource]A Resource is an instrument connected to your system and the Resource provides a complete description of the set of capabilities for the instrument. There are several types of VISA resources: INSTR, MEMACC, INTFC, BACKPLANE, SERVANT, SOCKET, and RAW.

Updated Text
It is important to understand some of VISA's Resource terminology since SwiftVISA and SwiftVISASwift don't support all the capabilities specificied in the VISA protocol.[@GH_VISA_Terminology_Resource]A Resource is an instrument connected to your system and the Resource provides a complete description of the set of capabilities for the instrument. There are several types of VISA resources: INSTR, MEMACC, INTFC, BACKPLANE, SERVANT, and SOCKET.

[OHildreth]

This is the most confusing part to me. VISA is a standard for a library allowing to communicate with instruments. So what you need is not a framework (I feel your MacOS experience shows here, on Windows I would never refer to VISA as a framework) but an implementation of the standard. The standard is based on C so manufacturer exposes a C interface which I agree is often not what we need or want. I am not sure how to re-phrase that part though.

Author Response:
Thanks again for all of our help clarifying this for us. I've updated the text with your recommendations and tried to emphasize that VISA is a standard, that a programmer needs to implement the standard to actually communicate with a devices, and that implementations of that standard already exist for people to use.

Original Text
While the VISA API provides a simple programming interface to control various T&M instruments, a set of frameworks and drivers are necessary to handle communication between the devices and the computer. This is often handled using a pre-compiled framework, such as the ones supplied by the National Instruments NI-VISA Framework[@NI-VISA_download] and Rohde & Schwarz R&S VISA framework[@GH_RS-VISA]. These C-based frameworks can communicate with a wide range of instrument types using a number of communication protocols.

Updated Text
VISA is a standard for a library allowing for communication with conforming T&M instruments. A programmer needs an implementation of the VISA standard to actually communicate between devices and the computer. The implementation often consists of a library (on macOS this could be a pre-compiled Framework or a Swift Package) to expose a VISA-compliant API for the programmer to use. Additionally, the implementation might also include drivers to establish a connection between the computer and the device (for example, macOS requires dedicated drivers to communicate with USB-connected devices, but not TCP/IP-connected devices). As one can imagine, developing the library and driver set is a significant amount of work and most programmers use VISA implementations developed by others, such as the National Instruments NI-VISA implementation[@NI-VISA_download] or the Rohde & Schwarz R&S VISA implementation[@GH_RS-VISA]. Since the VISA standard is based on C, these manufacturers expose a C interface that can communicate with a wide range of instrument types using a number of communication protocols.

[MatthieuDartiailh]

It all looks good to me. Thanks for doing the edits.

When you mention drivers in link with VISA implementation it may be worth to talk about kernel drivers (if that applies to MacOS). I know that I often abuse the term driver when developing a bridge for a specific instrument and because of this I had to think twice about what kind of driver you meant. Explicitly mentioning you are talking about kernel drivers may avoid some confusion. This is not a blocker for me so I will close the issue.