IVI-C Driver Walkthrough

In this walkthrough, you will create a simple IVI-COM driver along with a help file and installer.

This walkthrough will consist of the eight main steps:

1. Creating the IVI-C driver project
2. Adding a function
3. Implementing a function using an instrument command
4. Adding an attribute that uses an enumerated type
5. Compiling the driver
6. Testing the driver
7. Creating the help file
8. Creating the driver installer

Creating the IVI-C Driver Project

We’ll create a new driver project called Acme4321. Nimbus is completely integrated with Microsoft Visual Studio, so the process of creating an IVI-C driver project begins with the same steps required to create any Visual Studio project.

To create the Acme4321 driver

1. Open Visual Studio.

2. From the File menu, chooseNew Project.

3. Select IVI-C Driver from the list of project types.

4. In the Name box, enter Acme4321.

5. Click OK.

   The New IVI-C Driver Wizard appears.

6. On the General Page, specify the following:

   • For Prefix, enter acme4321.
   • For Instrument manufacturer, enter Acme Corporation.
   • For Driver vendor, enter Pacific MindWorks.
   • For Instrument model, enter Acme4321.
   • For Instrument class, leave the selection at none.

7. On the Instrument I/O Page, specify the following:

   • Check the Enable VISA-based I/O check box.
   • Check the Generate direct I/O functions and attributes check box.
   • Leave all other settings on this page at their default values.

8. On the LXI Compliance Page, leave the Conformance combo box at its default value of none.

9. On the Projects Page, enable the following:

   • Create unit test
   • Create help project
   • Create setup project
   • Create C++ application

10. Click Finish to create the project.

    The Driver Designer should automatically open. If it does not, then double-click the Driver Designer node in Solution Explorer. The project has been created and you are now ready to add some functions and properties to your Acme4321 driver.

Adding a Function

When you add new functionality to a driver, you organize the functions and attributes in a hierarchy, grouping them in interfaces.

To add a Configure function with parameters:

1. Expand the Acme4321 root node to reveal the functions and attributes already added to your driver by Nimbus.

   All of the functions and attributes in the driver at this point are shown greyed out to indicate that they cannot be modified. This is because all of these functions and attributes are part of the IVI-defined inherent capabilities.

   Notice that there is an Instrument Specific node that is empty. This is the portion of the hierarchy we will use to add the functionality of our driver that is specific to our instrument.

2. Right-click on the Instrument Specific node and choose Add Function.

   A new function node is added to the hierarchy with a default name, and the node enters edit mode.

3. Change the function name to Configure.

4. Note that a parameter named Vi of type ViSession is automatically added to the function as the first parameter. All IVI-C driver functions must include a ViSession parameter to represent the driver session. Nimbus automatically adds this parameter and makes it read-only so that it cannot mistakently be modified.

5. Right click on the Configure function and choose Add Parameter.

   A new parameter is added to the function with a default name, and the node enters edit mode.

6. Change the parameter name to NumRecords and hit Enter.

   Note that the parameter is added with a default data type of ViReal64.

7. Change the data type of the NumRecords parameter using the Item Editor. This is done by right-clicking on the Type text box and choosing Int32 from the context menu of available types.

8. Add a second parameter by right-clicking the Configure function again, choosing Add Parameter.

   For the parameter name, enter Enabled and hit Enter. Note that Nimbus automatically infers the desired Boolean parameter type from the name of the parameter.

9. Finally, we’ll add a third parameter and enter both the parameter name and data type by typing directly into the node label while it is in edit mode.

10. Right-click the Configure function and choose Add Parameter.

11. Type the name TriggerSource followed by a colon followed by string.

Implementing a function using an instrument command

Although Nimbus supports developing drivers for any type of instrument — register-based, message-based, or custom I/O devices, special features are provided that make message-based IVI driver development particularly efficient. Every function or attribute can be implemented by associating an instrument command with the function or attribute. Nimbus can be instructed to automatically format the runtime value of function parameters into the instrument command string. The section of the walkthrough will present some of the automatic instrument command formatting features provided by Nimbus.

To implement a function using an instrument command:

1. From the tree view, select the Configure function under the Instrument Specific node.

2. From the Item Editor, change the Implementation style to be Instrument command. This enables the Command text box.

