IVI-COM 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:

Creating the IVI-COM driver project
Adding a method
Implementing a method using the Instrument Command Editor
Adding a property that uses an enumerated type
Compiling the driver
Testing the driver
Creating the help file
Designing an IVI-C wrapper
Creating the driver installer

Creating the IVI-COM 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-COM driver project begins with the same steps required to create any Visual Studio project.

To create the Acme4321 driver

Open Visual Studio.
From the File menu, chooseNew Project.
Select IVI-COM Driver from the list of project types.
In the Name box, enter Acme4321.
Click OK.

The New IVI-COM Driver Wizard appears.
On the General Page, specify the following:
- For Instrument manufacturer, enter Acme Corporation.
- For Driver vendor, enter Pacific MindWorks.
- For .NET assembly name prefix, enter MindWorks.
- For **Instrument model **, enter Acme4321.
On the IVI Instrument Classes Page, leave all instrument classes unchecked.
On the LXI Compliance Page, select the None radio button.
On the Features Page, specify the following:
- Enable the IVI-C wrapper check box and set the Prefix to acme.
On the Projects Page, enable only the following:
- Create IVI-COM help project
- Create IVI-COM setup project
- Create IVI-COM unit test
- Create IVI-C unit test
Leave the other check boxes unchecked.
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 methods and properties to your Acme4321 driver.

Adding a Method

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

To add a Configure method with parameters:

Expand the Acme4321 type library node and then expand the Hierarchy node to reveal the methods and properties already added to your driver by Nimbus.

All of the methods and properties in the driver at this point are shown greyed out to indicate that they cannot be modified. This is because all of these methods are inherited from the IVI-defined IIviDriver interface.
Right-click on the Hierarchy node and choose Add Method.

A new method node is added to the hierarchy with a default name, and the node enters edit mode.
Change the method name to Configure.
Right click on the Configure method and choose Add Parameter.

A new parameter is added to the hierarchy with a default name, and the node enters edit mode.
Change the parameter name to NumRecords and hit Enter.

Note that the parameter is added with a default data type of Double.
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.
Add a second parameter by right-clicking the Configure method 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.
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.
Right-click the Configure method and choose Add Parameter.
Type the name TriggerSource followed by a colon followed by string.

Implementing a Method Using the Instrument Command Editor

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 method or property can be implemented by associating an instrument command with the method or property. Nimbus can be instructed to automatically format the runtime value of method 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 method using an instrument command:

From the tree view, select the Configure method under the Hierarchy node.
From the Item Editor, change the Implementation style to be Instrument Command. This enables the Command text box.
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.
Each parameter used in the instrument command can be formatted in a variety of ways. The easiest way to specify the formatting of command parameters is to use the Instrument Command Editor. Invoke the Instrument Command Editor by clicking on the editor icon at the far right of the Command text box.
Select the NumRecords parameter in the Parameters listbox. Nimbus provides a variety of numeric formatting options, such hex or binary, variable field width, and right/left justification with optional padding.

See the topic Using the Instrument Command Editor for detailed information on the various parameter formatting options available.
Next, select the Enabled parameter. The Instrument Command Editor displays a table that allows you to enter an arbitrary string to associate with the two possible values for the boolean parameter — VARIANT_TRUE and VARIANT_FALSE.

Enter ON for the value VARIANT_TRUE and OFF for the value VARIANT_FALSE.
Click OK to close the Instrument Command Editor.
Nimbus generates all of the code needed to format the instrument command according to the settings chosen in the Instrument Command Editor. Several commands are available from the IVI-COM Designer to inspect the generated code.

Right-click on the Configure method and select Go to Forwarding Shim.
Nimbus navigates to the ForwardingShims.nimbus.cpp file. This Nimbus-managed file generates important pre-processing and post-processing code for each method and property in the driver. One of its main tasks is to format the instrument command. For the Configure method, the command formatting is performed by the following section of code in the shim:
```
CString strCmd;
hr = CFormattedIo::Printf(strCmd, pT->GetRoot(), _T("ACQ:CONFIG %d,%{VARIANT_BOOL}s; TRIG:SOUR %$Bs"), NumRecords, Enabled, TriggerSource);
```
A complete discussion of instrument command formatting is provided in the topic Working With Instrument Commands.
Return to the IVI-COM Designer. Right-click on the Configure method and choose Go to Implementation.
Nimbus navigates to the CoAcme4321.nimbus.cpp. The implementation of the Configure method in this file includes only a call to the InstrPrintCommand function. InstrPrintCommand sends the string formatted in the shim to the device.
The implementation of the Configure method 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, we must use the Nimbus Template Library function GetSimulate to determine if the driver is operating in simulation mode. If it is, we will simply return from the function so that the InstrPrintCommand function does not attempt to perform any I/O.

