viFindRsrc and the Instrument Discovery Service

If you are a VISA programmer, or you use applications developed with the VISA I/O library, you use the viFindRsrc and viFindNext functions to discover and list instruments in your test system. These functions query the Keysight Instrument Discovery Service to determine what resources are available to the system. The Discovery Service maintains up-to-date information on available instruments on most interfaces, including information on many LAN instruments: Because this information is kept up to date by the Discovery Service, viFindRsrc and viFindNext do not independently discover or verify instruments.

By default, the VISA functions viFindRsrc and viFindNext do not return every device found by the Discovery Service. LAN instruments that have been auto-discovered are not returned by default. This is because:

In certain environments, a LAN subnet may have a very large number of connected instruments. Not all of these instruments are relevant to any individual user's application. These instruments can create confusion and performance issues in some applications that assume all instrument returned by viFindRsrc/viFindNext are of interest.
Prior to Keysight IO Libraries Suite 17.0, IO Libraries Suite did not auto-discover LAN instruments. Therefore, the presence of these instruments in the viFindRsrc/viFindNext results may cause backward compatibility problems for some applications.

Manually-Added Instruments and Auto-Discovered Instruments

Each instrument in your configuration is either manually-added or auto-discovered. If the instrument was discovered by the Keysight Instrument Discovery Service and automatically displayed in Instruments View's instruments list, (either during auto-scan or as a result of clicking Rescan All ( in Windows, in Linux)), it is an auto-discovered instrument. If the instrument was added to configuration by specifying its properties (e.g., LAN IP address), then it is a manually-added instrument.

Behavior of viFindRsrc, viFindNext, and viOpen

The scanning algorithm employed by viFindRsrc and viFindNext considers whether an instrument is manually added or auto-discovered to determine whether to scan for the instrument or to assume its presence. In addition, viOpen uses this property to decide whether to verify the presence of the instrument. These algorithms also consider the type of interface that the instrument is on.

LAN instruments on a local subnet are discovered but may not be automatically added to the My Instruments list. These LAN instruments are not returned by viFindRsrc. They must be manually added to the My Instruments list.

Once a user manually adds a LAN instrument to the My Instruments list, either by entering its IP address or by selecting it from the local subnet list, it will be returned by viFindRsrc.

Other types of instruments, such as GPIB and USB, are considered auto-discovered and automatically appear in the My Instruments list. These instruments are always returned by viFindRsrc.

However, if VI_KTATTR_RETURN_ALL is set to VI_TRUE, then all instruments known to the Discovery Service are returned by vifindRsrc. To set this attribute, call:

viSetAttribute( drmSession, VI_KTATTR_RETURN_ALL, VI_TRUE );

When VI_KTATTR_RETURN_ALL is VI_FALSE (the default):

For auto-discovered instruments, viFindRsrc and viFindNext scan for each instrument at the instrument's address. If the instrument is present and turned on, it will be returned by viFindRsrc/viFindNext. If the instrument is missing or nonfunctional (e.g., turned off), it will not be returned.

For manually-added instruments, viFindRsrc and viFindNext assume the presence of an instrument at that address. The instrument will be included in the returned values from viFindRsrc/viFindNext regardless of whether the instrument is actually present.

If an instrument has multiple connections (for example, multiple LAN addresses, or connections via several interfaces, such as LAN and GPIB), viFindRsrc and viFindNext return all connections (addresses) of that instrument.

USB instrument address formats are different for the following VISA application:

32 bit VISA application: decimal format of USB VendorID and ProductID

64 bit VISA application: hex format of USB VendorID and ProductID

When an instrument is discovered, whether it is configured for an anonymous connection or not, viFindRsrc will exclude any credentials from the returned VISA address. For example, if an instrument is configured with the credential "Ca" and has an actual VISA address of TCPIP0::ca@10.2.2.2::hislip0::INSTR, viFindRsrc will still return TCPIP0::10.2.2.2::hislip0::INSTR.

viOpen behavior:

For auto-discovered instruments, viOpen verifies the presence of the instrument on which you are trying to open a session.

For manually-added instruments on all interfaces, viOpen does not verify the presence of the instrument. If the device is not present or not turned on, you will not discover this until you attempt to communicate with the instrument.

viOpen may fail if the instrument certificate is invalid, so you should connect to the SIC Expert application to view and update the certificate details.

Auto-Discover and Auto-Scan

Most GPIB interfaces have auto-discover and auto-scan properties, which you can set in Connection Expert. Both of these settings default to on. (Remote GPIB and 488.2 GPIB interfaces do not support auto-scan.)

If auto-discover is off, the Discovery Service will not find new instruments on this interface, so new instruments will not be returned by viFindRsrc/viFindNext.

If auto-scan is off, the Discovery Service will only find new instruments when the PC starts up or when you click Rescan All ( in Windows, in Linux)in the instruments list. Therefore, viFindRsrc/viFindNext will not return instruments that have been added to the system since the last startup or rescan. Additionally, instruments that are no longer available will still be returned by viFindRsrc/viFindNext, if they were available at the time of the last startup or rescan.

The IO Libraries Suite auto-scan feature can cause certain instruments on GPIB interfaces to go into remote mode every 15 seconds. When the Discovery Service detects an affected instrument model, it automatically turns off auto-scan for the affected GPIB interface. For detailed information on this issue, see Instrument Discovery and Identification on Specific Interface Types.

On LAN (TCPIP) interfaces:

Instruments on the local subnet that conform to LXI 1.3 or later will be auto-discovered when they come online and automatically removed from the system configuration when they go offline. Therefore, if VI_KTATTR_RETURN_ALL is true, then viFindRsrc/viFindNext will return these instruments if they are available and will not return them if they are offline. (As described above, if VI_KTATTR_RETURN_ALL is false – the default – then viFindRsrc/viFindNext will not return auto-discovered LAN instruments.)

Instruments on the local subnet that conform to LXI 1.2 will be discovered when the PC starts up and when you click the Rescan All ( in Windows, in Linux)button. Therefore, viFindRsrc/viFindNext will not return such instruments if they have been added to the system since the last startup or rescan. Additionally, LXI 1.2 instruments that are no longer available will still be returned by viFindRsrc/viFindNext, if they were available at the time of the last startup or rescan, and if VI_KTATTR_RETURN_ALL is true.

Other LAN instruments may need to be manually added in Connection Expert before they can be returned by viFindRsrc/viFindNext.

To set Auto-discovery and Auto-Scan, select the interface (either GPIB or LAN), click , Settings, then the Auto Discovery tab. If necessary, select either the GPIB or the LAN tab.

About the Discovery Service and the defaultRM Session

viFindRsrc is called using a defaultRM session. The list of devices is cached in the defaultRM object and is not updated once it has been read. Therefore, even though the Discovery Service keeps the list up to date, VISA won’t know about changes until every — not just the current — defaultRM session is closed and another defaultRM session is opened. This means that if you call viFindRsrc using a session that has been open for a while, the information returned may be stale.

Additional notes: