SPiiPlus C Library (V5-20)
SPiiPlus C Library (V5-20)
C Library
Programmers’ Guide
Version 5.20
V e r s i o n 5 . 2 0 , October 30, 2006
COPYRIGHT
Copyright ® 1999 - 2005 ACS Motion Control Ltd.
Changes are periodically made to the information in this document. Changes are published as release
notes and are be incorporated into future revisions of this document.
No part of this document may be reproduced in any form without prior written permission from ACS
Motion Control.
TRADEMARKS
ACS Motion Control, PEG and SPii are trademarks of ACS Motion Control Ltd.
Visual Basic and Windows are trademarks of Microsoft Corporation.
Any other companies and product names mentioned herein may be the trademarks of their respective
owners.
Website: http://www.AcsMotionControl.com
Information: [email protected]
Tech Support: [email protected]
Page Change
16 Section 3.3.1, Redistributed Files - updated lists
16 Section 3.3.2, File Destinations - updated lists
99 Section 5.40.3, information in paragraph updated
128 Section 5.54, acsc_GetConf Spelling correction in function name; int * Value
changed to double * Value
193 Section 5.94, acsc_GetSingleMessage - new function
272 Section 5.140, acsc_SetCallback - interrupt parameters updated, updated
information in the Note
274 Section 5.141, acsc_SetCallbackExt - interrupt parameters updated, updated
information in the Note
280 Section 5.144, acsc_SetConf - key parameters updated
291 Section 5.151, acsc_SetInterruptMask - parameters updated
313 Section 5.165, acsc_SetServer - new function added
388 Section 7.12, Callback Interrupts Types - this section is rearranged into
Table 52, Callback Interrupts Types - Hardware and Table 53, Callback
Interrupts Types - Software
390 Section 7.13, Callback Interrupts Masks - new masks added
Page Change
5 Section 2.1, Operation Environment - Support for Microsoft Windows
authentication as required by Windows XP Service Pack 2.
5 Section 2.2, Communication Log - Description of the implementation of the User-
Mode Driver communication log.
31 Table 37, Error Diagnosis - acsc_GetMotionError removed from table
119 acsc_FlushLogFile - New function
132 acsc_GetEthernetCards - New function
165 acsc_GetMotionError - Obsolete function, note added
315 acsc_SetServerExt - New function
316 acsc_SetServerLoginExt - New function
Table of Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Organization of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Related SPiiPlus Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 The SPiiPlus Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.4 Conventions Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.5 Statement Text and Icons Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Operation Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Communication Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 C Library Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Communication Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Controller Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.7 Supplied Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.8 Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2.9 Use of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.10 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.11 Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.12 Hardware Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.13 Dual-port RAM (DPRAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.14 Non-waiting Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
3 Using the SPiiPlus C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.1 Library Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.2 Building C/C++ Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 Redistribution of User Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4 List of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.1 Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.2 Service Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.3 ACSPL+ Program Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
4.4 Read and Write Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.5 Load File to ACSPL+ Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.6 Multiple Thread Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.7 History Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
4.8 Unsolicited Messages Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.9 Log File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.10 System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.11 Setting and Reading the Motion Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
4.12 Axis/Motor Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.13 Motion Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.14 Point-to-Point Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
4.15 Track Motion Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.16 Jogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.17 Slaved Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
4.18 Multi-Point Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5.32 acsc_DownloadBuffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.33 acsc_Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.34 acsc_EnableFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
5.35 acsc_EnableM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
5.36 acsc_EnableResponse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
5.37 acsc_EndSequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
5.38 acsc_EndSequenceM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
5.39 acsc_ExtAddPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
5.40 acsc_ExtAddPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
5.41 acsc_ExtArc1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
5.42 acsc_ExtArc2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
5.43 acsc_ExtLine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
5.44 acsc_ExtToPoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
5.45 acsc_ExtToPointM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
5.46 acsc_FaultClear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
5.47 acsc_FaultClearM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
5.48 acsc_FlushLogFile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.49 acsc_GetAcceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.50 acsc_GetAnalogInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.51 acsc_GetAnalogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.52 acsc_GetAxisState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
5.53 acsc_GetCommOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.54 acsc_GetConf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
5.55 acsc_GetDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
5.56 acsc_GetDefaultTimeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
5.57 acsc_GetEthernetCards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
5.58 acsc_GetErrorString . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
5.59 acsc_GetExtInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
5.60 acsc_GetExtInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
5.61 acsc_GetExtOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
5.62 acsc_GetExtOutputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
5.63 acsc_GetFault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
5.64 acsc_GetFaultMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
5.65 acsc_GetFirmwareVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
5.66 acsc_GetFPosition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
5.67 acsc_GetFVelocity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
5.68 acsc_GetHistory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
5.69 acsc_GetIndexState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
5.70 acsc_GetInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
5.71 acsc_GetInputPort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
5.72 acsc_GetInterruptMask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
5.73 acsc_GetJerk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
5.74 acsc_GetKillDeceleration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
5.75 acsc_GetLastError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
5.76 acsc_GetLibraryVersion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.77 acsc_GetMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
5.78 acsc_GetMotionError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
5.79 acsc_GetMotorError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
List of Tables
Table 1 Related SPiiPlus Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Table 2 Collateral Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Table 3 Text Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Table 4 Hardware Interrupt Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Table 5 Registry Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Table 6 Registry Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Table 7 Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Table 8 Service Communication Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Table 9 ASSPL+ Program Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Table 10 Read and Write Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 11 Load File to ACSPL+ Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 12 Multiple Thread Synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 13 History Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Table 14 Unsolicited Messages Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 15 Log File Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 16 System Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 17 Setting and Reading Motion Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Table 18 Axis/Motor Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Table 19 Motion Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 20 Point-to-Point Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 21 Track Motion Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 22 Jogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 23 Slaved Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Table 24 Multi-point Motion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 25 Arbitrary Path Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 26 PVT Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 27 Segmented Motion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Table 28 Points and Segments Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 29 Data Collection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Table 30 Status Report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 31 Input/Output Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Table 32 Safety Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 33 Wait-for-Condition Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Table 34 Callback Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 35 Variables Management. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 36 Service Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Table 37 Error Diagnosis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 38 Dual Port RAM (DPRAM) Access Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 39 Position Event Generation (PEG) Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Table 40 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
Table 41 General Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Table 42 General Communication Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Table 43 Ethernet Communication Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Table 44 Axis Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Table 45 Motion Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Table 46 Data Collection Flags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Table 47 Data Collection Flags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Table 48 Axis State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Table 49 Index and Mark State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Table 50 Program State Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
List of Figures
Figure 1 C Library Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1 Introduction
The SPiiPlus C Library supports the creation of a user application that operates in a PC host
computer and communicates with SPiiPlus motion controllers. The SPiiPlus C Library
implements a rich set of controller operations and conceals from the application the complexity
of low-level communication and synchronization with the controller.
Note
Highlights an essential operating or maintenance procedure,
condition, or statement
Model
Model Dependent Text Here!
CAUTION
Caution describes a condition that may result in damage to
equipment.
2 General Information
communication tasks.
The host application is provided with a robust C Function API to make calls the C Library
which in turn communicates with the SPiiPlus Controller through the controller drivers. The
controller then returns the reply to the to the caller application.
The host application may contact C Library from remote location by setting its IP address or
the machine name. Set the IP address with the acsc_SetServer function.
Up to four host applications may communicate with the controller simultaneously via a single
physical connection.
Host
Application 2
Remote
C Library Application
spiiplushost
2.8 Highlights
• Unified support of all communication channels (Serial, Ethernet, PCI Bus)
All functions except acsc_OpenComm*** functions are identical for all communication
channels. The user application remains substantially the same and works through any of the
available communication channels.
• Controller simulator as an additional communication channels
All library functions can work with the Simulator exactly as with the actual controller. The
user application activates the simulator by opening a special communication channel. The
user is not required to change his application in order to communicate with the Simulator.
• Support of multi-threaded user application
The user application can consist of several threads. Each thread can call SPiiPlus C Library
functions simultaneously. The library also provides special functions for the
synchronization SPiiPlus C functions called from concurrent threads.
• Automatic synchronization and mutual exclusion of concurrent threads
Both waiting and non-waiting calls of SPiiPlus C functions can be used from different
threads without any blocking or affect one to another. The library provides automatic
synchronization and mutual exclusion of concurrent threads so the threads are not delayed
one by another. Each thread operates with its maximum available rate.
• Concurrent support of up to 10 communication channels in one application
One application can open up to 10 communication channels simultaneously. Different
communication channels are usually connected to different controllers. However, two or
more communication channels can be connected to one controller. For example, one
application can communicate with one controller through both Ethernet and serial links.
• Acknowledgement for each controller command
The library automatically checks the status of each command sent by the user application to
the controller. The user application can check the status to confirm that the command was
received successfully. This applies for both waiting and non-waiting calls.
• Communication history
The library supports the storage of all messages sent to and received from the controller in
a memory buffer. The application can retrieve the full or partial contents of the buffer and
can clear the history buffer.
• Separate processing of unsolicited messages
Most messages sent from the controller to the host are responses to the host commands.
However, the controller can send unsolicited messages, for example, because of executing
the disp command. The library separates the unsolicited messages from the overall message
flow and provides special function for handling unsolicited messages.
• Rich set of functions for setting and reading parameters, motion, program
management, I/O ports, safety controls, and other.
• Two calling modes
Most library functions can be called in either waiting or non-waiting mode. In waiting
mode, the calling thread does not continue until the controller acknowledges the command
execution. In non-waiting mode, a function returns immediately and the actual work of
sending the command and receiving acknowledgement is performed by the internal thread
of the library.
• Debug Tools
The library provides different tools that facilitate debugging of the user application. The
simulator and the communication history mentioned above are the primary debugging
tools. The user can also open a log file that stores all communications between the
application and the controller.
• Setting user callback functions for predefined events
The possibility exists to set a callback function that will be called when a specified event
occurs in the controller. This lets you define a constant reaction by the user host application
to events inside the controller without polling the controller status. See “Callbacks” on
Page 9,
• Wait-for-Condition Functions
To facilitate user programming, the library includes functions that delay the calling thread
until a specific condition is satisfied. Some of the functions periodically pole the relevant
controller status until the condition is true, or the time out expired. Some of these functions
are based on the callback mechanism, see “Callbacks” on Page 9. The functions with this
option are:
• acsc_WaitMotionEnd
• acsc_WaitLogicalMotionEnd
• acsc_WaitProgramEnd
• acsc_WaitInput
These functions will use the callback mechanism if the callback to the relevant event is set,
otherwise polling is used.
• Support for Windows 9/x/NT/2000/ME
The user application that communicates through the library takes no notice of the
operational environment. The library itself chooses the proper device driver and conceals
all differences between the operating systems from the user application.
2.10 Callbacks
There is an option to define an automatic response in the user application to several events
inside the controller. The user specifies a function that will be called when certain event occurs.
This approach helps user application to avoid polling of the controller status and only to execute
the defined reaction when it is needed.
The library may set several callbacks in the same time. Every one of them runs in its own thread
2.11 Timing
When working with PCI bus, the callbacks are initiated through physical interrupts generated
by the controller. In the Simulator, the interrupt mechanism is emulated with OS mechanisms.
In all other kinds of communication, the controller sends an alert message over the
communication channel in order to inform the host about the event.
Although the implementation is transparent, the timing is different varies for each
communication channel as follows:
• In PCI communication, the callbacks are based upon PCI interrupts and response is very fast
(sub-millisecond level).
• In all other channels, callback operation includes sending/receiving a message that requires
much more time. Specific figures depend on the communication channel rate.
From the viewpoint of the Callback Mechanism, all communication channels are functionally
equivalent, but differ in timing.
Note
Do not use ‘0’ as the Null character.
• If Wait is a valid pointer, the call is non-waiting and the function returns immediately.
• If Wait is ACSC_IGNORE, the call is non-waiting and will neglect of the operation result.
ACSC_WAITBLOCK is defined as follows:
Structure: ACSC_WAITBLOCK { HANDLE Event; int Ret; };
When a thread activates a non-waiting call, the library passes the request to an internal thread
that sends the command to the controller and then monitors the controller responses. When the
controller responds to the command, the internal thread stores the response in the internal
buffers. The calling thread can retrieve the controller response with help of the
acsc_WaitForAsyncCall function and validate the completion result in the Ret member of the
structure.
Up to 256 non-waiting calls can be activated before any acsc_WaitForAsyncCall is called. It
{
// something doing here
….
// retrieve controller response
if (acsc_WaitForAsyncCall(Handle, buf, &Received, &wait, 5000))
{
buf[Received] = ‘\0’;
printf(“Motors state: %s\n”, buf);
}
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘\0’;
printf(“error: %s\n”, buf);
}
}
else
{
printf(“transaction error: %d\n”, acsc_GetLastError());
}
If (acsc_Transaction( Handle,cmd,strlen(cmd),buf,
100, &Received, ACSC_IGNORE))
{
printf(“transaction error: %d\n”, acsc_GetLastError());
}
Note
If the application is executed on a computer without the SPiiPlus
software package installation, the user must install several library and
support files. This process is called “redistribution”.
Note
The INF files are required only for registration process; they should be
placed at well-known destination.
Copy ACSCSRV.EXE to target machine. The exact place is not important; it is convenient to
put it in the application directory. The main thing is to configure Windows to launch
ACSCSRV.EXE on start-up.
The preferred way to do so is to make an addition to the registry key as follows:
HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Run a new string
value named “ACSCSRV”
The string should contain the full path to the location of ACSCSRV.EXE.
On start-up Windows will start the user-mode driver on the current machine for each user that
logs in.
Note
ACSCSRV.EXE may be placed anywhere on the target machine.
4 List of Functions
4.16 Jogging
Table 22 Jogging
Function Description
acsc_Jog Initiates a single-axis jog motion.
acsc_JogM Initiates a multi-axis jog motion.
5.1 acsc_AddPoint
The function adds a point to a single-axis multi-point or spline motion.
int acsc_AddPoint(HANDLE Handle, int Axis, double Point, ACSC_WAITBLOCK*
Wait)
5.1.1 Parameters
5.1.3 Remarks
The function adds a point to a single-axis multi-point or spline motion. To add a point to a multi-
axis motion, use acsc_AddPVPointM. To add a point with a specified non-default velocity or
time interval use acsc_AddPVPoint or acsc_AddPVPointM.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the point is added to the
motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call
this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.1.4 Example
5.2 acsc_AddPointM
The function adds a point to a multi-axis multi-point or spline motion.
int acsc_AddPointM(HANDLE Handle, int* Axes, double* Point,
ACSC_WAITBLOCK* Wait)
5.2.1 Parameters
Axes Array of involved axes. Each element specifies one involved axis:
ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y – to Y etc. After the
last axis, one additional element must be located that contains –1 and
marks the end of the array.
For the full list of the axis constants, see “Axis Definitions” on
Page 383.
Point Array of the coordinates of added point. The number and order of values
must correspond to the Axes array. The Point must specify a value for
each element of Axes except the last –1 element.
5.2.3 Remarks
The function adds a point to a multi-axis multi-point or spline motion. To add a point to a single-
axis motion, use acsc_AddPoint. To add a point with a specified non-default velocity or time
interval use acsc_ExtAddPoint or acsc_ExtAddPointM.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the point is added to the
motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call
this function periodically until the function returns non-zero value.
All axes specified in the Axes array must be specified before the call of the acsc_MultiPointM
or acsc_SplineM function. The number and order of the axes in the Axes array must correspond
exactly to the number and order of the axes of acsc_MultiPointM or acsc_SplineM functions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
5.2.4 Example
5.3 acsc_AddPVPoint
The function adds a point to a single-axis PV spline motion and specifies velocity.
int acsc_AddPVPoint(HANDLE Handle, int Axis, double Point, double Velocity,
ACSC_WAITBLOCK* Wait)
5.3.1 Parameters
5.3.3 Remarks
Before this function can be used, PV spline motion must be initiated by calling acsc_Spline
with the appropriate flags.
The function adds a point to a single-axis PV spline motion with a uniform time and specified
velocity at that point
To add a point to a multi-axis PV motion, use acsc_AddPVPointM. To add a point to a PVT
motion with non-uniform time interval, use the acsc_AddPVTPoint and
acsc_AddPVTPointM functions. The function can wait for the controller response or can
return immediately as specified by the Wait argument.
The controller response indicates that the command was accepted and the point is added to the
motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call
this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.3.4 Example
int i;
if (!acsc_Spline(Handle, // communication handle
ACSC_AMF_CUBIC, //PV motion uniform time inteval
ACSC_AXIS_X, // axis X
10, // uniform interval 10 ms
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// add some points
for (i = 0; i <100; i++)
acsc_AddPVPoint(Handle,ACSC_AXIS_X,i*100,i*100,NULL);
//position,velocity and time interval for each point
5.4 acsc_AddPVPointM
The function adds a point to a multiple-axis PV spline motion and specifies velocity.
int acsc_AddPVPointM(HANDLE Handle, int *Axis, double *Point, double *Velocity,
ACSC_WAITBLOCK* Wait)
5.4.1 Parameters
Point Array of the coordinates of added point. The number and order of values
must correspond to the Axes array. The Point must specify a value for
each element of Axes except the last –1 element.
Velocity Array of the velocities of added point. The number and order of values
must correspond to the Axes array. The Velocity must specify a value
for each element of Axes except the last –1 element.
5.4.3 Remarks
Before this function can be used, PVT spline motion must be initiated by calling acsc_SplineM
with the appropriate flags.
The function adds a point to a multiple-axis PV spline motion with a uniform time and specified
velocity at that point.
To add a point to a single-axis PV motion, use acsc_AddPVPoint. To add a point to a PVT
motion with non-uniform time interval, use the acsc_AddPVTPoint and
acsc_AddPVTPointM functions.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the point is added to the
motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call
this function periodically until the function returns non-zero value.
All axes specified in the Axes array must be specified before the call of the acsc_MultiPointM
or acsc_SplineM function. The number and order of the axes in the Axes array must correspond
exactly to the number and order of the axes of acsc_MultiPointM or acsc_SplineM functions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.4.4 Example
int i;
int Axis[]={ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z,-1};
double Point[3];
double Velocity[3];
if (!acsc_SplineM(Handle, // communication handle
ACSC_AMF_CUBIC, // PV motion
Axis, // axis X
10, // uniform interval 10 ms
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// add some points
for (i = 0; i <100; i++)
{
Point[0]=i*50; Point[1]=i*100; Point[2]=i*150;
Velocity[0]=i*50; Velocity [1]=i*100; Velocity [2]=i*150;
acsc_AddPVPointM(Handle,Axis,Point,Velocity,NULL);
//position,velocity and time interval for each point
}
// the end of the arbitrary path motion
acsc_EndSequence(Handle, ACSC_AXIS_X, NULL);
5.5 acsc_AddPVTPoint
The function adds a point to a single-axis PVT spline motion and specifies velocity and motion
time.
int acsc_AddPVTPoint(HANDLE Handle, int Axis, double Point, double Velocity,double
TimeInterval, ACSC_WAITBLOCK* Wait)
5.5.1 Parameters
TimeInterval If the motion was activated by the acsc_Spline function with the
ACSC_AMF_VARTIME flag, this parameter defines the time interval
between the previous point and the present one.
5.5.3 Remarks
Before this function can be used, PV spline motion must be initiated by calling acsc_Spline
with the appropriate flags.
The function adds a point to a single-axis PVT spline motion with a non-uniform time and
specified velocity at that point.
To add a point to a multi-axis PVT motion, use acsc_AddPVTPointM. To add a point to a PV
motion with uniform time interval, use the acsc_AddPVPoint and acsc_AddPVPointM
functions.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the point is added to the
motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call
this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.5.4 Example
int i;
if (!acsc_Spline(Handle, // communication handle
ACSC_AMF_CUBIC|ACSC_AMF_VARTIME,//PVT motion
ACSC_AXIS_X, // axis X
0, // uniform interval is not used
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// add some points
for (i = 0; i <100; i++)
acsc_AddPVTPoint(Handle,ACSC_AXIS_X,i*100,i*100,100+i,NULL);
//position,velocity and time interval for each point
5.6 acsc_AddPVTPointM
The function adds a point to a multiple-axis PVT spline motion and specifies velocity and
motion time.
int acsc_AddPVTPointM(HANDLE Handle, int *Axis, double *Point, double
*Velocity,double TimeInterval, ACSC_WAITBLOCK* Wait)
5.6.1 Parameters
Point Array of the coordinates of added point. The number and order of values
must correspond to the Axes array. The Point must specify a value for
each element of Axes except the last –1 element.
Velocity Array of the velocities of added point. The number and order of values
must correspond to the Axes array. The Velocity must specify a value for
each element of Axes except the last –1 element.
TimeInterval If the motion was activated by the acsc_SplineM function with the
ACSC_AMF_VARTIME flag, this parameter defines the time interval
between the previous point and the present one.
5.6.3 Remarks
Before this function can be used, PVT spline motion must be initiated by calling acsc_SplineM
with the appropriate flags.
The function adds a point to a multiple-axis PVT spline motion with a non-uniform time and
specified velocity at that point.
To add a point to a single-axis PVT motion, use acsc_AddPVTPoint. To add a point to a PV
motion with uniform time interval, use the acsc_AddPVPoint and acsc_AddPointM
functions.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the point is added to the
motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call
this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.6.4 Example
int i;
int Axis[]={ACSC_AXIS_X, ACSC_AXIS_Y, ACSC_AXIS_Z,-1};
double Point[3];
double Velocity[3];
if (!acsc_SplineM(Handle, // communication handle
ACSC_AMF_CUBIC|ACSC_AMF_VARTIME,//PVT motion
Axis, // axis X
0, // uniform interval is not used
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// add some points
for (i = 0; i <100; i++)
{
Point[0]=i*50; Point[1]=i*100; Point[2]=i*150;
Velocity[0]=i*50; Velocity [1]=i*100; Velocity [2]=i*150;
acsc_AddPVTPointM(Handle,Axis,Point,Velocity,100+i,NULL);
//position,velocity and time interval for each point
}
// the end of the arbitrary path motion
acsc_EndSequence(Handle, ACSC_AXIS_X, NULL);
5.7 acsc_AppendBuffer
The function appends one or more ACSPL+ lines to the program in the specified buffer.
int acsc_AppendBuffer(HANDLE Handle, int Buffer, char* Program, int Count,
ACSC_WAITBLOCK* Wait)
5.7.1 Parameters
5.7.3 Remarks
The function appends one or more ACSPL+ lines to the program in the specified buffer. If the
buffer already contains any program, the new text is appended to the end of the existing
program.
No compilation or syntax check is provided during downloading. In fact, any text, not only a
correct program, can be inserted into a buffer. In order to compile the program and check its
accuracy, the compile command must be executed after downloading.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.7.4 Example
5.8 acsc_Arc1
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point, the coordinates of the final point and the direction of rotation.
int acsc_Arc1(HANDLE Handle, int* Axes, double* Center, double* FinalPoint, int
Rotation, ACSC_WAITBLOCK* Wait)
5.8.1 Parameters
Center Array of the center coordinates. The number and order of values must
correspond to the Axes array. The Center must specify a value for each
element of the Axes except the last–1 element.
FinalPoint Array of the final point coordinates. The number and order of values
must correspond to the Axes array. The FinalPoint must specify a value
for each element of Axes except the last –1 element.
5.8.3 Remarks
The function adds an arc segment to the segmented motion and specifies the coordinates of the
center point, the coordinates of the final point and the direction of rotation. To add an arc
segment with a specified non-default velocity, use acsc_ExtArc1.
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of the acsc_Segment function.
The parameter Center specifies the coordinates of the arc center. The parameter FinalPoint
specifies the coordinates of the final point. All coordinates are absolute in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.8.4 Example
5.9 acsc_Arc2
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point and the rotation angle.
int acsc_Arc2(HANDLE Handle, int* Axes, double* Center, double Angle,
ACSC_WAITBLOCK* Wait)
5.9.1 Parameters
Center Array of the center coordinates. The number and order of values
must correspond to the Axes array. The Center must specify a value
for each element of Axes except the last –1 element.
5.9.3 Remarks
The function adds an arc segment to the segmented motion and specifies the coordinates of the
center point and the rotation angle. To add an arc segment with a specified non-default velocity,
use acsc_ExtArc2.
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of the acsc_Segment function.
The parameter Center specifies the coordinates of the arc center. The coordinates are absolute
in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns a non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item a call to the acsc_WaitForAsyncCall function.
5.9.4 Example
5.10 acsc_AssignPins
The function defines whether a digital output is allocated to the corresponding bit of the OUT
array (for general purpose use) or allocated for PEG function use.
int acsc_AssignPins(HANDLE Handle,int Axis,unsigned short Mask,
ACSC_WAITBLOCK* Wait)
5.10.1 Parameters
5.10.3 Remarks
The function calls the ACSPL command SetConf (205, axis, Mask), where Mask is the output
mask. For a description of the output mask, see the description of SetConf in the SPiiPlus
ACSPL+ programmers guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.10.4 Example
5.11 acsc_Break
The function terminates a motion immediately and provides a smooth transition to the next
motion.
int acsc_Break(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.11.1 Parameters
5.11.3 Remarks
The function terminates the executed motion that involves the specified axis only if the next
motion is waiting in the corresponding motion queue. The terminated motion can be either
single-axis or multi-axis.
If the motion queue contains no waiting motion, the break command is not executed
immediately. The current motion continues instead until the next motion is planned to the same
motion queue. Only then is the break command executed.
If no executed motion involves the specified axis, or the motion finishes before the next motion
is planned, the function has no effect.
When executing the break command, the controller terminates the motion immediately without
any deceleration profile. The controller builds instead a smooth third-order transition profile to
the next motion.
Use caution when implementing the break command with a multi-axis motion, because the
controller provides a smooth transition profile of the vector velocity. In a single-axis motion,
this ensures a smooth axis velocity. However, in a multi-axis motion an axis velocity can
change abruptly if the terminated and next motions are not tangent to the junction point. To
avoid jerk, the terminated and next motion must be tangent or nearly tangent in the junction
point.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.11.4 Example
5.12 acsc_BreakM
The function terminates several motions immediately and provides a smooth transition to the
next motions.
int acsc_BreakM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.12.1 Parameters
5.12.3 Remarks
The function terminates the executed motions that involve the specified axes. Only those
motions are terminated that have the next motion waiting in the corresponding motion queue.
The terminated motions can be either single-axis or multi-axis.
If a motion queue contains no waiting motion, the break command does not immediately affect
the corresponding axis. The current motion continues instead until the next motion is planned
to the same motion queue. Only then, the break command is executed.
If no executed motion involves the specified axis, or the corresponding motion finishes before
the next motion is planned, the function does not affect the axis.
When executing the break command, the controller terminates the motion immediately without
any deceleration profile. Instead, the controller builds a smooth third-order transition profile to
the next motion.
Use caution when implementing the break command with a multi-axis motion, because the
controller provides a smooth transition profile of the vector velocity. In a single-axis motion,
this ensures a smooth axis velocity, but in a multi-axis motion, an axis velocity can change
abruptly if the terminated and next motions are not tangent in the junction point. To avoid jerk,
the terminated and next motion must be tangent or nearly tangent in the junction point.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.12.4 Example
5.13 acsc_CancelOperation
The function cancels any asynchronous (non-waiting) call or all operations with the specified
communication handle.
int acsc_CancelOperation(HANDLE Handle, ACSC_WAITBLOCK* Wait)
5.13.1 Parameters
5.13.3 Remarks
If Wait points to a valid ACSC_WAITBLOCK structure, the function cancels the
corresponding call with the error ACSC_OPERATIONABORTED. If the corresponding call
was not found the error ACSC_CANCELOPERATIONERROR will be returned by
acsc_GetLastError function.
If Wait is NULL, the function cancels all of the waiting and non-waiting calls for the specified
communication handle.
5.13.4 Example
5.14 acsc_CaptureComm
The function captures a communication channel.
int acsc_CaptureComm(HANDLE Handle)
5.14.1 Parameters
5.14.3 Remarks
The function captures the communication handle for the calling thread and prevents access to
this communication handle from other threads.
If one thread captures the communication handle and another thread calls one of SPiiPlus C
Library functions using the same handle, the second thread will be delayed until the first thread
executes acsc_ReleaseComm.
The function provides ability to execute a sequence of functions without risk of intervention
from other threads.
5.14.4 Example
if (!acsc_CaptureComm(Handle))
{
printf("capture communication error: %d\n", acsc_GetLastError());
}
5.15 acsc_ClearBuffer
The function deletes the specified ACSPL+ program lines in the specified program buffer.
int acsc_ClearBuffer(HANDLE Handle, int Buffer, int FromLine, int ToLine,
ACSC_WAITBLOCK* Wait)
5.15.1 Parameters
5.15.3 Remarks
The function deletes the specified ACSPL+ program lines in the specified program buffer.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.15.4 Example
5.16 acsc_ClearVariables
The function deletes all persistent global variables.
int acsc_ClearVariables (HANDLE Handle, ACSC_WAITBLOCK* Wait)
5.16.1 Parameters
5.16.3 Remarks
The function deletes all persistent global variables created by the acsc_DeclareVariable
function.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.16.4 Example
5.17 acsc_CloseComm
The function closes communication via the specified communication channel.
int acsc_CloseComm(HANDLE Handle)
5.17.1 Parameters
5.17.3 Remarks
The function closes the communication channel and releases all system resources related to the
channel. If the function closes communication with the Simulator, the function also terminates
the Simulator.
Each acsc_OpenComm*** call in the application must have the corresponding
acsc_CloseComm call in order to return the resources to the system.
5.17.4 Example
if (!acsc_CloseComm(Handle))
{
printf("error closing communication: %d\n", acsc_GetLastError());
}
5.18 acsc_CloseHistoryBuffer
The function closes the history buffer and discards all stored history.
int acsc_CloseHistoryBuffer(HANDLE Handle)
5.18.1 Parameters
5.18.3 Remarks
The function closes the history buffer and releases the used memory. All information stored in
the buffer is discarded.
5.18.4 Example
if (!acsc_CloseHistoryBuffer(Handle))
{
printf("closing history buffer error: %d\n", acsc_GetLastError());
}
5.19 acsc_CloseLogFile
The function closes the log file.
5.19.1 Parameters
5.19.3 Remarks
An application must always call the acsc_CloseLogFile before it exits. Otherwise, the data
written to the file might be lost.
5.19.4 Example
if (!acsc_CloseLogFile(Handle))
{
printf("closing log file error: %d\n", acsc_GetLastError());
}
5.20 acsc_CloseMessageBuffer
The function closes the messages buffer and discards all stored unsolicited messages.
int acsc_CloseMessageBuffer(HANDLE Handle)
5.20.1 Parameters
5.20.3 Remarks
The function closes the message buffer and releases the used memory. All unsolicited messages
stored in the buffer are discarded.
5.20.4 Example
if (!acsc_CloseMessageBuffer(Handle))
{
printf("closing unsolicited messages buffer error: %d\n",
acsc_GetLastError());
}
5.21 acsc_Collect
Note
This function is equivalent to acsc_CollectB. It is mantained only for
compatibility with previous versions. For new software development
use acsc_CollectB.
5.21.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
ACSC_DCF_TEMPORAL: temporal data collection. The sampling
period is calculated automatically according to the collection time.
ACSC_DCF_CYCLIC: cyclic data collection uses the collection array
as a cyclic buffer and continues infinitely. When the array is full, each
new sample overwrites the oldest sample in the array.
Array Pointer to the null-terminated string contained the name of the array that
stores the collected samples.
The array must be declared as a global variable by an ACSPL+ program
or by the acsc_DeclareVariable function.
acsc_GetLastError.
5.21.3 Remarks
The array that stores the samples can be one or two-dimensional. One-dimensional array is
allowed only if the variable list contains one variable name.
The number of the array rows must be equal or more than the number of variables in the variable
list. The number of the array columns must be equal or more than the number of samples
specified by the NSample argument.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.21.4 Example
5.22 acsc_CollectB
The function initiates data collection.
int acsc_CollectB(HANDLE Handle, int Flags, char* Array, int NSample, int Period,
char* Vars, ACSC_WAITBLOCK* Wait)
Note
This function is an improvement of acsc_Collect. For new software
development, it is recommended to use acsc_CollectB.
5.22.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
ACSC_DCF_TEMPORAL: temporal data collection. The sampling
period is calculated automatically according to the collection time.
ACSC_DCF_CYCLIC: cyclic data collection uses the collection array
as a cyclic buffer and continues infinitely. When the array is full, each
new sample overwrites the oldest sample in the array.
Array Pointer to the null-terminated string contained the name of the array that
stores the collected samples.
The array must be declared as a global variable by an ACSPL+ program
or by the acsc_DeclareVariable function.
5.22.3 Remarks
The array that stores the samples can be one or two-dimensional. One-dimensional array is
allowed only if the variable list contains one variable name.
The number of the array rows must be equal or more than the number of variables in the variable
list. The number of the array columns must be equal or more than the number of samples
specified by the NSample argument.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.22.4 Example
5.23 acsc_Command
The function sends a command to the controller and analyzes the controller response.
int acsc_Command (HANDLE Handle, char* OutBuf, int OutCount,
ACSC_WAITBLOCK* Wait)
Note
Any ASCII command being sent to the controller must end with '\r' (13)
character, otherwise it won't be recognized as valid.
5.23.1 Parameters
5.23.3 Remarks
The function is similar to acsc_Transaction except that the controller response is not
transferred to the calling thread. The function is used mainly for the commands that the
controller responds to with a prompt. In this case, the exact characters that constitute the prompt
are irrelevant for the calling thread. The function provides analysis of the prompt, and if the
operation fails, the calling thread can obtain the error code.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.23.4 Example
5.24 acsc_CompileBuffer
The function compiles ACSPL+ program in the specified program buffer(s).
int acsc_CompileBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait)
5.24.1 Parameters
5.24.3 Remarks
The function compiles ACSPL+ program in the specified program buffer or all programs in all
buffers if the parameter Buffer is ACSC_NONE.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the program was compiled successfully.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.24.4 Example
5.25 acsc_DeclareVariable
The function creates the persistent global variable.
int acsc_DeclareVariable (HANDLE Handle, int Type, char* Name,
ACSC_WAITBLOCK* Wait)
5.25.1 Parameters
5.25.3 Remarks
The function creates the persistent global variable specified by the parameter Name of type
specified by the parameter Type. The variable can be used as any other standard or global
variable.
If it is necessary to declare one or two-dimensional array, the parameter Name should also
contains the dimensional size in brackets.
The lifetime of a persistent global variable is not connected with any program buffer. The
persistent variable survives any change in the program buffers and can be erased only by the
acsc_ClearVariables function.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.25.4 Example
5.26 acsc_Disable
The function shuts off a motor.
int acsc_Disable(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.26.1 Parameters
5.26.3 Remarks
The function shuts off a motor. After shutting off the motor cannot follow the reference and
remains at idle.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.26.4 Example
5.27 acsc_DisableAll
The function shuts off all motors.
int acsc_DisableAll(HANDLE Handle, ACSC_WAITBLOCK* Wait)
5.27.1 Parameters
5.27.3 Remarks
The function shuts off all motors. After the shutting off none of motors can follow the
corresponding, reference and all motors remain idle.
If no motors are currently enabled, the function has no effect.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.27.4 Example
5.28 acsc_DisableExt
The function shuts off a motor and defines the disable reason.
int acsc_DisableExt(HANDLE Handle, int Axis,int Reason, ACSC_WAITBLOCK*
Wait)
5.28.1 Parameters
If the function fails, the return value is zero. Get extended error information by call
acsc_GetLastError.
5.28.3 Remarks
The function shuts off a motor. After shutting off the motor cannot follow the reference and
remains at idle.
If Reason specifies one of the available motor termination codes, the state of the disabled motor
will be identical to the state of the motor disabled for the corresponding fault. This provides an
enhanced implementation of user-defined fault response.
If the second parameter specifies an arbitrary number, the motor state will be displayed as
“Kill/disable reason: <number> - customer code. This provides ability to separate different
DISABLE commands in the application.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.28.4 Example
5.29 acsc_DisableFault
The function disables the specified motor or system fault.
int acsc_DisableFault(HANDLE Handle, int Axis, int Fault, ACSC_WAITBLOCK*
Wait)
5.29.1 Parameters
5.29.3 Remarks
The function disables the examination and processing of the specified motor or system fault by
setting the specified bit of the fault mask to zero.
The motor faults are related to a specific motor, the power amplifier, and the Servo processor.
For example: Position Error, Encoder Error, and Driver Alarm.
The system faults are not related to any specific motor, for example: Emergency Stop, Memory
Fault.
For more information about the controller faults, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.29.4 Example
5.30 acsc_DisableM
The function shuts off several motors.
int acsc_DisableM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.30.1 Parameters
5.30.3 Remarks
The function shuts off several motors. After the shutting off, the motors cannot follow the
corresponding reference and remain idle.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.30.4 Example
5.31 acsc_DisableResponse
The function disables the default response to the specified motor or system fault.
int acsc_DisableResponse(HANDLE Handle, int Axis, int Response,
ACSC_WAITBLOCK* Wait)
5.31.1 Parameters
Response The response to be disabled. Only one default response can be disabled
at a time.
To specify the fault, one of the constants ACSC_SAFETY_*** can be
used. See “Safety Control Masks” on Page 387 for a detailed
description of these constants.
5.31.3 Remarks
The function disables the default response to the specified motor or system fault by setting the
specified bit of the response mask to zero.
The default response is a controller-predefined action for the corresponding fault. For more
information about the controller faults and default responses, see SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.31.4 Example
5.32 acsc_DownloadBuffer
The function is renamed to acsc_AppendBuffer. Previously written applications can use this
function as before.
5.33 acsc_Enable
The function activates a motor.
int acsc_Enable(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.33.1 Parameters
5.33.3 Remarks
The function activates a motor. After the activation, the motor begins to follow the reference
and physical motion is available.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.33.4 Example
5.34 acsc_EnableFault
The function enables the specified motor or system fault.
5.34.1 Parameters
Fault The fault to be enabled. Only one fault can be enabled at a time.
To specify the fault, one of the constants ACSC_SAFETY_*** can be
used. See “Safety Control Masks” on Page 387 for a detailed
description of these constants.
5.34.3 Remarks
The function enables the examination and processing of the specified motor or system fault by
setting the specified bit of the fault mask to one.
The motor faults are related to a specific motor, the power amplifier, and the Servo processor.
For example: Position Error, Encoder Error, and Driver Alarm.
The system faults are not related to any specific motor. For example: Emergency Stop, Memory
Fault.
For more information about the controller faults, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.34.4 Example
5.35 acsc_EnableM
The function activates several motors.
int acsc_EnableM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.35.1 Parameters
5.35.3 Remarks
The function activates several motors. After the activation, the motors begin to follow the
corresponding reference and physical motions for the specified motors are available.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.35.4 Example
5.36 acsc_EnableResponse
The function enables the response to the specified motor or system fault.
int acsc_EnableResponse(HANDLE Handle, int Axis, int Response,
ACSC_WAITBLOCK* Wait)
5.36.1 Parameters
Response The default response to be enabled. Only one default response can be
enabled at a time.
To specify the default response, one of the constants
ACSC_SAFETY_*** can be used. See “Safety Control Masks” on
Page 387 for a detailed description of these constants.
5.36.3 Remarks
The function enables the default response to the specified motor or system fault by setting the
specified bit of the response mask to one.
The default response is a controller-predefined action for the corresponding fault. For more
information about the controller faults and default responses, see SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.36.4 Example
5.37 acsc_EndSequence
The function informs the controller, that no more points will be specified for the current single-
axis motion.
int acsc_EndSequence(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.37.1 Parameters
5.37.3 Remarks
The motion finishes when the acsc_EndSequence function is executed. If the call of
acsc_EndSequence is omitted, the motion will stop at the last point of the sequence and wait
for the next point. No transition to the next motion in the motion queue will occur until the
acsc_EndSequence function executes.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
This function applies to the single-axis multi-point or spline (arbitrary path) motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.37.4 Example
5.38 acsc_EndSequenceM
The function informs the controller, that no more points or segments will be specified for the
current multi-axis motion.
int acsc_EndSequence(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.38.1 Parameters
5.38.3 Remarks
The motion finishes when the acsc_EndSequenceM function is executed. If the call of
acsc_EndSequenceM is omitted, the motion will stop at the last point or segment of the
sequence and wait for the next point. No transition to the next motion in the motion queue will
occur until the acsc_EndSequenceM function executes.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
This function applies to the multi-axis multi-point, spline (arbitrary path) and segmented
motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.38.4 Example
5.39 acsc_ExtAddPoint
The function adds a point to a single-axis multi-point or spline motion and specifies a specific
velocity or motion time.
int acsc_ExtAddPoint(HANDLE Handle, int Axis, double Point, double Rate,
ACSC_WAITBLOCK* Wait)
5.39.1 Parameters
5.39.3 Remarks
The function adds a point to a single-axis multi-point motion with specific velocity or to single-
axis spline motion with a non-uniform time.
To add a point to a multi-axis motion, use acsc_ExtAddPointM. To add a point to a motion
with default velocity or uniform time interval, the acsc_AddPoint and acsc_AddPointM
functions are more convenient.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the point is added to the
motion buffer. The point can be rejected if the motion buffer is full. In this case, you can call
this function periodically until the function returns a non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.39.4 Example
5.40 acsc_ExtAddPointM
The function adds a point to a multi-axis multi-point or spline motion and specifies a specific
velocity or motion time.
int acsc_ExtAddPointM(HANDLE Handle, int* Axes, double* Point, double Rate,
ACSC_WAITBLOCK* Wait)
5.40.1 Parameters
5.40.3 Remarks
The function adds a point to a multi-axis multi-point or spline motion. To add a point to a single-
axis motion, use acsc_ExtAddPoint. To add a point to a motion with a default velocity or a
5.40.4 Example
5.41 acsc_ExtArc1
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point, the coordinates of the final point, the direction of rotation, and the vector velocity
for the current segment.
int acsc_ExtArc1(HANDLE Handle, int* Axes, double* Center, double* FinalPoint, int
Rotation, double Velocity, ACSC_WAITBLOCK* Wait)
5.41.1 Parameters
Center Array of the center coordinates. The number and order of values must
correspond to the Axes array. The Center must specify a value for each
element of Axes except the last –1 element.
FinalPoint Array of the final point coordinates. The number and order of values
must correspond to the Axes array. The FinalPoint must specify a value
for each element of Axes except the last –1 element.
Velocity If the motion was activated by the acsc_Segment function with the
ACSC_AMF_VELOCITY flag, this parameter specifies a motion
velocity for current segment.
5.41.3 Remarks
The function adds an arc segment to the segmented motion and specifies the coordinates of the
center point, the coordinates of the final point, the direction of rotation, and the vector velocity
for the current segment. To add an arc segment with default velocity, use acsc_Arc1.
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of acsc_Segment function.
The parameter Center specifies the coordinates of the arc center. The parameter FinalPoint
specifies the coordinates of the final point. All coordinates are absolute in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.41.4 Example
Axes, // axes XY
Center, // center of the circle
Point, // final point
ACSC_CLOCKWISE, // clockwise rotation
25000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// add arc segment with center (1000, 0), final point (1000, 1000),
// clockwise rotation, vector velocity 15000
Center[0] = 1000; Center[1] = 0;
Point[0] = 1000; Point[1] = 1000;
if (!acsc_ExtArc1(Handle, // communication handle
Axes, // axes XY
Center, // center of the circle
Point, // final point
ACSC_CLOCKWISE, // clockwise rotation
15000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
5.42 acsc_ExtArc2
The function adds an arc segment to a segmented motion and specifies the coordinates of the
center point, the rotation angle, and the vector velocity for the current segment.
int acsc_ExtArc2(HANDLE Handle, int* Axes, double* Center, double Angle, double
Velocity, ACSC_WAITBLOCK* Wait)
5.42.1 Parameters
Center Array of the center coordinates. The number and order of values must
correspond to the Axes array. The Center must specify a value for each
element of Axes except the last –1 element.
Velocity If the motion was activated by the acsc_Segment function with the
ACSC_AMF_VELOCITY flag, this parameter specifies a motion
velocity for current segment.
5.42.3 Remarks
The function adds an arc segment to the segmented motion and specifies the coordinates of the
center point, the rotation angle, and the vector velocity for the current segment. To add an arc
segment with default velocity, use acsc_Arc2.
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of axes of the acsc_Segment function.
The parameter Center specifies the coordinates of the arc center. The coordinates are absolute
in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns a non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.42.4 Example
Axes, // axes XY
Center, // center of the circle
-3.141529,// semicircle
15000, // vector velocity
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);
5.43 acsc_ExtLine
The function adds a linear segment to a segmented motion and specifies a motion velocity.
int acsc_ExtLine(HANDLE Handle, int* Axes, double* Point, double Velocity,
ACSC_WAITBLOCK* Wait)
5.43.1 Parameters
Point Array of the final point coordinates. The number and order of values
must correspond to the Axes array. The Point must specify a value for
each element of Axes except the last –1 element.
Velocity If the motion was activated by the acsc_Segment function with the
ACSC_AMF_VELOCITY flag, this parameter specifies a motion
velocity for current segment.
5.43.3 Remarks
The function adds a linear segment to the segmented motion and specifies a motion velocity for
the current segment. To add a linear segment with default velocity, use acsc_Line.
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of the acsc_Segment function.
The parameter Point specifies the coordinates of the final point. The coordinates are absolute
in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In that case, you can
call this function periodically until the function returns a non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.43.4 Example
5.44 acsc_ExtToPoint
The function initiates a single-axis motion to the specified point using the specified velocity or
end velocity.
int acsc_ExtToPoint(HANDLE Handle, int Flags, int Axis, double Point, double Velocity,
double EndVelocity, ACSC_WAITBLOCK* Wait)
5.44.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don't start it until the
function acsc_Go is executed.
• ACSC_AMF_RELATIVE: the Point value is relative to the end
point of the previous motion. If the flag is not specified, the Point
specifies an absolute coordinate.
• ACSC_AMF_VELOCITY: the motion will use velocity specified by
the Velocity argument instead of the default velocity.
• ACSC_AMF_ENDVELOCITY: the motion will come to the end
point with the velocity specified by the EndVelocity argument.
EndVelocity Velocity in the target point. The argument is used only if the
ACSC_AMF_ENDVELOCITY flag is specified. Otherwise, the motion
finishes with zero velocity.
5.44.3 Remarks
The function initiates a single-axis point-to-point motion.
If the ACSC_AMF_VELOCITY flag is specified, the motion is executed using the velocity
specified by the Velocity argument. Otherwise, the required motion velocity is used. The
required motion velocity is the velocity specified by the previous call of the acsc_SetVelocity
function, or the default velocity if the function was not called.
If the ACSC_AMF_ENDVELOCITY flag is specified, the motion velocity at the final point is
specified by the EndVelocity argument. Otherwise, the motion velocity at the final point is
zero.
To execute a multi-axis point-to-point motion with the specified velocity or end velocity, use
acsc_ExtToPointM. To execute motion with default motion velocity and zero end velocity,
use acsc_ExtToPoint or acsc_ToPointM.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function does not wait for the motion end. To wait for the motion end, use
acsc_WaitMotionEnd function.
The motion builds the velocity profile using the required values of acceleration, deceleration
and jerk of the specified axis.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.44.4 Example
5.45 acsc_ExtToPointM
The function initiates a multi-axis motion to the specified point using the specified velocity or
end velocity.
int acsc_ExtToPointM(HANDLE Handle, int Flags, int* Axes, double* Point, double
Velocity, double EndVelocity, ACSC_WAITBLOCK* Wait)
5.45.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don't start it until the
function acsc_Go is executed.
• ACSC_AMF_RELATIVE: the Point values are relative to the end of
the previous motion. If the flag is not specified, the Point specifies
absolute coordinates.
• ACSC_AMF_VELOCITY: the motion will use velocity specified by
the Velocity argument instead of the default velocity.
• ACSC_AMF_ENDVELOCITY: the motion will come to the end
with the velocity specified by the EndVelocity argument.
• ACSC_AMF_MAXIMUM: not to use the motion parameters from
the leading axis but to calculate the maximum allowed motion
velocity, acceleration, deceleration and jerk of the involved axes.
Point Array of the target coordinates. The number and order of values must
correspond to the Axes array. The Point must specify a value for each
element of Axes except the last –1 element.
EndVelocity Vector velocity in the target point. The argument is used only if the
ACSC_AMF_ENDVELOCITY is specified. Otherwise, the motion
finishes with zero velocity.
5.45.3 Remarks
The function initiates a multi-axis point-to-point motion.
If the ACSC_AMF_VELOCITY flag is specified, the motion is executed using the velocity
specified by the Velocity argument. Otherwise, the required motion velocity is used. The
required motion velocity is the velocity specified by the previous call of the acsc_SetVelocity
function, or the default velocity if the function was not called.
If the ACSC_AMF_ENDVELOCITY flag is specified, the motion velocity at the final point is
specified by the EndVelocity argument. Otherwise, the motion velocity at the final point is
zero.
To execute a single-axis point-to-point motion with the specified velocity or end velocity, use
acsc_ExtToPoint. To execute a motion with default motion velocity and zero end velocity, use
acsc_ToPoint or acsc_ToPointM.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function does not wait for the motion end. To wait for the motion end, use
acsc_WaitMotionEnd function.
The motion builds the velocity profile using the required values of acceleration, deceleration
and jerk of the leading axis. The leading axis is the first axis in the Axes array.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.45.4 Example
5.46 acsc_FaultClear
The function clears the current faults and the result of the previous fault stored in the
MERR variable.
int acsc_FaultClear(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.46.1 Parameters
5.46.3 Remarks
The function clears the current faults of the specified axis and the result of the previous fault
stored in the MERR variable.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.46.4 Example
5.47 acsc_FaultClearM
The function clears the current faults and results of previous faults stored in the MERR variable
for multiple axes.
int acsc_FaultClearM(HANDLE Handle, int *Axes, ACSC_WAITBLOCK* Wait)
5.47.1 Parameters
5.47.3 Remarks
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
If the reason for the fault is still active, the controller will set the fault immediately after this
command is performed. If cleared fault is Encoder Error, the feedback position is reset to zero.
5.47.4 Example
5.48 acsc_FlushLogFile
This function allows flushing the User-Mode Driver (UMD) internal binary buffer to a
specified text file from the C Library application.
acscFlushLogFile(char*filename)
5.48.1 Parameters
5.48.3 Remarks
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
If the reason for the fault is still active, the controller will set the fault immediately after this
command is performed. If cleared fault is Encoder Error, the feedback position is reset to zero.
5.48.4 Example
{
printf("transaction error: %d\n", acsc_GetLastError());
}
5.49 acsc_GetAcceleration
The function retrieves a value of motion acceleration.
int acsc_GetAcceleration(HANDLE Handle, int Axis, double* Acceleration,
ACSC_WAITBLOCK* Wait)
5.49.1 Parameters
Acceleration Pointer to the variable that receives the value of motion acceleration.
5.49.3 Remarks
The function retrieves the value of the motion acceleration. The retrieved value is a value
defined by a previous call of the acsc_SetAcceleration function, or the default value if the
function was not called before.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Acceleration and Wait items until a call to the acsc_WaitForAsyncCall function.
5.49.4 Example
5.50 acsc_GetAnalogInput
The function retrieves the current numerical value of the specified analog inputs.
int acsc_GetAnalogInput(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK*
Wait)
5.50.1 Parameters
Value Pointer to a variable that receives the current value of the specific analog
inputs.
5.50.3 Remarks
The function retrieves the current numerical value of the specified analog inputs.
Analog inputs are represented in the controller variable AIN. For more information about
analog inputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.50.4 Example
5.51 acsc_GetAnalogOutput
The function retrieves the current numerical value of the specified analog outputs.
int acsc_GetAnalogOutput(HANDLE Handle, int Port, int* Value,
ACSC_WAITBLOCK* Wait)
5.51.1 Parameters
Value Pointer to a variable that receives the current numerical value of the
specific analog outputs.
5.51.3 Remarks
The function retrieves the current numerical value of the specified analog outputs. To write a
value to the specific analog outputs, use the acsc_SetAnalogOutput function.
Analog outputs are represented in the controller variable AOUT. For more information about
analog outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.51.4 Example
5.52 acsc_GetAxisState
The function retrieves the current axis state.
int acsc_GetAxisState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK*
Wait)
5.52.1 Parameters
State Pointer to a variable that receives the current axis state. The parameter
can include one or more of the following flags:
• ACSC_AST_LEAD – an axis is leading in a group
• ACSC_AST_DC – an axis data collection is in progress
• ACSC_AST_PEG – a PEG for the specified axis is in progress
• ACSC_AST_MOVE – an axis is moving
• ACSC_AST_ACC – an axis is accelerating
• ACSC_AST_SEGMENT – a construction of segmented motion for
the specified axis is in progress
• ACSC_AST_VELLOCK – a slave motion for the specified axis is
synchronized to master in velocity lock mode
• ACSC_AST_POSLOCK - a slave motion for the specified axis is
synchronized to master in position lock mode
5.52.3 Remarks
The function retrieves the current axis state.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the State and Wait items until a call to the acsc_WaitForAsyncCall function.
5.52.4 Example
5.53 acsc_GetCommOptions
The function retrieves the communication options.
int acsc_GetCommOptions(HANDLE Handle, unsigned int* Options)
5.53.1 Parameters
5.53.3 Remarks
The function retrieves the current communication options. To set the communication option
call acsc_SetCommOptions.
5.53.4 Example
5.54 acsc_GetConf
The function reads system configuration data.
int acsc_GetConf(HANDLE Handle, int Key, int Index, double *Value,
ACSC_WAITBLOCK* Wait)
5.54.1 Parameters
5.54.3 Remarks
The function reads system configuration data. The Key parameter specifies the feature number
and the Index parameter defines axis or buffer to which it should be applied. For detailed
description of system configuration see “SPiiPlus ACSPL+ Programmer’s Guide” GetConf
definition.
5.54.4 Example
5.55 acsc_GetDeceleration
The function retrieves a value of motion deceleration.
int acsc_GetDeceleration(HANDLE Handle, int Axis, double* Deceleration,
ACSC_WAITBLOCK* Wait)
5.55.1 Parameters
Deceleration Pointer to the variable that receives the value of motion deceleration.
5.55.3 Remarks
The function retrieves the value of the motion deceleration. The retrieved value is a value
defined by a previous call of the acsc_SetDeceleration function, or the default value if the
function was not previously called.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Deceleration and Wait items until a call to the acsc_WaitForAsyncCall function.
5.55.4 Example
5.56 acsc_GetDefaultTimeout
The function retrieves default communication timeout.
int acsc_GetDefaultTimeout(HANDLE Handle)
5.56.1 Parameters
5.56.3 Remarks
The value of the default time-out depends on the type of established communication channel.
Time-out also depends on the baud rate value for serial communication.
5.56.4 Example
5.57 acsc_GetEthernetCards
The function detects available controllers through a standard Etherneet connection. By default,
the function searches the local network segment. The default setting can be changed, as
described below.
int acsc_GetEthernetCards(in_addr*IPaddresses,int Max, int*Ncontrollers,unsigned
long BroadcastAddress)
5.57.1 Parameters
5.57.3 Remarks
Function Execution
The function executes as follows:
1. Broadcasts a message to the network
2. Collects all received replies
3. Filters out all replies sent by nodes other than the SPiiPlus controller
4. The function then stores controller's IP addresses in the IPaddresses array, assigns
Ncontrollers with the number of detected controllers and returns.
If the size of the IPaddresses array appears too small for all detected controllers (Ncontrollers
> Max), only Max addresses are stored in the array.
In order to convert the in_addr structure to a dot-delineated string, use the inet_ntoa()
Microsoft Windows function.
Broadcasting Considerations
If BroadcastAddress needs to be specified as other than ACSC_NONE, use the inet_addr
Microsoft Windows function to convert the dot-delineated string to an integer parameter.
The function uses the following broadcasting message:
"ACS-TECH80\r"
The target port for broadcasting is 700. A node that doesn't support port 700 simply does not
see the broadcasting message. If a node other than the controller supports port 700, the node
receives the message. However, since the message format is meaningful only for SPiiPlus
controllers, any other node that receives the message either ignores it or responds with an error
message that is filtered out by the function.
Normally, the user specifies ACSC_NONE in the BroadcastAddress parameter. In this case,
the function uses broadcast address 255.255.255.255. The address causes broadcasting in a
local segment of the network. If the host computer is connected to several local segments
(multi-home node), the broadcasting message is sent to all connected segments.
The user may wish to specify explicit broadcasting addresses in the following cases:
• To reduce the broadcasting area. In a multi-home node, the specific address can restrict
broadcasting to one of the connected segments.
• To extend the broadcasting area. If a wide area network (WAN) is supported, a proper
broadcasting address can broadcast to the entire WAN, or part of the WAN.
For information about how to use broadcasting addresses, refer to the network documentation.
Note
SPiiPlus controllers running with FW 4.50 or below will not be found
with a mask other than ACSC_NONE.
5.57.4 Example
in_addr IPaddresses[100];
int Ncontrollers;
char *DotStr;
char Version[100];
int N;
HANDLE h;
int I;
if (!acsc_GetEthernetCards(IPaddresses,100, &Ncontrollers,ACSC_NONE))
{
printf("Error %d\n", acsc_GetLastError());
}
for(I=0;I<Ncontrollers;I++)
{
DotStr=inet_ntoa(IPaddresses[I]);
h=acsc_OpenCommEthernet(DotStr,ACSC_SOCKET_STREAM_PORT);
if(h!=ACSC_INVALID)
{
if(acsc_GetFirmwareVersion(h,Version, 100,&N,NULL))
{
Version[N]=0;
printf("%s\n",Version);
}
acsc_CloseComm(h);
}
}
5.58 acsc_GetErrorString
The function retrieves the explanation of an error code.
int acsc_GetErrorString(HANDLE Handle, int ErrorCode, char* ErrorStr, int Count,
int* Received)
5.58.1 Parameters
ErrorStr Pointer to the buffer that receives the text explanation of ErrorCode.
5.58.3 Remarks
The function retrieves the string that contains the text explanation of the error code returned by
the acsc_GetLastError, acsc_GetMotorError, acsc_GetMotionError, and
acsc_GetProgramError functions.
The function will not copy more than Count characters to the ErrorStr buffer. If the buffer is
too small, the error explanation can be truncated.
For the SPiiPlus C Library error codes, the function returns immediately with the text
explanation. For the controller’s error codes, the function refers to the controller to get the text
explanation.
5.58.4 Example
char ErrorStr[256];
int ErrorCode, Received;
ErrorCode = acsc_GetLastError();
if (acsc_GetErrorString(Handle, // communication handle
ErrorCode, // error code
ErrorStr, // buffer for the error explanation
255, // available buffer length
&Received// number of actually received bytes
))
{
ErrorStr[Received] = ‘\0’;
printf("function returned error: %d (%s)\n", ErrorCode, ErrorStr);
}
5.59 acsc_GetExtInput
The function retrieves the current state of the specified extended input.
int acsc_GetExtInput(HANDLE Handle, int Port, int Bit, int* Value,
ACSC_WAITBLOCK* Wait)
5.59.1 Parameters
Value Pointer to a variable that receives the current state of the specific input.
The value will be populated by 0 or 1.
5.59.3 Remarks
The function retrieves the current state of the specified extended input. To get values of all
inputs of the specific extended port, use the acsc_GetExtInputPort function.
Extended inputs are represented in the controller variable EXTIN. For more information about
extended inputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.59.4 Example
5.60 acsc_GetExtInputPort
The function retrieves the current state of the specified extended input port.
int acsc_GetExtInputPort(HANDLE Handle, int Port, int* Value,
ACSC_WAITBLOCK* Wait)
5.60.1 Parameters
Value Pointer to a variable that receives the current state of the specific
input port.
5.60.3 Remarks
The function retrieves the current state of the specified extended input port. To get the value of
the specific input of the specific extended port, use the acsc_GetExtInput function.
Extended inputs are represented in the controller variable EXTIN. For more information about
extended inputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.60.4 Example
5.61 acsc_GetExtOutput
The function retrieves the current state of the specified extended output.
int acsc_GetExtOutput(HANDLE Handle, int Port, int Bit, int* Value,
ACSC_WAITBLOCK* Wait)
5.61.1 Parameters
Value Pointer to a variable that receives the current state of the specific
output. The value will be populated by 0 or 1.
5.61.3 Remarks
The function retrieves the current state of the specified extended output. To get values of all
outputs of the specific extended port, use the acsc_GetExtOutputPort function.
Extended outputs are represented in the controller variable EXTOUT. For more information
about extended outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.61.4 Example
5.62 acsc_GetExtOutputPort
The function retrieves the current state of the specified extended output port.
int acsc_GetExtOutputPort(HANDLE Handle, int Port, int* Value,
ACSC_WAITBLOCK* Wait)
5.62.1 Parameters
Value Pointer to a variable that receives the current state of the specific output.
The value will be populated by 0 or 1.
5.62.3 Remarks
The function retrieves the current state of the specified extended output port. To get the value
of the specific output of the specific extended port, use the acsc_GetExtOutputPort function.
Extended outputs are represented in the controller variable EXTOUT. For more information
about extended outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.62.4 Example
5.63 acsc_GetFault
The function retrieves the set of bits that indicate the motor or system faults.
int acsc_GetFault(HANDLE Handle, int Axis, int* Fault, ACSC_WAITBLOCK* Wait)
5.63.1 Parameters
Fault Pointer to the variable that receives the current set of fault bits.
5.63.3 Remarks
The function retrieves the set of bits that indicate motor or system faults.
Motor faults are related to a specific motor, the power amplifier, and the Servo processor. For
example: Position Error, Encoder Error, or Driver Alarm.
System faults are not related to any specific motor. For example: Emergency Stop or Memory
Fault.
The parameter Fault receives the set of bits that indicates the controller faults. To recognize the
specific fault, constants ACSC_SAFETY_*** can be used. See “Safety Control Masks” on
Page 387 for a detailed description of these constants.
For more information about the controller faults, see the SPiiPlus ACSPL+ Programmer’s
Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Fault and Wait items until a call to the acsc_WaitForAsyncCall function.
5.63.4 Example
5.64 acsc_GetFaultMask
The function retrieves the mask that defines which controller faults are examined and
processed.
int acsc_GetFaultMask(HANDLE Handle, int Axis, int* Mask, ACSC_WAITBLOCK*
Wait)
5.64.1 Parameters
5.64.3 Remarks
The function retrieves the mask, defining which controller faults are examined and processed.
If a bit of the parameter Mask is zero, the corresponding fault is disabled.
The controller faults are of two types: motor faults and system faults.
The motor faults are related to a specific motor, the power amplifier or the Servo processor. For
example: Position Error, Encoder Error or Driver Alarm.
The system faults are not related to any specific motor, for example: Emergency Stop or
Memory Fault.
For more information about the controller faults, see the SPiiPlus ACSPL+ Programmer’s
Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Mask and Wait items until a call to the acsc_WaitForAsyncCall function.
5.64.4 Example
5.65 acsc_GetFirmwareVersion
The function retrieves the firmware version of the controller.
int acsc_GetFirmwareVersion(HANDLE Handle, char* Version, int Count, int*
Received, ACSC_WAITBLOCK* Wait)
5.65.1 Parameters
5.65.3 Remarks
The function retrieves the character string that contains the firmware version of the controller.
The function will not copy more than Count characters to the Version buffer. If the buffer is
too small, the firmware version can be truncated.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Version, Received, and Wait items until a call to the acsc_WaitForAsyncCall
function.
5.65.4 Example
5.66 acsc_GetFPosition
The function retrieves an instant value of the motor feedback position.
int acsc_GetFPosition(HANDLE Handle, int Axis, double* FPosition,
ACSC_WAITBLOCK* Wait)
5.66.1 Parameters
FPosition Pointer to a variable that receives the instant value of the motor
feedback position.
5.66.3 Remarks
The function retrieves an instant value of the motor feedback position. The feedback position
is a measured position of the motor transferred to user units.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the FPosition and Wait items until a call to the acsc_WaitForAsyncCall function.
5.66.4 Example
5.67 acsc_GetFVelocity
The function retrieves an instant value of the motor feedback velocity. Unlike
acsc_GetVelocity, the function retrieves the actually measured velocity and not the required
value.
int acsc_GetFVelocity(HANDLE Handle, int Axis, double* FVelocity,
ACSC_WAITBLOCK* Wait)
5.67.1 Parameters
FVelocity Pointer to a variable that receives the instant value of the motor
feedback velocity.
5.67.3 Remarks
The function retrieves an instant value of the motor feedback velocity. The feedback velocity
is a measured velocity of the motor transferred to user units.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the FVelocity and Wait items until a call to the acsc_WaitForAsyncCall function.
5.67.4 Example
5.68 acsc_GetHistory
The function retrieves the contents of the history buffer.
int acsc_GetHistory(HANDLE Handle, char* Buf, int Count, int* Received, BOOL
bClear)
5.68.1 Parameters
5.68.3 Remarks
The function retrieves the communication history from the history buffer and stores it in the
buffer pointed by Buf.
The communication history includes all commands sent to the controller and all responses and
unsolicited messages received from the controller. The amount of received data does not exceed
the size of the history buffer. The history buffer works as a cyclic buffer: when the amount of
the stored data exceeds the buffer size, the newly stored data overwrites the earliest data in the
buffer.
Therefore, as a rule, the retrieved communication history includes only the recently sent
commands and receives responses and unsolicited messages. The depth of the retrieved history
depends on the history buffer size.
The history data is retrieved in historical order, i.e. the earliest message is stored at the
beginning of Buf. The first retrieved message in Buf can be incomplete, because of being
partially overwritten in the history buffer.
If the size of the Buf is less than the size of the history buffer, only the most recent part of the
stored history is retrieved.
5.68.4 Example
int Received;
char Buf[10000];
if (!acsc_GetHistory(Handle, // communication handle
Buf, // pointer to the buffer that receives a
// communication history
10000, // size of this buffer
&Received, // number of characters that were actually received
TRUE // clear contents of the history buffer
))
{
printf("getting history error: %d\n", acsc_GetLastError());
}
5.69 acsc_GetIndexState
The function retrieves the current set of bits that indicate the index and mark state.
int acsc_GetIndexState(HANDLE Handle, int Axis, int* State, ACSC_WAITBLOCK*
Wait)
5.69.1 Parameters
State Pointer to a variable that receives the current set of bits that indicate
the index and mark state. The parameter can include one or more of
the following flags:
• ACSC_IST_IND – a primary encoder index of the specified
axis is latched
• ACSC_IST_IND2 – a secondary encoder index of the specified
axis is latched
• ACSC_IST_MARK – a MARK1 signal has been generated and
position of the specified axis was latched
• ACSC_IST_MARK2 – a MARK2 signal has been generated
and position of the specified axis was latched
5.69.3 Remarks
The function retrieves the current set of bits that indicate the index and mark state.
The controller processes index/mark signals as follows:
When an index/mark signal is encountered for the first time, the controller latches feedback
positions and raises the corresponding bit. As long as a bit is raised, the controller does not latch
feedback position even if the signal occurs again. To resume latching logic, the application must
call the acsc_ResetIndexState function to explicitly reset the corresponding bit.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the State and Wait items until a call to the acsc_WaitForAsyncCall function.
5.69.4 Example
5.70 acsc_GetInput
The function retrieves the current state of the specified digital input.
int acsc_GetInput(HANDLE Handle, int Port, int Bit, int* Value, ACSC_WAITBLOCK*
Wait)
5.70.1 Parameters
Value Pointer to a variable that receives the current state of the specific input.
The value will be populated by 0 or 1.
5.70.3 Remarks
The function retrieves the current state of the specified digital input. To get values of all inputs
of the specific port, use the acsc_GetInputPort function.
Digital inputs are represented in the controller variable IN. For more information about digital
inputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.70.4 Example
5.71 acsc_GetInputPort
The function retrieves the current state of the specified digital input port.
int acsc_GetInputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK*
Wait)
5.71.1 Parameters
Value Pointer to a variable that receives the current state of the specific input
port.
5.71.3 Remarks
The function retrieves the current state of the specified digital input port. To get the value of the
specific input of the specific port, use the acsc_GetInput function.
Digital inputs are represented in the controller variable IN. For more information about digital
inputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.71.4 Example
5.72 acsc_GetInterruptMask
The function retrieves the mask for specified interrupt.
int acsc_GetInterruptMask(HANDLE Handle, int Interrupt, int* Mask)
5.72.1 Parameters
acsc_GetLastError.
5.72.3 Remarks
The function retrieves the bit mask for specified interrupt. To set the mask for specified
interrupt, call .
5.72.4 Example
// the example shows how to get the mask for specific interrupt
int Mask;
if (!acsc_GetInterruptMask( Handle, // communication handle
ACSC_INTR_PHYSICAL_MOTION_END, // specified interrupt
&Mask // received value
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
5.73 acsc_GetJerk
The function retrieves a value of motion jerk.
int acsc_GetJerk(HANDLE Handle, int Axis, double* Jerk, ACSC_WAITBLOCK*
Wait)
5.73.1 Parameters
Jerk Pointer to the variable that receives the value of motion jerk.
5.73.3 Remarks
The function retrieves the value of the motion jerk. The retrieved value is a value defined by a
previous call of the acsc_SetJerk function, or the default value if the function was not called
before.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Jerk and Wait items until a call to the acsc_WaitForAsyncCall function.
5.73.4 Example
5.74 acsc_GetKillDeceleration
The function retrieves a value of motion kill deceleration.
int acsc_GetKillDeceleration(HANDLE Handle, int Axis, double* KillDeceleration,
ACSC_WAITBLOCK* Wait)
5.74.1 Parameters
KillDeceleration Pointer to the variable that receives the value of motion kill
deceleration.
5.74.3 Remarks
The function retrieves the value of the motion kill deceleration. The retrieved value is a value
defined by a previous call of the acsc_SetKillDeceleration function, or the default value if the
function was not called before.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the KillDeceleration and Wait items until a call to the acsc_WaitForAsyncCall
function.
5.74.4 Example
5.75 acsc_GetLastError
The function returns the calling thread’s last-error code value. The last-error code is maintained
on a per-thread basis. Multiple threads do not overwrite each other’s last-error code.
int acsc_GetLastError()
5.75.1 Parameters
This function has no parameters.
5.75.3 Remarks
It is necessary to call acsc_GetLastError immediately when some functions return zero value.
That is because all of the functions rewrite the error code value when they are called.
For a complete List of Error Codes, “List of Error Codes” on Page 375.
5.75.4 Example
5.76 acsc_GetLibraryVersion
The function retrieves the SPiiPlus C Library version number.
unsigned int acsc_GetLibraryVersion()
5.76.1 Parameters
This function has no parameters.
5.76.3 Remarks
The SPiiPlus C Library version consists of four (or less) numbers separated by points: #.#.#.#.
The binary version number is represented by 32-bit unsigned integer value. Each byte of this
value specifies one number in the following order: high byte of high word – first number, low
byte of high word – second number, high byte of low word – third number and low byte of low
word – forth number. For example version “2.10” has the following binary representation
(hexadecimal format): 0x020A0000.
First two numbers in the string form are obligatory. Any release version of the library consists
of two numbers. The third and fourth numbers specify an alpha or beta version, special or
private build, etc.
5.76.4 Example
5.77 acsc_GetMessage
The function retrieves unsolicited messages from the buffer. This function only works if you
5.77.1 Parameters
bClear If TRUE, the function clears the contents of the unsolicited messages
buffer after retrieving the message.
If FALSE, the unsolicited messages buffer is not cleared.
5.77.3 Remarks
The function retrieves all stored unsolicited messages from the message buffer.
The function always returns immediately. If no, unsolicited message is received, the function
assigns zero to the Received variable.
Parameter Count specifies the buffer size. If a received message contains more than Count
characters, the function transfers to buffer only Count characters, assigns Received with
Count value and returns non-zero. The remaining characters of the message are removed from
the message buffer.
If the Count is equal to or more than the length of the message, the function transfers the whole
message to buffer and assigns variable Received with a number of characters that were actually
transferred.
5.77.4 Example
nt Received;
char Buf[10000];
if (!acsc_GetMessage( Handle, // communication handle
Buf, // pointer to the buffer that
// receives unsolicited messages
10000, // size of this buffer
&Received, // number of characters that were
// actually received
TRUE // clear contents of the
// unsolicited messages buffer
))
{
printf("getting unsolicited message error: %d\n",
acsc_GetLastError());
}
5.78 acsc_GetMotionError
Note
This function is obsolete and will be deprecated in a future version of
the C Library. The function is supported for backward compatibility. In
all cases, use acsc_GetMotorError instead.
The function retrieves the termination code of the last executed motion of the specified axis.
int acsc_GetMotionError(HANDLE Handle, int Axis, int* Error,
ACSC_WAITBLOCK* Wait)
5.78.1 Parameters
Error Pointer to a variable that receives the termination code of the last
executed motion.
5.78.3 Remarks
The function retrieves the termination code of the last executed motion of the specified axis.
If the motion is in progress, the parameter Error is zero. If the motion terminates for any
reason, the parameter Error contains the termination code. To get the error explanation, use the
function acsc_GetErrorString.
See the SPiiPlus ACSPL+ Programmer’s Guide for all available motion termination codes
description.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function.
5.78.4 Example
5.79 acsc_GetMotorError
The function retrieves the reason for motor disabling.
int acsc_GetMotorError(HANDLE Handle, int Axis, int* Error, ACSC_WAITBLOCK*
Wait)
5.79.1 Parameters
Error Pointer to a variable that receives the reason why the motor was
disabled.
5.79.3 Remarks
The function retrieves the reason for motor disabling.
If the motor is enabled the parameter, Error is zero. If the motor was disabled, the parameter
Error contains the reason for motor disabling. To get the error explanation, use the
acsc_GetErrorString function.
See “SPiiPlus ACSPL+ Programmer’s Guide” for all available motor error code descriptions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function.
5.79.4 Example
{
printf("transaction error: %d\n", acsc_GetLastError());
}
5.80 acsc_GetMotorState
The function retrieves the current motor state.
5.80.1 Parameters
State Pointer to a variable that receives the current motor state. The parameter
can include one or more of the following flags:
• ACSC_MST_ENABLE — a motor is enabled
• ACSC_MST_INPOS — a motor has reached a target position
• ACSC_MST_MOVE — a motor is moving
• ACSC_MST_ACC — a motor is accelerating
5.80.3 Remarks
The function retrieves the current motor state.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the State and Wait items until a call to the acsc_WaitForAsyncCall function.
5.80.4 Example
5.81 acsc_GetOutput
The function retrieves the current state of the specified digital output.
int acsc_GetOutput(HANDLE Handle, int Port, int Bit, int* Value,
ACSC_WAITBLOCK* Wait)
5.81.1 Parameters
Value Pointer to a variable that receives the current state of the specific output.
The value will be populated by 0 or 1.
5.81.3 Remarks
The function retrieves the current state of the specified digital output. To get values of all
outputs of the specific port, use the acsc_GetOutputPort function.
Digital outputs are represented in the controller variable OUT. For more information about
digital outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.81.4 Example
5.82 acsc_GetOutputPort
The function retrieves the current state of the specified digital output port.
int acsc_GetOutputPort(HANDLE Handle, int Port, int* Value, ACSC_WAITBLOCK*
Wait)
5.82.1 Parameters
Value Pointer to a variable that receives the current state of the specific output.
The value will be populated by 0 or 1.
5.82.3 Remarks
The function retrieves the current state of the specified digital output port. To get the value of
the specific output of the specific port, use the acsc_GetOutput function.
Digital outputs are represented in the controller variable OUT. For more information about
digital outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
5.82.4 Example
5.83 acsc_GetPCICards
The function retrieves information about the controller cards inserted in the computer PCI Bus.
int acsc_GetPCICards(ACSC_PCI_SLOT* Cards, int Count, int* ObtainedCards)
5.83.1 Parameters
5.83.3 Remarks
The function scans the PCI Bus for the inserted controller cards and fills the Cards array with
5.83.4 Example
ACSC_PCI_SLOT CardsList[16];
int DetectedCardsCount;
if (acsc_GetPCICards( CardsList, // pointer to the declared
// array
// to save the detected
// cards information
16, // size of this array
&DetectedCardsCount // number of cards that were
// actually detected
))
{
printf("Found %d SB1218PCI cards\n", DetectedCardsCount);
}
else
{
printf("error while scanning PCI bus: %d\n", acsc_GetLastError());
}
5.84 acsc_GetProgramError
The function retrieves the error code of the last program error encountered in the specified
buffer.
int acsc_GetProgramError(HANDLE Handle, int Buffer, int* Error,
ACSC_WAITBLOCK* Wait)
5.84.1 Parameters
5.84.3 Remarks
The function retrieves the error code of the last program error encountered in the specified
buffer.
If the program is running, the parameter Error is zero. If the program terminates for any reason,
the parameter Error contains the termination code. To get the error explanation, use the
function acsc_GetErrorString.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Error and Wait items until a call to the acsc_WaitForAsyncCall function.
5.84.4 Example
}
}
}
else
{
printf("transaction error: %d\n", acsc_GetLastError());
}
5.85 acsc_GetProgramState
The function retrieves the current state of the program buffer.
int acsc_GetProgramState(HANDLE Handle, int Buffer, int* State,
ACSC_WAITBLOCK* Wait)
5.85.1 Parameters
State Pointer to a variable that receives the current state of the program
buffer. The parameter can include one or more of the following flags:
• ACSC_PST_COMPILED – a program in the specified buffer is
compiled
• ACSC_PST_RUN – a program in the specified buffer is running
• ACSC_PST_AUTO – an auto routine in the specified buffer is
running
• ACSC_PST_DEBUG – a program in the specified buffer is
executed in debug mode, i.e. breakpoints are active
• ACSC_PST_SUSPEND – a program in the specified buffer is
suspended after the step execution or due to breakpoint in debug
mode
5.85.3 Remarks
The function retrieves the current state of the program buffer.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the State and Wait items until a call to the acsc_WaitForAsyncCall function.
5.85.4 Example
5.86 acsc_GetQueueOverflowTimeout
The function retrieves the Queue Overflow Timeout.
int acsc_GetQueueOverflowTimeout(HANDLE Handle)
5.86.1 Parameters
5.86.3 Remarks
See explanation about Queue Overflow Timeout in “Non-waiting Calls” on Page 12.
5.86.4 Example
5.87 acsc_GetResponseMask
The function retrieves the mask that defines the motor or the system faults for which the
controller provides the default response.
int acsc_GetResponseMask(HANDLE Handle, int Axis, int* Mask,
ACSC_WAITBLOCK* Wait)
5.87.1 Parameters
5.87.3 Remarks
The function retrieves the mask that defines the motor or the system faults for which the
controller provides the default response. If a bit of the parameter Mask is zero, the controller
does not provide a default response to the corresponding fault.
The default response is a controller-predefined action for the corresponding fault. For more
information about the controller faults and default, responses see the SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Mask and Wait items until a call to the acsc_WaitForAsyncCall function.
5.87.4 Example
5.88 acsc_GetRPosition
The function retrieves an instant value of the motor reference position.
int acsc_GetRPosition(HANDLE Handle, int Axis, double* RPosition,
ACSC_WAITBLOCK* Wait)
5.88.1 Parameters
Rposition Pointer to a variable that receives the instant value of the motor
reference position.
5.88.3 Remarks
The function retrieves an instant value of the motor reference position. The reference position
is a value calculated by the controller as a reference for the motor.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the RPosition and Wait items until a call to the acsc_WaitForAsyncCall function.
5.88.4 Example
5.89 acsc_GetRVelocity
The function retrieves an instant value of the motor reference velocity.
int acsc_GetRVelocity(HANDLE Handle, int Axis, double* RVelocity,
ACSC_WAITBLOCK* Wait)
5.89.1 Parameters
RVelocity Pointer to a variable that receives the instant value of the motor
reference velocity.
5.89.3 Remarks
The function retrieves an instant value of the motor reference velocity. The reference velocity
is a value calculated by the controller in the process of motion generation.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the RVelocity and Wait items until a call to the acsc_WaitForAsyncCall function.
5.89.4 Example
5.90 acsc_GetSafetyInput
The function retrieves the current state of the specified safety input.
int acsc_GetSafetyInput(HANDLE Handle, int Axis, int Input, int* Value,
ACSC_WAITBLOCK* Wait)
5.90.1 Parameters
Value Pointer to a variable that receives the current state of the specified
inputs. The value will be populated by 0 or 1. The value will receive 1
if any of the specified safety inputs in the Input field is on. Otherwise, it
receives 0.
5.90.3 Remarks
The function retrieves the current state of the specified safety input. To get values of all safety
inputs of the specific axis, use the acsc_GetSafetyInput function.
Safety inputs are represented in the controller variables SAFIN and S_SAFIN. For more
information about safety inputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
Note
Some safety inputs can be unavailable in specific controller model. For
example, SPiiPlus SA controller does not provide Motor Overheat,
Preliminary Left Limit, or Preliminary Right Limit safety inputs.
See specific model documentation for details.
5.90.4 Example
5.91 acsc_GetSafetyInputPort
The function retrieves the current state of the specified safety input port.
int acsc_GetSafetyInputPort(HANDLE Handle, int Axis, int* Value,
ACSC_WAITBLOCK* Wait)
5.91.1 Parameters
Value Pointer to a variable that receives the current state of the specific safety
input port.
To recognize a specific motor safety input, only one of the following
constants can be used:
• ΑCSC_SAFETY_RL
• ACSC_SAFETY_LL
• ACSC_SAFETY_RL2
• ACSC_SAFETY_LL2
• ACSC_SAFETY_HOT
• ACSC_SAFETY_DRIVE
To recognize a specific system safety input, only ACSC_SAFETY_ES
constant can be used.
See “Safety Control Masks” on Page 387 for a detailed description of
these constants.
5.91.3 Remarks
The function retrieves the current state of the specified safety input port. To get the state of the
Note
Some safety inputs can be unavailable in a specific controller model.
For example, SPiiPlus SA controller does not provide Motor Overheat,
Preliminary Left Limit, and Preliminary Right Limit safety inputs.
See specific model documentation for details.
5.91.4 Example
5.92 acsc_GetSafetyInputPortInv
The function retrieves the set of bits that define inversion for the specified safety input port.
int acsc_GetSafetyInputPortInv(HANDLE Handle, int Axis, int* Value,
ACSC_WAITBLOCK* Wait)
5.92.1 Parameters
Value Pointer to a variable that receives the set of bits that define inversion for
the specific safety input port.
To recognize a specific bit, use the following constants:
• ACSC_SAFETY_RL
• ACSC_SAFETY_LL
• ACSC_SAFETY_RL2
• ACSC_SAFETY_LL2
• ACSC_SAFETY_HOT
• ACSC_SAFETY_DRIVE
Use the ACSC_SAFETY_ES constant to recognize an inversion for the
specific system safety input port,.
See “Safety Control Masks” on Page 387 for a detailed description of
these constants.
5.92.3 Remarks
The function retrieves the set of bits that define inversion for the specified safety input port. To
set the specific inversion for the specific safety input port, use the
acsc_GetSafetyInputPortInv function.
If a bit of the retrieved set is zero, the corresponding signal is not inverted and therefore high
voltage is considered an active state. If a bit is raised, the signal is inverted and low voltage is
considered an active state.
The inversions of safety inputs are represented in the controller variables SAFINI and
S_SAFINI. For more information about safety inputs, see the SPiiPlus ACSPL+ Programmer’s
Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Value and Wait items until a call to the acsc_WaitForAsyncCall function.
Note
Some safety inputs can be unavailable in a specific controller model.
For example, SPiiPlus SA controller does not provide Motor Overheat,
Preliminary Left Limit, and Preliminary Right Limit safety inputs.
See specific model documentation for details.
5.92.4 Example
5.93 acsc_GetSerialNumber
The function retrieves the controller serial number.
int acsc_GetSerialNumber(HANDLE Handle, char* SerialNumber, int Count, int*
Received, ACSC_WAITBLOCK* Wait)
5.93.1 Parameters
5.93.3 Remarks
The function retrieves the character string that contains the controller serial number. The
function will not copy more than Count characters to the SerialNumber buffer. If the buffer is
too small, the serial number can be truncated.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the SerialNumber, Received and Wait items until a call to the
acsc_WaitForAsyncCall function.
5.93.4 Example
{
SerialNumber[Received] = ‘\0’;
printf("Controller serial number: %s\n", SerialNumber);
}
5.94 acsc_GetSingleMessage
The function retrieves single unsolicited message from the buffer. This function only works if
you setup a buffer using acsc_OpenMessageBuffer. If there is no message in the buffer the
function waits till the message arrives or time out expires.
int acsc_GetSingleMessage (HANDLE Handle, char *Message,int *Length,int Timeout)
5.94.1 Parameters
5.94.3 Remarks
The function retrieves a single unsolicited message from the message buffer.
If no unsolicited message is received, the function waits until a message arrives.
If message arrives, Length will contain the received message length. If the timeout expires, the
function exits with the ACSC_TIMEOUT error.
5.94.4 Example
int Length;
char Buf[10000];
if (!acsc_GetMessage(Handle, // communication handle
Buf, // pointer to the buffer that
// receives unsolicited messages
&L, // number of characters that were actually received
1000 // Wait for 1 second till a message arrives
))
{
printf("getting unsolicited message error: %d\n",
acsc_GetLastError());
}
5.95 acsc_GetTargetPosition
The function retrieves the instant value of track position.
int acsc_GetTargetPosition(HANDLE Handle, int Axis, double *TargetPosition,
ACSC_WAITBLOCK* Wait)
5.95.1 Parameters
TargetPosition The pointer to variable that receives the instant value of the target
position.
5.95.3 Remarks
The function reads a current value of the corresponding TPOS variable. If the corresponding
axis is initialized with track motion, TPOS controls the motion of the axis.
For more information see the explanation of the track command in the SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.95.4 Example
5.96 acsc_GetTimeout
The function retrieves communication timeout.
int acsc_GetTimeout(HANDLE Handle)
5.96.1 Parameters
5.96.3 Example
5.97 acsc_GetVelocity
The function retrieves a value of motion velocity.
int acsc_GetVelocity(HANDLE Handle, int Axis, double* Velocity,
ACSC_WAITBLOCK* Wait)
5.97.1 Parameters
Velocity Pointer to the variable that receives the value of motion velocity.
5.97.3 Remarks
The function retrieves the value of the motion velocity. The retrieved value is a value defined
by a previous call of the acsc_SetVelocity function, or the default value if the function was not
called before.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Velocity and Wait items until a call to the acsc_WaitForAsyncCall function.
5.97.4 Example
5.98 acsc_Go
The function starts up a motion waiting in the specified motion queue.
int acsc_Go(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.98.1 Parameters
5.98.3 Remarks
A motion that was planned with ACSC_AMF_WAIT flag does not start until the acsc_Go
function is executed. Being planned, a motion waits in the appropriate motion queue.
Each axis has a separate motion queue. A single-axis motion waits in the motion queue of the
corresponding axis. A multi-axis motion waits in the motion queue of the leading axis. The
leading axis is an axis specified first in the motion command.
The acsc_Go function initiates the motion waiting in the motion queue of the specified axis. If
no motion waits in the motion queue, the function has no effect.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.98.4 Example
5.99 acsc_GoM
The function synchronously starts up several motions that are waiting in the specified motion
queues.
int acsc_GoM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.99.1 Parameters
5.99.3 Remarks
A motion that was planned with ACSC_AMF_WAIT flag does not start until the acsc_GoM
function is executed. After being planned, a motion waits in the appropriate motion queue.
Each axis has a separate motion queue. A single-axis motion waits in the motion queue of the
corresponding axis. A multi-axis motion waits in the motion queue of the leading axis. The
leading axis is an axis specified first in the motion command.
The acsc_GoM function initiates the motions waiting in the motion queues of the specified
axes. If no motion waits in one or more motion queues, the corresponding axes are not affected.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.99.4 Example
5.100 acsc_Group
The function creates a coordinate system for a multi-axis motion.
int acsc_Group(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.100.1 Parameters
5.100.3 Remarks
The function creates a coordinate system for a multi-axis motion. The first element of the Axes
array specifies the leading axis. The motion parameters of the leading axis become the default
motion parameters for the group.
An axis can belong to only one group at a time. If the application requires restructuring the axes,
it must split the existing group and only then create the new one. To split the existing group,
use acsc_Split function. To split all existing groups, use the acsc_SplitAll function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.100.4 Example
5.101 acsc_Halt
The function terminates a motion using the full deceleration profile.
int acsc_Halt(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.101.1 Parameters
5.101.3 Remarks
The function terminates the executed motion that involves the specified axis. The terminated
motion can be either single-axis or multi-axis. Any other motion waiting in the corresponding
motion queue is discarded and will not be executed.
If no executed motion involves the specified axis, the function has no effect.
The terminated motion finishes using the full third-order deceleration profile and the motion
deceleration value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.101.4 Example
5.102 acsc_HaltM
The function terminates several motions using the full deceleration profile.
int acsc_HaltM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.102.1 Parameters
5.102.3 Remarks
The function terminates all executed motions that involve the specified axes. The terminated
motions can be either single-axis or multi-axis. All other motions waiting in the corresponding
motion queues are discarded and will not be executed.
If no executed motion involves a specified axis, the function has no effect on the corresponding
axis.
The terminated motions finish using the full third-order deceleration profile and the motion
deceleration values.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.102.4 Example
5.103 acsc_Jog
The function initiates a single-axis jog motion.
int acsc_Jog(HANDLE Handle, int Flags, int Axis, double Velocity,
ACSC_WAITBLOCK* Wait)
5.103.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_Go is executed.
• ACSC_AMF_VELOCITY: the motion will use the velocity
specified by the Velocity argument instead of the default velocity.
5.103.3 Remarks
The function initiates a single-axis jog. To execute multi-axis jog, use acsc_JogM.
The jog motion is a motion with constant velocity and no defined ending point. The jog motion
continues until the next motion is planned, or the motion is killed for any reason.
The motion builds the velocity profile using the default values of acceleration, deceleration and
jerk of the specified axis. If the ACSC_AMF_VELOCITY flag is not specified, the default
value of velocity is used as well. In this case, only the sign of Velocity is used in order to specify
the direction of motion. The positive velocity defines a positive direction, the negative velocity
– negative direction.
If the ACSC_AMF_VELOCITY flag is specified, the value of Velocity is used instead of the
default velocity. The sign of Velocity defines the direction of the motion.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. No waiting for the motion end is provided.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.103.4 Example
5.104 acsc_JogM
The function initiates a multi-axis jog motion.
int acsc_JogM(HANDLE Handle, int Flags, int* Axes, int* Direction, double Velocity,
ACSC_WAITBLOCK* Wait)
5.104.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_Go is executed.
• ACSC_AMF_VELOCITY: the motion will use the velocity
specified by the Velocity argument instead of the default velocity.
If the function fails, the return value is zero. Get extended error information by call
acsc_GetLastError.
5.104.3 Remarks
The function initiates a multi-axis jog motion. To execute single-axis jog motion, use acsc_Jog.
The jog motion is a motion with constant velocity and no defined ending point. The jog motion
continues until the next motion is planned, or the motion is killed for any reason.
The motion builds the vector velocity profile using the default values of velocity, acceleration,
deceleration and jerk of the axis group. If the ACSC_AMF_VELOCITY flag is not specified,
the default value of velocity is used as well. If the ACSC_AMF_VELOCITY flag is specified,
the value of Velocity is used instead of the default velocity.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function cannot wait or validate the end of the motion. To wait for the motion
end, use the acsc_WaitMotionEnd function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.104.4 Example
5.105 acsc_Kill
The function terminates a motion using reduced deceleration profile.
int acsc_Kill(HANDLE Handle, int Axis, ACSC_WAITBLOCK* Wait)
5.105.1 Parameters
5.105.3 Remarks
The function terminates the executed motion that involves the specified axis. The terminated
motion can be either single-axis or multi-axis. Any other motion waiting in the corresponding
motion queue is discarded and will not be executed.
If no executed motion involves the specified axis, the function has no effect.
The terminated motion finishes with the reduced second-order deceleration profile and the kill
deceleration value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.105.4 Example
5.106 acsc_KillAll
The function terminates all currently executed motions.
int acsc_KillAll(HANDLE Handle, ACSC_WAITBLOCK* Wait)
5.106.1 Parameters
5.106.3 Remarks
The function terminates all currently executed motions. Any other motion waiting in any
motion queue is discarded and will not be executed.
If no motion is currently executed, the function has no effect.
The terminated motions finish with the reduced second-order deceleration profile and the kill
deceleration values.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.106.4 Example
5.107 acsc_KillExt
The function terminates a motion using reduced deceleration profile and defines the kill reason.
int acsc_KillExt(HANDLE Handle, int Axis, int Reason,ACSC_WAITBLOCK* Wait)
5.107.1 Parameters
Reason Integer number that defines the reason of kill. The specified value
is stored in the MERR variable in the controller and so modifies
the state of the killed motor.
5.107.3 Remarks
The function terminates the executed motion that involves the specified axis. The terminated
motion can be either single-axis or multi-axis. Any other motion waiting in the corresponding
motion queue is discarded and will not be executed.
If no executed motion involves the specified axis, the function has no effect.
The terminated motion finishes with the reduced second-order deceleration profile and the kill
deceleration value.
If Reason specifies one of the available motor termination codes, the state of the killed motor
will be identical to the state of the motor killed for the corresponding fault. This provides an
enhanced implementation of user-defined fault response.
If the second parameter specifies an arbitrary number, the motor state will be displayed as
“Kill/disable reason: <number> - customer code. This provides ability to separate different
KILL commands in the application.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the KillDeceleration and Wait items until a call to the acsc_WaitForAsyncCall
function.
5.107.4 Example
5.108 acsc_KillM
The function terminates several motions using reduced deceleration profile.
int acsc_KillM(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.108.1 Parameters
5.108.3 Remarks
The function terminates all executed motions that involve the specified axes. The terminated
motions can be either single-axis or multi-axis. All other motions waiting in the corresponding
motion queues are discarded and will not be executed.
If no executed motion involves a specified axis, the function has no effect on the corresponding
axis.
The terminated motions finish with the reduced second-order deceleration profile and the kill
deceleration values.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.108.4 Example
5.109 acsc_Line
The function adds a linear segment to a segmented motion.
int acsc_Line(HANDLE Handle, int* Axes, double* Point, ACSC_WAITBLOCK* Wait)
5.109.1 Parameters
Point Array of the final point coordinates. The number and order of values
must correspond to the Axes array. The Point must specify a value for
each element of Axes except the last –1 element.
5.109.3 Remarks
The function adds a linear segment to the segmented motion. To add a linear segment with a
specified non-default velocity, use acsc_ExtLine.
All axes specified in the Axes array must be specified before the call of the acsc_Segment
function. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of acsc_Segment function.
The parameter Point specifies the coordinates of the final point. The coordinates are absolute
in the plane.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the segment is added to
the motion buffer. The segment can be rejected if the motion buffer is full. In this case, you can
call this function periodically until the function returns non-zero value.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.109.4 Example
5.110 acsc_LoadBuffer
The function clears the specified program buffer and then loads ACSPL+ program to this
buffer.
int acsc_LoadBuffer(HANDLE Handle, int Buffer, char* Program, int Count,
ACSC_WAITBLOCK* Wait)
5.110.1 Parameters
5.110.3 Remarks
The function clears the specified program buffer and then loads ACSPL+ program to this
buffer.
No compilation or syntax check is provided during downloading. Any text, not only a correct
program, can be inserted into a buffer. In order to compile the program and check its accuracy,
the compile command must be executed after downloading.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.110.4 Example
5.111 acsc_LoadBufferIgnoreServiceLines
The function clears the specified program buffer and then loads ACSPL+ to this buffer.
All lines that start with # are ignored.
int acsc_LoadBufferIgnoreServiceLines(HANDLE Handle, int Buffer, char* Program,
int Count, ACSC_WAITBLOCK* Wait)
Note
This function is obsolete and is maintained only for backwards
compatablitiy. When loading files saved from the MultiDebugger and
MMI use the acsc_LoadBuffersFromFile function.
5.111.1 Parameters
5.111.3 Remarks
The function clears the specified program buffer and then loads ACSPL+ program to this
buffer.
No compilation or syntax check is provided during downloading. Any text, not only a correct
program, can be inserted into a buffer. In order to compile the program and check its accuracy,
the compile command must be executed after downloading.
Note
You can use this function in order to load program from file created by
SPiiPlus MMI or SPiiPlus MD only if it contains a program from one
buffer only. Otherwise, programs from several buffers will stick
together, because the separators are ignored.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.111.4 Example
5.112 acsc_LoadBuffersFromFile
The function opens a file that contains one or more ACSPL+ programs allocated to several
buffers and download the programs to the corresponding buffers.
int acsc_LoadBuffersFromFile(HANDLE Handle, char *Filename,
ACSC_WAITBLOCK* Wait)
5.112.1 Parameters
5.112.3 Remarks
The function analyzes the file, determines which program buffers should be loaded, clears them
and then loads ACSPL+ programs to those buffers.
SPiiPlus software tools save ACSPL+ programs in the following format:
# Header: Date, Firmware version etc.
#Buf1 (buffer number)
ACSPL+ program of Buf1
#Buf2 (buffer number)
ACSPL+ program of Buf2
#Buf3 (buffer number)
ACSPL+ program of Buf3 etc.
The number of buffers in a file may change from 1 to 10, without any default order.
No compilation or syntax check is provided during downloading. Any text, not only a correct
program, can be inserted into a buffer. In order to compile the program and check its accuracy,
the compile command must be executed after downloading.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.112.4 Example
5.113 acsc_LoadFileToIntegerVariable
This function writes value(s) from text file to integer variable.
int acsc_LoadFileToIntegerVariable(HANDLE Handle, int NBuf, char* Var, int From1,
int To1, int From2, int To2, char* Filename,ACSC_WAITBLOCK* Wait)
5.113.1 Parameters
5.113.3 Remarks
The function writes to a specified integer variable or array.
The variable can be a standard controller variable, user global or user local.
Standard and user global variables have global scope. Therefore, parameter Nbuf must be
ACSC_NONE (-1) for these classes of variables.
User local variable exists only within a buffer. The buffer number must be specified for user
local variable.
If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE (-1). The
function writes the value pointed by Values to the specified variable.
If the variable is a one-dimensional array, From1, To1 must specify the index range and
From2, To2 must be ACSC_NONE (-1). Array Values must contain To1-From1+1 values at
least. The function writes the values to the specified variable from index From1 to index To1
inclusively.
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. The text file,
pointed by Filename parameter, must contain (To1-From1+1)x(To2-From2+1) values at least,
otherwise error will occur. The function uses the text file as follows: first, the function retrieves
the To2-From2 values and writes them to row From1 of the specified controller variable, then
retrieves next To2-From2 values and writes them to row From1+1 of the specified controller
variable, etc.
The text file is processed line-by-line; any characters except numbers, dots, commas and
exponent ‘e’ are translated as separators between the numbers. Line that starts with no digits is
5.113.4 Example
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 ……………
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 ……………
…
…
5.114 acsc_LoadFileToRealVariable
The function writes value(s) from text file to real variable.
int acsc_LoadFileToRealVariable(HANDLE Handle, int NBuf, char* Var, int From1, int
To1, int From2, int To2, char* Filename,ACSC_WAITBLOCK* Wait)
5.114.1 Parameters
5.114.3 Remarks
The function writes to a specified integer variable or array.
The variable can be a standard controller variable, user global or user local.
Standard and user global variables have global scope. Therefore, parameter Nbuf must be
ACSC_NONE (-1) for these classes of variables.
User local variable exists only within a buffer. The buffer number must be specified for user
local variable.
If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE (-1). The
function writes the value pointed by Values to the specified variable.
If the variable is a one-dimensional array, From1, To1 must specify the index range and
From2, To2 must be ACSC_NONE (-1). Array Values must contain To1-From1+1 values at
least. The function writes the values to the specified variable from index From1 to index To1
inclusively.
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. The text file,
pointed by Filename parameter, must contain (To1-From1+1)x(To2-From2+1) values at least,
otherwise error will occur. The function uses the text file as follows: first, the function retrieves
the To2-From2 values and writes them to row From1 of the specified controller variable, then
retrieves next To2-From2 values and writes them to row From1+1 of the specified controller
variable, etc.
The text file is processed line-by-line; any characters except numbers, dots, commas and
exponent ‘e’ are translated as separators between the numbers. Line that starts with no digits is
considered as comment and ignored.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.114.4 Example
5.115 acsc_MultiPoint
The function initiates a single-axis multi-point motion.
int acsc_MultiPoint(HANDLE Handle, int Flags, int Axis, double Dwell,
ACSC_WAITBLOCK* Wait)
5.115.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_Go is executed.
• ACSC_AMF_RELATIVE: the coordinates of each point are
relative. The first point is relative to the instant position when the
motion starts; the second point is relative to the first, etc. If the flag
is not specified, the coordinates of each point are absolute.
• ACSC_AMF_VELOCITY: the motion uses the velocity specified
with each point instead of the default velocity.
• ACSC_AMF_CYCLIC: the motion uses the point sequence as a
cyclic array. After positioning to the last point it does positioning to
the first point and continues.
5.115.3 Remarks
The function initiates a single-axis multi-point motion. To execute multi-axis multi-point
motion, use acsc_MultiPointM.
The motion executes sequential positioning to each of the specified points, optionally with
dwell in each point.
The function itself does not specify any point, so that the created motion starts only after the
first point is specified. The points of motion are specified by using the acsc_AddPoint or
acsc_ExtAddPoint functions that follow this function.
The motion finishes when the acsc_EndSequence function is executed. If the call of
acsc_EndSequence is omitted, the motion will stop at the last point of the sequence and wait
for the next point. No transition to the next motion in the motion queue will occur until the
function acsc_EndSequence executes.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function cannot wait or validate the end of the motion. To wait for the motion
end, use the acsc_WaitMotionEnd function.
During positioning to each point, a velocity profile is built using the default values of
acceleration, deceleration, and jerk of the specified axis. If the ACSC_AMF_VELOCITY flag
is not specified, the default value of velocity is used as well. If the ACSC_AMF_VELOCITY
flag is specified, the value of velocity specified in subsequent acsc_ExtAddPoint functions is
used.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.115.4 Example
5.116 acsc_MultiPointM
The function initiates a multi-axis multi-point motion.
int acsc_MultiPointM(HANDLE Handle, int Flags, int* Axes, double Dwell,
ACSC_WAITBLOCK* Wait)
5.116.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_GoM is executed.
• ACSC_AMF_RELATIVE: the coordinates of each point are
relative. The first point is relative to the instant position when the
motion starts; the second point is relative to the first, etc. If the flag
is not specified, the coordinates of each point are absolute.
• ACSC_AMF_VELOCITY: the motion will use the velocity
specified with each point instead of the default velocity.
• ACSC_AMF_CYCLIC: the motion uses the point sequence as a
cyclic array: after positioning to the last point does positioning to the
first point and continues.
5.116.3 Remarks
The function initiates a multi-axis multi-point motion. To execute single-axis multi-point
motion, use acsc_MultiPoint.
The motion executes sequential positioning to each of the specified points, optionally with
dwell in each point.
The function itself does not specify any point, so the created motion starts only after the first
point is specified. The points of motion are specified by using acsc_AddPointM or
acsc_ExtAddPointM, functions that follow this function.
The motion finishes when the acsc_EndSequenceM function is executed. If the call of
acsc_EndSequenceM is omitted, the motion will stop at the last point of the sequence and wait
for the next point. No transition to the next motion in the motion queue will occur until the
function acsc_EndSequenceM executes.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function cannot wait or validate the end of the motion. To wait for the motion
end, use acsc_WaitMotionEnd function.
During positioning to each point, a vector velocity profile is built using the default values of
velocity, acceleration, deceleration, and jerk of the axis group. If the AFM_VELOCITY flag is
not specified, the default value of velocity is used as well. If the AFM_VELOCITY flag is
specified, the value of velocity specified in subsequent acsc_ExtAddPointM functions is used.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.116.4 Example
{
printf("transaction error: %d\n", acsc_GetLastError());
}
// add some points
Points[0] = 1000; Points[1] = 1000;
acsc_AddPointM(Handle, Axes, Points, NULL);// from the point 1000, 1000
Points[0] = 2000; Points[1] = 2000;
acsc_AddPointM(Handle, Axes, Points, NULL);// to the point 2000, 2000
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL);// the end of the multi-point motion
5.117 acsc_OpenCommDirect
The function starts up the Simulator and opens communication with the Simulator.
HANDLE acsc_OpenCommDirect()
5.117.1 Parameters
This function has no parameters.
If the function fails, the return value is ACSC_INVALID (-1). Get extended error information
by call acsc_GetLastError.
5.117.3 Remarks
The Simulator is a part of the SPiiPlus C Library. When the application calls
acsc_OpenCommDirect, the library starts up the Simulator as a separate process on the same
PC and opens a simulator communication channel for communication with the simulator.
After a channel is open, any SPiiPlus C function works with the Simulator exactly as with a
physical controller.
Note
For the simulator to be to be found by acsc_OpenCommDirect, a copy
of the simulator executable file, sb4.exe (located in the SPiiPlus BIN
folder), must be in the same folder as the application executable file.
5.117.4 Example
5.118 acsc_OpenCommEthernet
The function opens communication with the controller via Ethernet.
HANDLE acsc_OpenCommEthernet(char* Address, int Port)
5.118.1 Parameters
5.118.3 Remarks
After a channel is open, any SPiiPlus C function works with the channel irrespective of the
physical nature of the channel.
If the parameter Port is ACSC_SOCKET_DGRAM_PORT, the library opens communication
using the connectionless socket and UDP communication protocol.
If the parameter Port is ACSC_SOCKET_STREAM_PORT, the library opens communication
using the connection-oriented socket and TCP communication protocol.
The controller supports both protocols. The UDP protocol provides faster communication, but
is not reliable when used in a multi-node network.
Use UDP protocol if the host computer has a point-to-point Ethernet connection to the
controller.
Use TCP protocol if the host computer is connected to the controller through the multi-node
Ethernet network.
5.118.4 Example
5.119 acsc_OpenCommPCI
The function opens a communication channel with the controller via PCI Bus.
Up to 4-communication channels can be open simultaneously with the same SPiiPlus card
through the PCI Bus.
HANDLE acsc_OpenCommPCI(int SlotNumber)
5.119.1 Parameters
5.119.3 Remarks
To open PCI communication the host PC, one or more controller cards must be inserted into the
computer PCI Bus.
After a channel is open, any SPiiPlus C function works with the channel irrespective of the
physical nature of the channel.
5.119.4 Example
5.120 acsc_OpenCommSerial
The function opens communication with the controller via a serial port.
HANDLE acsc_OpenCommSerial(int Channel, int Rate)
5.120.1 Parameters
5.120.3 Remarks
After a channel is open, any SPiiPlus C function works with the channel irrespective of the
physical nature of the channel.
5.120.4 Example
5.121 acsc_OpenHistoryBuffer
The function opens a history buffer.
LP_ACSC_HISTORYBUFFER acsc_OpenHistoryBuffer(HANDLE Handle, int Size)
5.121.1 Parameters
5.121.3 Remarks
The function allocates a history buffer that stores all commands sent to the controller and all
responses and unsolicited messages received from the controller.
Only one history buffer can be open for each communication handle.
The buffer works as a cyclic buffer. When the amount of the stored data exceeds the buffer size,
the newly stored data overwrites the earliest data in the buffer.
5.121.4 Example
5.122 acsc_OpenLogFile
The function opens log file.
int acsc_OpenLogFile(HANDLE Handle, char* FileName)
5.122.1 Parameters
FileName Pointer to the null-terminated string contained name or path of the log
file.
5.122.3 Remarks
The function opens a binary file that stores all communication history.
Only one log file can be open for each communication handle.
If the log file has been open, the library writes all incoming and outgoing messages to the
specified file. The messages are written to the file in binary format, i.e. exactly as they are
received and sent, including all service bytes.
Unlike the history buffer, the log file cannot be read within the library. The main usage of the
5.122.4 Example
if (!acsc_OpenLogFile(Handle, "acs_comm.log"))
{
printf("opening log file error: %d\n", acsc_GetLastError());
}
5.123 acsc_OpenMessageBuffer
The function opens an unsolicited messages buffer.
LP_ACSC_HISTORYBUFFER acsc_OpenMessageBuffer(HANDLE Handle, int Size)
5.123.1 Parameters
5.123.3 Remarks
The function allocates a buffer that stores unsolicited messages from the controller.
Unsolicited messages are messages that the controller sends on its own initiative and not as a
response to command. For example, the disp command in an ACSPL+ program forces the
controller to send an unsolicited message.
Only one message buffer can be open for each communication handle.
If the message buffer has been open, the library separates unsolicited messages from the
controller responses and stores them in the message buffer. In this case, the acsc_Receive
function retrieves only the controller replies, and the acsc_GetMessage function retrieves
unsolicited messages. If the message buffer is not open, acsc_Receive retrieves both replies and
unsolicited messages. If the user application does not call acsc_Receive or acsc_GetMessage
and uses only acsc_Transaction and acsc_Command, the unsolicited messages are discarded.
The message buffer works as a FIFO buffer: acsc_GetMessage extracts the earliest message
stored in the buffer. If acsc_GetMessage extracts the messages slower than the controller
produces them, buffer overflow can occur, and some messages will be lost. Generally, the
greater the buffer, the less likely is buffer overflow to occur.
5.123.4 Example
5.124 acsc_PegI
The function initiates incremental PEG. Incremental PEG function is defined by first point, last
point and the interval.
int acsc_PegI(HANDLE Handle, int Flags, int Axis, double Width, int FirstPoint, int
Interval, int LastPoint, int TbNumber, double TbPeriod, ACSC_WAITBLOCK* Wait)
5.124.1 Parameters
5.124.3 Remarks
The function initiates incremental PEG generation. See details in ACSPL+ programmers guide.
The time-based pulse generation is optional, if it is not used, TbPeriod and TbNumber should
be ACSC_NONE.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.124.4 Example
5.125 acsc_PegR
The function initiates random PEG. Random PEG function specifies an array of points where
position-based events should be generated.
int acsc_PegR(HANDLE Handle,int Flags,int Axis,double Width,char*
PointArray,char* StateArray,int TbNumber, double TbPeriod, ACSC_WAITBLOCK*
Wait)
5.125.1 Parameters
PointArray Null-terminated string contained the name of the real array that stores
positions at which PEG pulse should be generated
The array must be declared as a global variable by an ACSPL+ program
or by the acsc_DeclareVariable function.
StateArray Null-terminated string contained the name of the integer array that
stores desired output state at each position.
The array must be declared as a global variable by an ACSPL+ program
or by the acsc_DeclareVariable function.
If output state change is not desired, this parameter should be NULL.
5.125.3 Remarks
The function initiates random PEG generation (see SPiiPlus ACSPL+ Programmer’s Guide).
StateArray should be NULL if output state won’t change because of PEG.
The time-based pulse generation is optional, if it is not used, TbPeriod and TbNumber should
be ACSC_NONE.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.125.4 Example
5.126 acsc_Projection
The function sets a projection matrix for segmented motion.
int acsc_Projection(HANDLE Handle, int* Axes, char* Matrix, ACSC_WAITBLOCK*
Wait)
5.126.1 Parameters
Matrix Pointer to the null-terminated string containing the name of the matrix
that provides the specified projection.
5.126.3 Remarks
The function sets a projection matrix for segmented motion.
The projection matrix connects the plane coordinates and the axis values in the axis group. The
projection can provide any transformation as rotation or scaling. The number of the matrix rows
must be equal to the number of the specified axes. The number of the matrix columns must
equal two.
The matrix must be declared before as a global variable by an ACSPL+ program or by the
acsc_DeclareVariable function and must be initialized by an ACSPL+ program or by the
acsc_WriteReal function.
For more information about projection, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.126.4 Example
5.127 acsc_ReadDPRAMInteger
The function reads 32-bit integer from the DPRAM.
acsc_ReadDPRAMInteger(HANDLE Handle, int address,int *Value)
5.127.1 Parameters
5.127.3 Remarks
Address has to be even number in the range of 128 to 508, because we use 16-bit alignment
when working with DPRAM. Addresses less than 128 are used for internal purposes.
Note
The function can be used only with the PCI and Simulator
communication channels.
5.127.4 Example
5.128 acsc_ReadDPRAMReal
The function reads 64-bit Real from the DPRAM.
acsc_ReadDPRAMReal(HANDLE Handle, int address, double *Value)
5.128.1 Parameters
5.128.3 Remarks
Address has to be even number in the range of 128 to 504, because we use 16-bit alignment
when working with DPRAM. Addresses less than 128 are used for internal purposes.
Note
The function can be used only with the PCI and Simulator
communication channels.
5.128.4 Example
5.129 acsc_ReadInteger
The function reads value(s) from integer variable.
int acsc_ReadInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, int* Values, ACSC_WAITBLOCK* Wait)
5.129.1 Parameters
NBuf Number of program buffer for local variable or ACSC_NONE for global
and standard variable.
5.129.3 Remarks
The function reads specified integer variable or array.
The variable can be a standard controller variable, a user global variable, or a user local
variable.
Standard and user global variables have global scope. Therefore, parameter Nbuf must be
ACSC_NONE (-1) for these classes of variables.
User local variable exists only within a buffer. The buffer number must be specified for user
local variable.
If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE. The
function reads the requested value and assigns it to the variable pointed by Values.
If the variable is a one-dimensional array, From1, To1 must specify the index range and
From2, To2 must be ACSC_NONE. Array Values must be of size To1-From1+1 at least. The
function reads all requested values from index From1 to index To1 inclusively and stores them
in the Values array.
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. Array
Values must be of size (To1-From1+1)x(To2-From2+1) values at least. The function uses the
Values array in such a way: first, the function reads To2-From2+1 values from row From1
and fills the Values array elements from 0 to To2-From2, then reads To2-From2+1 values
from raw From1+1 and fills the Values array elements from To2-From2+1 to 2*(To2-
From2)+1, etc.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Values and Wait items until a call to the acsc_WaitForAsyncCall function.
5.129.4 Example
5.130 acsc_ReadReal
The function reads value(s) from a real variable.
int acsc_ReadReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int From2,
int To2, double* Values, ACSC_WAITBLOCK* Wait)
5.130.1 Parameters
5.130.3 Remarks
The function reads specified real variable or array.
The variable can be a standard controller variable, user global variable, or user local variable.
Standard and user global variables have global scope. Therefore, parameter Nbuf must be
ACSC_NONE (-1) for these classes of variables.
User local variable exists only within a buffer. The buffer number must be specified for user
local variable.
If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE. The
function reads the requested value and assigns it to the variable pointed by Values.
If the variable is a one-dimensional array, From1, To1 must specify the index range and
From2, To2 must be ACSC_NONE. Array Values must be of size To1-From1+1 at least. The
function reads all requested values from index From1 to index To1 inclusively and stores them
in the Values array.
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. Array
Values must be of size (To1-From1+1)x(To2-From2+1) values at least. The function uses the
Values array in such a way: first, the function reads To2-From2+1 values from row From1
and fills the Values array elements from 0 to To2-From2, then reads To2-From2+1 values
from raw From1+1 and fills the Values array elements from To2-From2+1 to 2*(To2-
From2)+1, etc.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Values and Wait items until a call to the acsc_WaitForAsyncCall function.
5.130.4 Example
5.131 acsc_Receive
The function receives a message from the controller.
int acsc_Receive(HANDLE Handle, char* Buf, int Count, int* Received,
ACSC_WAITBLOCK* Wait)
5.131.1 Parameters
5.131.3 Remarks
The function retrieves currently stored data from an input internal library buffer. If the number
of bytes in the input library buffer is longer than Count, the function retrieves and stores only
Count characters in the buffer pointed by Buf. The Received parameter will contain the exact
number of the characters stored in InBuf.
The function returns immediately after storing data in the user buffer irrespective of value of
the Wait parameter.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Note
This function is only used for compatibility with the previous version of
zero-library. To communicate with the controller, use the
acsc_Transaction or acsc_Command functions.
5.131.4 Example
5.132 acsc_ReleaseComm
The function releases a communication channel.
int acsc_ReleaseComm(HANDLE Handle)
5.132.1 Parameters
acsc_GetLastError.
5.132.3 Remarks
The function releases the communication handle captured by acsc_CaptureComm and allows
other threads to communicate through the channel.
5.132.4 Example
if (!acsc_ReleaseComm(Handle))
{
printf("release communication error: %d\n", acsc_GetLastError());
}
5.133 acsc_ResetIndexState
The function resets the specified bit of the index/mark state.
int acsc_ResetIndexState(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)
5.133.1 Parameters
Mask The parameter contains bit to be cleared. Only one of the following flags
can be specified:
• ACSC_IST_IND – a primary encoder index of the specified axis is
latched
• ACSC_IST_IND2 – a secondary encoder index of the specified axis
is latched
5.133.3 Remarks
The function resets the specified bit of the index/mark state. The parameter Mask contains a
bit, which must be cleared, i.e. the function resets only that bit of the index/mark state, which
corresponds to non-zero bit of the parameter Mask. To get the current index/mark state, use
acsc_GetIndexState function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.133.4 Example
5.133.5 acsc_ResetIndexState
The function resets the specified bit of the index/mark state.
int acsc_ResetIndexState(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)
5.133.6 Parameters
Mask The parameter contains bit to be cleared. Only one of the following flags
can be specified:
• ACSC_IST_IND – a primary encoder index of the specified axis is
latched
• ACSC_IST_IND2 – a secondary encoder index of the specified axis
is latched
• ACSC_IST_MARK – a MARK1 signal has been generated and
position of the specified axis was latched
• ACSC_IST_MARK2 – a MARK2 signal has been generated and
position of the specified axis was latched
5.133.8 Remarks
The function resets the specified bit of the index/mark state. The parameter Mask contains a
bit, which must be cleared, i.e. the function resets only that bit of the index/mark state, which
corresponds to non-zero bit of the parameter Mask. To get the current index/mark state, use
acsc_GetIndexState function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.133.9 Example
5.134 acsc_RunBuffer
The function starts up ACSPL+ program in the specified buffer.
int acsc_RunBuffer(HANDLE Handle, int Buffer, char* Label, ACSC_WAITBLOCK*
Wait)
5.134.1 Parameters
5.134.3 Remarks
The function starts up ACSPL+ program in the specified buffer. The execution starts from the
specified label, or from the first line if the label is not specified.
If the program was not compiled before, the function first compiles the program and then starts
it. If an error was encountered during compilation, the program does not start.
If the program was suspended by the acsc_SuspendBuffer function, the function resumes the
program execution from the point where the program was suspended.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the program in the specified buffer was started
successfully. The function does not wait for the program end. To wait for the program end, use
the acsc_WaitProgramEnd function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.134.4 Example
5.135 acsc_Send
The function sends a message to the controller.
int acsc_Send(HANDLE Handle, char* Buf, int Count, ACSC_WAITBLOCK* Wait)
5.135.1 Parameters
acsc_GetLastError.
5.135.3 Remarks
The function sends a specified number of characters to the controller. The function does not
receive a controller response.
The function can be useful for applications like communication terminal to send any commands
to the controller. All background communication can be received with help of the
acsc_GetHistory function, which retrieves communication history.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.135.4 Example
5.136 acsc_Segment
The function initiates a multi-axis segmented motion.
int acsc_Segment(HANDLE Handle, int Flags, int* Axes, double* Point,
ACSC_WAITBLOCK* Wait)
5.136.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_GoM is executed.
• ACSC_AMF_VELOCITY: the motion will use velocity specified
for each segment instead of the default velocity.
• ACSC_AMF_CYCLIC: the motion uses the segment sequence as a
cyclic array: after the last segment, move along the first segment etc.
• ACSC_AMF_VELOCITYLOCK: slaved motion: the motion
advances in accordance to the master value of the leading axis.
• ACSC_AMF_POSITIONLOCK: slaved motion, strictly conformed
to master.
• ACSC_AMF_EXTRAPOLATED: if a master value travels beyond
the specified path, the last or the first segment is extrapolated.
• ACSC_AMF_STALLED: if a master value travels beyond the
specified path, the motion stalls at the last or first point.
Point Array of the coordinates of the initial point on the plane. The number and
order of values must correspond to the Axes array. The Point must
specify a value for each element of Axes except the last –1 element.
acsc_GetLastError.
5.136.3 Remarks
The function initiates a multi-axis segmented motion.
Segmented motion moves axes along a continuous path. The path is defined as a sequence of
linear and arc segments on the plane. Although segmented motion follows a flat path, it can
involve any number of axes, because the motion plane can be connected to the axes at any
projection transformation. To use such transformation, use the acsc_Projection function.
The function itself does not specify any segment, so the created motion starts only after the first
segment is specified. The segments of motion are specified by the using acsc_Line,
acsc_Arc1, acsc_Arc2, acsc_ExtLine, acsc_ExtArc1, or acsc_ExtArc2 functions that follow
this function.
The motion finishes when the acsc_EndSequenceM function is executed. If the call of
acsc_EndSequenceM is omitted, the motion will stop at the last segment of the sequence and
wait for the next segment. No transition to the next motion in the motion queue will occur until
the function acsc_EndSequenceM is executed.
During positioning to each point, a vector velocity profile is built using the default values of
velocity, acceleration, deceleration, and jerk of the axis group. If the AFM_VELOCITY flag is
not specified, the default value of velocity is used as well. If the AFM_VELOCITY flag is
specified, the value of velocity specified in subsequent acsc_ExtLine, acsc_ExtArc1, or
acsc_ExtArc2 functions is used.
The flags ACSC_AMF_EXTRAPOLATED and ACSC_AMF_STALLED are relevant only
for slaved motion and must be used with ACSC_AMF_VELOCITYLOCK or
ACSC_AMF_POSITIONLOCK flags.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function does not wait and does not validate the end of the motion. To wait
for the motion end, use the acsc_WaitMotionEnd function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.136.4 Example
5.137 acsc_SetAcceleration
The function defines a value of motion acceleration.
5.137.1 Parameters
Acceleration The value specifies required motion acceleration. The value will be used
in the subsequent motions except the master-slave motions.
5.137.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects the motions initiated after the function call. The function has no effect on
any motion that was started or planned before the function call. To change acceleration of an
executed or planned motion, use the acsc_SetAccelerationImm function.
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.137.4 Example
5.138 acsc_SetAccelerationImm
The function defines a value of motion acceleration. Unlike acsc_SetAcceleration, the
function has immediate effect on any executed and planned motion.
int acsc_SetAccelerationImm(HANDLE Handle, int Axis, double Acceleration,
ACSC_WAITBLOCK* Wait)
5.138.1 Parameters
5.138.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects:
• The currently executed motion.
• The waiting motions that were planned before the function call.
• The motions that will be commanded after the function call.
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.138.4 Example
5.139 acsc_SetAnalogOutput
The function writes the current numerical value to the specified analog outputs.
int acsc_SetAnalogOutput(HANDLE Handle, int Port, int Value, ACSC_WAITBLOCK*
Wait)
5.139.1 Parameters
If the function fails, the return value is zero. Get extended error information by cal
lacsc_GetLastError.
5.139.3 Remarks
The function writes the current numerical value to the specified analog outputs. To get a value
of the specific analog outputs, use the acsc_GetAnalogOutput function.
Analog outputs are represented in the controller variable AOUT. For more information about
analog outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.139.4 Example
5.140 acsc_SetCallback
The function installs a user-defined callback function for the specified interrupt condition
int acsc_SetCallback(HANDLE Handle, ACSC_INTR_CALLBACK_FUNC Callback,
int Interrupt)
5.140.1 Parameters
5.140.3 Remarks
The function installs a user-defined callback function Callback for the specified interrupt
condition Interrupt.
The library calls the Callback function when the specified interrupt occurs. The bit-mapped
parameter Param of the function Callback identifies which axis/buffer/input the interrupt was
generated for. See “Callback Interrupts Masks” on Page 390 for a detailed description of the
parameter Param for each interrupt.
One callback can be installed for each interrupt. The library creates a separate thread for each
interrupt. Therefore, each callback function is called in a separate thread so that the callbacks
do not delay one another.
To uninstall a specific callback, call the function acsc_SetCallbackwith the parameter
Callback equal to NULL and the parameter Interrupt equal to the specified interrupt type.
Note
Before the PEG interrupts can be detected, the acsc_AssignPins
function must be called.
5.140.4 Example
5.141 acsc_SetCallbackExt
The function installs a user-defined callback function for the specified interrupt condition with
user-defined parameter.
5.141.1 Parameters
5.141.3 Remarks
The function installs a user-defined callback function Callback for the specified interrupts
condition Interrupt.
The library calls the Callback function when the specified interrupt occurs. The bit-mapped
parameter Param of the function Callback identifies for which axis/buffer/input the interrupt
was generated. See “Callback Interrupts Masks” on Page 390 for a detailed description of
the parameter Param for each interrupt.
One callback can be installed for each interrupt, for same communication channel. The library
creates a separate thread for each interrupt. Therefore, each callback function is called in a
separate thread so that the callbacks do not delay one another.
User on Callback registration defines the parameter UserParameter. It is especially useful
when several SPiiPlus cards are used. That allows setting the same function as a Callback on
certain interrupt, for all the cards. Inside that function user can see by the UserParameter,
Note
Before the PEG interrupts can be detected, the acsc_AssignPins
function must be called.
5.141.4 Example
5.142 acsc_SetCallbackPriority
The function sets the priority for all callback threads.
int acsc_SetCallbackPriority(HANDLE Handle, int Priority)
5.142.1 Parameters
Priority Specifies the priority value for the callback thread. This parameter can be
one of the operating system defined priority levels.
For example Win32 API defines the following priorities:
THREAD_PRIORITY_ABOVE_NORMAL
THREAD_PRIORITY_BELOW_NORMAL
THREAD_PRIORITY_HIGHEST
THREAD_PRIORITY_IDLE
THREAD_PRIORITY_LOWEST
THREAD_PRIORITY_NORMAL
THREAD_PRIORITY_TIME_CRITICAL
As default, all callback threads have a normal priority.
5.142.3 Remarks
The operating system uses the priority level of all executable threads to determine which thread
gets the next slice of CPU time. Basically, threads are scheduled in a round-robin fashion at
each priority level, and only when there are no executable threads at a higher level does
scheduling of threads at a lower level take place.
When manipulating priorities, be very careful to ensure that a high-priority thread does not
consume all of the available CPU time.
See corresponding operating system guides for details.
Note
The function can be used only with the PCI communication channel.
5.142.4 Example
5.143 acsc_SetCommOptions
The function sets the communication options.
int acsc_SetCommOptions(HANDLE Handle, unsigned int Options)
5.143.1 Parameters
5.143.3 Remarks
The function sets the communication options. To get current communication option, call
acsc_GetCommOptions.
To add some communication options to the current configuration, modify an Option parameter
that has been filled in by a call to acsc_GetCommOptions. This ensures that the other
communication options will have same values.
5.143.4 Example
5.144 acsc_SetConf
The function writes system configuration data.
int acsc_SetConf(HANDLE Handle, int Key, int Index, double Value,
ACSC_WAITBLOCK* Wait)
5.144.1 Parameters
5.144.3 Remarks
The function writes system configuration data. The Key parameter specifies the feature number
and the Index parameter defines axis or buffer to which it should be applied. Use
ACSC_CONF_XXX constants in the value field. For detailed description of system
configuration see the description of the SetConf function in the SPiiPlus ACSPL+
Programmer’s Guide.
5.144.4 Example
5.145 acsc_SetDeceleration
The function defines a value of motion deceleration.
int acsc_SetDeceleration(HANDLE Handle, int Axis, double Deceleration,
ACSC_WAITBLOCK* Wait)
5.145.1 Parameters
Deceleration The value specifies a required motion deceleration. The value will
be used in the subsequent motions except the master-slave motions.
5.145.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects the motions initiated after the function call. The function has no effect on
any motion that was started or planned before the function call. To change deceleration of an
executed or planned motion, use the acsc_SetDecelerationImm function.
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.145.4 Example
5.146 acsc_SetDecelerationImm
The function defines a value of motion deceleration. Unlike acsc_SetDeceleration, the
function has immediate effect on any executed and planned motion.
int acsc_SetDecelerationImm(HANDLE Handle, int Axis, double Deceleration,
ACSC_WAITBLOCK* Wait)
5.146.1 Parameters
5.146.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects:
• The currently executed motion.
• The waiting motions that were planned before the function call.
• The motions that will be commanded after the function call.
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.146.4 Example
5.147 acsc_SetExtOutput
The function sets the specified extended output to the specified value.
int acsc_SetExtOutput(HANDLE Handle, int Port, int Bit, int Value,
ACSC_WAITBLOCK* Wait)
5.147.1 Parameters
Value The value to be written to the specified output. Any non-zero value is
interpreted as 1.
5.147.3 Remarks
The function sets the specified extended output to the specified value. To set values of all
outputs of the specific extended port, use the acsc_SetExtOutputPort function.
Extended outputs are represented in the controller EXTOUT variable. For more information
about extended outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.147.4 Example
5.148 acsc_SetExtOutputPort
The function sets the specified extended output port to the specified value.
int acsc_SetExtOutputPort(HANDLE Handle, int Port, int Value,
ACSC_WAITBLOCK* Wait)
5.148.1 Parameters
5.148.3 Remarks
The function sets the specified extended output port to the specified value. To set the value of
the specific output of the specific extended port, use the acsc_SetExtOutput function.
Extended outputs are represented in the controller variable EXTOUT. For more information
about extended outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.148.4 Example
5.149 acsc_SetFaultMask
The function sets the mask that enables or disables the examination and processing of controller
faults.
int acsc_SetFaultMask(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)
5.149.1 Parameters
5.149.3 Remarks
The function sets the mask that enables/disables the examination and processing of the
controller faults. The two types of controller faults are motor faults and system faults.
The motor faults are related to a specific motor, the power amplifier or the Servo processor. For
example: Position Error, Encoder Error or Driver Alarm.
The system faults are not related to any specific motor. For example: Emergency Stop or
Memory Fault.
For more information about the controller faults, see the SPiiPlus ACSPL+ Programmer’s
Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.149.4 Example
5.150 acsc_SetFPosition
The function assigns a current value of feedback position.
int acsc_SetFPosition(HANDLE Handle, int Axis, double FPosition,
ACSC_WAITBLOCK* Wait)
5.150.1 Parameters
5.150.3 Remarks
The function assigns a current value to the feedback position. No physical motion occurs. The
motor remains in the same position; only the internal controller offsets are adjusted so that the
periodic calculation of the feedback position will provide the required results.
For more information see the explanation of the SET command in the SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.150.4 Example
5.151 acsc_SetInterruptMask
The function sets the mask for specified interrupt.
int acsc_SetInterruptMask(HANDLE Handle, int Interrupt, int Mask)
5.151.1 Parameters
5.151.3 Remarks
The function sets the bit mask for specified interrupt. To get current mask for specified
interrupt, call acsc_GetInterruptMask.
Using a mask, you can reduce the number of calls of your callback function. The callback will
be called only if the interrupt is caused by an axis/buffer/input that corresponds to non-zero bit
in the related mask.
Note
The function can be used only with the PCI communication channel.
5.151.4 Example
// the example shows how to configure the interrupt mask to monitor only
// specific axis
if (!acsc_SetInterruptMask(Handle, // communication handle
ACSC_INTR_PHYSICAL_MOTION_END, // specified interrupt
ACSC_MASK_AXIS_X // enable interrupt
// only for the axis X
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
5.152 acsc_SetIterations
The function sets the number of iterations in one transaction.
int acsc_SetIterations(HANDLE Handle, int Iterations)
5.152.1 Parameters
5.152.3 Remarks
If, after the transmission of command to the controller, the controller response is not received
during the predefined time, the library repeats the transmission of command. The number of
those iterations is defined by the Iterations parameter for each communication channel
independently.
Most of the SPiiPlus C functions perform communication with the controller by transactions
(i.e. they send commands and wait for responses) that are based on the acsc_Transaction
function. Therefore, the changing of number of iterations can have an influence on the behavior
of the user application.
The default the number of iterations for all communication channels is 2.
5.152.4 Example
if (!acsc_SetIterations(Handle, 2))
{
printf("number of iterations setting error: %d\n",
acsc_GetLastError());
}
5.153 acsc_SetJerk
The function defines a value of motion jerk.
int acsc_SetJerk(HANDLE Handle, int Axis, double Jerk, ACSC_WAITBLOCK* Wait)
5.153.1 Parameters
Jerk The value specifies a required motion jerk. The value will be used in the
subsequent motions except for the master-slave motions.
5.153.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects the motions initiated after the function call. The function has no effect on
any motion that was started or planned before the function call. To change the jerk of an
executed or planned motion, use the acsc_SetJerkImm function.
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.153.4 Example
5.154 acsc_SetJerkImm
The function defines a value of motion jerk. Unlike acsc_SetJerk, the function has immediate
effect on any executed and planned motion.
int acsc_SetJerkImm(HANDLE Handle, int Axis, double Jerk, ACSC_WAITBLOCK*
Wait)
5.154.1 Parameters
5.154.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects:
• The currently executed motion.
• The waiting motions that were planned before the function call.
• The motions that will be commanded after the function call.
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.154.4 Example
5.155 acsc_SetKillDeceleration
The function defines a value of motion kill deceleration.
int acsc_SetKillDeceleration(HANDLE Handle, int Axis, double KillDeceleration,
ACSC_WAITBLOCK* Wait)
5.155.1 Parameters
KillDeceleration The value specifies a required motion kill deceleration. The value will
be used in the subsequent motions.
5.155.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects the motions initiated after the function call. The function has no effect on
any motion that was started or planned before the function call.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.155.4 Example
5.156 acsc_SetKillDecelerationImm
The function defines a value of motion kill deceleration. Unlike acsc_SetKillDeceleration, the
function has an immediate effect on any executed and planned motion.
int acsc_SetKillDecelerationImm(HANDLE Handle, int Axis, double Deceleration,
ACSC_WAITBLOCK* Wait)
5.156.1 Parameters
5.156.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects:
• The currently executed motion
• The waiting motions that were planned before the function call
• The motions that will be commanded after the function call
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.156.4 Example
5.157 acsc_SetLogFileOptions
The function sets the log file options.
acsc_SetLogFileOptions(HANDLE Handle,ACSC_LOG_DETALIZATION_LEVEL
Detalization, ACSC_LOG_DATA_PRESENTATION Presentation)
5.157.1 Parameters
5.157.3 Remarks
The function configures the log file options. The function may be called before or after the log
file is opened.
5.157.4 Example
5.158 acsc_SetMaster
The function initiates calculating of master value for an axis.
int acsc_SetMaster(HANDLE Handle, int Axis, char* Formula, ACSC_WAITBLOCK*
Wait)
5.158.1 Parameters
Formula ASCII string that specifies a rule for calculating master value.
5.158.3 Remarks
The function initiates calculating of master value for an axis.
The master value for each axis is presented in the controller as one element of the MPOS array.
Once the acsc_SetMaster function is called, the controller is calculates the master value for the
specified axis each controller cycle.
The acsc_SetMaster function can be called again for the same axis at any time. At that
moment, the controller discards the previous formula and accepts the newly specified formula
for the master calculation.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the controller starts
calculating the master value according to the formula.
The Formula string can specify any valid ACSPL+ expression that uses any standard or user
global variables as its operands.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.158.4 Example
5.159 acsc_SetOutput
The function sets the specified digital output to the specified value.
int acsc_SetOutput(HANDLE Handle, int Port, int Bit, int Value, ACSC_WAITBLOCK*
Wait)
5.159.1 Parameters
Value The value to be written to the specified output. Any non-zero value is
interpreted as 1.
5.159.3 Remarks
The function sets the specified digital output to the specified value. To set values of all outputs
of a specific port, use the acsc_SetExtOutputPort function.
Digital outputs are represented in the controller variable OUT. For more information about
digital outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.159.4 Example
5.160 acsc_SetOutputPort
The function sets the specified digital output port to the specified value.
int acsc_SetOutputPort(HANDLE Handle, int Port, int Value, ACSC_WAITBLOCK*
Wait)
5.160.1 Parameters
5.160.3 Remarks
The function sets the specified digital output port to the specified value. To set the value of the
specific output of the specific port, use the acsc_SetOutput function.
Digital outputs are represented in the controller variable OUT. For more information about
digital outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.160.4 Example
5.161 acsc_SetQueueOverflowTimeout
The function sets the Queue Overflow Timeout.
int acsc_SetQueueOverflowTimeout (HANDLE Handle, int Delay)
5.161.1 Parameters
5.161.3 Remarks
The function sets Queue Overflow Timeout value in milliseconds. See also “Non-waiting
Calls” on Page 12.
5.161.4 Example
if (!acsc_ SetQueueOverflowTimeout(Handle,100))
{
printf("Queue Overflow Timeout setting error: %d\n",
acsc_GetLastError());
}
5.162 acsc_SetResponseMask
The function retrieves the mask that defines the motor or the system faults for which the
controller provides the default response.
int acsc_SetResponseMask(HANDLE Handle, int Axis, int Mask, ACSC_WAITBLOCK*
Wait)
5.162.1 Parameters
5.162.3 Remarks
The function retrieves the mask that defines the motor or the system faults for which the
controller provides the default response.
The default response is a controller-predefined action for the corresponding fault. For more
information about the controller faults and default responses, see the SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.162.4 Example
5.163 acsc_SetRPosition
The function assigns a current value of reference position.
int acsc_SetRPosition(HANDLE Handle, int Axis, double RPosition,
ACSC_WAITBLOCK* Wait)
5.163.1 Parameters
5.163.3 Remarks
The function assigns a current value to the reference position. No physical motion occurs. The
motor remains in the same position; only the internal controller offsets are adjusted so that the
periodic calculation of the reference position will provide the required results.
For more information see explanation of the SET command in the SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.163.4 Example
5.164 acsc_SetSafetyInputPortInv
The function sets the set of bits that define inversion for the specified safety input port.
int acsc_SetSafetyInputPortInv(HANDLE Handle, int Axis, int Value,
ACSC_WAITBLOCK* Wait)
5.164.1 Parameters
5.164.3 Remarks
The function sets the bits that define inversion for the specified safety input port. To retrieve an
inversion for the specific safety input port, use the acsc_GetSafetyInputPortInv function.
If a bit of the set is zero, the corresponding signal will not be inverted and therefore high voltage
is considered an active state. If a bit is raised, the signal will be inverted and low voltage is
considered an active state.
The inversions of safety inputs are represented in the controller variables SAFINI and
S_SAFINI. For more information about safety, inputs see SPiiPlus ACSPL+ Programmer’s
Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
Note
Some safety inputs can be unavailable in a specific controller model.
For example, SPiiPlus SA controller does not provide Motor Overheat,
Preliminary Left Limit, and Preliminary Right Limit safety inputs. See
specific model documentation for details.
5.164.4 Example
5.165 acsc_SetServer
The function defines user-mode driver host IP address
int acsc_SetServer(char *IP)
5.165.1 Parameters
5.165.3 Remarks
The function sets the IP address of the User-Mode Driver (UMD) host. Once the function is
called all acsc_OpenCommxxx calls will attempt to establish communication via the user-mode
driver that was specified in recent acsc_SetServer call. In order to establish communication via
different user-mode driver host acsc_SetServer should be called again.
Use the function only if the application needs to establish communication with a controller
through the remote computer.
If the function is not called, by default all connections are established through the local
computer. Only a controller connected to the local computer by a serial cable, PCI bus or
Ethernet can be accessed.
Once the function is called, it defines the remote computer to be used as a communication
server. Any subsequent acsc_OpenCommxxx call will attempt to establish communication with
a controller connected to that remote computer.
Application can simultaneously communicate through several communication servers. Use the
following pattern to open communication channels through several servers:
Handle01= acsc_OpenComxxx(…); // Open all channels with controllers
// connected to the local computer
Handle02= ascs_OpenComxxx(…)
SetServer(Server1); // Set Server1
Handle11=acsc_OpenComxxx(…); // Open all channels with controllers
// connected to Server1
Handle12= acsc_OpenComxxx(…)
SetServer(Server2); // Set Server2
Handle21= acsc_OpenComxxx(…); // Open all channels with controllers
// connected to Server2
Handle22= acsc_OpenComxxx(…)
Note
when the application calls SetServer(Server2) all handles related to the
local computer or to Server1 remain valid. Then the application can use
all handles to provide simultaneous communication with many
controllers through different servers.
5.165.4 Example
5.166 acsc_SetServerExt
The function behaves as acsc_SetServer but explicitly specifies the IP port number for a
remore connection, where acsc_SetServer uses only the default port.
int acsc_SetServerExt(char*IP,intPort)
5.166.1 Parameters
IP IP address where to look for server.
5.166.3 Remarks
This function is used for access over varying IP ports
5.166.4 Example
This doesn’t look like the other examples
acsc_SetServerExt("10.0.0.13",7777)
Handle=acsc_OpenCommPCI(-1)//Will attempt to find active UMD running on host
//"10.0.0.13" and listenning on Port 7777
//And open communication with PCI card at that
host
5.167 acsc_SetServerLoginExt
The function behaves as acsc_SetServerExt and in addition passes login data.
int acsc_SetServerExtLogin(char *IP, int Port, char *Username, char *Password, char
*Domain)
5.167.1 Parameters
5.167.3 Example
acsc_SetServerExtLogin("10.0.0.13",7777,"Mickey","viva11","ACS-Tech80")
Handle=acsc_OpenCommPCI(-1)//Will attempt to find active UMD running on host
//"10.0.0.13" and listenning on Port 7777
//On the host attempt to login as "Mickey"
//And open communication with PCI card at that
host
5.168 acsc_SetTargetPosition
The function assigns a current value of track position.
int acsc_SetTargetPosition(HANDLE Handle, int Axis, double TargetPosition,
ACSC_WAITBLOCK* Wait)
5.168.1 Parameters
If the function fails, the return value is zero. Get extended error information by call
acsc_GetLastError.
5.168.3 Remarks
The function assigns a current value to the Track position. If the corresponding axis is
initialized with track motion, the change of TPOS will cause generation of ptp motion to that
new value.
For more information see the explanation of the track command in the SPiiPlus ACSPL+
Programmer’s Guide.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.168.4 Example
5.169 acsc_SetTimeout
The function sets the communication timeout.
int acsc_SetTimeout(HANDLE Handle, int Timeout)
5.169.1 Parameters
5.169.3 Remarks
The function sets the communication timeout.
All of the subsequent waiting calls of the functions will wait for the controller response
Timeout in milliseconds. If the controller does not respond to the sent command during this
time, SPiiPlus C functions return with zero value. In this case, the call of acsc_GetLastError
will return the ACSC_TIMEOUT error.
5.169.4 Example
if (!acsc_SetTimeout(Handle, 5000))
{
printf("timeout set error: %d\n", acsc_GetLastError());
}
5.170 acsc_SetVelocity
The function defines a value of motion velocity.
int acsc_SetVelocity(HANDLE Handle, int Axis, double Velocity, ACSC_WAITBLOCK*
Wait)
5.170.1 Parameters
Velocity The value specifies required motion velocity. The value will be used in
the subsequent motions except for the master-slave motions and the
motions activated with the ACSC_AMF_VELOCITY flag.
5.170.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects the motions initiated after the function call. The function has no effect on
any motion that was started or planned before the function call. To change velocity of an
executed or planned motion, use the acsc_SetVelocityImm function.
The function has no effect on the master-slave motions and the motions activated with the
ACSC_AMF_VELOCITY flag.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.170.4 Example
5.171 acsc_SetVelocityImm
The function defines a value of motion velocity. Unlike acsc_SetVelocity, the function has
immediate effect on any executed or planned motion.
int acsc_SetVelocityImm(HANDLE Handle, int Axis, double Velocity,
ACSC_WAITBLOCK* Wait)
5.171.1 Parameters
5.171.3 Remarks
The function writes the specified value to the controller.
One value can be specified for each axis.
A single-axis motion uses the value of the corresponding axis. A multi-axis motion uses the
value of the leading axis. The leading axis is an axis specified first in the motion command.
The function affects:
• The currently executed motion. The controller provides a smooth transition from the instant
current velocity to the specified new value.
• The waiting motions that were planned before the function call.
• The motions that will be commanded after the function call.
The function has no effect on the master-slave motions.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.171.4 Example
5.172 acsc_Slave
The function initiates a master-slave motion.
int acsc_Slave(HANDLE Handle, int Flags, int Axis, ACSC_WAITBLOCK* Wait)
5.172.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_Go is executed.
• ACSC_AMF_POSITIONLOCK: the motion will use position lock.
If the flag is not specified, velocity lock is used (see “Remarks” on
Page 323).
5.172.3 Remarks
The function initiates a single-axis master-slave motion with an unlimited area of following. If
the area of following must be limited, use acsc_SlaveStalled.
The master-slave motion continues until the motion is killed or the motion fails for any reason.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully.
The master value for the specified axis must be defined before by the call to acsc_SetMaster
function. The acsc_SetMaster function can be called again in order to change the formula of
master calculation. If at this moment the master-slave motion is in progress, the slave can come
out from synchronism. The controller then regains synchronism, probably with a different value
of offset between the master and slave.
If the ACSC_AMF_POSITIONLOCK flag is not specified, the function activates a velocity-
lock mode of slaved motion. When synchronized, the APOS axis reference follows the MPOS
with a constant offset:
APOS = MPOS + C
The value of C is latched at the moment when the motion comes to synchronism, and then
remains unchanged as long as the motion is synchronous. If at the moment of motion start the
master velocity is zero, the motion starts synchronously and C is equal to the difference
between initial values of APOS and MPOS.
If the ACSC_AMF_POSITIONLOCK flag is specified, the function activates a position-lock
mode of slaved motion. When synchronized, the APOS axis reference strictly follows the
MPOS:
APOS = MPOS
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.172.4 Example
5.173 acsc_SlaveStalled
The function initiates master-slave motion within predefined limits.
int acsc_SlaveStalled(HANDLE Handle, int Flags, int Axis, double Left, double Right,
ACSC_WAITBLOCK* Wait)
5.173.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
acsc_Go function is executed.
• ACSC_AMF_POSITIONLOCK: the motion will use position lock. If
the flag is not specified, velocity lock is used (see “Remarks” on
Page 326).
5.173.3 Remarks
The function initiates single-axis master-slave motion within predefiend limits. Use acsc_Slave
to initiate unlimited motion. For sophisticated forms of master-slave motion, use slaved
variants of segmented and spline motions.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully.
The master-slave motion continues until the kill command is executed, or the motion fails for
any reason.
The master value for the specified axis must be defined before by the call to acsc_SetMaster
function. The acsc_SetMaster function can be called again in order to change the formula of
master calculation. If at this moment the master-slave motion is in progress, the slave can come
out from synchronism. The controller then regains synchronism, probably with a different value
of offset between the master and slave.
If the ACSC_AMF_POSITIONLOCK flag is not specified, the function activates a velocity-
lock mode of slaved motion. When synchronized, the APOS axis reference follows the MPOS
with a constant offset:
APOS = MPOS + C
The value of C is latched at the moment when the motion comes to synchronism, and then
remains unchanged as long as the motion is synchronous. If at the moment of motion start the
master velocity is zero, the motion starts synchronously and C is equal to the difference
between initial values of APOS and MPOS.
If the ACSC_AMF_POSITIONLOCK flag is specified, the function activates a position-lock
mode of slaved motion. When synchronized, the APOS axis reference strictly follows the
MPOS:
APOS = MPOS
The Left and Right values define the allowed area of changing the APOS value. The MPOS
value is not limited and can exceed the limits. In this case, the motion comes out from
synchronism, and the APOS value remains (stalls) in one of the limits until the change of
MPOS allows following again.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.173.4 Example
5.174 acsc_Spline
The function initiates a single-axis spline motion. The motion follows an arbitrary path defined
by a set of points.
int acsc_Spline(HANDLE Handle, int Flags, int Axis, double Period,
ACSC_WAITBLOCK* Wait)
5.174.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
acsc_Go function is executed.
• ACSC_AMF_RELATIVE: use the coordinates of each point as
relative. The first point is relative to the instant position when the
motion starts; the second point is relative to the first, etc. If the flag
is not specified, the coordinates of each point are absolute.
• ACSC_AMF_VARTIME: the time interval between adjacent points
is non-uniform and is specified along with each added point. If the
flag is not specified, the interval is uniform and is specified in the
Period argument.
Period Time interval between adjacent points. The parameter is used only if
the ACSC_AMF_VARTIME flag is not specified.
5.174.3 Remarks
The function initiates a single-axis spline motion. To execute multi-axis spline motion, use
acsc_SplineM.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function cannot wait or validate the end of the motion. To wait for the motion
end, use the acsc_WaitMotionEnd function.
The motion does not use the default values of velocity, acceleration, deceleration, and jerk. The
points and the time intervals between the points completely define the motion profile.
Points for arbitrary path motion are defined by the consequent calls of acsc_AddPoint or
acsc_ExtAddPoint functions. The acsc_EndSequence function terminates the point sequence.
After execution of the acsc_EndSequence function, no acsc_AddPoint or acsc_ExtAddPoint
functions for this motion are allowed.
The trajectory of the motion follows through the defined points. Each point presents the instant
desired position at a specific moment. Time intervals between the points are uniform, or non-
uniform as defined by the ACSC_AMF_VARTIME flag.
This motion does not use a motion profile generation. The time intervals between the points are
typically short, so that the array of the points implicitly specifies the desired velocity in each
point.
If the time interval does not coincide with the controller cycle, the controller provides
interpolation of the points according to the ACSC_AMF_CUBIC flag.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.174.4 Example
5.175 acsc_SplineM
The function initiates a multi-axis spline motion. The motion follows an arbitrary path defined
by a set of points.
int acsc_SplineM(HANDLE Handle, int Flags, int* Axes, double Period,
ACSC_WAITBLOCK* Wait)
5.175.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
acsc_GoM function is executed.
• ACSC_AMF_RELATIVE: the coordinates of each point are
relative. The first point is relative to the instant position when the
motion starts; the second point is relative to the first, etc. If the flag
is not specified, the coordinates of each point are absolute.
• ACSC_AMF_VARTIME: the time interval between adjacent points
is non-uniform and is specified along with each added point. If the
flag is not specified, the interval is uniform and is specified in the
Period argument.
• ΑCSC_AMF_CYCLIC: the motion uses the point sequence as a
cyclic array: after the last point the motion comes to the first point
and continues.
Period Time interval between adjacent points. The parameter is used only if
the ACSC_AMF_VARTIME flag is not specified.
5.175.3 Remarks
The function initiates a multi-axis spline motion. To execute a single-axis spline motion, use
acsc_Spline.
The function can wait for the controller response or can return immediately as specified by the
Wait argument.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function cannot wait or validate the end of the motion. To wait for the motion
end, use the acsc_WaitMotionEnd function.
The motion does not use the default values of velocity, acceleration, deceleration, and jerk. The
points and the time intervals between the points define the motion profile completely.
Points for arbitrary path motion are defined by the consequent calls of the acsc_AddPointM or
acsc_ExtAddPointM functions. The acsc_EndSequenceM function terminates the point
sequence. After execution of the acsc_EndSequenceM function, no acsc_AddPointM or
acsc_ExtAddPointM functions for this motion are allowed.
The trajectory of the motion follows through the defined points. Each point presents the instant
desired position at a specific moment. Time intervals between the points are uniform, or non-
uniform as defined by the ACSC_AMF_VARTIME flag.
This motion does not use motion profile generation. Typically, the time intervals between the
points are short, so that the array of the points implicitly specifies the desired velocity in each
point.
If the time interval does not coincide with the controller cycle, the controller provides
interpolation of the points according to the ACSC_AMF_CUBIC flag.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.175.4 Example
Axes, // axes XY
10, // uniform interval 10 ms
NULL // waiting call
))
{
printf("transaction error: %d\n", acsc_GetLastError());
}
do
{
if(!acsc_AddPointM(Handle, Axes, Points, NULL))
ErrNum=acsc_GetLastError();
else
ErrNum=0;
}while(ErrNum==3065);
}
// finish the motion
acsc_EndSequenceM(Handle, Axes, NULL); // the end of arbitrary path motion
5.176 acsc_Split
The function breaks down an axis group created before.
5.176.1 Parameters
5.176.3 Remarks
The function breaks down an axis group created before by the acsc_Group function. The Axes
parameter must specify the same axes as for the acsc_Group function that created the group.
After the splitting up the group no longer exists.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.176.4 Example
5.177 acsc_SplitAll
The function breaks down all axis groups created before.
int acsc_SplitAll(HANDLE Handle, ACSC_WAITBLOCK* Wait)
5.177.1 Parameters
acsc_GetLastError.
5.177.3 Remarks
The function breaks down all axis groups created before by the acsc_Group function.
The application may call this function to ensure that no axes are grouped. If no groups are
currently existed, the function has no effect.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.177.4 Example
5.178 acsc_StopBuffer
The function stops the execution of ACSPL+ program in the specified buffer(s).
int acsc_StopBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait)
5.178.1 Parameters
5.178.3 Remarks
The function stops ACSPL+ program execution in the specified buffer or in all buffers if the
parameter Buffer is ACSC_NONE.
The function has no effect if the program in the specified buffer is not running.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.178.4 Example
5.179 acsc_StopCollect
The function terminates data collection.
int acsc_StopCollect(HANDLE Handle, ACSC_WAITBLOCK* Wait)
5.179.1 Parameters
5.179.3 Remarks
The usual system data collection finishes when the required number of samples is collected or
the acsc_StopCollect function is executed. The application can wait for data collection end
with the acsc_WaitCollectEnd function.
The temporal data collection runs until the acsc_StopCollect function is executed.
The function terminates the data collection prematurely. The application can determine the
number of actually collected samples from the S_DCN variable and the actual sampling period
from the S_DCP variable.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.179.4 Example
5.180 acsc_StopPeg
The function stops PEG.
int acsc_StopPeg(HANDLE Handle,int Axis, ACSC_WAITBLOCK* Wait)
5.180.1 Parameters
5.180.3 Remarks
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.180.4 Example
5.181 acsc_Stopper
The function provides a smooth transition between two segments of segmented motion.
int acsc_Stopper(HANDLE Handle, int* Axes, ACSC_WAITBLOCK* Wait)
5.181.1 Parameters
5.181.3 Remarks
The controller builds the motion so that the vector velocity follows the smooth velocity
diagram. The segments define the projection of the vector velocity to axis velocities. If all
segments are connected smoothly, axis velocity is also smooth. However, if the user defined a
path with an inflection point, axis velocity has a jump in this point. The jump can cause a motion
failure due to the acceleration limit.
The function is used to avoid velocity jump in the inflection points. If the function is specified
between two segments, the controller provides smooth deceleration to zero in the end of first
segment and smooth acceleration to specified velocity in the beginning of second segment.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.181.4 Example
5.182 acsc_SuspendBuffer
The function suspends the execution of ACSPL+ program in the specified program buffer(s).
int acsc_SuspendBuffer(HANDLE Handle, int Buffer, ACSC_WAITBLOCK* Wait)
5.182.1 Parameters
5.182.3 Remarks
The function suspends ACSPL+ program execution in the specified buffer or in all buffers if
the parameter Buffer is ACSC_NONE. The function has no effect if the program in the
specified buffer is not running.
To resume execution of the program in the specified buffer, call the acsc_RunBuffer function.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.182.4 Example
5.183 acsc_Track
The function initiates a single-axis track motion.
int acsc_Track(HANDLE Handle, int Flags, int Axis, ACSC_WAITBLOCK* Wait)
5.183.1 Parameters
5.183.3 Remarks
The function initiates a single-axis track motion. After the motion is initialized, ptp motion will
be generated with every change in TPOS value.
The controller response indicates that the command was accepted and the motion was planned
successfully.
5.183.4 Example
5.184 acsc_ToPoint
The function initiates a single-axis motion to the specified point.
int acsc_ToPoint(HANDLE Handle, int Flags, int Axis, double Point,
ACSC_WAITBLOCK* Wait)
5.184.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_Go is executed.
ACSC_AMF_RELATIVE: the Point value is relative to the end point
of the previous motion. If the flag is not specified, the Point specifies
an absolute coordinate.
5.184.3 Remarks
The function initiates a single-axis point-to-point motion.
The motion is executed using the required motion velocity and finishes with zero end velocity.
The required motion velocity is the velocity specified by the previous call of the
acsc_SetVelocity function or the default velocity if the function was not called.
To execute multi-axis point-to-point motion, use acsc_ToPointM. To execute motion with
other motion velocity or non-zero end velocity, use acsc_ToPoint or acsc_ExtToPointM.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function does not wait for the motion end. To wait for the motion end, use
acsc_WaitMotionEnd function.
The motion builds the velocity profile using the required values of velocity, acceleration,
deceleration, and jerk of the specified axis.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.184.4 Example
5.185 acsc_ToPointM
The function initiates a multi-axis motion to the specified point.
int acsc_ToPointM(HANDLE Handle, int Flags, int* Axes, double* Point,
ACSC_WAITBLOCK* Wait)
5.185.1 Parameters
Flags Bit-mapped parameter that can include one or more of the following
flags:
• ACSC_AMF_WAIT: plan the motion but don’t start it until the
function acsc_GoM is executed.
• ACSC_AMF_RELATIVE: the Point values are relative to the end
point of the previous motion. If the flag is not specified, the Point
specifies absolute coordinates.
• ACSC_AMF_MAXIMUM: not to use the motion parameters from
the leading axis but to calculate the maximum allowed motion
velocity, acceleration, deceleration, and jerk of the involved axes.
Point Array of the target coordinates. The number and order of values must
correspond to the Axes array. The Point must specify a value for each
element of Axes except the last –1 element.
5.185.3 Remarks
The function initiates a multi-axis point-to-point motion.
The motion is executed using the required motion velocity and finishes with zero end velocity.
The required motion velocity is the velocity specified by the previous call of the
acsc_SetVelocity function, or the default velocity if the function was not called.
To execute single-axis point-to-point motion, use acsc_ToPoint.To execute motion with other
motion velocity or non-zero end velocity, use acsc_ExtToPoint or acsc_ExtToPointM.
The controller response indicates that the command was accepted and the motion was planned
successfully. The function does not wait for the motion end. To wait for the motion end, use
acsc_WaitMotionEnd function.
The motion builds the velocity profile using the required values of velocity, acceleration,
deceleration, and jerk of the leading axis. The leading axis is the first axis in the Axes array.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.185.4 Example
5.186 acsc_Transaction
The function executes one transaction with the controller, i.e. it sends a command and receives
a controller response.
int acsc_Transaction (HANDLE Handle, char* OutBuf, int OutCount, char* InBuf, int
InCount, int* Received, ACSC_WAITBLOCK* Wait)
Note
Any ASCII command being sent to the controller must end with '\r' (13)
character, otherwise it won't be recognized as valid.
5.186.1 Parameters
5.186.3 Remarks
The full operation of transaction includes the following steps:
1. Send OutCount characters from OutBuf to the controller.
2. Waits until the controller response is received or the timeout occurs. In the case of timeout,
set Received to zero, store error value and return.
3. Store the controller response in InBuf. If the controller response is longer than InCount,
store only InCount characters.
4. Writes to Received the exact number of the characters stored in InBuf.
5. Analyzes the controller response, and set the error value if the response indicates an error.
If the Wait argument is NULL, the call is waiting and the function does not return until the full
operation is finished.
If the Wait argument points to a valid ACSC_WAITBLOCK structure, the call is non-waiting
and the function returns immediately after the first step. An internal library thread executes the
rest of the operation. The calling thread can validate if the operation finished and can retrieve
the operation result using the acsc_WaitForAsyncCall function.
5.186.4 Example
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘\0’;
printf("error: %s\n", buf);
}
}
else
{
printf("transaction error: %d\n", acsc_GetLastError());
}
5.187 acsc_UploadBuffer
The function uploads ACSPL+ program from the specified program buffer.
int acsc_UploadBuffer(HANDLE Handle, int Buffer, int Offset, char* Program, int
Count, int* Received, ACSC_WAITBLOCK* Wait)
5.187.1 Parameters
Offset Binary offset in the buffer that defines start point of uploading.
5.187.3 Remarks
The function uploads ACSPL+ program from the specified program buffer.
Uploading starts from the specified offset. The first uploaded character is character number
Offset in the program text. Uploading lasts until Count characters are uploaded or the end of
the program is achieved. The function assigns variable Received with a number of characters
that were actually uploaded. The value can be less than Count if the function failed or the end
of the program is achieved.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Text, Received and Wait items until a call to the acsc_WaitForAsyncCall function.
5.187.4 Example
5.188 acsc_WaitCollectEnd
The function waits for the end of data collection.
int acsc_WaitCollectEnd(HANDLE Handle, int Timeout)
5.188.1 Parameters
5.188.3 Remarks
The function does not return while the system data collection is in progress and the specified
time-out interval has not elapsed. The function verifies the S_ST.#DC system flag.
5.188.4 Example
5.189 acsc_WaitForAsyncCall
The function waits for completion of asynchronous call and retrieves a data.
int acsc_WaitForAsyncCall(HANDLE Handle, void* Buf, int* Received,
ACSC_WAITBLOCK* Wait, int Timeout)
5.189.1 Parameters
5.189.3 Remarks
The function waits for completion of asynchronous call, corresponds to the Wait parameter,
and retrieves controller response to the buffer pointed by Buf. The Wait and Buf must be the
same pointers passed to SPiiPlus C function when asynchronous call was initiated.
If the call of SPiiPlus C function was successful, the function retrieves controller response to
the buffer Buf. The Received parameter will contain the number of actually received
characters.
If the call of SPiiPlus C function does not return a response (for example: acsc_Enable,
acsc_Jog, etc.) Buf has to be NULL.
If the call of SPiiPlus C function returned the error, the function retrieves this error code in the
Ret member of the Wait parameter.
If the SPiiPlus C function has not been completed in Timeout milliseconds, the function aborts
specified asynchronous call and returns ACSC_TIMEOUT error.
If the call of SPiiPlus C function has been aborted by the acsc_CancelOperation function, the
function returns ACSC_OPERATIONABORTED error.
5.189.4 Example
5.190 acsc_WaitInput
The function waits for the specified state of digital input.
int acsc_WaitInput (HANDLE Handle, int Port, int Bit, int State, int Timeout)
5.190.1 Parameters
5.190.3 Remarks
The basic configuration of the SPiiPlus PCI model provides only 16 inputs. Therefore, the Port
must be 0, and the Bit can be specified from 0 to 15.
5.190.4 Example
5.191 acsc_WaitLogicalMotionEnd
The function waits for the logical end of a motion.
int acsc_WaitLogicalMotionEnd (HANDLE Handle, int Axis, int Timeout)
5.191.1 Parameters
5.191.3 Remarks
The function does not return while the specified axis is involved in a motion and the specified
time-out interval has not elapsed.
The function differs from the acsc_WaitMotionEnd function. Examining the same motion, the
acsc_WaitMotionEnd function will return later. The acsc_WaitLogicalMotionEnd function
returns when the generation of the motion finishes. On the other hand, the
acsc_WaitMotionEnd function returns when the generation of the motion finishes and the
motor has settled in the final position.
5.191.4 Example
5.192 acsc_WaitMotionEnd
The function waits for the end of a motion.
int acsc_WaitMotionEnd (HANDLE Handle, int Axis, int Timeout)
5.192.1 Parameters
5.192.3 Remarks
The function does not return while the specified axis is involved in a motion, the motor has not
settled in the final position and the specified time-out interval has not elapsed.
The function differs from the acsc_WaitLogicalMotionEnd function. Examining the same
motion, the acsc_WaitMotionEnd function will return latter. The
acsc_WaitLogicalMotionEnd function returns when the generation of the motion finishes. On
the other hand, the acsc_WaitMotionEnd function returns when the generation of the motion
finishes and the motor has settled in the final position.
5.192.4 Example
5.193 acsc_WaitMotorEnabled
The function waits for the specified state of the specified motor.
int acsc_WaitMotorEnabled (HANDLE Handle, int Axis, int State, int Timeout)
5.193.1 Parameters
5.193.3 Remarks
The function does not return while the specified motor is not in the desired state and the
specified time-out interval has not elapsed. The function examines the MST.#ENABLED
motor flag.
5.193.4 Example
5.194 acsc_WaitProgramEnd
The function waits for the program termination in the specified buffer.
int acsc_WaitProgramEnd (HANDLE Handle, int Buffer, int Timeout)
5.194.1 Parameters
5.194.3 Remarks
The function does not return while the ACSPL+ program in the specified buffer is in progress
and the specified time-out interval has not elapsed.
5.194.4 Example
5.195 acsc_WaitUserCondition
The function waits for the user-defined condition.
int acsc_WaitUserCondition(HANDLE Handle, ACSC_USER_CONDITION_FUNC
UserCondition, int Timeout)
5.195.1 Parameters
5.195.3 Remarks
The function calls the UserCondition function in order to determine the termination moment.
While the UserCondition function returns zero and the specified time-out interval has not
elapsed, the acsc_WaitUserCondition function calls UserCondition periodically. Once the
UserCondition function returns non-zero results, the acsc_WaitUserCondition function also
returns.
The UserCondition function accepts as argument the Handle parameter, passed to the function
acsc_WaitUserCondition.
If the condition is satisfied, the UserCondition function returns 1, if it is not satisfied – 0. In
case of an error the UserCondition function returns –1.
5.195.4 Example
5.196 acsc_WriteInteger
The function writes value(s) to integer variable.
int acsc_WriteInteger(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, int* Values, ACSC_WAITBLOCK* Wait)
5.196.1 Parameters
5.196.3 Remarks
The function writes to a specified integer variable or array.
The variable can be a standard controller variable, user global or user local.
Standard and user global variables have global scope. Therefore, parameter Nbuf must be
ACSC_NONE (-1) for these classes of variables.
User local variable exists only within a buffer. The buffer number must be specified for user
local variable.
If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE (-1). The
function writes the value pointed by Values to the specified variable.
If the variable is a one-dimensional array, From1, To1 must specify the index range and
From2, To2 must be ACSC_NONE (-1). Array Values must contain To1-From1+1 values at
least. The function writes the values to the specified variable from index From1 to index To1
inclusively.
If the variable is a two-dimensional array, From1, To1 must specify the index range of the first
dimension and From2, To2 must specify the index range of the second dimension. Array
Values must contain (To1-From1+1)x(To2-From2+1) values at least. The function uses the
Values array as follows: first, the function retrieves the Values elements from 0 to To2-From2
and writes them to row From1 of the specified controller variable, then retrieves the Values
elements from To2-From2+1 to 2*(To2-From2)+1 and writes them to row From1+1 of the
specified controller variable, etc.
If Wait points to a valid ACSC_WAITBLOCK structure, the calling thread must not use or
delete the Wait item until a call to the acsc_WaitForAsyncCall function.
5.196.4 Example
5.197 acsc_WriteLogFile
The function writes to log file.
int acsc_WriteLogFile(HANDLE Handle, char* Buf, int Count)
5.197.1 Parameters
Buf Pointer to the buffer that contains the string to be written to log file.
5.197.3 Remarks
The function writes data from a buffer to log file. The log file should be previously opened by
the function acsc_OpenLogFile.
The function adds its arguments to the internal UMD binary buffer. In previous C Library
versions, the log file had to be explicitly opened by the function acsc_OpenLogFile, otherwise
the function would return an error. Starting with C Library version 5.0, this is no longer the case.
See, acsc_FlushLogFile.
5.197.4 Example
5.198 acsc_WriteReal
The function writes value(s) to the real variable.
int acsc_WriteReal(HANDLE Handle, int NBuf, char* Var, int From1, int To1, int
From2, int To2, double* Values, ACSC_WAITBLOCK* Wait)
5.198.1 Parameters
5.198.3 Remarks
The function writes to the specified real variable or array.
The variable can be a standard controller variable, user global or user local.
Standard and user global variables have global scope. Therefore, parameter Nbuf must be
ACSC_NONE (-1) for these classes of variables.
User local variable exists only within a buffer. The buffer number must be specified for user
local variable.
If the variable is scalar, all indexes From1, To1, From2, To2 must be ACSC_NONE (-1). The
5.198.4 Example
5.199 acsc_WriteDPRAMInteger
The function writes 32-bit integer to the DPRAM.
acsc_WriteDPRAMInteger(HANDLE Handle, int address,int Value)
5.199.1 Parameters
5.199.3 Remarks
Address has to be even number in the range of 128 to 508, because we use 16-bit alignment
when working with DPRAM. Addresses less than 128 are used for internal purposes.
Note
The function can be used only with the PCI and Simulator
communication channels.
5.199.4 Example
5.200 acsc_WriteDPRAMReal
The function writes 64-bit Real to the DPRAM.
acsc_WriteDPRAMReal(HANDLE Handle, int address, double Value)
5.200.1 Parameters
5.200.3 Remarks
Address has to be even number in the range of 128 to 504, because we use 16-bit alignment
when working with DPRAM. Addresses less than 128 are used for internal purposes.
Note
The function can be used only with the PCI and Simulator
communication channels.
5.200.4 Example
Note
Any error code greater than 1000 is a controller error defined in the
SPiiPlus ACSPL+ Programmer’s Guide.
ACSC_STOPPED_RESPONDING 198 The controller does not reply for more than 20
seconds.
Returned by any function that exchanges data
with the controller.
Check the following:
• Controller is powered on (MPU LED is
green)
• Controller connected properly to host
• Controller executes a time consuming
command like compilation of a large
program, save to flash, load to flash, etc.
ACSC_DLL_UMD_VERSION 199 The DLL and the UMD versions are not
compatible.
Returned by one of the acsc_OpenComm
functions.
Verify that the files ACSCL.DLL and
ACSCSRV.EXE are of the same version.
7 Constants
7.1 General
Table 41 General Constants
Constant Value Description
ACSC_INVALID -1 Invalid communication handle
ACSC_NONE -1 Placeholder for redundant values,
like the second index in a one-
dimensional array
ACSC_IGNORE 0xFFFFFFFF Used for non-waiting calls with
neglect of operation results
ACSC_INT_TYPE 1 Integer type of the variable
ACSC_REAL_TYPE 2 Real type of the variable
ACSC_MAX_LINE 100000 Maximum number of lines in the
program buffer
ACSC_COUNTERCLOCKWISE 1 Counterclockwise rotation
ACSC_CLOCKWISE -1 Clockwise rotation
ACSC_POSITIVE_DIRECTION 1 A move in positive direction
ACSC_NEGATIVE_DIRECTION -1 A move in negative direction
Note
See the SPiiPlus ACSPL+ Programmer’s Guide for detailed
explanations of faults.
8 Structures
8.1 ACSC_WAITBLOCK
The structure is used for non-waiting calls of the SPiiPlus C functions.
struct ACSC_WAITBLOCK { HANDLE Event; int Ret; };
8.1.1 Members
8.1.2 Remarks
To initiate non-waiting call the user thread declares the ACSC_WAITBLOCK structure and
passes the pointer to this structure to SPiiPlus C function as parameter. When a thread activates
a non-waiting call, the library passes the request to an internal thread that sends the command
to the controller and then monitors the controller responses. When the controller responds to the
command, the internal thread stores the response in the internal buffer. The calling thread can
retrieve the response with help of the acsc_WaitForAsyncCall function and validate the Ret.
The error codes stored in Ret are the same that the acsc_GetLastError function returns.
8.2 ACSC_PCI_SLOT
The structure defines a physical location of PCI card. This structure is used in the
acsc_GetPCICards function and contains the information about detected PCI card.
struct ACSC_PCI_SLOT { unsigned int BusNumber; unsigned int SlotNumber; unsigned
int Function; };
8.2.1 Members
8.2.2 Remarks
The SlotNumber can be used in the acsc_OpenCommPCI call in order to open
communication with a specific card. Other members have no use in SPiiPlus C Library.
8.3 ACSC_HISTORYBUFFER
The structure defines a state of the history and message buffers. This structure is used by the
acsc_OpenHistoryBuffer and acsc_OpenMessageBuffer functions.
struct ACSC_HISTORYBUFFER { int Max; int Cur; int Ring; char* Buf};
8.3.1 Members
Table 58 ACSC History Buffer Members
Type Name Description
int Max Buffer size
int Cur Number of bytes currently stored in the buffer
int Ring Circular index in the buffer
char Buf Pointer to the buffer
8.3.2 Remarks
Max is equal to the requested Size and never changes its value.
Cur is a number of bytes currently stored in the buffer. From the beginning, Cur is zero, then
grows up to Max, and then remains unchanged.
Ring is a circular index in the buffer: if the buffer is full, the most recent byte is stored in
position Ring-1, the earliest byte is stored in position Ring.
The user program must never change the members in the structure or write to the history buffer.
However, the user program can read the structure and the buffer directly. If doing so, the user
should be aware that the library includes a separate thread that watches the replies from the
controller. For this reason the contents of the buffer and structure members can change
asynchronously to the user thread.
9 Enums
9.1 ACSC_LOG_DETALIZATION_LEVEL
This enum is used for setting log file parameters in function acsc_SetLogFileOptions.
typedef enum ACSC_LOG_DETALIZATION_LEVEL{Minimum,Medium,Maximum};
9.1.1 Members
Table 59 ACSC Log Detalization Level Members
Type Name Description
int Minimum Value 0: Minumum information
int Medium Value 1: Medium information
int Maximum Value 2: Maximum information
9.2 ACSC_LOG_DATA_PRESENTATION
This enum is used for setting log file parameters in function acsc_SetLogFileOptions.
typedef enum ACSC_LOG_DATA_PRESENTATION {Compact,Formatted,Full};
9.2.1 Members
10 Sample Programs
The following samples demonstrate the usage of the SPiiPlus C Library functions. The
examples show how to write the C/C++ applications that can communicate with the SPiiPlus
controller.
The samples open the communication with the controller or the simulator and perform some
simple tasks, like starting of a point-to-point motion, reading of a motor feedback position,
downloading an ACSPL+ program to the controller program buffer, etc.
After installation of the package in the SPiiPlus C Library directory, the full source code of
these samples with the projects for Visual C++® 5 and Visual C++ 6 can be found.
10.1.1 ACSPL+
The sample shows how to open communication with the simulator or with the controller (via
serial, ethernet or PCI Bus), how to download the ACSPL+ program to controller's buffer, and
how to execute it. The ACSPL+ program executes a reciprocated point-to-point motion.
File ACSPL.CPP:
#include <conio.h>
#include <stdio.h>
#include "windows.h"
#include "C:\Program Files\ACS Electronics\SB1218 Tools\ACSC\acsc.h"
HANDLE hComm; // communication handle
void ErrorsHandler(const char* ErrorMessage, BOOL fCloseComm)
{
printf (ErrorMessage);
printf ("press any key to exit.\n");
if (fCloseComm) acsc_CloseComm(hComm);
_getch();
};
int main(int argc, char *argv[])
{
double FPOS;
// ACSPL+ program which we download to controller's buffer
// The program performs a reciprocated motion from position 0 to 4000
// and then back
char* prog = " enable X \r\n\
St: \r\n \
ptp X, 4000 \r\n\
ptp X, 0 \r\n \
goto St \r\n \
stop \r\n ";
printf ("ACS-Tech80 Ltd. Copyright (C) 2000. All Rights \
Reserved.\n");
printf ("Application executes reciprocated point-to-point motion\n");
/*****************************************************************/
// Open communication with simulator
printf ("Application opens communication with the simulator, \
downloads\n");
printf ("program to controller's and executes it using SPiiPlus C
Library \
functions\n\n");
printf ("Wait for opening of communication with the simulator...\n");
hComm = acsc_OpenCommDirect();
if (hComm == ACSC_INVALID)
{
ErrorsHandler("error while opening communication.\n", FALSE);
return -1;
}
printf ("Communication with the simulator was established \
successfully!\n");
/*****************************************************************/
/********************************************************************
// Example of opening communication with the controller via COM1
printf ("Application opens communication with the controller via \
COM1, downloads\n");
printf ("program to the controller and executes it using SPiiPlus C \
Library functions\n\n");
printf ("Wait for opening of communication with the \
controller...\n");
controller...\n");
hComm = acsc_OpenCommPCI(ACSC_NONE);
if (hComm == ACSC_INVALID)
{
ErrorsHandler("error while opening communication.\n", FALSE);
return -1;
}
printf ("Communication with the controller was established \
successfully!\n");
/*****************************************************************/
_getch();
while (!_kbhit())
{
// read the feedback position of axis X
if (acsc_GetFPosition(hComm, ACSC_AXIS_X, &FPOS, NULL))
{
printf ("%f\r", FPOS);
}
Sleep(500);
}
return 0;
}
10.1.2 Immediate
The sample shows how to open communication with the simulator or with the controller (via
serial, ethernet or PCI Bus) and how to execute a reciprocated point-to-point motion only by
calling appropriate SPiiPlus C functions without any ACSPL+ program.
File IMMEDIATE.CPP:
#include <conio.h>
#include <stdio.h>
#include "windows.h"
#include "C:\Program Files\ACS Electronics\SB1218 Tools\ACSC\acsc.h"
HANDLE hComm; // communication handle
while (!_kbhit())
{
// execute point-to-point motion to position 4000
if (!acsc_ToPoint(hComm, 0, ACSC_AXIS_X, 4000, NULL))
{
ErrorsHandler("PTP motion error.\n", TRUE);
return -1;
}
printf ("Moving to the position 4000...\n");
// execute backward point-to-point motion to position 0
if (!acsc_ToPoint(hComm, 0, ACSC_AXIS_X, 0, NULL))
{
ErrorsHandler("PTP motion error.\n", TRUE);
return -1;
}
printf ("Moving back to the position 0...\n");