Modify the implementation of Configure to the following:
```
HRESULT hr = S_OK;

if (GetSimulate())
  return hr;

hr = InstrPrintCommand();

return hr;
```

Adding a Property That Uses an Enumerated Type

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

To define a property that uses an enum:

We start by defining the enum itself. From the IVI-COM 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.
For the name, simply enter TriggerSource and hit Enter.

This adds an enum named Acme4321TriggerSourceEnum. By convention, enum names in IVI drivers begin with the driver name (Acme4321, in this case) and end with Enum. For convenience, Nimbus allows you to enter just the short name (TriggerSource) for the enum and Nimbus adds the standard enum prefix and suffix.
We need to add three enum members to the Acme4321TriggerSourceEnum. Right-click on the Acme4321TriggerSourceEnum 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.
Enter Internal for the member name and hit Enter. Notice that Nimbus automatically adds a member with the fully-qualified name Acme4321TriggerSourceInternal.
Right-click again on the Acme4321TriggerSourceEnum and add two more members — External and Software.
We now need to add a property that uses the new enum. Right-click on the Hierarchy node and select Add Property.

Enter SweepSource for the property name followed by a colon followed by TriggerSource. This adds a property named SweepSource of type Acme4321TriggerSourceEnum.
With the SweepSource property selected in the tree view, change the Implementation style in the Item Editor to Instrument Command.
For the Setter command, enter the following command that will be sent to the device when the property value is written:

TRIG:SOUR {value}

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

TRIG:SOUR?

The setter command instructs Nimbus to take the value of the property 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 property, 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 Acme4321TriggerSourceEnum values.
In order to translate the enum values to and from instrument command and respone strings, the Instrument Command Editor is used to map each enum member to a command string.

Click on the editor icon at the right end of the Setter command text box.
The Instrument Command Editor displays a table with the short name of the three enum members we defined — Internal, External, and Software.

In the Instrument Command column of the table, enter the command INT for Internal, EXT for External, and SW for Software.
For the unit tests used later in this walkthrough to work properly, we need to configure the simulation behavior of the SweepSource property.

With the SweepSource property selected in the tree view, click the Simulation tab in the Item Editor and click the Last value set radio button.

Compiling the Driver

To compile the driver:

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.

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.
From Solution Explorer, right click on the solution and choose Configuration Manager. The Configuration Manager Dialog Box appears.
From the Configuration Manager dialog, choose the x86 platform from the Action solution platform combo box.

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
Acme4321CppConsoleApplication	Win32	Checked
Acme4321CsConsoleApplication	x86	Checked
Acme4321CWrapperConsoleApplication	Win32	Checked
Acme4321CWrapperUnitTest	Win32	Checked
Acme4321Driver	Win32	Checked
Acme4321Help	Any CPU	Unchecked
Acme4321Setup	x86	Unchecked
Acme4321UnitTest	x86	Checked

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

Also make sure Debug is selected in the Solution Configurations combo box.
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 projects.

For the Debug build we performed in this step, the output files will be placed in the following folder:
- \<solutionFolder\>\build\Debug\x86
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

From the Test menu, choose Windows and then select Test View.
The Test View window appears docked with Solution Explorer. Change the Group By combo box to Class Name. This will show all of the test classes for the IVI-COM driver. One test class is created for each interface implemented by the IVI-COM driver.
Expand the test class node for the IAcme4321Test class, right-click on the SweepSource property and choose Open Test.
Visual Studio navigates to the C# unit test method for the SweepSource property. The test code for this method sets the value of the property, reads back the value in the instrument, and then compares the value set to the value read to ensure that the property worked. It repeats this sequence for each of the three members of the Acme4321TriggerSourceEnum.
Go to the top of the IAcme4321Test test class. Right-click on the BaseTest base class and click Go To Definition.

The definition of the BaseTest class is opened. This class is the base class for all test classes in the unit test project. It serves a very important purpose — it houses the _Init and _Close methods. The _Init method is executed before each test method. Correspondingly, the _Close is executed after each test method.

These methods are used to perform any required initialization and cleanup. At a minimum, the _Init method must invoke the driver’s Initialize method, while the _Close method must call the driver’s Close method.
Typically, within the _Init, the logicalName 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 logicalName, as we will be operating the driver in simulation mode.

Modify the driverSetup variable to run the driver in simulation mode, as follows:
```
driverSetup = "Simulate=True";
```
From the Build menu, choose Build Acme4321UnitTest.
From the Driver Test View, right-click the Acme4321UnitTest node and choose Run Selection.

The Driver Results View opens in the lower portion of the IDE and shows the status of the unit test methods as they execute. Nimbus generates working code for all of the IVI inherent capabilities.

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:

