LabVIEW API Design

Sorry it's been a while since my last post. I've been traveling, most recently to New Mexico and Colorado for National Instruments Technical Symposia, and a little bit of photography at the Bosque del Apache National Wildlife Refuge.

In my role at National Instruments, I work with many of the driver and toolkit groups that provide LabVIEW APIs for their products. We make decisions about how to best represent our products in easy to learn and easy to use ways.

We're often faced with difficult tradeoffs, and some decisions come down to a "gut feel" by those of us involved. I thought I'd share some of the thought process that goes into making a good API for LabVIEW.

First, a little history. Many of you have attended, or at least heard of, NIWeek—Thousands of users, dozens of presentations, dozens of exhibitors. Did you know that we have a similar NI-only event called "NITech"? This is where NI R&D sets aside three days to have NI engineers present to other other NI engineers. We learn about the latest hardware and software technologies, ongoing research ideas, and good development practices. (And just as at NIWeek, we have fun, too.)

At NITech 2001, I co-presented a session on "Why Good Hardware APIs are Different in LabVIEW, CVI, VB, and VC". Each development environment is different. Some differences are radical, such as LabVIEW's data flow approach vs. text languages that are control flow. Some are as simple as the differences in the online help systems, or the fact that LabVIEW APIs have icons in addition to function names. One conclusion of the presentation is that it's worth it to fine-tune an API for the development environment your users are going to use.

For NITech 2002, I expanded the presentation and called it "Good LabVIEW API Design". I moved it out into the open at NIWeek 2003, where I updated it and called it "Developing High Quality LabVIEW Add-ons". For NIWeek 2004, I updated it once again, and put some spin on the name—"Advanced LabVIEW Design—Usability, Reusability, and Maintainability".

Some of the ideas from those presentations have been incorporated into either the LabVIEW Development Guidelines (available in the LabVIEW help), or the Instrument Driver Development Guidelines. I don't plan to rehash every guideline here, but there are a few ideas from the presentations I'd like to cover from time to time.

At a recent LXI meeting, I was asked whether it made sense for IVI-COM drivers to have LabVIEW VI wrappers around them. That is, instead of having users use the IVI-COM drivers as COM objects directly in LabVIEW, should he create a VI for every property and method in the driver? As with so many things, the answer is, "it depends".

When someone asks, "should I do it this way?", you have to step back and consider the alternatives. There's not necesssarily one perfect way.

A few years ago, one of the well-known instrument vendors developed LabVIEW instrument drivers that consisted of hundreds of VIs. Basically, they had one VI per SCPI command. In a scope API, you called one VI to set coupling, and another to set vertical range, and another for vertical offset. In my book, this was pretty low-level tedious programming. It was also error-prone—some instruments, for example, have a particular order in which you need to send the commands.

I've argued that users really want a higher-level instrument driver—"configure channel" or "configure vertical", not the lower-level components. Let the author of the instrument driver figure out the programming details once, instead of pushing that onto each user. Still, some vendors really like the low-level approach, since it's so powerful and so granular. I think users who want such a low-level approach can use VISA Write to send their own SCPI commands.

Let me restate this to make the tradeoffs clearer. Approach 1 is to have hundreds of simple VIs that consist mostly of VISA Write calls. The driver covers every command the instrument can handle. Approach 2 is to have only a few more complex, higher-level VIs that are commonly used. If you want something more granular, you either modify one of the existing VIs, or you create your own new VI with a VISA Write in it.

I generally lean towards approach 2. The first approach is often overwhelming, and users don't know where to start and how to put the pieces together.

The IVI APIs presented some new challenges. They're more complex, and it's not as simple to insert a VISA Write in your code to tweak a specific setting. So the IVI-C APIs have a few high-level methods, and hundreds of low-level properties. When we designed the first IVI-C APIs for the various instrument classes, we tried to make it so that 80% of typical user applications could be accomplished with only the higher-level methods.

The palette menus for an IVI-C driver in LabVIEW expose the high-level functions. We often also include a single property node to make it easy to get to the rest of the API. Thus, the palettes lead you to the right starting place for the API.

The same idea could map to IVI-COM. Unfortunately, IVI-COM drivers do not always expose a high-level approach in the specific driver interface. Recall from my earlier post about IVI-C and IVI-COM, that the specific interface to an IVI-COM driver doesn't conform to any standard.

So, since I don't know anything about the structure of the API, I can't recommend creating LabVIEW wrappers around it. And because I know that most IVI-COM specific interfaces use a low-level, property-centric approach, I usually actively discourage creating wrapper VIs. The end user is going to have to explore the entire API to figure out how to put it together in an application. Fortunately, the LabVIEW Class Browser (under the View menu, and new in 8.0, I think), makes it somewhat easier to explore IVI-COM drivers.

On the other hand, if you have a well-designed API that has easy-to-use high-level functions, it makes sense to highlight those in the palette menus and lead users to them.

More on API design in future posts.