Page 1 of 17. Getting Started with IVI-COM and C# for the Lambda Genesys
Power Supply. 1. Introduction. This is a step-by-step guide to writing a program to
...
Page 1 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply
1.
Introduction This is a step-by-step guide to writing a program to remotely control the Genesys power supply using the Lambda IVI-COM drivers. This tutorial has instructions and sample code for a Microsoft Visual Studio C# project. It starts by showing how to use the IEEE-488 (IEMD option) connection, and then it shows the small amount of change is needed to use the RS-232/485 and LAN options. The C# code can be used as a guide for writing Visual Basic .NET and C++ programs.
2.
Table of Contents 1.
INTRODUCTION .................................................................1
2.
TABLE OF CONTENTS..........................................................1
3.
REQUIREMENTS .................................................................2
4.
ADDITIONAL HELP..............................................................3
5.
YOUR FIRST IEEE PROGRAM USING C# ................................4
6.
ADDING A COMMUNICATION ERROR HANDLER .................... 12
7.
ADDING AN INSTRUMENT ERROR HANDLER ........................ 13
8.
PROGRAMMING WITH THE RS-232/485 PORT ...................... 16
9.
PROGRAMMING WITH THE LAN PORT ................................. 17
Page 2 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply 3.
Requirements A.
B.
C.
D.
E.
F.
Windows Operating System: This tutorial is written using .NET version 2.0 for Windows XP. Other versions of Windows and .NET are supported. Prior to Microsoft Vista, .NET is freely available as a download. Microsoft Visual Studio: The examples use the Visual Studio 2005 development environment, although other versions are supported. Any language that uses COM or .NET objects should be compatible with the IVI drivers. Prior Experience with C# Programming: This tutorial assumes prior experience with Visual Studio C#. You should know how to create buttons and text boxes, modify their properties and handle button events. You should also know how to build, run and debug your application. IVI Drivers: The Lambda Genesys IVI driver package must be installed. It is available as a download from: http://www.lambda-hp.com/product_html/genesys1u.htm Click on the “Documentation Download Drivers” link to register. Install the file “LambdaGenPS.2.x.x.x.msi” on your computer VISA Drivers: The IVI technology is built upon a layer of hardware drivers called VISA (for “Virtual Instrument Software Architecture”). These drivers are available with the National Instruments Measurement and Automation Explorer (NI-MAX), the Agilent IO Libraries and from other companies. Electrical Interface: almost all personal computers have an RS-232 port or a local area network (LAN) port. If your Genesys power supply uses the RS-485 or IEEE-488 (IEMD option) ports, you will need to install these interface cards into your computer or laptop.
Page 3 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply 4.
Additional Help In addition to this document, a “Getting Started” and language reference Help is installed by the Lambda Genesys IVI driver package. This help file may be opened through the Start menu as shown below:
Below is a sample of the Help file’s contents:
Page 4 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply 5.
Your First IEEE Program Using C# A.
Launch Visual Studio 2005.
On the menu bar, select “File New Project…” See the New Project dialog box open (picture below). Select: Visual C# for Windows, and Windows Application. Ender your project name and folder name. The sample program uses the project name “LAGEN IEMD Simple”. Click “OK”.
The following discussion uses the Visual Studio solution file:
LAGEN IEMD Simple.sln which is included in the Lambda “Getting Started with IVI” download.
Page 5 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply B.
Create the Form with Objects
On the program’s “Form1”, add buttons and text boxes as shown in the example below. The example includes the following objects: InitButton: click this to open the communication port to a Genesys power supply at a specified IEEE address. The example program is fixed for the default IEEE address = 6. SlavTextBox: if you have an RS-485 Multi-drop chain of supplies, enter an RS-485 address (0 to 30) to select a supply. ApplyButton: if you have an RS-485 Multi-drop chain of supplies, click this to select a Multi-drop supply at the textbox’s address. ToggleOutButton: click to toggle the supply’s output ON or OFF. ProgVoltTextBox: enter a new voltage limit setting to be sent to the selected supply when the ProgVoltButton is clicked. ProgVoltButton: click this to send the text box’s program voltage setting to the power supply. MeasVoltTextBox: displays the output voltage read from the power supply after the MeasVoltButton is clicked. MeasVoltButton: click to read the output voltage from the supply. CloseButton: click this to close the connection to the IEEE port. This does not close the program.
Page 6 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply C.
Open the “Add Reference” Dialog
On the Visual Studio menu bar, select “Project Add Reference…”
Page 7 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply
D.
Add the IVI Driver Reference
See the “Add Reference” dialog box open. Select the “COM” tab (not the .NET tab). Scroll down to find: “IVI LambdaGenPS 2.0 Type Library” Click “OK”.
Page 8 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply See the References explorer now shows four new references have been added to the project: -
IviDCPwrLib IviDriverLib LambdaGenPSLib VisaComLib
Page 9 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply E.
Add an Instance of the Driver
In the “Form1” code section: In the code header, add a “using” directive to use the type: using Lambda.LambdaGenPS.Interop;
-
In the “Form1” class, create an instance of the IVI driver. Name the IVI driver “GenIvi” to the with this statement: ILambdaGenPS GenIvi;
Page 10 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply F.
Add a Step to Initialize the IEEE Port
Now you are ready to insert calls to the IVI drivers that will communicate to the Genesys power supply over the IEEE bus. In the “InitButton_Click” event handler, create an instance of the “GenIvi” driver. Call the “GenIvi.Initilize” method. It has four parameters.
private void InitButton_Click( object sender, EventArgs e ) { GenIvi = new LambdaGenPSClass( ); GenIvi.Initialize( "GPIB0::6::INSTR", true, true, "" ); }
The first parameter is “GPIB0::6::INSTR”. This is the VISA name for the connection, which is an IEEE-488 instrument set to address 6 that is connected to an IEEE controller card set to address 0. For more description of the Initialize method, the “F1” key context sensitive help does not work well, because Initialize has several levels of definition. Therefore, it is recommended you navigate directly to the LambdaGenPS help file as shown:
Navigate the Help file index for the entry “Initialize method”. The parameter descriptions are given in detail. Code samples are given for Visual Basic, C# and C++.
Page 11 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply G.
Add a Step to Toggle the Supply’s Output
Now you can use any GenIvi driver to configure and monitor the power supply. Notice, that after typing just a few letters of a method, the Intellisense will open a listbox of allowed properties and methods.
private void ToggleOutButton_Click( object sender, EventArgs e ) { Boolean OutState; OutState = GenIvi.Output.Enabled; GenIvi.Output.Enabled = !OutState; }
As shown in the sample program, there is a “ToggleOutButton” that will read the output ON or OFF state and then send a command to change the state to the opposite.
H.
No Error Handling
Although this is how a complete program is written, there is no error hander. If communication is lost, then the NET exception handler will display an error and then stop the program. See the next section for better error handling.
Page 12 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply 6.
Adding a Communication Error Handler The following discussion uses the Visual Studio solution file:
LAGEN IEMD ErrorHandler.sln The .NET framework handles errors by throwing exceptions. Any driver call should be in a “Try” statement followed by a “Catch” exception handler.
private void ProgVoltButton_Click( object sender, EventArgs e ) { // Clicked the button send a new program voltage value try { GenIvi.Output.VoltageLimit = Double.Parse( ProgVoltTextBox.Text ); } catch ( Exception ex ) { MessageBox.Show( "Program Voltage error: " + ex.Message ); } }
If there is a communication error, using the sample code will produce the following error message box:
Note that the Try and Catch will only report communication errors. They will not report instrument errors, such as trying to program a setting out of range. To catch instrument errors, you must read the SYSTEM:ERROR messages from the supply. See the next section for this solution.
Page 13 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply 7.
Adding an Instrument Error Handler The following discussion uses the Visual Studio solution file:
LAGEN IEMD BetterError.sln The communication error handler, in section 6 above, will only catch errors if the communication link is disconnected in some way. If your program tries to set the power supply to an illegal value, an exception (error) is not created. To determine if the last command was accepted, the program must send the “SYSTEM:ERROR?” query. By enabling the QueryInstrStatus driver property, this query is done automatically after each command and an exception is generated if a command was not accepted.
A.
Create the Scope of COMException
In the code header, add the statement as shown below.
using Lambda.LambdaGenPS.Interop; // For defining an error COMException class just for instruments using System.Runtime.InteropServices; namespace LAGEN_IEMD_BetterError
B.
Configure the Driver for Automatic Error Query
In the Initialize method, the fourth parameter is an option string. Set “QueryInstrStatus” to TRUE to enable automatic queries for instrument errors, as shown below.
GenIvi = new LambdaGenPSClass( ); try { GenIvi.Initialize( "GPIB0::6::INSTR", true, true, "QueryInstrStatus=True"); }
Page 14 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply C.
Handle Instrument Errors
A “try – catch” structure is used to handle cases where the power supply cannot do a command because something is wrong with the command. Although catching “Exception” will handle all errors that the computer can generate, we are only interested in catching errors that the communication interface can generate. Therefore, the program catches “COMException”.
private void ProgVoltButton_Click( object sender, EventArgs e ) { // Clicked the button to send a new program voltage value try { GenIvi.Output.VoltageLimit = Double.Parse( ProgVoltTextBox.Text ); } catch ( COMException ) { Int32 ErrorCode = 0; String ErrorMessage = ""; GenIvi.Utility.ErrorQuery( ref ErrorCode, ref ErrorMessage ); MessageBox.Show( "Program Voltage error: " + ErrorCode + ", " + ErrorMessage ); } }
With this code in your program, if you try to program the voltage setting to any value that the power supply cannot accept, the new setting will be ignored, a COMException will be generated, and a messagebox will appear. For example, say an attempt is made to program a supply to 900 volts. Since this is above the supply’s rating, the command will not be accepted and the messagebox below will appear:
Page 15 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply D.
COMException Discussions
There are several ways to detect errors and handle them. The different choices require some consideration. -
May Slow Down Communication Speed. Initializing a communication port with “QueryInstrStatus=TRUE” may slow down the maximum commands per second to the power supply. This is because of the added traffic to read the SYSTEM:ERROR? message after each command. - For RS-232/485, there is no loss of speed. - For LAN, there is only a small loss because of the Ethernet has to carry more messages. - For IEEE, speed is slightly reduced because of the extra command parsing and bus messages being sent.
-
Disable QueryInstrStatus When Not Needed. You may want to do your program development with “QueryInstrStatus=TRUE” to catch programming errors, and then set it FALSE (or remove the option string) when the program is finished. It is also possible to turn the automatic error reporting ON or OFF in your program. This allows the program to enable this feature only when needed. Use the following example to do this:
GenIvi.DriverOperation.QueryInstrumentStatus = true;
-
// or false
Not All Exceptions are Handled: After the “Catch( COMException)” handler, it is recommended that you add a structure to “Catch( Exception)”. This is because errors occur, such a broken communication link or a runtime error, which are not handled by a COMException event.
Page 16 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply
8.
Programming with the RS-232/485 Port Writing IVI-COM programs for the RS-232/485 ports is the same as the example above for the IEEE interface. The only change is in the initialize option string
A.
RS-232 Initialize
For the IEEE Initialize, the entire connection is defined in the VISA resource name string. For the RS-232/485 port, The VISA name only selects the computer’s COM port (COM1, COM2 etc.). The Genesys address and the Baud rate are specified in the fourth parameter of the call to Initialize. This fourth parameter is an option string. In the example below, the following settings are shown: -
“ASRL1” = the computer’s COM1 port is selected
-
“DriverSetup=” is the required start of the RS-232 string.
-
“SerialAddress=6” is the Genesys front panel address setting. It may be a number from 0 to 30.
-
“BaudRate=9600” is the Genesys front panel serial bits-per-second. It may be 1200, 2400, 4800, 9600 or 19200
private void InitButton_Click( object sender, EventArgs e ) // Clicked the button to initialize the RS-232 connection { GenIvi = new LambdaGenPSClass( ); try { // Open COM1 port to Genesys at address = 6 with Baud Rate = 9600 GenIvi.Initialize( "ASRL1::INSTR", true, true, "DriverSetup=SerialAddress=6,BaudRate=9600" ); } catch ( Exception ex ) { MessageBox.Show( "Initialize error: " + ex.Message ); } }
Page 17 of 17
Getting Started with IVI-COM and C# for the Lambda Genesys Power Supply
9.
Programming with the LAN Port Writing IVI-COM programs for the LAN port is the same as the example above for the IEEE interface. The only change is in the initialize option string.
A.
LAN Initialize with IP Address
Like the IEEE Initialize, the entire LAN connection is defined in the VISA resource name string. Below is an example if the power supply IP address is “12.120.25.243”. private void InitButton_Click( object sender, EventArgs e ) { GenIvi = new LambdaGenPSClass( ); GenIvi.Initialize( "TCPIP::169.254.7.53::INSTR", true, true, "" ); }
B.
LAN Initialize with Hostname
If the LAN power supply is connected through a network server, it’s hostname may be registered by the NBNS or DNS services. In this case, the hostname may be used in the VISA resource name string instead of the IP address. Below is an example if the power supply hostname is “GENH30-25-827”.
private void InitButton_Click( object sender, EventArgs e ) { GenIvi = new LambdaGenPSClass( ); GenIvi.Initialize( "TCPIP::GENH30-25-827::INSTR", true, true, "" ); }