The .NET interop assembly help (for IntelliSense support in .NET languages, such as C# and Visual Basic.NET).
Microsoft Help Viewer help content (for use with the Visual Studio).
The Help 1.0 (.chm) help file (for standalone viewing and viewing in non-Microsoft IDEs).
The COM type library (for COM-aware environments, such as Visual Basic 6 and many others).

To enter help content for a method:

From the IVI-COM Designer, select the Configure method.
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.
Enter the following in the Summary field:

Configures the device acquisition.
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>

 This method configures the device acquisition. The NumRecords
 parameter controls how many sweeps are performed.


 Call the Configure method before invoking the acquisition with the
 Initiate method.

</body>
</html>
```
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.
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 method. This feature of driver help files is very useful for end users accustomed to direct SCPI (or other messaging protocol) programming.
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.
From Solution Explorer, right-click on the Acme4321Help 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.
From Solution Explorer, right-click on the Acme4321Help project and choose Build. While the build is in progress, the Visual Studio Output window will display the progress of the help project build.
Once the build completes, right-click on the Acme4321Help 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.
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.
Expand the Acme4321 IVI-COM Driver node in the help viewer, then Reference, Driver Hierarchy, and finally IAcme4321. This is where all the dynamically generated help for the main driver interface’s methods, properties and events will appear.
Click on the Configure node in the help viewer table of content. Note that the help documentation entered for the Configure method appears in the generated help file.

Designing an IVI-C wrapper

One of the most powerful features of Nimbus is the ability to develop a fully compliant IVI-C driver using the same code base as the IVI-COM driver. This greatly simplifies driver development and maintenance.

To develop an IVI-C wrapper:

From Solution Explorer, double-click the Driver Settings Editor node.

The Driver Settings Editor appears.
Select the IVI-C tab and make sure that IVI-C wrapper generation is enabled. If not, click the Add button to enable it.
Nimbus automatically generates and manages the required IVI-C files — specifically, the header file (.h), the function panel file (.fp), and the attribute information file (.sub). These files can be examined in the Acme4321Driver folder on disk. If you have LabWindows/CVI installed, you can double-click the .fp file to view the function panels generated for the driver.
With IVI-C wrapper generation enabled, the IVI-C tab in the Driver Designer now becomes available. Select the IVI-C tab to view the hierarchy of IVI-C functions and attributes that correspond to the IVI-COM methods and properties in the driver.
In the tree view of the IVI-C tab, expand the Acme4321 node to locate the Configure function. Note the Info Panel displays the IVI-COM Configure method associated with the IVI-C function.

Click on the IVI-COM Configure method in the Info Panel to quickly navigate to the IVI-COM view.
IVI-C functions and attributes are automatically maintained in terms of IVI-COM methods and properties. When a new IVI-COM method is added to the driver, a corresponding IVI-C function is automatically added with the proper IVI-C types and parameters. Similarly, when an IVI-COM property is added, a new IVI-C attribute is created and associated with the property.

From the IVI-COM Configure method, right-click and choose Rename. Enter ConfigureAcquisition as the new method name.

Right-click on the ConfigureAcquisition method and select Go to IVI-C Function. Note that the IVI-C function has also been renamed to ConfigureAcquisition so that it remains “in-sync” with the IVI-COM method.
From the IVI-C tab, right-click on the ConfigureAcquisition function and click Go to Implementation.

Nimbus opens the auto-generated Acme4321.nimbus.cpp file and navigates to the implementation of the ConfigureAcquisition function. Notice how Nimbus automatically generates all of the necessary code to invoke the underlying IVI-COM method — converting IVI-C parameters to their IVI-COM counterparts and even translating errors in the IVI-COM driver to IVI-C format via the TranslateHRESULT function.

Nimbus also offers the ability to disable the auto-generated implementation of any IVI-C function or attribute. By selecting the Manual radio button in the IVI-C Item Editor Nimbus will add an empty stub implementation of an IVI-C function or attribute to a user-managed Acme4321.cpp file. This allows complete control of the IVI-C implementation.

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 Acme4321Setup project. Nimbus manages the XML files for you as you add functionality to your IVI driver. For instance, as new interfaces and repeated capabilities are added to the driver, Nimbus automatically updates the WiX source XML files to include new registry entries for the COM interfaces and classes.

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

From Solution Explorer, expand the Acme4321Setup 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-COM 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-COM 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.
Double click on Setup.wxs in the Solution Explorer to launch the driver setup designer.
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.
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.
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.
Navigate to a folder on disk with some files and subfolders and click OK.
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.
Right-click on the Acme4321Setup project and choose Build.
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 Acme4321Setup.msi has been created.

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-COM driver, implement, test and document methods and properties. We have also shown how to create and customize an IVI-compliant driver installer. You might want to explore the following topics: