Home

1. 2 Referencing Upon startup or after a call to Mercury INI a controller has no way of knowing the absolute position of a connected axis The axis is said to be unreferenced and no moves can be made Moves can be made allowable in the following ways gt The axis can be referenced This involves moving it until it trips a reference or limit switch See the Mercury_REF Mercury_MNL and Mercury_MPL functions for details gt The controller can be told to set the reference mode for the axis OFF and allow relative moves only without knowledge of the absolute position See the Mercury_RON function for details gt For axes with reference mode OFF the controller can be told to assume the absolute position has a given value See the Mercury_POS function for details 3 DLL Handling To get access to and use the DLL functions the library must be included in your software project There are a number of techniques supported by the Windows operating system and supplied by the different development systems The following sections describe the methods which are most commonly used For detailed information consult the relevant documentation of the development environment being used It is possible to use the Mercury_DLL DLL in Delphi projects Please see http www drbob42 com delphi headconv htm for a detailed description of the steps necessary 3 1 Using a Static Import Library The PI_Mercury_GCS_DLL DLL module is accompanied
2. Flash read failed HW match code missing invalid FW match code missing invalid HW version missing invalid FW version missing invalid FW Update failed No error occurred during function call Error during com operation could not be specified Error while sending data Error while receiving data Not connected no port with given ID open Buffer overflow Error while opening port Timeout error There are more lines waiting in buffer There is no interface or DLL handle with the given ID Event message for notification could not be opened Function not supported by this interface type Error while sending echoed data IEEE488 System error IEEE488 Function requires GPIB board to be CIC IEEE488 Write function detected no listeners IEEE488 Interface board not addressed correctly IEEE488 Invalid argument to function call Page 54 PI 18 Release 1 0 1 PI Mercury Windows GCS 1 0 DLL COM_GPIB_ESAC COM_GPIB_EABO COM_GPIB_ENEB COM_GPIB_EDMA COM_GPIB_EOIP COM_GPIB_ECAP COM_GPIB_EFSO COM_GPIB_EBUS COM_GPIB_ESTB COM_GPIB_ESRQ COM_GPIB_ETAB COM_GPIB_ELCK COM_RS_INVALID_DATA_BITS COM_ERROR_RS_SETTINGS COM_INTERNAL_RESOURCES_ERROR COM_DLL_FUNC_ERROR COM_FTDIUSB_INVALID_HANDLE COM_FTDIUSB_DEVICE_NOT_FOUND COM_FTDIUSB_DEVICE_NOT_OPENED COM_FTDIUSB_IO_ERROR COM_FTDIUSB_INSUFFICIENT_RESOURCES COM FTDIUSB INVALID PARAMETER COM FTDIUSB INVALID BAUD RATE COM FTDIUSB DEVICE NOT OPENED
3. NOTE Although the GCS DLL has a gateway for sending native commands mixing native and GCS commands is not recommended GCS move commands for example may not work properly after the position has been changed by a native command 1 3 Axes and Stages Mercury Class controllers can be chained together on an RS 232 bus network and all controlled through one port of the host computer USB or RS 232 One that network native commands are used and the commands and responses are always sent between the host computer and one selected controller with the other controllers in the deselected state The GCS DLL makes a network of Mercury Class controllers connected to one port look like one controller with up to 16 axes if host s RS 232 port is used number of usable axes may be limited to as few as 6 by current available See the controller User Manual for information on setting the controller device number 1 to 16 typically 4 address DIP switches are used The device number determines the default identifiers of the corresponding axes and I O channels 1 3 1 Axis Designators By default the axes are named A to P The axis connected to the Mercury controller with device number 1 will be addressed as axis A in the GCS DLL the Mercury No 5 will provide axis E etc If these two controllers are the only ones connected the GCS DLL will provide only the two axes A and E Release 1 0 1 www pi ws
4. This DLL is not thread safe The function calls of the DLL are not synchronized and can be safely used only by one thread at a time 1 5 Overview This document describes the general handling of GCS DLLs and the individual functions of the MERCURY GCS DLL You can also use this document when you are working with the GCS COM server see Section 6 on p 12 for the COM server special features Units and GCS p 9 explains the units used for commanding positions Referencing p 9 explains how to properly initialize your system and the connected stages DLL Handling p 9 explains how to load the library and how to access the functions provided by the MERCURY DLL Function Calls p 11 and Types Used in PI Software p 11 provides some general information about the syntax of most commands in the DLL GCS COM Server p 12 points out the differences between DLL and COM server handling Native Command Gateway p 15 shows how to initiate communication with a Mercury Class controller or controller network see also Interface Settings p 20 Mercury Class Commands p 20 describes the functions encapsulating the embedded GCS commands for Mercury Class controllers Motion Parameters Overview p 42 describes how to handle the stage parameters and list the valid parameter set Error Code p 50 has a description of the possible errors Vv Vv NV VV V VV WV Release 1 0 1 www pi ws Page 8 PI PI Mercury Windows GCS 1 0 DLL So
5. define macro n See the Mercury Native Commands manual for details 12 3 Macro Translation by the GCS DLL 12 3 1 Macro Creation from GCS The GCS macro creation mechanism involves placing a GCS controller in macro recording mode sending it commands and then exiting macro recording mode While in macro recording mode the controller neither executes nor responds to commands but simply stores them in the macro In normal operation the GCS DLL translates GCS based functions to Mercury native commands The GCS macro recording mechanism is easily translated to native commands with the use of a macro recording flag in the DLL While the flag is set DLL function calls create native commands as usual but they are saved rather than sent to the controller When recording is completed Mercury MAC_END function the saved commands are assembled into a compound command beginning with MD given a cursory check and if they are acceptable the macro definition compound command is sent to the controller Here are some of the implications m The DLL may decide not to send the macro to the controller at all Whether or not the macro was sent can be checked with Mercury qERR after Mercury_MAC_END If the macro was not sent error 1010 will be set Admittedly the error description text can be misleading Release 1 0 1 www pi ws Page 46 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E m Referencing operations with REF are
6. Arguments ID ID of controller network szOldAxes old identifiers of the axes szNewAxes new identifiers of the axes Returns TRUE if successful FALSE otherwise Errors PI INVALID AXIS IDENTIFIER if the characters are not valid PI UNKNOWN AXIS IDENTIFIER if szO dAxes contains unknown axes PI AXIS ALREADY EXISTS if one of szNewAxes is already in use PI INVALID ARGUMENT if sz01ldAxes and szNewAxes have different lengths or if a character in szNewAxes is used for more than one old axis Release 1 0 1 www pi ws Page 40 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury_SPA int ID const char szAxes int iCmdarray double dValarray Corresponding command SPA Set parameters for szAxes For each parameter you must specify an axis in szAxes and a parameter ID in the corresponding element of iCmdarray Mercury SPA has two arrays as arguments The first array has the parameters which have to be modified the second one the values If you want to set the velocity ID 10 to 0 05 the acceleration ID 11 to 8 and the deceleration ID 12 to 8 you can use the following code in C syntax char szAxes AAA aime emab LO diy zip double values 0 05 8 8 Mercury_SPA id szAxes cmd values szAxes AAA cmd 10 11 12 values 0 05 8 8 szAxes 0 A cmd O 10 values 0 0 05 szAxes 1 A cmd I 11 values 1 8 szAxes 2 A cmd
7. be found This file is required to connect a stage with the CST command No wave being output to specified axis Invalid password Error during communication with OPM Optical Power Meter maybe no OPM connected WaveEditor Error during wave creation incorrect number of parameters WaveEditor Frequency out of range WaveEditor Error during wave creation incorrect index for integer parameter Page 58 PI 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 Release 1 0 1 PI Mercury Windows GCS 1 0 DLL PI WAVE EDITOR WRONG DP VALUE PI WAVE EDITOR WRONG ITEM VALUE PI WAVE EDITOR MISSING GRAPH COMPONENT PI EXT PROFILE UNALLOWED CMD PI EXT PROFILE EXPECTING MOTION ERROR PI EXT PROFILE ACTIVE PI EXT PROFILE INDEX OUT OF RANGE PI PROFILE GENERATOR NO PROFILE PI PROFILE GENERATOR OUT OF LIMITS PI PROFILE GENERATOR UNKNOWN PARAMETER PI PROFILE GENERATOR PAR OUT OF RANGE PI EXT PROFILE OUT OF MEMORY PI EXT PROFILE WRONG CLUSTER PI UNKNOWN CLUSTER IDENTIFIER www pi ws Software Manual MS154E WaveEditor Error during wave creation incorrect index for floating point parameter WaveEditor Error during wave creation could not calculate value WaveEditor Graph display component not installed User Profile Mode Command is not allowed check for required preparatory commands User Profile Mode First target position in Us
8. ccccceeeeeeeeeeeeeeeeeeeeeeeeenneeees 8 TTCAAS et tt k k an kon a to e iis Gohan ian 8 OVEMVIOW dok io kankan ki lika kd ka E 8 WAITS ANE OCS ce ola eka ee we anan kg besnansbnxaasdgnandenieeson Aa KR 9 Hardware Physical Units and SCalINQ errrrrrererrrrrrrresoerernen 9 Rounding GONSIQBETATIONS wii koko v b ske n kan sa ak kan kane enpak vise 9 Referencing eki a kak n a ai Coax ol kk kk A kk a kk n kk A AD 9 DLL Handling fe ak kak e ka n a kk lk kk a kk e A A AD 9 Using a Static Import EIDrany sc koki laa kali ai l ap aw kw e n pi ik kaa die 9 Using a Module Definition File 2 Liiirrrrrrrrrrrrereroeeerrroorrrtasasanon 10 Using Windows API FUunctions ccccceeeeeeeeeeeneeneeeeeeeeeeeenaae 10 FUNGCHON Calls ticiscsiecssecstecscecstecscscstecsesastessdscstecsdscstenndscnat 11 Controller Dii nsira al a ko ts Nocatee kon kin BA 11 Axis ID ntifiers cecccceee cece cece keen cece cece sees eeeeeneeeeeeeeeeseeeeeeeeeees 11 AXIS Parameters ei e E ancien 11 Types Used in PI Software cccccccccsssssseeeeeeteeeeeeeeees 11 Bool an Values neare ieat keer ananena EEEE E EERE a ELE 11 NOLLE PoiNterS dede ea on aaa p deran aie 12 G STINGS acna a ee es Saas wee ean 12 GCS COM Semel cscsccsccctcccsctetieccucctieccnceticceuccteecenceticceecees 12 No Need for Controller IDS cccccsccecceeeeeesesesseeeeeeeeeseeeeees 12 No Need for Buffer SIZOS iccssicssiwntndvaotnncnineladtinaueate 13 COM Properties
9. const char szAxes BOOL pbValarray Check if szAxes are moving If an axis is moving the corresponding element of the array will be TRUE otherwise FALSE If no axes are specified only one boolean value is returned and pbValarray 0 will contain a composite answer TRUE if at least one axis is moving FALSE if no axis is moving Arguments ID ID of controller network szAxes string with axes if or NULL all axes are affected pbValarray pointer to array to receive statuses of the axes Returns TRUE if successful FALSE otherwise BOOL Mercury_IsRecordingMacro int ID BOOL pbRecordingMacro Check if controller is currently recording a macro Note With Mercury Class controllers with native software Macro recording mode is a state of the library only See Macro Storage on Controller beginning on p 46 for more details Arguments ID D of controller network pbRecordingMacro pointer to boolean to receive answer TRUE if recording a macro FALSE otherwise Returns TRUE if successful FALSE otherwise BOOL Mercury_IsReferenceOK int ID const char szAxes BOOL pbValarray Check the reference state of the given axes Call Mercury_qREF p 35 to find out which axes have a reference switch Axes with a reference switch can be referenced with Mercury REF p 39 axes with limit switches with Mercury _MNL p 30 or Mercury _MPL p 30 Arguments ID ID of controller network szAxes stri
10. const char szAxes double valarray BOOL Mercury WAC int ID const char szCondition a a a a a Release 1 0 1 www pi ws Page 21 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 10 2 Detailed Description These functions encapsulate the GCS ASCII commands supported by Mercury Class controllers and provide some shortcuts to make the work with these controllers easier See Function Calls p 11 for some general notes about the parameter syntax Types Used in PI Software p 11 will give you some general information about the syntax of most commands NOTE Keep in mind that a Network of Mercury Class controllers chained together and connected to a single host PC interface is handled as single a multi axis controller by the DLL Each axis has its own Mercury Class controller and the DLL addresses commands for that axis to that controller 10 3 Function Documentation BOOL Mercury_BRA int ID const char szAxes BOOL pbValarray Corresponding GCS command BRA Set brake state for szAxes to on TRUE or off FALSE Factory power up default state for the brake control line is in the Brake ON state INI command sets brake OFF Arguments ild ID of controller network szAxes string with axes pbValarray modes for the specified axes TRUE for on FALSE for off Returns TRUE if successful FALSE otherwise BOOL Mercury_CLR int ID const char szAxes Correspondin
11. too low Command execution not possible while Autozero is running Autozero requires at least one linear axis Initialization still in progress Parameter is read only Parameter not found in non volatile memory Voltage out of limits Not enough memory available for requested wav curve not enough memory available for DDL table DDL can not be started time delay larger than DDL table DDL can not be started GCS array doesn t support different length request arrays which have different length separately Attempt to restart the generator while it is running in single step mode MOV MVR SVA SVR STE IMP and WGO blocked when analog target is active MOV MVR SVA SVR STE and IMP blocked when wave generator is active PI LabVIEW driver reports error See source control for details No stage connected to axis File with axis parameters not found Invalid axis parameter file Backup file with axis parameters not found PI internal error code 204 SMO with servo on uudecode incomplete header uudecode nothing to decode Page 52 PI 208 209 210 211 212 213 214 215 216 217 218 219 301 302 303 304 305 306 307 308 309 310 311 333 555 601 602 603 1000 1001 1002 Release 1 0 1 PI Mercury Windows GCS 1 0 DLL PI CNTR UUDECODE ILLEGAL FORMAT PI_CNTR_CRC32_ERROR PI_CNTR_ILLEGAL_FILENAME PI_CNTR_FILE_NOT_FOUND PI_CNTR_FILE_WRITE_ERROR PI CNTR DTR HINDERS VELOCITY CHANG
12. 0 1 www pi ws Page 45 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 12 Macro Storage on Controller Up to 32 macros can be stored in non volatile memory on each Mercury Class controller Macros are stored in the command language of the controller With present firmware this is the Mercury native command set 12 1 Features and Restrictions The native command macro storage facility has the following features which result in certain restrictions m Each macro can contain up to 16 such commands m The macros are identified by numbers 0 to 31 m Macro 0 if defined is the autostart macro which is executed automatically upon power up or reset m Macros are executed on the controller where they are stored so commands in a macro may address only the axis and or I O channels associated with that controller there is no command interface communication between controllers Interaction between separate axes is conceivable only through suitable programming and hardwiring of I O lines m The position values stored in the macros are in counts This means that a macro may not work properly if run when different stage types are connected to the controller A different stage could have a very different travel ratio and thus move to a position far different from the one intended 12 2 Native Macro Recording Mechanism A macro is stored on the controller by placing it in a compound command beginning with the native command MDn
13. Communication Error Move to limit switch failed Attempt to reference axis with referencing disabled Selected axis is controlled by joystick Controller detected communication error MOV motion still in progress Unknown parameter No commands were recorded with REP Password invalid Data Record Table does not exist Page 51 PI 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 100 200 201 202 203 204 205 206 207 Release 1 0 1 PI Mercury Windows GCS 1 0 DLL PI CNTR INVALID RECORDER SRC OPT PI CNTR INVALID RECORDER SRC CHAN PI CNTR PARAM PROTECTION PI CNTR AUTOZERO RUNNING PI CNTR NO LINEAR AXIS PI CNTR INIT RUNNING PI CNTR READ ONLY PARAMETER PI CNTR PAM NOT FOUND PI CNTR VOL OUT OF LIMITS PI CNTR WAVE TOO LARGE PI CNTR NOT ENOUGH DDL MEMORY PI CNTR DDL TIME DELAY TOO LARGE PI CNTR DIFFERENT ARRAY LENGTH PI CNTR GEN SINGLE MODE RESTART PI CNTR ANALOG TARGET ACTIVE PI CNTR WAVE GENERATOR ACTIVE PI LABVIEW ERROR PI CNTR NO AXIS PI CNTR NO AXIS PARAM FILE PI CNTR INVALID AXIS PARAM FILE PI CNTR NO AXIS PARAM BACKUP PI CNTR RESERVED 204 PI CNTR SMO WITH SERVO ON PI CNTR UUDECODE INCOMPLETE HEADER PI CNTR UUDECODE NOTHING TO DECODE www pi ws Software Manual MS154E Source does not exist number too low or too high Source Record Table number too low or too high Protected Param current Command Level CCL
14. FOR ERASE COM FTDIUSB DEVICE NOT OPENED FOR WRITE COM FTDIUSB FAILED TO WRITE DEVICE COM FTDIUSB EEPROM READ FAILED COM FTDIUSB EEPROM WRITE FAILED COM FTDIUSB EEPROM ERASE FAILED COM FTDIUSB EEPROM NOT PRESENT www pi ws Software Manual MS154E IEEE488 Function requires GPIB board to be SAC IEEE488 I O operation aborted IEEE488 Interface board not found IEEE488 Error performing DMA IEEE488 I O operation started before previous operation completed IEEE488 No capability for intended operation IEEE488 File system operation error IEEE488 Command error during device call IEEE488 Serial poll status byte lost IEEE488 SRQ remains asserted IEEE488 Return buffer full IEEE488 Address or board locked RS 232 5 data bits with 2 stop bits is an invalid combination as is 6 7 or 8 data bits with 1 5 stop bits RS 232 Error configuring the COM port Error dealing with internal system resources events threads A DLL or one of the required functions could not be loaded FTDIUSB invalid handle FTDIUSB device not found FTDIUSB device not opened FTDIUSB IO error FTDIUSB insufficient resources FTDIUSB invalid parameter FTDIUSB invalid baud rate FTDIUSB device not opened for erase FTDIUSB device not opened for write FTDIUSB failed to write device FTDIUSB EEPROM read failed FTDIUSB EEPROM write failed FTDIUSB EEPROM erase failed FTDIUSB EEPROM not present Page 55 PI PI Me
15. Mercury_IsConnected 0 if pMercury_IsConnected NULL do something for example return FALSE BOOL bResult pMercury_IsConnected 1 call Mercury_IsConnected 1 Release 1 0 1 www pi ws Page 10 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 4 Function Calls Almost all functions will return a boolean value of type BOOL see Types Used in PI Software p 11 If the function succeeded the return value is TRUE otherwise it is FALSE To find out what went wrong call Mercury GetError p 18 and look up the value returned in Error Code p 50 The first argument to most function calls is the ID of the selected controller network 4 1 Controller ID The first argument to most function calls is the ID of the selected controller network To allow the handling of multiple controller networks the DLL returns a non negative ID when a connection to a controller network is opened This is a kind of index to an internal array storing the information for the different controller networks All other calls addressing the same controller network require this ID as first argument The individual Mercury Class controllers in a Mercury controller network are distinguished by the axes which they control 4 2 Axis Identifiers Many functions accept one or more axis identifiers If no axes are specified either by giving an empty string or a NULL pointer some functions will address all connected a
16. NO DIGITAL INPUT PI CNTR NO DIGITAL OUTPUT PI CNTR NO MCM PI_CNTR_INVALID_MCM PI_CNTR_INVALID_CNTR_NUMBER PI_CNTR_NO_JOYSTICK_CONNECTED PI_CNTR_INVALID_EGE_AXIS PI_CNTR_SLAVE_POSITION_OUT_OF_RANGE PI_CNTR_COMMAND_EGE_SLAVE PI_CNTR_JOYSTICK_CALIBRATION_FAILED PI_CNTR_REFERENCING_FAILED PI_CNTR_OPM_MISSING PI CNTR OPM NOT INITIALIZED PI CNTR OPM COM ERROR PI CNTR MOVE TO LIMIT SWITCH FAILED PI CNTR REF WITH REF DISABLED PI CNTR AXIS UNDER JOYSTICK CONTROL PI_CNTR_COMMUNICATION_ERROR PI_CNTR_DYNAMIC_MOVE_IN_PROCESS PI_CNTR_UNKNOWN_PARAMETER PI_CNTR_NO_REP_RECORDED PI_CNTR_INVALID_PASSWORD PI_CNTR_INVALID_RECORDER_CHAN www pi ws Software Manual MS154E Soft limit out of range No manual pad found No more step response values No step response values recorded Axis has no reference sensor Axis has no limit switch No relay card installed Command not allowed for selected stage s No digital input installed No digital output configured No more MCM responses No MCM values recorded Controller number invalid No joystick configured Invalid axis for electronic gearing axis can not be slave Position of slave axis is out of range Slave axis cannot be commanded directly when electronic gearing is enabled Calibration of joystick failed Referencing failed OPM Optical Power Meter missing OPM Optical Power Meter not initialized or cannot be initialized OPM Optical Power Meter
17. all axes are queried pdValarray pointer to array to be filled with minimum positions of the axes Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 37 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury_qTMxX int ID const char szAxes double pdValarray Corresponding command TMx Get the high end of the travel range of szAxes in physical units and relative to the current home position Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pdValarray pointer to array to be filled with maximum positions of the axes Returns TRUE if successful FALSE otherwise BOOL Mercury_qTNJ int ID int pnNr Corresponding command TNJ Get the number of joysticks Note the software can not determine if a joystick is actually connected to a C 663 This is the maximum possible number of joysticks that can be connected to the network Parameters ID ID of controller network pnNr pointer to int to receive the number of joysticks Returns TRUE if successful FALSE otherwise BOOL Mercury_qTVI int ID char axes const int maxlen Corresponding command TVI Get list of all characters that can be used as axis identifiers Each character in the returned string could be used as a valid axis identifier after being assigned with Mercury SAI Arguments ID ID of controller network axes buffer to receive the string re
18. and edit this new file Notes The GCS DLL only accepts the DAT files PiStages dat and MercuryUserStages dat Although it is possible to save DAT files with any user defined names they are not used by the software The CST p 22 and VST p 39 commands look for the files MercuryUserStages dat and PiStages dat in the directory of the executable EXE file If you have selected the Typical setup type this directory is set automatically to C lt Program Files gt Pl GcsTranslator default If you choose the Custom setup type you can specify another directory In that case the CST p 22 and VST p 39 commands will look there for the MercuryUserStages dat and PiStages dat files 8 2 Stage Definition Function Overview BOOL Mercury_AddStage const ID const char szAxes BOOL Mercury_RemoveStage int ID const char szStageName Release 1 0 1 www pi ws Page 16 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury_OpenUserStagesEditDialog int ID BOOL Mercury_OpenPiStagesEditDialog int ID 8 3 Stage Parameter IDs When defining user stages it is important to set the stage parameters correctly See the Mercury_qSPA function call on p 36 for the parameters most frequently accessed by the user for a complete list see the Parameter List Section p 43 BOOL Mercury_AddStage const int i d char const szAxes Adds the stage of the specified axis to the file MercuryUserStages dat
19. array to be filled with target positions of the axes Returns TRUE if successful FALSE otherwise BOOL Mercury gONT int ID const char szAxes BOOL pbValarray Corresponding command ONT Check if szAxes have reached target position Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried and a separate answer provided for each pdValarray pointer to array to be filled with current on target status of the axes Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 34 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury_qPOS int ID const char szAxes double pdValarray Corresponding command POS Get the positions of szAxes Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pdValarray positions of the axes Returns TRUE if successful FALSE otherwise BOOL Mercury_qREF int ID const char szAxes BOOL pbValarray Corresponding command REF Check if the given axes have reference switches Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pbValarray pointer to array for answers TRUE if axis has a reference switch FALSE if not Returns TRUE if successful FALSE otherwise BOOL Mercury_qRON int ID const char szAxes BOOL pbValarray Corresponding command RON Gets reference mode for given axe
20. by the PI_Mercury_GCS_DLL LIB file This is the static import library which can be used by the Microsoft Visual C system for 32 bit applications In addition other systems like the National Instruments LabWindows CVI or Watcom C can handle i e understand the binary format of a VC static library When the static library is used the programmer must 1 Use a header or source file in which the DLL functions are declared as needed for the compiler The declaration should take into account that these functions come from a C Language Interface When building a C program the functions have to be declared with the attribute specifying that they are Release 1 0 1 www pi ws Page 9 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E coming from a C environment The VC compiler needs an extern c modifier The declaration must also specify that these functions are to be called like standard Win API functions That means the VC compiler needs to see a WINAPI or ___stdcal1 modifier in the declaration 2 Add the static import library to the program project This is needed by the linker and tells it that the functions are located in a DLL and that they are to be linked dynamically during program startup 3 2 Using a Module Definition File The module definition file is a standard element resource of a 16 or 32 bit Windows application Most IDEs integrated development environments support the use of module definition file
21. char szBuffer int maxlen BOOL Mercury SetErrorCheck int ID BOOL bErrorCheck VVVVVV 9 2 Detailed Description To use the DLL and communicate with a Mercury class controller or controller network the DLL must be initialized with one of the open functions Mercury_InterfaceSetupDlg or Mercury_ConnectRS232 To allow the handling of multiple controller networks the DLL will return a non negative ID when one of these functions is called This is a kind of index to an internal array storing the information for the different controller networks All other calls addressing the same controller network have this ID as first parameter Mercury_CloseConnection will close the connection to the specified controller network and free its system resources 9 3 Function Documentation void Mercury_CloseConnection int ID Close connection to Mercury Class controller network associated with D ID will not be valid any longer Arguments ID ID of controller network if ID is not valid nothing will happen int Mercury_ConnectRS232 int nPortNr long BaudRate Open an RS 232 COM interface to a controller All future calls to control this controller need the ID returned by this call Arguments nPortNr COM port to use e g 1 for COM1 BaudRate to use Returns ID of new object 1 if interface could not be opened or no controller is responding int Mercury_GetError int ID Get error status if there is no error
22. following lines to a central header file of your project typedef int BOOL define TRUE 1 Release 1 0 1 www pi ws Page 11 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E define FALSE 0 5 2 NULL Pointers In the library and the documentation null pointers pointers pointing nowhere have the value NULL This is defined in the Windows environment If your compiler does not know this simply use define NULL 0 5 3 C Strings The library uses the C convention to handle strings Strings are stored as char arrays with 0 as terminating delimiter Thus the type of a c string is char Do not forget to provide enough memory for the final 0 If you declare char text HELLO it will occupy 6 bytes in memory To remind you of the zero at the end the names of the corresponding variables start with sz 6 GCS COM Server For some programming languages it is much simpler to use a COM server than to link to DLL functions Mainly Visual Basic and other script languages e g Python Perl provide good support for calling COM functions See the provided samples for ways to integrate the GCS COM into the different languages development environments Sample programs and the appropriate source code are to be found in the Samples directory of the product CD The functions are more or less the same as provided by the DLL so this manual can be used to get to know the basic functionality There are however fundamental
23. may be done at any time though admin rights are required Choose to select the device from a list and give the Drivers directory on the product CD as the location to search Release 1 0 1 www pi ws Page 6 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E NOTE The USB drivers make the USB interface appear to the software as an additional RS 232 COM port That port is present only when the Mercury USB device is connected and powered up To initiate communication use the DLL functions described in Communication Initialization on p 17 1 2 General Command Set GCS It is possible to use either the Mercury native ASCII command set or the PI General Command Set GCS to operate a Mercury class controller The native ASCII command set is understood by all versions of the controller firmware directly see the Mercury Native Commands manual for details GCS the PI standard command set offers compatibility between different controllers With current firmware GCS command support is implemented by the Windows DLL described in this manual which translates the GCS commands to the native commands Once the PI Mercury Class_GCS_DLL dll library is installed you can use for example the LabVIEW GCS drivers to control a Mercury class controller as though it were any GCS compatible controller If you are using LabView please read the documentation for the LabVIEW drivers to find out how to connect to the GCS library
24. of controller network iJoystickIDs array with device numbers of devices having a directly connected joystick axis iAxesiDs array with axis IDs of the joystick axes must be 1 for C 663 which only has 1 joystick axis per device iArraySize size of arrays buffer buffer to receive the string read in from controller will contains axis IDs of axes associated with corresponding joystick axis maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury qJON int ID const int iJoystickIDs BOOL pbValarray int iArraySize Corresponding command JON Gets joystick enable disable states for given motion controller axes The joystick axes are identified by the device number of the Mercury Class controller to which they are connected see p 8 See the controller User Manual for Device Number setting typically 4 DIP switches are used to set a negative logic binary value one less than the device number See also Mercury_JON Arguments ID ID of controller network iJoystickIDs array with device numbers of devices having a directly connected joystick axis pbValarray pointer to array to receive the joystick axis enable states of the specified motion controller axes 0 for deactivated 1 for activated iArraySize size of arrays Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 33 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Merc
25. queried pbValarray pointer to array to receive the servo modes of the specified axes TRUE for on FALSE for off Returns TRUE if successful FALSE otherwise BOOL Mercury_qTAC int JD int pnNr Corresponding command TAC Get the number of installed analog channels Parameters ID ID of controller network pnNr pointer to int to receive the number of installed boards Returns TRUE if successful FALSE otherwise BOOL Mercury_qTAV int ID int nChannel double pdValue Corresponding command TAV Read analog input Parameters ID ID of controller network nChannel index of channel to use see Section 1 3 2 pdValue pointer to double for storing the value read from analog input Returns TRUE if successful FALSE otherwise BOOL Mercury_qTIO int ID int pnINr int pnONr Corresponding command TIO Get the number of digital input and output channels installed Arguments ID ID of controller network pniNr pointer to int to receive the number of digital input channels installed pnONr pointer to int to receive the number of digital output channels installed Returns TRUE if successful FALSE otherwise BOOL Mercury_qTMN int ID const char szAxes double pdValarray Corresponding command TMN Get the low end of travel range of szAxes in physical units and relative to the current home position Arguments ID ID of controller network szAxes string with axes if or NULL
26. set in the library this function will call Mercury qERR p 32 to determine the error status in one of the controllers in the network Any error returned is also cleared Returns error ID see Error codes p 50 for the meaning of the codes int Mercury_InterfaceSetupDlg const char szRegKeyName Open dialog to let user select the interface and create a new Controller object All future calls to control this Mercury Network need the ID returned by this call See Interface Settings p 20 for a detailed description of the dialogs shown Arguments szRegKeyName key in the Windows registry in which to store the settings the key used is HKEY_LOCAL_MACHINE SOFTWARE lt your keyname gt if keyname is NULL or the default key HKEY_LOCAL_MACHINE SOFTWARE PI Mercury_DLL is used Note If your programming language is C or C use W to represent a single in a literal for example to create MyCompany Mercury_DLL you must call Release 1 0 1 www pi ws Page 18 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Mercury_InterfaceSetupDlg MyCompany Mercury_DLL Returns ID of new object 1 if user pressed CANCEL the interface could not be opened or no Mercury Class controller is responding BOOL Mercury_IsConnected int ID Check if there is a Mercury Class controller network with an ID of D Returns TRUE if D points to an exisiting controller network FA
27. syntax differences e No controller ID since you can create instances of the COM object for every single controller network connected see Section 6 1 e With COM it is possible to allocate space for strings and arrays by the callee without disturbing the caller so there is no need to send any buffer sizes or array lengths to the COM functions see Section 6 2 e Itis possible to have properties which not only set values but also trigger certain functions see Section 6 3 6 1 No Need for Controller IDs You can create instances for every controller network connected Below is an example of equivalent C or C and Visual Basic code aime JDL int ID2 IDI Mercury ConnectRS232 1 115200 ID2 Mercury ConnectRS232 2 115200 if Mercury IsConnected ID1 Pran t AIeEould mot connect toy controller i if Mercury IsConnected ID2 printet TCouldinot connect to controller 247 C or C code Dim MERCURY1 As New MERCURY Release 1 0 1 www pi ws Page 12 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Dim MERCURY2 As New MERCURY MERCURY1 ConnectRS232 1 115200 MERCURY2 ConnectRS232 2 115200 If Not MERCURY1 IsConnected Then Me Caption Could not connect to controller 1 End If If Not MERCURY2 IsConnected Then Me Caption Could not connect to controller 2 End If Visual Basic code 6 2 No Need for Buffer Sizes If you want to read a string with a DLL functions from the DLL you need to alloca
28. szAxes BOOL Mercury MOV int ID const char szAxes double pdValarray BOOL Mercury MPL int ID const char szAxes BOOL Mercury MVR int ID const char szAxes double pdValarray int pnDelay BOOL Mercury POS int ID const char szAxes double pdValarray BOOL Mercury qBRA int ID char axes int maxlen BOOL Mercury qCST int ID const char szAxes char names int maxlen BOOL Mercury qDFF int ID const char szAxes double pdValarray BOOL Mercury_qDFH int ID const char szAxes double pdValarray BOOL Mercury_qDIO int ID const char szChannels BOOL pbValarray BOOL Mercury_qERR int ID int pError BOOL Mercury_qHLP int ID char buffer int maxlen BOOL Mercury_qIDN int ID char buffer int maxlen BOOL Mercury qJAX int ID const int iJoystickIDs const int iAxesIDs int iArraySize char szAxesBuffer int iBufferSize BOOL Mercury_qJON int ID const int iJoystickIDs BOOL pbValarray int iArraySize BOOL Mercury_qLIM int ID const char szAxes BOOL pbValarray BOOL Mercury_qMAC int ID char szName char szBuffer int maxlen BOOL Mercury_qMOV int ID const char szAxes double pdValarray BOOL Mercury_qNLM int ID const char szAxes double pdValarray BOOL Mercury_qONT int ID const char szAxes BOOL pbValarray BOOL Mercury qPLM int ID const char szAxes double pdValarray BOOL Mercury qPOS int ID const char szAxes double pdValarray BOOL Me
29. with the user defined stages Arguments ild ID of controller szAxes character of the axis Returns TRUE if successful FALSE otherwise BOOL Mercury_RemoveStage const int ild char szStageName Removes the stage with the given name from the MercuryUserStages dat file which contains the user defined stages Arguments ild ID of controller szStageName the stage name as string Returns TRUE if successful FALSE otherwise BOOL Mercury OpenPiStagesEditDialog const int ild Opens a dialog to look at the PiStages dat file which contains the stages defined by PI No changes can be made to this file Arguments ild ID of controller Returns TRUE if successful FALSE otherwise BOOL Mercury_OpenUserStagesEditDialog const int ild Opens a dialog to edit add and remove stages from the MercuryUserStages dat file which contains the user defined stages Arguments ild ID of controller Returns TRUE if successful FALSE if the buffer was too small to store the message 9 Communication Initialization 9 1 Functions gt int Mercury_ConnectRS 232 int nPortNr long BaudRate Release 1 0 1 www pi ws Page 17 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E int Mercury_InterfaceSetupDlg const char szRegKeyName BOOL bShowDetails BOOL Mercury IsConnected int ID void Mercury CloseConnection int ID int Mercury GetError int ID BOOL Mercury TranslateError int errNr
30. www pi ws About This Document Users of This Manual This manual assumes that the reader has a fundamental understanding of basic servo systems as well as motion control concepts and applicable safety procedures The manual describes the PI General Command Set GCS Windows DLL for Mercury Class controllers With present firmware all software which accepts GCS commands must pass them to the controller via this DLL or the corresponding COM Server This document is available as PDF file on the product CD For updated releases see www pi ws contact your PI Sales Engineer or write info pi ws Conventions The notes and symbols used in this manual have the following meanings CAUTION Calls attention to a procedure practice or condition which if not correctly performed or adhered to could result in damage to equipment NOTE Provides additional information or application hints Related Documents The Mercury controller and the software tools which might be delivered with the controller are described in their own manuals see below All documents are available as PDF files via download from the PI Website www pi ws or on the product CD For updated releases contact your Physik Instrumente Sales Engineer or write info pi ws Hardware User Manuals User Manuals for all hardware components Mercury GCSLabVIEW_MS149E LabView VIs based on PI GCS command set Mercury GCS DLL MS154E WindowsGCS based DLL Library this document P
31. 2 12 values 2 8 Note If the same axis has the same parameter ID more than once only the last value will be set For example Mercury_SPA id AAA 10 10 12 0 06 0 05 9 will set the velocity of A to 0 05 and the deceleration to 9 Arguments ID ID of controller network szAxes axis for which the parameter should be set iCmdarray Ds of parameters dValarray array with the values for the parameters Returns TRUE if successful FALSE otherwise Errors PI INVALID SPA CMD ID one of the IDs in iCmdarray is not valid BOOL Mercury STP int ID Corresponding command STP Stop all axes This includes motion of all axes Mercury MOV Mercury MVR referencing motion Mercury_MNL Mercury MPL Mercury REF and macros Sets error code to 10 whether any axis was in motion or not Arguments ID ID of controller network Returns TRUE if successful FALSE otherwise BOOL Mercury SVO int ID const char szAxes BOOL pbValarray Corresponding command svo Set servo control on or off closed loop open loop mode If pbValarray index is FALSE the mode is off if TRUE it is set to on Arguments ID ID of controller network Release 1 0 1 www pi ws Page 41 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E szAxes string with axes pbValarray pointer to boolean array with servo modes for the specified axes TRUE for on FALSE for off Returns TRUE if successful FALSE otherwise
32. B or RS 232 interface are interconnected using a RS 232 bus architecture The host communicates with one Mercury Class device ata time Such a network appears to the MERCURY GCS DLL user as a single multi axis controller and is usually referred to in this manual as a controller network 1 1 Quick Start 1 1 1 Software Installation To install the PI Mercury GCS DLL on your host PC proceed as follows gt Be sure to login to the host PC with administrator rights gt Ifthe Setup Wizard does not open automatically start it from the root directory of the CD with the i icon Follow the on screen instructions You can choose between typical and custom installation Typical components are GCS LabView drivers Native and GCS DLLs PiMikroMove8 MMCRun and all manuals Typical is recommended gt Sample programs and the appropriate source code are to be found in the Sample directory of the product CD 1 1 2 Connect the Controller CAUTION Never connect the RS 232 IN and USB connectors of the same controller to a PC at the same time as damage may result Physically connect the controller or controller network to the PC Never connect both USB and RS 232 cables to the host at the same time See the controller User Manual for details 1 1 3 Install USB Drivers When the USB interface to the controller network is connected for the first time you will be given the opportunity to install the drivers this
33. BOOL Mercury_VEL int ID const char szAxes double valarray Corresponding command VEL Set the velocities to use for moves of szAxes Arguments ID ID of controller network szAxes string with axes pdValarray pointer to array with velocity settings for the axes Returns TRUE if successful FALSE otherwise BOOL Mercury WAC int ID char szCondition Corresponding command wAC WAit until a given Condition of the following type occurs one given value is compared with a queried value according to a given rule Can only be used in macros When the macro interpreter accesses this command the condition is checked If it is true the current macro is stopped otherwise macro execution continues with the next line If the condition is fulfilled later it has no effect Valid conditions are ONT and DIO but only the digital I O channels or the axis of the Mercury on which the macro is stored can be queried see Section 12 Exampe Mercury_WAC ID ONT A 1 Arguments ID ID of controller network szCondition string with condition to evaluate Returns TRUE if successful FALSE otherwise 11 Motion Parameters Overview 11 1 Parameter Handling CAUTION The parameters listed in Section 11 2 are hardware specific Incorrect values may lead to improper operation or damage of your hardware Change settings only after consultation with PI Most of the parameters listed below describe the physical
34. Check 18 SPA 40 Mercury_SPA 40 SPA 35 Mercury STP 40 SRG 36 Mercury SVO 41 static import library 9 Mercury_TranslateError 18 STP 40 Mercury_VEL 41 SVO 41 Mercury_WAC 41 SVO 36 MEX 28 TAC 36 MNL 29 TAV 36 module definition file 9 TIO 37 MOV 29 TMN 37 MOV 34 TMX 37 MPL 29 TNJ 37 MVR 30 TRUE 11 NULL 11 TVI 38 ONT 34 User defind stages 15 POS 30 VEL 41 POS 34 VEL 38 REF 39 VER 38 REF 34 VST 38 RON 39 WAC 41 RON 35 Release 1 0 1 www pi ws Page 61
35. E PI CNTR POSITION UNKNOWN PI CNTR CONN POSSIBLY BROKEN PI CNTR ON LIMIT SWITCH PI CNTR UNEXPECTED STRUT STOP PI CNTR POSITION BASED ON ESTIMATION PI CNTR POSITION BASED ON INTERPOLATION PI CNTR SEND BUFFER OVERFLOW PI CNTR VOLTAGE OUT OF LIMITS PI CNTR VOLTAGE SET WHEN SERVO ON PI CNTR RECEIVING BUFFER OVERFLOW PI CNTR EEPROM ERROR PI CNTR I2C ERROR PI CNTR RECEIVING TIMEOUT PI CNTR TIMEOUT PI CNTR MACRO OUT OF SPACE PI CNTR EUI OLDVERSION CFGDATA PI CNTR EUI INVALID CFGDATA PI CNTR HARDWARE ERROR PI CNTR UNKNOWN ERROR PI CNTR NOT ENOUGH MEMORY PI CNTR HW VOLTAGE ERROR PI_CNTR_HW_TEMPERATURE_ERROR PI_CNTR_TOO_MANY_NESTED_MACROS PI_CNTR_MACRO_ALREADY_DEFINED PI_CNTR_NO_MACRO_RECORDING www pi ws Software Manual MS154E uudecode illegal UUE format CRC32 error Illegal file name must be 8 0 format File not found on controller Error writing file on controller VEL command not allowed in DTR Command Mode Position calculations failed The connection between controller and stage may be broken The connected stage has driven into a limit switch call CLR to resume operation Strut test command failed because of an unexpected strut stop Position can be estimated only while MOV is running Position was calculated while MOV is running Send buffer overflow Voltage out of limits Attempt to set voltage when servo on Received command is too long Error w
36. E Being able to specify the parameters of a stage and then save those parameters as a set under the stage name makes it easier to connect to previously defined stages New user defined stages are all stored in MERCURYUserStages dat and known PI stages are in PiStages dat For parameter descriptions see the Parameter List Section p 43 Two separate mechanisms are provided for the use of stage parameter sets gt You can execute a function call that puts the P StageEditor a GUI dialog on the screen where your user can set the stage parameters as he or she desires See the separate PI Stage Editor manual for a description of how to operate that graphic interface gt You can put the desired values in variables and execute function calls for setting the parameters and manipulating the parameter sets See the function descriptions and the parameter ID list on p 43 for details In either case the procedure involves optionally loading a parameter set connecting a stage from the list of stage names in the dat files perhaps then deleting that stage user defined stages only or editing the current active parameters and saving them under a new name to MercuryUserStages dat It is not possible to edit MercuryUserStages dat directly all changes go via the currently active parameter set PiStages dat may not be edited at all but updated versions should be made available regularly from PI 8 1 Function Calls to Edit Remove an
37. EX int ID char szCondition Corresponding command MEX Stop Macro EXecution due to a given condition of the following type one given value is compared with a queried value according to a given rule Can only be used in macros When the macro interpreter accesses this command the condition is checked If it is true the current macro is stopped otherwise macro execution continues with the next line If the condition is fulfilled later it has no effect Valid conditions are e DIO but only the digital O channels of the Mercury on which the macro is stored can be queried e JBS but only the button 1 associated with the joystick axis connected to the controller on which the macro is stored can be queried See Macro Storage on Controller p 46 Examples Mercury_MEX ID DIO A 1 Mercury_MEX ID JBS 4 1 1 Arguments ID ID of controller network szCondition string with condition to evaluate Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 29 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury MNL int ID const char szAxes Corresponding command MNL For each of the axes in szAxes in turn reset soft limits and home position move the axis to its negative limit switch and back until the limit switch disengages set the position counter to the minimum position value and set the reference state to referenced This can be used to refe
38. IMikroMove User Manual SM148E PIMikroMove Operating Software GCS based Mercury Commands MS163E Mercury GCS Commands PlStageEditor SM144E Software for managing GCS stage data database MMCRun MS139E Mercury Operating Software native commands Mercury Native DLL 8 LabVIEW MS177E Windows DLL Library and LabView VIs native command based Mercury Native Commands MS176E Native Mercury Commands 54E PI PI Mercury Windows GCS 1 0 DLL Software Manual MS1 Contents 1 1 1 1 1 2 1 3 l 1 2 1 3 3 1 3 2 3 3 l 1 4 1 5 1 6 6 1 6 2 3 1 3 2 3 3 4 1 4 2 4 3 5 1 5 2 5 3 6 1 6 2 6 3 Release 1 0 1 DISGTA MEN 5 d oui eti ond sion kok to pied aaa aaka 5 Introduction to MERCURY GCS DLL vvvrerrrrres 6 Q ick SI AN seta te ek e e kale bel et la te ie 6 Software Installation wer ian sak ako e op rmn en ke dik kt e a ki ka a 6 Connect the Controller 3 kose vol a da k po aki lt ok a at os 6 Install USB DriverS ccccccccccsssssssssccceesessssseesessseeesssssssssnnseeeees 6 General Command Set GCS eeeccceeeeesseeeeeeseeeeeeeenneeeeeeeeeeeees rg Axes AN SIAGOS ii koke teke ko kask ie as poke sd va eka bi aka ki ent en kak da be 7 PIS DESIGNALONS one eko nt ocx are ye n ka e a on pon bk Bob ne po aye 7 VO Line Designators a sents artis ds Seca nos kidnap be 8 Controller Joystick CONNECTIONS
39. LSE otherwise BOOL Mercury_SetErrorCheck int ID BOOL bErrorCheck Set error check mode of the library With this call you can specify whether the library should check the error state of the currently selected controller on the controller network with ERR after sending a command This will slow down communications so if you need a high data rate switch off error checking and call Mercury_GetError p 18 yourself when there is time to do so You might want to use permanent error checking to debug your application and switch it off for normal operation At startup of the library error checking is switched on Arguments ID ID of controller network bErrorCheck switch error checking on TRUE or off FALSE Returns the previous state i e before this call BOOL Mercury_TranslateError int errNr char szBuffer int maxlen Translate error number to error message Arguments errNr number of error as returned from Mercury_GetError p 18 szBuffer pointer to buffer that will store the message maxlen size of the buffer Returns TRUE if successful FALSE if the buffer was too small to store the message Release 1 0 1 www pi ws Page 19 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 9 4 Interface Settings See the controller user manual for hardware connection details Only those interfaces actually implemented in connected hardware can be used NOTE The USB drivers make the USB interface appear
40. Page 7 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 1 3 2 I O Line Designators Each Mercury and Mercury Step controller provides four analog digital input and four digital output lines For digital IO these channels are named with the characters ABCD EFGH IJKL MNOP OQRST UVWX YZ12 3456 7890 gt lt alle Jan o pte 188 Sen in groups of 4 one group for each of the 16 possible controller addresses For analog input 0 to 5 V the input channels of a Mercury Class network have IDs from 1 to 64 again 4 x 1 less than the device number is added to the line number to give the channel number Note that for C 862 controllers the last channel is digital only Example A network with a C 862 DC Motor Controller with device number 1 and a C 663 Stepper Controller with device number 3 The GCS DLL will provide e Axes A and D e Digital I O using channel IDs A B C D M N O and P e Analog input using channel IDs 1 3 and 25 28 1 3 3 Controller Joystick Connections Each axis associated with a controller having a joystick port can be associated with one axis of motion of a joystick That axis and the associated joystick button is identified in the network by the controller device number Note that the included joystick Y cable permits connecting one axis and one logical button of one joystick to one controller and the other axis and other button to another controller 1 4 Threads
41. Piezo Nano Positioning PI MS154E Software Manual Mercury Class PI Mercury GCS DLL Release 1 0 1 Date 2007 12 19 This document describes software for use with the following product s E C 863 Mercury Networkable Single Axis DC Motor Controller E C 862 Mercury Networkable Single Axis DC Motor Controller E C 663 Mercury Step Networkable Single Axis Stepper Motor Controller Physik Instrumente PI GmbH 6 Co KG Auf der R merstr 1 76228 Karlsruhe Germany Tel 49 721 4846 0 Fax 49 721 4846 299 Moving the NanoWorld www pi ws info pi ws www pi ws Physik Instrumente PI GmbH amp Co KG is the owner of the following company names and trademarks PI PIMikroMove Mercury Mercury Step The following designations are protected company names or registered trademarks of third parties Windows LabView Copyright 1999 2007 by Physik Instrumente PI GmbH amp Co KG Karlsruhe Germany The text photographs and drawings in this manual enjoy copyright protection With regard thereto Physik Instrumente PI GmbH amp Co KG reserves all rights Use of said text photographs and drawings is permitted only in part and only upon citation of the source First printing 2007 12 19 Document Number MS154E Release 1 0 1 Pl_Mercury_GCS_DLL_MS154E doc Subject to change without notice This manual is superseded by any new release The newest release is available for download at
42. RAM SET ERROR PI NUMBER OF POSSIBLE WAVES EXCEEDED PI NUMBER OF POSSIBLE GENERATORS EXCEEDED PI NO WAVE FOR AXIS DEFINED PI CANT STOP OR START WAV PI REFERENCE ERROR PI REQUIRED WAVE NOT FOUND PI INVALID SPP CMD ID PI STAGE NAME ISNT UNIQUE PI FILE TRANSFER BEGIN MISSING PI FILE TRANSFER ERROR TEMP FILE PI FILE TRANSFER CRC ERROR PI COULDNT FIND PISTAGES DAT PI NO WAVE RUNNING PI INVALID PASSWORD PI OPM COM ERROR PI WAVE EDITOR WRONG PARAMNUM PI WAVE EDITOR FREQUENCY OUT OF RANGE PI WAVE EDITOR WRONG IP VALUE www pi ws Software Manual MS154E There is already a parameter file open Close it before opening a new file Could not open parameter file The version of the connected controller is invalid Parameter could not be set with SPA parameter not defined for this controller The maximum number of wave definitions has been exceeded The maximum number of wave generators has been exceeded No wave defined for specified axis Wave output to axis already stopped started Not all axes could be referenced Could not find parameter set required by frequency relation Command ID given to SPP or SPP is not valid A stage name given to CST is not unique A uuencoded file transferred did not start with begin followed by the proper filename Could not create read file on host PC Checksum error when transferring a file to from the controller The PiStages dat database could not
43. TR AXIS HAS NO BRAKE PI CNTR DOUBLE AXIS PI CNTR ILLEGAL AXIS PI CNTR PARAM NR PI CNTR INVALID REAL NR PI CNTR MISSING PARAM www pi ws No error Parameter syntax error Unknown command Command length out of limits or command buffer overrun Error while scanning Unallowable move attempted on unreferenced axis or move attempted with servo off Parameter for SGA not valid Position out of limits Velocity out of limits Attempt to set pivot point while U V and W not all 0 Controller was stopped by command Parameter for SST or for one of the embedded scan algorithms out of range Invalid axis combination for fast scan Parameter for NAV out of range Invalid analog channel Invalid axis identifier Unknown stage name Parameter out of range Invalid macro name Error while recording macro Macro not found Axis has no brake Axis identifier specified more than once Illegal axis Incorrect number of parameters Invalid floating point number Parameter missing Page 50 PI 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 Release 1 0 1 PI Mercury Windows GCS 1 0 DLL PI CNTR SOFT LIMIT OUT OF RANGE PI CNTR NO MANUAL PAD PI CNTR NO JUMP PI CNTR INVALID JUMP PI CNTR AXIS HAS NO REFERENCE PI CNTR STAGE HAS NO LIM SWITCH PI CNTR NO RELAY CARD PI CNTR CMD NOT ALLOWED FOR STAGE PI CNTR
44. ad in maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_qVEL int ID const char szAxes double valarray Corresponding command VEL Get the velocity settings of szAxes This is the velocity set to be used for moves Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pdValarray pointer to array to be filled with the velocities of the axes Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 38 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury_qVER int ID char buffer const int maxlen Corresponding command VER Get version of the controller firmware Arguments ID ID of controller network buffer buffer to receive the string read in maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_qVST int ID char buffer int maxlen Corresponding command VST Get the names of stages selectable with Mercury_CST Parameters ID ID of controller network buffer buffer to receive the string read in from controller lines are separated by line feed characters maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury REF int ID const char szAxes Corresponding command REF For each of t
45. allowed because with the Mercury native command set it is possible to tell how to move toward or away from the reference switch Because REF is not implemented as single commands in the native command set it will occupy more than one command slot in the macro see examples below A total of only 16 native commands may be stored in a macro ona Mercury Class controller That means that when using GCS commands which translate to multiple native commands e g REF INI little soace may be left for other commands m The way in which a GCS function is translated into a native command can depend on the stage connected and how it was referenced A macro made under one set of conditions will not function properly if run under others As a result o Macros are only valid for the stage type that was connected when the macro was created o Only relative moves can be used without concern in macros o Absolute moves require the axis to have been referenced with exactly the same sequence of referencing commands when the macro is run as when it was created Note that having the software save positions at shutdown and restore them from saved values involves RON POS referencing m The macro names used at the GCS level are assigned using the following strict convention aMCOnn where ais the current axis designator associated with the controller and mn is a two digit number between 00 and 31 In addition all the MAC commands take an axis d
46. bic response curve The cubic curve offers more sensitive control around the middle position and less sensitivity close to the maximum velocity Arguments ID ID of controller network iJoystickIDs array with device numbers of motion axis controllers each with a joystick axis attached piValarray pointer to array with table types for the corresponding joystick axes iArraySize size of arrays Returns TRUE if successful FALSE otherwise BOOL Mercury_JON int ID const int iJoystickIDs const BOOL pbValarray int iArraySize Corresponding command JON Enable disable direct joystick control for given motion controller axes To enable set the corresponding entry in pbValarray to TRUE The motion controller axes are identified by the device number of the Mercury Class controller to which the joystick axis is connected see p 8 See the controller User Manual for Device Number setting typically 4 DIP switches are used to set a negative logic binary value one less than the device number Do not enable axes with no physical joystick connected as uncontrolled motion could occur The C 862 Mercury DC Motor Controller does not have a joystick port Arguments Release 1 0 1 www pi ws Page 27 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E ID ID of controller network iJoystickIDs array with device numbers of devices having a directly connected joystick axis pbValarray pointer to array with joystick enable states for th
47. d Add Stage Definitions Note that the parameter which determines whether a stage is new or not is the Name parameter If there is noName specified the parameter set is not valid Only when the current parameter set is valid can you for example call INI To create a valid parameter set for a new stage you can use the Mercury_SPA function call p 41 You can ease the creation by loading an existing parameter set with CST p 22 and afterwards change the name and any other parameters which differ with SPA The CST command connects a valid stage i e makes its parameter set active It uses the corresponding parameters in the DAT files so that you do not have to set them all by yourself To save a new stage and thus make it available for a future connection with CST use Mercury_AddStage p to add its parameter set to MercuryUserStages dat After addition to MERCURY UserStages dat the stage will also appear in the list returned by VST p If you want to remove a stage from MercuryUserStages dat call Mercury_RemoveStage p 17 If you want to change parameters in MercuryUserStages dat directly call Mercury_OpenUserStagesEditDialog to open it with the PlStageEditor With Mercury_OpenPiStagesEditDialog you can open the PiStages dat with the PiStageEditor but the file is protected and can not be changed However with the P StageEditor it is possible to save PiStages dat under a new name in the same directory
48. e specified motion axis controllers 0 for deactivate 1 for activate iArraySize size of arrays Returns TRUE if successful FALSE otherwise BOOL Mercury_MAC_BKG int ID char szName Corresponding command MAC BEG Put the DLL in macro recording mode See Macro Storage on Controller beginning on p 46 for details This function sets a flag in the library and effects the operation of other functions Function will fail if already in recording mode If successful the commands that follow become part of the macro so do not check error state unless FALSE is returned Arguments ID ID of controller network szName name under which macro will be stored in the controller must of the form aMCOnn where a is the axis designation of the axis controlled by the controller on which the macro is to be stored and nnis the ID number for the macro 0 to 31 Macro 0 is executed on power up or reset whether there is a PC connected or not Returns TRUE if successful FALSE otherwise Errors PI IN MACRO MODE if a macro is already being recorded BOOL Mercury MAC DEL int ID char szName Corresponding command MAC DEL Delete macro with name szName To find out what macros are available call Mercury_qMAC p 34 See Macro Storage on Controller beginning on p 46 for more details Arguments ID ID of controller network szName name of the macro to delete Returns TRUE if successful FALSE otherwise BOOL Mercur
49. eference Arguments ID ID of controller szAwnser the buffer to receive the answer bufsize the size of szAnswer Returns TRUE if no error FALSE otherwise BOOL Mercury_SendNonGCSString int ID const char szCommand Sends a native command to one of the Mercury s in the network Any native command can be sent this function is also intended to allow use of native commands not having a corresponding GCS function in the current version of the library Notes Do not mix up the GCS command set and the native command set GCS move commands do not work properly anymore after the position was changed by native commands If you want to address different controllers the native command two character address selection code can also be sent with this function see the Mercury Native Commands manual for details char addr 21g addr 0 1 addr l A for mercury with address 0 addr 2 0 Mercury_SendNonGCSString ID addr See the Native Commands manual for a description of the native commands which are understood by the firmware and for a command reference Arguments ID ID of controller szCommand the GCS command as string Returns TRUE if no error FALSE otherwise 8 Functions for User Defined Stages The PI Mercury GCS DLL also has functions allowing you to both define and save new stages parameter sets Release 1 0 1 www pi ws Page 15 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154
50. eioen aaa aa e EEEE Ini 13 www pi ws Page 4 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 7 Native Command Gatewa cccssssssseeeeeeeeeeeeeeeeeeseeeeees 15 8 Functions for User Defined StaQ S vvrrrrrrrans 15 8 1 Function Calls to Edit Remove and Add Stage Definitions 16 8 2 Stage Definition Function Overview c ccceeeesceeeeeeetteeeeeeeeee 16 8 3 Stage Parameter IDS secs cece cosine haan tee eee 17 9 Communication Initialization cccceeeeeseeeteeeeeteeeeeees 17 9 1 FUNCHONS eppen eere e eP erR e A EA REEE aa 17 9 2 Detailed DESCNPMON vwe asse yok oken sd ina ana dok fado ro da ia kek ab 18 9 3 Function Documentation cscs e kee ak api ek kapa senp ie pakse pak ee 18 9 4 Interface Settings w2 book lo ot ka la aie f pe tek pape beni st ke s n 20 9 4 1 RS 232 SON OS S y kopi ei ete ki kan an tela tee kin do eka 20 10 Mercury Class COMMANGS cccccceeeeeeeeeeeeeeeeeeeeeeeees 20 10 1 FUNCTIONS ekri krak e e en arera aaa aaa AAE AE EEROR RE aaa 20 10 2 Detailed DESCNPMON veve poke eee pau so rin ei en pd pate da kan akote 22 10 3 Function Documentation e eye its oot oo io finn a ion rak pe n 22 11 Motion Parameters Overview c sccssssseseeeeeeeeeeeeeeeeees 42 11 1 Parameter Handling side w bone koni poto sland lete teva kad Pm ak rati e 42 11 2 Parameter Uist icsctsiscietectets rene kisa e b k m veni ip ad ka et petet tini save 43 11 3 T
51. er Profile is too far from current position Controller is already in User Profile Mode User Profile Mode Block or Data Set index out of allowed range ProfileGenerator No profile has been created yet ProfileGenerator Generated profile exceeds limits of one or both axes ProfileGenerator Unknown parameter ID in Set Get Parameter command ProfileGenerator Parameter out of allowed range User Profile Mode Out of memory User Profile Mode Cluster is not assigned to this axis Unknown cluster identifier Page 59 PI PI Mercury Windows GCS 1 0 DLL 14 Index IDN 32 axis parameters 11 BOOL 11 boolen values 11 BRA 21 BRA 30 cstrings 11 CLR 21 Commands 19 CST 21 CST 31 DEL 22 DFF 22 DFF 31 DFH 22 DFH 31 DIO 22 DIO 31 dynamic loading of a DLL 10 ERR 32 Error Codes 49 FALSE 11 GetProcAddress Win32 API function 10 GOH 24 HLP 32 HLT 24 INI 24 JDT 26 32 JON 26 JON 33 LIB static import library 9 LIM 33 linking a DLL 9 LoadLibrary Win32 API function 10 MAC BEG 27 MAC DEL 27 MAC END 27 MAC START 28 MAC 33 Mercury_ GcsCommandset 23 Mercury_ GcsGetAnswer 23 Mercury_AddStage 16 Mercury_BRA 21 Mercury_CloseConnection 17 Mercury_CLR 21 Mercury_ConnectRS232 17 Mercury_CST 21 Mercury DEL 22 Mercury_DFF 22 Mercury_DFH 22 Mercury_DIO 22 Mercury_END 27 Mercury_GcsGetAnswerSize 23 Mercury_GetError 17 Mercury GetinputChannelNames 23 Mercury GetOutp
52. erSize int ID int iAnswerSize BOOL Mercury_GetInputChannelNames int ID char szBuffer int maxlen BOOL Mercury GetOutputChannelNames int ID char szBuffer int maxlen BOOL Mercury_GetRefResult int ID const char szAxes int pnResuli BOOL Mercury_GOH int ID const char szAxes BOOL Mercury HLT int ID const char szAxes BOOL Mercury INI int ID const char szAxes BOOL Mercury IsMoving const int ID const char szAxes BOOL pbValarray BOOL Mercury IsRecordingMacro int ID BOOL pbRecordingMacro BOOL Mercury_IsReferenceOK int ID const char szAxes BOOL pbValarray BOOL Mercury IsReferencing int ID const char szAxes BOOL pbisReferencing VVVVVVVVVVVVVVVVV VV Release 1 0 1 www pi ws Page 20 VVVVVVVVVVVV VV VV VV VV VV VV VV VV VV VV VV VVVV VV VV VV VV VV VV VV VV VV VV PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury IsRunningMacro int ID BOOL pbRunningMacro BOOL Mercury_JDT int ID const int iJoystickIDs const int iValarray int iArraySize BOOL Mercury_JON int ID const int iJoystickIDs const BOOL pbValarray int iArraySize BOOL Mercury_MAC_BEG int ID const char szName BOOL Mercury MAC DEL int ID const char szName BOOL Mercury MAC END int ID BOOL Mercury MAC NSTART int ID const char szName int nrRuns BOOL Mercury MAC START int ID const char szName BOOL Mercury MEX int ID const char szCondition BOOL Mercury MNL int ID const char
53. es 8 of the 16 possible command slots It can thus be seen that INI and REF will not both fit in the same macro MVR The relative move sizes entered with MVR and converted into counts using the parameters of the currently configured stage before being stored So if a macro containing MVR A2 is created with an M 111 2DG configured on axis A and later an M 505 4PD is configured for A with CST the macro will read out as MVR A 58 2542 Release 1 0 1 www pi ws Page 49 PI 13 PI Mercury Windows GCS 1 0 DLL Error Codes Software Manual MS154E The error codes listed here are those of the PI General Command Set As such some are not relevant to C 7XX controllers and will simply never occur with the systems this manual describes Controller Errors 0 1 2 Oo ao N o 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 Release 1 0 1 PI CNTR NO ERROR PI CNTR PARAM SYNTAX PI CNTR UNKNOWN COMMAND PI CNTR COMMAND TOO LONG PI CNTR SCAN ERROR PI CNTR MOVE WITHOUT REF OR NO SERVO PI_CNTR_INVALID_SGA_PARAM PI_CNTR_POS_OUT_OF_LIMITS PI_CNTR_VEL_OUT_OF_LIMITS PI_CNTR_SET_PIVOT_NOT_POSSIBLE PI CNTR STOP PI CNTR SST OR SCAN RANGE PI CNTR INVALID SCAN AXES PI_CNTR_INVALID_NAV_PARAM PI_CNTR_INVALID_ANALOG_INPUT PI_CNTR_INVALID_AXIS_IDENTIFIER PI_CNTR_INVALID_STAGE_NAME PI CNTR PARAM OUT OF RANGE PI CNTR INVALID MACRO NAME PI CNTR MACRO RECORD PI CNTR MACRO NOT FOUND PI CN
54. esignator as an argument The macros AMCO00 BMCOOO etc for axes A B respectively are the autostart macros which are executed automatically upon startup or reset of the individual axis controller The name thus already specifies the axis which the macro addresses m Only the following GCS DLL functions are allowable when the macro recording flag is set Use of a disallowed command will cause the next MAC END to set an error o Mercury_BRA Mercury_DEL Mercury_DFH Mercury_DIO Mercury_GOH Mercury_HLT Mercury_INI generates a large number of native commands in the macro see below Mercury IsRecordingMacro Mercury MAC START macro called must reside on the same controller 000000 O O For example position values in millimeters or degrees in GCS motion commands are converted to counts The count values are calculated when the macro is created using the parameters for the stage configured on the corresponding axis controller Because it is not possible to set the current absolute position to a desired value but only to 0 the count values in the controller s internal position counter after a GCS move to a given position may be very different depending on how the axis was referenced with REF MNL MPL or a RON POS combination Release 1 0 1 www pi ws Page 47 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Mercury_MAC_END takes DLL out of Macro Recording Mode Mercury_MEX wi
55. ftware Manual MS154E 1 6 Units and GCS 1 6 1 Hardware Physical Units and Scaling The GCS General Command Set system uses basic physical units of measure Most controllers and GCS software have default conversion factors chosen to convert hardware dependent units e g encoder counts into millimeters or degrees as appropriate see Mercury SPA and Mercury qSPA descriptions parameters 14 and 15 The defaults are generally taken from a database of stages that can be connected An additional scale factor can be applied see Mercury_DFF to the basic physical unit making a working physical unit available without overwriting the conversion factor for the first This is the unit referred to by the term physical unit in the rest of this manual 1 6 2 Rounding Considerations When converting move commands in physical units to the hardware dependent units required by the motion control layers rounding errors can occur The GCS software is so designed that a relative move of x physical units will always result in a relative move of the same number of hardware units Because of rounding errors this means for example that 2 relative moves of x physical units may differ slightly from one relative move of 2x When making large numbers of relative moves especially when moving back and forth either intersperse absolute moves or make sure that each relative move in one direction is matched by a relative move of the same size in the other direction
56. g command CLR Clear status of szAxes Arguments ID ID of controller network szAxes string with axes if or NULL all axes are affected Returns TRUE if successful FALSE otherwise BOOL Mercury_CST int ID const char szAxes const char names Corresponding command CST Set the types of the stages connected to szAxes The individual names must be separated by a line feed character in the string rendered by n in the following C source code example M 505 1PD nM 505 2PD Arguments Release 1 0 1 www pi ws Page 22 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E ID ID of controller network szAxes identifiers of the stages if or NULL all axes are affected names string with stage type names separated by line feed characters n in C literals Returns TRUE if successful FALSE otherwise BOOL Mercury_DEL int ID double dmSeconds Corresponding command DEL Delay the controller for dmSeconds milliseconds Note The delay will only affect the controller network the function will return immediately Commands sent to the controller network during the delay will be queued Arguments ID ID of controller network dmSeconds time in milliseconds Returns TRUE if successful FALSE otherwise BOOL Mercury_DFF int D const char szAxes const double pdValarray Corresponding GCS command DFF Defines a scale factor by which to divide the basic physical units to get the uni
57. ge but actually is not Arguments ID ID of controller network szAxes string with axes pdValarray pointer to array with absolute positions for the specified axes in physical units Returns TRUE if successful FALSE otherwise Errors PI CNTR CMD NOT ALLOWED FOR STAGE if the reference mode for any of the given axes is ON BOOL Mercury qBRA int ID char szBuffer intmaxlen Corresponding GCS command BRA Get axes with brakes Arguments ild ID of controller network szBuffer buffer to store the read in string maxlen size of buffer must be given to avoid a buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_qCST int ID const char szAxes char names const int maxlen Corresponding command CST Get the type names of the connected stages szAxes The individual names are preceded by the axis identifier and an equals sign and followed by an ASCII line feed character For example A M 714 00 1PDLF B M 511 HDLF Arguments ID ID of controller network szAxes identifiers of the stages if or NULL all axes are queried names buffer to receive the list of names read in from controller lines are separated by line feeds maxlen size of name must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 31 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury_qDFF in
58. he axes in szAxes turn reset soft limits and home position move the axis to its reference switch passing it if necessary to approach from the negative side set the position counter to the minimum position value and set the reference state to referenced Each axis must be equipped with a reference switch use Mercury_qREF to find out Mercury REF returns before the controller has finished Call Mercury_IsReferencing p 27 to find out if the axes are still moving and Mercury GetRefResult p 25 to get the results of the referencing move The controller will be busy while referencing so most other commands will cause a PI CONTROLLER BUSY error Use Mercury_STP p Fehler Textmarke nicht definiert to stop reference motion Arguments ID ID of controller network szAxes string with axes Returns TRUE if successful FALSE otherwise BOOL Mercury_RON int ID const char szAxes BOOL pbValarray Corresponding command RON Sets reference mode for given axes If the reference mode of an axis is ON the axis must be driven to the reference switch Mercury_REF or to a limit switch using Mercury_MPL Mercury_MNL before any other motion can be commanded If reference mode is OFF no referencing is required for the axis Only relative moves can be commanded Mercury_MVR unless the controller is informed of the actual position with Mercury_POS Afterwards relative and absolute moves can be commanded For
59. hile reading writing EEPROM Error on I2C bus Timeout while receiving command A lengthy operation has not finished in the expected time Insufficient space to store macro Configuration data has old version number Invalid configuration data Internal hardware error BasMac unknown controller error not enough memory hardware voltage error hardware temperature out of range Too many nested macros Macro already defined Macro recording not activated Page 53 PI 1003 1004 2000 4000 4001 4002 4003 4004 4005 4006 4007 PI Mercury Windows GCS 1 0 DLL PI_CNTR_INVALID_MAC_PARAM PI_CNTR_RESERVED_1004 PI_CNTR_ALREADY_HAS_SERIAL_NUMBER PI_CNTR_SECTOR_ERASE_FAILED PI CNTR FLASH PROGRAM FAILED PI CNTR FLASH READ FAILED PI CNTR HW MATCHCODE ERROR PI CNTR FW MATCHCODE ERROR PI CNTR HW VERSION ERROR PI CNTR FW VERSION ERROR PI CNTR FW UPDATE ERROR Interface Errors 10 11 12 13 144 15 16 17 Release 1 0 1 COM_NO_ERROR COM_ERROR SEND_ERROR REC_ERROR NOT_CONNECTED_ERROR COM_BUFFER_OVERFLOW CONNECTION_FAILED COM_TIMEOUT COM_MULTILINE_RESPONSE COM_INVALID_ID COM_NOTIFY_EVENT_ERROR COM_NOT_IMPLEMENTED COM_ECHO_ERROR COM_GPIB_EDVR COM_GPIB_ECIC COM_GPIB_ENOL COM_GPIB_EADR COM_GPIB_EARG www pi ws Software Manual MS154E Invalid parameter for MAC PI internal error code 1004 Controller already has a serial number Sector erase failed Flash program failed
60. i ws Page 13 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Loop While MERCURY Referencing wait until referenced MERCURY A 10 Sleep 1000 Dim currentPos As Double currentPos MERCURY A Visual Basic Code Release 1 0 1 www pi ws Page 14 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 7 Native Command Gateway The GCS DLL includes a function which provides access to all the commands of the controller s native command set Use of this set is only recommended for users who have already worked with this command set and do not want to learn the GCS command set The General Command Set should be preferred because of its compatibility with other PI controllers The GCS DLL function calls giving access to native commands responses are as follows gt BOOL Mercury_ReceiveNonGCSString intID char szString int iMaxSize gt BOOL Mercury_SendNonGCSString intID const char szString BOOL Mercury_ReceiveNonGCSString int ID char szAnswer int bufsize Gets the answer to a native command of one of the Mercury s in the network provided its length does not exceed bufsize The answers to a native command are stored inside the DLL where as much space as necessary is obtained Each call to this function returns and deletes the oldest answer in the DLL Note See the Mercury Native Commands manual for a description of the native commands which are understood by the firmware and for a command r
61. irst Arguments ID ID of controller network pnError pointer to integer to receive error code of the controller Returns TRUE if successful FALSE otherwise BOOL Mercury_qHLP int ID char buffer const int maxlen Corresponding command HLP Read in the help string of the controller The answer is quite long up to 3000 characters so be sure to provide enough space Arguments Page 32 Release 1 0 1 www pi ws PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E ID ID of controller network buffer buffer to receive the string read in from controller lines are separated by line feed characters maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_qIDN int ID char buffer const int maxlen Corresponding command IDN Get identification string of the controller Arguments ID ID of controller network buffer buffer to receive the string read in from controller contains controller hardware full name firmware version and date maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_qJAX int ID const int iJoystickIDs const int iAxesIDs int iArraySize char szAxesBuffer int iBufferSize Corresponding command JAX Reports correspondence between joystick port numbers device numbers and axis identifiers for axes with joystick ports Arguments ID ID
62. mand as string Returns TRUE if successful FALSE otherwise BOOL Mercury GesGetAnswer int ID char szAnswer const int bufsize Gets the answer to GCS command see Mercury_GcsCommandset p 24 Arguments ID ID of controller network szAnswer the buffer to receive the answer Bufsize the size of the buffer for the answer Returns TRUE if successful FALSE otherwise BOOL Mercury_GcsGetAnswerSize int ID int pnAnswerSize Gets the size of the answer to a GCS command Mercury_GcsCommandset p 24 Arguments ID ID of controller network pnAnswerSize pointer to integer to receive the size of the next answer Returns TRUE if successful FALSE otherwise BOOL Mercury_GetInputChannelNames int D char szBuffer int maxlen Get valid single character identifiers for installed digital input channels Each character in the returned string is the valid channel identifier of an installed digital input channel For a Mercury Class controller network the string contains 4 characters for each connected axis see Section 1 3 2 for details Call Mercury qDIO to get the states of the digital inputs Parameters ID ID of controller network szBuffer buffer to receive the identifier string maxlen size of szBuffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_GetOutputChannelNames int D char szBuffer int maxlen Get valid single character ide
63. n always be done independent of the development system or files which have to be added to the project When the DLL is loaded dynamically during program execution the programmer has to 1 Use a header or source file in which local or global pointers of a type appropriate for pointing to a function entry point are defined This type could be defined in a typedef expression In the following example the type FP_Mercury_IsConnected is defined as a pointer to a function which has an int as argument and returns a BOOL value Afterwards a variable of that type is defined typedef BOOL WINAPI FP_Mercury_IsConnected int FP_Mercury_IsConnected p Mercury _IsConnected 2 Call the Win32 API LoadLibrary function The DLL must be loaded into the process address space of the application before access to the library functions is possible This is why the LoadLibrary function has to be called The instance handle obtained has to be saved for us by the Get ProcAddress function Example HINSTANCE hPI_D11 LoadLibrary PI_Mercury_GCS_DLL DLL 0 3 Call the Win32 API GetProcAddress function for each desired DLL function To call a library function the entry point in the loaded module must be known This address can be assigned to the appropriate function pointer using the Get ProcAddress function Afterwards the pointer can be used to call the function Example pMercury_IsConnected FP Mercury IsConnected GetProcAddress hPI_D11
64. n axis in szAxes and a parameter ID in the corresponding element of iCmdarray See Section 11 on p 42 for a list of valid parameter IDs Arguments ID ID of controller network szAxes axes for each of which a parameter should be read iCmdarray Ds of parameters dValarray array to be filled with the values of the parameters Returns TRUE if successful FALSE otherwise Errors PI INVALID SPA CMD ID one of the IDs in iCmdarray is not valid BOOL Mercury qSRG int ID const char szAxes const int iCmdarray long IValarray Corresponding command SRG Read the values of the specifed registers ID of the parameters can only be 3 which will read in the signal input lines register byte 2 of the C 663 and byte 4 for the C 862 See the Mercury GCS Commands manual for detailed description of the parameters Arguments ID ID of controller network szAxes axes for each of which a parameter should be read iCmdarray Ds of parameters IValarray array to be filled with the values of the registers Returns TRUE if successful FALSE otherwise Errors PI INVALID SPA CMD ID one of the IDs in iCmdarray is not valid BOOL Mercury qS VO int ID const char szAxes BOOL pbValarray Corresponding command svo Get the servo mode for szAxes Arguments Release 1 0 1 www pi ws Page 36 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E ID ID of controller network szAxes string with axes if or NULL all axes are
65. nd out if the axes are still moving and Mercury_GetRefResult p 25 to get the results of the referencing move The controller will be busy while referencing so most other commands will cause a PI CONTROLLER BUSY error Use Mercury_STP p 24 to stop referencing motion Arguments ID ID of controller network szAxes axes to move Returns TRUE if successful FALSE otherwise Errors PI UNKNOWN AXIS IDENTIFIER cAxis is no valid axis identifier BOOL Mercury_MVR int ID const char szAxes double pdValarray Corresponding command MVR Move szAxes relatively Release 1 0 1 www pi ws Page 30 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Arguments ID ID of controller network szAxes string with axes pdValarray pointer to array with distances to move in physical units Returns TRUE if successful FALSE otherwise BOOL Mercury_POS int ID const char szAxes double pdValarray Corresponding command POS Sets absolute positions position counters for given axes Reference mode for the axes must be OFF No motion occurs See Mercury_RON for a detailed description of reference mode and how to turn it on and off For stages with neither reference nor limit switch reference mode is automatically OFF Note that when the actual position is incorrectly set with this command stages can be driven into the limit switch when moving to a position which is thought to be within the travel range of the sta
66. ng with axes if or NULL all axes are queried pbValarray pointer to boolean array to receive answers TRUE if the axis is referenced FALSE if not Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 26 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury IsReferencing int ID const char szAxes BOOL pblsReferencing Check if axis is busy referencing Note If you do not specify any axis you will get back only one BOOL It will be TRUE if the controller is referencing any axis Arguments ID ID of controller network szAxes string with axes if or NULL single value is returned TRUE if any axis is being referenced pbisReferencing pointer to boolean array to receive statuses of axes or of the controller TRUE if referencing FALSE otherwise Returns TRUE if successful FALSE otherwise BOOL Mercury_IsRunningMacro int ID BOOL pbRunningMacro Corresponding command 8 Check if controller is currently running a macro Arguments ID ID of controller network pbRunningMacro pointer to boolean to receive answer TRUE if a macro is running on at least one of the devices in the network FALSE otherwise Returns TRUE if successful FALSE otherwise BOOL Mercury_JDT int ID const int iJoystickIDs const int piValarray int iArraySize Corresponding command JDT Load pre defined joystick response table The table type can be either 1 for linear or 3 for cu
67. nipulated by sending the native commands MDn TMn TZ etc Macro Define Tell Macro n Tell Macro Zero with Mercury_Sendnongcsstring see Mercury Native Commands manual for native command descriptions Native commands that have no equivalent in GCS e g FE3 are listed in their original form as follows lt non GCS FE3 gt Release 1 0 1 www pi ws Page 48 PI 12 3 3 PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Macro Translation and Listing Examples INI When converted to native commands INI is separated into all of its separate functions when the stored macro is listed with MAC they are shown as a long list of separate commands From the list it is obvious that when INI is used not many commands are left before the macro is full With an M 505 4PD the dialog can look as follows gt gt CST DM 505 4PD gt gt ERR lt lt 0 gt gt MAC BEG DMC003 gt gt INI D gt gt MAC END gt gt ERR lt lt 0 gt gt MAC DMCOO3 SPA D50 O SPA D24 0 BRA DO SPA D1 200 SPA D2 150 SPA D3 100 SPA D8 2000 SPA D4 2000 VO Dil VEL D25 SPA D11 4000000 lt lt STP REF Similarly REF A is stored as the following sequence shown this time in the native command set SV40000 FE2 WS MR 40000 WS FE WS SV100000 This sequence when read with MAC is recognized by the DLL and translated back to REF A obscuring the fact that it occupi
68. ntifiers for installed digital output channels Each character in the returned string is the valid channel identifier of an installed digital output channel For a Mercury Class controller Release 1 0 1 www pi ws Page 24 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E network the string contains 4 characters for each connected axis see Section 1 3 2 for details Call Mercury_DIO using these IDs to set the states of the outputs Parameters ID ID of controller network szBuffer buffer to receive the identifier string maxlen size of szBuffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_GetRefResult int ID const char szAxes int pnResult Get results of last call to Mercury REF p 39 Mercury _MNL p 30 or Mercury_MPL p 30 If still referencing or no reference move was started since startup of library the result is 0 Call Mercury_qREF p 35 to see which axes have a reference switch Mercury_REF can be used only for axes with reference switches Mercury MNL p 30 and Mercury MPL p 30 for axes with limit switches Call Mercury_IsReferencing to find out if there are axes still referencing Parameters ID ID of controller network szAxes string with axes if or NULL result refers to all axes pnResult pointer to array of integers to receive result 1 if successful O if reference move failed has not finished yet or axis does n
69. ore arguments given to function is invalid empty string index out ofrange Axis identifier is already in use by a connected stage Invalid axis identifier Could not access array data in COM server Range of array does not fit the number of parameters Invalid parameter ID given to SPA or SPA Number for AVG out of range must be gt 0 Incorrect number of samples given to WAV Generation of wave failed Motion error while axis in motion call CLR to resume operation Controller is already running a macro Configuration of PZT stage or amplifier failed Current settings are not valid for desired configuration Unknown channel identifier Error while reading writing wave generator parameter file Could not find description of wave form Maybe WG INI is missing The WGWaveEditor DLL function was not found at startup The user cancelled a dialog Error from C 844 Controller DLL necessary to call function not loaded or function not found in DLL The open parameter file is protected and cannot be edited There is no parameter file open Selected stage does not exist Page 57 PI 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 Release 1 0 1 PI Mercury Windows GCS 1 0 DLL PI_PARAMETER_FILE_ALREADY_OPENED PI PARAMETER FILE OPEN ERROR PI INVALID CONTROLLER VERSION PI PA
70. ot have the required switch Returns TRUE if successful FALSE otherwise BOOL Mercury_GOH int ID const char szAxes Corresponding command GOH Move all axes in szAxes to their home positions Arguments ID ID of controller network szAxes string with axes if or NULL all axes are affected Returns TRUE if successful FALSE otherwise BOOL Mercury_HLT int ID const char szAxes Corresponding command HLT Halt motion of szAxes smoothly Does not work for Mercury MNL Mercury MPL or Mercury REF motion use Mercury_ EmergencyStop p Fehler Textmarke nicht definiert instead after axis stops target is set to current position Sets error code 10 whether any motion is stopped or not Arguments ID ID of controller network szAxes string with axes if or NULL all axes are affected Returns TRUE if successful FALSE otherwise BOOL Mercury INI int ID const char szAxes Corresponding command INI Initialize szAxes resets motion control chip for the axis sets referenced state to not referenced sets the brake control line in the Brake OFF state and if axis was under joystick control disables the joystick Release 1 0 1 www pi ws Page 25 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Arguments ID ID of controller network szAxes string with axes if or NULL all axes are affected Returns TRUE if successful FALSE otherwise BOOL Mercury_IsMoving const int ID
71. properties and limits of a stage They can be changed by several functions but modifying them imprudently could cause damage to the stage So please handle these parameters with care Release 1 0 1 www pi ws Page 42 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Generally parameters should only be changed in real special cases and only after consultation with PI especially the servo loop parameters With Mercury_SPA p 36 you can obtain a list of the current parameter values in RAM 11 2 Parameter List Parameter numbers in italics apply to C 663 those in bold to C 862 1 P Term 0 to 32767 2 I Term 0 to 32767 3 D Term 0 to 32767 4 I Limit 0 to 32767 8 Maximum position error 0 to 32767 Counts 10 Maximum allowed velocity gt 0 Physical This parameter is a maximum units limit and not the current velocity By default the current velocity is half the maximum allowed velocity To change the current velocity use the VEL command 11 Maximum allowed Physical acceleration units 14 Numerator of the counts 1 to 2147483647 factor num denom per physical unit factor This factor includes the physical transmission ratio and the resolution of the stage Note To customize your physical unit use parameter 18 instead 15 Denominator of the 1 to 2147483647 factor num denom counts per physical unit This factor includes the physical factor transmission
72. ransmission Ratio and Scaling Factor vvvveeereeeerrrrrooes 45 12 Macro Storage on Controller cccccceseeeeeeeeeeeeeeeeeeeeees 46 12 1 Features and Restrictions esans nasyon ote dovesctenecasgasot caseteetalasyeashe 46 12 2 Native Macro Recording Mechanism rreeereeeerrrerrrrranananon 46 12 3 Macro Translation by the GCS DLL ee eeeeeeeeeeteeeeeeeeeees 46 12 3 1 Macro Creation from GOS 13 as idee sodo b s anben acer ian kota idee sik 46 12 3 2 GCS Listing Stored Macro k sekre kin s aka nbe ta ap seks e ka mea ke anana vn 48 12 3 3 Macro Translation and Listing Examples vvverrrerrrrreresenen 49 13 ErrOr COGS wissiissssscessescssscsteassssssscnteesssanssbscsassacsseasssueeecnss 50 14 INGO pt oi atc eee eee 60 0 Disclaimer This software is provided as is PI does not guarantee that this software is free of errors and will not be responsible for any damage arising from the use of this software The user agrees to use this software on his own responsibility Release 1 0 1 www pi ws Page 5 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 1 Introduction to MERCURY GCS DLL The PI Mercury Class GCS DLL allows controlling one or more PI Mercury Class controller networks each consisting of one or more Mercury Class controllers Each network is connected to a host PC via a single RS 232 or USB port NOTE Multiple controllers on a single host computer US
73. ratio and the resolution of the stage Note To customize your physical unit use parameter 18 instead 17 Invert the direction 1 to invert the direction else 1 18 Scaling factor This factor can be used to change 1 7976931348623 the physical unit of the stage e g 1E308 to a factor of 25 4 converts a 1 7976931348623 physical unit of mm to inches 1E308 It is recommended to use the DFF command to change this factor 19 Rotary stage 1 rotary stage else 0 20 Stage has a reference 1 the stage has a reference else 0 21 Maximum travel range in 0 to 2147483647 Physical positive direction units 22 Value at reference 2147483647 to Physical position 2147483647 units Release 1 0 1 www pi ws Page 43 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 23 Distance from the 2147483647 to Physiccal negative limit to the 2147483647 units reference position 24 Axis limit mode 0 positive limit switch active high pos HI negative limit switch active high neg HI 1 positive limit switch active low pos LO neg HI 2 pos HI neg LO 3 pos LO neg LO 25 Stage type 0 DC motor Wrong stage type will cause 2 Voice coil malfunction 4 Piezo motor 48 Maximum travel range in 2147483647 to Physiccal negative direction 2147483647 unit 49 Invert the reference 1 invert the reference else 0 60 Stage name maximum 15 charac
74. rcury Windows GCS 1 0 DLL 48 COM FTDIUSB EEPROM NOT PROGRAMMED 49 COM FTDIUSB INVALID ARGS 50 COM FTDIUSB NOT SUPPORTED 51 COM FTDIUSB OTHER ERROR 52 COM PORT ALREADY OPEN 53 COM PORT CHECKSUM ERROR 54 COM SOCKET NOT READY 55 COM SOCKET PORT IN USE 56 COM SOCKET NOT CONNECTED 57 COM SOCKET TERMINATED 58 COM SOCKET NO RESPONSE 59 COM SOCKET INTERRUPTED DLL Errors 1001 PI UNKNOWN AXIS IDENTIFIER 1002 PI NR NAV OUT OF RANGE 1003 PI INVALID SGA 1004 PI UNEXPECTED RESPONSE 1005 PI NO MANUAL PAD 1006 PI INVALID MANUAL PAD KNOB 1007 PI INVALID MANUAL PAD AXIS 1008 PI CONTROLLER BUSY 1009 PI THREAD ERROR 1010 PI IN MACRO MODE 1011 PI NOT IN MACRO MODE 1012 PI MACRO FILE ERROR Release 1 0 1 www pi ws Software Manual MS154E FTDIUSB EEPROM not programmed FTDIUSB invalid arguments FTDIUSB not supported FTDIUSB other error Error while opening the COM port was already open Checksum error in received data from COM port Socket not ready you should call the function again Port is used by another socket Socket not connected or not valid Connection terminated by peer Can t connect to peer Operation was interrupted by a non blocked signal Unknown axis identifier Number for NAV out of range must be in 1 10000 Invalid value for SGA must be one of 1 10 100 1000 Controller sent unexpected response No manual control pad installed calls to SMA and related command
75. rcury qREF int ID const char szAxes BOOL pbValarray BOOL Mercury_qRON int ID const char szAxes BOOL pbValarray BOOL Mercury_qSAI int ID char axes int maxlen BOOL Mercury qSAl ALL int ID char axes int maxlen BOOL Mercury_qSPA int ID const char szAxes const int iCmdarray double dValarray BOOL Mercury qSRGr int ID const char szAxes const int iCmdarray int iValarray BOOL Mercury qSVO int ID const char szAxes BOOL pbValarray BOOL Mercury_qTAC int D int pnNr BOOL Mercury_qTAV int ID int nChannel double pdValue BOOL Mercury_qTIO int ID int pNr BOOL Mercury_qTMN int ID const char szAxes double pdValarray BOOL Mercury qTMX int ID const char szAxes double pdValarray BOOL Mercury qTNJ int ID int pnNr BOOL Mercury_qTVI int ID char axes const int maxlen BOOL Mercury_qVEL int ID const char szAxes double valarray BOOL Mercury_qVER int ID char buffer const int maxlen BOOL Mercury_qVST int D char buffer int maxlen BOOL Mercury_REF int ID const char szAxes BOOL Mercury RON int ID const char szAxes BOOL pbValarray BOOL Mercury SAI int ID const char szOldAxes const char szNewAxes BOOL Mercury SAV int ID const char szAxes BOOL Mercury SPA int ID const char szAxes int iCmdarray double dValarray BOOL Mercury STP int ID BOOL Mercury SVO int ID const char szAxes BOOL pbValarray BOOL Mercury VEL int ID
76. rence axes without reference switches Mercury_MNL returns before the controller has finished Call Mercury_IsReferencing p 27 to find out if the axes are still moving and Mercury_GetRefResult p 25 to get the results of the referencing move The controller will be busy while referencing so most other commands will cause a PI CONTROLLER BUSY error Use Mercury_STP p Fehler Textmarke nicht definiert to stop referencing motion Arguments ID ID of controller network szAxes axes to move Returns TRUE if successful FALSE otherwise Errors PI UNKNOWN AXIS IDENTIFIER szAxes contains an invalid axis identifier BOOL Mercury MOV int ID const char szAxes double pdValarray Corresponding command Mov Move szAxes to absolute position Arguments ID ID of controller network szAxes string with axes pdValarray pointer to array with target positions for the axes Returns TRUE if successful FALSE otherwise BOOL Mercury MPL int ID const char szAxes Corresponding command MPL For each of the axes in szAxes in turn reset soft limits and home position move the axis past its positive limit switch and back until the limit switch disengages set the position counter to the maximum position value and set the reference state to referenced This can be used to reference axes without reference switches Mercury_MPL returns before the controller has finished Call Mercury_IsReferencing p 27 to fi
77. s Besides specification of the module type and other parameters like stack size function imports from DLLs can be declared In some cases the IDE supports static import libraries If that is the case the IDE might not support the ability to declare DLL imported functions in the module definition file When a module definition file is used the programmer must 1 Use a header or source file where the DLL functions have to be declared which is needed for the compiler In the declaration should be taken into account that these function come from a C Language Interface When building a C program the functions have to be declared with the attribute that they are coming from a C environment The VC compiler needs an extern C modifier The declaration also must be aware that these functions have to be called like standard Win API functions Therefore the VC compiler need a WINAPI or stdcall modifier in the declaration 2 Modify the module definition file with an IMPORTS section In this section all functions used in the program must be named Follow the syntax of the IMPORTS statement Example IMPORTS PI_Mercury_GCS_DLL Mercury_TIsConnected 3 3 Using Windows API Functions If the library is not to be loaded during program startup it can sometimes be loaded during program execution using Windows API functions The entry point for each desired function has to be obtained The DLL linking loading with API functions during program execution ca
78. s See Mercury_RON for a detailed description of reference mode Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pbValarray pointer to array to receive reference modes for the specified axes Returns TRUE if successful FALSE otherwise BOOL Mercury_qSAI int ID char axes const int maxlen Corresponding command SAI Get connected axes Each character in the returned string is an axis identifier for one connected axis Arguments ID ID of controller network axes buffer to receive the string read in maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise Release 1 0 1 www pi ws Page 35 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury qSAl ALL int ID char axes int maxlen Corresponding GCS command SAI ALL Get all possible axes and not only all connected and configured axes as returned by the Mercury qSAl function Each character in the returned string is an axis identifier for one possible axis Arguments ild ID of controller network axes buffer to store the read in string maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury qSPA int ID const char szAxes int iCmdarray double dValarray Corresponding command SPA Read parameters for szAxes For each desired parameter you must specify a
79. s are not allowed Invalid number for manual control pad knob Axis not currently controlled by a manual control pad Controller is busy with some lengthy operation e g reference move fast scan algorithm Internal error could not start thread Controller is already in macro mode command not valid in macro mode Controller not in macro mode command not valid unless macro mode active Could not open file to write or read macro Page 56 PI 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 Release 1 0 1 PI Mercury Windows GCS 1 0 DLL PlI_NO_MACRO_OR_EMPTY PI MACRO EDITOR ERROR PI INVALID ARGUMENT PI AXIS ALREADY EXISTS PI INVALID AXIS IDENTIFIER PI COM ARRAY ERROR PI COM ARRAY RANGE ERROR PI INVALID SPA CMD ID PI NR AVG OUT OF RANGE PI WAV SAMPLES OUT OF RANGE PI WAV FAILED PI MOTION ERROR PI RUNNING MACRO PI PZT CONFIG FAILED PI_PZT_CONFIG_INVALID_PARAMS PI UNKNOWN CHANNEL IDENTIFIER PI WAVE PARAM FILE ERROR PI UNKNOWN WAVE SET PI WAVE EDITOR FUNC NOT LOADED PI USER CANCELLED PI C844 ERROR PI DLL NOT LOADED PI PARAMETER FILE PROTECTED PI NO PARAMETER FILE OPENED PI STAGE DOES NOT EXIST www pi ws Software Manual MS154E No macro with given name on controller or macro is empty Internal error in macro editor One or m
80. stages with neither reference nor limit switch reference mode is automatically OFF Note that when the reference mode is off and the actual position is incorrectly set with Mercury_POS stages can be driven into the limit switch when moving to a position which is thought to be within the travel range of the stage but actually is not Release 1 0 1 www pi ws Page 39 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E Arguments ID ID of controller network szAxes string with axes pbValarray pointer to array to receive the reference modes for the specified axes Returns TRUE if successful FALSE otherwise Errors PI CNTR STAGE HAS NO LIM SWITCH if the axis has no reference or limit switches and reference mode can not be switched ON BOOL Mercury SAT int ID const char szOldAxes const char szNewAxes Corresponding command SAT Rename connected axes Axis designated by the first character in szOldAxes will be renamed to first character in szNewAxes etc with the remaining characters of the two equal length strings User can change the names of axes with this function The characters in szNewAxes character must not be in use for another existing axis and must be one of the valid identifiers All characters in szNewAxes will be converted to uppercase letters To find out which characters are valid call Mercury qTVI p 38 Only the last occurrence of an axis identifier in szNewAxes will be used to change the name
81. t D const char szAxes double pdValarray Corresponding GCS command DFF Get scale factors for szAxes set with Mercury_DFF Arguments ild ID of controller network szAxes string with axes if or NULL all axes are queried pdValarray pointer to array to receive factors of the axes Returns TRUE if successful FALSE otherwise BOOL Mercury_qDFH int ID const char szAxes double pdValarray Corresponding command DFH Get displacement of the home position from its default for szAxes in physical units Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pdValarray pointer to array to receive the home position displacements of the axes Returns TRUE if successful FALSE otherwise BOOL Mercury_qDIO int ID const char szChannels BOOL pbValarray Corresponding command DIO Get the states of szChannels digital input channel s Parameters ID ID of controller network szChannels string with digital input channel identifiers if or NULL all channels are queried pbValarray pointer to array to receive the states of digital input channels TRUE if HIGH FALSE if LOW Returns TRUE if successful FALSE otherwise BOOL Mercury_qERR int ID int pError Corresponding command ERR Get the error state of the controller It is safer to call Mercury_GetError p 18 because this will check the internal error state of the library f
82. te the neccessary space and tell the DLL how large the buffer is The COM server however expects a string object The COM server can let the string grow and the string object itself holds all the neccessary information about length and memory requirements Thus the following C or C and Visual Basic code is equivalent char sIDN 1024 Mercury gIDN ID SIDN 1024 C or C code Dim sIDN As String MERCURY gIDN sIDN Visual Basic Code 6 3 COM Properties A COM server can have so called properties These behave like ordinary variables but if you read from or write to them an internal function is triggered not every property needs to support both reading and writing Most GCS COM servers have a property moving So you do not need to call IsMoving but can simply use read that property and a call to IsMoving is generated internally Some GCS COM servers have properties for many axis identifiers If you assign a new value to one of these properties and the corresponding axis is connected a MOV is sent If you read from such a property the COM will first call POS and then set the value Here are two more blocks of equivalent code BOOL bIsReferencing do Sleep 100 Mercury IsReferencing ID amp bIsReferencing while bReferencing TRUE Mercury MOV ID A 10 Sleep 1000 double currentPos Mercury qPOS ID A amp currentPos C or C code Do Sleep 100 Release 1 0 1 www p
83. ters 64 Hold Current HC native command in mA 65 Drive Current DC native command in mA 66 Hold Time HT native command in ms 67 max current max value that DC and HC can have in mA Release 1 0 1 www pi ws Page 44 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E 11 3 Transmission Ratio and Scaling Factor The physical unit used for the stages i e for the axes of the controller results from the following interrelation of some stage parameters POZ Gap ese CpuD CpuN CpuD Cnt PU SF x Description Physical Unit Numerator of the counts per physical unit factor Denominator of the counts per physical unit factor Scaling factor Number means the parameter ID in Mercury_SPA p 41 and Mercury_qSPA p 36 and in the list in Section 11 2 See also Mercury_DFF p 23 The Counts per physical unit factor which results from parameter 14 divided by parameter 15 includes the physical transmission ratio and the resolution of the stage CAUTION To customize the physical unit of a stage do not change parameter 14 and parameter 15 but use Mercury DFF p 23 instead Although Mercury DFF has the same effect as changing parameter 18 with Mercury SPA you should only use Mercury DFF and not Mercury SPA to modify the scaling factor Example If you set with Mercury DFF a value of 25 4 for an axis the physical unit for this axis is converted from mm to inches Release 1
84. th DIO lt channel gt lt b gt as condition Mercury_MEX with JBS lt joystick gt 1 lt b gt as condition Mercury_MVR Mercury_REF generates a large number of native commands in the macro see below Mercury SPAQ Access to the following SPA parameters by macros is permitted all others will be ignored e 1 P Term e 2 l Term e 3 D Term e 4 Limit e 8 Max Position Error e 10 Max Velocity e 11 Max Acceleration muss gt 200 sein e 24 Limit Switch Mode e e e e P 00000 O 50 No Limit Switch 64 Hold Current HC native command in mA 65 Drive Current DC native command in mA 66 Hold Time HT native command in ms Mercury_STP Mercury_SVO Mercury_VEL Mercury_WAC with DIO lt channel gt lt b gt as condition where b 1 or 0 for TRUE FALSE o Mercury WAC with ONT axis 1 as condition 12 3 2 GCS Listing Stored Macros When the Mercury_qMAC function is used with a macro name to list the contents of a macro the native commands stored on the unit are translated back to GCS commands See the GCS Mercury Commands Manual document MS163E for details with all the implications that entails Functions that cause several native commands to be stored in the macro may not be recognized when the macro is listed making it possible to see the GCS versions of the individual functions see INI example below oooo The native command versions can of course be ma
85. to the software as an additional RS 232 COM port That port is present only when the Mercury USB device is connected and powered up The baud rate setting must agree with that set on all devices in the network CAUTION Never connect the RS 232 IN and USB connectors of the same controller to a PC at the same time as damage may result 9 4 1 RS 232 Settings e COM Port Select the desired COM port of the PC something x like COM1 or COM2 The user will see only the ports available on the system If the USB drivers are installed and a Mercury CoMPart com gt Class controller with USB interface is connected and powered up the USB interface will appear as an additional COM port Baudrate 9600 gt e Baud Rate The baud rate of the interface Default value is 9600 as shown The settings here and on the controller hardware should match Cancel 10 Mercury Class Commands 10 1 Functions BOOL Mercury_BRA int ID const char szAxes BOOL pbValarray BOOL Mercury_CST int ID const char szAxes const char names BOOL Mercury_DEL int ID double dSeconds BOOL Mercury_DFF int ID const char szAxes const double pdValarray BOOL Mercury_DFH int ID const char szAxes BOOL Mercury DIO int ID const char szChannels BOOL pbValarray BOOL Mercury_GcsCommandset int ID char const szCommand BOOL Mercury GcsGetAnswer int ID char szAnswer const int bufsize BOOL Mercury_GcsGetAnsw
86. ts to use for szAxes e g a factor of 25 4 converts the basic physical units of millimeters of all axes in szAxes to inches See also Section 11 3 on p 45 Arguments ild D of controller network szAxes string with axes pdValarray factors for the axes Returns TRUE if successful FALSE otherwise BOOL Mercury_DFH int ID const char szAxes Corresponding command DFH Makes current positions of szAxes the new home position Arguments ID ID of controller network szAxes string with axes if or NULL all axes are affected Returns TRUE if successful FALSE otherwise BOOL Mercury_DIO int ID const char szChannels BOOL pbValarray Corresponding command DIO Set digital output channels high or low If pbValarray index is TRUE the mode is set to HIGH otherwise it is set to LOW Parameters ID ID of controller network szChannels string with digital output channel identifiers Mercury_GetOutputChannelNames can be used to retrieve the channel names valid for Mercury_DIO Release 1 0 1 www pi ws Page 23 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E pbValarray array containing the states of specified digital output channels TRUE for HIGH FALSE for LOW Returns TRUE if successful FALSE otherwise BOOL Mercury_GcsCommandset int ID char const szxCommand Sends a GCS command to the controller network Arguments ID ID of controller network szCommand the GCS com
87. ury_qLIM int ID const char szAxes BOOL pbValarray Corresponding command LIM Check if the given axes have limit switches Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pbValarray pointer to array to receive the limit switch info TRUE if axis has limit switches FALSE if not Returns TRUE if successful FALSE otherwise BOOL Mercury_qMAC int ID char szName char szBuffer const int maxlen Corresponding command MAC Get available macros or list contents of a specific macro If szName is empty or NULL all available macros are listed in szBuffer separated with line feed characters Otherwise the content of the macro with name szName is listed the single lines separated with by line feed characters If there are no macros stored or the requested macro is empty the answer will be Arguments ID ID of controller network szName string with name of the macro to list szBuffer buffer to receive the string read in from controller lines are separated by line feed characters maxlen size of buffer must be given to avoid buffer overflow Returns TRUE if successful FALSE otherwise BOOL Mercury_qMOV int ID const char szAxes double pdValarray Corresponding command Mov Read the commanded target positions for szAxes Arguments ID ID of controller network szAxes string with axes if or NULL all axes are queried pdValarray pointer to
88. utChannelNames 23 Mercury GetRefResult 24 Release 1 0 1 www pi ws Software Manual MS154E Mercury GOH 24 Mercury HLT 24 Mercury INI 24 Mercury InterfaceSetupDlg 18 Mercury ISConnected 18 Mercury IsMoving 25 Mercury IsRecordingMacro 25 Mercury_IsReferenceOK 25 Mercury_IsReferencing 26 Mercury IsRunningMacro 26 Mercury JDT 26 Mercury JON 26 Mercury MAC BEG 27 Mercury MAC DMC 27 Mercury MAC NSTART 28 Mercury MAC START 28 Mercury MEX 28 Mercury MNL 29 Mercury MOV 29 Mercury MPL 29 Mercury MVR 30 Mercury OpenPiStagesEditDialog 16 Mercury OpenUserStagesEditDialog 17 Mercury POS 30 Mercury qBRA 30 Mercury qCST 31 Mercury qDFF 31 Mercury qDFH 31 Mercury qDIO 31 Mercury qgERR 32 Mercury_qHLP 32 Mercury_qIDN 32 Mercury_qJAX 32 Mercury_qJON 33 Mercury qLIM 33 Mercury_qMAC 33 Mercury_qMOV 34 Mercury_qONT 34 Mercury qPOS 34 Mercury_qREF 34 Mercury gRON 35 Mercury qSAl 35 Mercury qSAl ALL 35 Mercury qSPA 35 Mercury qSRG 36 Mercury qSVO 36 Mercury qTAC 36 Mercury qTAV 36 Mercury qTIO 37 Mercury qTMN 37 Mercury qTMX 37 Mercury qgTNJ 37 Mercury qTVI 38 Mercury qVEL 38 Mercury qVER 38 Mercury qVST 38 Mercury ReceiveNonGCSString 14 Page 60 PI PI Mercury Windows GCS 1 0 DLL Mercury_REF 39 Software Manual MS154E RS 232 settings 19 Mercury_RemoveStage 16 SAI 39 Mercury_RON 39 SAI 35 Mercury_SAI 39 SAI ALL 35 Mercury SendNonGCSString 14 settings for RS 232 19 Mercury SetError
89. xes In a Mercury Class controller network the different axes correspond to the different individual controllers 4 3 Axis Parameters The parameters for the axes are stored in an array passed to the function The parameter for the first axis is stored in array 0 for the second axis in array 1 and so on So if you call Mercury_qPOS ABC double pos 3 the position for A is in pos 0 for B in pos 1 and for C in pos 2 Axes szAxes ABC Positions pos 1 0 2 0 3 0 szAxes 0 A pos 0 1 0 szAxes 1 B pos 1l 2 0 szAxes 2 C pos 2 3 0 If you call Mercury_MOV AC double pos 2 the target position for A is in pos 0 and for Cin pos 1 Each axis identifier is sent only once Only the last occurrence of an axis identifier is actually sent to the controller with its argument Thus if you call Mercury MOV AAB pos 3 withpos 3 1 0 2 0 3 0 A will move to 2 0 and B to 3 0 If you then call Mercury qPOS AAB pos 3 pos 0 and pos 1 will contain 2 0 as the position of A See Mercury_MOV p 30 and Mercury qPOS p 35 See Types Used in PI Software p 11 for a description of types used for parameters 5 Types Used in PI Software 5 1 Boolean Values The library uses the convention used in Microsoft s C for boolean values If your compiler does not support this directly it can be easily set up Just add the
90. y_MAC_END int ID Corresponding command MAC END Take the DLL out of macro recording mode This function resets a flag in the library and effects the operation of certain other functions Function will fail if the DLL is not in recording mode See Macro Storage on Controller beginning on p 46 for more details Arguments ID ID of controller network Returns TRUE if successful FALSE otherwise Errors PI NOT IN MACRO MODE the controller was not recording a macro Release 1 0 1 www pi ws Page 28 PI PI Mercury Windows GCS 1 0 DLL Software Manual MS154E BOOL Mercury_MAC_NSTART int ID char szName int nrRuns Corresponding command MAC START Start macro with name szName The macro is repeated nrRuns times To find out what macros are available call Mercury_qMAC p 34 See Macro Storage on Controller beginning on p 46 for more details Arguments ID ID of controller network szName string with name of the macro to start nrRuns nr ofruns Returns TRUE if successful FALSE otherwise BOOL Mercury_MAC_START int ID char szName Corresponding command MAC START Start macro with name szName To find out what macros are available call Mercury_qMAC p 34 See Macro Storage on Controller beginning on p 46 for more details Arguments ID ID of controller network szName string with name of the macro to start Returns TRUE if successful FALSE otherwise BOOL Mercury_M

Table of Contents :

Contents

Download Pdf Manuals

Related Search

Related Contents