Home

NI-488.2 User Manual - National Instruments

1. National Instruments 5 3 NI I O Trace Utility This chapter introduces you to NI I O Trace a utility that monitors and records multiple National Instruments APIs for example NI 488 2 and NI VISA Overview NI I O Trace monitors records and displays the NI 488 2 calls made from NI 488 2 applications You can use it to troubleshoot errors in your application and to verify the communication with your GPIB instrument NI I O Trace shows which NI 488 2 calls are being used to communicate with your instrument If your application is not working properly you can use NI I O Trace to search for failed NI 488 2 calls Starting NI I O Trace Windows To start NI I O Trace complete the following steps 1 Start MAX as described in Chapter 2 Measurement amp Automation Explorer Windows 2 From the menu bar select Tools NI I O Trace OS X and Linux To start NI I O Trace complete the following steps 1 Start GPIB Explorer as described in Chapter 3 GPIB Explorer OS X and Linux 2 From the menu bar select Tools NI I O Trace National Instruments 6 1 Chapter 6 NI I O Trace Utility Monitoring API Calls with NI I O Trace To display NI 488 2 API calls as they are made do the following 1 On the NII O Trace toolbar click the green arrow button to start a capture 2 Start the NI 488 2 application you want to monitor NI I O Trace records and displays all NI 488 2 calls as shown in Figure 6 1
2. Fees GPIB Digital Voltometer Another GPIB Printer Configuration Requirements To achieve the high data transfer rate that the GPIB was designed for you must limit the number of devices on the bus and the physical distance between devices The following restrictions are typical A maximum separation of 4 m between any two devices and an average separation of 2 m over the entire bus A maximum total cable length of 20 m A maximum of 15 devices or controllers connected to each bus with at least two thirds powered on For high speed HS488 operation the following restrictions apply e All devices in the system must be powered on e Cable lengths must be as short as possible with up to a maximum of 15 m of cable for each system e There must be at least one equivalent device load per meter of cable If you want to exceed these limitations you can use a bus extender to increase the cable length or a bus expander to increase the number of device loads You can order bus extenders and expanders from National Instruments 1 2 ni com Measurement amp Automation Explorer Windows This chapter describes Measurement amp Automation Explorer MAX an interactive utility you can use with the NI 488 2 software for Windows OS X and Linux NI 488 2 for OS X and NI 488 2 for Linux have a similar program called GPIB Explorer For more information refer to Chapter 3
3. Device driver software installed within the operating system A message that signals the end of a data string END is sent by asserting the GPIB End or Identify EOD line with the last data byte A GPIB line that signals either the last byte of a data message END or the parallel poll Identify IDY message A 7 or 8 bit end of string character that is sent as the last byte of a data message End of transmission The Event Status bit Part of the IEEE 488 2 defined status byte which is received from a device responding to a serial poll First in first out Group Execute Trigger The GPIB command used to trigger a device or internal function of an addressed Listener General Purpose Interface Bus This is the common name for the communications interface system defined in ANSI IEEE Standard 488 1 2003 and ANSI IEEE Standard 488 2 1992 The address of a device on the GPIB composed of a primary address MLA and MTA and perhaps a secondary address MSA The GPIB board has both a GPIB address and an I O address National Instruments G 3 Glossary GPIB board GTL H handshake hex high level function HS488 VO T O address ibcnt G 4 ni com Refers to the National Instruments family of GPIB interfaces Go To Local The GPIB command used to place an addressed Listener in local front panel control mode The mechanism used to transfer bytes from the source handshake function of one devi
4. Technical Support Support at ni com support includes the following resources Self Help Technical Resources Visit ni com support for software drivers and updates a searchable KnowledgeBase product manuals step by step troubleshooting wizards thousands of example programs tutorials application notes instrument drivers and so on Registered users also receive access to the NI Discussion Forums at ni com forums NI Applications Engineers make sure every question submitted online receives an answer Software Support Service Membership the Standard Service Program SSP is a renewable one year subscription included with almost every NI software product including NI Developer Suite This program entitles members to direct access to NI Applications Engineers through phone and email for one to one technical support as well as exclusive access to online training modules at ni com self paced training NI also offers flexible extended contract options that guarantee your SSP benefits are available without interruption for as long as you need them Visit ni com ssp for more information Declaration of Conformity DoC A DoC is our claim of compliance with the Council of the European Communities using the manufacturer s declaration of conformity This system affords the user protection for electromagnetic compatibility EMC and product safety You can obtain the DoC for your product by visiting ni com cert
5. Unconfigure the device for parallel polling with ibppc Notice that any value having the parallel poll disable bit set bit 4 in the bit pattern disables the configuration so you can use any value between hex 70 and 7E ibppc dev 0x70 Parallel Polling with Multi Device NI 488 2 Calls Complete the following steps to implement parallel polling using multi device NI 488 2 calls Each step contains example code 1 Configure the device for parallel polling using the PPol1Config call unless the device can configure itself for parallel polling The following example configures a device at address 3 to assert data line 5 DIOS when its ist value is 1 include ni4882 h char response Addr4882_t AddressList 2 The following command clears the GPIB SendIFC 0 The value of sense is compared with the ist bit of the device and determines whether the data line is asserted PPollConfig 0 3 5 1 Conduct the parallel poll using PPo11 store the response and check the response for a certain value In the following example because DIOS is asserted by the device if ist is 1 the program checks bit 4 hex 10 in the response to determine the value of ist PPoll 0 amp response If response has bit 4 hex 10 set the ist bit of the device at that time is equal to 1 If it does not appear the ist bit is equal to 0 Check the bit in the following statement if response amp 0x10 printf The ist equals
6. int ud int v Pibsta int GetProcAddress Gpib32Lib LPCSTR user _ibsta Piberr int GetProcAddress Gpib32Lib LPCSTR user _iberr Pibcntl long GetProcAddress Gpib32Lib LPCSTR user _ibcnt Pibdev int __stdcall arte int ant it int dant GetProcAddress Gpib32Lib LPCSTR ibdev Pibonl int __stdcall int int GetProcAddress Gpib32Lib LPCSTR ibonl If Get ProcAddress fails it returns a NULL pointer The following code fragment shows you how to verify that none of the calls to Get ProcAddress failed if Pibsta NULL Piberr NULL Pibcntl NULL Pibdev NULL Pibonl NULL Free the GPIB library FreeLibrary Gpib32Lib printf GetProcAddress failed National Instruments 4 17 Chapter 4 Developing Your NI 488 2 Application Your Win32 application needs to dereference the pointer to access either the status variables or function The following code shows you how to call a function and access the status variable from within your application dvm Pibdev 0 1 0 T10s 1 0 if Pibsta amp ERR printf Call failed Before exiting your application you need to free gpib 32 d11 with the following command FreeLibrary Gpib32Lib For more information about direct entry refer to the help for your development environment Language Specific Programming Instructions for OS X
7. Clear the Device Use ibc1r to clear the device This resets the internal functions of the device to the default state Device Communication Step 3 Communicate with the Device Communicate with the device by sending it the IDN query and then reading back the response Many devices respond to this query by returning a description of the device Refer to the documentation that came with your GPIB device to see specific instructions on the proper way to communicate with it Step 3a Use ibwrt to send the IDN query command to the device Step 3b Use ibrd to read the response from the device Continue communicating with the GPIB device until you are finished Cleanup Step 4 Place the Device Offline before Exiting Your Application Use ibon1 to put the device handle offline before you exit the application National Instruments 4 9 Chapter 4 Developing Your NI 488 2 Application Applications That Use Multiple Interfaces or Communicate with Multiple GPIB Devices This section describes items you should include in your application and provides general program steps with an NI 488 2 example Items to Include Include the following items in your application e Header files In a C application include the header file ni4882 h which contains prototypes for the NI 488 2 calls and constants that you can use in your application Error checking Check for errors after each NI 488 2 call e Error handling D
8. semaphore serial poll service request source handshake SPD SPE SRQ status byte status word synchronous System Controller T TAD Talker TCT G 8 ni com An object that maintains a count between zero and some maximum value limiting the number of threads that are simultaneously accessing a shared resource The process of polling and reading the status byte of one device at a time See also parallel poll See SRQ The GPIB interface function that transmits data and commands Talkers use this function to send data and the Controller uses it to send commands See also acceptor handshake and handshake Serial Poll Disable The GPIB command used to cancel an SPE command Serial Poll Enable The GPIB command used to enable a specific device to be polled That device must also be addressed to talk See also SPD Service Request The GPIB line that a device asserts to notify the CIC that the device needs servicing The IEEE 488 2 defined data byte sent by a device when it is serially polled See Ibsta Refers to the relationship between the GPIB driver functions and a process when executing driver functions is predictable the process is blocked until the driver completes the function The single designated Controller that can assert control become CIC of the GPIB by sending the Interface Clear IFC message Other devices can become CIC only by having control passed to them Talk Addre
9. 1 n else printf The ist equals 0 n Unconfigure the device for parallel polling using PPo1l1Unconf ig as shown in the following example In this example the NOADDR constant must appear at the end of the array to signal the end of the address list If NOADDR is the only value in the array all devices receive the parallel poll disable message AddressList 0 3 AddressList 1 NOADDR PPollUnconfig 0 AddressList National Instruments 8 15 GPIB Basics The ANSI IEEE Standard 488 1 2003 also known as the General Purpose Interface Bus GPIB describes a standard interface for communication between instruments and controllers from various vendors It contains information about electrical mechanical and functional specifications GPIB is a digital 8 bit parallel communications interface that supports both interlocked and noninterlocked handshaking The interlocked handshake also known as three wire handshake allows for data transfer rates of 1 Mbyte s and higher The noninterlocked handshake also known as HS488 allows for data transfer rates up to 8 Mbytes s The bus supports one System Controller usually a computer and up to 14 additional instruments The ANSI IEEE Standard 488 2 1992 extends IEEE 488 1 by defining a bus communication protocol a common set of data codes and formats and a generic set of common device commands Talkers Listeners and Controllers GPIB devices can be Talkers
10. 2 User Manual Enable Disable NI 488 2 DOS Support NI 488 2 DOS support allows GPIB programs compiled for MS DOS to run on 32 bit Windows DOS support is enabled by default on 32 bit Windows systems Note NI 488 2 DOS support is available only on 32 bit Windows To disable NI 488 2 DOS support complete the following steps 1 Edit the config nt file located in your Windows System32 directory usually c windows system32 2 Add the REM prefix to the Gpib nt com line as in the following example to comment out the line REM device lt path gt NI 488 2 DOSWIN16 Gpib nt com where lt path gt is the directory where you installed the NI 488 2 software To re enable NI 488 2 DOS support 1 Edit the config nt file 2 Remove the REM prefix from the Gpib nt com line Access Additional Help and Resources To access additional help and resources for the NI 488 2 software and your GPIB hardware refer to the following sections NI 488 2 Help The NI 488 2 Help addresses questions you might have about NI 488 2 and includes a function reference and troubleshooting information You can access the N 488 2 Help as follows 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Select Help Help Topics NI 488 2 National Instruments GPIB Website You can access the National Instruments GPIB website as follows 1 Start MAX as described in the Starting Measurement amp Automation Explor
11. Controller EOI Talker uses the EOI line to mark the end of a data message Controller end or identify uses the EOI line when it conducts a parallel poll National Instruments A 3 Status Word Conditions This appendix gives a detailed description of the conditions reported in the status word Ibsta or ibsta For information about how to use Ibsta or ibsta in your application program refer to the NI 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual Each bit in Ibsta or ibsta can be set for device calls dev board calls brd or both dev brd Table B 1 shows the status word layout Table B 1 Status Word Layout Mnemonic Bit Pos Hex Value Type Description ERR 15 8000 dev brd NI 488 2 error TIMO 14 4000 dev brd Time limit exceeded END 13 2000 dev brd END or EOS detected SRQI 12 1000 brd SRQ interrupt received RQS 11 800 dev Device requesting service CMPL 8 100 dev brd T O completed LOK 7 80 brd Lockout State REM 6 40 brd Remote State CIC 5 20 brd Controller In Charge ATN 4 10 brd Attention is asserted TACS 3 8 brd Talker LACS 2 4 brd Listener DTAS 1 2 brd Device Trigger State DCAS 0 1 brd Device Clear State National Instruments B 1 Appendix B Status Word Conditions ERR dev brd ERR is set in the status word following any call that results
12. Figure 6 1 NI 488 2 Calls Recorded by NI I O Trace Shown on Windows Using the NI I O Trace Help 4 NIVO Trace capture on File Edit View Tools Help Hj E e 6 2 Number Description Status iberr ibcntl Time 1 ibdev 0 3 0 0x0 T10s 13 1 0x0000 0x0100 0 0x0000 16 16 47 786 2 ibdr UD0 0x0100 0 0x0004 16 16 47 819 3 ibwrt UDO IDN 5 0x5 ox0100 0 0x0005 16 16 49 425 4 ibrd UDO National Inst 2000 0x7D0 0x2100 0 Ox003C 16 16 49 434 5 ibwrt UDO CONF VOLT AC 22 0x16 ox0100 o0 0x0016 16 17 30 850 6 ibwrt UDO READ VOLT AC 13 OxD ox0100 o0 Ox000D 16 18 16 097 7 ibrd UDO 3 5355 2000 0x7D0 0x2100 0 0x0007 16 18 17 000 4 m tje Captured 0 Displayed 9 To view the built in context sensitive help for the NI I O Trace utility select Help Help Topics in NI T O Trace You can also view the help by clicking on the question mark button on the NI T O Trace toolbar and then clicking on the area of the screen about which you have a question Locating Errors with NI I O Trace All NI 488 2 calls returned with an error are displayed in red within the main NI I O Trace window 6 2 ni com NI 488 2 User Manual Debugging Existing Applications If the application does not have built in error detection handling you can use NI I O Trace to determine which NI 488 2 call is failing Once you know which NI 488 2 call fails refer to Appendix B
13. GPIB address configured for that device in the software does not match the GPIB address of any device connected to the bus that the GPIB cable is not connected to the device or that the device is not powered on ENOL can occur in situations where the GPIB interface is not the CIC and the Controller asserts ATN before the write call in progress has ended Solutions Possible solutions for this error are as follows e Make sure that the GPIB address of your device matches the GPIB address of the device to which you want to write data e Use the appropriate hex code in ibcmd to address your device e Check your cable connections and make sure at least two thirds of your devices are powered on e Call ibconfig with the IbcPAD or IbcSAD if necessary options to match the configured address to the device switch settings EADR 3 EADR occurs when the GPIB interface is CIC and is not properly addressing itself before read and write functions This error is usually associated with board level functions EADR is also returned by the function ibgts when the shadow handshake feature is requested and the GPIB ATN line is already unasserted In this case the shadow handshake is not possible and the error is returned to notify you of that fact National Instruments C 3 Appendix C Error Codes and Solutions Solutions Possible solutions for this error are as follows e Make sure that the GPIB interface is addressed correctly
14. Ibent Using Interactive Control to Communicate with Devices cece seceeseeecneeeceeeeteeneees 4 8 Programming Models snsc a vesaciccisccatiels a een tetanus eee eas 4 8 Applications That Communicate with a Single GPIB Device cece eeeeeee 4 8 Applications That Use Multiple Interfaces or Communicate with Multiple GPIB Devices 4 2 a die lee ee eek Language Specific Programming Instructions for Windows Microsoft Visual C C Version 6 0 or Later 0 Borland C C Version 5 0 2 or Later ccecescessesecsecesenseseceeseeeeeeeeseeseeeeseeeeees Visual Basic Version 6 0 c cccceccesessessessecseescesceseeseeeeseeeeeceeceecaeeaeeaecaecaeeaecatensente Direct Entry wath Ciern oa dy soe ccs ce n i E E EE a E E A s Language Specific Programming Instructions for OS X eeeseeeeeseseeererresrrrerrererrerereese Language Specific Programming Instructions for Linux 0 0 0 cece seeeeteeeeeeeeeeeeeeeeees vi ni com NI 488 2 User Manual Chapter 5 Debugging Your Application NITO Traein elated bed ien diem bein nS es atin Bie ees 5 1 Starting NI VO Trace x cc ceccccccecascskctcen conden contecdeseecdessdechstcstcvadsaduedaadede senses sense sevsederd 5 1 Debugging Existing Applications ccceccessessessesececseceececeecessenseceecsecsecaeeseeaeeseees 5 1 Performance Considerations ccccesssssesscescesceseesecseceecaecacescensensecsecseeseeaeeneeneeeees 5 1 Global Status Functio
15. Interactive Control utility Table 7 3 summarizes the syntax of the multi device NI 488 2 calls in the Interactive Control utility Table 7 4 summarizes the auxiliary functions that you can use in the Interactive Control utility For more information about the function parameters type help If you enter only the function name the Interactive Control utility prompts you for parameters Table 7 1 Syntax for Device Level Traditional NI 488 2 Calls in Interactive Control Syntax Description ibask option Return configuration information where option is a mnemonic for a configuration parameter ibclr Clear specified device ibconfig option value Alter configurable parameters where option is mnemonic for a configuration parameter ibdev BdIndx pad sad tmo Open an unused device ibdev parameters are BdIndx pad sad tmo eot eos eot eos ibeos v Change disable EOS message ibeot v Enable disable END message ibfind devname Return unit descriptor where devname is the symbolic name of the device template to use for example dvm iblck v Acquire or release an exclusive device lock for the current process LockWaitTime ibloc Go to local ibnotify mask Start an asynchronous wait for selected events where mask is a hex or decimal integer or a list of mask bit mnemonics for example ibnotify TIMO CMPL ibonl v Place device online or offline ibpad v Change primary add
16. Listeners or Controllers A Talker sends out data messages Listeners receive data messages The Controller usually a computer manages the flow of information on the bus It defines the communication links and sends GPIB commands to devices Some devices are capable of playing more than one role A digital voltmeter for example can be a Talker and a Listener If your system has a National Instruments GPIB interface and software installed it can function as a Talker Listener and Controller Controller In Charge and System Controller You can have multiple Controllers on the GPIB but only one Controller at a time can be the active Controller or Controller In Charge CIC The CIC can be either active or inactive standby Control can pass from the current CIC to an idle Controller but only the System Controller usually a GPIB interface can make itself the CIC National Instruments A 1 Appendix A GPIB Basics GPIB Addressing All GPIB devices and interfaces must be assigned a unique GPIB address A GPIB address is made up of two parts a primary address and an optional secondary address The primary address is a number in the range 0 to 30 The Controller uses this address to form a talk or listen address that is sent over the GPIB when communicating with a device Most devices just use primary addressing The GPIB Controller manages the communication across the GPIB by using the addresses to designate which devices s
17. MINDSTORMS are trademarks of the LEGO Group TETRIX by Pitsco is a trademark of Pitsco Inc FIELDBUS FOUNDATION and FOUNDATION are trademarks of the Fieldbus Foundation EtherCAT is a registered trademark of and licensed by Beckhoff Automation GmbH CANopen is a registered Community Trademark of CAN in Automation e V DeviceNet and EtherNet IP are trademarks of ODVA Go SensorDAQ and Vernier are registered trademarks of Vernier Software amp Technology Vernier Software amp Technology and vernier com are trademarks or trade dress Xilinx is the registered trademark of Xilinx Inc Taptite and Trilobular are registered trademarks of Research Engineering amp Manufacturing Inc FireWire is the registered trademark of Apple Inc Linux is the registered trademark of Linus Torvalds in the U S and other countries Handle Graphics MATLAB Real Time Workshop Simulink Stateflow and xPC TargetBox are registered trademarks and TargetBox and Target Language Compiler are trademarks of The MathWorks Inc Tektronix Tek and Tektronix Enabling Technology are registered trademarks of Tektronix Inc The Bluetooth word mark is a registered trademark owned by the Bluetooth SIG Inc The ExpressCard word mark and logos are owned by PCMCIA and any use of such marks by National Instruments is under license The mark LabWindows is used under a license from Microsoft Corporation Windows is a registered
18. National Instruments 8 7 Chapter 8 NI 488 2 Programming Techniques if LocalIbsta amp ERR printf ibwrt failed No more callbacks n DeviceError TRUE return 0 else return RQS Writing Multithreaded NI 488 2 Applications If you are writing a multithreaded NI 488 2 application and you plan to make all of your NI 488 2 calls from a single thread you can safely continue to use the NI 488 2 global functions Ibsta Iberr and Ibcnt The NI 488 2 global functions are defined on a per process basis so each process accesses its own copy of the NI 488 2 globals If you are writing a multithreaded NI 488 2 application and you plan to make NI 488 2 calls from more than a single thread you cannot safely continue to use the traditional NI 488 2 global functions without some form of synchronization for example semaphores mutexes critical sections To understand why refer to the following example Assume that a process has two separate threads that make NI 488 2 calls thread 1 and thread 2 Just as thread 1 is about to examine one of the NI 488 2 globals it gets preempted and thread 2 is allowed to run Thread 2 proceeds to make several NI 488 2 calls that automatically update the NI 488 2 globals Later when thread 1 is allowed to run the NI 488 2 global that it is ready to examine is no longer in a known state and its value is no longer reliable The previous example illustrates a well known multithreading prob
19. The following information describes how to develop compile and link your OS X NI 488 2 applications Before you compile your application remember to include the following line at the beginning of your program include lt NI4882 ni4882 h gt To compile and link your application include NI4882 framework in your project The framework is located at Library Frameworks To compile and link your application in a Terminal Shell type the following code on the command line cc cprog c framework NI4882 or gcc cprog c framework NI4882 To build a 32 bit application on a 64 bit system you must provide the m32 option as shown in the following examples cc m32 cprog c framework NI4882 or gcc m32 cprog c framework NI4882 4 18 ni com NI 488 2 User Manual Language Specific Programming Instructions for Linux The following information describes how to develop compile and link your Linux NI 488 2 applications for the NI4882 API Before you compile your application remember to include the following line at the beginning of your program include lt ni4882 h gt Your application must link with the NI 488 2 dynamic library 1ibni4882 so There are two ways to load a dynamic library on Linux static and dynamic To have the library statically loaded at the time your application starts compile and link your application as shown in the following examples gcc prog c 1ni4882 or g prog cpp 1ni4882 To build
20. Trigger State DCAS 0 1 brd Device Clear State The language header file defines each Ibsta status bit You can test for an Ibsta status bit being set using the bitwise and operator amp in C C For example the Ibsta ERR bitis bit 15 of Ibsta To check for an NI 488 2 error use the following statement after each NI 488 2 call if Ibsta amp ERR printf NI 488 2 error encountered Error Function Iberr If the ERR bit is set in Ibsta an NI 488 2 error has occurred When an error occurs the error type is specified by Iberr To check for an NI 488 2 error use the following statement after each NI 488 2 call if Ibsta amp ERR printf NI 488 2 error Sd encountered Iberr SI Note The value in Iberr is meaningful as an error only when the ERR bit is set in Ibsta indicating that an error has occurred For more information about error codes and solutions refer to Chapter 5 Debugging Your Application or Appendix C Error Codes and Solutions National Instruments 4 7 Chapter 4 Developing Your NI 488 2 Application Count Function Ibcnt The count function is updated after each read write or command function In addition Ibcnt is updated after specific 488 2 style functions in certain error cases Refer to the N 488 2 Help function reference for an explanation of how each function uses the count function Ibcnt is defined to be the type unsigned int If you are reading data the count varia
21. X section for more details on how to develop your application Linux NI 488 2 provides the 1ibni4882 so dynamically linked library which can be used from 32 bit and 64 bit C C applications Refer to the Language Specific Programming Instructions for Linux section for more details on how to develop your application 4 2 ni com NI 488 2 User Manual Differences Between the GPIB32 API and NI4882 API The NI 488 2 for Windows 2 6 NI 488 2 for Linux 3 2 and NI 488 2 for Mac OS X 3 2 releases officially add support for a new API as part of the 64 bit application interface Every effort has been made to have the new NI4882 API closely match the existing GPIB32 API while incorporating API design best practices To use the new API you must recompile applications using the new header and object files The following list describes the major changes in the NI4882 API e Judicious application of the const keyword has been added where appropriate e Wide variants of functions now use the wchar_t instead of unsigned short type e Functions taking in parameters that describe a pointer length now use size_t types e Status variables now use the unsigned int type ThreadIbcnt1 has been removed Macros redirect calls to ThreadIbcnt e Global status functions have been added These are Ibsta Iberr and Ibcnt New code should use these functions instead of ibsta iberr or ibcnt ibcntl e Long term deprecated functions have been completely remove
22. and installs the hardware To add a new GPIB Ethernet interface to your system complete the following steps 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Right click Devices and Interfaces and select Create New 3 Inthe Create New dialog window select GPIB ENET 100 or GPIB ENET 1000 and click Finish The GPIB Ethernet Wizard appears 4 Follow the prompts in the GPIB Ethernet Wizard to add your interface MAX automatically updates the list of installed GPIB interfaces You also can select View Refresh to update the list Ethernet GPIB devices are listed under Network Devices Locate Your GPIB Interface To locate a GPIB interface within MAX complete the following steps 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Expand Devices and Interfaces 3 Depending on the GPIB interface it is listed in its appropriate section e Plug and Play GPIB interfaces such as PCI GPIB or GPIB USB HS are listed directly under Devices and Interfaces e GPIB interfaces installed in a PXI system are listed under that system GPIB Ethernet interfaces that have been added are listed under Network Devices Remove a GPIB Interface To remove a Plug and Play interface from your computer disconnect it making sure to turn off the computer if the interface requires it To remove a GPIB Ethernet interface from your computer you must manually delete
23. either the traditional or multi device NI 488 2 calls If you use multi device NI 488 2 calls to execute parallel polls you do not need extensive knowledge of the parallel polling messages However you should use the traditional NI 488 2 National Instruments 8 13 Chapter 8 NI 488 2 Programming Techniques calls for parallel polling when the GPIB interface is not the Controller and the interface must configure itself for a parallel poll and set its own individual status bit ist Parallel Polling with Traditional NI 488 2 Calls Complete the following steps to implement parallel polling using traditional NI 488 2 calls Each step contains example code 1 8 14 Configure the device for parallel polling using the ibppc function unless the device can configure itself for parallel polling ibppc requires an 8 bit value to designate the data line number the ist sense and whether the function configures the device for the parallel poll The bit pattern is as follows 0 1 1 E S D2 D1 DO E is 1 to disable parallel polling and 0 to enable parallel polling for that particular device S is 1 if the device is to assert the assigned data line when ist is 1 and 0 if the device is to assert the assigned data line when ist is 0 D2 through DO determine the number of the assigned data line The physical line number is the binary line number plus one For example DIO3 has a binary bit pattern of 010 The following example code config
24. gpiberr char msg function prototype then your application invokes it as follows if Ibsta amp ERR gpiberr NI 488 2 error 4 8 ni com NI 488 2 User Manual General Program Steps and Examples The following steps show you how to use the traditional NI 488 2 device level calls in your application The NI 488 2 software includes the devquery source code example to demonstrate these principles Initialization Step 1 Open a Device Use ibdev to open a device handle The ibdev function requires the following parameters e Connect board index typically 0 for GPIBO e Primary address for the GPIB instrument refer to the instrument user manual or use the FindLstn function to dynamically determine the GPIB address of your GPIB device as described in Step 2 Determine the GPIB Address of Your Device in the Applications That Use Multiple Interfaces or Communicate with Multiple GPIB Devices section e Secondary address for the GPIB instrument 0 if the GPIB instrument does not use secondary addressing Timeout period typically set to T10s which is 10 seconds e End of transfer mode typically set to 1 so that EOI is asserted with the last byte of writes EOS detection mode typically 0 if the GPIB instrument does not use EOS characters A successful ibdev call returns a device handle ud that is used for all device level traditional NI 488 2 calls that communicate with the GPIB instrument Step 2
25. in an error You can determine the particular error by examining the error function Iberr Appendix C Error Codes and Solutions describes error codes that are recorded in Iberr along with possible solutions ERR is cleared following any call that does not result in an error TIMO dev brd TIMO indicates that the timeout period has expired TIMO is set in the status word following any synchronous I O functions for example ibcmd ibrd ibwrt Receive Send and SendCmds if the timeout period expires before the I O operation has completed TIMO is also set in the status word following an ibwait or ibnotify call ifthe TIMO bit is set in the mask parameter and the timeout period expires before any other specified mask bit condition occurs TIMO is cleared in all other circumstances END dev brd END indicates either that the GPIB EOI line has been asserted or that the EOS byte has been received if the software is configured to terminate a read on an EOS byte If the GPIB interface is performing a shadow handshake as a result of the ibgts function any other function can return a status word with the END bit set if the END condition occurs before or during that call END is cleared when any I O operation is initiated Some applications might need to know the exact I O read termination mode of a read operation EOI by itself the EOS character by itself or EOI plus the EOS character You can use the ibconfig function option IbcEndBitI
26. is mnemonic for value a configuration parameter ibdma v Enable disable DMA ibeos v Change disable EOS message ibeot v Enable disable END message 7 6 ni com NI 488 2 User Manual Table 7 2 Syntax for Board Level Traditional NI 488 2 Calls in Interactive Control Continued Syntax Description ibfind udname Return unit descriptor where udname is the symbolic name of interface for example gpib0 ibgts v Go from Active Controller to standby ibist v Set clear ist iblck v Acquire or release an exclusive interface lock for the current LockWaitTime process iblines Read the state of all GPIB control lines ibln pad sad Check for presence of device on the GPIB at pad sad ibloe Go to local ibnotify mask Start an asynchronous wait for selected events where mask is a hex or decimal integer or a list of mask bit mnemonics for example ibnotify TIMO CMPL ibonl v Place device online or offline ibpad v Change primary address ibppe v Parallel poll configure ibrd count Read data where count is the bytes to read ibrda count Read data asynchronously where count is the bytes to read ibrdf flname Read data to file where f 1name is pathname of file to read ibrpp Conduct a parallel poll ibrsc v Request release system control ibrsv v Request service ibsad v Change secondary address ibsic Send i
27. ni4882 obj MD With Microsoft Visual C Version 8 0 or later to compile and link a Win64 console application named cprog in the Visual C x64 Command Prompt using the environment variable NIEXTCCOMPILERSUPP type in the following on the command line cl I S3NIEXTCCOMPILERSUPP include cprog c SNIEXTCCOMPILERSUPP 1ib64 msvc ni4882 obj MD Borland C C Version 5 0 2 or Later Before you compile your Win32 C application make sure that the following line is included at the beginning of your program include ni4882 h The NIEXTCCOMPILERSUPP environment variable is provided as an alias to the location of C language support files You can use this variable when compiling and linking an application To compile and link a Win32 console application named cprog in a DOS shell using the environment variable NIEXTCCOMPILERSUPP type in the following on the command line bec32 I S NIEXTCCOMPILERSUPP S include w32 cprog c SNIEXTCCOMPI LERSUPP 1ib32 borland ni4882 ob3 Borland CodeGear Embarcadero does not have a 64 bit compiler at the time of this writing 4 12 ni com NI 488 2 User Manual Visual Basic Version 6 0 With Visual Basic you can access the traditional NI 488 2 calls as subroutines using the BASIC keyword CALL followed by the traditional NI 488 2 call name or you can access them using the il set of functions With some of the NI 488 2 calls for example ibrd and Receive the length of the str
28. no lock Solutions Call iblck to lock the interface If iblck continues to return ELCK lengthen the LockWaitTime and wait for the other process to relinquish its interface lock Ensure that you have successfully locked the interface prior to unlocking it EARM 22 EARM indicates that ibnotify s asynchronous event notification mechanism failed to rearm itself This generally occurs when an ibnotify Callback has attempted to rearm itself by returning an illegal value or when a fatal driver error EDVR has occurred Solutions Ensure that the value being returned by your Callback function is a valid ibnotify mask value Return a zero value from your Callback function to unregister the asynchronous event notification mechanism Then call ibnotify to re enable notification C 8 ni com NI 488 2 User Manual EHDL 23 EHDL results when an invalid handle is passed to a function call The following are some examples e A valid board handle is passed in as a handle parameter to a device level NI 488 function or a valid device handle is passed in as a handle parameter to a board level NI 488 function e An invalid board or device unit descriptor is passed as input to any NI 488 2 function e A boardID outside the range of 0 to 99 is passed in to a traditional NI 488 board level function or NI 488 2 routine e ibconfig or ibask is called with a device unit descriptor and a board only configuration option or with a board
29. operations It is set whenever an I O operation is complete CMPL is cleared while the I O operation is in progress LOK brd LOK indicates whether the interface is in a lockout state While LOK is set the EnableLocal or ibloc call is inoperative for that interface LOK is set whenever the GPIB interface detects that the Local Lockout LLO message has been sent either by the GPIB interface or by another Controller LOK is cleared when the System Controller unasserts the Remote Enable REN GPIB line REM brd REM indicates whether the interface is in the remote state REM is set whenever the Remote Enable REN GPIB line is asserted and the GPIB interface detects that its listen address has been sent either by the GPIB interface or by another Controller REM is cleared in the following situations e When REN becomes unasserted e When the GPIB interface as a Listener detects that the Go to Local GTL command has been sent either by the GPIB interface or by another Controller When the ibloc function is called while the LOK bit is cleared in the status word CIC brd CIC indicates whether the GPIB interface is the Controller In Charge CIC is set when the SendIFC or ibsic call is executed either while the GPIB interface is System Controller or when another Controller passes control to the GPIB interface CIC is cleared either when the GPIB interface detects Interface Clear IFC from the System Controller or when the GPIB in
30. protocol These functions give you the flexibility and control to handle situations such as the following e Communicating with non compliant non IEEE 488 2 devices e Altering various low level interface configurations e Managing the bus in non typical ways Board level functions that an NI 488 2 application might use include the following ibcmd ibrd ibwrt and ibconfig For a detailed list refer to the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual Using Multiple Interfaces and or Multiple Devices When your system includes an interface that must access multiple devices use the multi device NI 488 2 calls which can perform the following tasks with a single call e Find the Listeners on the bus using FindLstn e Find a device requesting service using FindRQS e Determine the state of the SRQ line or wait for SRQ to be asserted using TestSRQ or WaitSRQ e Address multiple devices to receive a command using SendList You can mix board level traditional NI 488 2 calls with the multi device NI 488 2 calls to have access to all the NI 488 2 functionality National Instruments 4 5 Chapter 4 Developing Your NI 488 2 Application Checking Status with Global Functions For applications accessing the NI4882 API each NI 488 2 call updates three global functions to reflect the status of the device or board you are using These global status
31. refer to the Using the NI 488 2 Documentation section of About This Manual Timing Errors If your application fails but the same calls issued interactively in the Interactive Control utility are successful your program might be issuing the NI 488 2 calls too quickly for your device to process and respond to them This problem can also result in corrupted or incomplete data This is only a problem with noncompliant GPIB devices A well behaved IEEE 488 device does not experience timing errors If your device is not well behaved you can test for and resolve the timing error by single stepping through your program and inserting finite delays between each NI 488 2 call One way to do this is to have your device communicate its status whenever possible Although this method is not possible 5 2 ni com NI 488 2 User Manual with many devices it is usually the best option Your delays are controlled by the device and your application can adjust itself and work independently on any platform Other delay mechanisms can exhibit differing behaviors on different platforms and thus might not eliminate timing errors Communication Errors The following sections describe communication errors you might encounter in your application Repeat Addressing Devices adhering to the IEEE 488 2 standard should remain in their current state until specific commands are sent across the GPIB to change their state However some devices require GPIB addre
32. request service When the GPIB SRQ line is asserted it signals the Controller that a service request is pending The Controller must then determine which device asserted the SRQ line and respond accordingly The most common method for SRQ detection and servicing is the serial poll This section describes how to set up your application to detect and respond to service requests from GPIB devices Service Requests from IEEE 488 Devices IEEE 488 devices request service from the GPIB Controller by asserting the GPIB SRQ line When the Controller acknowledges the SRQ it serial polls each open device on the bus to determine which device requested service Any device requesting service returns an 8 bit status byte with bit 6 set and then unasserts the SRQ line Devices not requesting service return a status byte with bit 6 cleared Manufacturers of IEEE 488 devices use the remaining seven bits to communicate the reason for the service request or to summarize the state of the device Service Requests from IEEE 488 2 Devices The IEEE 488 2 standard refined the bit assignments in the status byte In addition to setting bit 6 when requesting service IEEE 488 2 devices also use two other bits to specify their status Bit 4 the Message Available bit MAV is set when the device is ready to send previously queried data Bit 5 the Event Status bit ESB is set if one or more of the enabled IEEE 488 2 events occurs These events include power on user reques
33. requesting control for the GPIB interface Then use a board level ibwait command to wait for CIC Talker Listener Applications Although designed for Controller In Charge applications you can also use the NI 488 2 software in most non Controller situations These situations are known as Talker Listener applications because the interface is not the GPIB Controller A Talker Listener application typically uses ibwait with a mask of 0 to monitor the status of the interface Then based on the status bits set in Ibsta the application takes whatever action is appropriate For example the application could monitor the status bits TACS Talker Active National Instruments 8 9 Chapter 8 NI 488 2 Programming Techniques State and LACS Listener Active State to determine when to send data to or receive data from the Controller The application could also monitor the DCAS Device Clear Active State and DTAS Device Trigger Active State bits to determine if the Controller has sent the device clear DCL or SDC or trigger GET messages to the interface If the application detects a device clear from the Controller it might reset the internal state of message buffers If it detects a trigger message from the Controller the application might begin an operation such as taking a voltage reading if the application is acting as a voltmeter Serial Polling You can use serial polling to obtain specific information from GPIB devices when they
34. trademark of Microsoft Corporation in the United States and other countries Other product and company names mentioned herein are trademarks or trade names of their respective companies Members of the National Instruments Alliance Partner Program are business entities independent from National Instruments and have no agency partnership or joint venture relationship with National Instruments Patents For patents covering National Instruments products technology refer to the appropriate location Help Patents in your software the patents txt file on your media or the National Instruments Patent Notice at ni com patents Export Compliance Information Refer to the Export Compliance Information at ni com legal export compliance for the National Instruments global trade compliance policy and how to obtain relevant HTS codes ECCNs and other import export data WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS YOU ARE ULTIMATELY RESPONSIBLE FOR VERIFYING AND VALIDATING THE SUITABILITY AND RELIABILITY OF THE PRODUCTS WHENEVER THE PRODUCTS ARE INCORPORATED IN YOUR SYSTEM OR APPLICATION INCLUDING THE APPROPRIATE DESIGN PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION PRODUCTS ARE NOT DESIGNED MANUFACTURED OR TESTED FOR USE IN LIFE OR SAFETY CRITICAL SYSTEMS HAZARDOUS ENVIRONMENTS OR ANY OTHER ENVIRONMENTS REQUIRING FAIL SAFE PERFORMANCE INCLUDING IN THE OPERATION OF NUCLEAR FACILITIES AIRCRAFT NAVIGATION AIR TRAFFIC CONTR
35. unit descriptor and a device only configuration option Solutions Do not use a device descriptor in a board function or vice versa Make sure that the board index passed to the NI 488 2 call is valid EWIP 26 EWIP indicates that an ibwait call is already in progress on the specified unit descriptor This error occurs when one thread within a process calls ibwait ona given descriptor when another thread within the same process is already performing an ibwait using that same descriptor Solutions Make sure that for any given unit descriptor only one thread calls ibwait at a time using that descriptor ERST 27 ERST results when an event notification was cancelled due to a reset of the interface An ibwait call pending in the driver returns ERST in the following situations e Another thread in the same process calls ibon1 using the same unit descriptor as ibwait e Another thread or another process issues a board level ibonl 1 An ibnotify Callback may be invoked with ERST in the following situations e Another process issues a board level ibonl 1 Solutions Do not call ibon1 with ibwait calls still pending in the driver Prevent other applications from calling ibon1 by locking the interface with iblck National Instruments C 9 Appendix C Error Codes and Solutions EPWR 28 EPWR results when an interface loses power This often results when the system goes to and returns from a standby state Sol
36. you how to call the LoadLibrary function and check for an error HINSTANCE ni4882Lib NULL ni4882Lib LoadLibrary NI14882 DLL if ni4882Lib NULL return FALSE For the prototypes for each function refer to the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual For functions that return an integer value like ibdev you need to cast the pointer as int _stdcall Pname where Pname is the name of the pointer to the function For calls that return an unsigned int value such as ibwrt you need to cast the pointer to the function as unsigned int _stdcall Pname where Pname is the name of the pointer to the function For functions that do not return a value like FindLstn or SendList you need to cast the pointer as void _stdcall Pname where Pname is the name of the pointer to the function It is followed by the function s list of parameters as described in the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual An example of how to declare the function pointer and parameter list for ibdev and ibonl follows int _stdcall Pibdev int ud int pad int sad int tmo int eot int eos unsigned int _stdcall Pibonl int ud int v 4 14 ni com NI 488 2 User Manual Your Windows application needs to use Get ProcAddress to get the addresse
37. 2 Documentation section of About This Manual For functions that return an integer value like ibdev or ibwrt the pointer to the function needs to be cast as follows int _stdcall Pname where Pname is the name of the pointer to the function For functions that do not return a value like FindLstn or SendList the pointer to the function needs to be cast as follows void _stdcall Pname where Pname is the name of the pointer to the function They are followed by the function s list of parameters as described in the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual 4 16 ni com NI 488 2 User Manual Following is an example of how to cast the function pointer and how the parameter list is set up for ibdev and ibon1 functions int _stdcall Pibdev int ud int pad int sad int tmo int eot int eos int _stdcall Pibonl int ud int v Next your Win32 application needs to use Get ProcAddress to get the addresses of the global status variables and functions your application needs The following code fragment shows you how to get the addresses of the pointers to the status variables and any functions your application needs Pointers to NI 488 2 global status variables int Pibsta int Piberr long Pibcntl static int __stdcall Pibdev int ud int pad int sad int tmo int eot int eos static int __stdcall Pibonl
38. 5 ibwrt UDO conf dc max 11 0xB 0x0100 0 0x0008 15 39 47 633 6 ibwrt UDO meas dc 8 0x8 0x0100 0 0x0008 15 40 01 793 7 ibrd UDO 0 8157 10 0xA 0x2100 0 0x0007 15 40 07 729 lt pif Captured 7 Displayed 7 For more information about using NI I O Trace select Help Help Topics in NI I O Trace National Instruments 2 5 Chapter 2 Measurement amp Automation Explorer Windows View or Change GPIB Interface Settings To view or change interface settings for your GPIB instruments complete the following steps 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Expand Devices and Interfaces and Locate Your GPIB Interface 3 Select your GPIB interface in the left window pane of MAX The interface properties appear in the right window pane of MAX 4 Optional Change the settings for your interface and click Save to apply the settings View GPIB Instrumentation Information To view information about your GPIB instruments complete the following steps 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Expand Devices and Interfaces and Locate Your GPIB Interface 3 Select your GPIB interface MAX displays the connected instruments in the right window pane 4 Ifyou have not already done so scan for connected instruments Right click your GPIB interface and select Scan for Instruments from the drop down menu that ap
39. 8 15 PPollUnconfig routine 8 15 primary GPIB address A 2 programming examples NI resources E 2 methodology choosing 4 2 models requirements for applications using multiple interfaces 4 10 requirements for multiple device applications 4 10 requirements for single device applications 4 8 Q q exit or quit function Interactive Control utility 7 10 R ReadStatusByte routine 8 12 Receive function 4 11 recording calls in NI I O Trace 6 3 related documentation x REM status word condition 4 7 B 1 B 3 removing GPIB interface in Measurement amp Automation Explorer 2 2 REN remote enable line table A 3 repeat addressing 5 3 repeat previous function function Interactive Control utility 7 9 RQS status word condition 4 7 B 1 B 2 S scanning for GPIB instruments 2 3 instruments not found 2 3 too many Listeners on GPIB 2 3 secondary GPIB address A 2 SendIFC function 4 10 SendList function 4 11 serial polling automatic serial polling 8 10 autopolling and interrupts 8 11 detecting an SRQ state 8 11 service requests IEEE 488 devices 8 10 IEEE 488 2 devices 8 10 using FindRQS function 8 12 with device level NI 488 2 calls 8 11 with multi device NI 488 2 calls 8 12 serial polling using AllSpoll function 8 13 service requests serial polling IEEE 488 devices 8 10 IEEE 488 2 devices 8 10 set 488 2 function Interactive Control utility 7 9 set udname function Interactive C
40. API For specific device communication instructions refer to the documentation that came with your instrument For information about using the Interactive Control utility and detailed examples refer to Chapter 7 Interactive Control Utility To view the help for Interactive Control type help at the Interactive Control command prompt Windows Start MAX as described in Chapter 2 Measurement amp Automation Explorer Windows 2 Select Tools NI 488 2 Interactive Control At the command prompt type NI 488 2 API calls to communicate interactively with your instrument For example you might use ibdev ibclr ibwrt ibrd and ibonl OS X 1 Double click Applications National Instruments NI 488 2 Interactive Control 2 At the command prompt type NI 488 2 API calls to communicate interactively with your instrument For example you might use ibdev ibclr ibwrt ibrd and ibonl Linux 1 To launch the Interactive Control utility enter the following command usr local bin gpibintctrl 2 At the command prompt type NI 488 2 API calls to communicate interactively with your instrument For example you might use ibdev ibclr ibwrt ibrd and ibonl National Instruments 4 1 Chapter 4 Developing Your NI 488 2 Application Choosing Your Programming Methodology Based on your development environment you can select a method for accessing the driver and based on your NI 488 2 programming needs you can choose how to use the
41. B Explorer OS X and Linux View or Change GPIB Interface Settings To view or change your interface settings complete the following steps 1 Start GPIB Explorer as described in the Starting GPIB Explorer section 2 Click your GPIB interface and click Properties The Properties dialog box appears Figure 3 3 GPIB Configuration ae GPIB Configuration x Termination Settings GPIB ENET 100 Hostname nienetcca1d8 Send EOI at end of Write I Terminate Read On EOS 0 EOS Byte I 8 bit EOS Compare J Set EOI with EOS on Write General Settings GPIB2 z GPIB Interface ID Primary Address Advanced Settings Secondary Address fo00nsec a Bus Timing VO Timeout Defaut Parallel Poll Duration Automatic Serial Polling Off z Cable Length for H5488 System Controller I Assert REN when SC OK Cancel 3 Optional Change the settings for your interface then click the OK button Access Additional Help and Resources To access additional help and resources for the NI 488 2 software and your GPIB hardware refer to the following sections NI 488 2 Help The NI 488 2 Help addresses questions you might have about NI 488 2 and includes a function reference and troubleshooting information You can access the N 488 2 Help as follows 1 Start GPIB Explorer as described in the Starting GPIB Explorer section 2 Select Help NI 488 2 Help from the menu bar 3 4 ni com NI 488 2 User Manual Nati
42. Documentation utility helps you find the documentation that you want to view You can also view these documents at ni com OS X To view these documents insert your NI 488 2 software distribution media and open the Documentation folder You can also view these documents at ni com Linux To view these documents insert your NI 488 2 software distribution media and browse to the Documentation directory You can also view these documents at ni com Accessing the NI 488 2 Help The NI 488 2 Help addresses questions you might have about NI 488 2 and includes a function reference and troubleshooting information National Instruments ix About This Manual Windows Select Start Programs National Instruments Measurement amp Automation to start Measurement amp Automation Explorer MAX Windows 8 Click NI Launcher and select Measurement amp Automation Explorer Select Help Help Topics NI 488 2 OS X Select Applications National Instruments NI 488 2 GPIB Explorer Select Help NI 488 2 Help Linux Run GPIB Explorer by entering the following command usr local bin gpibexplorer Select Help NI 488 2 Help Conventions The following conventions appear in this manual IEEE 488 and IEEE 488 and IEEE 488 2 refer to the ANSI IEEE Standard 488 1 2003 IEEE 488 2 and the ANSI IEEE Standard 488 2 1992 respectively which define the GPIB Related Documentation The following documents contain informatio
43. GPIB Explorer OS X and Linux Overview You can perform the following GPIB related tasks in MAX e Establish basic communication with your GPIB instruments Scan for instruments connected to your GPIB interface e Use Self Test to troubleshoot NI 488 2 problems e Launch NI I O Trace to monitor NI 488 2 or VISA API calls to GPIB interfaces e View information about your GPIB hardware and NI 488 2 software e Reconfigure GPIB interface settings e Locate additional help resources for GPIB and NI 488 2 Starting Measurement amp Automation Explorer To start Measurement amp Automation Explorer MAX select Starb gt Programs NI MAX Windows 8 Click NI Launcher and select NI MAX The Measurement amp Automation Explorer window shows the configuration tree at the left the item view in the tabbed middle window and a collapsible help pane at the right Item view shows System Settings and System Resources when NI MAX starts Troubleshoot NI 488 2 Problems Self Test verifies that your GPIB hardware and the NI 488 2 software are installed correctly and able to perform basic I O functions To start Self Test right click the device name in the configuration tree and select Self Test from the shortcut menu National Instruments 2 1 Chapter 2 Measurement amp Automation Explorer Windows Add a New GPIB Interface For plug and play interfaces such as PCI or USB the system automatically detects
44. GPIB Explorer as described in the Starting GPIB Explorer section You should see your interface in the list of configured interfaces Delete a GPIB Interface To remove a GPIB interface from your system complete the following steps Non Plug and Play Interfaces For Example GPIB ENET 100 1 2 3 Start GPIB Explorer as described in the Starting GPIB Explorer section Click your GPIB interface and select Delete When prompted click the Yes button to confirm the removal of your interface Plug and Play Interfaces For Example PCI GPIB 1 2 Close GPIB Explorer if it is running Physically remove the interface from your system making sure to shut down the system if your interface is not hot swappable Refer to the GPIB Hardware Installation Guide and Specifications for more details on how to do this To view the document you need Acrobat Reader which you can download from www adobe com OS X The GPIB Hardware Installation Guide and Specifications is installed with NI 488 2 To access this document double click Applications National Instruments NI 488 2 Documentation Linux The GPIB Hardware Installation Guide and Specifications is installed with NI 488 2 It is in the usr local natinst ni4882 docs directory Start GPIB Explorer as described in the Starting GPIB Explorer section The interface you just removed should not be in the list of configured interfaces National Instruments 3 3 Chapter 3 GPI
45. Group Execute Trigger GET command has been sent by another Controller DTAS is cleared on any call immediately following an ibwait or ibnotify call ifthe DTAS bit is set in the ibwait mask parameter DCAS brd DCAS indicates whether the GPIB interface has detected a device clear command DCAS is set whenever the GPIB interface detects that the Device Clear DCL command has been sent by another Controller or whenever the GPIB interface as a Listener detects that the Selected Device Clear SDC command has been sent by another Controller If you use the ibwait or ibnotify function to wait for DCAS and the wait is completed DCAS is cleared from Ibsta after the next NI 488 2 call The same is true of reads and writes If you call a read or write function such as ibwrt or Send and DCAS is set in Ibsta the I O operation is aborted DCAS is cleared from Ibsta after the next NI 488 2 call B 4 ni com Error Codes and Solutions This appendix lists a description of each error some conditions under which it might occur and possible solutions Table C 1 lists the GPIB error codes Table C 1 GPIB Error Codes Error Mnemonic Value Meaning EDVR 0 System error ECIC 1 Function requires GPIB interface to be CIC ENOL 2 No Listeners on the GPIB EADR 3 GPIB interface not addressed correctly EARG 4 Invalid argument to function call ESAC 5 GPIB interface not System C
46. I O Trace as ibconfig calls This is because macros redirect those calls to use ibconfig Avoid confusion by using ipconfig directly In most cases applications written in the NI4882 API will continue to work on older versions of the NI 488 2 for Windows software back to version 1 7 Certain new ibask and ibconfig options break this backwards compatibility and those options are easily avoidable by using alternative options Existing applications using the GPIB32 API continue to execute unchanged The GPIB32 API will continue to exist but is available only for 32 bit applications Applications written in the NI4882 API compile on both 32 bit and 64 bit environments To port an application to a 64 bit environment requires that the application migrate to the NI4882 API and be recompiled The following NI4882 API constructs break API compatibility with older versions of NI 488 2 e ibask IbaEOS ibconfig IbcEOS Choosing How to Use the NI 488 2 API The NI 488 2 API has two subsets of calls to meet your application needs Both of these sets the traditional calls and the multi device calls are compatible across computer platforms and operating systems so you can port programs to other platforms with little or no source code modification For most applications the traditional NI 488 2 calls are sufficient If you have a complex configuration with one or more interfaces and multiple devices use the multi device NI 488 2 calls Whichever opti
47. In the following example an error condition EBUS has occurred during a data transfer udt ibwrt IDN 8100 err cmpl error EBUS count 1 ud0 In this example the addressing command bytes could not be transmitted to the device This indicates that either the GPIB device is powered off or the GPIB cable is disconnected For a detailed list of the error codes and possible solutions refer to Appendix C Error Codes and Solutions 7 10 ni com NI 488 2 User Manual Count Information When an I O function completes the Interactive Control utility displays the actual number of bytes sent or received regardless of the existence of an error condition If one of the addresses in an address list to a multi device NI 488 2 call is invalid then the error is EARG and the Interactive Control utility displays the index of the invalid address as the count The count has a different meaning depending on which NI 488 2 call is made For the correct interpretation of the count return refer to the function descriptions in the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual National Instruments 7 11 NI 488 2 Programming Techniques This chapter describes techniques for using some NI 488 2 calls in your application For more information about each function refer to the N 488 2 Help For instructions on accessing the help refer to the Us
48. Interfaces and Locate Your GPIB Interface Right click your GPIB interface and select Interactive Control from the drop down menu that appears Interactive Control automatically opens a session to the selected GPIB interface At the command prompt type NI 488 2 API calls to communicate interactively with the your instrument For example you might use ibdev ibclr ibwrt ibrd and ibonl To view the help for Interactive Control type help at the Interactive Control command prompt For more information on using this utility refer to Chapter 7 Interactive Control Utility Monitor and Record NI 488 2 Calls To monitor NI 488 2 calls use NI I O Trace as follows 1 2 3 4 Start MAX as described in the Starting Measurement amp Automation Explorer section Select Tools NI I O Trace to open the application On the NI T O Trace toolbar click the green arrow button to start a capture Start the NI 488 2 application that you want to monitor NI T O Trace records and displays all NI 488 2 calls as shown in Figure 2 2 Figure 2 2 NI 488 2 Calls Recorded by NI I O Trace 4 NIVO Trace capture off SS File Edit View Tools Help Staje AJA le ae J p Status cr a ibdev 0 3 0 0x0 T10s 13 1 0x000 0x0100 0x0000 2 ibelr UDO 0x0100 0 0x0004 15 39 15 257 3 ibwrt UDO idn 5 0x5 0x0100 0 0x0005 15 39 25 761 4 ibrd UDO National Inst 100 0x64 0x2100 0 0x003E 15 39 32 001
49. LUKE 4 35 2C 20 34 37 39 30 31 5 47901 37 33 2C 20 31 2E 36 20 73 1 6 44 31 2E 30 OA D 10 When you finish communicating with the device make sure you put it offline using the ibonl command as follows ud0 ibonl 0 0100 cmpl The ibonl command properly closes the device handle and the ud0 prompt is no longer available To exit Interactive Control type q National Instruments 7 3 Chapter 7 Interactive Control Utility Interactive Control Syntax The following special rules apply to making calls from the Interactive Control utility e The ud or BoardId parameter is implied by the Interactive Control prompt therefore it is never included in the call Except for reads the count parameter to calls is unnecessary because buffer lengths are automatically determined by Interactive Control e Function return values are handled automatically by Interactive Control In addition to printing out the return ibsta value for the function it also prints other return values e Ifyou do not know what parameters are appropriate to pass to a given function call type in the function name and press lt Enter gt The Interactive Control utility then prompts you for each required parameter Number Syntax You can enter numbers in either hexadecimal or decimal format Hexadecimal numbers You must prefix hexadecimal numbers with 0x For example ibpad 0x16 sets the primary address to 16 hexadecimal 22 decimal Deci
50. MER S SOLE REMEDIES AND SHALL APPLY EVEN IF SUCH REMEDIES FAIL OF THEIR ESSENTIAL PURPOSE EXCEPT AS EXPRESSLY SET FORTH HEREIN PRODUCTS ARE PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND AND NI DISCLAIMS ALL WARRANTIES EXPRESSED OR IMPLIED WITH RESPECT TO THE PRODUCTS INCLUDING ANY IMPLIED WARRANTIES OF MERCHANTABILITY FITNESS FOR A PARTICULAR PURPOSE TITLE OR NON INFRINGEMENT AND ANY WARRANTIES THAT MAY ARISE FROM USAGE OF TRADE OR COURSE OF DEALING NI DOES NOT WARRANT GUARANTEE OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF OR THE RESULTS OF THE USE OF THE PRODUCTS IN TERMS OF CORRECTNESS ACCURACY RELIABILITY OR OTHERWISE NI DOES NOT WARRANT THAT THE OPERATION OF THE PRODUCTS WILL BE UNINTERRUPTED OR ERROR FREE In the event that you and NI have a separate signed written agreement with warranty terms covering the products then the warranty terms in the separate agreement shall control Copyright Under the copyright laws this publication may not be reproduced or transmitted in any form electronic or mechanical including photocopying recording storing in an information retrieval system or translating in whole or in part without the prior written consent of National Instruments Corporation National Instruments respects the intellectual property of others and we ask our users to do the same NI software is protected by copyright and other intellectual property laws Where NI software may be used to reproduce software or oth
51. NI 488 2 NI 488 2 User Manual June 2015 7 NATIONAL 370428V 01 y INSTRUMENTS Worldwide Technical Support and Product Information nai con Worldwide Offices Visit ni com niglobal to access the branch office websites which provide up to date contact information support phone numbers email addresses and current events National Instruments Corporate Headquarters 11500 North Mopac Expressway Austin Texas 78759 3504 USA Tel 512 683 0100 For further support information see the NJ Services appendix To comment on National Instruments documentation refer to the National Instruments website at ni com info and enter the Info Code feedback 2002 2015 National Instruments All rights reserved Legal Information Limited Warranty This document is provided as is and is subject to being changed without notice in future editions For the latest version refer to ni com manuals NI reviews this document carefully for technical accuracy however NI MAKES NO EXPRESS OR IMPLIED WARRANTIES AS TO THE ACCURACY OF THE INFORMATION CONTAINED HEREIN AND SHALL NOT BE LIABLE FOR ANY ERRORS NI warrants that its hardware products will be free of defects in materials and workmanship that cause the product to fail to substantially conform to the applicable NI published specifications for one 1 year from the date of invoice For a period of ninety 90 days from the date of invoice NI warrants that i its software products w
52. NI 488 2 API Choosing a Method to Access the NI 488 2 Driver Windows Applications using the older GPIB32 API can access the NI 488 2 dynamic link library DLL gpib 32 d11 either by using an NI 488 2 application interface or by direct access Applications using the new NI4882 API can access the NI 488 2 dynamic link library DLL ni4882 d11 by using an NI 488 2 application interface or by direct access NI 488 2 Application Interfaces You can use an application interface if your program is written in Microsoft Visual C C 6 0 or later Borland C C 5 02 or later Microsoft Visual Basic 6 0 or any NET programming language Otherwise you must access the dynamic link library directly For more information about application interfaces refer to N 488 2 Application Interface Files in the NI 488 2 Help Direct Entry Access You can access the DLL directly from any programming environment that allows you to request addresses of variables and calls that a DLL exports The dynamic link libraries export pointers to each of the global status functions or variables and all the NI 488 2 calls For more information about direct entry access refer to Directly Accessing the ni4882 dll Exports in C or Directly Accessing the gpib 32 dll Exports in C in the NI 488 2 Help OS X NI 488 2 provides NI4882 framework which can be used from 32 bit and 64 bit C C applications Refer to the Language Specific Programming Instructions for OS
53. OL SYSTEMS LIFE SAVING OR LIFE SUSTAINING SYSTEMS OR SUCH OTHER MEDICAL DEVICES OR ANY OTHER APPLICATION IN WHICH THE FAILURE OF THE PRODUCT OR SERVICE COULD LEAD TO DEATH PERSONAL INJURY SEVERE PROPERTY DAMAGE OR ENVIRONMENTAL HARM COLLECTIVELY HIGH RISK USES FURTHER PRUDENT STEPS MUST BE TAKEN TO PROTECT AGAINST FAILURES INCLUDING PROVIDING BACK UP AND SHUT DOWN MECHANISMS NI EXPRESSLY DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY OF FITNESS OF THE PRODUCTS OR SERVICES FOR HIGH RISK USES Contents About This Manual Using the NI 488 2 Documentation cccccccessessessesseescescesceseeeeseeeeseceeceececeaeeeeaeeaeeae ix Windows seene ene etuer rnEeE ENESE nE EAEE NGS ix OSK E E EEE AO E EA E i Accessing the NI 488 2 Help Conventions eecececeseeseceeeesseeeees Related Documentation nsoscrnisneiezoiisoririiiiiri naii i ENEE E A Chapter 1 Introduction Setting Up and Configuring Your System e ssssesssssessesesstsesssetseseeessrsesseestserseseeessesess 1 1 Controlling More Than One Interface 1 2 Configuration Requirement cccccccecssssessessesseeeceseeeeseeseceeceecaeceaeeaeaaecsecaeeaeeaeeneens 1 2 Chapter 2 Measurement amp Automation Explorer Windows OVETVIEW soniri tiei A AREE AOR EE EER E E E 2 1 Starting Measurement amp Automation Explorer sesesessssesesseessrsessesessserststeesesessesesssees 2 1 Troubleshoot NI 488 2 Problems cccccccesccsssceecessees
54. Polling say Implementing a Parallel Poll eee eceseeeceesesseeeeeceseseeeceeceeecseseceeceeeecneseeeeeaeeenets 8 13 Appendix A GPIB Basics Appendix B Status Word Conditions Appendix C Error Codes and Solutions Appendix D Common Questions Appendix E NI Services Glossary Index viii ni com About This Manual This manual describes the features and functions of the NI 488 2 software You can use the NI 488 2 software with Windows OS X and Linux Refer to the general readme file located on your installation media or in the installation directory for the operating system versions supported by the current version of NI 488 2 Using the NI 488 2 Documentation The following NI 488 2 documentation is available with your NI 488 2 software distribution media The Getting Started Installation Guide briefly describes how to install the NI 488 2 software and your GPIB hardware This manual describes the features and functionality of the NI 488 2 software The GPIB Hardware Installation Guide and Specifications contains detailed instructions on how to install and configure your GPIB hardware This guide also includes hardware specifications and compliance information To view these documents you need Adobe Acrobat Reader which you can download from www adobe com Windows To view these documents insert your NI 488 2 software distribution media and select the View Documentation option The View
55. Start GPIB Explorer as described in Chapter 3 GPIB Explorer OS X and Linux 2 From the menu bar select Tools NI I O Trace Debugging Existing Applications Once you know which NI 488 2 call fails refer to Appendix B Status Word Conditions and Appendix C Error Codes and Solutions for help understanding why the NI 488 2 call failed This information is also available in the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual Performance Considerations NI I O Trace can slow down the performance of your NI 488 2 application and certain configurations of NI I O Trace have a larger impact on performance than others For example configuring NI I O Trace to record calls to an output file or to use full buffers might have a significant impact on the performance of both your application and your system For this reason use NI I O Trace only while you are debugging your application or in situations where performance is not critical For more information about using NI I O Trace select Help Help Topics in NI I O Trace National Instruments 5 1 Chapter 5 Debugging Your Application Global Status Functions At the end of each NI 488 2 call the global status functions Ibsta Iberr and Ibcnt are updated If you are developing an NI 488 2 application you should check for errors after each NI 488 2 call If a NI 488 2 call failed the high bit of Ibsta
56. Status Word Conditions and Appendix C Error Codes and Solutions for help understanding why the NI 488 2 call failed This information is also available in the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual Viewing Properties for Recorded Calls To see the detailed properties of any call recorded in the main NI I O Trace window double click on the call The NI I O Trace Property Sheet window appears It contains general input output and buffer information as applicable to each call Exiting NI I O Trace When you exit NI I O Trace its current configuration is saved and used to configure NI I O Trace when you start it again Unless you save the data captured in NI I O Trace before you exit that information is lost To save the captured data stop the capture by clicking on the red button on the toolbar Then select File Save As to save the data in a spy file After you save your data select File Exit to exit the NI I O Trace utility Performance Considerations NI I O Trace can slow down the performance of your NI 488 2 application and certain configurations of NI I O Trace have a larger impact on performance than others For example configuring NI I O Trace to record calls to an output file or to use full buffers might have a significant impact on the performance of both your application and your system For this reason use NI I O Trace
57. a 32 bit application on a 64 bit system you must provide the m32 option as shown in the following examples gcc m32 prog c 1ni4882 or g m32 prog cpp 1ni4882 To have the library dynamically loaded on demand when your application accesses the library include ni4882 o during the link phase of your application as shown in the following examples gcc prog c ni4882 0 ldl or g prog cpp ni4882 0 ldl The file ni4882 o contains code to dynamically load the library This file is located in usr local natinst ni4882 lib and usr local natinst ni4882 lib64 The advantage of the latter way of compiling and linking your application is that it allows your application to run regardless of whether the NI 488 2 software is installed as long as it does not make any NI 488 2 calls National Instruments 4 19 Debugging Your Application This chapter describes several ways to debug your application NI I O Trace The NI T O Trace utility monitors NI 488 2 API calls made by NI 488 2 applications If an application does not have built in error detection handling you can use NI I O Trace to determine which NI 488 2 call is failing Starting NI I O Trace Windows To start NI I O Trace complete the following steps 1 Start MAX as described in Chapter 2 Measurement amp Automation Explorer Windows 2 From the menu bar select Tools NI I O Trace OS X and Linux To start NI I O Trace complete the following steps 1
58. able can transfer data faster than four HS488 devices connected by 4 m of cable Waiting for GPIB Conditions You can use the ibwait function to obtain the current ibsta value or to suspend your application until a specified condition occurs on the GPIB If you use ibwait with a parameter of zero it immediately updates ibsta and returns If you want to use ibwait to wait for one or more events to occur pass a wait mask to the function The wait mask should always include the TIMO event otherwise your application is suspended indefinitely until one of the wait mask events occurs Asynchronous Event Notification in NI 488 2 Applications NI 488 2 applications can asynchronously receive event notifications using the ibnotify function This function is useful if you want your application to be notified asynchronously about the occurrence of one or more GPIB events For example you might choose to use ibnotify if your application only needs to interact with your GPIB device when it is requesting service After calling ibnotify your application does not need to check the status of your GPIB device Then when your GPIB device requests service the NI 488 2 driver automatically notifies your application that the event has occurred by invoking a callback function The callback function is registered with the NI 488 2 driver when the ibnotify call is made National Instruments 8 3 Chapter 8 NI 488 2 Programming Techniques Calling the
59. about your GPIB ENET 1000 network settings refer to the GPIB ENET 1000 information in the GPIB Hardware Installation Guide and Specifications Device Configuration Use the GPIB Ethernet Device Configuration web page if you need to configure the GPIB ENET 1000 network parameters manually If your network uses DHCP the network configuration is performed automatically at startup and you do not need to run this utility unless you want to change the hostname Consult your network administrator if you do not know whether your network uses DHCP 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Expand Devices and Interfaces and then expand Network Devices 3 Right click your GPIB ENET 1000 interface and select Device Configuration from the drop down menu that appears The GPIB Ethernet Device Configuration web page should launch in a browser window 2 8 ni com NI 488 2 User Manual Update GPIB ENET 1000 Firmware You can run the Firmware Update utility as follows 1 2 3 Start MAX as described in the Starting Measurement amp Automation Explorer section Expand Devices and Interfaces and then expand Network Devices Right click your GPIB ENET 1000 interface and select Device Configuration from the drop down menu that appears The GPIB Ethernet Device Configuration web page should launch in a browser window In the Details section of the GPIB Ethernet Device Configuration web page fi
60. aitSRQ 0 amp WaitResult if WaitResult 8 12 ni com NI 488 2 User Manual printf SRQ is asserted n FindRQS 0 AddrList amp SerialPollResponse if Ibsta amp ERR printf Device at pad x returned byte Sx n AddrList Ibcnt int SerialPollResponse DevicePad AddrList Ibcnt DeviceResponse SerialPollResponse return Example 2 Using AllSpoll This example shows you how to use Al1Spo11 to serial poll three devices with a single call void GetAllSerialPollResponses Addr4882 t AddrList short ResponseList int WaitResult WaitSRQ 0 amp WaitResult if WaitResult printf SRQ is asserted n AllSpoll 0 AddrList ResponseList if Ibsta amp ERR for i 0 AddrList i NOADDR i printf Device at pad x returned byte x n AddrList i ResponseList i return Parallel Polling Although parallel polling is not widely used it is a useful method for obtaining the status of more than one device at the same time The advantage of parallel polling is that a single parallel poll can easily check up to eight individual devices at once In comparison eight separate serial polls would be required to check eight devices for their serial poll response bytes The value of the individual status bit ist determines the parallel poll response Implementing a Parallel Poll You can implement parallel polling with
61. ar To start the Interactive Control utility complete the following steps Windows 1 Select Start Programs National Instruments Measurement amp Automation to start MAX 2 Expand Devices and Interfaces and Locate Your GPIB Interface National Instruments 7 1 Chapter 7 Interactive Control Utility 3 Right click your GPIB interface and select Interactive Control from the drop down menu that appears OS X Double click Applications National Instruments NI 488 2 Interactive Control Linux Enter the following command usr local bin gpibintctrl To use the Interactive Control utility to test a sequence of NI 488 2 calls complete the following steps 1 Open either an interface handle or device handle to use for further NI 488 2 calls Use ibdev to open a device handle ibfind to open an interface handle or the set 488 2 command to switch to a 488 2 prompt The following example uses ibdev to open a device assigns it to access interface gpib0 chooses a primary address of 6 with no secondary address sets a timeout of 10 seconds T10s 13 enables the END message and disables the EOS mode ibdev enter board index 0 enter primary address 6 enter secondary address 0 enter timeout 13 enter EOI on last byte flag 1 enter end of string mode byte 0 udo A Note Ifyou type a command and no parameters Interactive Control prompts you for the necessary arguments If you already know the requ
62. ate with up to 100 GPIB interfaces Windows How can I determine which version of the NI 488 2 software I have installed To view the NI 488 2 software version complete the following steps 1 Start MAX as described in Chapter 2 Measurement amp Automation Explorer Windows 2 Expand the Software 3 Click NI 488 2 MAX displays the version number of the NI 488 2 software in the right window pane What do I do if my GPIB hardware is listed in the Windows Device Manager with a circled X or an exclamation point overlaid on it Refer to the Troubleshooting topics in the N 488 2 Help for information about what might cause this problem If you cannot resolve the problem contact National Instruments D 2 ni com NI 488 2 User Manual How can I determine which type of GPIB hardware I have installed Start MAX as described in Chapter 2 Measurement amp Automation Explorer Windows Then expand Devices and Interfaces MAX lists your installed GPIB hardware under Devices and Interfaces and Locate Your GPIB Interface Are interrupts and DMA required for the NI 488 2 software Generally plug in interface cards such as the PCI GPIB require interrupt resources in your computer Remote interfaces such as the GPIB USB and GPIB Ethernet products do not require interrupt resources in your computer There may be exceptions to this statement Refer to the general readme file located on your installation media or in the installat
63. before calling ibrd ibwrt RcvRespMsg or SendDataBytes e Avoid calling ibgts except immediately after an ibcmd call ibcmd causes ATN to be asserted EARG 4 EARG results when an invalid argument is passed to a function call The following are some examples e ibconfig with the IbcTMO option called with a value not in the range 0 through 17 e ibconfig with the IbcEOS option called with meaningless bits set in the high byte of the second parameter e ibconfig with the IbcPAD or IbcSAD option called with invalid addresses e ibppc called with invalid parallel poll configurations e A multi device NI 488 2 call made with an invalid address e PPollConfig called with an invalid data line or sense bit Solutions Make sure that the parameters passed to the NI 488 2 call are valid ESAC 5 ESAC results when ibsic ibsre SendIFC EnableRemote or the IbcSRE option in ibconfig is called when the GPIB interface does not have System Controller capability Solutions Give the GPIB interface System Controller capability by calling the IbcSc option in ibconfig or by using MAX to configure that capability into the software EABO 6 EABO indicates that an I O operation has been canceled usually due to a timeout condition Other causes are calling ibstop or receiving the Device Clear message from the CIC while performing an I O operation Frequently the I O is not progressing the Listener is not continuing to handsha
64. bles indicate the number of bytes read If you are sending data or commands the count variables reflect the number of bytes sent Using Interactive Control to Communicate with Devices Before you begin writing your application you might want to use the Interactive Control utility to communicate with your instruments interactively by typing in commands from the keyboard rather than from an application You can use the Interactive Control utility to learn to communicate with your instruments using the NI 488 2 API For specific device communication instructions refer to the user manual that came with your instrument For information about using the Interactive Control utility and detailed examples refer to Chapter 7 Interactive Control Utility Programming Models Applications That Communicate with a Single GPIB Device This section describes items you should include in your application and provides general program steps with an NI 488 2 example Items to Include Include the following items in your application Header files In a C application include the header file ni4882 h which contains prototypes for the NI 488 2 calls and constants that you can use in your application Error checking Check for errors after each NI 488 2 call Error handling Declare and define a function to handle NI 488 2 errors This function takes the device offline and closes the application If the function is declared as void
65. brsp failed No more callbacks n DeviceError TRUE return 0 If the returned status byte equals the expected response then the device has valid data to send otherwise it has a fault condition to report if SpollByte expectedResponse printf Device returned invalid response Status byte 0x x n SpollByte DeviceError TRUE return 0 Read the data from the device If the ERR bit is set in LocallIbsta then print an error message and return LocallIbsta ibrd LocalUd ReadBuffer 40L if LocalIbsta amp ERR printf ibrd failed No more callbacks n DeviceError TRUE return 0 The string returned by ibrd is a binary string whose length is specified by the byte count in ibcntl However many GPIB instruments return ASCII data strings and this example makes this assumption Because of this it is possible to add a NULL character to the end of the data received and use the printf function to display the ASCII data The following code illustrates that ReadBuffer ibcntl 0 Convert the data into a numeric value sscanf ReadBuffer Sf amp Readings ReadingsTaken Display the data Printf Reading f n Readings ReadingsTaken ReadingsTaken 1 if ReadingsTaken gt 1000 return 0 else Issue a request to the device to send the data and rearm callback on RQS LocallIbsta ibwrt LocalUd SEND DATA 9L
66. carry both data and command messages A 2 ni com NI 488 2 User Manual Handshake Lines Three hardware handshake lines asynchronously control the transfer of message bytes between devices This process is a three wire interlocked handshake and it guarantees that devices send and receive message bytes on the data lines without transmission error Table A 2 summarizes the GPIB handshake lines Table A 2 GPIB Handshake Lines Line Description NRFD Listening device is ready not ready to receive a message byte Also not ready for data used by the Talker to signal high speed HS488 GPIB transfers NDAC Listening device has has not accepted a message byte not data accepted DAV Talking device indicates signals on data lines are stable valid data data valid Interface Management Lines Five hardware lines manage the flow of information across the bus Table A 3 summarizes the GPIB interface management lines Table A 3 GPIB Interface Management Lines Line Description ATN Controller drives ATN true when it sends commands and false when it attention sends data messages IFC System Controller drives the IFC line to initialize the bus and make interface clear itself CIC REN System Controller drives the REN line to place devices in remote or remote enable local program mode SRQ Any device can drive the SRQ line to asynchronously request service service request from the
67. ce to the acceptor handshake function of another device DAV NRFD and NDAC three GPIB lines are used in an interlocked fashion to signal the phases of the transfer so that bytes can be sent asynchronously for example without a clock at the speed of the slowest device For more information about handshaking refer to the ANSI IEEE Standard 488 1 2003 Hexadecimal A number represented in base 16 For example decimal 16 is hex 10 See device level function A high speed data transfer protocol for IEEE 488 This protocol increases performance for GPIB reads and writes up to 8 Mbytes s depending on your system Hertz Input output In this manual it is the transmission of commands or messages between the system via the GPIB board and other devices on the GPIB The address of the GPIB board from the point of view of the CPU as opposed to the GPIB address of the GPIB board Also called port address or board address After each NI 488 2 I O call this global variable contains the actual number of bytes transmitted On systems with a 16 bit integer such as MS DOS ibcnt isa 16 bit integer and ibcnt1 is a 32 bit integer For cross platform compatibility use ibcnt1 unless using the newer NI4882 API For accessing the newer NI4882 API use the global function Ibcnt instead Lbeon ibcentl iberr Iberr ibsta Ibsta IEEE interface message ISA ist NI 488 2 User Manual After each NI 488 2 call
68. cess NI 488 2 globals substitute a call to get the corresponding per thread NI 488 2 global For example you can replace the following line of code if Ibsta amp ERR with if ThreadIbsta amp ERR 4 Note Ifyou are using ibnotify in your application refer to the Asynchronous Event Notification in NI 488 2 Applications section the ibnotify callback is executed in a separate thread that is created by the NI 488 2 driver Therefore if your application makes NI 488 2 calls from the ibnotify callback function and makes NI 488 2 calls from other places you must use the ThreadIbsta ThreadIberr and ThreadIbcnt functions described in this section instead of the per process NI 488 2 globals Device Level Calls and Bus Management The device level traditional NI 488 2 calls are designed to perform all of the GPIB management for your application However the NI 488 2 driver can handle bus management only when the GPIB interface is CIC Controller In Charge Only the CIC is able to send command bytes to the devices on the bus to perform device addressing or other bus management activities If your GPIB interface is configured as the System Controller default it automatically makes itself the CIC by asserting the IFC line the first time you make a device level call Ifthe current CIC does not pass control the NI 488 2 driver returns the ECIC error code to your application If this happens you could send a device specific command
69. d e Most functions with an ibconfig have been removed Using ibconfig is recommended for new code Existing functions redirect to using ibconfig using macros These are the affected functions ibpad ibsad ibtmo ibeot ibrse ibsre ibeos ibdma ibist ibrsv e Many macro definitions have been improved for programmatic safety Modifying existing applications to use the NI4882 API should require minimal changes In most cases using the new include file ni 4882 h instead of ni488 h and linking to the new object file Windows ni4882 o0bj instead of gpib 32 obj Linux 1i6ni4882 so instead of libgpibapi so OS X ni4882 framework instead of ni488 framework There may still be warnings due to changes to the signed property of the status variable type National Instruments 4 3 Chapter 4 Developing Your NI 488 2 Application Complications may arise in several uncommon use cases The following issues have been encountered e Storing function pointers for the ibnotify callback This causes a type mismatch on the assignment To solve this fix the function prototype of the callback to use unsigned int for the status parameters e Using function pointers to ibf ind This causes a preprocessor error because the ibfind macro requires a one parameter argument To solve this point to ibfindA or ibfindw depending on the unicode convention in your application e Configuration functions show up in NI
70. d to manage the GPIB Industry Standard Architecture An Individual Status bit of the status byte used in the Parallel Poll Configure function National Instruments G 5 Glossary L LAD Listener LLO low level function M MAV MLA MSA MTA multitasking N NDAC NRFD G 6 ni com Listen Address See also MLA A GPIB device that receives data messages from a Talker Local Lockout The GPIB command used to tell all devices that they may or should ignore remote GPIB data messages or local front panel controls depending on whether the device is in local or remote program mode A rudimentary board or device function that performs a single operation Meters The Message Available bit is part of the IEEE 488 2 defined status byte which is received from a device responding to a serial poll My Listen Address A GPIB command used to address a device to be a Listener It can be any one of the 31 primary addresses My Secondary Address The GPIB command used to address a device to be a Listener or a Talker when extended two byte addressing is used The complete address is a MLA or MTA address followed by an MSA address There are 31 secondary addresses for a total of 961 distinct listen or talk addresses for devices My Talk Address A GPIB command used to address a device to be a Talker It can be any one of the 31 primary addresses The concurrent processing of more than one program
71. device Receive address count termination Receive data from a device ReceiveSetup address Receive setup ResetSys addrlist Reset multiple devices 7 8 ni com NI 488 2 User Manual Table 7 3 Syntax for Multi Device NI 488 2 Calls in Interactive Control Continued Syntax Description Send address buffer eotmode Send data to a device SendCmds buffer Send command bytes SendDataBytes buffer eotmode Send data bytes SendIFC Send interface clear SendList addrlist buffer eotmode Send data to multiple devices SendLLOoO Put devices in local lockout SendSetup addrlist Send setup SetRWLS addrlist Put devices in remote with lockout state TestSRO Test for service request ie TestSys addrlist Cause multiple devices to perform self tests a rigger address Trigger a device TriggerList addrlist Trigger multiple devices WaitSRQ Wait for service request Table 7 4 Auxiliary Functions in Interactive Control Function Description set udname Select active device or interface where udname is the symbolic name of the new device or interface for example dev1 or gpib0 Call ibfind or ibdev initially to open each device or interface set 488 2 v Start using multi device NI 488 2 calls for interface v help Display the Interactive Control utility hel
72. devices into their configuration mode Non HS488 devices should ignore this message The second byte is a GPIB secondary command that indicates the number of meters of cable in your system It is called the Configure CFGn message Because HS488 can operate only with cable lengths of 1 to 15 m only CFGn values of 1 through 15 hex 61 through 6F are valid If the cable length was configured properly in the GPIB Configuration utility you can determine how 8 2 ni com NI 488 2 User Manual many meters of cable are in your system by calling ibask option IbaHSCableLength in your application For more information about CFE and CFGn messages refer to the Multiline Interface Messages topic in the NJ 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual System Configuration Effects on HS488 Maximum HS488 data transfer rates can be limited by your host computer and GPIB system setup For example when using a PC compatible computer with PCI bus the maximum obtainable transfer rate is 8 Mbytes s but when using another bus such as USB or Ethernet the maximum data transfer rate depends on the maximum transfer rate of that bus The same IEEE 488 cabling constraints for a 350 ns T1 delay apply to HS488 As you increase the amount of cable in your GPIB configuration the maximum data transfer rate using HS488 decreases For example two HS488 devices connected by two meters of c
73. dows 2 6 GPIB web site 2 7 3 5 gpib 32 dll exports National Instruments 1 3 Index accessing directly 4 16 using to invoke functions 4 13 GPIB ENET 100 network settings viewing or changing 2 8 3 5 configuring network parameters 2 8 GPIB ENET 1000 network settings viewing or changing 2 8 3 5 configuring network parameters 2 8 updating GPIB ENET 1000 firmware 2 9 H handshake lines A 3 help accessing 2 7 3 4 Linux x OS X x Windows x NI I O Trace help 2 5 6 2 NI 488 2 Help 2 7 3 4 technical support E 2 Help display Interactive Control utility help function table 7 9 Help option function Interactive Control utility 7 9 high speed data transfers HS488 cable length 8 2 enabling HS488 8 2 system configuration effects 8 3 HS488 See high speed data transfers l ibask function 8 3 ibclr function clearing a device 4 9 using in Interactive Control utility example 7 2 Ibent or ibent 4 8 ibconfig function determining assertion of EOI line 8 2 enabling autopolling 8 10 enabling high speed data transfers 8 2 ibconfig changing cable length 8 2 ibdev function opening devices 4 9 l 4 ni com using in Interactive Control utility example 7 2 Iberr or iberr determining error type 4 7 ibnotify function calling 8 4 programming example 8 5 ibnotify asynchronous event notification 8 4 ibonl function placing device offline 4 9 using in Interactive Control utility
74. e SendList to send the IDN query command to multiple GPIB devices The address is the list of GPIB devices to be queried The buffer that you pass to SendList is the command message to the device Step 4b Use Receive for each device to read the responses from each device Continue communicating with the GPIB devices until you are finished Cleanup Step 5 Place the Interface Offline before Exiting Your Application Use ibon1 to put the interface offline before you exit the application National Instruments 4 11 Chapter 4 Developing Your NI 488 2 Application Language Specific Programming Instructions for Windows The following sections describe how to develop compile and link your Windows NI 488 2 applications using various programming languages Microsoft Visual C C Version 6 0 or Later Before you compile your application include the following line at the beginning of your program include ni4882 h The NIEXTCCOMPILERSUPP environment variable is provided as an alias to the location of C language support files You can use this variable when compiling and linking an application With Microsoft Visual C Version 6 0 or later to compile and link a Win32 console application named cprog ina DOS shell or Visual C s Command Prompt using the environment variable NIEXTCCOMPILERSUPP type in the following on the command line cl I SNIEXTCCOMPILERSUPP include cprog c SNIEXTCCOMPILERSUPP 1ib32 msvc
75. e given primary address are tested and 4 10 ni com NI 488 2 User Manual the GPIB address of any devices found is stored in the GPIB addresses list When you have the list of GPIB addresses you can determine which one corresponds to your instrument and use it for subsequent calls Alternately if you already know your GPIB device s primary and secondary address you can create an appropriate GPIB address to use in subsequent NI 488 2 calls as follows a GPIB address is a 16 bit value that contains the primary address in the low byte and the secondary address in the high byte If you are not using secondary addressing the secondary address is 0 For example if the primary address is 1 then the 16 bit value is 0x01 otherwise if the primary address is 1 and the secondary address is 0x67 then the 16 bit value is 0x6701 Step 3 Initialize the Devices Use DevClearList to clear the devices on the GPIB The first argument is the GPIB interface number The second argument is the list of GPIB addresses that were found to be listening as determined in Step 2 Device Communication Step 4 Communicate with the Devices Communicate with the devices by sending them the IDN query and then reading back the responses Many devices respond to this query by returning a description of the device Refer to the documentation that came with your GPIB devices to see specific instruction on the proper way to communicate with them Step 4a Us
76. ecesseseecscesseeeeecsseeeecseceseecaseneeeenees 2 1 Add a New GPIB Interface Locate Your GPIB Interface Remove a GPIB Interface Scan for GPIB I strum nts seenen e aana a E aaia aai aty Instruments Not Fo dy rocr an an En TAE EE T a i Too Many Listeners on the GPIB ccceeeeesceeceseeseeseeseceeceecaecasesaecsecsecaecaeeneeneees 2 3 Communicate with Your Instrument 0 c cccccccesccssecescecseceecessecsecescesseceseecseceseesaeenesessens 2 3 Basic Communication Query Write Read 1 2 4 Advanced Communication 2 5 Monitor and Record NI 488 2 Calls 2 5 View or Change GPIB Interface Settings cccsesseescesceseeseeeeceeceeceececeaecnecaecaeeneentente 2 6 View GPIB Instrumentation Information cccccccsccecessecsscessesseceseecsecescessecneeesseseeeaaes 2 6 Change GPIB Device Teinp lates scscic sscssetetschsaycactecescts chetetesseaslepagelab cantante EREE 2 6 Enable Disable NI 488 2 DOS Support ceccsesseeseeeesenceeceseeeeeceeceeeeceesevseceeeessesarenees 2 7 Access Additional Help and Resources 2 7 NI 488 2 Help ccceccccecesesceseeteteeeeeeenes 2 7 National Instruments GPIB Website 2 7 View or Change GPIB ENET 100 Network Settings 0 0 00 ceeeeeecneeeceeeeeeeceeseeeenees 2 8 Device Configuration seen be liteon adden aa a o rE N 2 8 View or Change GPIB ENET 1000 Network Settings irns eeraa rinra E EEA OAA AEAT AIT OAE 2 8 De
77. echnicians using only original parts at a National Instruments service center Calibration Through regular calibration you can quantify and improve the measurement performance of an instrument NI provides state of the art calibration services If your product supports calibration you can obtain the calibration certificate for your product at ni com calibration System Integration If you have time constraints limited in house technical resources or other project challenges National Instruments Alliance Partner members can help To learn more call your local NI office or visit ni com alliance National Instruments E 1 Appendix E NI Services For information about other technical support options in your area visit ni com services Training and Certification The NI training and certification program is the most effective way to increase application development proficiency and productivity Visit ni com training for more information The Skills Guide assists you in identifying the proficiency requirements of your current application and gives you options for obtaining those skills consistent with your time and budget constraints and personal learning preferences Visit ni com skills guide to see these custom paths Nloffers courses in several languages and formats including instructor led classes at facilities worldwide courses on site at your facility and online courses to serve your individual needs
78. echniques if ud lt 0 printf ibdev failed n return 0 Issue a request to the device to send the data If the ERR bit is set in ibsta then print an error message that the call failed and exit the program ibwrt ud SEND DATA 9L if Ibsta amp ERR printf unable to write to device n return 0 set up the asynchronous event notification on RQS ibnotify ud RQS MyCallback NULL if Ibsta amp ERR printf ibnotify call failed n return 0 while ReadingsTaken lt 1000 amp amp DeviceError Your application does useful work here For example it might process the device readings or do any other useful work disable notification ibnotify ud 0 NULL NULL Call the ibonl function to disable the hardware and software ibon1 ud 0 return 1 int __stdcall MyCallback int LocalUd int LocalIbsta int LocalIberr 8 6 long LocalIbcntl void RefData char SpollByte char ReadBuffer 40 If the ERR bit is set in LocalIbsta then print an error message and return if LocallIbsta amp ERR printf GPIB error d has occurred No more callbacks n LocallIberr DeviceError TRUE return 0 Read the serial poll byte from the device If the ERR bit is set in LocalIbsta then print an error message and return ni com NI 488 2 User Manual LocallIbsta ibrsp LocalUd amp SpollByte if LocalIbsta amp ERR printf i
79. eclare and define a function to handle NI 488 2 errors This function takes the device offline and closes the application If the function is declared as void gpiberr char msg function prototype then your application invokes it as follows if Ibsta amp ERR gpiberr NI 488 2 error General Program Steps and Examples The following steps show you how to use the multi device NI 488 2 calls in your application The NI 488 2 software includes the 4882query source code examples to demonstrate these principles Initialization Step 1 Become Controller In Charge CIC Use SendIFC to initialize the bus and the GPIB interface so that the GPIB interface is Controller In Charge CIC The only argument of SendIFC is the GPIB interface number typically 0 for GPIBO Step 2 Determine the GPIB Address of Your Device Use FindLstn to find all the devices attached to the GPIB The FindLstn function requires the following parameters e Interface number typically 0 for GPIBO e A list of primary addresses terminated with the NOADDR constant e A list for reported GPIB addresses of devices found listening on the GPIB e Limit which is the number of the GPIB addresses to report Use FindLstn to test for the presence of all of the primary addresses that are passed to it Ifa device is present at a particular primary address then the primary address is stored in the GPIB addresses list Otherwise all secondary addresses of th
80. ecording NI 488 2 calls on Windows 2 5 monitoring API calls with 6 2 overview 6 1 performance considerations 5 1 6 3 National Instruments l 5 Index saving captured data to a file 6 3 starting 5 1 6 1 viewing properties for recorded calls 6 3 NI MAX Self Test 2 1 C 2 C 5 D 2 NI 488 2 common questions D 1 device level calls and bus management 8 9 SRQ and serial polling with device level NI 488 2 calls 8 11 SRQ and serial polling with multi device NI 488 2 calls 8 12 NI 488 2 API choosing how to access 4 2 choosing how to use 4 4 dynamic link library 4 2 NI 488 2 calls examples in Interactive Control utility 7 2 Interactive Control utility syntax board level calls table 7 6 device level calls table 7 5 multi device calls table 7 8 parallel polling multi device calls 8 15 SRQ and serial polling 8 11 8 12 NI 488 2 Communicator 2 4 sample screen figure 2 4 NI 488 2 programming techniques Borland C C 4 12 direct entry with C 4 13 Linux 4 19 Microsoft Visual C C 4 12 OS X 4 18 Visual Basic 4 13 NI 488 2 Troubleshooting Wizard 3 1 C 2 C 5 D 2 ni4882 dll exports accessing directly 4 14 NRFD not ready for data line table A 3 O Online help See help OS X GPIB Explorer 3 1 programming instructions 4 18 l 6 ni com P parallel polling implementing 8 13 using NI 488 2 calls multi device 8 15 traditional 8 14 PPoll routine 8 15 PPollConfig routine
81. ents Right click your GPIB interface and select Scan for Instruments from the drop down menu that appears Refer to the Scan for GPIB Instruments section for more information MAX displays the connected instruments below your GPIB interface Right click your GPIB instrument in the left window pane and select Communicate with Instrument from the drop down menu that appears The NI 488 2 Communicator dialog box appears as shown in Figure 2 1 Figure 2 1 NI 488 2 Communicator NI 488 2 Communicator GPIBO InstrumentO Primary Address 3 Globals Status ibsta 0x100 Cue krite Leoead i ber None ibenti 4 Send String IDN Configured String Received CMPL Show Sample Configure EOS Type a command in the Send String field and do one of the following To write a command to the instrument then read a response back click the Query button To write a command to the instrument click the Write button e To read a response from the instrument click the Read button To view sample C C code that performs a simple query of a GPIB instrument click the Show Sample button 2 4 ni com NI 488 2 User Manual Advanced Communication For advanced interactive communication with GPIB instruments use the Interactive Control utility as follows 1 2 3 Start MAX as described in the Starting Measurement amp Automation Explorer section Expand Devices and
82. er Windows OS X Run Applications National Instruments NI 488 2 Troubleshooting Wizard Linux Enter the following command usr local bin gpibtsw Use the unit descriptor returned from ibdev or ibfind as the first parameter in subsequent traditional NI 488 2 calls Examine the variable before the failing function to make sure its value has not been corrupted ECIC 1 ECIC is returned when one of the following functions is called while the interface is not CIC C 2 Any device level traditional NI 488 2 calls that affect the GPIB Any board level traditional NI 488 2 calls that issue GPIB command bytes ibcmd ibcmda ibln and ibrpp ibcac and ibgts Any NI 488 2 multi device calls that issue GPIB command bytes SendCmds PPo11 Send and Receive ni com NI 488 2 User Manual Solutions Possible solutions for this error are as follows e Use ibsic or SendIFC to make the GPIB interface become CIC on the GPIB e Use the IbcSC option in ibconfig to make sure your GPIB interface is configured as System Controller In multiple CIC situations always be certain that the CIC bit appears in the status word Ibsta before attempting these calls Ifit does not appear you can perform an ibwait for CIC call to delay further processing until control is passed to the interface ENOL 2 ENOL usually occurs when a write operation is attempted with no Listeners addressed For a device write ENOL indicates that the
83. er materials belonging to others you may use NI software only to reproduce materials that you may reproduce in accordance with the terms of any applicable license or other legal restriction End User License Agreements and Third Party Legal Notices You can find end user license agreements EULAs and third party legal notices in the following locations e Notices are located in the lt National Instruments gt _Legal Information and lt National Instruments gt directories e EULAs are located in the lt National Instruments gt Shared MDF Legal license directory e Review lt National Instruments gt Legal Information txt for information on including legal information in installers built with NI products U S Government Restricted Rights If you are an agency department or other entity of the United States Government Government the use duplication reproduction release modification disclosure or transfer of the technical data included in this manual is governed by the Restricted Rights provisions under Federal Acquisition Regulation 52 227 14 for civilian agencies and Defense Federal Acquisition Regulation Supplement Section 252 227 7014 and 252 227 7015 for military agencies Trademarks Refer to the NI Trademarks and Logo Guidelines at ni com trademarks for more information on National Instruments trademarks ARM Keil and Vision are trademarks or registered of ARM Ltd or its subsidiaries LEGO the LEGO logo WEDO and
84. er section 2 Select Help National Instruments on the Web GPIB Home Page National Instruments 2 7 Chapter 2 Measurement amp Automation Explorer Windows View or Change GPIB ENET 100 Network Settings To view or change the network settings of your GPIB ENET 100 refer to the following sections For more information about your GPIB ENET 100 network settings refer to the GPIB ENET 100 information in the GPIB Hardware Guide Device Configuration Use the NI Ethernet Device Configuration utility if you need to manually configure the network parameters of the GPIB ENET 100 If your network uses DHCP the network configuration is performed automatically at startup and you do not need to run this utility unless you want to change the hostname Consult your network administrator if you do not know whether your network uses DHCP 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Expand Devices and Interfaces and then expand Network Devices 3 Right click your GPIB ENET 100 interface and select Device Configuration from the drop down menu that appears For more information about the NI Ethernet Device Configuration utility refer to the GPIB ENET 100 information in the GPIB Hardware Installation Guide and Specifications View or Change GPIB ENET 1000 Network Settings To view or change the network settings of your GPIB ENET 1000 refer to the following sections For more information
85. evice it can never serial poll the device and unassert SRQ e A GPIB bus tester or similar equipment might be forcing the SRQ line to be asserted e A cable problem might exist involving the SRQ line Although the occurrence of ESRQ warns you of a definite GPIB problem it does not affect GPIB operations except that you cannot depend on the Ibsta RQS bit while the condition lasts Solutions Check to see if other devices not used by your application are asserting SRQ Disconnect them from the GPIB if necessary National Instruments C 7 Appendix C Error Codes and Solutions ETAB 20 ETAB occurs only during the FindLstn and FindRQS functions ETAB indicates that there was some problem with a table used by these functions e Inthe case of FindLstn ETAB means that the given table did not have enough room to hold all the addresses of the Listeners found e In the case of FindROS ETAB means that none of the devices in the given table were requesting service Solutions In the case of FindLstn increase the size of result arrays In the case of FindRQS check to see if other devices not used by your application are asserting SRQ Disconnect them from the GPIB if necessary ELCK 21 ELCK indicates that the requested operation could not be performed because of an existing lock by another process accessing the same interface ELCK is also returned when a process attempts to unlock an interface for which it currently has
86. example 7 3 ibppc function 8 14 ibrd function reading response from device 4 9 using in Interactive Control utility example 7 3 ibrpp function 8 14 ibrsp function automatic serial polling 8 11 conducting single serial poll 8 11 Ibsta or ibsta bit layout definitions 4 6 B 1 return value information 4 6 ibwait function causing autopolling 8 11 Talker Listener applications 8 9 waiting for GPIB conditions 8 3 ibwrt function sending IDN query to device 4 9 using in Interactive Control utility example 7 3 IEEE 488 and IEEE 488 2 x IFC interface clear line table A 3 Interactive Control utility auxiliary functions table 7 9 commands 7 5 communicating with instruments 4 1 4 8 count 7 11 error information 7 10 getting started 7 1 NI 488 2 addresses 7 4 function examples 7 2 numbers 7 4 strings 7 4 overview 7 1 status word Ibsta 7 10 summary 2 5 syntax addresses 7 4 board level traditional NI 488 2 calls table 7 6 device level traditional NI 488 2 calls table 7 5 multi device NI 488 2 calls table 7 8 numbers 7 4 strings 7 4 interface management lines A 3 L LACS status word condition 4 7 B 1 B 4 Linux GPIB Explorer 3 1 programming instructions 4 19 listen address A 2 Listeners 8 9 A 1 too many found on GPIB 2 3 locating a GPIB interface in Measurement amp Automation Explorer 2 2 LOK status word condition 4 7 B 1 B 3 M Measurement amp Automat
87. fer to Chapter 4 Developing Your NI 488 2 Application How do I check for errors in my NI 488 2 application Examine the value of Ibsta after each NI 488 2 call Ifa call fails the ERR bit of Ibsta is set and an error code is stored in Iberr For more information about global status functions refer to Chapter 5 Debugging Your Application National Instruments D 1 Appendix D Common Questions How do I troubleshoot problems Use available tools to troubleshoot NI 488 2 problems Windows Use the NI MAX Self Test feature as described in Chapter 2 Measurement amp Automation Explorer Windows OS X Run Applications National Instruments NI 488 2 Troubleshooting Wizard e Linux Enter the following command usr local bin gpibtsw What information should I have before I call National Instruments Before you call National Instruments record the results of running Self Test Windows or the Troubleshooting Wizard OS X and Linux How can I determine if my GPIB hardware and the NI 488 2 software are installed properly e Windows Use the NI MAX Self Test feature as described in Chapter 2 Measurement amp Automation Explorer Windows e OS X Run Applications National Instruments NI 488 2 Troubleshooting Wizard e Linux Enter the following command usr local bin gpibtsw How many GPIB interfaces can I configure for use with the NI 488 2 software You can configure the NI 488 2 software to communic
88. functions are the status word Ibsta the error function Iberr and the count function Ibcnt They contain useful information about the performance of your application Your application should check these functions after each NI 488 2 call For more information about each status function refer to the following sections For applications accessing the older GPIB32 API including the Visual Basic 6 0 application interface use the equivalent global variables These global status variables are the status word ibsta the error variable iberr and the count variables ibcnt and ibcnt1 ibcnt is defined to be the type int while ibcnt1 is the size of type long int For all cases if the sizes of ibcnt and ibcntl are the same ibcnt and ibcnt1 are equal For cross platform compatibility all applications should use ibcnt1 For applications accessing the newer NI4882 API use the global function calls rather than the global variables The global functions replace the global variables with the newer NI4882 API Note If your application is a multithreaded application refer to the Writing Multithreaded NI 488 2 Applications section of Chapter 8 N 488 2 Programming Techniques Status Word Ibsta All calls update a global status function Ipsta which contains information about the state of the GPIB and your GPIB hardware You can examine various status bits in Ibsta and use that information to make decisions about continued processing If y
89. he N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual 1 Note The ibnotify callback is executed in a separate thread of execution from the rest of your application If your application will be performing other NI 488 2 operations while it is using ibnotify use the per thread NI 488 2 globals that are provided by the ThreadIbsta ThreadIberr and ThreadIbcnt functions described in the Writing Multithreaded NI 488 2 Applications section In addition if your application needs to share global variables with the callback use a synchronization primitive for example a semaphore to protect access to any globals For more information about the use of synchronization primitives refer to the documentation about using operating system synchronization objects that came with your development tools 8 4 ni com NI 488 2 User Manual ibnotify Programming Example The following code is an example of how you can use ibnotify in your application Assume that your GPIB device is a multimeter that you program to acquire a reading by sending SEND DATA The multimeter requests service when it has a reading ready and each reading is a floating point value In this example globals are shared by the Callback thread and the main thread and the access of the globals is not protected by synchronization In this case synchronization of access to these globals is not necessary beca
90. hould be listening or talking at any given moment Typically your computer is the GPIB Controller and it manages communication with your GPIB device by sending messages to it and receiving messages from it A talk address is formed by setting bit 6 the TA Talk Active bit of the GPIB address A listen address is formed by setting bit 5 the LA Listen Active bit of the GPIB address For example if a device is at address 1 the Controller sends hex 41 address 1 with bit 6 set to make the device a Talker Because the Controller is usually at primary address 0 it sends hex 20 address 0 with bit 5 set to make itself a Listener Table A 1 shows the configuration of the GPIB address bits Table A 1 GPIB Address Bits Bit Position 7 6 5 4 3 2 1 0 Meaning 0 TA LA GPIB Primary Address range 0 to 30 With some devices you can use secondary addressing A secondary address is a number in the range hex 60 to hex 7E When you use secondary addressing the Controller sends the primary talk or listen address of the device followed by the secondary address of the device Sending Messages across the GPIB Devices on the bus communicate by sending messages Signals and lines transfer these messages across the GPIB interface which consists of 16 signal lines and 8 ground return shield drain lines The 16 signal lines are discussed in the following sections Data Lines Eight data lines DIO1 through DIO8
91. ibnotify Function ibnotify has the following function prototype unsigned int ibnotify int ud unit descriptor int mask bit mask of GPIB events GpibNotifyCallback t Callback callback function void RefData user defined reference data Both board level and device level ibnotify calls are supported by the NI 488 2 driver If you are using device level calls you can call ibnotify with a device handle for ud and a mask of RQS CMPL END or TIMO If you are using board level calls you can call ibnotify witha board handle for ud and a mask of any values except RQS The ibnotify mask bits are identical to the ibwait mask bits In the example of waiting for your GPIB device to request service you might choose to pass ibnotify a mask with RQS for device level or SRQI for board level The callback function that you register with the ibnotify call is invoked by the NI 488 2 driver when one or more of the mask bits passed to ibnotify is TRUE The callback function is of type GPIBNotifyCallback_t and is defined in the gpib header file ni4882 h The callback function is passed a unit descriptor the current values of the NI 488 2 global variables and the user defined reference data that was passed to the original ibnotify call The NI 488 2 driver interprets the return value for the callback as a mask value that is used to automatically rearm the callback if it is non zero For a complete description of ibnot ify refer to t
92. ication must de reference the pointer to access the function call The following code shows you how to call a function and access the status function from within your application dvm Pibdev 0 1 0 T10s 1 0 if PThreadIbsta amp ERR ERR printf Call failed National Instruments 4 15 Chapter 4 Developing Your NI 488 2 Application Before exiting your application you need to free ni4882 d11 with the following command FreeLibrary ni4882Lib For more examples of directly accessing ni4882 d11 refer to the direct entry sample programs dlldevquery c and d114882query c installed with the NI 488 2 software For more information about direct entry refer to the help for your development environment Directly Accessing the gpib 32 dll Exports Make sure that the following lines are included at the beginning of your C application ifdef cplusplus extern C endif include lt windows h gt include ni488 h ifdef cplusplus endif In your Win32 application you need to load gpib 32 d11 before accessing the gpib 32 d11 exports The following code fragment shows you how to call the LoadLibrary function to load gpib 32 d11 and check for an error HINSTANCE Gpib32Lib NULL Gpib32Lib LoadLibrary GPIB 32 DLL if Gpib32Lib NULL return FALSE For the prototypes for each function refer to the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488
93. ification or contact your local office at ni com contact You also can visit the Worldwide Offices section of ni com niglobal to access the branch office websites which provide up to date contact information support phone numbers email addresses and current events E 2 ni com Glossary Symbol Prefix Value p pico 10 12 n nano 10 u micro 106 m milli 103 k kilo 103 M mega 106 G giga 10 T tera 10 2 A acceptor handshake access board ANSI API application interface ASCII asynchronous automatic serial polling Listeners use this GPIB interface function to receive data and all devices use it to receive commands See also source handshake and handshake The GPIB board that controls and communicates with the devices on the bus that are attached to it American National Standards Institute Application Programming Interface Formerly called language interface Code that enables an application program that uses NI 488 2 calls to access the driver American Standard Code for Information Interchange An action or event that occurs at an unpredictable time with respect to the execution of a program A feature of the GPIB software in which serial polls are executed automatically by the driver whenever a device asserts the GPIB SRQ line Also called autopolling National Instruments G 1 Glossary B base I O address BIOS board level func
94. ill perform substantially in accordance with the applicable documentation provided with the software and ii the software media will be free from defects in materials and workmanship If NI receives notice of a defect or non conformance during the applicable warranty period NI will in its discretion i repair or replace the affected product or ii refund the fees paid for the affected product Repaired or replaced Hardware will be warranted for the remainder of the original warranty period or ninety 90 days whichever is longer If NI elects to repair or replace the product NI may use new or refurbished parts or products that are equivalent to new in performance and reliability and are at least functionally equivalent to the original part or product You must obtain an RMA number from NI before returning any product to NI NI reserves the right to charge a fee for examining and testing Hardware not covered by the Limited Warranty This Limited Warranty does not apply if the defect of the product resulted from improper or inadequate maintenance installation repair or calibration performed by a party other than NI unauthorized modification improper environment use of an improper hardware or software key improper use or operation outside of the specification for the product improper voltages accident abuse or neglect or a hazard such as lightning flood or other act of nature THE REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND THE CUSTO
95. ing accessed Solutions Possible solutions for this error are as follows e Make sure the filename path and drive that you specified are correct e Make sure that the access mode of the file is correct e Make sure there is enough room on the disk to hold the file C 6 ni com NI 488 2 User Manual EBUS 14 EBUS results when certain GPIB bus errors occur during device functions All device functions send command bytes to perform addressing and other bus management Devices are expected to accept these command bytes within the time limit specified by the default configuration or the IbcTMO option in the ibconfig function EBUS results if a timeout occurred while sending these command bytes EBUS can occur if there are no functioning devices present on the GPIB Solutions Possible solutions for this error are as follows e Verify that the instrument is operating correctly e Check your cable connections and make sure at least two thirds of your devices are powered on e Ifthe timeout period is too short for the driver to send command bytes increase the timeout period ESRQ 16 ESRQ can only be returned by a device level ibwait call with RQS set in the mask ESRQ indicates that a wait for RQS is not possible because the GPIB SRQ line is stuck on This situation can be caused by the following events e Usually a device unknown to the software is asserting SRQ Because the software does not know of this d
96. ing buffer is automatically calculated within the actual function or subroutine which eliminates the need to pass in the length as an extra parameter For more information about function syntax for Visual Basic refer to the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual Before you run your Visual Basic application include the niglobal bas and vbib 32 bas files in your application project file Direct Entry with C Direct entry is available for 32 bit and 64 bit ni4882 d11s and the 32 bit gpib 32 d11 The following sections describe how to use direct entry with C DLL Exports gpib 32 d11 exports pointers to the global variables and all of the NI 488 2 calls Pointers to the global variables ibsta iberr ibcnt and ibcnt1 are accessible through these exported variables int user ibsta int user iberr int user_ibcnt long user_ibcntl Except for the functions that have string parameters such as ibfind ibrdf and ibwrtf all the NI 488 2 call names are exported from the DLL Thus to use direct entry to access a particular function and to get a pointer to the exported function you just need to call Get ProcAddress passing the name of the function as a parameter For more information about the parameters to use when you invoke the function refer to the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documen
97. ing the NI 488 2 Documentation section of About This Manual Termination of Data Transfers GPIB data transfers are terminated either when the GPIB EOI line is asserted with the last byte of a transfer or when a preconfigured end of string EOS character is transmitted By default EOI is asserted with the last byte of writes and the EOS modes are disabled You can use the ibconfig IbcEOT function to enable or disable the end of transmission EOT mode If EOT mode is enabled the GPIB EOI line is asserted when the last byte of a write is sent out on the GPIB If it is disabled the EOI line is not asserted with the last byte of a write You can use the ibconfig IbcEOS function to enable disable or configure the EOS modes EOS mode configuration includes the following information A 7 bit or 8 bit EOS byte EOS comparison method This indicates whether the EOS byte has seven or eight significant bits For a 7 bit EOS byte the eighth bit of the EOS byte is ignored EOS write method TIf this is enabled the GPIB EOI line is automatically asserted when the EOS byte is written to the GPIB If the buffer passed into an ibwrt call contains five occurrences of the EOS byte the EOI line is asserted as each of the five EOS bytes are written to the GPIB If an ibwrt buffer does not contain an occurrence of the EOS byte the EOI line is not asserted unless the EOT mode is enabled in which case the EOI line is asserted with the last byte
98. ion Explorer accessing additional help and resources 2 7 accessing help 2 7 adding new GPIB interface 2 2 changing GPIB device templates 2 6 communicating with instruments 2 3 enabling disabling NI 488 2 DOS support 2 7 locating a GPIB interface 2 2 monitoring and recording NI 488 2 calls 2 5 overview 2 1 removing GPIB interface 2 2 scanning for GPIB instruments 2 3 starting 2 1 NI 488 2 User Manual viewing GPIB instrumentation information 2 6 viewing or changing GPIB interface settings 2 6 viewing or changing GPIB ENET 100 network settings configuring network parameters 2 8 viewing or changing GPIB ENET 1000 network settings configuring network parameters 2 8 updating GPIB ENET 1000 firmware 2 9 Message Available bit MAV 8 10 messages sending across GPIB data lines A 2 handshake lines A 3 interface management lines A 3 Microsoft Visual Basic programming instructions 4 13 Microsoft Visual C C programming instructions 4 12 multiple interfaces or multiple devices 4 5 multithreaded NI 488 2 applications writing 8 8 N n execute function n times function Interactive Control utility 7 10 n execute previous function n times function Interactive Control utility 7 10 National Instruments GPIB web site 2 7 3 5 NDAC not data accepted line table A 3 NI I O Trace utility debugging applications 5 1 6 3 exiting 6 3 help 6 2 locating errors 6 2 monitoring and r
99. ion directory for the latest interface options supported by the current version of NI 488 2 DMA is not required for the NI 488 2 software National Instruments D 3 NI Services National Instruments provides global services and support as part of our commitment to your success Take advantage of product services in addition to training and certification programs that meet your needs during each phase of the application life cycle from planning and development through deployment and ongoing maintenance To get started register your product at ni com myproducts As a registered NI product user you are entitled to the following benefits e Access to applicable product services e Easier product management with an online account e Receive critical part notifications software updates and service expirations Log in to your National Instruments ni com User Profile to get personalized access to your services Services and Resources e Maintenance and Hardware Services NI helps you identify your systems accuracy and reliability requirements and provides warranty sparing and calibration services to help you maintain accuracy and minimize downtime over the life of your system Visit ni com services for more information Warranty and Repair All NI hardware features a one year standard warranty that is extendable up to five years NI offers repair services performed in a timely manner by highly trained factory t
100. ions 5 2 NI I O Trace utility 5 1 NI 488 2 error codes 5 2 application development communicating with instruments multiple interfaces or multiple devices 4 10 single GPIB device 4 8 using Interactive Control utility 4 1 using NI 488 2 Communicator 2 4 general program steps and examples multiple interface or multiple device applications 4 10 single device applications 4 9 items to include multiple interface or multiple device applications 4 10 single device applications 4 8 talker listener applications 8 9 application interfaces 4 2 asynchronous event notification in NI 488 2 applications calling ibnotify function 8 4 ibnotify programming example 8 5 ATN attention line table A 3 ATN status word condition 4 7 B 1 B 3 automatic serial polling enabling 8 10 stuck SRQ state 8 11 autopolling and interrupts 8 11 auxiliary functions Interactive Control utility 7 9 B Borland C C programming instructions 4 12 buffer option function Interactive Control utility 7 10 bus extenders and expanders 1 2 bus management and device level calls 8 9 C CIC status word condition 4 7 B 1 B 3 CMPL status word condition 4 7 B 1 B 3 communicating with instruments advanced communication 2 5 multiple devices 4 5 multiple interfaces 4 5 single GPIB device 4 5 using Interactive Control utility 4 8 using Measurement amp Automation Explorer 2 3 using NI 488 2 Communicator 2 4 communicati
101. ired arguments you can type them at the command prompt as follows ibdev 0 6 0 13 1 0 ud0 A Note Ifyou do not know the primary and secondary address of your GPIB instrument use Interactive Control to discover it First select 488 2 style by entering set 488 2 where represents the board number 0 to 99 to which you have connected your device Then use the FindLstn command to discover the address of your device For help using FindLstn enter help findlstn at the command prompt 2 After you successfully complete ibdev you have a ud prompt The new prompt udo represents a device level handle that you can use for further NI 488 2 calls To clear the device use ibclr as follows ud0 ibclr 0100 cmpl 7 2 ni com NI 488 2 User Manual To write data to the device use ibwrt Make sure that you refer to the documentation that came with your GPIB instrument for recognized command messages ud0 ibwrt enter string 0100 cmpl count 5 IDN Or equivalently ud0 ibwrt IDN 0100 cmpl count 5 To read data from your device use ibrd The data that is read from the instrument is displayed For example to read 29 bytes enter the following ud0 ibrd enter byte count 29 0100 cmpl count 29 46 4C 55 4B 45 2C 20 34 FLUKE 4 35 2C 20 34 37 39 30 31 5 47901 37 33 2C 20 31 2E 36 20 73 1 6 44 31 2E 30 OA D 10 Or equivalently ud0 ibrd 29 0100 cmpl count 29 46 4C 55 4B 45 2C 20 34 F
102. it from within MAX by completing the following steps 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Expand Devices and Interfaces and then expand Network Devices 3 Right click your GPIB Ethernet interface and select Delete from the context menu 4 When prompted confirm your selection 5 Select ViewRefresh to update the list of interfaces in Measurement amp Automation Explorer 2 2 ni com NI 488 2 User Manual Scan for GPIB Instruments To scan for instruments connected to your GPIB interface or to add a new instrument to your system complete the following steps 1 Make sure that your instrument is powered on and connected to your GPIB interface 2 Start MAX as described in the Starting Measurement amp Automation Explorer section 3 Expand Devices and Interfaces and Locate Your GPIB Interface 4 Right click your GPIB interface and select Scan for Instruments from the drop down menu that appears Connected instruments appear beneath the GPIB interface in the Measurement amp Automation Explorer configuration tree Instruments Not Found If MAX reports that it did not find any instruments make sure that your GPIB instruments are powered on and properly connected to the GPIB interface with a GPIB cable Then scan for instruments again as described in the Scan for GPIB Instruments section Too Many Listeners on the GPIB If MAX reports that it found too many Liste
103. itional NI 488 2 call ibrsp to conduct a serial poll ibrsp conducts a single serial poll and returns the serial poll response byte to the application If automatic serial polling is enabled the application can use ibwait to suspend program execution until RQS appears in the status word Ibsta The program can then call ibrsp to obtain the serial poll response byte The following example shows you how to use the ibwait and ibrsp functions in a typical SRQ servicing situation when automatic serial polling is enabled include ni4882 h char GetSerialPollResponse int DeviceHandle char SerialPollResponse 0 National Instruments 8 11 Chapter 8 NI 488 2 Programming Techniques ibwait DeviceHandle TIMO RQS if Ibsta amp RQS printf Device asserted SRQ n Use ibrsp to retrieve the serial poll response ibrsp DeviceHandle amp SerialPollResponse return SerialPollResponse SRQ and Serial Polling with Multi Device NI 488 2 Calls The NI 488 2 software includes a set of multi device NI 488 2 calls that you can use to conduct SRQ servicing and serial polling Calls pertinent to SRQ servicing and serial polling are AllSpoll ReadStatusByte FindRQS Test SRO and WaitSRQ Following are descriptions of each of the calls AllSpoll can serial poll multiple devices with a single call It places the status bytes from each polled instrument into a predefined array Then you must check the RQS bi
104. ke or the Talker has stopped talking or the byte count in the call which timed out was more than the other device was expecting C 4 ni com NI 488 2 User Manual Solutions Possible solutions for this error are as follows e Use the correct byte count in input functions or have the Talker use the END message to signify the end of the transfer Lengthen the timeout period for the I O operation using the IbcTMO option in ibconfig e Make sure that you have configured your device to send data before you request data ENEB 7 ENEB occurs when a GPIB interface is configured for use by the system but the driver cannot find the interface This problem happens when the interface is not physically plugged into the system the I O address specified during configuration does not match the actual interface setting or there is a system conflict with the base I O address Solutions Use troubleshooting tools to make sure there is a GPIB interface in your computer that is properly configured both in hardware and software and using a valid base I O address Windows Use the NI MAX Self Test feature as described in Chapter 2 Measurement amp Automation Explorer Windows OS X Run Applications National Instruments NI 488 2 Troubleshooting Wizard Linux Enter the following command usr local bin gpibtsw EOIP 10 EOIP occurs when an asynchronous I O operation has not finished before some other call is made During asy
105. lem It is unsafe to access process global functions from multiple threads of execution You can avoid this problem in two ways e Use synchronization to protect access to process global functions Do not use process global functions If you choose to implement the synchronization solution you must ensure that the code making NI 488 2 calls and examining the NI 488 2 globals modified by a NI 488 2 call is protected by a synchronization primitive For example each thread might acquire a semaphore before making a NI 488 2 call and then release the semaphore after examining the NI 488 2 globals modified by the call For more information about the use of synchronization primitives refer to your operating system documentation about synchronization objects supported by your operating system If you choose not to use process global functions you can access per thread copies of the NI 488 2 global variables using a special set of NI 488 2 calls Whenever a thread makes an NI 488 2 call the driver keeps a private copy of the NI 488 2 globals for that thread The 8 8 ni com NI 488 2 User Manual following code shows the set of functions you can use to access these per thread NI 488 2 global functions unsigned int ThreadIbsta return thread specific Ibsta unsigned int ThreadIberr return thread specific Iberr unsigned int ThreadIbcnt return thread specific Ibcnt In your application instead of accessing the per pro
106. mal numbers Enter the number only For example ibpad 22 sets the primary address to 22 decimal String Syntax You can enter strings as an ASCII character sequence hex bytes or special symbols ASCII character sequence You must enclose the entire sequence in quotation marks Hex byte You must use a backslash character and an x followed by the hex value For example hex 40 is represented by x40 Special symbols Some instruments require special termination or end of string EOS characters that indicate to the device that a transmission has ended The two most common EOS characters are r and n r represents a carriage return character and n represents a linefeed character You can use these special characters to insert the carriage return and linefeed characters into a string as in IDN r n Address Syntax Some of the NI 488 2 calls have an address or address list parameter An address is a 16 bit representation of the GPIB device address The primary address is stored in the low byte and the secondary address if any is stored in the high byte For example a device at primary address 6 and secondary address 0x67 has an address of 0x6706 A NULL address is represented as Oxffff An address list is represented by a comma separated list of addresses such as 1 0xb706 3 7 4 ni com NI 488 2 User Manual Interactive Control Commands Tables 7 1 and 7 2 summarize the syntax of the traditional NI 488 2 calls in the
107. n that you may find helpful as you read this manual e ANSI IEEE Standard 488 1 2003 JEEE Standard Digital Interface for Programmable Instrumentation ANSI IEEE Standard 488 2 1992 IEEE Standard Codes Formats Protocols and Common Commands GPIB Hardware Installation Guide and Specifications e NI 488 2 for Linux Installation Guide NI 488 2 for Mac OS X Getting Started x ni com Introduction This chapter describes how to set up your GPIB system Setting Up and Configuring Your System Devices are usually connected with a cable assembly consisting of a shielded 24 conductor cable with both a plug and receptacle connector at each end With this design you can link devices in a linear configuration a star configuration or a combination of the two configurations Figure 1 1 shows the linear and star configurations Figure 1 1 Linear and Star System Configuration Device A Device D Device A Device B Device C Device B Device C a Linear Configuration b Star Configuration National Instruments 1 1 Chapter 1 Introduction Controlling More Than One Interface Figure 1 2 shows an example of a multi interface system configuration gpib0 is a PCI GPIB and is the access interface for the voltmeter gpib1 is a GPIB ENET 100 and is the access interface for the plotter and printer Figure 1 2 Example of Multiboard System Configuration one
108. nabling HS488 To enable HS488 for your GPIB interface use the ibconfig function option IbcHSCableLength The value passed to ibconfig should specify the number of meters of cable in your GPIB configuration If you specify a cable length that is much smaller than what you actually use the transferred data could become corrupted If you specify a cable length longer than what you actually use the data is transferred successfully but more slowly than if you specified the correct cable length In addition to using ibconfig to configure your GPIB interface for HS488 the Controller In Charge must send out GPIB command bytes interface messages to configure other devices for HS488 transfers If you are using device level calls the NI 488 2 software automatically sends the HS488 configuration message to devices If you enabled the HS488 protocol in the GPIB Configuration utility the NI 488 2 software sends out the HS488 configuration message when you use ibdev to bring a device online When you use ibconfig ona board handle the next device level call will retransmit the cable length to the bus If you are using board level traditional NI 488 2 calls or multi device NI 488 2 calls and you want to configure devices for high speed you must send the HS488 configuration messages using ibcmd or SendCmds The HS488 configuration message is made up of two GPIB command bytes The first byte the Configure Enable CFE message hex IF places all HS488
109. nchronous I O you can only use ibstop ibnotify ibwait and ibonl or perform other non GPIB operations If any other call is attempted EOIP is returned National Instruments C 5 Appendix C Error Codes and Solutions Solutions Resynchronize the driver and the application before making any further NI 488 2 calls Resynchronization is accomplished by using one of the following functions ibnotify callback If the Ibsta value passed to the ibnotify callback contains CMPL the driver and application are resynchronized ibnotify If the returned Ibsta contains CMPL the driver and application are resynchronized ibwait If the returned ITbsta contains CMPL the driver and application are resynchronized ibstop The I O is canceled the driver and application are resynchronized ibonl The I O is canceled and the interface is reset the driver and application are resynchronized ECAP 11 ECAP results when your GPIB interface lacks the ability to carry out an operation or when a particular capability has been disabled in the software and a call is made that requires the capability Solutions Check the validity of the call or make sure your GPIB interface and the driver both have the needed capability EFSO 12 EFSO results when an ibrdf or ibwrtf call encounters a problem performing a file operation Specifically this error indicates that the function is unable to open create seek write or close the file be
110. nd the Firmware section and click Update For more information about the Firmware Update utility refer to the GPIB ENET 1000 information in the GPIB Hardware Installation Guide and Specifications National Instruments 2 9 GPIB Explorer OS X and Linux This chapter describes GPIB Explorer an interactive utility you can use with the NI 488 2 software for OS X and Linux You can perform the following GPIB related tasks in GPIB Explorer Add or remove GPIB interfaces Reconfigure GPIB interface settings Launch the NI 488 2 Troubleshooting Wizard to troubleshoot GPIB and NI 488 2 problems Launch NI I O Trace to monitor NI 488 2 calls to GPIB interfaces Locate additional help resources for GPIB and NI 488 2 Starting GPIB Explorer OS X To start GPIB Explorer from the Finder double click Applications National Instruments NI 488 2 GPIB Explorer Figure 3 1 shows GPIB Explorer in OS X Figure 3 1 GPIB Explorer OS X LAA GPIB Explorer The interfaces listed below are currently installed GPIB Name Interface Type GPIBO PCI GPIB GPIB1 PCI GPIB Delete GPIB2 GPIB ENET 100 Properties Refresh v 5 5 a o amp oO v High Perforr 9 7 2 exit National Instruments 3 1 Chapter 3 GPIB Explorer OS X and Linux Linux To start GPIB Explorer enter the following command usr local bin gpibexplorer Figure 3 2 sh
111. ners on the GPIB refer to the following possible solutions e Ifyou have a running GPIB Analyzer with the GPIB handshake option enabled disable the GPIB handshake option in the GPIB Analyzer e Ifyou have a GPIB extender in your system MAX cannot detect any instruments connected to your GPIB interface Instead you can verify communication with your instruments using the Interactive Control utility To do so select Tools NI 488 2 Interactive Control For more information about verifying instrument communication type help at the Interactive Control command prompt Communicate with Your Instrument To establish basic or advanced communication with your instruments refer to the following sections For more information about instrument communication and a list of the commands that your instrument understands refer to the documentation that came with your GPIB instrument Most instruments respond to the IDN command by returning an identification string National Instruments 2 3 Chapter 2 Measurement amp Automation Explorer Windows Basic Communication Query Write Read To establish basic communication with your instrument use the NI 488 2 Communicator as follows 1 2 3 4 Start MAX as described in the Starting Measurement amp Automation Explorer section Expand Devices and Interfaces and Locate Your GPIB Interface Select your GPIB interface If you have not already done so scan for connected instrum
112. ns NI 488 2 Error Codes Configuration Errors se Timitio Error S ienen ina BA DE Ri Reet ee ask ee Communication Ertors enaa EE acess sets aia a Ee cee ee eae Repeat Addressing Termination Method viii ited aos basic ee eek Mi tlie dea earn AA Y 5 3 Other Errors 33 4 3 ei hh i i he a ais es es She eile 5 3 Chapter 6 NI I O Trace ee Overview sii Starting NI vO Trace Windows en en a ia A R a a era Eea OS X and Linux Monitoring API Calls with NI I O Trace c eeeeeccesceseeseeseesecsecseesceseeseeeeeeeeeeceeeeeetseeaees 6 2 Using the NI I O Trace Help oo cccccsccssessesseseesecescesceseeseeseeeesececeecececsaecaecaeeaeenseaaeats 6 2 Locating Errors with NI I O Trace 6 2 Debugging Existing Applications 6 3 Viewing Properties for Recorded Calls 6 3 Exiting NI VO ace aia3 et ea tinea teen dated R ERE aed 6 3 Performance Considerations cccscsessesscseseeseeseseeseseesessesevscsaeseeeceaeacsecnenecsaeaeecnesateeens 6 3 Chapter 7 Interactive Control Utility OVERVIEW fips Sone ee sae reed ees eat os See aa ies 7 1 Getting Started with Interactive Control 00 0 cece see eseeeeseeeeeeceesersceeeeseeevscsaesesscenetees 7 1 Interactive Control Syntax 1 4 Number Syntax 7 4 String Syntax 7 4 Address Syntaks noen Gees tee dea tal E EEE didn e a Ra EERE 7 4 Interactive Control Commands cessssecssesceecseseeseceeseescsevseaesevsceaeeesscsevecsaeseeecsese
113. ntains at least one more response byte If this happens continue to call ibrsp until the RQS bit is cleared from the status word Stuck SRQ State If autopolling is enabled and the GPIB interface detects an SRQ the driver serial polls all open devices connected to that interface The serial poll continues until either SRQ unasserts or all the devices have been polled Ifno device responds positively to the serial poll or if SRQ remains in effect because of a faulty instrument or cable a stuck SRQ state is in effect If this happens during an ibwait for RQS the driver reports the ESRQ error If the stuck SRQ state happens no further polls are attempted until an ibwait for RQS is made When ibwait is issued the stuck SRQ state is terminated and the driver attempts a new set of serial polls Autopolling and Interrupts If autopolling is enabled the NI 488 2 software can perform autopolling after any device level call provided that no GPIB T O is currently in progress Because the driver uses interrupts an automatic serial poll can occur even when your application is not making any calls to the NI 488 2 software Autopolling can also occur when a device level ibwait for RQS is in progress Autopolling is not allowed when an application calls a board level traditional or multi device NI 488 2 call or the stuck SRQ ESRQ condition occurs SRQ and Serial Polling with Device Level Traditional NI 488 2 Calls You can use the device level trad
114. nterface clear ibsre v Set clear remote enable line ibstop Abort asynchronous operation ibtmo v Change disable time limit National Instruments 7 7 Chapter 7 Interactive Control Utility Table 7 2 Syntax for Board Level Traditional NI 488 2 Calls in Interactive Control Continued Syntax Description ibwait mask Wait for selected event where mask is a hex or decimal integer or a list of mask bit mnemonics such as ibwait TIMO CMPL ibwrt wrtbuf Write data ibwrta wrtbuf Write data asynchronously ibwrtf filname Write data from a file where f1name is pathname of file to write Table 7 3 Syntax for Multi Device NI 488 2 Calls in Interactive Control Syntax Description AllSpoll addrlist Serial poll multiple devices DevClear address Clear a device DevClearList addrlist Clear multiple devices EnableLocal addrlist Enable local control EnableRemote addrlist Enable remote control FindLstn padlist limit Find all Listeners FindRQS addrlist Find device asserting SRQ PassControl address Pass control to a device PPoll Parallel poll devices PPollConfig address dataline lineSense Configure device for parallel poll PPollUnconfig addrlist Unconfigure device for parallel poll RcvRespMsg count termination Receive response message ReadStatusByte address Serial poll a
115. of the write EOS read method TIf this is enabled ibrd ibrda and ibrdf calls are terminated when the EOS byte is detected on the GPIB when the GPIB EOI line is asserted or when the specified count is reached If the EOS read method is disabled ibrd ibrda and ibrdf calls terminate only when the GPIB EOI line is asserted or the specified count has been read National Instruments 8 1 Chapter 8 NI 488 2 Programming Techniques You can use the ibconfig function to configure the software to indicate whether the GPIB EOI line was asserted when the EOS byte was read in Use the IbcEndBitIsNormal option to configure the software to report only the END bit in Ibsta when the GPIB EOI line is asserted By default END is reported in Ibsta when either the EOS byte is read in or the EOI line is asserted during a read High Speed Data Transfers HS488 National Instruments has designed a high speed data transfer protocol for IEEE 488 called HS488 This protocol increases performance for GPIB reads and writes up to 8 Mbytes s depending on your system HS488 is part of the IEEE 488 1 2003 standard thus you can mix IEEE 488 1 IEEE 488 2 and HS488 devices in the same system If HS488 is enabled HS488 compliant interfaces implement high speed transfers automatically when communicating with HS488 instruments If you attempt to enable HS488 on a GPIB interface that does not have HS488 capable hardware the ECAP error code is returned E
116. on errors repeat addressing 5 3 termination method 5 3 configuration See also Interactive Control utility National Instruments l 1 Index controlling more than one interface 1 1 1 2 errors 5 2 linear and star system configuration figure 1 1 multiboard system example figure 1 2 requirements 1 2 system configuration effects on HS488 1 2 Configure CFGn message 8 3 Configure Enable CFE message 8 3 Controller in Charge CIC active or inactive A 1 bus management 8 9 System Controller as CIC A 1 Controllers definition A 1 conventions used in the manual x count information in Interactive Control utility 7 11 D data lines A 2 data transfers high speed HS488 terminating 8 1 DAV data valid line table A 3 DCAS status word condition 4 7 B 1 B 4 debugging checking NI 488 2 error codes 5 2 communication errors repeat addressing 5 3 termination method 5 3 configuration errors 5 2 GPIB error codes table C 1 NI I O Trace utility 5 1 6 3 timing errors 5 2 using global status functions 5 2 deleting GPIB interface 3 3 DevClear function 7 8 DevClearList function 4 11 7 8 device level calls and bus management 8 9 direct entry with C accessing gpib 32 dll exports 4 16 accessing ni4882 dll exports 4 14 l 2 ni com exporting pointers to global variables and function calls 4 13 documentation accessing NI 488 2 documentation ix accessing NI 488 2 Help ix convention
117. on you choose bus management operations necessary for device communication are performed automatically The following sections describe some differences between the traditional NI 488 2 calls and the multi device NI 488 2 calls 4 4 ni com NI 488 2 User Manual Communicating with a Single GPIB Device If your system has only one device attached to each interface the traditional NI 488 2 calls are probably sufficient for your programming needs A typical NI 488 2 application with a single device has three phases e Initialization use ibdev to get a handle and use ibclr to clear the device Device Communication use ibwrt ibrd ibtrg ibrsp and ibwait to communicate with the device e Cleanup use ibon1 to put the handle offline Refer to the sample applications that are installed with the NI 488 2 software to see detailed examples for different GPIB device types For NI 488 2 applications that need to control the GPIB in non typical ways for example to communicate with non compliant GPIB devices there is a set of low level functions that perform rudimentary GPIB functions If you use these functions you need to understand GPIB management details such as how to address talkers and listeners Refer to Appendix A GPIB Basics for some details on GPIB management The set of low level functions are called board level functions They access the interface directly and require you to handle the addressing and bus management
118. onal Instruments GPIB Website 1 Start GPIB Explorer as described in the Starting GPIB Explorer section 2 Select Help NI GPIB Home Page from the menu bar to access the National Instruments website for GPIB View or Change GPIB Ethernet Device Network Settings To view or change the network settings of your GPIB Ethernet device refer to the following sections For more information about your network settings refer to the GPIB Hardware Guide To view the GPIB Hardware Installation Guide and Specifications you need Adobe Acrobat Reader which you can download from www adobe com OS X The GPIB Hardware Installation Guide and Specifications is installed with NI 488 2 To access this document double click Applications National Instruments NI 488 2 Documentation Linux The GPIB Hardware Installation Guide and Specifications is installed with NI 488 2 It is in the usr local natinst ni4882 docs directory National Instruments 3 5 Developing Your NI 488 2 Application This chapter describes how to develop an NI 488 2 application using the NI 488 2 API Interactive Instrument Control Before you write your NI 488 2 application you might want to use the Interactive Control utility to communicate with your instruments interactively by typing individual commands rather than issuing them from an application You can also use the Interactive Control utility to learn to communicate with your instruments using the NI 488 2
119. only while you are debugging your application or in situations where performance is not critical National Instruments 6 3 Interactive Control Utility This chapter introduces you to the Interactive Control utility which lets you communicate with GPIB devices interactively Overview With the Interactive Control utility you communicate with the GPIB devices through functions you interactively type in at the keyboard For specific information about communicating with your particular device refer to the documentation that came with the device You can use the Interactive Control utility to practice communication with the instrument troubleshoot problems and develop your application The Interactive Control utility helps you to learn about your instrument and to troubleshoot problems by displaying the following information on your screen after you enter a command e Results of the status word Ibsta in hexadecimal notation e Mnemonic constant of each bit set in Ibsta e Mnemonic value of the error function Iberr if an error exists the ERR bit is set in Ibsta e Count value for each read write or command function e Data received from your instrument Getting Started with Interactive Control This section shows you how to use the Interactive Control utility to test a sequence of NI 488 2 calls For help on any Interactive Control command type help followed by the command For example type help ibdev orhelp devcle
120. ontrol utility 7 9 SRQ service request line table A 3 SRQI status word condition 4 7 B 1 B 2 starting GPIB Explorer 3 1 status of devices or interfaces global functions 4 6 status word Ibsta 4 6 ATN B 3 CIC B 3 CMPL B 3 DCAS B 4 DTAS B 4 END B 2 ERR B 2 Interactive Control utility 7 10 LACS B 4 LOK B 3 REM B 3 RQS B 2 SRQI B 2 status word layout table 4 6 B 1 TACS B 4 TIMO B 2 stuck SRQ state 8 11 syntax in Interactive Control utility 7 4 System Controller A 1 NI 488 2 User Manual T TACS status word condition 4 7 B 1 B 4 talk address A 2 Talker Listener applications 8 9 Talkers A 1 terminating data transfers 8 1 termination methods errors caused by 5 3 TestSRQ routine 8 12 ThreadIbent function 8 9 ThreadIberr function 8 9 ThreadIbsta function 8 9 timing errors 5 2 TIMO status word condition 4 6 B 1 B 2 troubleshooting Self Test 2 1 C 2 C 5 D 2 Troubleshooting Wizard 3 1 C 2 C 5 D 2 turn OFF display function Interactive Control utility 7 9 turn ON display function Interactive Control utility 7 9 V Visual Basic programming instructions 4 13 W waiting for GPIB conditions ibwait 8 3 WaitSRQ routine 8 12 National Instruments 1 7
121. ontroller as required EABO 6 VO operation aborted timeout ENEB 7 Nonexistent GPIB interface EOIP 10 Asynchronous I O in progress ECAP 11 No capability for operation EFSO 12 File system error EBUS 14 GPIB bus error ESRQ 16 SRQ stuck in ON position ETAB 20 Table problem ELCK 21 GPIB interface is locked and cannot be accessed EARM 22 ibnotify callback failed to rearm EHDL 23 Input handle is invalid EWIP 26 Wait in progress on specified input handle ERST 27 The event notification was cancelled due to a reset of the interface EPWR 28 The interface lost power National Instruments C 1 Appendix C Error Codes and Solutions EDVR 0 EDVR is returned when the interface or device name passed to ibfind or the interface index passed to ibdev cannot be accessed The global function Ibcnt contains an error code This error occurs when you try to access an interface or device that is not installed or configured properly EDVR is also returned if there is an internal driver error Solutions Possible solutions for this error are as follows Use ibdev to open a device without specifying its symbolic name Use only device or interface names that are configured in the GPIB Configuration utility as parameters to the ibfind function Use troubleshooting tools to ensure that each interface you want to access is working properly Windows Use the NI MAX Self Test feature as described in Chapter 2 Measurement amp Automation Explor
122. or task Not Data Accepted One of the three GPIB handshake lines See also handshake Not Ready For Data One of the three GPIB handshake lines See also handshake P parallel poll PC PCI PIO PPC PPD PPE PPU programmed I O R resynchronize RQS SDC NI 488 2 User Manual The process of polling all configured devices at once and reading a composite poll response See also serial poll Personal computer Peripheral Component Interconnect See programmed I O Parallel Poll Configure The GPIB command used to configure an addressed Listener to participate in polls Parallel Poll Disable The GPIB command used to disable a configured device from participating in polls There are 16 PPD commands Parallel Poll Enable The GPIB command used to enable a configured device to participate in polls and to assign a DIO response line There are 16 PPE commands Parallel Poll Unconfigure The GPIB command used to disable any device from participating in polls Low speed data transfer between the GPIB interface and memory in which the CPU moves each data byte according to program instructions See also DMA When the driver indicates to the application that asynchronous T O operations have completed Request Service Seconds Selected Device Clear The GPIB command used to reset internal or device functions of an addressed Listener See also DCL National Instruments G 7 Glossary
123. ou check for possible errors after each call using the Ibsta ERR bit debugging your application is much easier When using the GPIB32 API ibsta is the global variable Each bit in Ibsta can be set for device level traditional NI 488 2 calls dev board level traditional NI 488 2 calls and multi device NI 488 2 calls brd or all dev brd Ibsta is a 32 bit value A bit value of one 1 indicates that a certain condition is in effect A bit value of zero 0 indicates that the condition is not in effect Table 4 1 shows the condition that each bit position represents the bit mnemonics and the type of calls for which the bit can be set For a detailed explanation of each status condition refer to Appendix B Status Word Conditions Table 4 1 Status Word Layout Mnemonic Bit Pos Hex Value Type Description ERR 15 8000 dev brd NI 488 2 error TIMO 14 4000 dev brd Time limit exceeded 4 6 ni com NI 488 2 User Manual Table 4 1 Status Word Layout Continued Mnemonic Bit Pos Hex Value Type Description END 13 2000 dev brd END or EOS detected SRQI 12 1000 brd SRQ interrupt received RQS 11 800 dev Device requesting service CMPL 8 100 dev brd T O completed LOK 7 80 brd Lockout State REM 6 40 brd Remote State CIC 5 20 brd Controller In Charge ATN 4 10 brd Attention is asserted TACS 3 8 brd Talker LACS 2 4 brd Listener DTAS 1 2 brd Device
124. ows GPIB Explorer in Linux Figure 3 2 GPIB Explorer Linux v to GPIB Explorer File Tools Help yx The interfaces listed below are currently installed GPIB Name Interface Type New PCI GPIB GPIB USB HS Delete Properties Software Si Refresh ili 2 i o a o G E o sa a a J Exit Add a New GPIB Interface To add a new GPIB interface to your system complete the following steps Non Plug and Play Interfaces For Example GPIB ENET 100 1 Start GPIB Explorer as described in the Starting GPIB Explorer section 2 Click New 3 Follow the prompts to add your GPIB interface to the system 3 2 ni com NI 488 2 User Manual Plug and Play Interfaces For Example PCI GPIB 1 2 Close GPIB Explorer if it is running Physically add the interface into your system making sure to shut down the system if your interface is not hot swappable Refer to the GPIB Hardware Installation Guide and Specifications for more details on how to do this To view the document you need Acrobat Reader which you can download from www adobe com OS X The GPIB Hardware Installation Guide and Specifications is installed with NI 488 2 To access this document double click Applications National Instruments NI 488 2 Documentation Linux The GPIB Hardware Installation Guide and Specifications is installed with NI 488 2 It is in the usr local natinst ni4882 docs directory Start
125. p help option Display help information about option where option is any NI 488 2 or auxiliary call for example help ibwrt orhelp set Repeat previous function Turn OFF display Turn ON display National Instruments 7 9 Chapter 7 Interactive Control Utility Table 7 4 Auxiliary Functions in Interactive Control Continued Function Description n function Execute function n times where function represents the correct Interactive Control function syntax n o Execute previous function n times filename Execute indirect file where filename is the pathname of a file that contains Interactive Control functions to be executed buffer Set type of display used for buffers Valid options are full brief option ascii and off Default is full q Exit or quit Status Word In the Interactive Control utility all NI 488 2 calls except ib find and ibdev return the status word Ibsta in two forms a hex value in square brackets and a list of mnemonics in parentheses In the following example the status word is on the second line showing that the write operation completed successfully ud0 ibwrt IDN 0100 cmpl count 5 udo For more information about Ibsta refer to Appendix B Status Word Conditions Error Information If an NI 488 2 call completes with an error the Interactive Control utility displays the relevant error mnemonic
126. pears Refer to the Scan for GPIB Instruments section for more information 5 Double click the instrument displayed in the right window pane MAX lists all the attributes for the instrument such as the primary address the secondary address if applicable the instrument s response to the identification query IDN and the GPIB interface number to which the device is connected Change GPIB Device Templates For older NI 488 2 applications you might need to modify one of the device templates to find a given GPIB instrument by name for example ibfind fluke45 Older applications still use ibfind instead of the preferred ibdev to obtain a device handle In new applications avoid using ibfind to obtain device handles and use ibdev instead You can use ibdev to dynamically configure your GPIB device handle ibdev also eliminates unnecessary device name requirements If you must modify a device template run the GPIB Configuration utility 1 Start MAX as described in the Starting Measurement amp Automation Explorer section 2 Select Help Help Topics NI 488 2 to view the N 488 2 Help 3 Search for the topic named How do I change a GPIB Device Template and click the link to open the GPIB Configuration utility Double click the device template you want to modify such as DEV1 Rename the template as described in your application documentation 6 Click the OK button twice to save your changes and exit 2 6 ni com NI 488
127. ress ibpet Pass control ibppe v Parallel poll configure ibrd count Read data where count is the bytes to read National Instruments 7 5 Chapter 7 Interactive Control Utility Table 7 1 Syntax for Device Level Traditional NI 488 2 Calls in Interactive Control Continued Syntax Description ibrda count Read data asynchronously where count is the bytes to read ibrdf filname Read data to file where f1name is pathname of file to read ibrpp Conduct a parallel poll ibrsp Return serial poll byte ibsad v Change secondary address ibstop Abort asynchronous operation ibtmo v Change disable time limit ibtrg Trigger selected device ibwait mask Wait for selected event where mask is a hex or decimal integer or a list of mask bit mnemonics such as ibwait TIMO CMPL ibwrt wrtbuf Write data ibwrta wrtbuf Write data asynchronously ibwrtf filname Write data from a file where f 1name is pathname of file to write Table 7 2 Syntax for Board Level Traditional NI 488 2 Calls in Interactive Control Syntax Description ibask option Return configuration information where option is amnemonic for a configuration parameter ibcac v Become active Controller ibcmd cmdbuf Send commands ibcmda cmdbuf Send commands asynchronously ibconfig option Alter configurable parameters where option
128. s of the function your application needs The following code fragment shows you how to get the addresses of the pointers to the thread specific status functions and any calls your application needs Pointers to NI 488 2 thread specific status functions static unsigned int __stdcall PThreadIbsta void static unsigned int __stdcall PThreadIberr void static unsigned int __stdcall PThreadIbcnt void static int __stdcall Pibdev int ud int pad int sad int tmo int eot int eos static unsigned int __stdcall Pibonl int ud int v PThreadIbsta unsigned int __stdcall void GetProcAddress ni4882Lib ThreadIbsta PThreadIberr unsigned int __stdcall void GetProcAddress ni4882Lib ThreadIberr PThreadIbcnt unsigned int __stdcall void GetProcAddress ni4882Lib ThreadIbcnt Pibdev int __stdcall int int int int int int GetProcAddress ni4882Lib ibdev Pibonl unsigned int __stdcall int int GetProcAddress ni4882Lib ibonl If Get ProcAddress fails it returns a NULL pointer The following code fragment shows you how to verify that none of the calls to Get ProcAddress failed if NULL PThreadIbsta NULL PThreadIberr NULL PTheadIbcnt NULL Pibdev NULL Pibonl Free the ni4882 library FreeLibrary ni4882Lib printf GetProcAddress failed Your Windows appl
129. s used in manual x related documentation x DOS support enabling or disabling 2 7 DTAS status word condition 4 7 B 1 B 4 dynamic link library 4 2 E EABO error code C 4 EADR error code C 3 EARG error code C 4 EARM error code C 8 EBUS error code C 7 ECAP error code C 6 ECIC error code C 2 EDVR error code C 2 EFSO error code C 6 EHDL error code C 9 ELCK error code C 8 END status word condition 4 7 B 1 B 2 ENEB error code C 5 ENOL error code C 3 EOI end or identify line table A 3 EOIP error code C 5 EOS comparison method 8 1 read method 8 1 write method 8 1 EPWR error code C 10 ERR status word condition 4 6 B 1 B 2 error codes and solutions EABO C 4 EADR C 3 EARG C 4 EARM C 8 EBUS C 7 ECAP C 6 ECIC C 2 EDVR C 2 EFSO C 6 EHDL C 9 ELCK C 8 ENEB C 5 ENOL C 3 EOIP C 5 EPWR C 10 ERST C 9 ESAC C 4 ESRQ C 7 ETAB C 8 EWIP C 9 GPIB table C 1 debugging applications 5 2 error conditions communication errors repeat addressing 5 3 termination method 5 3 configuration errors 5 2 Interactive Control utility 7 10 timing errors 5 2 error function Iberr 4 7 error tracking with NI I O Trace 6 2 error type reporting 4 7 ERST error code C 9 ESAC error code C 4 ESRQ error code C 7 ETAB error code C 8 Ethernet Device Configuration utility 2 8 Event Status bit ESB 8 10 EWIP error code C 9 execute function n times n function Interactive Control u
130. sNormal1 to enable a mode in which the END bit is set only when EOI is asserted In this mode if the I O operation completes because of the EOS character by itself END is not set The application should check the last byte of the received buffer to see if it is the EOS character SRQI brd SRQI indicates that a GPIB device is requesting service SRQI is set when the GPIB interface is CIC and the GPIB SRQ line is asserted SRQI is cleared either when the GPIB interface ceases to be the CIC or when the GPIB SRQ line is unasserted RQS dev RQS appears in the status word only after a device level call and indicates that the device is requesting service RQS is set whenever one or more positive serial poll response bytes have been received from the device A positive serial poll response byte always has bit 6 asserted Automatic serial polling must be enabled it is enabled by default for RQS to automatically appear in Ibsta You can also wait for a device to request service regardless of the state of B 2 ni com NI 488 2 User Manual automatic serial polling by calling ibwait with a mask that contains RQS Do not issue an ibwait call on RQS for a device that does not respond to serial polls Use ibrsp to acquire the serial poll response byte that was received RQS is cleared when all of the stored serial poll response bytes have been reported to you through the ibrsp function CMPL dev brd CMPL indicates the condition of I O
131. sees 7 5 Status WOT ss coated ees a A EEEE TE abt enc e neuen A E E AOE 7 10 Error Information ise eseo rar r setae EEEE hah shovel AE EAP EE I ER 7 10 Count Information a a a a E 7 11 National Instruments vii Contents Chapter 8 NI 488 2 Programming Techniques Termination of Data Transfersor cnans epe e Medici the a aiee Dee Ee High Speed Data Transfers H8488 s sesessesseseeeessssseeesrresrsrsrsererssssrerersrsrerersereererersesee Enabling HS488 ssseneesesseeseseeessrsesseeses System Configuration Effects on HS488 Waiting for GPIB Conditions sseesessseseeeeeseseeeereresrreerrrsrerereesee aa es Asynchronous Event Notification in NI 488 2 Applications ccccccscseesersensereeeeeeeee 8 3 Calling the ibnotiffy FUNCtION 0 eee ceeeeceeeeecececeecsesenseceesecnesesseaeeevseeesesseneeees ibnotify Programming Example Writing Multithreaded NI 488 2 Applications Device Level Calls and Bus Management is Talker Listener Applications sorsien neee E E ais Serial Pollitigys ected sh cneet a a a a a a A A a a Ea SSe Service Requests from IEEE 488 Devices Service Requests from IEEE 488 2 Devices Automatic Serial Polling sesesesssseseseesesesessteessseestsessesesssersesestssestsereesrseestsesss ig SRQ and Serial Polling with Device Level Traditional NI 488 2 Calls 8 11 SRQ and Serial Polling with Multi Device NI 488 2 Calls cies seseeereetenees 8 12 Parallel
132. ss See also MTA A GPIB device that sends data messages to Listeners Take Control The GPIB command used to pass control of the bus from the current Controller to an addressed Talker timeout TLC ud UNL UNT NI 488 2 User Manual A feature of the GPIB driver that prevents I O functions from hanging indefinitely when there is a problem on the GPIB An integrated circuit that implements most of the GPIB Talker Listener and Controller functions in hardware Unit descriptor A variable name and first argument of each function call that contains the unit descriptor of the GPIB interface or other GPIB device that is the object of the function Unlisten The GPIB command used to unaddress any active Listeners Untalk The GPIB command used to unaddress an active Talker National Instruments G 9 Index Symbols repeat previous function function Interactive Control utility 7 9 turn ON display function Interactive Control utility 7 9 turn OFF display function Interactive Control utility 7 9 filename execute indirect file function Interactive Control utility 7 10 A accessing NI 488 2 driver 4 2 Active Controller A 1 adding new GPIB interface in GPIB Explorer 3 2 in Measurement amp Automation Explorer 2 2 address syntax in Interactive Control utility 7 4 AllSpoll function serial polling multiple devices with a single call 8 13 application debugging global status funct
133. ssing before any GPIB activity Therefore you might need to configure your NI 488 2 driver to perform repeat addressing if your device does not remain in its currently addressed state You can either reconfigure from your application using ibconfig or reconfigure using MAX a Note National Instruments recommends using ibconfig to modify the configuration If your application uses ibconfig it works properly regardless of the previous configuration For more information about ibconfig refer to the description of ibconfig in the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual Termination Method You should be aware of the data termination method that your device uses By default your NI 488 2 software is configured to send EOI on writes and terminate reads on EOI or a specific byte count If you send a command string to your device and it does not respond it might not be recognizing the end of the command In that case you need to send a termination message such as lt CR gt lt LF gt after a write command as follows ibwrt dev COMMAND x0D x0A 9 Other Errors If you experience other errors in your application refer to the N 488 2 Help It includes extensive troubleshooting information and the answers to frequently asked questions For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual
134. t bit 6 or hex 40 of each status byte to determine whether that device requested service ReadStatusByte is similar to Al1Spo11 except that it only serial polls a single device It is similar to the device level NI 488 2 ibrsp function FindROQS serial polls a list of devices until it finds a device that is requesting service or until it has polled all of the devices on the list The call returns the index and status byte value of the device requesting service TestSRQ determines whether the SRQ line is asserted and returns to the program immediately e WaitSRQ is similar to Test SRQ except that WaitSRQ suspends the application until either SRQ is asserted or the timeout period is exceeded The following examples use these calls to detect SRQ and then determine which device requested service In these examples three devices are present on the GPIB at addresses 3 4 and 5 and the GPIB interface is designated as bus index 0 The first example uses FindROQS to determine which device is requesting service and the second example uses Al1Spol11 to serial poll all three devices Both examples use Wait SRQ to wait for the GPIB SRQ line to be asserted Example 1 Using FindRQS This example shows you how to use FindROQS to find the first device that is requesting service void GetASerialPollResponse char DevicePad char DeviceResponse char SerialPollResponse 0 int WaitResult Addr4882 t Addrlist 4 3 4 5 NOADDR W
135. t command error execution error device dependent error query error request control and operation complete The device can assert SRQ when ESB or MAV are set or when a manufacturer defined condition occurs Automatic Serial Polling Ifyou want your application to conduct a serial poll automatically when the SRQ line is asserted you can enable automatic serial polling The autopolling procedure occurs as follows 1 To enable autopolling use the board level configuration function ibcon fig with option IbcAUTOPOLL or the GPIB Configuration utility Autopolling is enabled by default 2 When the SRQ line is asserted the driver automatically serial polls the open devices 3 Each positive serial poll response bit 6 or hex 40 is set is stored in a queue associated with the device that requested service The RQS bit of the device status word Ibsta is set 8 10 ni com NI 488 2 User Manual 4 The polling continues until SRQ is unasserted or an error condition is detected To empty the queue use the ibrsp function ibrsp returns the first queued response Other responses are read in first in first out FIFO fashion If the RQS bit of the status word is not set when ibrsp is called a serial poll is conducted and returns the response received To prevent queue overflow empty the queue as soon as an automatic serial poll occurs 6 Ifthe RQS bit of the status word is still set after ibrsp is called the response byte queue co
136. tation section of About This Manual The functions such as ibfind ibrdf and ibwrtf all require an argument that is a name ibfind requires an interface or device name and ibrdf and ibwrtf require a file name Because Windows supports both ASCII 8 bit and Unicode 16 bit characters the DLLs export both ASCII and Unicode versions of these functions The ASCII versions are named ibfindaA ibrdfA and ibwrt fA The Unicode versions are named ibfindw ibrdfw and ibwrt fW You can use either the Unicode or ASCII versions of these functions with Windows National Instruments 4 13 Chapter 4 Developing Your NI 488 2 Application In addition to pointers to the status functions or variables and a handle to the loaded DLL you must define the direct entry prototypes for the functions you use in your application For the prototypes for each function exported by the DLL refer to the appropriate header file ni4882 h for ni4882 format or ni488 h for gpib 32 format For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual For more information about direct entry refer to the help for your development environment Directly Accessing the ni4882 dll Exports Make sure that the following lines are included at the beginning of your C application include lt windows h gt include ni4882 h In your Windows application you first need to load ni4882 d11 The following code fragment shows
137. terface passes control to another device ATN brd ATN indicates the state of the GPIB Attention ATN line ATN is set whenever the GPIB ATN line is asserted and it is cleared when the ATN line is unasserted National Instruments B 3 Appendix B Status Word Conditions TACS brd TACS indicates whether the GPIB interface is addressed as a Talker TACS is set whenever the GPIB interface detects that its talk address and secondary address if enabled has been sent either by the GPIB interface itself or by another Controller TACS is cleared whenever the GPIB interface detects the Untalk UNT command its own listen address a talk address other than its own talk address or Interface Clear IFC LACS brd LACS indicates whether the GPIB interface is addressed as a Listener LACS is set whenever the GPIB interface detects that its listen address and secondary address if enabled has been sent either by the GPIB interface itself or by another Controller LACS is also set whenever the GPIB interface shadow handshakes as a result of the ibgts function LACS is cleared whenever the GPIB interface detects the Unlisten UNL command its own talk address Interface Clear IFC or that the ibgts function has been called without shadow handshake DTAS brd DTAS indicates whether the GPIB interface has detected a device trigger command DTAS is set whenever the GPIB interface as a Listener detects that the
138. the ERR bit is set For a failed NI 488 2 call Iberr contains a value that defines the error In some error cases the value in Ibcnt contains even more error information Once you know which NI 488 2 call fails refer to Appendix B Status Word Conditions and Appendix C Error Codes and Solutions for help understanding why the NI 488 2 call failed This information is also available in the N 488 2 Help For instructions on accessing the help refer to the Using the NI 488 2 Documentation section of About This Manual NI 488 2 Error Codes The error function Iberr is meaningful only when the ERR bit in the status function Ibsta is set For a detailed description of each error and possible solutions refer to Appendix C Error Codes and Solutions Configuration Errors Several applications require customized configuration of the NI 488 2 driver For example you might want to terminate reads on a special end of string character or you might require secondary addressing In these cases you can either reconfigure from your application using the ibcon fig function or reconfigure using the GPIB Configuration utility 4 Note National Instruments recommends using ibconfig to modify the configuration If your application uses ibconfig it works properly regardless of the previous configuration For more information about using ibconfig refer to the description of ibconfig in the NI 488 2 Help For instructions on accessing the help
139. this global function contains the actual number of bytes transmitted The Ibcnt function returns a 32 bit integer For accessing the newer NI4882 API this function is recommended instead of the global variables ibcnt and ibentl After each NI 488 2 I O call this global variable contains the actual number of bytes transmitted On systems with a 16 bit integer such as MS DOS ibcnt isa 16 bit integer and ibcnt1 is a 32 bit integer For cross platform compatibility use ibcnt1 unless using the newer NI4882 API For accessing the newer NI4882 API use the global function Ibcnt instead A global variable that contains the specific error code associated with a function call that failed For accessing the newer NI4882 API use the global function Iberr instead A global function that contains the specific error code associated with a function call that failed For accessing the newer NI4882 API this function is recommended instead of the global variable iberr At the end of each function call this global variable status word contains status information For accessing the newer NI4882 API use the global function Ibsta instead At the end of each function call this global function contains status information For accessing the newer NI4882 API this function is recommended instead of the global variable ibsta Institute of Electrical and Electronic Engineers A broadcast message sent from the Controller to all devices and use
140. tility 7 10 execute indirect file function Interactive Control utility 7 10 execute previous function n times n function Interactive Control utility 7 10 exit or quit q function Interactive Control utility 7 10 F FindLstn function 4 10 FindRQS function finding first device requesting service 8 12 frequently asked questions D 1 functions See global functions NI 488 2 User Manual G global functions debugging applications 5 2 error function Iberr 4 7 global variables status word Ibsta 4 6 writing multithreaded NI 488 2 applications 8 8 GPIB configuration controlling more than one interface 1 2 linear and star system configuration figure 1 1 requirements 1 2 interface management lines A 3 overview A 1 sending messages across A 2 Talkers Listeners and Controllers A 1 GPIB addresses primary and secondary A 2 syntax in Interactive Control utility 7 4 GPIB Configuration utility changing GPIB device templates 2 6 starting 2 6 GPIB device templates modifying 2 6 GPIB Explorer accessing additional help and resources 3 4 GPIB web site 3 5 help 3 4 adding new GPIB interface 3 2 deleting a GPIB interface 3 3 GPIB interface settings 3 4 Linux startup screen figure 3 2 OS X startup screen figure 3 1 starting 3 1 GPIB Hardware Installation Guide and Specifications ix GPIB instrumentation information 2 6 GPIB interface settings viewing or changing 3 4 under Win
141. tion C CFE CFGn CIC CPU DAV DCL device level function DIO1 through DIO8 DLL G 2 ni com See I O address Basic Input Output System A rudimentary function that performs a single operation Configuration Enable The GPIB command which precedes CFGn and is used to place devices into their configuration mode These GPIB commands CFG1 through CFG15 follow CFE and are used to configure all devices for the number of meters of cable in the system so HS488 transfers occur without errors Controller In Charge The device that manages the GPIB by sending interface messages to other devices Central processing unit Data Valid One of the three GPIB handshake lines See also handshake Device Clear The GPIB command used to reset the device or internal functions of all devices See also SDC A function that combines several rudimentary board operations into one function so that the user does not have to be concerned with bus management or other GPIB protocol matters The GPIB lines that are used to transmit command or data bytes from one device to another Dynamic link library DMA driver E END or END Message EOI EOS or EOS Byte EOT ESB FIFO GET GPIB GPIB address NI 488 2 User Manual Direct memory access High speed data transfer between the GPIB board and memory that is not handled directly by the CPU Not available on some systems See also programmed I O
142. ures a device for parallel polling using traditional NI 488 2 calls The device asserts DIO7 if its ist is 0 In this example the ibdev command opens a device that has a primary address of 3 has no secondary address has a timeout of 3 s asserts EOI with the last byte of a write operation and has EOS characters disabled include ni4882 h dev ibdev 0 3 0 T3s 1 0 The following call configures the device to respond to the poll on DIO7 and to assert the line in the case when its ist is 0 Pass the binary bit pattern 0110 0110 or hex 66 to ibppc ibppc dev 0x66 If the GPIB interface configures itself for a parallel poll you should still use the ibppc function Pass the interface index or an interface unit descriptor value as the first argument in ibppc Also if the individual status bit ist of the interface needs to be changed use the IbcIst option with the ibconfig function In the following example the GPIB interface is to configure itself to participate in a parallel poll It asserts DIOS when ist is 1 if a parallel poll is conducted ibppc 0 Ox6C ibconfig 0 IbcIst 1 Conduct the parallel poll using ibrpp and check the response for a certain value The following example code performs the parallel poll and compares the response to hex 10 which corresponds to DIOS If that bit is set the ist of the device is 1 ibrpp dev amp ppr if ppr amp 0x10 printf ist 1 n ni com NI 488 2 User Manual
143. use of the way they are used in the application only a single thread is writing the global values and that thread only adds information increases the count or adds another reading to the array of floats A Note The following example is written using the GpibNotifyCallback_t definition for Windows Refer to the gpib header file ni 4882 h for the proper definition of the Callback thread for your platform Other than a possible minor change in the definition of the Callback thread this example will work on all platforms include lt stdio h gt include ni4882 h int stdcall MyCallback int LocalUd int LocallIbsta int LocallIberr long LocalIbcntl void RefData int ReadingsTaken 0 float Readings 1000 BOOL DeviceError FALSE char expectedResponse 0x43 int main int ud Assign a unique identifier to the device and store it in the variable ud ibdev opens an available device and assigns it to access GPIBO with a primary address of 1 a secondary address of 0 a timeout of 10 seconds the END message enabled and the EOS mode disabled If ud is less than zero then print an error message that the call failed and exit the program ud ibdev 0 connect board T primary address of GPIB device 0 secondary address of GPIB device T10s 10 second I O timeout Ly BOT mode turned on 0 BOS mode disabled National Instruments 8 5 Chapter 8 NI 488 2 Programming T
144. utions Take all handles offline and reinitialize the application Quit the application and restart Disable standby and hibernate modes on the PC C 10 ni com Common Questions This appendix answers some common questions about the NI 488 2 software General GPIB Questions How many devices can I configure for use with the NI 488 2 software You can configure the NI 488 2 software to use up to 1 024 logical devices The maximum number of physical devices you should connect to a single GPIB interface is 14 or fewer depending on your system configuration When should I use the Interactive Control utility You can use the Interactive Control utility to test and verify instrument communication troubleshoot problems and develop your application For more information refer to Chapter 7 Interactive Control Utility How do I use an NI 488 2 application interface For information about using NI 488 2 application interfaces refer to Chapter 4 Developing Your NI 488 2 Application What do I need to know to communicate properly with my GPIB instrument Refer to the documentation that came with your instrument The command sequences that you use depend on the specific instrument The documentation for each instrument should include the GPIB commands that you need to communicate with your instrument In most cases device level traditional NI 488 2 calls are sufficient for communicating with instruments For more information re
145. vice Configuration sessersrercroiiisosnsiieriii e iii 2 8 Update GPIB ENET 1000 Firmware 00 cccceececcescesceeeseeseesecaecaecaecaeeaeeaeeaeeneeeeees 2 9 National Instruments v Contents Chapter 3 GPIB Explorer OS X and Linux Starting GPIB Explorer zest ive diced dover leh ted eaten e Nal ea detent ORD EE OEE acai tases E cds guesebsaduanetd Jauoas aueieeer diesel bienesenciassesieibecee View or Change GPIB Interface Settings Access Additional Help and Resources NI 488 2 Help tition deca E Gh tla te Ba a RAR Aes National Instruments GPIB Website eceeceecsseecneeececseeeceeceesecnesevsceaesessenaeaeeas View or Change GPIB Ethernet Device Network Settings 00 0 ccceeeeesereeeeeeneeeeneeees 3 5 Chapter 4 Developing Your NI 488 2 Application Interactive Instrument Control oo cccccecsccecsccesssceessececseceseececseceseecessseeesecessssensseeesaees 4 1 Wind OWS orais E EEEE aks ins Satoh BARE Gea a A 4 1 Choosing Your Programming Methodology ccessssceseseeeceeceeeceeseeeesesenseceeeesaeeenees 4 2 Choosing a Method to Access the NI 488 2 Driver cccecseceeseceecteseeeeeeeeeeeeeenees 4 2 Choosing How to Use the NI 488 2 API oo ceceeesseneeseeseeeeceeeececaeeeceeseeeesaesenees 4 4 Checking Status with Global Functions 0 cccccessesessesseeecsesesseceeeeeseeevsesaesensceeesesaeeeeees 4 6 Status Word Ibsta cceeeseeseeeeee Error Function Iberr Count Function

NI-488.2 User Manual - National Instruments

Contents

Download Pdf Manuals

Related Search

Related Contents