3. In the Command text box, enter the following command:

   ACQ:CONFIG {NumRecords},{Enabled}; TRIG:SOUR {TriggerSource}

   The above command uses parameter tags enclosed in curly braces ({ }) to insert the runtime value of parameters into the command. Notice that when you type a left curly brace ({), Nimbus presents an IntelliSense context menu from which you can select the desired parameter to use in the instrument command.

4. Nimbus generates all of the code needed to format the instrument command and send the result to the instrument. Several commands are available from the IVI-C Designer to inspect the generated code.

   Right-click on the Configure function and select Go to Implementation.

5. Nimbus navigates to the acme4321.cpp file. For the Configure function, the command is formatted and sent by the following section of code in the function implementation:

   status = viPrintf(GetVisaSession(Vi), "ACQ:CONFIG %ld,%s; TRIG:SOUR %s\n", NumRecords, strEnabled.c_str(), TriggerSource);

   A complete discussion of instrument command formatting is provided in the topic Working With Instrument Commands.

6. The implementation of the Configure function needs to be modified so that it works in simulation mode — that is, when no device is physically available. (This is important for steps later in this walkthrough.) For this, Nimbus has already created an if-statement block of code designated for just this purpose. It currently returns the error IVIC_ERROR_FUNCTION_NOT_SUPPORTED and it marked with a TODO block. If simulation is enabled, then we will simply return from the function so that the viPrintf function does not attempt to perform any I/O.

   Modify the implementation of Configure to the following:

   if (SimulationEnabled(Vi))
   {
       return VI_SUCCESS;
   }

Adding an attribute that uses an enumerated type

Enumerated types are commonly used as attribute types and parameter types. Nimbus provides special support for defining enums and using them in function and attribute instrument commands.

To define a attribute that uses an enum:

1. We start by defining the enum itself. From the IVI-C Designer, right-click on the Enums node and choose Add Enum.

   A new enum node is added with a default name and the node enters edit mode.

2. For the name, simply enter TriggerSource and hit Enter.

   Creating an enum in an IVI-C driver does not physically create an enumerated type anywhere in the driver. It simply serves as a pseudo type which can be used to group together a set of related constant values. The constant values are defined when we create enum members for this enum, as we will do shortly.

3. We need to add three enum members to the TriggerSource. Right-click on the TriggerSource and choose Add Enum Member.

   A new enum member is added to the enum with a default name and the enum member enters edit mode.

4. Enter Internal for the member name and hit Enter.

5. Right-click again on the TriggerSource and add two more members — External and Software.

6. We now need to add an attribute that uses the new enum. Right-click on the Instrument Specific node and select Add Attribute.

   Enter SweepSource for the attribute name followed by a colon followed by TriggerSource. This adds a attribute named SweepSource of type TriggerSource.

7. With the SweepSource attribute selected in the tree view, change the Implementation style in the Item Editor to Instrument command.

8. For the Setter command, enter the following command that will be sent to the device when the attribute value is written:

   TRIG:SOUR {value}

   For the Getter command, enter the following query that will be sent to the device when the attribute value is read:

   TRIG:SOUR?

   The setter command instructs Nimbus to take the value of the attribute and place it in the command in place of the {value} parameter tag. For reads from the instrument, first the Getter command is sent, and then Nimbus reads from the device and parses the response according to the Getter response specified. For the SweepSource attribute, leave the Getter response set to {value}, which simply means that the device responds by sending a value that Nimbus will parse into one of the allowed TriggerSource values.

9. In order to translate the enum values to and from instrument command and respone strings, the Enum Member Editor is used to map each enum member to a command string.

   Select each of the three enum members and enter for the Command textbox INT for Internal, EXT for External, and SW for Software. These strings are stored within a special map managed by Nimbus in the driver project’s Enums.h file.

Compiling the Driver

To compile the driver:

1. The first step in compiling a Nimbus driver is to properly setting the build configuration. This typicall has to be done once the first time a new driver is compiled. However, adding, removing, or even uloading projects from a solution can cause the Configuration Manager settings to get modified.

   Important

   Adding, removing, or unloading projects from a driver solution can modify the Configuration Manager settings. The tasks explained here may need to be performed again after such operations.

2. From Solution Explorer, right click on the solution and choose Configuration Manager. The Configuration Manager Dialog Box appears.

3. From the Configuration Manager dialog, choose the x86 platform from the Action solution platform combo box.

4. Make sure that the Platform column setting and Build column setting for each project is set according to the table below. (Note the list of projects that appears depends upon the driver options chosen.)

   Project	Platform	Build
   Acme4321CDriver	Win32	Checked
   Acme4321CDriverConsoleApplication	Win32	Checked
   Acme4321CDriverUnitTest	Win32	Checked
   Acme4321CDriverHelp	Any CPU	Unchecked
   Acme4321CDriverSetup	x86	Unchecked

5. Make sure x86 is selected in the Solution Platforms combo box.

   Also make sure Debug is selected in the Solution Configurations combo box.

6. From the Build menu, select Build Solution.

   This will perform a 32-bit compilation of the driver project, the unit test projects, and the client application project.

   For the Debug build we performed in this step, the output files will be placed in the following folder:

   • \<build\>\Debug\x86

7. The driver is now ready to use in an application. The build process registers the driver with the IVI Configuration Store. You can use a 3rd-party IVI browsers, such as Measurement Automation Explorer^® (MAX) from National Instruments^®.

Testing the driver

With the driver compiled and ready to use, the next task is to use the Visual Studio integrated unit testing tools.

To run the driver unit tests

1. From the Test menu, choose Windows and then select Test Explorer. The Test Explorer window appears.

2. Within Test Explorer Right-click on the ATTR_SWEEPSOURCE attribute and choose Open Test.

3. Visual Studio navigates to the C++ unit test function for the SweepSource attribute. The test code for this function sets the value of the attribute, reads back the value in the instrument, and then compares the value set to the value read to ensure that the attribute worked. It repeats this sequence for each of the three members of the TriggerSource.

4. Go to the top of the UnitTest.cpp file within the unit test project.

   The top of the unit test contains two important functions delineated by the TEST_METHOD_INITIALIZE and TEST_METHOD_CLEANUP functions. These functions are called before and after (respectively) each TEST_METHOD in the unit test. These functions used to perform any required initialization and cleanup. At a minimum, the TEST_METHOD_INITIALIZE function must invoke the driver’s InitWithOptions function, while the TEST_METHOD_CLEANUP function must call the driver’s close function.

5. Typically, within the TEST_METHOD_INITIALIZE, the g_resourceDesc variable is set to a valid I/O resource descriptor or to a valid logical name configured in the IVI Configuration Store. For purposes of this walkthrough, we need not set the g_resourceDesc, as we will be operating the driver in simulation mode.

   Modify the OptionsString parameter in the call to InitWithOptions to run the driver in simulation mode, as follows:

   auto status = acme4321_InitWithOptions(g_resourceDesc, VI_TRUE, VI_TRUE, "QueryInstrStatus=True, Simulate=True, DriverSetup= ", &g_session);

6. From the Build menu, choose Build Acme4321CDriverUnitTest.

7. From the Test Explorer, right-click the ATTR_SWEEPSOURCE node and choose Run Selection.

   The test succeeds because automatically Nimbus generates code for the driver in simulation mode that remembers the last value set and returns that value when queried. This behavior is what most users would expect for IVI-C driver attributes operating in simulation mode. Additionally, this same test works equally well in live mode when communicating with an instrument because the instrument should also be storing the state of each instrument variable and returning that state when queried.

Creating the Help File

Nimbus provides powerful and flexible features for creating driver help files. Help file templates allow complete control over help file styling and content so that custom branding and other styling requirements can easily be incorporated.

One of the most compelling aspects of the Nimbus help editing features is that they provide a single place to enter help content that is used in many places. This greatly simplifies driver documentation management. For instance, the Summary field in the Help Editor is used in all of the following places:

• Microsoft Help Viewer help content (for use with Visual Studio).
• The Help 1.0 (.chm) help file (for standalone viewing and viewing in non-Microsoft IDEs).
• The IVI-C function panel file (.fp)
• The IVI-C attribute information file (.sub)

To enter help content for a function:

1. From the IVI-C Designer, select the Configure function.

2. Click on the Help tab at the bottom of the Item Editor to bring up the Help Editor.

   The Summary tab (listed at the top of the Item Editor) should be the active tab.

3. Enter the following in the Summary field:

   Configures the device acquisition.

4. Click on the Remarks tab. This will activate the standard Visual Studio HTML editor. The HTML editor allows use of any arbitrary HTML formatting tags.

   In the HTML editor for the Remarks field, enter the following within the \<body\> tag that’s already been provided:

   <html>
   <body>
   <p>
       This function configures the device acquisition.  The <i>NumRecords</i>
       parameter controls how many sweeps are performed.
   </p>
   <p>
       Call the <b>Configure</b> function before invoking the acquisition with the
       <b>Initiate</b> function.
   </p>
   </body>
   </html>

   Important

   Even though the built-in Visual Studio HTML editor is used for editing HTML content, the contents of these fields must be XHTML, which is a stricter form of HTML. Among other things, this means that all HTML tags must be closed just like XML tags are. For example, instead of using \<hr\> to insert a horizontal separator, you must use \<hr/\> or \<hr\>\</hr\>. If any XHTML rules are violated, the driver help previewer will display an error, and the help project will fail to build.

   Help content is required to be XHTML in order to be used by the Microsoft Help Viewer that’s used by Visual Studio.

5. Click on the Preview tab in the Help Editor to instantly view the newly entered help content. The formatted HTML text entered for the Remarks field is rendered just as it will appear in the compiled driver help file.

   Note that Nimbus automatically includes an Instrument Command section on the help page for the function. This feature of driver help files is very useful for end users accustomed to direct SCPI (or other messaging protocol) programming.

6. The layout and styling of the driver help file is completely customizable via Nimbus Help Templates. Nimbus ships with one pre-built help template that mimics the classic format of MSDN help.

   From Solution Explorer, right-click on the Acme4321Help project and choose Properties. The Template page shows a preview of each type of help page for the currently active help template. You can easily choose another help template from the Available templates combo box.

   See the topic Working with Help Templates for a complete discussion of driver help file customization using templates.

7. From Solution Explorer, right-click on the Acme4321CDriverHelp project and choose Properties.

   For the purpose of this walkthrough, check the Help 1.x (.chm) help format, but leave the other options cleared. The options on this page are described in detailed here.

8. From Solution Explorer, right-click on the Acme4321CDriverHelp project and choose Build. While the build is in progress, the Visual Studio Output window will display the progress of the help project build.

9. Once the build completes, right-click on the Acme4321CDriverHelp project in the Solution Explorer and select View Help 1.x (.chm). This will open the newly built driver help file in the Help 1.x viewer.

10. In the help viewer, click on the Contents tab and then expand the Getting Started node. Note that several boilerplate help pages have been included in the driver’s help file, which are described in more detail here.

11. Expand the Acme4321 IVI-C Driver node in the help viewer, then Reference, and finally Hierarchy. This is where all of the dynamically generated help for the driver functions and properties will appear.

12. Click on the Configure node in the help viewer table of content. Note that the help documentation entered for the Configure function appears in the generated help file.

Creating the driver installer

The final task in developing a Nimbus IVI driver is creating the driver installer. The IVI specifications impose a number of detailed requirements for IVI driver installers. Nimbus uses Windows Installer XML (WiX) as the underlying technology for building driver installers. The WiX toolset is in widespread use, expecially within Microsoft where it is used to produce the installers for such large-scale projects as Microsoft Office, Visual Studio, and SQL Server.

WiX installers consist of a series of XML files that get compiled in the Acme4321CDriverSetup project. Nimbus manages the XML files for you as you add functionality to your IVI driver.

Nimbus also provides a powerful and easy-to-use graphical designer for customizing a driver installer, such as for installing example programs or other dependent files outside the control of Nimbus.

To customize the driver installer

1. From Solution Explorer, expand the Acme4321CDriverSetup project node. Note that several files have already been added to this project:

   • Images*.*

     This folder contains icon and graphic files that are used by the driver installer.

   • Internal*.wx?

     This folder contains WiX source files that define the required folder structure required for IVI-C driver installers by the IVI standards, as well as localizable string resources used on driver installer screens.

   • EULA.rtf

     The contents of this license agreement file will be displayed on a driver installer screen when the driver installer is run on end-user machines. You must not remove this file. The EULA.rtf file is essentially empty, providing a place for you to enter the specifics of your driver’s end-user license agreement.

   • Readme.txt

     A starter template for a standard IVI-C driver readme file.

   • Setup.wxs

     This WiX source file defines the overall layout of the driver installer, and is the file that’s modified by the integrated driver setup designer.

2. Double click on Setup.wxs in the Solution Explorer to launch the driver setup designer.

3. The Setup Designer shows the standard IVI folders present on any system with the IVI Shared Components. These standard folders are shown in gray to indicate that they cannot be modified by a driver installer. The Setup Designer also shows the Acme4321 driver folders under which the driver files will be deployed on the target machine.

4. Navigate to a folder on disk with some files and subfolders and click OK. A dialog box titled Select Files to Add will be displayed. Check and uncheck files to be included in the driver installer as desired. Press OK when you’re done.

   Note that the selected folder, its files, and any subfolders and files chosen are now displayed in the Setup Designer tree view. This folder structure will be created on the end-user system by the driver installer.

5. From the Setup Designer tree view, right-click the Examples folder and choose Add and then select Add Folder…

   The standard Windows Add Folder Dialog appears.

6. Navigate to a folder on disk with some files and subfolders and click OK.

7. Return to the Setup.wxs file and note how Nimbus has automatically added the appropriate WiX entries to integrate the selected items with the driver installer.

8. Right-click on the Acme4321CDriverSetup project and choose Build.

9. When the build has completed, navigate to the \<solutionFolder\>\build\debug\x86 directory below the driver solution folder and note that an .msi installer package named Acme4321.msi has been created.

   Caution

   Never run a driver installer on the same machine on which the driver was compiled. The registry entries associated with the driver could become corrupt. IVI-COM driver installers must ALWAYS be tested on a separate test machine.

Next steps

This walkthrough has illustrated how to create a simple IVI-C driver, implement, test and document functions and properties. We have also shown how to create and customize an IVI-compliant driver installer. You might want to explore the following topics:

• Understanding the Nimbus User Interface
• Adding Functionality to an IVI-C Driver
• Adding Support for Multiple Instrument Models
• Implementing Driver Functions and Attributes
• Developing an IVI-C Driver