Using Instruments

VISA supports a variety of instruments, all of which have different features that they support. Currently SwiftVISA only supports USB instruments, however other instrument types will be added in the future. This tutorial will walk you through connecting to a USB instrument and reading/writing values to it.

To start, create a new project named "InstrumentsTutorial".

For this tutorial, we recommend that you have a USB instrument to connect to your computer. If you do not, you can still follow the steps for this tutorial, however your application will not do anything useful.

In order to communicate with our instrument, we must first create an Instrument instance. Read this reference on how to create instruments. After reading the reference, update your ViewController.swift file so it looks like this:

import Cocoa
import SwiftVISA

class ViewController: NSViewController {
    var instrument: Instrument?
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        do {
            let identifier = "/* Replace this comment with your resource identifier */"
            let instrument = try InstrumentManager.default?.makeInstrument(identifier: identifier)
            self.instrument = instrument
        } catch {
            print(error)
        }
        
        if instrument == nil {
            print("Error: Your instrument could not be connected to")
        } else {
            print("Success! Your instrument was connected to")
        }
    }
}

This adds an instrument property to your view controller, and initializes it when viewDidLoad() is called. Run your application. If you are connected to your USB instrument and entered the correct identifier, you should see the text "Success! Your instrument was connected to" outputted in the console. Otherwise, you should see the text "Error: Your instrument could not be connected to".

Now we would like to communicate with our instrument. To do this, we will use the SCPI protocol to send and receive ASCII strings to and from our instrument. To do this there are the read(as:) and write(_:) methods on instrument. Let's ask the instrument for its identity string. To do this, add the following function to ViewController:

func getIdentifier() {
    try? instrument?.write("*IDN?")
    guard let identity = try? instrument?.read(as: String.self) else {
        print("Error writing to or reading from the insrument.")
        return
    }
    print(identity)
}

Then, call this function at the end of your viewDidLoad() method. After adding this code, you should see two errors generated. Why is this happening? Because VISA supports many different types of instruments, each with different communication protocols and features, when you make an instrument from the resource manager, SwiftVISA only knows that it is some type of instrument and only provides access to functionality that is available to every type of instrument. Many instruments are able to communicate by sending and receiving ASCII strings, which is what we are trying to achieve. These instruments are called message based instruments and all adhere to the MessageBasedInstrument protocol. In order to use the functionality of MessageBasedInstrument we must cast our instrument. Change the line

self.instrument = instrument

to

self.instrument = instrument as? MessageBasedInstrument

and the line

var instrument: Instrument?

to

var instrument: MessageBasedInstrument?

Your code should now build without any errors. Run your application and you should see your instrument's identifier printed to the console. Congratulations! You have build your first app using SwiftVISA.