Archived: Using the Configuration API in NI Switch Executive 2.1

Prior to the advent of NISE, extensive switching configurations were typically created and managed in large spreadsheets with programs such as Microsoft Excel. because no specific standard existed, the emaount of details in these documents varied widely. NISE integrated into MAX and created a standard user interface to configure switching configurations. Before NISE 2.1, users were forced to manage their switch system solely in MAX. With 2.1, a configuration API was implemented letting the user access and edit information outside MAX.

The configuration API provides a programmatic interface to configure your NISE virtual devices. Use the configuration API for the following tasks:

• Virtual device creation/editing - Create new virtual devices programmatically and edit existing configurations. The configuration API provides programmatic access to IVI devices, channels, exclusions, hardwires, and buses, routes and route groups.
• Configuration management - Programmatically import, export, delete, and rename NISE configurations.
• Report generation - Create both simple and advanced reports by reading the configuration associated with a specified virtual device.

The following tasks are explained in this application note:

1. Create a new NISE virtual device or open an existing one, and associate IVI Switches with it
2. Configure Channels and Exclusions
3. Configure Hardwires and Buses
4. Create Routes and Route Groups

To create and modify NISE Virtual Devices using the Configuration API, you must be familiar with its Object Hierarchy, as shown below. The object hierarchy can also be found in the NISE Help file under Start » Programs » National Instruments » Switch Executive » Documentation » NI Switch Executive Help » Configuration » Programming .
<p>

Fig 1: NISE Configuration API Tree

To access the NISE Configuration API objects, methods and properties from Excel, you must first include a reference to the NISE Configuration API type library in VBA.

Follow these steps to add the necessary reference:

1 - Open Visual Basic Editor by selecting Tools >> Macro >> Visual Basic Editor as shown in Figure 2

Fig 2 : Opening Visual Basic Editor

2 - Open the References window by selecting Tools >> References as shown in Figure 3.

3 - Select NI Switch Executive Configuration API. In the window that appears, scroll through the list of references until you find NISE Configuration API. Place a check mark in its respective box, and click OK, as shown in Figure 4.

Fig 4: Selecting NISE configuration API

Note:

• If your application will perform NISE actions, such as connecting and disconnecting routes, also place a check next NI Switch Executive.
• If your application also accesses the IVI Configuration Store to get and set information about IVI Switches in your NISE configuration, place a check next to the IVI Configuration Store.

Once you have referenced NISE Configuration API in VBA, you can begin using the Configuration API objects in custom macros.

1- Initialize NiseVirtualDevices Object.

Before you can do anything with any NISE Virtual Device – create a new one, edit an existing one, import configuration from Excel – you must first instantiate a NiseVirtualDevices object in VBA. A NiseVirtualDevices object is a top-level collection of all of the NISE configurations.

With a NiseVirtualDevices collection, nise, instantiated, you can now call different methods on the nise object, as well as get and set properties of the NISE object. Table 1 shows a summary of the methods and properties available for the object class NiseVirtualDevices.

Table 1: NiseVirtualDevices Methods and Properties

2- Create or Open a NiseVirtualDevice Object.

Next you would want to declare an NiseVirtualDevice object and initialize it to create or modify a specific NISE Virtual Device.

Once your NiseVirtualDevice object, sevd, is declared, you can initialize the sevd object in one of two ways:

• Add a unique new NiseVirtualDevice

• Get an existing NiseVirtualDevice

When creating or getting a NiseVirtualDevice, it is imperative that you incorporate error checking. For instance, if you try to name a new Nise VirtualDevice using the name of another Nise Virtual Device, you will get an error. Or if you try to get an existing NiseVirtualDevice, and one cannot be found that matches the name you asked for, you will get an error. (The examples at the end of this document illustrates good error checking habits.)

With a NiseVirtualDevice object, sevd, instantiated, you can now get and set properties of the sevd object. Table 2 lists the methods and properties available for the object class NiseVirtualDevice.

Table 2: NiseVirtualDevice Methods and Properties

3 - Add or Remove IVI Switches to a NiseVirtualDevice object.

Next, perform actions on the IviDevices property of sevd. You can declare a new IviDevices variable, and then access the properties of the IviDevices object. However, you can also skip this step and access the IviDevice properties via the sevd object.

