Archived: Using the Configuration API in NI Switch Executive 2.1

NI does not actively maintain this document.

This content provides support for older products and technology, so you may notice outdated links or obsolete information about operating systems or other relevant products.

Aperçu



NI Switch Executive (NISE) is an intelligent switch management and routing application. With NISE, you gain increased development productivity by interactively configuring switch modules, signal routes and naming channels, external connections and routes. You also increase test code reuse and system performance by integrating NISE with TestStand, LabVIEW, and Measurement Studio. Ultimately, NISE simplifies switch system configuration and management and increases test performance, lowering your cost to test.

In NISE 2.1, the Configuration API provides a programmatic interface to configure your NISE virtual devices. You can use the configuration API to create and edit virtual devices, manage your NISE configurations, and generate reports. In the past, these tasks were only through Measurement & Automation Explorer (MAX).

This application note explains how to use the NISE configuration API via macros in Microsoft Excel.

Prior knowledge of the following items is needed:
· NI Switch Executive
· Creating custom macros in Excel
· Visual Basic for Applications (VBA)
· Object-Oriented Programming

To examine and run the example at the end of each section, download the examples NISE Configuration API - Excel VBA Examples.

Contents

NISE Configuration API

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

Configuration API Object Hierarchy

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

Configuration API programming in Excel

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.

Fig 3: Opening reference window


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.

Creating and Editing Virtual Devices


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.

Dim nise As NiseVirtualDevices
Set nise = New NiseVirtualDevices


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.

Object Class Methods Properties
NiseVirtualDevices

Add

Remove

Save

Count

Item

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.

Dim sevd As NiseVirtualDevice


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

  • Add a unique new NiseVirtualDevice
Set sevd = nise.Add(“NewSEVD”)
  • Get an existing NiseVirtualDevice
Set sevd = nise(“ExistingSEVD”)


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.

NiseVirtualDevice (none) Buses
Channels
Comment
Exclusions
HardWires
IviDevices
Name
RouteGroups
Routes
Version

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:

IviDevices Add
Clear
Remove
Count
Item
Virtual Device
IviDevice (none) Channels
Comment
Name
Virtual Device

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:

sevd.IviDevices.Add "SampleSwitch"
sevd.IviDevices("SampleSwitch").Comment = "This is a sample"

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:

Dim iviDevices As NiseIviDevices
Dim iviDevice As NiseIviDevice

Set iviDevices = sevd.iviDevices
Set iviDevice = iviDevices.Add("SampleSwitch")

iviDevice.Comment = "This is a sample"

Follow similar processes to remove IviDevices from a Virtual Device.

EXAMPLE:

For an example of how to create a new Virtual Device and associate IVI Switch logical names with it from an Excel spreadsheet, see Create_Name_Add_IVI_Devices.xls.

Creating and Editing Channels and Exclusions


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:

Object Class Methods Properties
Channels Add
Clear
Remove
Count
Item
Virtual Device
Channel (none) Comment
Enabled
FormattedName
Hardwire
IviDevice
Name
ReservedForRouting
SignalCharacteristics
VirtualDevice

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.

EXAMPLE:

To see an example of this see Configure_Channels.xls. The VBA code for this example assumes that you have previously run Create_Name_Add_IVI_Devices.xls.

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:

Exclusions Add
Clear
Remove
Count
Item
Virtual Device
Exclusion (none) Comment
Enabled
Mutual
Name
Set1
Set2
Type
VirtualDevice

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

Set chan = sevd.Channels(1)

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

Set chan2 = sevd.Channels(2)
Dim chan3 As NiseChannel
Set chan3 = sevd.Channels(3)


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

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

EXAMPLE:

For an example of how to programmatically configure exclusions, see Configure_Exclusions.xls. This example assumes that you have already run Create_Name_Add_IVI_Devices.xls and Configure_Channels.xls.

Creating and Editing Hardwires


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:

Object Class Methods Properties
Hardwires Add
Clear
Remove
Count
Item
Virtual Device
Hardwire (none) Channels
Comment
Name
ParentBus
VirtualDevice

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.

EXAMPLE:

For an example of how to programmatically configure exclusions, see Configure_Hardwires.xls. This example assumes that you have already run Create_Name_Add_IVI_Devices.xls, Configure_Channels.xls, and Configure_Exclusions.xls

Creating and Editing Routes and Route Groups


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:

Object Class Methods Properties
Routes Add
Clear
Remove
Count
Item
Virtual Device
Route (none) ChannelsInUse
Comment
Constraints
Endpoint1
Endpoint2
MulticonnectMode
Name
ParentRouteGroups
Specification
SpecificationType
VirtualDevice

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

The endpoints in this case are the eighth and ninth channels associated with this particular virtual device.
  • kSpecifiedByFullPath
    The routing engine uses the fully specified path to determine the route.
sevdRoute.SpecificationType = kSpecifiedByFullPath

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

  • kSpecifiedByBoth
If the full path fails to connect, the routing engine uses endpoints to determine the route.


EXAMPLE:

For an example of how to programmatically configure routes, see Configure_Routes.xls. This example assumes that you have already run Create_Name_Add_IVI_Devices.xls, Configure_Channels.xls, Configure_Exclusions.xls, and Configure_Hardwires.xls.

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:

RouteGroups Add
Clear
Remove
Count
Item
Virtual Device
RouteGroup (none) ChildRouteGroups
ChildRoutes
Comment
Name
VirtualDevice

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.

EXAMPLE:

For an example of how to programmatically configure routes, see Configure_Route_Groups.xls. This example assumes that you have already run Create_Name_Add_IVI_Devices.xls, Configure_Channels.xls, Configure_Exclusions.xls, Configure_Hardwires.xls, and Configure_Routes.xls.

Error Checking


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.

Generating Custom Repots


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

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