Writing New Python-IVI Drivers

Note: this page is under construction

First, you're going to need to download the IVI specification for the type of instrument you have from the IVI foundation. This isn't completely necessary, but there is a lot of information in the spec about the specific functionality of various commands that isn't in the source code. I suppose this should probably be changed, but the spec is freely available so it isn't that big of an issue. You only need to download the spec for your type of device (IviFgen, IviScope, etc.). You're also going to need to download the programming guide for your instrument, if you haven't already.

Now that you know what instrument class your instrument is, you should create a file for it in the proper subdirectory with the proper name. Note that supporting several instruments in the same line is pretty easy, just look at some of the other files for reference. I would highly recommend creating wrappers for all of the instruments in the series even if you don't have any on hand for testing. You also will need to add a line (or several lines) to init.py in the same directory so that the instrument files are loaded automatically with python-ivi and don't need to be loaded individually.

The structure of the individual driver files is quite simple. Take a look at the existing files for reference. Start by adding the header comment and license information. Then add the correct includes. At minimum, you will need to include ivi and the particular instrument class that you need from the parent directory (from .. include ivi). After that, you can specify any constants and/or mappings that the instrument requires. IVI specifies one set of standard configuration values for a lot of functions and this does not necessarily agree with the instrument's firmware, so it's likely you will need to redefine several of these lists as mappings to make writing the code easier. This can be done incrementally while the driver functionality is being implemented.

Next, you need to add the class definition. The name should match the file name, and it will derive from ivi.Driver and the supported subclasses of your instrument. Go over the IVI spec and the programming guide and see what subclasses are supported by seeing which functions are supported by the instrument. There isn't always going to be a 1:1 mapping - there will likely be functions that the instrument does not support but IVI has a wrapper for, and there will likely be functions that IVI does not have a wrapper for but the instrument does support that may be very useful. You should add a subclass if any portion of its functionality is supported by the instrument.

After that, you need to define the functions common to all IVI drivers. You can just copy everything from init to utility_unlock_object from an existing driver and then update everything for your instrument. Generally all this code will be very similar. Take a look at some of the existing drivers for reference. Very important: any super() calls must be updated so that the class name matches (requirement for Python 2). You should also remove all of the initialization in init that you don't need - the bare minimum is _instrument_id and all of the _identity values. For some instruments, you're going to need to specify channel counts as well as an _init_channels or _init_outputs method. Note that if one of these methods is needed, it cannot be empty as it must at least have a call to super so that all of the proper init methods are called. At this point, you can test the connection to the equipment to make sure it is communicating and reading out the ID properly.

Testing you code is actually pretty straightforward; you don't need to re-install the library to test it; just make sure to instantiate it while you're running in the same directory as the ivi folder (not inside). I recommend ipython for testing. Unfortulatey, the auto reload doesn't work very well for python-ivi, so you'll need to restart ipython every time you change something. However, it supports history and autocompletion, so after you import IVI once, you can just type 'imp' and hit the up arrow until 'import ivi' shows up.

Test the interface and identity query by instantiating your driver and connecting to the instrument by running something like this in ipython:

import ivi
mso = ivi.agilent.agilentMSO7104A("TCPIP0::192.168.1.104::INSTR")
mso.identity.instrument_model

If everything is working, the instrument's model number will be displayed. Once you get this working, you can move on to implementing the actual functionality.

Start by copying in all of the bare function definitions from the driver file. Copy all of the get and _set function definitions from the ivi driver file for the Base class and all of the subclasses that you are implementing. You also need any methods whose only implementation is 'pass'. The ones that call other methods can generally be left out as the default implementation should be fine. You may also want to copy some of the instance variable initializations from the __init_ method as well if you need different defaults. These should be added to the init method you created earlier for your instrument.

Finally, you need to go write python code for all of the functions that the instrument supports. Take a look at some _get/_set pairs for some of the existing drivers to see the format. It's rather straightforward but quite tedious.