Object classes IviDevices and IviDevice have the associated properties and methods liste in Table 3:

Table 3: IviDevices and IviDevice Methods and Properties To add a new IVI Switch to the list of IviDevices associated with NiseVirtualDevice sevd, call the following lines of code:

The above code will only work if there is an IVI Switch with a logical name that matches SampleSwitch. Otherwise, the code will result in errors.

If you wanted to have specific variables for sevd’s properties IviDevices and IviDevice, the above code can be broken up into the following lines of code:

Follow similar processes to remove IviDevices from a Virtual Device.

1 - Configure Channels

When you associate IVI devices with NISE Virtual Devices, you can create channels aliases, set channels to be reserved for routing, and add comments as needed. The NISE name of your channels will typically follow a format similar to the following:

SampleSwitch1/c2

In this example, “SampleSwitch1” is the IVI Logical Name of the IVI device, and “c2” (column 2) is the IVI channel name. Before programmatically configuring any channel properties, you should be familiar with the channel name format of your IVI device.

With this information, you can modify information about your virtual device’s channels. To modify individual channels, you will need to be familiar with the object classes Channels and Channel, which have the associated properties and methods listed in Table 4:

Table 4: Channels and channel Methods and Properties

To modify a specific channel’s properties, you must first get a reference to that channel from the channels collection of your virtual device, sevd. Using the Item property (a default property any collection) of a NiseChannels collection, you can get a channel reference using one of the following methods:

• Using the channel alias
  If a channel alias has been set for your channel you can use the following method.

Dim sevdChannel As NiseChannel
Set sevdChannel = sevd.Channels(“Arb”)

• Using the NI Switch Executive name

This name would be similar to SampleSwitch1/c2 from above.

Dim sevdChannel As NiseChannel
Set sevdChannel = sevd.Channels(“SampleSwitch1/c2”)

• Using a numeric or one-based index

Dim sevdChannel As NiseChannel
Set sevdChannel = sevd.Channels(10)

Once you have referenced your channel, you can modify properties as desired.



2 - Configure Exclusions
An exclusion is a user-defined connection rule. The NISE routing engine prevents the connection of excluded channels.

The object classes Exclusions and Exclusion have the properties and methods listed in Table 5:

Table 5: NiseVirtualDevice Methods and Properties

There are two types of exclusions, mutual and set exclusions. The following code uses one-base indices to get references for individual items in collections.

1 - Mutual Exclusions

Mutual Exclusions contain a list of channels that should never connect to one another. Mutual exclusions have Type property values of kMutualExclusion.

Dim sevdMutEx As NiseExclusion
Set sevdMutEx = sevd.Exclusion.Add (“NewExclusion”, _ kMutualExclusion)

Once a reference has been created for a mutual exclusion, you can add or remove associated channels to the exclusion. For each exclusion, you can add channels to one of three collections of excluded channels - MutualChannels, Set1Channels, and Set2Channels. Set1Channels and Set2Channels are addressed in the Set Exclusions section that follows. Use the following code to add a channel to the above exclusion sevdMutEx:

Dim chan As NiseChannel

sevdMutEx.MutualChannels.Add chan

2 - Set Exclusions

Set exclusions contain two lists of channels. Channels from the first list should never connect to channels of the second list. Set exclusions have Type property values of kSetExclusion.

Dim sevdSetEx As NiseExclusion
Set sevdSetEx = sevd.Exclusion.Add (“NewExclusion”, _ kSetExclusion)

Once a reference has been created for a set exclusion, you can add or remove associated channels to either Set1Channels or Set2Channels exclusion. To associate two channels with a set exclusion – one channel in Set1 and another in Set2, do something similar to the following exclusion sevdSetEx:

Dim chan2 As NiseChannel

sevdMutEx.Set1Channels.Add chan2
sevdMutEx.Set2Channels.Add chan3

Similar methods can be called to remove channels from exclusion collections.

Configure Hardwires

If you have physical connections between channels on your IVI Device(s) you must account for them in software. This is done by creating hardwires.

The object classes Hardwires and Hardwire have the properties and methods listed Table 6:

Table 6: Hardwires and Hardwire Methods and Properties

Associate every channel that is physically connected to another channel with a specific Hardwire reference. The following code demonstrate one way to add two channels to a Hardwire:

Dim chan4 As NiseChannel
Set chan4 = sevd.Channels(4)
Dim chan5 As NiseChannel
Set chan5 = sevd.Channels(5)

Dim hwire As NiseHardwire
Set hwire = sevd.Hardwires.Add (“NewHardwire”)

hwire.Channels.Add chan4
hwire.Channels.Add chan5

You are not limited to only two channels per hardwire. If you have more than two channels per hardwire, make sure all the connected channels are associated with a single Hardwire reference.

1 - Configure Routes

A route is a user-defined connection from one channel (row, column, COM, NO, and so on) to another. Before we can use NISE functions such as connect and disconnect routes, your routes need to be specified.

The object classes Routes and Route have the properties and methods listed table 7:

Table 7: Routes and Route Methods and Properties

Any route you create will have a name that you reference in NISE functions. Before specifying how you connect from one channel to another, you must first create a route reference:

Dim sevdRoute As NiseRoute
Set sevdRoute = sevd.Routes.Add (“NewRoute”)

With the route reference created, you next need to choose how you will create the route’s specification. SpecificationType specifies the connect method the routing engine uses to determine a route, and has three possible values:

• kSpecifiedByEndpoints
  The routing engine uses endpoints to determine the route. The following code shows how to set this value and how to set the route specification with this specification type:

sevdRoute.SpecificationType = kSpecifiedByEndpoints
sevdRoute.Specification = sevd.Channes(8).Name & _ “->” & sevd.Channels(9).Name

• kSpecifiedByFullPath
  The routing engine uses the fully specified path to determine the route.

sevdRoute.Specification = “[DIO_3->SampleMatrix1/r7->SampleMatrix2/r7->UUT_IO_3]”

• kSpecifiedByBoth

2 - Configure Route Groups

A route group is a user-defined group of routes and/or other route groups associated with a single alias name. You can use route groups to set up simultaneous switching configurations quickly. Route groups also enable NISE to make better decisions about which resources to use when creating a route. Each route group must have a unique name.

The object classes RouteGroups and RouteGroup have the properties and methods listed in Table 8:

Table 8: RouteGroups and RouteGroup Methods and Properties

Just as routes require a route object before channels can be associated with a route, route groups must be created before you can associate child routes or child route groups:

Dim sevdRouteGroup As NiseRouteGroup
Set sevdRouteGroup = sevd.RouteGroups.Add (“ParentRouteGroup”)

With a route group created and initialized, you can now add child routes and child route groups to the current route group.

Adding Routes
If you had previously created a NiseRoute object “PowerToUUT”, and you wanted to add it to a route group “ParentRouteGroup”, you would need to do the following after getting a reference to “ParentRouteGroup”;

Dim sevdChildRoute As NiseRoute
Set sevdChildRoute = sevd.Routes(“PowerToUUT”)

sevdRouteGroup.ChildRoutes.Add sevdChildRoute

Adding Route Groups
Adding a child route group follows a very similar process. After getting a reference to your parent route group, get a reference to the route group you want to add to the parent route group. Then add the reference, as shown in the code below:

Dim sevdChildRouteGroup As NiseRouteGroup
Set sevdChildRouteGroup = sevd.RouteGroups(1)

sevdRouteGroup.ChildRouteGroups.Add sevdChildRouteGroup

The above code assumes that you have previously created at least one other route group.

The examples shown in the previous sections are meant to give you a high level perspective of what it takes to use the configuration API. Examples do not, however, illustrate how to do error checking (they were simplified for readability). When working with the objects provided by the configuration API, it is vital that you check for errors.

ImportFromExcel.xls installs with NISE and is typically found in the C:\Program Files\National Instruments\Switch Executive\Examples\Excel directory. With Generated Report.xls open, open ImportFromExcel.xls, select the Generated Report from the drop down list, and select import. It should programmatically create a new NISE Virtual Device. Look at the VBA code for ImportFromExcel.xls to see methods of error checking such as the use of “On Error” statements.

Instead of using the Generate Report button in NISE, you can create custom reports using the configuration API. GenerateExcelReport.xls, an example of a custom report generator, is installed at C:\Program Files\National Instruments\Switch Executive\Examples\Excel directory.

Related Links

Using Microsoft Excel and NI Switch Executive in Test System Development
Products and Services: NI Switch Executive