SPiiPlus MATLAB 

Library

Programmer's Guide
April 2021
Document Revision: 3.10
 SPiiPlus MATLAB Library Programmer's Guide

SPiiPlus MATLAB Library

Release Date: April 2021

COPYRIGHT

© ACS Motion Control Ltd., 2021. All rights reserved.

Changes are periodically made to the information in this document. Changes are published as release notes and later
incorporated into 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, SPiiPlus, PEG, MARK, ServoBoost, NetworkBoost and NanoPWN are trademarks of ACS Motion Control Ltd.

EtherCAT is registered trademark and patented technology, licensed by Beckhoff Automation GmbH, Germany.

Any other companies and product names mentioned herein may be the trademarks of their respective owners.

www.acsmotioncontrol.com

[email protected]

[email protected]

NOTICE

The information in this document is deemed to be correct at the time of publishing. ACS Motion Control reserves the right to
change specifications without notice. ACS Motion Control is not responsible for incidental, consequential, or special damages of
any kind in connection with using this document.

Version 3.10 2
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

1. Revision History
Date Revision Description

Removed enumeration value reserved for internal use

December 2020 3.10
only

September
3.02 Add DataCollectionExt and DataCollectionExtAsync
2020

July 2020 3.01 SDK Update

May 2018 2.60 First release

Version 3.10 3
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

Conventions Used in this Guide

Text Formats

Format Description

Bold Names of GUI objects or commands

BOLD + UPPERCASE ACSPL+ variables and commands

Monospace + grey background Code example

Italic Names of other documents

Blue Hyperlink

[] In commands indicates optional item(s)

| In commands indicates either/or items

Flagged Text

Note - includes additional information or programming tips.

Caution - describes a condition that may result in damage to equipment.

Warning - describes a condition that may result in serious bodily injury or

death.

Model - highlights a specification, procedure, condition, or statement that

depends on the product model

Advanced - indicates a topic for advanced users.

Version 3.10 4
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

Related Documents
Documents listed in the following table provide additional information related to this document.
The most updated version of the documents can be downloaded by authorized users from ACS
Downloads.

Version 3.10 5
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

Table of Contents
1. Revision History 3
2. General Information 19
2.1 General 19
2.2 Operating Environment 19
2.3 Communication Channels 19
2.4 Controller Simulation 19
2.5 Installation and Supplied Components 19
2.6 Asynchronous Calls Support 19
2.6.1 GetResult 20
2.7 Standard (SPiiPlus C Library) Features 20
2.8 Specific MATLAB Library Features 21
2.9 Communication Scenarios 22
3. Using the SPiiPlus MATLAB Library 24
3.1 Redistribution 24
3.2 MathWorks® MATLAB® 24
4. Methods 25
4.1 Communication Methods 26
4.1.1 Structures 27
4.1.1.1 ACSC_CONNECTION_DESC 27
4.1.1.2 ACSC_PCI_SLOT 27
4.1.1.3 ACSC_CONNECTION_INFO 27
4.1.2 Enumerations 28
4.1.2.1 ACSC_CONNECTION_TYPE 28
4.1.3 CancelOperation 28
4.1.4 Command 29
4.1.5 CloseComm 30
4.1.6 FlushLogFile 30
4.1.7 GetConnectionsList 31
4.1.8 GetEthernetCards 31
4.1.9 GetPCICards 32
4.1.10 OpenCommSimulator 33
4.1.11 OpenCommEthernetTCP 33

Version 3.10 6
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.1.12 OpenCommEthernetUDP 34
4.1.13 OpenCommPCI 34
4.1.14 OpenCommSerial 35
4.1.15 GetConnectionInfo 36
4.1.16 SetServerExtLogin 36
4.1.17 TerminateConnection 37
4.1.18 Transaction 38
4.2 EtherCAT® Methods 39
4.2.1 GetEtherCATState 39
4.2.2 GetEtherCATError 40
4.2.3 MapEtherCATInput 42
4.2.4 MapEtherCATOutput 43
4.2.5 UnmapEtherCATInputsOutputs 44
4.2.6 GetEtherCATSlaveIndex 44
4.2.7 GetEtherCATSlaveOffset 45
4.2.8 GetEtherCATSlaveVendorID 46
4.2.9 GetEtherCATSlaveProductID 46
4.2.10 GetEtherCATSlaveRevision 47
4.2.11 GetEtherCATSlaveType 48
4.2.12 GetEtherCATSlaveState 49
4.3 Service Communication Methods 49
4.3.1 GetACSCHandle 50
4.3.2 GetNETLibraryVersion 51
4.3.3 GetCommOptions 51
4.3.4 GetDefaultTimeout 52
4.3.5 GetErrorString 52
4.3.6 GetLibraryVersion 53
4.3.7 GetTimeout 54
4.3.8 SetIterations 54
4.3.9 SetCommOptions 55
4.3.10 SetTimeout 55
4.3.11 SetQueueOverflowTimeout 56
4.3.12 GetQueueOverflowTimeout 56
4.4 ACSPL+ Program Management Methods 57

Version 3.10 7
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.4.1 AppendBuffer 57
4.4.2 ClearBuffer 58
4.4.3 CompileBuffer 59
4.4.4 LoadBuffer 60
4.4.5 LoadBuffersFromFile 61
4.4.6 RunBuffer 62
4.4.7 StopBuffer 63
4.4.8 SuspendBuffer 64
4.4.9 UploadBuffer 65
4.5 Read and Write Variables Methods 66
4.5.1 ReadVariable 66
4.5.2 ReadVariableAsScalar 71
4.5.3 ReadVariableAsVector 73
4.5.4 ReadVariableAsMatrix 76
4.5.5 WriteVariable 78
4.6 History Buffer Management Methods 83
4.6.1 OpenHistoryBuffer 84
4.6.2 CloseHistoryBuffer 84
4.6.3 GetHistory 85
4.7 Unsolicited Messages Buffer Management Methods 86
4.7.1 OpenMessageBuffer 86
4.7.2 CloseMessageBuffer 87
4.7.3 GetSingleMessage 87
4.8 Log File Management Methods 88
4.8.1 SetLogFileOptions 88
4.8.2 OpenLogFile 89
4.8.3 CloseLogFile 90
4.8.4 WriteLogFile 90
4.8.5 GetLogData 91
4.9 SPiiPlusSC Log File Management Methods 92
4.9.1 OpenSCLogFile 92
4.9.2 CloseSCLogFile 93
4.9.3 WriteSCLogFile 93
4.9.4 FlushSCLogFile 93

Version 3.10 8
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.10 Shared Memory Methods 94

4.10.1 GetSharedMemoryAddress 94
4.10.2 ReadSharedMemoryInteger 95
4.10.3 ReadSharedMemoryReal 95
4.10.4 WriteSharedMemoryVariable 96
4.10.5 Shared Memory Program Example 96
4.11 System Configuration Methods 97
4.11.1 SetConf 97
4.11.2 GetConf 98
4.11.3 GetVolatileMemoryUsage 99
4.11.4 GetVolatileMemoryTotal 100
4.11.5 GetVolatileMemoryFree 100
4.11.6 GetNonVolatileMemoryUsage 101
4.11.7 GetNonVolatileMemoryTotal 102
4.11.8 GetNonVolatileMemoryFree 102
4.12 Setting and Reading Motion Parameters Methods 103
4.12.1 SetVelocity 104
4.12.2 SetVelocityImm 105
4.12.3 GetVelocity 106
4.12.4 SetAcceleration 107
4.12.5 SetAccelerationImm 108
4.12.6 GetAcceleration 109
4.12.7 SetDeceleration 110
4.12.8 SetDecelerationImm 111
4.12.9 GetDeceleration 112
4.12.10 SetJerk 113
4.12.11 SetJerkImm 113
4.12.12 GetJerk 114
4.12.13 SetKillDeceleration 115
4.12.14 SetKillDecelerationImm 116
4.12.15 GetKillDeceleration 117
4.12.16 SetFPosition 118
4.12.17 GetFPosition 119
4.12.18 SetRPosition 119

Version 3.10 9
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.12.19 GetRPosition 120

4.12.20 GetFVelocity 121
4.12.21 GetRVelocity 122
4.13 Axis/Motor Management Methods 122
4.13.1 Commut 123
4.13.2 Enable 124
4.13.3 EnableM 125
4.13.4 Disable 126
4.13.5 DisableAll 126
4.13.6 DisableExt 127
4.13.7 DisableM 128
4.13.8 Group 129
4.13.9 Split 130
4.13.10 SplitAll 131
4.14 Motion Management Methods 132
4.14.1 Go 132
4.14.2 GoM 133
4.14.3 Halt 134
4.14.4 HaltM 136
4.14.5 Kill 137
4.14.6 KillAll 138
4.14.7 KillM 139
4.14.8 KillExt 140
4.14.9 Break 141
4.14.10 BreakM 143
4.15 Point-to-Point Motion Methods 144
4.15.1 ToPoint 144
4.15.2 ToPointM 146
4.15.3 ExtToPoint 147
4.15.4 ExtToPointM 149
4.16 Track Motion Control Method 151
4.16.1 Track 152
4.16.2 SetTargetPosition 153
4.16.3 GetTargetPosition 154

Version 3.10 10
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.17 Jog Methods 155

4.17.1 Jog 155
4.17.2 JogM 157
4.18 Slaved Motion Methods 158
4.18.1 SetMaster 159
4.18.2 Slave 160
4.18.3 SlaveStalled 162
4.19 Multi-Point Motion Methods 164
4.19.1 MultiPoint 164
4.19.2 MultiPointM 166
4.20 Arbitrary Path Motion Methods 167
4.20.1 Spline 168
4.20.2 SplineM 170
4.21 PVT Methods 172
4.21.1 AddPVPoint 172
4.21.2 AddPVPointM 173
4.21.3 AddPVTPoint 175
4.21.4 AddPVTPointM 176
4.22 Segmented Motion Methods 178
4.22.1 ExtendedSegmentedMotionExt 178
4.22.2 SegmentLine 183
4.22.3 SegmentArc1 185
4.22.4 SegmentArc2 188
4.22.5 Stopper 191
4.22.6 Projection 193
4.23 Points and Segments Manipulation Methods 194
4.23.1 AddPoint 195
4.23.2 AddPointM 196
4.23.3 ExtAddPoint 197
4.23.4 ExtAddPointM 199
4.23.5 EndSequence 200
4.23.6 EndSequenceM 201
4.24 Data Collection Methods 202
4.24.1 DataCollectionExt 203

Version 3.10 11
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.24.2 StopCollect 204

4.25 Status Report Methods 206
4.25.1 GetMotorState 206
4.25.2 GetAxisState 207
4.25.3 GetIndexState 207
4.25.4 ResetIndexState 208
4.25.5 GetProgramState 210
4.26 Inputs/Outputs Access Methods 210
4.26.1 GetInput 211
4.26.2 GetInputPort 212
4.26.3 GetOutput 213
4.26.4 GetOutputPort 214
4.26.5 SetOutput 215
4.26.6 SetOutputPort 215
4.26.7 GetAnalogInputNT 216
4.26.8 GetAnalogOutputNT 217
4.26.9 SetAnalogOutputNT 218
4.26.10 GetExtInput 219
4.26.11 GetExtInputPort 220
4.26.12 GetExtOutput 220
4.26.13 GetExtOutputPort 221
4.26.14 SetExtOutput 222
4.26.15 SetExtOutputPort 223
4.27 Safety Control Methods 224
4.27.1 GetFault 225
4.27.2 SetFaultMask 226
4.27.3 GetFaultMask 227
4.27.4 EnableFault 228
4.27.5 DisableFault 229
4.27.6 SetResponseMask 230
4.27.7 GetResponseMask 231
4.27.8 EnableResponse 232
4.27.9 DisableResponse 233
4.27.10 GetSafetyInput 234

Version 3.10 12
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.27.11 GetSafetyInputPort 235

4.27.12 SetSafetyInputPortInv 237
4.27.13 FaultClear 238
4.27.14 FaultClearM 239
4.28 Wait-for-Condition Methods 240
4.28.1 WaitMotionEnd 240
4.28.2 WaitLogicalMotionEnd 241
4.28.3 WaitCollectEnd 241
4.28.4 WaitProgramEnd 242
4.28.5 WaitMotorCommutated 243
4.28.6 WaitMotorEnabled 243
4.28.7 WaitInput 244
4.29 Event and Interrupt Handling Methods 245
4.29.1 EnableEvent 245
4.29.2 DisableEvent 246
4.29.3 SetInterruptMask 247
4.29.4 GetInterruptMask 248
4.30 Variables Management Methods 250
4.30.1 DeclareVariable 250
4.30.2 ClearVariables 251
4.31 Service Methods 251
4.31.1 GetFirmwareVersion 252
4.31.2 GetSerialNumber 252
4.31.3 SysInfo 253
4.31.4 GetBuffersCount 253
4.31.5 GetAxesCount 254
4.31.6 GetDBufferIndex 254
4.31.7 GetUMDVersion 255
4.32 Error Diagnosis Methods 256
4.32.1 GetMotorError 256
4.32.2 GetMotionError 257
4.32.3 GetProgramError 257
4.33 Position Event Generation (PEG) Methods 258
4.33.1 AssignPegNT 259

Version 3.10 13
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.33.2 AssignPegOutputsNT 260

4.33.3 AssignFastInputsNT 261
4.33.4 PegIncNT 262
4.33.5 PegRandomNT 263
4.33.6 WaitPegReadyNT 265
4.33.7 StartPegNT 265
4.33.8 StopPegNT 266
4.34 Application Save/Load Methods 266
4.34.1 Structures and Classes 267
4.34.1.1 ApplicationFileInfo 267
4.34.1.2 ACSC_APPSL_SECTION 267
4.34.1.3 ACSC_APPSL_ATTRIBUTE 268
4.34.1.4 ACSC_APPSL_STRING 268
4.34.2 Enumerations 268
4.34.2.1 ACSC_APPSL_FILETYPE 268
4.34.3 AnalyzeApplication 269
4.34.4 LoadApplication 269
4.34.5 SaveApplication 270
4.34.6 FreeApplication 271
4.35 Load/Upload Data To/From Controller Methods 271
4.35.1 LoadDataToController 271
4.35.2 UploadDataFromController 273
4.36 Emergency Stop Methods 275
4.36.1 RegisterEmergencyStop 276
4.36.2 UnregisterEmergencyStop 277
4.37 Reboot Methods 277
4.37.1 ControllerReboot 277
4.37.2 ControllerFactoryDefault 278
4.38 Host-Controller File Operations 278
4.38.1 CopyFileToController 279
4.38.2 DeleteFileFromController 279
4.39 Save to Flash Functions 280
4.39.1 ControllerSaveToFlash 280
4.40 SPiiPlusSC Management 281

Version 3.10 14
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

4.40.1 StartSPiiPlusSC 282

4.40.2 StopSPiiPlusSC 282
5. Enumerations 283
5.1 General Definitions 283
5.2 General Communication Options 283
5.3 Ethernet Communication Options 284
5.4 Axis Definitions 284
5.5 Buffer Definitions 284
5.6 Servo Processor (SP) Definitions 285
5.7 EtherCAT Flags 285
5.8 Motion Flags 285
5.9 Data Collection Flags 288
5.10 Motor State Flags 288
5.11 Axis State Flags 289
5.12 Index and Mark State Flags 289
5.13 Program State Flags 290
5.14 Safety Control Masks 291
5.15 Interrupt Types 292
5.16 Callback Interrupt Masks 294
5.17 Configuration Keys 294
5.18 System Information Keys 295
5.19 Representation, Variables and Return Types Definitions 296
5.20 Log Detalization and Presentation Definitions 297
6. Events 298
7. Error Handling 299
7.1 Error Handling Example in C# 299
7.2 Error Codes 299

Version 3.10 15
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

List of Tables
Table 3-1. Communication Methods 26
Table 3-2. EtherCAT Methods 39
Table 3-3. EtherCAT States 40
Table 3-4. EtherCAT Error Codes 41
Table 3-5. Service Communication Methods 50
Table 3-6. ACSPL+ Program Management Methods 57
Table 3-7. Read and Write Variables Methods 66
Table 3-8. Value Dimension Indices 80
Table 3-9. History Buffer Management Methods 83
Table 3-10. Unsolicited Messages Buffer Management Methods 86
Table 3-11. Log File Management Methods 88
Table 3-12. SPiiPlusSC Log File Management Methods 92
Table 3-13. Shared Memory Methods 94
Table 3-14. System Configuration Methods 97
Table 3-15. Setting and Reading the Motion Parameters Methods 103
Table 3-16. Axis/Motor Management Methods 123
Table 3-17. Motion Management Methods 132
Table 3-18. Point-to-Point Motion Methods 144
Table 3-19. Track Motion Control Method 151
Table 3-20. Jog Methods 155
Table 3-21. Slaved Motion Methods 158
Table 3-22. Multi-Point Motion Methods 164
Table 3-23. Arbitrary Path Motion Methods 168
Table 3-24. PVT Methods 172
Table 3-25. Segmented Motion Methods 178
Table 3-26. Points and Segments Manipulation Methods 194
Table 3-27. Data Collection Methods 202
Table 3-28. Status Report Methods 206
Table 3-29. Inputs/Outputs Access Methods 211
Table 3-30. Safety Control Methods 224
Table 3-31. Wait-for-Condition Methods 240

Version 3.10 16
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

Table 3-32. Event and Interrupt Handling Methods 245

Table 3-33. Variables Management Methods 250
Table 3-34. Service Methods 251
Table 3-35. Error Diagnosis Methods 256
Table 3-36. Non-NT Position Event Generation (PEG) Methods 258
Table 3-37. Application Save/Load Methods 266
Table 3-38. Load/Upload Data To/From Controller Methods 271
Table 3-39. Emergency Stop Methods 275
Table 3-40. Reboot Methods 277
Table 3-41. Host-Controller File Copying Methods 279
Table 3-42. Save to Flash Methods 280
Table 3-43. SPiiPlusSC Management Methods 281
Table 4-1. GeneralDefinitions 283
Table 4-2. General Communication Options 283
Table 4-3. Ethernet Communication Options 284
Table 4-4. EtherCAT Flags 285
Table 4-5. Motion Flags 286
Table 4-6. Rotation Directrion Flags 287
Table 4-7. Global Directrion Flags 288
Table 4-8. Data Collection Flags 288
Table 4-9. Motor State Flags 288
Table 4-10. Axis State Flags 289
Table 4-11. Index and Mark State Flags 290
Table 4-12. Program State Flags 290
Table 4-13. Safety Control Masks 291
Table 4-14. Interrupt Types 292
Table 4-15. Callback Interrupt Axis Masks 294
Table 4-16. Configuration Keys 294
Table 4-17. System Information Keys 295
Table 4-18. Return Types 296
Table 4-19. ACSPL+ Variables Types 296
Table 4-20. Representation Types 296
Table 4-21. Log Detalization Definitions 297
Table 4-22. Log Presentation Definitions 297

Version 3.10 17
 SPiiPlus MATLAB Library Programmer's Guide
1.   Revision History

Table 5-1. Events and Interrupts 298

Table 6-1. NET Library Error Codes 299

Version 3.10 18
 SPiiPlus MATLAB Library Programmer's Guide
2.   General Information

2. General Information
2.1 General
The SPiiPlus MATLAB Library provides the easiest way to incorporate SPiiPlus motion control
functionality.

2.2 Operating Environment

> Windows 7 SP1 (x86 and x64)
> Windows 8 (x86 and x64)
> Windows 8.1 (x86 and x64)
> Windows 10
> Windows Server 2008 R2 SP1 (x64)
> Windows Server 2012 R2 (x64)
> Windows Server 2016 R2 (x64)
> Windows Server 2019 (x64)

Windows XP and Windows Server 2003 are no longer supported.

The SPiiPlus MATLAB Library supports MathWorks® MATLAB® R2011b (v7.12) and later.

2.3 Communication Channels

The SPiiPlus MATLAB Library supports all communication channels provided by SPiiPlus motion
controllers:
> Serial (RS-232)
> Ethernet (point-to-point and network)

2.4 Controller Simulation

The SPiiPlus MATLAB Library supports communication with a SPiiPlus Controller Simulator. The
SPiiPlus Controller Simulator emulates a controller, enabling program debugging and
demonstrations without a connection to a physical controller.

2.5 Installation and Supplied Components

The SPiiPlus MATLAB Library depends on SPiiPlus .NET library.

2.6 Asynchronous Calls Support

The SPiiPlus MATLAB Library provides an ability of asynchronous operations. Each method that
supports asynchronous mode has compliment method with Async postfix. These async methods

Version 3.10 19
 SPiiPlus MATLAB Library Programmer's Guide
2.   General Information

return ACSC_WAITBLOCK object that can be used to wait for operation completion and receive
operation results.

2.6.1 GetResult
Description
The method returns the result of a previous asynchronous call.
Syntax
result = object.Getresult(waitblock, timeout)
Arguments

Waitblock ACSC_WAITBLOCK structure returned by Async method.

Timeout Number of milliseconds to wait for result.

Return Value

Object representing result of a previous asynchronous call, that can be further

Result
cast to specific MATLAB type, if necessary.

Remarks
To get a result of a previous asynchronous call GetResult method should be used. It receives the
wait block returned by async function and a timeout for wait operation. The return value of
GetResult method is .NET object that can be further cast to string, int or double type, according to
asynchronous function called.
If the method fails, the Error object is filled with the error description.
Example

%Get controller serial number asynchronuously

wb = Ch.TransactionAsync('?SN');
reply = GetResult(wb, 2000);

2.7 Standard (SPiiPlus C Library) Features

The SPiiPlus MATLAB Library provides the same standard features as the SPiiPlus C Library (see
SPiiPlus C Library Reference), including:
> Unified support for all communication channels (Serial and Ethernet)
All SPiiPlus MATLAB Library methods except the OpenCommxxx methods are identical for all
communication channels. A (host computer) user application doesn't require any other
modification to work with different communication channels.
> Controller simulator communication channel
All SPiiPlus MATLAB Library methods support the SPiiPlus Controller Simulator. The user
client 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.
> Concurrent support for up to 10 communication channels in one application

Version 3.10 20
 SPiiPlus MATLAB Library Programmer's Guide
2.   General Information

One user client application can open up to ten communication channels simultaneously.
Different communication channels are usually connected to different controllers.
However, two or more communication channels can be connected to the same controller.
For example, an application can communicate with a controller through both the
controller's Ethernet channel and its serial channels.
> Acknowledgement for each command sent to the controller
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.
> Communication history
The SPiiPlus MATLAB Library enables storage in a memory buffer of all messages sent to,
and received from, the controller. The application can retrieve data from the buffer and
can clear the buffer.
> Separate processing of unsolicited messages
Most messages sent from the controller to the host are responses to host commands.
However, the controller can send unsolicited messages, for example, as output from a
DISP command. The library separates the unsolicited messages from the overall message
flow and provides a special method for handling unsolicited messages.
> Rich functionality
The MATLAB library supports setting and reading parameters, advanced motion control,
program management, I/O, safety, and more.
> Debug tools
The SPiiPlus MATLAB Library provides 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.

2.8 Specific MATLAB Library Features

The SPiiPlus MATLAB Library supports the following features:
> Generating events for predefined controller events
The SPiiPlus MATLAB Library generates events for the user client application if one of the
following events occurs:
> Emergency Stop signal has been generated
> Motion has ended
> Motion has been interrupted due to a fault
> Motor has been disabled due to a fault
> ACSPL+ program in the controller has completed
> User-defined event with passed pareameters by INTERRUPTEX command
> Other events

Version 3.10 21
 SPiiPlus MATLAB Library Programmer's Guide
2.   General Information

2.9 Communication Scenarios

One user application can open up to 10 communication channels simultaneously through the
SPiiPlus MATLAB Library. Usually the application opens different communication channels to work
with different controller at the same time.
The following communication scenarios are typical for application development.
> Application works with one controller through one communication channel
Application creates communication channel object, opens communication and then uses
any SPiiPlus MATLAB Library methods. Before closing the application closes communication
and then destroys the communication channel object.

%create communication object

channel = SPiiPlusMatlab;
%open connection (simulator)
channel.OpenCommSimulator;
%get axis position
pos = channel.GetFPosition(AxisDefs.ACSC_AXIS_1);

%close communication
channel.CloseComm; 

> Application works with several controllers by turns. Only one communication channel is
open at the same time
Application creates communication channel object, opens communication with first
controller and then uses any SPiiPlus MATLAB Library methods. When the application
needs to connect to the second controller, it closes the previous communication and then
opens new a communication. In this case the application uses the same communication
channel object for each controller.
Before closing the application closes communication, then destroys communication
channel.

%create communication object

channel = SPiiPlusMatlab;
%open connection (simulator)
channel.OpenCommSimulator;
%get axis position
pos = channel.GetFPosition(AxisDefs.ACSC_AXIS_1);
 channel.CloseComm;
%open connection (serial)
handle = channel.OpenCommSerial(1, 115200);
%get axis position
pos = channel.GetFPosition(AxisDefs.ACSC_AXIS_0);

%close communication
channel.CloseComm;

> Application works with several controllers at the same time

Version 3.10 22
 SPiiPlus MATLAB Library Programmer's Guide
2.   General Information

In this case the application needs to open several communication channel objects, one for
each controller. Then for each communication channel it opens communication with
different controllers. Before closing the application closes all communications, then
destroys all communication channels.

%create communication object

channel1 = SPiiPlusMatlab;
channel2 = SPiiPlusMatlab;
channel3 = SPiiPlusMatlab;

%open connections
channel1.OpenCommSimulator;
channel2.OpenCommSerial(1, 115200);
channel3.OpenCommPCI(10);
%get axis position
pos1 = channel1.GetFPosition(AxisDefs.ACSC_AXIS_1);
pos2 = channel2.GetFPosition(AxisDefs.ACSC_AXIS_2);
pos3 = channel3.GetFPosition(AxisDefs.ACSC_AXIS_3);
%close communication
channel1.CloseComm;
channel2.CloseComm;
channel3.CloseComm;

Version 3.10 23
 SPiiPlus MATLAB Library Programmer's Guide
3.   Using the SPiiPlus MATLAB Library

3. Using the SPiiPlus MATLAB Library

This chapter describes how to use the SPiiPlus MATLAB Library and provides examples of how to
call SPiiPlus MATLAB methods from MathWorks® MATLAB®.

3.1 Redistribution

SPiiPlus MATLAB Library is installed automatically by the SPiiPlus ADK Suite installation.

3.2 MathWorks® MATLAB®

1. Open MathWorks® MATLAB® Application
2. Navigate with “Current Folder” explorer to parent folder containing “SPiiPlusMatlab” folder.
3. Click right click on “SPiiPlusMatlab” folder and choose from context menu option “Add to
Path -> Selected Folders and Subfolders”. Alternatively, it is possible to use “addpath()”
standard method. See more details about “addpath()” method in MATLAB documentation.
channel = SPiiPlusMatlab;
4. Now you can call SPiiPlus MATLAB Library methods. For example,
channel.OpenCommPCI(-1);

Version 3.10 24
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4. Methods
This chapter details the methods available in the SPiiPlus MATLAB Library. Each method contains of
following documentation structure:
> Brief description
> Syntax in the form of: object.method_name(argument, argument, …), where object is a
placeholder for a valid object name, and each argument is of the form:  argument_name.
> Description of the arguments and their function.
> Return Value
> Remarks
> Example - A short MATLAB code example.
The methods are broken down into the following categories:
> Communication Methods
> EtherCAT® Methods
> Service Communication Methods
> ACSPL+ Program Management Methods
> Read and Write Variables Methods
> History Buffer Management Methods
> Unsolicited Messages Buffer Management Methods
> Log File Management Methods
> SPiiPlusSC Log File Management Methods
> Shared Memory Methods
> System Configuration Methods
> Setting and Reading Motion Parameters Methods
> Axis/Motor Management Methods
> Motion Management Methods
> Point-to-Point Motion Methods
> Track Motion Control Method
> Jog Methods
> Slaved Motion Methods
> Multi-Point Motion Methods
> Arbitrary Path Motion Methods
> PVT Methods
> Segmented Motion Methods
> Points and Segments Manipulation Methods

Version 3.10 25
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

> Data Collection Methods

> Status Report Methods
> Inputs/Outputs Access Methods
> Safety Control Methods
> Wait-for-Condition Methods
> Event and Interrupt Handling Methods
> Variables Management Methods
> Service Methods
> Error Diagnosis Methods
> Position Event Generation (PEG) Methods
> Application Save/Load Methods
> Load/Upload Data To/From Controller Methods
> Emergency Stop Methods
> Reboot Methods

4.1 Communication Methods

SPiiPlus MATLAB Communication methods are as follows:
Table 3-1. Communication Methods

Method Description

CancelOperation Cancels all operations.

Sends a command to the controller and analyzes the controller

Command
response.

CloseComm Closes communication (for all kinds of communication).

Allows flushing the User-Mode Driver (UMD) internal binary

FlushLogFile
buffer to a specified text file, from a user application.

GetConnectionInfo Retrieves the details of opened communication channel.

Retrieves all currently opened on active server connections and

GetConnectionsList
its details.

GetEthernetCards Retrieves all SPiiPlus controller IP addresses within a local domain.

GetPCICards Retrieves information about the installed SPiiPlus PCI cards.

The Communication methods employ the following structures:

Version 3.10 26
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.1.1 Structures
The Communication methods employ the following structures:

4.1.1.1 ACSC_CONNECTION_DESC
Description
This structure describes the connection information.
Syntax
ACSC_CONNECTION_DESC(application, handle, processId)
Members

Application Application Name

handle Channel’s handle

ProcessId Application process ID

4.1.1.2 ACSC_PCI_SLOT
Description
This structure defines a physical location of PCI card.
Syntax
ACSC_PCI_SLOT(busNumber, slotNumber, func)
Members

BusNumber PCI physical bus number of card

SlotNumber PCI physical slot number of card

Function PCI function of card

4.1.1.3 ACSC_CONNECTION_INFO
Description
This structure provides information about specified controller connection for an application. Used in
the GetConnectionInfo method.
Syntax
ACSC_CONNECTION_INFO(type, serialPort, serialBaudRate, pCISlot,
ethernetProtocol, ethernetIP, ethernetPort)
Members

Type Connection Type

Communication channel of serial communication: 1

SerialPort
corresponds to COM1, 2 – to COM2, etc.

Version 3.10 27
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Communication rate of serial communication in bits per second

SerialBaudRate
(baud).

PCISlot Number of the PCI slot of the controller card.

EthernetProtocol Ethernet protocol

Contains the network address of the controller in symbolic or

EthernetIP
TCP/IP dotted form.

EthernetPort Service port.

4.1.2 Enumerations
The Communication methods employ the following enums:

4.1.2.1 ACSC_CONNECTION_TYPE
Description
This enum is used for setting communication type. Used in the GetConnectionInfo method.
Values

ACSC_NOT_CONNECTED Value 0: Not Connected

ACSC_SERIAL Value 1: Serial Communication

ACSC_PCI Value 2: PCI Communication

ACSC_ETHERNET Value 3: Ethernet Communication

ACSC_DIRECT Value 4: Direct (Simulator) Communication

4.1.3 CancelOperation
Description
This method cancels asynchronous (non-waiting) call.
Syntax
object.CancelOperation(wb);

ACSC_WAITBLOCK object returned by invocation of asynchronous call that needed

wb
to be canceled

Return Value
None.
Remarks
The method waits for the controller response. If the method fails, the Error object is filled with the
error description.

Version 3.10 28
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

% Shutdown all motors

wb = Ch.DisableAllAsync;
% Cancel shutdown
Ch.CancelOperation(wb);

4.1.4 Command
Description
The method sends a command to the controller and analyzes the controller response.
Syntax
object.Command(commandName);
Async Syntax
wb = object.CommandAsync(commandName);
Arguments

commandName The command to be sent.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call

Remarks
The method sends a vector of characters containing one or more ACSPL+ commands to the
controller. The method verifies that the controller receives the command but does not return the
controller response. The method is intended for commands where the controller response does
not include any information except the prompt.

For commands where the controller response includes some information, use
Transaction.

Example

%Executed controller’s command

Ch.Command('enable 0');

%Executed controller’s command asynchronously

wb = Ch.CommandAsync('enable 0');

Version 3.10 29
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.1.5 CloseComm
Description
The method closes communication via the specified communication channel.
Syntax
object.CloseComm;
Arguments
None
Return Value
None.
Remarks
The method closes the communication channel and releases all system resources related to the
channel. If the method closes communication with the Simulator, it also terminates the Simulator.
Each OpenComm*** (for example, OpenCommSerial) call in the application must be followed at
some time with a CloseComm call in order to return the resources to the system.
If the method fails, the Error object is filled with the error description.
Example

%Closes the communication channel

Ch.CloseComm;

4.1.6 FlushLogFile
Description
The method allows flushing the User-Mode Driver (UMD) internal binary buffer to a specified text
file, from a user application.
Syntax
object.FlushLogFile(fileName);
Arguments

Vector of characters specifying the text file into which the buffer is to be
fileName
flushed

Return Value
None.
Remarks
If Continuous Log is active, the function will fail.
Example

%Flush UMD buffer to file

Ch.FlushLogFile('C:\\log.txt');

Version 3.10 30
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.1.7 GetConnectionsList
Description
This method retrieves all currently opened connections on active server and their details.
Syntax
connectionsList = object.GetConnectionsList;
Arguments
None
Return Value

Array of ACSC_CONNECTION_DESC structures representing

connections description array. Array length equal to number of
connectionsList
active connections found or zero if there are no connections on
active server.

Remarks
Each connection is described by its handle, application name and process ID, therefore, all
arguments will have the same size and order, after the method returns.
This method can be used to check if there are some unused connections that remain from
applications that did not close the communication channel or were not gracefully closed
(terminated or killed).
Each returned connection can be terminated only by the TerminateConnection method.
Using any method of the SetServer family makes previously returned connections irrelevant
because it changes the active server.
Example

%Get active connections list, find application by name and terminate its
connection
name = 'neededApplication.exe';
connectionList = Ch.GetConnectionsList;
for i=1:length(connectionList)
if strcmp(name, connectionList(i).Application)

Ch.TerminateConnection( connectionList(i));
end
end

4.1.8 GetEthernetCards
Description
The method retrieves all SPiiPlus controller IP addresses within a local domain through a standard
Ethernet communication protocol.

Version 3.10 31
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
ethernetCards = object.GetEthernetCards(broadcast);
Arguments

broadcast IP address for broadcasting. Normally has to be IPAddress.Broadcast.

Return Value

Cell array of IP addresses of found SPiiPlus cards or empty array if no

ethernetCards cards are detected.

Example

% Example call GetThernetCards

ethernetCards = Ch.GetEthernetCards('255.255.255.255');
disp(ethernetCards);

4.1.9 GetPCICards
Description
This method retrieves information about the controller cards inserted in the computer PCI Bus.
Syntax
pciCards = object.GetPCICards;
Arguments
None
Return Value

Array of ACSC_PCI_SLOT structures, where each array element

pciCards
belongs to found card

Remarks
If no controller cards are detected, the method returns empty array, otherwise method fills the
array with information about the detected cards.
The slotNumber member of ACSC_PCI_SLOT. SlotNumber can be used in the OpenCommPCI call to
open communication with a specific card.
If the method fails, the Error object is filled with the error description.
Example

% Example call GetPCICards

pciCards = Ch.GetPCICards;
for i=1:length(pciCards)
disp(pciCards(i));
end

Version 3.10 32
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.1.10 OpenCommSimulator
Description
The method starts up the Simulator and opens communication with the Simulator.
Syntax
object.OpenCommSimulator;
Arguments
None.
Return Value
None.
Remarks
The Simulator is a part of the SPiiPlus MATLAB Library. When the application calls
OpenCommSimulator, 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  MATLAB method works with the Simulator exactly as with a
physical controller.
If the method fails, the Error object is filled with the error description.
Example

%Starts up the Simulator and opens communication with the Simulator

Ch.OpenCommSimulator;

4.1.11 OpenCommEthernetTCP
Description
The method opens communication with the controller via Ethernet using the TCP protocol.
Syntax
object.OpenCommEthernetTCP(address, port)
Arguments

Vector of characters that contains the network address of the controller in

address
symbolic or TCP/IP dotted form.

port Scalar representing the service port.

Return Value
None.
Remarks
After a channel is open, any SPiiPlus MATLAB method works with the channel irrespective of the
physical nature of the channel.

Version 3.10 33
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Use TCP protocol if the host computer is connected to the controller through the multi-node
Ethernet network.
If the method fails, the Error object is filled with the error description.
Example

%Open Ethernet with TCP protocol communication with the controller

ip = '10.0.0.100';
port = 701; %ACSC_SOCKET_STREAM_PORT
Ch.OpenCommEthernetTCP(ip, port);

4.1.12 OpenCommEthernetUDP
Description
The method opens communication with the controller via Ethernet using the UDP protocol.
Syntax
object.OpenCommEthernetUDP(address, port);
Arguments

Vector of characters that contains the network address of the controller in

address
symbolic or TCP/IP dotted form.

port Scalar representing the service port.

Return Value
None.
Remarks
After a channel is open, any SPiiPlus MATLAB method works with the channel irrespective of the
physical nature of the channel.
Use UDP protocol if the host computer has a point-to-point Ethernet connection to the controller.
If the method fails, the Error object is filled with the error description.
Example

%Open Ethernet with UDP protocol communication with the controller

ip = '10.0.0.100';
port = 700; %ACSC_SOCKET_DGRAM_PORT
Ch.OpenCommEthernetUDP(ip, port);

4.1.13 OpenCommPCI
Description
The method 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.

Version 3.10 34
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
object.OpenCommPCI(slotNumber);
Arguments

Number of the slot of the controller card. If slotNumber is zero, the

slotNumber
method opens communication with the first found controller card.

Return Value
None.
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 MATLAB method works with the channel irrespective of the
physical nature of the channel.
If the method fails, the Error object is filled with the error description.
Example

%Open communication with the first found controller card

Ch.OpenCommPCI(0);

4.1.14 OpenCommSerial
Description
The method opens communication with the controller via a serial port.
Syntax
object.OpenCommSerial(channel, rate);
Arguments

channel Communication channel: 1 corresponds to COM1, 2 – to COM2, etc.

Communication rate in bits per second (baud).

This parameter must be equal to the controller variable IOBAUD for the
rate
successful link with the controller.
By passing -1, the method will automatically determine the baud rate.

Return Value
None.
Remarks
After a channel is open, any SPiiPlus COM method works with the channel irrespective of the
physical nature of the channel.
If the method fails, the Error object is filled with the error description.

Version 3.10 35
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Open serial communication through port COM1 with baud rate 115200
Ch.OpenCommSerial(1, 115200);

4.1.15 GetConnectionInfo
Description
The method is used to retrieve the details of opened communication channel.
Syntax
connInfo = object.GetConnectionInfo;
Arguments
None
Return Value

connInfo ACSC_CONNECTION_INFO structure

Example

%Get connection info

connInfo = Ch.GetConnectionInfo;
fprintf('IP: %s\n', connInfo.EthernetIP);
fprintf('Ethernet Port: %d\n', connInfo.EthernetPort);
fprintf('Ethernet Protocol: %d\n', connInfo.EthernetProtocol);
fprintf('PCI Slot: %d\n', connInfo.PCISlot);
fprintf('Serial Baud Rate: %d\n', connInfo.SerialBaudRate);
fprintf('Serial Port: %d\n', connInfo.SerialPort);

4.1.16 SetServerExtLogin
Description
The method sets the remote User-Mode Driver (UMD) with a specified IP address, port number, and
user login.
Syntax
object.SetServerExtLogin(iP, port, username, password, domain);
Arguments

Vector of characters representing IP address of the remote

iP UMD. This address should be the same address displayed in the
remote UMD dialog.

port Scalar representing Scalar representing Remote service port

Vector of characters representing User name on the remote

username
host.

Version 3.10 36
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Vector of characters representing Password on the remote

password
host.

Vector of characters representing Domain name on the

domain
remote host.

Return Value
None.
Remarks
The method sets the remote UMD with the specified IP address, port number, and user login
information. User login information is required if the remote UMD does not run in the current
domain, or the remote computer was not previously logged in to the current domain.
Example

%Example call SetServerExtLogin

Ch.SetServerExtLogin('127.0.0.1', 9999, 'username', 'pass', 'domain');

4.1.17 TerminateConnection
Description
This method terminates specified communication channel (connection) on active server.
Syntax
object.TerminateConnection(connection);
Arguments

Connection description (ACSC_CONNECTION_DESC) structure obtained

connection
through call to GetConnectionsList method.

Return Value
None
Remarks
This method can be used to terminate connections that remain from applications that did not close
the communication channel or were not gracefully closed (terminated or killed).
Using any method of the SetServer family makes previously returned connections list irrelevant
because it changes active server, and obligates new call of GetConnectionsList.
Example

%Get active connections list , find application by name and terminate

%its connection
name = 'neededApplication.exe';
connectionList = Ch.GetConnectionsList;
for i=1:length(connectionList)

Version 3.10 37
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

if ( strcmp(name, connectionList(i).Application) )

Ch.TerminateConnection( connectionList(i) );
end
end

4.1.18 Transaction
Description
The method executes one transaction with the controller, i.e., it sends a command and receives a
controller response.
Syntax
response = object.Transaction(command);
Async Syntax
wb = object.TransactionAsync(command);
Arguments

command Vector of characters representing command to be sent.

Return Value

response Vector of characters representing controller response.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The full operation of transaction includes the following steps:
1. Send Command to the controller.
2. Wait until the controller response is received or the timeout occurs.
3. Return a controller response.
4. If the method fails, the Error object is filled with the error description.
Example

%Get controller serial number

cmd = '?SN';
%The method executes one transaction
reply = Ch.Transaction(cmd);
%The method executes one transaction asynchronuously
wb = Ch.TransactionAsync(cmd);
reply = GetResult(wb, 2000);

Version 3.10 38
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.2 EtherCAT® Methods

The EtherCAT methods are:
Table 3-2. EtherCAT Methods

Method Description

GetEtherCATState Retrieves the EtherCAT state.

GetEtherCATError Retrieves the last EtherCAT error code.

MapEtherCATInput Maps network input variables.

MapEtherCATOutput Maps network output variables.

UnmapEtherCATInputsOutputs Cancels mapping of input or output variables.

GetEtherCATSlaveIndex Retrieves index of specified EtherCAT slave.

GetEtherCATSlaveOffset Retrieves offset of specified EtherCAT slave.

GetEtherCATSlaveVendorID Retrieves Vendor IDof specified EtherCAT slave.

GetEtherCATSlaveProductID Retrieves Prodct ID of specified EtherCAT slave.

GetEtherCATSlaveRevision Retrieves revision of specified EtherCAT slave.

GetEtherCATSlaveType Retrieves type of specified EtherCAT slave.

GetEtherCATSlaveState Retrieves EtherCAT state of specified EtherCAT slave.

4.2.1 GetEtherCATState
Description
The method is used to retrieve the EtherCAT state.
Syntax
ethercatFlags = object.GetEtherCATState;
Async Syntax
wb = object.GetEtherCATStateAsync;
Arguments
None
Return Value

ethercatFlags See Table 3-3.

Version 3.10 39
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The EtherCAT State contained in the variable designated by the State argument is defined by the
following bits:
Table 3-3. EtherCAT States

Bit Name Description

0 #SCAN The scan process was performed successfully.

1 #CONFIG There is no deviation between XML and actual setup.

2 #INITOK All bus devices are successfully set to INIT state.

3 #CONNECTED Indicates valid Ethernet cable connection to the master.

If DCM is used, indicates synchronization between master

4 #INSYNC
and the bus.

5 #OP The EtherCAT bus is operational.

All bits (except #INSYNC in some cases) should be true for proper bus functioning. When monitoring
the bus state, checking bit #OP is enough. Any bus error will reset the #OP bit.
Example

%Example call GetEtherCATState

ethercatFlags = Ch.GetEtherCATState;

%Example asynchronuos call GetEtherCATState

wb = Ch.GetEtherCATStateAsync;

4.2.2 GetEtherCATError
Description
The method is used to retrieve the last EtherCAT error code.
Syntax
etherCATError = object.GetEtherCATError;
Async Syntax
wb = object.GetEtherCATErrorAsync;
Arguments
None

Version 3.10 40
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value

etherCATError Scalar value representing EtherCAT error defined in Table 3-4.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The EtherCAT error codes are:
Table 3-4. EtherCAT Error Codes

Error Description

6000 General EtherCAT Error

6001 EtherCAT cable not connected

6002 EtherCAT master is in incorrect State

6003 Not all EtherCAT frames can be processed

6004 EtherCAT Slave Error

6005 EtherCAT initialization failure

6006 EtherCAT can't complete the operation

6007 EtherCAT work count error

6008 Not all EtherCAT slaves are in the OP State

6009 EtherCAT protocol timeout

6010 Slave initialization failed

6011 Bus configuration mismatch

Example

%Example call GetEtherCATError

etherCatError = Ch.GetEtherCATError;

%Example asynchronuos call GetEtherCATState

wb = Ch.GetEtherCATErrorAsync;

Version 3.10 41
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.2.3 MapEtherCATInput
Description
The method is used for raw mapping of network input variables of any size. Once the method is
called successfully, the firmware copies the value of the network input variable at the
corresponding EtherCAT offset into the ACSPL+ variable every controller cycle.

The method call is legal only when the EtherCAT State is OP.

Syntax
object.MapEtherCATInput(flags, offset, variableName);
Async Syntax
wb = object.MapEtherCATInputAsync(flags, offset, variableName);
Arguments

flags MotionFlags parameter. Currently should be ACSC_NONE.

Scalar representing internal EtherCAT offset of network input variable.

Should be taken from the response to the #ETHERCAT command in
offset
the SPiiPlus MMI Application Studio Communication Terminal or can be
seen via System Setup.

Vector of characters representing a valid name of ACSPL+ variable,

variableName
global or standard.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example
In the following example, network variable of EtherCAT node 0 at offset 43 is being mapped to the
global variable: I0.

flags = MotionFlags.ACSC_NONE;
offset = 43;
varName = 'l0';

%Example synchronous call MapEtherCATInput

Ch.MapEtherCATInput(flags, offset, varName);
%Example asynchronous call MapEtherCATInput
wb = Ch.MapEtherCATInputAsync(flags, offset, varName);

Version 3.10 42
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.2.4 MapEtherCATOutput
Description
The method is used for raw mapping of network output variables of any size. Once the method is
called successfully, the firmware copies the value of specified ACSPL+ variable into the network
output variable at the corresponding EtherCAT offset, during every controller cycle.

The method call is legal only when the EtherCAT State is OP.

Syntax
object.MapEtherCATOutput(flags, offset, variableName);
Async Syntax
wb = object.MapEtherCATOutputAsync(flags, offset, variableName);
Arguments

flags MotionFlags parameter. Currently should be ACSC_NONE.

Scalar representing internal EtherCAT offset of network input variable.

Should be taken from the response to the #ETHERCAT command in
offset
the SPiiPlus MMI Application Studio Communication Terminal or can be
seen via System Setup.

Vector of characters representing a valid name of ACSPL+ variable,

variableName
global or standard.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example
In the following example, network variable of EtherCAT node 0 at offset 26 is being mapped to
global variable: I1.

flags = MotionFlags.ACSC_NONE;
offset = 26;
varName = 'l1';

%Example synchronous call MapEtherCATInput

Ch.MapEtherCATInput(flags, offset, varName);
%Example asynchronous call MapEtherCATInput
wb = Ch.MapEtherCATInputAsync(flags, offset, varName);

Version 3.10 43
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.2.5 UnmapEtherCATInputsOutputs
Description
The method resets all previous mapping defined by MapEtherCATInput and MapEtherCATOutput
methods.

The method call is legal only when the EtherCAT State is OP.

Syntax
object.UnmapEtherCATInputsOutputs;
Async Syntax
wb = object.UnmapEtherCATInputsOutputsAsync;
Arguments
None
Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Example synchronous call UnmapEtherCATInputsOutputs

Ch.UnmapEtherCATInputsOutputs;
%Example asynchronous call UnmapEtherCATInputsOutputs
wb = Ch.UnmapEtherCATInputsOutputsAsync;

4.2.6 GetEtherCATSlaveIndex
Description
The method retrieves the index of an EtherCAT slave according to provided parameters.
Syntax
index = object.GetEtherCATSlaveIndex(vendorID, productID, count);
Async Syntax
wb = object.GetEtherCATSlaveIndexAsync(vendorID, productID, count);
Arguments

vendorID Scalar representing EtherCAT Vendor ID of the desired slave.

productID Scalar representing EtherCAT Product ID of the desired slave.

Version 3.10 44
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Scalar representing Internal count of devices with the same Product and
count
Vendor IDs.

Return Value

index Scalar representing index of an EtherCAT slave.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

vendorID = 2;
productID = 270807122;
count = 0;

%Example synchronous call GetEtherCATSlaveIndex

index = Ch.GetEtherCATSlaveIndex(vendorID, productID, count);
%Example asynchronous call GetEtherCATSlaveIndex
wb = Ch.GetEtherCATSlaveIndexAsync(vendorID, productID, count);

index = Ch.GetResult()

4.2.7 GetEtherCATSlaveOffset
Description
The method retrieves the offset of a network variable of a specified EtherCAT slave in EtherCAT
telegram.
Syntax
offset = object.GetEtherCATSlaveOffset(variableName, slaveIndex);
Async Syntax
wb = object.GetEtherCATSlaveOffsetAsync(variableName, slaveIndex);
Arguments

Vector of characters representing name of the EtherCAT

variableName
network variable.

Scalar representing index of the required EtherCAT slave, which

slaveIndex can be determined by using the GetEtherCATSlaveIndex
method.

Return Value

offset Scalar representing offset of a network variable.

Version 3.10 45
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

varName = 'Output';
slaveIndex = 3;

%Example synchronous call GetEtherCATSlaveOffset

index = Ch.GetEtherCATSlaveOffset(varName, slaveIndex);
%Example asynchronous call GetEtherCATSlaveOffset
wb = Ch.GetEtherCATSlaveOffsetAsync(varName, slaveIndex);
index = GetResult(wb, 2000);

4.2.8 GetEtherCATSlaveVendorID
Description
The method retrieves the Vendor ID of a specified EtherCAT slave.
Syntax
venID = object.GetEtherCATSlaveVendorID(slaveIndex);
Async Syntax
wb = object.GetEtherCATSlaveVendorIDAsync(slaveIndex);
Arguments

Scalar representing index of the desired EtherCAT slave, which can be

slaveIndex
determined by using the GetEtherCATSlaveIndex method.

Return Value

venID Scalar representing the Vendor ID.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

slaveIndex = 3;

%Example synchronous call GetEtherCATSlaveVendorID

index = Ch.GetEtherCATSlaveVendorID(slaveIndex);
%Example asynchronous call GetEtherCATSlaveVendorID
wb = Ch.GetEtherCATSlaveVendorIDAsync(slaveIndex);

4.2.9 GetEtherCATSlaveProductID
Description
The method retrieves the Product ID of a specified EtherCAT slave.

Version 3.10 46
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
prodID = object.GetEtherCATSlaveProductID(slaveIndex);
Async Syntax
wb = object.GetEtherCATSlaveProductID(int slaveIndex);
Arguments

Scalar representing index of the desired EtherCAT slave, which can be

slaveIndex
determined by using the GetEtherCATSlaveIndex method.

Return Value

prodID Scalar representing the Product ID.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

slaveIndex = 3;

%Example synchronous call GetEtherCATSlaveProductID

index = Ch.GetEtherCATSlaveProductID(slaveIndex);
%Example asynchronous call GetEtherCATSlaveProductID
wb = Ch.GetEtherCATSlaveProductIDAsync(slaveIndex);

4.2.10 GetEtherCATSlaveRevision
Description
The method retrieves the revision of a specified EtherCAT slave.
Syntax
revision = object.GetEtherCATSlaveRevision (slaveIndex);
Async Syntax
wb = object.GetEtherCATSlaveRevisionAsync (slaveIndex);
Arguments

Scalar representing  index of the desired EtherCAT slave, which can be

slaveIndex
determined by using the GetEtherCATSlaveIndex method.

Return Value

revision Scalar representing the revision number.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 47
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

slaveIndex = 3;

%Example synchronous call GetEtherCATSlaveRevision

index = Ch.GetEtherCATSlaveRevision(slaveIndex);
%Example asynchronous call GetEtherCATSlaveRevision
wb = Ch.GetEtherCATSlaveRevisionAsync(slaveIndex);

4.2.11 GetEtherCATSlaveType
Description
The method retrieves the type of a specified EtherCAT slave.
Syntax
type = object.GetEtherCATSlaveType(vendorID, productID);
Async Syntax
wb = object.GetEtherCATSlaveTypeAsync(vendorID, productID);
Arguments

vendorID Scalar representing   a vendor ID of the EtherCAT slave.

productID Scalar representing   a product ID of the EtherCAT slave.

Return Value

type Scalar representing  a received type

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks:
The type of specified EtherCAT slave. The value can be one of the following:
> 0 – ACS device
> 1 – Non-ACS Servo
> 2 – Non-ACS Stepper
> 3 – Non-ACS I/O
> -1 – Device not found at slave index
Example

vendorID = 2;
productID = 270807122;

%Example synchronous call GetEtherCATSlaveType

Version 3.10 48
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

index = Ch.GetEtherCATSlaveType(vendorID, productID);

%Example asynchronous call GetEtherCATSlaveType
wb = Ch.GetEtherCATSlaveTypeAsync(vendorID, productID);

4.2.12 GetEtherCATSlaveState
Description
The method retrieves the EtherCAT state of a specified EtherCAT slave.
Syntax
state = object.GetEtherCATSlaveState (slaveIndex);
Async Syntax
wb = object.GetEtherCATSlaveProductID(slaveIndex);
Arguments

Scalar representing index of the desired EtherCAT slave, which can be

slaveIndex
determined by using the GetEtherCATSlaveIndex method.

Return Value

state Scalar representing a received state.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks:
Returns the state of specified EtherCAT slave.The value can be one of the following:
> 1 – INIT
> 2 – PREOP
> 4 – SAFEOP
> 8 – OP
> -1 – Device not found at slave index
Example

slaveIndex = 3;

%Example synchronous call GetEtherCATSlaveState

index = Ch.GetEtherCATSlaveState(slaveIndex);
%Example asynchronous call GetEtherCATSlaveState
wb = Ch.GetEtherCATSlaveStateAsync(slaveIndex);

4.3 Service Communication Methods

The Service Communication methods are:

Version 3.10 49
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Table 3-5. Service Communication Methods

Method Description

GetACSCHandle Retrieves the SPiiPlus C Library communication handle

GetNETLibraryVersion Retrieves the SPiiPlus MATLAB Library version number.

GetCommOptions Retrieves the communication options.

GetDefaultTimeout Retrieves default communication timeout.

GetErrorString Retrieves the explanation of an error code.

GetLibraryVersion Retrieves the legacy SPiiPlus C Library version number.

GetTimeout Retrieves communication timeout.

SetIterations Sets the number of iterations of one transaction.

SetCommOptions Sets the communication options.

SetTimeout Sets communication timeout.

4.3.1 GetACSCHandle
Description
The method retrieves the SPiiPlus C Library communication handle.
Syntax
handle = object.GetACSCHandle;
Arguments
None.
Return Value

handle Scalar representing the SPiiPlus C Library communication handle.

Remarks
The method retrieves the SPiiPlus C Library communication handle. If the method fails, the Error
object is filled with the error description.
Example

%Retrieve communication handle

handle = Ch.GetACSCHandle;

Version 3.10 50
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.3.2 GetNETLibraryVersion
Description
The method retrieves the SPiiPlus NET Library version number.
Syntax
version = object.GetNETLibraryVersion;
Arguments
None.
Return Value

version Scalar representing SPiiPlus NET Library version number.

Remarks
The SPiiPlus NET 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 the version “2.10” has the following binary representation
(hexadecimal format): 0x020A0000.
The 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.
If the method fails, the Error object is filled with the error description.
Example

%Retrieve the SPiiPlus COM Library

version = Ch.GetNETLibraryVersion;

4.3.3 GetCommOptions
Description
The method retrieves the communication options.
Syntax
options = object.GetCommOptions;
Arguments
None.
Return Value

CommOptions enumeration representing the current

options
communication options.

Remarks
To set the communication options call SetCommOptions.

Version 3.10 51
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The return value is bit-mapped to represent the current communication options. Currently only the
following option flag is supported:
ACSC_COMM_USE_CHECKSUM - communication mode when each command sends to the controller
with checksum and the controller responds with checksum.
If the method fails, the Error object is filled with the error description.
Example

%Retrieve the current communication options

options = Ch.GetCommOptions;

4.3.4 GetDefaultTimeout
Description
The method retrieves default communication timeout.
Syntax
timeout = object.GetDefaultTimeout;
Arguments
None.
Return Value

timeout Scalar representing the default communication timeout.

Remarks
The value of the default timeout depends on the type of the established communication channel.
Timeout depends also on the baud rate value for serial communication.
If the method fails, the Error object is filled with the error description.
Example

%Retrieve default communication timeout

timeout = Ch.GetDefaultTimeout;

4.3.5 GetErrorString
Description
The method retrieves the explanation of an error code.
Syntax
errorStr = object.GetErrorString(errorCode);
Arguments

Scalar representing an error code returned by the following methods:

errorCode
GetMotorErrorGetMotionErrorGetProgramError

Version 3.10 52
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value

errorStr Vector of characters representing the explanation of an error code.

Remarks
If the error relates to SPiiPlus MATLAB Library, the method returns immediately with the text
explanation. If the error relates to the controller, the method receives the text explanation from
the controller.
If the method fails, the Error object is filled with the error description.
Example

%The method retrieves the explanation of 'an error code 3260.

errorStr = Ch.GetErrorString(3260);

4.3.6 GetLibraryVersion
Description
The method retrieves the legacy SPiiPlus C Library version number.
Syntax
libVersion = object.GetLibraryVersion;
Arguments
None.
Return Value

libVersion Scalar representing the legacy SPiiPlus C Library version number.

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 the version “2.10” has the following binary representation (hexadecimal
format): 0x020A0000.
The 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.
If the method fails, the Error object is filled with the error description.
Example

%Retrieve the SPiiPlus C Library version number

libVersion = Ch.GetLibraryVersion;

Version 3.10 53
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.3.7 GetTimeout
Description
The method retrieves communication timeout.
Syntax
timeout = object.GetTimeout;
Arguments
None.
Return Value

timeout Scalar representing the communication timeout.

Remarks
If the method succeeds, the return value is the current timeout value in milliseconds. If the method
fails, the Error object is filled with the error description.
Example

%Retrieves communication timeout

timeout = Ch.GetTimeout;

4.3.8 SetIterations
Description
The method sets the number of iterations in one transaction.
Syntax
object.SetIterations(iterations);
Arguments

iterations Scalar representing the number of iterations.

Return Value
None.
Remarks
If, after the transmission of command to the controller, the controller response is not received
during the predefined time, the library repeats the command transmission. The number of those
iterations is defined by iterations parameter for each communication channel independently.
Most of the SPiiPlus MATLAB methods perform communication with the controller by transactions
(i.e. they send commands and wait for responses) that are based on the Transaction method.
Therefore, the changing of the number of iterations can have an influence on the behavior of the
user application.
The default number of iterations for all communication channels is 2. If the method fails, the Error
object is filled with the error description.

Version 3.10 54
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Sets the number of iterations in one transaction

%number of iterations for all communication channels is 2
Ch.SetIterations(2);

4.3.9 SetCommOptions
Description
The method sets the communication options.
Syntax
object.SetCommOptions(options);
Arguments

Communication options to be set. Bit-mapped parameter that can include

one of the following flags:
> ACSC_COMM_USE_CHECKSUM: the communication mode used when
each command is sent to the controller with checksum and the
options
controller also responds with checksum.
> ACSC_COMM_AUTORECOVER_HW_ERROR: when a hardware error is
detected in the communication channel and this bit is set, the library
automatically repeats the transaction, without counting iterations.

Return Value
None.
Remarks
The method sets the communication options. To get current communication option, call
GetCommOptions.
To add some communication options to the current configuration, modify options that have been
filled in by a call to GetCommOptions, using bitor() operator. This ensures that the other
communication options will have same values.
If the method fails, the Error object is filled with the error description.
Example

%Example sets the mode with checksum

options  = Ch.GetCommOptions;
Ch.SetCommOptions( bitor(options, CommOptions.ACSC_COMM_USE_CHECKSUM));

4.3.10 SetTimeout
Description
The method sets the communication timeout.
Syntax
object.SetTimeout(timeout);

Version 3.10 55
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

timeout Scalar representing the maximum waiting time in milliseconds.

Return Value
None.
Remarks
The method sets the communication timeout.
All of the subsequent waiting calls of the methods will wait for the controller response timeout in
milliseconds. If the controller does not respond to the sent command during this time, SPiiPlus NET
methods will throw ACSException with the error code assigned to ACSC_TIMEOUT.
If the method fails, the Error object is filled with the error description.
Example

%Set the communication timeout of 2 seconds

Ch.SetTimeout(2000);

4.3.11 SetQueueOverflowTimeout
Description
The method sets the Queue Overflow timeout.
Syntax
OBJECT.SETQUEUEOVERFLOWTIMEOUT(TIMEOUT);
Arguments

timeout Scalar representing the maximum waiting time in milliseconds.

Return Value
None.
Example

%Set the Queue Overflow timeout of 2 seconds

Ch.SetQueueOverflowTimeout(2000);

4.3.12 GetQueueOverflowTimeout
Description
The method retrieves the Queue Overflow timeout.
Syntax
timeout  = object.GetQueueOverflowTimeout;
Arguments
None.

Version 3.10 56
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value

timeout Scalar representing the maximum waiting time in milliseconds.

Example

%Retrieve the Queue Overflow timeout in milliseconds

timeout = Ch.GetQueueOverflowTimeout;

4.4 ACSPL+ Program Management Methods

The ACSPL+ Program Management methods are:
Table 3-6. ACSPL+ Program Management Methods

Method Description

Appends one or more ACSPL+ lines to the program in the

AppendBuffer
specified program buffer.

Deletes the specified ACSPL+ program lines in the specified

ClearBuffer
program buffer.

CompileBuffer Compiles ACSPL+ program in the specified program buffer(s).

Clears the specified program buffer and then loads ACSPL+

LoadBuffer
program to this buffer.

Opens a file that contains one or more ACSPL+ programs

LoadBuffersFromFile allocated to several buffers and download the programs to the
corresponding buffers.

RunBuffer Starts up ACSPL+ program in the specified program buffer.

StopBuffer Stops ACSPL+ program in the specified program buffer(s).

SuspendBuffer Suspends ACSPL+ program in the specified program buffer(s).

UploadBuffer Uploads ACSPL+ program from the specified program buffer.

4.4.1 AppendBuffer
Description
The method appends one or more ACSPL+ lines to the program in the specified buffer.
Syntax
object.AppendBuffer(buffer, text);
Async Syntax
wb = object.AppendBufferAsync(buffer, text);

Version 3.10 57
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

ProgramBuffer enumeration representing Number of a program buffer in the

buffer
controller.

text Vector of characters containing an ACSPL+ program(s).

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

program = 'enable 0;jog 0;stop\n';

%The method appends one ACSPL+ line to buffer 0
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_0,program);

%The method appends asynchronously one ACSPL+ line to buffer 0

wb = Ch.AppendBufferAsync(ProgramBuffer.ACSC_BUFFER_0,program);

4.4.2 ClearBuffer
Description
Deletes the specified ACSPL+ program lines in the specified program buffer.
Syntax
object.ClearBuffer(buffer, fromLine, toLine);
Async Syntax
wb = object.ClearBufferAsync(buffer, fromLine, toLine);
Arguments

buffer ProgramBuffer enumeration representing buffer number, from 0 to 9.

fromLine, These arguments specify a range of lines to be deleted.

toLine fromLine starts from 1.

Version 3.10 58
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If toLine is larger then the total number of lines in the specified program
buffer, the range includes the last program line.
If toLine is ACSC_MAX_LINE, the method deletes all lines in the specified
buffer.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method deletes the specified ACSPL+ program lines in the specified program buffer. If the
method fails, the Error object is filled with the error description.
Example

program = 'enable 0;jog 0;stop\n';

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_0,program);

%Delete buffer 0 from line 1 to 1000

Ch.ClearBuffer(ProgramBuffer.ACSC_BUFFER_0,1,1000);

%Delete buffer 0 from line 1 to 1000 asynchronously

wb = Ch.ClearBufferAsync(ProgramBuffer.ACSC_BUFFER_0,1,1000);

4.4.3 CompileBuffer
Description
The method compiles the ACSPL+ program in the specified program buffer(s).
Syntax
object.CompileBuffer(buffer)
Async Syntax
wb = object.CompileBufferAsync(buffer)
Arguments

ProgramBuffer enumeration representing buffer number, from 0 to 9.

buffer You can use ACSC_NONE instead of the buffer number to compile all programs
in all buffers.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 59
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method compiles an ACSPL+ program in the specified program buffer or all programs in all
buffers if buffer is ACSC_NONE.
The method succeeds if the compile command was transmitted successfully to the controller, i.e.,
the communication channel is OK and the specified buffer was not running. However, this does not
mean that the compile operation was completed successfully.
In order to get information about the results of the compile operation, use ReadVariable to read
PERR, which contains the most recent error that occurred in each buffer. If PERR is zero, the buffer
was compiled successfully.
Otherwise, PERR contains the error that occurred during the compilation. The method waits for the
controller response. If the method fails, the Error object is filled with the error description.
Example

program = 'enable 0;jog 0;stop\n';

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_0,program);

%The method compiles ACSPL+ program in buffer 0

Ch.CompileBuffer(ProgramBuffer.ACSC_BUFFER_0);

%The method compiles ACSPL+ program in buffer 0 asynchronously

wb = Ch.CompileBufferAsync(ProgramBuffer.ACSC_BUFFER_0);

4.4.4 LoadBuffer
Description
The method clears the specified program buffer and then loads ACSPL+ program to this buffer.
Syntax
object.LoadBuffer(buffer, text);
Async Syntax
wb = object.LoadBufferAsync(buffer, text);
Arguments

ProgramBuffer enumeration representing number of a program buffer in the

buffer
controller.

text Vector of characters containing an ACSPL+ program(s).

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 60
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

program = '!This is a test ACSPL+ program;Stop\n';

%Load a line to buffer 0
Ch.LoadBuffer(ProgramBuffer.ACSC_BUFFER_0,program);

%Load a line to buffer 0 asynchronously

wb = Ch.LoadBufferAsync(ProgramBuffer.ACSC_BUFFER_0,program);

% Following example loads a program to buffer 3

k=1;
A{1,k} = 'while(1)'; k = k + 1;
A{1,k} = 'ptp/e(0), 30'; k = k + 1;
A{1,k} = 'wait 500'; k = k + 1;
A{1,k} = 'ptp/e(0), -30'; k = k + 1;
A{1,k} = 'wait 500';k = k + 1;
A{1,k} = 'end'; k = k + 1;

s = ''; for k = 1:size(A,2); s = [s, '%s\n'];end

buffer = sprintf(s,A{1,:});
ch.LoadBuffer(3,buffer)

4.4.5 LoadBuffersFromFile
Description
The method opens a file that contains one or more ACSPL+ programs allocated to several buffers
and download the programs to the corresponding buffers.
Syntax
object.LoadBuffersFromFile(filename);
Arguments

filename Vector of characters representing name and path of the file to be loaded.

Return Value
None.
Remarks
The method analyzes the file, determines which program buffers should be loaded, clears them
and then loads ACSPL+ programs to those buffers.

Version 3.10 61
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The method can be called only synchronously.

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 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 the method fails, the Error object is filled with the error description.
Example

filePath = 'C:\\ACSPLFile.txt';
%Opens a file to load
Ch.LoadBuffersFromFile(filePath);

4.4.6 RunBuffer
Description
The method starts up ACSPL+ program in the specified buffer.
Syntax
object.RunBuffer(buffer, label);
Async Syntax
wb = object.RunBufferAsync(buffer, label);
Arguments

ProgramBuffer enumeration representing number of a program buffer in the

buffer
controller.

Vector of characters representing Label in the program from which the

label execution starts.
If [ ] is specified instead of a pointer, the execution starts from the first line.

Return Value
None.

Version 3.10 62
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method 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 SuspendBuffer method, the method resumes the program
execution from the powhere the program was suspended.
The method waits for the controller response.
The controller response indicates that the program in the specified buffer was started successfully.
The method does not wait for the program end. To wait for the program end, use the
WaitProgramEnd method.
If the method fails, the Error object is filled with the error description.
Example

%Append and run buffer 1

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'ST:');
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'!an empty loop');
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'goto ST');
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_1,[]);

%Append and run buffer 2 asynchronuously

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_2,'ST:');
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_2,'!an empty loop');
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_2,'goto ST');
wb = Ch.RunBufferAsync(ProgramBuffer.ACSC_BUFFER_2,[]);

4.4.7 StopBuffer
Description
The method stops the execution of ACSPL+ program in the specified buffer(s).
Syntax
object.StopBuffer(buffer);
Async Syntax
wb = object.StopBufferAsync(buffer);
Arguments

ProgramBuffer enumeration representing number of a program buffer in the

controller.
buffer
To stop the execution of all buffers, use ACSC_NONE instead of the buffer
number.

Version 3.10 63
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method stops ACSPL+ program execution in the specified buffer or in all buffers if Buffer is
ACSC_NONE.
The method has no effect if the program in the specified buffer is not running. If the method fails,
the Error object is filled with the error description.
Example

%Append and run buffer 1

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'ST:;! Empty buffer;goto
ST');
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_1,[]);
%Stop running buffer 1
Ch.StopBuffer(ProgramBuffer.ACSC_BUFFER_1);

%Append and run buffer 2

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_2,'ST:;! Empty buffer;goto
ST');
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_2,[]);
%Stop running buffer 2 asynchronuously
wb = Ch.StopBufferAsync(ProgramBuffer.ACSC_BUFFER_2);

4.4.8 SuspendBuffer
Description
The method suspends the execution of ACSPL+ program in the specified program buffer(s).
Syntax
object.SuspendBuffer(buffer);
Async Syntax
wb = object.SuspendBufferAsync(buffer);
Arguments

ProgramBuffer enumeration representing number of a program buffer in the

controller.
buffer
To stop the execution of all buffers, use ACSC_NONE instead of the buffer
number.

Return Value
None.

Version 3.10 64
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method suspends ACSPL+ program execution in the specified buffer or in all buffers if buffer is
ACSC_NONE. The method 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 RunBuffer method. If the
method fails, the Error object is filled with the error description.
Example

%Append and run buffers 1 and 2

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'ST:;! Empty buffer;goto
ST');
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_1,[]);
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_2,'ST:;! Empty buffer;goto
ST');
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_2,[]);
%Suspend all buffers
Ch.SuspendBuffer(ProgramBuffer.ACSC_NONE);

%Append and run buffers 3 and 4

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_3,'ST:;! Empty buffer;goto
ST');
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_4,[]);
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_4,'ST:;! Empty buffer;goto
ST');
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_4,[]);

%Suspend all buffers asynchronuously

Ch.SuspendBufferAsync(ProgramBuffer.ACSC_NONE);

4.4.9 UploadBuffer
Description
The method uploads ACSPL+ program from the specified program buffer.
Syntax
reply = object.UploadBuffer(buffer);
Arguments

ProgramBuffer enumeration representing number of a program buffer in the

buffer
controller.

Return Value

reply Vector of characters with uploaded text.

Version 3.10 65
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method uploads ACSPL+ program from the specified program buffer. If the method fails, the
Error object is filled with the error description.
Example

program  = '!This is an empty buffer\n';

%Appends  program to buffer 0
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_0, program);
%Get program of buffer 0
reply = Ch.UploadBuffer(ProgramBuffer.ACSC_BUFFER_0);

4.5 Read and Write Variables Methods

The Read and Write Variable methods are:
Table 3-7. Read and Write Variables Methods

Method Description

Reads variable from a controller and returns it in the form of

ReadVariable
object

ReadVariableAsScalar Reads variable from a controller and returns it as scalar object

Reads variable from a controller and returns it in the form

ReadVariableAsVector
object that contains one-dimension array

Reads variable from a controller and returns it in the form

ReadVariableAsMatrix
object that contains two-dimensions array

WriteVariable Writes to controller variable(s)

4.5.1 ReadVariable
Description
The method reads a variable from the controller.
Syntax
result = object.ReadVariable(variable, nBuf, from1, to1, from2, to2);
Async Syntax
wb = object.ReadVariableAsync(variable, nBuf, from1, to1, from2, to2);
Arguments

variable Vector of characters representing the name of the controller variable.

ProgramBuffer enumeration representing number of program buffer for

nBuf
local variable or ProgramBuffer.ACSC_NONE for global and ACSPL+ variables.

Version 3.10 66
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

from1, to1 Index range (first dimension) starting from zero. Default value: -1.

from2, to2 Index range (second dimension) starting from zero. Default value: -1.

Return Value

The type of return value is real or integer, depending on the type of controller
variable.
result The return value can be scalar, vector (one-dimensional array) or matrix (two-
dimensional array) depending on data that the controller retrieves.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method reads scalar variables, vectors, rows of matrix, and columns of matrix or matrices from
a controller and retrieves data as object. The resultant data are initialized depending on what data
is received from the controller: scalar, vector or matrix.
If you want the return value to be in some specified type, use ReadVariableAsScalar,
ReadVariableAsVector or ReadVariableAsMatrix methods.
The variable can be an ACSPL+ controller variable, a user global variable, or a user local variable.
ACSPL+ and user global variables have global scope; therefore nBuf must be omitted or specified
as ProgramBuffer.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.
The index parameters can be specified as follows:
> To read the whole variable
> To read one element of the variable
> To read several elements of the variable
The following explains how to specify indexes in several typical cases.
1. Reading whole variable
The from1, to1, from2 and to2 indexes should be omitted or specified as “-1”
The method returns all elements of Variable as object initialized as:
> Scalar, if the Variable is scalar
> Vector, if the Variable is a one-dimensional array
> Matrix, if the Variable is a two-dimensional array
2. Reading one element from vector (one-dimensional array)

Version 3.10 67
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The from1 and to1 should be equal and specify the index of the element. from2 and to2
should be omitted or specified as -1. The method returns the element value as object,
initialized as scalar.
3. Reading one element from matrix (two-dimensional array)
from1 should equal to1 and specify row number. The from2 and to2 should be equal and
specify column number. The method returns the element value as object, initialized as
scalar method
4. Reading a sub-vector (more than one vector element)
from1 and to1 should specify the sub-vector index range, where from1 should be less than
to1. from2 and to2 should be omitted or specified as -1. The method returns data as object,
initialized as a vector with the number of elements equal to to1– from1 +1.
5. Reading a row or part of a row from a matrix
from1 should equal to1 and specify the row number. The from2 and to2 should specify the
element range within the specified row, where from2 should be less than to2. The
method returns data as object, initialized as a vector with the number of elements equal
to2 – from2 +1.
6. Reading a column or part of a column from a matrix
from1 and to1 should specify the range of rows within the specified column, where from1
should be less than to1. from2 and to2 should be equal and specify the column number.
The method returns data as object, initialized as a vector with the number of elements
equal to to1–from1+1.
7. Reading sub-matrix from matrix
from1 and to1 should specify the range of rows, where from1 should be less then to1. from2
and to2 should specify columns range, where from2 should be less than to2. The method
returns data as object, initialized as a matrix with the number of rows equal to to1– from1
+1 and the number of columns equal to to2 – from2 +1.
If the method fails, the Error object is filled with the error description.
Example

%Read variable

%Reading whole variable, if the variable is scalar:

%Parameters: 'BAUD' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variable
obj = Ch.ReadVariable('BAUD');
%or:
obj = Ch.ReadVariable('BAUD', ProgramBuffer.ACSC_NONE);
%Now var is a scalar value

%Reading whole variable, if the variable is one-dimensional array:

%Parameters: 'VEL' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variable
obj = Ch.ReadVariable('VEL');
%or:

Version 3.10 68
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

obj = Ch.ReadVariable('VEL', ProgramBuffer.ACSC_NONE);

%Now var is a vector of size 8

%Reading whole variable, if the variable is two-dimensional array:

%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' – user variable name
%(optional:)ProgramBuffer.ACSC_NONE - global variable
obj = Ch.ReadVariable('MyMatrix');
%or:
obj = Ch.ReadVariable('MyMatrix', ProgramBuffer.ACSC_NONE);
%Now var is a matrix of size 3x4

%Reading one element from vector (one-dimensional array):

%Reading one element with index 3:
%Parameters: 'VEL' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
%elementIndx - from1, to1
elementIndx = 3;
obj = Ch.ReadVariable('VEL', ProgramBuffer.ACSC_NONE, elementIndx,
elementIndx);
%Now var is a scalar value

%Reading one element from matrix (two-dimensional array):

%Reading one element of matrix from row 1, column 2:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' – user variable name
%ProgramBuffer.ACSC_NONE - global variable
%elementRow - from1, to1
%elementColumn – from2, to2
elementRow = 1;
elementColumn = 2;
obj = Ch.ReadVariable('MyMatrix',ProgramBuffer.ACSC_NONE, elementRow,
elementRow, elementColumn, elementColumn);
%Now var is a scalar value

%Reading sub-vector (more then one element) from vector:

%Reading sub-vector with indexes from 1 to 5:
%Parameters: 'VEL' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
%fromIndex - from1
%toIndex – to1
fromIndex = 1;
toIndex = 5;
obj = Ch.ReadVariable('VEL', ProgramBuffer.ACSC_NONE, fromIndex,
toIndex);
%Now var is a vector of size 5

%Reading row or part of row from matrix:

Version 3.10 69
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Reading a part of row 1 from element with index 0 till element with 
%index 2:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' - user variable name
%ProgramBuffer.ACSC_NONE - global variable
%rowIndex - from1, to1
%fromColumnIndex – from2
%toColumnIndex – to2
rowIndex = 1;
fromColumnIndex = 0;
toColumnIndex = 2;
obj = Ch.ReadVariable('MyMatrix', ProgramBuffer.ACSC_NONE, rowIndex,
rowIndex, fromColumnIndex, toColumnIndex);
%Now var is a vector of size 3

%Reading column or part of column from matrix:

%Reading a part of column 1 from element with index 0 till element with 
%index 1:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' - user variable name
%ProgramBuffer.ACSC_NONE - global variable
%fromRowIndx - from1
%toRowIndx – to1
%columnIndx – from2, to2
fromRowIndx = 0;
toRowIndx = 1;
columnIndx = 1;
obj = Ch.ReadVariable('MyMatrix',ProgramBuffer.ACSC_NONE, fromRowIndx,
toRowIndx, columnIndx, columnIndx);
%Now var is a vector of size 2

%Reading sub-matrix from matrix:

%Reading sub-matrix with rows from 0 to 1 and colomns from 0 to 2:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' - user variable name
%ProgramBuffer.ACSC_NONE - global variable
%fromRowIndx - from1
%toRowIndx – to1
%fromColumnIndx – from2
%toColumnIndx – to2
fromRowIndx = 0;
toRowIndx = 1;
fromColumnIndx = 0;
toColumnIndx = 2;
obj = Ch.ReadVariable('MyMatrix',ProgramBuffer.ACSC_NONE, fromRowIndx,
toRowIndx, fromColumnIndx, toColumnIndx);

Version 3.10 70
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Now var is a matrix 2x3

4.5.2 ReadVariableAsScalar
Description
The method reads the variable from a controller and returns as a scalar.
Syntax
object.ReadVariableAsScalar (variable, nBuf, ind1, ind2);
Async Syntax
wb = object.ReadVariableAsScalarAsync(variable, nBuf, ind1, ind2);
Arguments

variable Vector of characters representing the name of the controller variable.

ProgramBuffer enumeration representing number of program buffer for

nBuf
local variable or ProgramBuffer.ACSC_NONE for global and ACSPL+ variables.

ind1 Index of first dimension (row number) starting from zero. Default value: -1

Index of second dimension (column number) starting from zero. Default

ind2
value: -1.

Return Value

The return value is scalar, that is, the type of return value is real or
result
integer, corresponding to the type of controller variable.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
Reads a scalar variable, one element of a vector or one element of a matrix from a controller and
returns the value as scalar.
If you require a method return value as one vector element, use the ReadVariableAsVector
method. If you require a method return value as one matrix element, use the
ReadVariableAsMatrix method.
The variable can be an ACSPL+ variable, a user-defined global variable, or a user-defined local
variable.
ACSPL+ and user global variables have global scope; therefore nBuf must be ProgramBuffer.ACSC_
NONE (–1) for these classes of variables.
User-defined local variables exist only within a buffer. The buffer number must be specified for
user-defined local variables.
The following explains how to read indexes in several typical cases.
1. Reading a scalar variable:

Version 3.10 71
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The ind1 and ind2 indexes should be omitted or specified as -1.

2. Reading one element from a vector (one-dimensional array):
ind1 should specify index of the element in the vector. ind2 should be omitted or specified
as -1.
3. Reading one element from a matrix (two-dimensional array):
ind1 should specify a row number and ind2 should specify a column number of the
element in the matrix.
If the method fails, the Error object is filled with the error description.
Example

%Read variable as scalar

%var in the next examples is returned as scalar
%Reading scalar variable:
%Parameters: 'BAUD' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
var = Ch.ReadVariableAsScalar('BAUD', ProgramBuffer.ACSC_NONE);
%or
wb = Ch.ReadVariableAsScalarAsync('BAUD', ProgramBuffer.ACSC_NONE);
var = GetResult(wb, 2000);

%Reading one element from vector (one-dimensional array):

%Reading one element with index 2:
%Parameters: 'VEL' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
index = 2;
var = Ch.ReadVariableAsScalar('VEL', ProgramBuffer.ACSC_NONE, index);
%or
wb = Ch.ReadVariableAsScalarAsync('VEL', ProgramBuffer.ACSC_NONE, index);
var = GetResult(wb, 2000);

%Reading one element from matrix (two-dimensional array):

%Reading one element of matrix from row 1, column 2:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' – user variable name
%ProgramBuffer.ACSC_NONE - global variable
rowIndex = 1;
columnIndex = 2;
var = Ch.ReadVariableAsScalar('MyMatrix', ProgramBuffer.ACSC_NONE,
rowIndex, columnIndex);
%or
wb = Ch.ReadVariableAsScalarAsync('MyMatrix', ProgramBuffer.ACSC_NONE,
rowIndex, columnIndex);
var = GetResult(wb, 2000);

Version 3.10 72
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.5.3 ReadVariableAsVector
Description
The method reads a variable from a controller and returns it as vector.
Syntax
result object.ReadVariableAsVector(variable, nBuf, from1, to1, from2, to2);
Async Syntax
wb = object.ReadVariableAsVectorAsync(variable, nBuf, from1, to1, from2, to2);
Arguments

variable Vector of characters representing the name of the controller variable.

ProgramBuffer enumeration representing number of program buffer for

nBuf
local variable or ProgramBuffer.ACSC_NONE for global and ACSPL+ variables.

from1, to1 Index range (first dimension) starting from zero. Default value: -1.

from2, to2 Index range (second dimension) starting from zero. Default value: -1.

Return Value

The return value is a one-dimensional array (vector). The type of return value
result
is real or integer, corresponding to the type of controller variable.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
If you want a return value as scalar or matrix use ReadVariableAsScalar or ReadVariableAsMatrix
methods correspondingly.
The variable can be an ACSPL+ variable, a user global variable, or a user local variable. ACSPL+ and
user global variables have global scope; therefore nBuf must be omitted or specified as
PROGRAMBUFFER.ACSC_NONE (–1) for these classes of variables.
User local variables exist only within a buffer. The buffer number must be specified for user local
variable.
The index parameters can be specified in many different ways to read whole variable, one element
of the variable or several elements of the variable. The following explains how to specify indexes in
several typical cases.
1. Reading whole variable:
The from1, to1, from2 and to2 indexes should be omitted or specified as -1.
The method returns all elements of variable as object initialized as:
Vector of size 1, if the variable is scalar
Vector of size N, if the variable is vector of size N

Version 3.10 73
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the variable is matrix, the method will return an error.

2. Reading sub-vector from vector:
The from1 and to1 should specify sub-vector index range, from1 should be less than or
equal to to1. The from2 and to2 should be omitted or specified as -1. The method returns
data as vector with number of elements equals to to1- from1+1.
3. Reading a row or part of a row from matrix:
The from1 and to1 should be equal and specify row number. The from2 and to2 should
specify elements range within the specified row, from2 should be less than or equal to
to2. The method returns data as vector with number of elements equals to to2 - from2 +1.
4. Reading a column or part of a column from matrix:
The from1 and to1 should specify rows range within the specified column, from1 should be less than
or equal to to1. The from2 and to2 should be equal and specify column number. The method
returns data as vector with number of elements equals to to1- from1+1.
If the method fails, the Error object is filled with the error description.

Version 3.10 74
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Read variable as vector

%var in the next examples is returned as vector

%Reading whole variable, if the variable is scalar:

%Parameters: 'BAUD' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variable
var = Ch.ReadVariableAsVector('BAUD');
%or:
var = Ch.ReadVariableAsVector('BAUD', ProgramBuffer.ACSC_NONE);
%now var is a vector of size 1

%Reading whole variable, if the variable is one-dimensional array:

%Parameters: 'VEL' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variable
var = Ch.ReadVariableAsVector('VEL');
%or:
var = Ch.ReadVariableAsVector('VEL', ProgramBuffer.ACSC_NONE);
%now var is a vector of size 8

%Reading sub-vector from vector:

%Reading sub-vector with indexes from 1 to 5:
%Parameters: 'VEL' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
%fromIndex – from11
%toIndex – to1
fromIndex = 1;
toIndex = 5;
var = Ch.ReadVariableAsVector('VEL',ProgramBuffer.ACSC_NONE, fromIndex,
toIndex);
%now var is a vector of size 5

%Reading row or part of row from matrix:

%Reading a part of row 1 from element with index 0 till element with
%index 2
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' – user variable name
%ProgramBuffer.ACSC_NONE - global variable
%rowIndex – from1, to1
%fromColumnIndex – from2
%toColumnIndex – to2
rowIndex = 1;  
fromColumnIndex = 0;
toColumnIndex = 2;
var = Ch.ReadVariableAsVector('MyMatrix', ProgramBuffer.ACSC_NONE,
rowIndex, rowIndex, fromColumnIndex, toColumnIndex);
%Now var is a vector of size 3

%Reading column or part of column from matrix:

Version 3.10 75
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Reading a part of colomn 1 from element with index 0 till element with
%index 1
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' – user variable name
%ProgramBuffer.ACSC_NONE - global variable
%fromRowIndex – from1
%toRowIndex – to1
%columnIndex – from2, to2
fromRowIndex = 0;
toRowIndex = 1;
columnIndex = 1;
var = Ch.ReadVariableAsVector('MyMatrix', ProgramBuffer.ACSC_NONE,
fromRowIndex, toRowIndex, columnIndex, columnIndex);
%Now var is a vector of size 2

4.5.4 ReadVariableAsMatrix
Description
The method reads the variable from a controller and returns it as matrix.
Syntax
result = object.ReadVariableAsMatrix(variable, nBuf, from1, to1, from2, to2)
Async Syntax
wb = object.ReadVariableAsMatrixAsync(variable, nBuf, from1, to1, from2, to2)
Arguments

variable Vector of characters representing the name of the controller variable.

ProgramBuffer enumeration representing number of program buffer for

nBuf local variable or PROGRAMBUFFER.ACSC_NONE for global and ACSPL+
variables.

from1, to1 Index range (first dimension) starting from zero. Default value: -1.

from2, to2 Index range (second dimension) starting from zero. Default value: -1.

Return Value

The return value is a two-dimensional array (matrix). The type of return

result
value is real or integer, corresponding to the type of controller variable.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 76
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
If you want a return value as scalar or vector use ReadVariableAsScalar or ReadVariableAsVector
methods  correspondingly.
The variable can be an ACSPL+ controller variable, a user global variable, or a user local variable.
ACSPL+ variables and user global variables have a global scope; therefore nBuf must be omitted or
specified as ProgramBuffer.ACSC_NONE (–1) for these classes of variables.
User local variables exist only within a buffer. The buffer number must be specified for user local
variable.
The index parameters can be specified in many different ways to read whole variable, one element
of the variable or several elements of the variable. The following explains how to specify indexes in
several typical cases.
> Reading a whole variable
from1, to1, from2 and to2 indexes should be omitted or specified as -1. The method returns
all elements of variable as object initialized as follows:
Matrix 1x1 , if the variable is scalar
Matrix 1xN, if the variable is vector of size N Matrix NxM, if the variable matrix NxM
> Reading a sub-vector from a vector
from1 and to1 should specify the sub-vector index range, from1 should be less than or
equal to to1. from2 and to2 should be omitted or specified as -1. The method returns data
as object, initialized as a matrix of size (to1–from1+1)x1.
> Reading a sub-matrix from a matrix
from1 and to1 should specify a range of rows, where from1 should be less than or equal to
to1. from2 and to2 should specify a range of columns , where from2 should be less than or
equal to to2. The method returns data as object, initialized as matrix with the number of
rows equal to to1–from1+1 and the number of columns equals to2–from2+1.
If the method fails, the Error object is filled with the error description.
Example

%Read variable as matrix

%var in the next examples is returned as matrix

%Reading whole variable, if the variable is scalar:

%Parameters: 'BAUD' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variablevar =
Ch.ReadVariableAsMatrix('BAUD');
%or:
var = Ch.ReadVariableAsMatrix('BAUD', ProgramBuffer.ACSC_NONE);
%now var is a matrix of size 1x1

%Reading whole variable, if the variable is one-dimensional array:

%Parameters: 'VEL' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variable

Version 3.10 77
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

var = Ch.ReadVariableAsMatrix('VEL');
%or:
var = Ch.ReadVariableAsMatrix('VEL', ProgramBuffer.ACSC_NONE);
%now var is a matrix of size 1x8

%Reading whole variable, if the variable is two-dimensional array:

%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' – user variable name
%(optional:)ProgramBuffer.ACSC_NONE - global variable
var = Ch.ReadVariableAsMatrix('MyMatrix');
%or:
var = Ch.ReadVariableAsMatrix('MyMatrix', ProgramBuffer.ACSC_NONE);
%now var is a matrix of size 3x4

%Reading sub-vector (more then one element) from vector:

%Reading sub-vector with indexes from 1 to 5:
%Parameters: 'VEL' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
%fromIndex – from11
%toIndex – to1
fromIndex = 1;
toIndex = 5;
var = Ch.ReadVariableAsMatrix('VEL',ProgramBuffer.ACSC_NONE, fromIndex,
toIndex);
%now var is a matrix of size 1x5

%Reading sub-matrix from matrix:

%Reading sub-matrix from with rows from 0 to 1 and colomns from 0 to 2
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: 'MyMatrix' – user variable name
%ProgramBuffer.ACSC_NONE - global variable
%fromRowIndex – from1
%toRowIndex – to1
%fromColumnIndex – from2
%toColumnIndex - to2
fromRowIndex = 0;
toRowIndex = 1;
fromColumnIndex =0;
toColumnIndex = 2;
var = Ch.ReadVariableAsMatrix('MyMatrix', ProgramBuffer.ACSC_NONE,
fromRowIndex, toRowIndex, fromColumnIndex, toColumnIndex);
%Now var is a matrix 2x3

4.5.5 WriteVariable
Description
The method writes a value defined as object to the controller variable(s).

Version 3.10 78
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
object.WriteVariable(value, variable, nBuf, from1, to1, from2, to2)
Async Syntax
wb = object.WriteVariableAsync(value, variable, nBuf, from1,  to1, from2, to2)
Arguments

Value to be assigned to the variable. The value can contain an integer or

value real number(s). The value can be scalar, one-dimensional array (vector) or
two-dimensional array (matrix).

variable Name of the controller variable

Number of program buffer for local variable or ProgramBuffer.ACSC_NONE

nBuf
for global and ACSPL+ variables.

Index range (first dimension) starting from zero of variable

from1, to1
(not of value). Default value: -1.

Index range (second dimension) starting from zero of variable (not of

from2, to2
value). Default value: -1.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
This method writes value to the specified variable. variable can be scalar, vector (one- dimensional
array) or matrix (two-dimensional array).
variable can be either an ASCPL+ variable, user global variable or a user local variable. ASCPL+ and
user global variables have global scope; therefore nBuf must be must be omitted or specified as
ProgramBuffer.ACSC_NONE (–1) for these classes of variables.
User local variable exist only within a buffer. The buffer number must be specified for user local
variable.
The index parameters can be specified in many different ways. Write the entire variable, a single
element of the variable or several elements of the variable as follows:
> Write value to whole variable
from1, to1, from2 and to2 indexes should be omitted or specified as  -1. The value
dimension should correspond to the variable dimension as follows:
> If variable is scalar, value should be scalar, or vector of size 1, or matrix of size 1x1
> If variable is vector of size N, value should be vector of size N, or matrix of size 1xN, or
matrix of size Nx1

Version 3.10 79
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

> If variable is matrix of size NxM, value should be matrix of size NxM
> Writing a value to one element of vector (one-dimensional array)
The from1 and to1 should be equal and specify index of the element. from2 and  to2 should
be omitted or specified as -1.
> Writing value to one element of matrix (two-dimensional array)
The from1 and to1 should be equal and specify row number. The from2 and TO2 should be
equal and specify column number.
> Writing a value to sub-vector (more then one element) of vector
The from1 and to1 should specify sub-vector index range, from1 should be less then to1.
The from2 and to2 should be omitted or specified as -1.
> Writing a value to row or part of row of matrix
The from1 and to1 should be equal and specify row number. The from2 and to2 should
specify elements range within the specified row, from2 should be less then to2.
> Writing a value to column or part of column of matrix
The from1 and to1 should specify rows range within the specified column, from1 should be
less than to1. The from2 and to2 should be equal and specify column number.
> Writing a value to sub-matrix of matrix
The from1 and to1 should specify rows range, from1 should be less then to1. The from2 and
to2 should specify columns range, from2 should be less then to2.
If indexes (from1, to1, from2, to2) are specified, their values must correspond to value dimensions
described below:
Table 3-8. Value Dimension Indices

Dimension Indeces

Scalar from1=to1 and from2=to2

(to1-from1+1=N and to2=from2) or

Vector of size N
(to1=from1 and to2-from2+1=N)

Matrix of size NxM to1-from1+1=N and to2-from2+1=M

Scalar from1=to1 and from2=to2

(to1-from1+1=N and to2=from2) or

Vector of size N
(to1=from1 and to2-from2+1=N)

value type is not required to be the same as variable type. The library provides automatic
conversion from integer to real and from real to integer.
If the method fails, the Error object is filled with the error description.

Version 3.10 80
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Write variable
%Initialize scalar
scalar = 57600;
%Initialize vector
vector = repmat(1.1, 1, 8);
%Initialize matrix
matrix = repmat(2, 3, 4);
%Initialize subVector
subVector = repmat(3, 1, 2);
%Initialize subMatrix
subMatrix = repmat(4, 2, 2);

%Writing scalar to whole variable:

%Parameters: scalar - value to be assigned to the variable
%'BAUD' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variable
Ch.WriteVariable(scalar, 'BAUD');
%or:
Ch.WriteVariable(scalar, 'BAUD', ProgramBuffer.ACSC_NONE);
%asynchronous call
wb = Ch1.WriteVariableAsync(scalar, 'BAUD');
%or:
wb = Ch1.WriteVariableAsync(scalar, 'BAUD', ProgramBuffer.ACSC_NONE);

%Writing vector (one-dimensional array) to the whole variable:

%Parameters: vector - value to be assigned to the variable
%'VEL' - controller variable name
%(optional:)ProgramBuffer.ACSC_NONE - ACSPL+ variable
Ch.WriteVariable(vector, 'VEL');
%or:
Ch.WriteVariable(vector, 'VEL', ProgramBuffer.ACSC_NONE);

%Writing matrix to whole variable:

%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: matrix - value to be assigned to the variable
%'MyMatrix' - user variable name
%(optional:)ProgramBuffer.ACSC_NONE - global variable
Ch.WriteVariable(matrix, 'MyMatrix');
%or:
Ch.WriteVariable(matrix, 'MyMatrix', ProgramBuffer.ACSC_NONE);

%Writing value to one element of vector (one-dimensional array):

%Parameters: scalar - value to be assigned to the variable
%'VEL' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
%elementIndx - from1, to1
elementIndex = 3;

Version 3.10 81
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.WriteVariable(scalar, 'VEL', ProgramBuffer.ACSC_NONE, elementIndex,

elementIndex);

%Writing value to one element of matrix (two-dimensional array):

%Writing value to one element of matrix from row 1, column 2:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: scalar - value to be assigned to the variable
%'MyMatrix' - user variable name
%ProgramBuffer.ACSC_NONE - global variable
%elementRow - from1, to1
%elementColumn – from2, to2
elementRow = 1;
elementColumn = 2;
Ch.WriteVariable(scalar, 'MyMatrix', ProgramBuffer.ACSC_NONE, elementRow,
elementRow, elementColumn, elementColumn);

%Writing value to sub-vector (more then one element) of vector:

%Writing sub-vector with indexes from 2 to 3:
%Parameters: subVector - value to be assigned to the
%variable
%'VEL' - controller variable name
%ProgramBuffer.ACSC_NONE - ACSPL+ variable
%fromIndex - from1
%toIndex – to1
fromIndex = 2;
toIndex = 3;
Ch.WriteVariable(subVector, 'VEL', ProgramBuffer.ACSC_NONE, fromIndex,
toIndex);

%Writing value to row or part of row of matrix:

%Writing value to row 1, from element with index 0 till element with
%index 1:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: subVector - value to be assigned to the
%variable
%'MyMatrix' - user variable name
%ProgramBuffer.ACSC_NONE - global variable
%rowIndex - from1, to1
%fromColumnIndex – from2
%toColumnIndex – to2
rowIndex = 1;
fromColumnIndex = 0;
toColumnIndex = 1;
Ch.WriteVariable(subVector, 'MyMatrix', ProgramBuffer.ACSC_NONE,
rowIndex, rowIndex, fromColumnIndex, toColumnIndex);

%Writing value to column or part of column of matrix:

Version 3.10 82
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Writing value to column 2, from element with index 0 till element with
%index 1:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: subVector - value to be assigned to the
%variable
%'MyMatrix' - user variable name
%ProgramBuffer.ACSC_NONE - global variable
%fromRowIndx - from1
%toRowIndx – to1
%columnIndx – from2, to2
fromRowIndx = 0;
toRowIndx = 1;
columnIndx = 2;
Ch.WriteVariable(subVector, 'MyMatrix', ProgramBuffer.ACSC_NONE,
fromRowIndx, toRowIndx, columnIndx, columnIndx);

%Writing value to sub-matrix of matrix:

%Writing sub-matrix to rows from 2 to 3 and colomns from 1 to 2:
%Assumed that MyMatrix variable is declared as global MyMatrix(3)(4)
%in the controller:
%Parameters: subMatrix - value to be assigned to the
%variable
%'MyMatrix' - user variable name
%ProgramBuffer.ACSC_NONE - global variable
%fromRowIndx - from1
%toRowIndx – to1
%fromColumnIndx – from2
%toColumnIndx – to2
fromRowIndx = 2;
toRowIndx = 3;
fromColumnIndx = 1;
toColumnIndx = 2;
Ch.WriteVariable(subMatrix, 'MyMatrix', ProgramBuffer.ACSC_NONE,
fromRowIndx, toRowIndx, fromColumnIndx, toColumnIndx);

4.6 History Buffer Management Methods

The History Buffer Management methods are:
Table 3-9. History Buffer Management Methods

Method Description

OpenHistoryBuffer Opens a history buffer.

CloseHistoryBuffer Closes a history buffer.

GetHistory Retrieves the contents of the history buffer.

Version 3.10 83
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.6.1 OpenHistoryBuffer
Description
The method opens a history buffer.
Syntax
object.OpenHistoryBuffer(size)
Arguments

size Required size of the buffer in bytes

Return Value
None.
Remarks
The method 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 channel.
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.
If the method fails, the Error object is filled with the error description.
Example

%Open history buffer

bufferSize = 5000;
%The method opens an history buffer size of the buffer is 5000
Ch.OpenHistoryBuffer(bufferSize);

4.6.2 CloseHistoryBuffer
Description
The method closes the history buffer and discards all stored history.
Syntax
object.CloseHistoryBuffer
Arguments
None.
Return Value
None.
Rermarks
The method closes the history buffer and releases the used memory. All information stored in the
buffer is discarded.
If the method fails, the Error object is filled with the error description.

Version 3.10 84
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Close history buffer

Ch.CloseHistoryBuffer;

4.6.3 GetHistory
Description
The method retrieves the contents of the history buffer.
Syntax
history = object.GetHistory(bClear);
Arguments

If TRUE, the method clears contents of the history buffer. If FALSE, the history
bClear
buffer content is not cleared.

Return Value

Vector of characters specifying the communication history from the history

history
buffer.

Remarks
The communication history includes all commands sent to the controller and all responses and
unsolicited messages from the controller. The amount of history data is limited by 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 recent commands,
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 the returned string. The beginning of the return string might be incomplete, if it has been
partially overwritten in the history buffer.
If the method fails, the Error object is filled with the error description.
Example

%Get history buffer

bufferSize = 5000;
cmd = 'enable 0';
%The method opens an history buffer
%size of the buffer is 5000
Ch.OpenHistoryBuffer(bufferSize);
%Sending the command "enable 0"
Ch.Send(cmd);
%The method retrieves the contents of the

Version 3.10 85
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%history buffer.
str = Ch.GetHistory(false);

4.7 Unsolicited Messages Buffer Management Methods

The Unsolicited Messages Buffer Management methods are:
Table 3-10. Unsolicited Messages Buffer Management Methods

Method Description

OpenMessageBuffer Opens an unsolicited messages buffer.

CloseMessageBuffer Closes an unsolicited messages buffer.

GetSingleMessage Retrieves single unsolicited message from the buffer.

4.7.1 OpenMessageBuffer
Description
The method opens an unsolicited messages buffer.
Syntax
object.OpenMessageBuffer(size);
Arguments

size Required size of the buffer in bytes

Return Value
None.
Remarks
The method 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 channel.
The message buffer works as a FIFO buffer: GetSingleMessage extracts the earliest message
stored in the buffer. If GetSingleMessage 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.
If the method fails, the Error object is filled with the error description.
Example

%Open message buffer

bufferSize = 5000;
%The method opens an unsolicited messages

Version 3.10 86
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%buffer size of the opened buffer is 5000

Ch.OpenMessageBuffer(bufferSize);

4.7.2 CloseMessageBuffer
Description
The method closes the messages buffer and discards all stored unsolicited messages.
Syntax
object.CloseMessageBuffer;
Arguments
None.
Return Value
None.
Remarks
The method closes the message buffer and releases the used memory. All unsolicited messages
stored in the buffer are discarded.
If the method fails, the Error object is filled with the error description.
Example

%Close message buffer

%The method closes the messages buffer
%and discards all stored unsolicited messages
Ch.CloseMessageBuffer;

4.7.3 GetSingleMessage
Description
The method retrieves single unsolicited message from the buffer. This method only works if you
setup a buffer using OpenMessageBuffer. If there is no message in the buffer the method waits
until the message arrives or time out expires.
Syntax
object.GetSingleMessage(timeout)
Arguments

timeout Maximum waiting time in milliseconds.

Return Value
String.
Remarks
The method retrieves single unsolicited message from the message buffer.

Version 3.10 87
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If no, unsolicited message is received the method waits until a message arrives. If the timeout
expires, the method exits with ACSC_TIMEOUT error.
If the method fails, the Error object is filled with the error description.
Example

bufferSize = 5000;
cmd = '?FPOS0';
timeout = 1000;
%The method opens an unsolicited messages
%buffer, size of the opened buffer is 5000
Ch.OpenMessageBuffer(bufferSize);
%Sending the command '?FPOS0'
Ch.Send(cmd);
%The method retrieves unsolicited message
%from the buffer and wait 1 second till a
%message arrives
message = Ch.GetSingleMessage(timeout);

4.8 Log File Management Methods

The Log File Management methods are:
Table 3-11. Log File Management Methods

Method Description

SetLogFileOptions Sets the log file options.

OpenLogFile Opens a log file.

CloseLogFile Closes a log file.

WriteLogFile Writes to a log file.

GetLogData Retrieves the data of firmware log.

4.8.1 SetLogFileOptions
Description
The function sets the log file options.
Syntax
object.SetLogFileOptions(detailization, presentation);

Version 3.10 88
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Minimum: Only communication traffic will be logged.

Medium: Communication traffic and some internal C Libprocess data will
detailization be logged.
Maximum: Communication traffic and all internal processdata will be
logged.

Compact: No more than the first ten bytes of each data string will be
logged. Non-printing characters will be represented in HexASCII code.
presentation Formatted: All the binary data will be logged. Non-printingcharacters
will be represented in Hex ASCII code.
Full: All the binary data will be logged as is.

Return Value
None.
Remarks
The function configures the log file options. The function may be called before or after the log file
is opened
Example

%Example of function acsc_SetLogFileOptions

detalization = ACSC_LOG_DETALIZATION_LEVEL.Maximum;
presentation = ACSC_LOG_DATA_PRESENTATION.Full;
Ch.SetLogFileOptions(detalization, presentation);

4.8.2 OpenLogFile
Description
The method opens a log file.
Syntax
object.OpenLogFile(filename);
Arguments

filename Vector of characters containing the name or path and name of the log file.

Return Value
None.
Remarks
The method opens a binary file that stores all communication history.
Only one log file can be open for each communication channel.

Version 3.10 89
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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 log
file is for debug purposes.
If the method fails, the Error object is filled with the error description.
Example

%Open log file

Ch.OpenLogFile('C:\\COMLogFile.log');

4.8.3 CloseLogFile
Description
The method closes the log file.
Syntax
object.CloseLogFile
Arguments
None.
Return Value
None.
Remarks
An application must always call CloseLogFile before it exits. Otherwise, the data written to the file
might be lost.
If the method fails, the Error object is filled with the error description.
Example

%Close log file example

%The method opens the log file 'COMLogFile.log'
Ch.OpenLogFile('C:\\COMLogFile.log');
%The method closes the log file 'COMLogFile.log'
Ch.CloseLogFile;

4.8.4 WriteLogFile
Description
The method writes to log file.
Syntax
object.WriteLogFile(buf)
Arguments

buf Vector of characters to be written to log file.

Version 3.10 90
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Remarks
The method writes data from a buffer to log file. The log file should be previously opened by the
OpenLogFile method.
The method adds its arguments to the internal UMD binary buffer. In previous C Library versions,
the log file had to be explicitly opened by the OpenLogFile method, otherwise the function would
return an error. Starting with COM Library version 5.0, this is no longer the case. See, FlushLogFile.
If the method fails, the Error object is populated with the error description.
Example

%Write to log file example

%Opens a log file
Ch.OpenLogFile('C:\\COMLogFile.log');
%Write to log file
Ch.WriteLogFile('Writing to log file');
%Close the log file
Ch.CloseLogFile;

4.8.5 GetLogData
Description
The method is used to retrieve the data of firmware log.
Syntax
object.GetLogData;
Async Syntax
wb = object.GetLogDataAsync
Arguments
None.
Return Value
String.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Synchronous Get log data

logData = Ch.GetLogData;
%Asynchronous Get log data
timeout = 2000;
wb = Ch.GetLogDataAsync;

Version 3.10 91
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

logData = Ch.GetResult(wb, timeout));

logData = char(logData);

4.9 SPiiPlusSC Log File Management Methods

These methods can only be used with the SPiiPlusSC Motion Controller.

The SPiiPlusSC Log File Management methods are:

Table 3-12. SPiiPlusSC Log File Management Methods

Method Description

OpenSCLogFile Used for opening the SPiiPlusSC log file.

CloseSCLogFile Used for closing the SPiiPlusSC log file.

WriteSCLogFile Used for writing to the SPiiPlusSC log file.

Enables flushing the SPiiPlusSC internal buffer to a specified text file

FlushSCLogFile
from the COM Library application.

4.9.1 OpenSCLogFile
Description
The method opens the SPiiPlusSC log file.
Syntax
object.OpenSCLogFile(filename);
Arguments

filename Vector of characters representing the name or path of the log file.

Return Value
None.
Remarks
The method opens a binary file that stores all SPiiPlusSC log history. The messages are written to
the file in binary format, i.e., exactly as they are received and sent, including all service bytes.
The main use of the SPiiPlusSC log file is for debugging purposes.
Example

%Open SPiiPlusSC log file

Ch.OpenSCLogFile('C:\\SCLogFile2.txt');

Version 3.10 92
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.9.2 CloseSCLogFile
Description
The method closes the SPiiPlusSC log file.
Syntax
object.CloseSCLogFile;
Arguments
None.
Return Value
None.
Remarks
An application must always call CloseSCLogFile before it exits; otherwise, the data written to the
file might be lost.
Example

%Close SPiiPlusSC log file

Ch.CloseSCLogFile;

4.9.3 WriteSCLogFile
Description
The method writes to the SPiiPlusSC log file.
Syntax
object.WriteSCLogFile(buf);
Arguments

buf Vector of characters representing the string to be written to the log file.

Return Value
None.
Remarks
The method writes data from a buffer to the SPiiPlusSC log file.
Example

%Write to SPiiPlusSC log file

Ch.WriteSCLogFile('Hello World!');

4.9.4 FlushSCLogFile
Description
The method enables flushing the SPiiPlusSC internal buffer to a specified text file from the .NET
Library application.

Version 3.10 93
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
object.FlushSCLogFile(filename, bClear);
Arguments

filename Vector of characters that specifies the file name.

Can be TRUE or FALSE:

bClear TRUE – the method clears contents of the log buffer.
FALSE – the log buffer content is not cleared.

Return Value
None.
Remarks
If Continuous Log is active, the function will fail.
Example

%Flush to SPiiPlusSC log file

Ch.FlushSCLogFile('C:\\SCLogFile3.txt', true);

4.10 Shared Memory Methods

The Shared Memory methods have been added in support of SPiiPlusSC Motion
Controller to enable accessing shared memory addresses. They cannot be used with
any other SPiiPlusNT family product.

The Shared Memory methods are:

Table 3-13. Shared Memory Methods

Method Description

GetSharedMemoryAddress Reads the address of shared memory variable.

Reads value(s) from an integer shared memory

ReadSharedMemoryInteger
variable.

ReadSharedMemoryReal Reads value(s) from a real shared memory variable.

Writes value(s) to a real or integer shared memory

WriteSharedMemoryVariable
variable.

4.10.1 GetSharedMemoryAddress
Description
The method reads the address of shared memory variable.

Version 3.10 94
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
address = object.GetSharedMemoryAddress(nBuf, var);
Async Syntax
wb = object.GetSharedMemoryAddressAsync(nBuf, var);
Arguments

Number of program buffer for local variable or ACSC_NONE for global and
nBuf
ACSPL+ variable.

var Vector of characters specifying the variable name.

Return Value

address Scalar specifying the address of shared memory variable.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example
See Shared Memory Program Example

4.10.2 ReadSharedMemoryInteger
Description
The method reads value(s) from an integer shared memory  variable.
Syntax
result = object.ReadSharedMemoryInteger(address, from1, to1, from2, to2);
Arguments

Scalar specifying the address of shared memory variable that should

address
be read.

from1, to1 Index range (first dimension) for one dimensional array variables.

from2, to2 Index range (second dimension) for two dimensional matrix variables.

Return Value

result Scalar or an array of singles

Example
See Shared Memory Program Example

4.10.3 ReadSharedMemoryReal
Description
The method reads value(s) from a real shared memory variable.

Version 3.10 95
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
result = object.ReadSharedMemoryReal( address, from1, to1, from2, to2);
Arguments

Scalar specifying the address of shared memory variable that should be

Address
read.

from1, to1 Index range (first dimension) for one dimensional array variables.

from2, to2 Index range (second dimension) for two dimensional matrix variables.

Return Value

result Scalar or an array of doubles

Returned value is a scalar or an array of doubles

Example
See Shared Memory Program Example

4.10.4 WriteSharedMemoryVariable
Description
The method writes value(s) to the integer or real shared memory variable.
Syntax
object.WriteSharedMemoryVariable(object value, uint address, int from1, int to1, int from2, int
to2);
Arguments

A value to be written. The value could be of integer type or real type or an

value
array of integers or reals.

address Shared memory address of the variable is to written to.

from1, to1 Index range (first dimension) for one dimensional array variables.

from2, to2 Index range (second dimension) for two-dimensional matrix variables.

Return Value
None.
Example
See Shared Memory Program Example

4.10.5 Shared Memory Program Example

CntValues = [ 1, 2, 3, 4 ];
address1 = Ch.GetSharedMemoryAddress(ProgramBuffer.ACSC_NONE,

Version 3.10 96
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

'intVariable');
Ch.WriteSharedMemoryVariable(intValues, address1, 0, 1, 0, 1);
intResults = Ch.ReadSharedMemoryInteger(address1, 0, 1, 0, 1);
realValues = [666.66, 777.77, 888.88, 999.99 ];
address2 = Ch.GetSharedMemoryAddress(ProgramBuffer.ACSC_NONE,
'realVariable');
Ch.WriteSharedMemoryVariable(realValues, address2, 0, 1, 0, 1);
realResults = Ch.ReadSharedMemoryReal(address2, 0, 1, 0, 1);

4.11 System Configuration Methods

The System Configuration methods are:
Table 3-14. System Configuration Methods

Method Description

SetConf The method writes system configuration data.

GetConf The method reads system configuration data.

The function retrieves the volatile memory load in

GetVolatileMemoryUsage
percentage.

The function retrieves the amount of total volatile

GetVolatileMemoryTotal
memory.

The function retrieves the amount of free volatile

GetVolatileMemoryFree
memory.

The function retrieves the non-volatile memory load in

GetNonVolatileMemoryUsage
percentage.

The function retrieves the amount of total non-volatile

GetNonVolatileMemoryTotal
memory.

The function retrieves the amount of free non-volatile

GetNonVolatileMemoryFree
memory.

4.11.1 SetConf
Description
The method writes system configuration data.
Syntax
object.SetConf(key, index, value)
Async Syntax
wb = object.SetConfAsync(key, index, value)

Version 3.10 97
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Scalar representing Configuration Key (see Configuration Keys) that specifies

key the configured feature. Assigns value of key argument in ACSPL+ SetConf
command (see SPiiPlus ACSPL+ Commmand & Variable Reference Guide).

index Specifies corresponding axis or buffer number. Assigns value of index

Value to write to specified key. Assigns value of value argument in ACSPL+

value
SetConf command.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method writes system configuration data. key specifies the feature number and index defines
the axis or buffer to which it should be applied. Use ACSC_CONF_XXX properties in the value field.
For detailed description of system configuration see the description of the SetConf method in the
SPiiPlus ACSPL+ Command and Variable Guide.
If the method fails, the Error object is filled with the error description.
Example

%configuration key 256 corresponding to ConfigKey.ACSC_CONF_DIGITAL_

SOURCE_KEY
key = ConfigKey.GetValue(ConfigKey.ACSC_CONF_DIGITAL_SOURCE_KEY);
%Synchronous Set configuration of axis 0
%Writes system configuration data of axis 0 to 1
Ch.SetConf(key, 0, 1);
%Asynchronous Set configuration of axis 0 to 1
wb = Ch.SetConfAsync(key, 0, 1)

4.11.2 GetConf
Description
The method reads system configuration data.
Syntax
conf = object.GetConf(key, index)
Async Syntax
wb = object.GetConfAsync(key, index)

Version 3.10 98
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Scalar representing Configuration Key (see Configuration Keys) that specifies

key the configured feature. Assigns value of key argument in ACSPL+ SetConf
command (see SPiiPlus ACSPL+ Commmand & Variable Reference Guide).

index Specifies corresponding axis or buffer number. Assigns value of index.

Return Value

conf Scalar specifying system configuration  data.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
key specifies the feature number and index defines axis or buffer to which it should be applied.
For detailed description of system configuration see SPiiPlus ACSPL+ Commmand & Variable
Reference Guide.
If the method fails, the Error object is filled with the error description.
Example

%configuration key 256 corresponding to ConfigKey.ACSC_CONF_DIGITAL_

SOURCE_KEY
key = ConfigKey.GetValue(ConfigKey.ACSC_CONF_DIGITAL_SOURCE_KEY);
%Synchronous Get configuration of axis 0
configuration = Ch.GetConf(key,0);
%Asynchronous Get configuration of axis 0
timeout = 2000;
wb = Ch.GetConfAsync(key, 0);
configuration = Ch.GetResult(wb, timeout);

4.11.3 GetVolatileMemoryUsage
Description
The function retrieves the volatile memory load in percentage.
Syntax
memUsg = object.GetVolatileMemoryUsage;
Async Syntax
wb = object.GetVolatileMemoryUsageAsync;
Arguments
None
Return Value

memUsg Scalar specifying the volatile memory load in percentage.

Version 3.10 99
 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Synchronous Get volatile memory usage

volatileMemUsg = Ch.GetVolatileMemoryUsage;

%Asynchronous Get volatile memory usage

timeout = 2000;
wb = Ch.GetVolatileMemoryUsageAsync;
volatileMemUsg = double(Ch.GetResult(wb, timeout));

4.11.4 GetVolatileMemoryTotal
Description
The function retrieves the amount of total volatile memory.
Syntax
memTotal = object.GetVolatileMemoryTotal;
Async Syntax
wb = object.GetVolatileMemoryTotalAsync
Arguments
None
Return Value

memTotal Scalar specifying the amount of total volatile memory.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Synchronous Get total volatile memory

volatileMemTotal = Ch.GetVolatileMemoryTotal;

%Asynchronous Get total volatile memory

timeout = 2000;
wb = Ch.GetVolatileMemoryTotalAsync;
volatileMemTotal = double(Ch.GetResult(wb, timeout));

4.11.5 GetVolatileMemoryFree
Description
The function retrieves the amount of free volatile memory.

Version 3.10 100

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
freeMem = object.GetVolatileMemoryFree;
Async Syntax
wb = object.GetVolatileMemoryFreeAsync;
Arguments
None
Return Value

freeMem Scalar specifying the amount of free volatile memory.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Synchronous Get volatile memory free

volFreeMem = Ch.GetVolatileMemoryFree;

%Asynchronous Get volatile memory free

timeout = 2000;
wb = Ch.GetVolatileMemoryFreeAsync;
volFreeMem = double(Ch.GetResult(wb, timeout));

4.11.6 GetNonVolatileMemoryUsage
Description
The function retrieves the non-volatile memory load in percentage.
Syntax
memUsg = object.GetNonVolatileMemoryUsage;
Async Syntax
wb = object.GetNonVolatileMemoryUsageAsync;
Arguments
None
Return Value

memUsg Scalar specifying the non-volatile memory load in percentage.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 101

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous Get non-volatile memory usage

nonVolatileMemoryUsage = Ch.GetNonVolatileMemoryUsage;

%Asynchronous Get non-volatile memory usage

timeout = 2000;
wb = Ch.GetNonVolatileMemoryUsageAsync;
nonVolatileMemoryUsage = double(Ch.GetResult(wb, timeout));

4.11.7 GetNonVolatileMemoryTotal
Description
The function retrieves the amount of total non-volatile memory.
Syntax
memTotal = object.GetNonVolatileMemoryTotal;
Async Syntax
wb = object.GetNonVolatileMemoryTotalAsync;
Arguments
None
Return Value

memTotal Scalar specifying the amount of total non-volatile memory.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Synchronous Get total non-volatile memory

nonVolatileMemoryTotal = Ch.GetNonVolatileMemoryTotal;

%Asynchronous Get total non-volatile memory

timeout = 2000;
wb = Ch.GetNonVolatileMemoryTotalAsync;
nonVolatileMemoryTotal = double(Ch.GetResult(wb, timeout));

4.11.8 GetNonVolatileMemoryFree
Description
The function retrieves the amount of free non-volatile memory.
Syntax
freeMem  = object.GetNonVolatileMemoryFree;

Version 3.10 102

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.GetNonVolatileMemoryFreeAsync;
Arguments
None
Return Value

freeMem Scalar specifying the amount of free non-volatile memory.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Synchronous Get free non-volatile memory

nonVolFreeMem = Ch.GetNonVolatileMemoryFree;

%Asynchronous Get free non-volatile memory

timeout = 2000;
wb = Ch.GetNonVolatileMemoryFreeAsync;
nonVolFreeMem = double(Ch.GetResult(wb, timeout));

4.12 Setting and Reading Motion Parameters Methods

The Setting and Reading Motion Parameters methods are:
Table 3-15. Setting and Reading the Motion Parameters Methods

Method Description

SetVelocity Defines a value of motion velocity.

Defines a value of motion velocity having an immediate

SetVelocityImm
effect on any executed as well as impending motion.

GetVelocity Retrieves a value of motion velocity.

SetAcceleration Defines a value of motion acceleration.

Defines a value of motion acceleration having an immediate

SetAccelerationImm
effect on any executed as well as impending motion.

GetAcceleration Retrieves a value of motion acceleration.

SetDeceleration Defines a value of motion deceleration.

Defines a value of motion deceleration having an immediate

SetDecelerationImm
effect on any executed as well as impending motion.

Version 3.10 103

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

GetDeceleration Retrieves a value of motion deceleration.

SetJerk Defines a value of motion jerk.

Defines a value of motion jerk having an immediate effect on

SetJerkImm
any executed as well as impending motion.

GetJerk Retrieves a value of motion jerk.

SetKillDeceleration Defines a value of kill deceleration.

Defines a value of kill deceleration having an immediate

SetKillDecelerationImm
effect on any executed as well as impending motion.

GetKillDeceleration Retrieves a value of kill deceleration.

SetFPosition Assigns a current value of feedback position.

GetFPosition Retrieves a current value of motor feedback position.

SetRPosition Assigns a current value of reference position.

GetRPosition Retrieves a current value of reference position.

GetFVelocity Retrieves a current value of motor feedback velocity.

GetRVelocity Retrieves a current value of reference velocity.

4.12.1 SetVelocity
Description
The method defines a value of motion velocity.
Syntax
object.SetVelocity(axis, velocity);
Async Syntax
wb = object.SetVelocityAsync(axis velocity);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

The value specifies required motion velocity. The value will be used in the
velocity subsequent motions except for the master-slave motions and the motions
activated with the ACSC_AMF_VELOCITY flag.

Version 3.10 104

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method affects the motions initiated after the method call. The method has no effect on any
motion that was started or planned before the method call. To change velocity of an executed or
planned motion, use the SetVelocityImm method.
The method has no effect on the master-slave motions and the motions activated with the
ACSC_AMF_VELOCITY flag.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous Set velocity of axis 0

velocity = 10000;
%Sets the velocity to 10000 to axis 0
Ch.SetVelocity(AxisDefs.ACSC_AXIS_0, velocity);

%Asynchronous Set velocity of axis 0

wb = Ch.SetVelocityAsync(AxisDefs.ACSC_AXIS_0, velocity);

4.12.2 SetVelocityImm
Description
The method defines a value of motion velocity. Unlike SetVelocity, the method has immediate
effect on any executed or planned motion.
Syntax
object.SetVelocityImm(axis, velocity);
Async Syntax
wb = object.SetVelocityImmAsync(axis, velocity);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

velocity The value specifies required motion velocity.

Return Value
None.

Version 3.10 105

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method 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 method call.

> The motions that will be commanded after the method call. The method has no effect
on the master-slave motions.

If the method fails, the Error object is filled with the error description.
Example

%Synchronous Set immediate velocity of axis 0

velocity = 80000;
%Writes the specified value of velocity to the controller
Ch.SetVelocityImm(AxisDefs.ACSC_AXIS_0, velocity);

%Asynchronous Set immediate velocity of axis 0

wb = Ch.SetVelocityImmAsync(AxisDefs.ACSC_AXIS_0, velocity);

4.12.3 GetVelocity
Description
The method retrieves a value of motion velocity.
Syntax
velocity = object.GetVelocity(axis);
Async Syntax
wb = object.GetVelocityAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
Double.
The method retrieves the value of the motion velocity.

Version 3.10 106

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The retrieved value is the value defined by a previous call of SetVelocity or the default value if the
method was not previously called.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous Get velocity of axis 0

%Retrieves a value of motion velocity of the 0 axis
velocity = Ch.GetVelocity(AxisDefs.ACSC_AXIS_0);

%Asynchronous Get velocity of axis 0

timeout = 2000;
wb = Ch.GetVelocityAsync(AxisDefs.ACSC_AXIS_0);
velocity = double(Ch.GetResult(wb, timeout));

4.12.4 SetAcceleration
Description
The method defines a value of motion acceleration.
Syntax
object.SetAcceleration(axis, acceleration);
Async Syntax
wb = object. SetAccelerationImmAsync(axis, acceleration);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions.

The scalar value specifies required motion acceleration. The value will
acceleration
be used in the subsequent motions except the master-slave motions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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.

Version 3.10 107

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The method affects the motions initiated after the method call. The method has no effect on any
motion that was started or planned before the method call. To change acceleration of an executed
or planned motion, use the SetAccelerationImm method.
The method has no effect on the master-slave motions.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous Set acceleration of axis 0

acceleration = 200000;
%Defines a value of motion acceleration to 200000
Ch.SetAcceleration(AxisDefs.ACSC_AXIS_0, acceleration);

%Asynchronous Set acceleration of axis 0

wb = Ch.SetAccelerationAsync(AxisDefs.ACSC_AXIS_0, acceleration);

4.12.5 SetAccelerationImm
Description
The method defines a value of motion acceleration. Unlike SetAcceleration, the method has
immediate effect on any executed and planned motion.
Syntax
object.SetAccelerationImm(axis, acceleration);
Async Syntax
wb = object. SetAccelerationImmAsync(axis, acceleration);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions.

acceleration The value specifies required motion acceleration.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method affects:

> The currently executed motion.

Version 3.10 108

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

> The waiting motions that were planned before the method call.

> The motions that will be commanded after the method call. The method has no effect
on the master-slave motions.

If the method fails, the Error object is filled with the error description.
Example

%Synchronous Set immediate acceleration of axis 0

acceleration = 300000;
%Writes the specified acceleration value to the controller
Ch.SetAccelerationImm(AxisDefs.ACSC_AXIS_0, acceleration);

%Asynchronous Set immediate acceleration of axis 0

wb = Ch.SetAccelerationImmAsync(AxisDefs.ACSC_AXIS_0, acceleration);

4.12.6 GetAcceleration
Description
The method retrieves a value of motion acceleration.
Syntax
acceleration = object.GetAcceleration(axis);
Async Syntax
wb = object.GetAccelerationAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

acceleration Scalar specifying the value of motion acceleration.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

The method retrieves the value of the motion acceleration.

Remarks
The retrieved value is either the value defined by a previous call of the SetAcceleration method or
the default value if there was no previous call of SetAcceleration.
If the method fails, the Error object is filled with the error description.

Version 3.10 109

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous Get acceleration of axis 0

acceleration = Ch.GetAcceleration(AxisDefs.ACSC_AXIS_0);

%Asynchronous Get acceleration of axis 0

timeout = 2000;
wb = Ch.GetAccelerationAsync(AxisDefs.ACSC_AXIS_0);
acceleration = double(Ch.GetResult(wb, timeout));

4.12.7 SetDeceleration
Description
The method defines a value of motion deceleration.
Syntax
object.SetDeceleration(axis,  deceleration);
Async Syntax
wb = object.SetDecelerationAsync(axis, deceleration);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions.

The scalar value specifies a required motion deceleration. The value will
deceleration
be used in the subsequent motions except the master-slave motions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method affects the motions initiated after the method call. The method has no effect on any
motion that was started or planned before the method call. To change deceleration of an executed
or planned motion, use the SetDecelerationImm method.
The method has no effect on the master-slave motions.
If the method fails, the Error object is filled with the error description.

Version 3.10 110

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous set deceleration of axis 0

Ch. SetDeceleration(AxisDefs.ACSC_AXIS_0, 100000);

%Asynchronous set deceleration of axis 0

wb = Ch.SetDecelerationAsync(AxisDefs.ACSC_AXIS_0, 100000);

4.12.8 SetDecelerationImm
Description
The method defines a value of motion deceleration. Unlike SetDeceleration, the method
immediatly affects any executed or intended motion.
Syntax
object.SetDecelerationImm(axis, deceleration);
Async Syntax
wb = object.SetDecelerationImmAsync(axis, deceleration);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

Axis
the axis 1, etc. For the axis constants see Axis Definitions.

The value specifies a required motion deceleration. The value will be

Deceleration
applied to all motions whether in progress or to be started.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method affects:

> The currently executed motion.

> The waiting motions that were planned before the method call.

> The motions that will be commanded after the method call. The method has no effect
on the master-slave motions.

If the method fails, the Error object is filled with the error description. 

Version 3.10 111

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%example of the waiting call of SetDecelerationImm for axis 0

Ch. SetDecelerationImm(AxisDefs.ACSC_AXIS_0, 100000);

%ple asynchronous call of SetDecelerationImm for axis 0

wb = Ch.SetDecelerationImmAsync(AxisDefs.ACSC_AXIS_0, 100000);

4.12.9 GetDeceleration
Description
The method retrieves a value of motion deceleration.
Syntax
deceleration = object.GetDeceleration(axis);
Async Syntax
wb = object.GetDecelerationAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

deceleration
the axis 1, etc. For the axis constants see Axis Definitions.

Return Value

axis Scalar specifying the value of motion deceleration.

The method retrieves the value of the motion deceleration.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The retrieved value is either the value defined by a previous call of the SetDeceleration method or
the default value if SetDeceleration was not previously called.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous get deceleration of axis 0

deceleration = Ch.GetDeceleration(AxisDefs.ACSC_AXIS_0);

%Asynchronous get deceleration of axis 0

wb = Ch.GetDecelerationAsync(AxisDefs.ACSC_AXIS_0);
deceleration = double(Ch.GetResult(wb, 2000));

Version 3.10 112

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.12.10 SetJerk
Description
The method defines a value of motion jerk.
Syntax
object.SetJerk(axis, jerk);
Async Syntax
wb = object.SetJerkAsync(axis, jerk);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

The scalar value specifies a required motion jerk. The value will be used in the
jerk
subsequent motions except for the master-slave motions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method affects the motions initiated after the method call. The method has no effect on any
motion that was started or planned before the method call. To change the jerk of an executed or
planned motion, use the SetJerkImm method.
The method has no effect on the master-slave motions.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous set jerk of axis 0

Ch.SetJerk(AxisDefs.ACSC_AXIS_0, 1000000);

%Asynchronous set jerk of axis 0

wb = Ch.SetJerkAsync(AxisDefs.ACSC_AXIS_0, 1000000);

4.12.11 SetJerkImm
Description
The method defines a value of motion jerk. Unlike SetJerk, the method has an immediate effect on
any executed and pending motion.

Version 3.10 113

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
object.SetJerkImm(axis, jerk);
Async Syntax
wb = object.SetJerkImmAsync(axis, jerk);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

Axis
etc. For the axis constants see Axis Definitions.

Jerk The scalalr value specifies a required motion jerk.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method affects:

> The currently executed motion.

> The waiting motions that were planned before the method call.

> The motions that will be commanded after the method call. The method has no effect
on the master-slave motions.

If the method fails, the Error object is filled with the error description.
Example

%Synchronous set immediate jerk of axis 0

Ch.SetJerkImm(AxisDefs.ACSC_AXIS_0, 1000000);

%Asynchronous set immediate jerk of axis 0

wb = Ch.SetJerkImmAsync(AxisDefs.ACSC_AXIS_0, 1000000);

4.12.12 GetJerk
Description
The method retrieves a value of motion jerk.
Syntax
jerk = object.GetJerk(axis);

Version 3.10 114

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.GetJerkAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

jerk Scalar specifying the value of the motion jerk.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The retrieved value is a value defined by a previous call of SetJerk, or the default value if the
method was not called before.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous get jerk of axis 0

jerk = Ch.GetJerk(AxisDefs.ACSC_AXIS_0);

%Asynchronous get jerk of axis 0

wb = Ch.GetJerkAsync(AxisDefs.ACSC_AXIS_0);
jerk = double(Ch.GetResult(wb, 2000));

4.12.13 SetKillDeceleration
Description
The method defines a value of motion kill deceleration.
Syntax
object.SetKillDeceleration(axis, killDeceleration);
Async Syntax
wb = object.SetKillDecelerationAsync(axis, killDeceleration);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1

axis
to the axis 1, etc. For the axis constants see Axis Definitions.

The scalar value specifies a required motion kill deceleration. The

killDeceleration
value will be used in the subsequent motions.

Return Value
None.

Version 3.10 115

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method affects the motions initiated after the method call. The method has no effect on any
motion that was started or planned before the method call.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous set motion kill deceleration of axis 0

Ch.SetKillDeceleration(AxisDefs.ACSC_AXIS_0, 1000000);

%Asynchronous set motion kill deceleration of axis 0

wb = Ch.SetKillDecelerationAsync(AxisDefs.ACSC_AXIS_0, 1000000);

4.12.14 SetKillDecelerationImm
Description
The method defines a value of motion kill deceleration. Unlike SetKillDeceleration, the method has
an immediate effect on any executed and planned motion.
Syntax
object.SetKillDecelerationImm(axis, killDeceleration);
Async Syntax
object.SetKillDecelerationImmAsync(axis, killDeceleration);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1

Axis
to the axis 1, etc. For the axis constants see Axis Definitions.

The scalar value specifies a required motion kill deceleration. The

KillDeceleration
value will be used in the subsequent motions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method writes the specified value to the controller. One value can be specified for each axis.

Version 3.10 116

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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 method affects:

> The currently executed motion.

> The waiting motions that were planned before the method call.

> The motions that will be commanded after the method call. The method has no effect
on the master-slave motions.

If the method fails, the Error object is filled with the error description.
Example

%Synchronous set immediate motion kill deceleration of axis 0

Ch.SetKillDecelerationImm(AxisDefs.ACSC_AXIS_0, 200000);

%Asynchronous set immediate motion kill deceleration of axis 0

wb = Ch.SetKillDecelerationImmAsync(AxisDefs.ACSC_AXIS_0, 200000);

4.12.15 GetKillDeceleration
Description
The method retrieves a value of motion kill deceleration.
Syntax
killDecl = object.GetKillDeceleration(axis);
Async Syntax
wb = object.GetKillDecelerationAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

killDecl Scalar specifying the value of the motion kill deceleration.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The retrieved value is a value defined by a previous call of SetKillDeceleration, or the default value
if the method was not previously called.
If the method fails, the Error object is filled with the error description.

Version 3.10 117

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous get motion kill deceleration of axis 0

killDeceleration = Ch.GetKillDeceleration(AxisDefs.ACSC_AXIS_0);

%Asynchronous get motion kill deceleration of axis 0

wb = Ch.GetKillDecelerationAsync(AxisDefs.ACSC_AXIS_0);
killDeceleration = double(Ch.GetResult(wb, 2000));

4.12.16 SetFPosition
Description
The method assigns a current value of feedback position.
Syntax
object.SetFPosition(axis, fPosition);
Async Syntax
wb = object.SetFPositionAsync(axis, fPosition);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

fPosition The scalar value specifies the current value of feedback position.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Synchronous set feedback position value of 0 to axis 0

Ch.SetFPosition(AxisDefs.ACSC_AXIS_0, 0);

%Asynchronous set feedback position value of 0 to axis 0

wb = Ch.SetFPositionAsync(AxisDefs.ACSC_AXIS_0, 0);

Version 3.10 118

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.12.17 GetFPosition
Description
The method retrieves the current value of the motor feedback position.
Syntax
fPosition = object.GetFPosition(axis);
Async Syntax
wb = object.GetFPositionAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

fPosition Scalar specifying the current value of the motor feedback position.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The feedback position is a measured position of the motor transferred to user units. If the method
fails, the Error object is filled with the error description.
Example

%Synchronous get motor feedback position

fPosition = Ch.GetFPosition(AxisDefs.ACSC_AXIS_0);

%Asynchronous get motor feedback position

wb = Ch.GetFPositionAsync(AxisDefs.ACSC_AXIS_0);
fPosition = double(Ch.GetResult(wb, 2000));

4.12.18 SetRPosition
Description
The method assigns a current value of reference position.
Syntax
object.SetRPosition(axis, rPosition);
Async Syntax
wb = object.SetRPositionAsync(axis, rPosition);

Version 3.10 119

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

rPosition The sacalar value specifies the current value of reference position.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Synchronous set reference position value of 0 to axis 0

Ch.SetRPosition(AxisDefs.ACSC_AXIS_0, 0);

%Asynchronous set reference position value of 0 to axis 0

wb = Ch.SetRPositionAsync(AxisDefs.ACSC_AXIS_0, 0);

4.12.19 GetRPosition
Description
The method retrieves an instant value of the motor reference position.
Syntax
rPosition = object.GetRPosition(axis);
Async Syntax
wb = object.GetRPositionAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

rPosition Scalar specifying the current value of the motor reference position.

Version 3.10 120

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method retrieves the current value of the motor reference position. The reference position is
a value calculated by the controller as a reference for the motor.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous get instant value of motor reference position

rPosition = Ch.GetRPosition(AxisDefs.ACSC_AXIS_0);

%Asynchronous get instant value of motor reference position

wb = Ch.GetRPositionAsync(AxisDefs.ACSC_AXIS_0);
fPosition = double(Ch.GetResult(wb, 2000));

4.12.20 GetFVelocity
Description
The method retrieves the instantaneous value of the motor feedback velocity. Unlike
GetVelocity, this method retrieves the actually measured velocity and not the required value.
Syntax
fVel = object.GetFVelocity(axis);
Async Syntax
wb = object.GetFVelocityAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

fVel Scalar specifying the instantaneous value of the motor feedback velocity.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The feedback velocity is a measured velocity of the motor transferred to user units. If the method
fails, the Error object is filled with the error description.

Version 3.10 121

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous get instant value of motor feedback velocity

fVelocity = Ch.GetFVelocity(AxisDefs.ACSC_AXIS_0);

%Asynchronous get instant value of motor feedback velocity

wb = Ch.GetFVelocity(AxisDefs.ACSC_AXIS_0);
fVelocity = double(Ch.GetResult(wb, 2000));

4.12.21 GetRVelocity
Description
The method retrieves an instant value of the motor reference velocity.
Syntax
rVel = object.GetRVelocity(axis);
Async Syntax
wb = object.GetRVelocityAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

rVel Scalar specifying the instantaneous value of the motor reference velocity.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The reference velocity is a value calculated by the controller in the process of motion generation.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous get instant value of motor reference velocity

rVelocity = Ch.GetRVelocity(AxisDefs.ACSC_AXIS_0);

%Asynchronous get instant value of motor reference velocity

wb = Ch.GetRVelocity(AxisDefs.ACSC_AXIS_0);
rVelocity = double(Ch.GetResult(wb, 2000));

4.13 Axis/Motor Management Methods

The Axis/Motor Management methods are:

Version 3.10 122

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Table 3-16. Axis/Motor Management Methods

Method Description

Commut Commutates a motor.

Enable Activates an axis.

EnableM Activates several axes.

Disable Shuts off an axis.

DisableAll Shuts off all axes.

DisableExt Shuts off an axis and defines the disable reason.

DisableM Shuts off several axes.

Group Creates a coordinate system for a multi-axis motion.

Split Breaks down a previously created axis group.

SplitAll Breaks down all previously created axis groups.

4.13.1 Commut
Description
The method initiates motor commutation.
Syntax
object.Commut(axis);
Async Syntax
wb = object.CommutAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method commutates a motor. After the commutation, the motor begins to follow the
reference and physical motion is available.
If the method fails, the Error object is populated with the error description.

Version 3.10 123

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

timeout = 5000;
%Commutate axis 0
Ch.Commut(AxisDefs.ACSC_AXIS_0);
%or
%Commutate axis 0 asynchronuously
wb = Ch.CommutAsync(AxisDefs.ACSC_AXIS_0);

% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_

ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is commutated during 5 sec
Ch.WaitMotorCommutated(AxisDefs.ACSC_AXIS_0,motorState, timeout);

4.13.2 Enable
Description
The method activates an axis.
Syntax
object.Enable(axis);
Async Syntax
wb = object.EnableAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method activates an axis. After activation, the axis begins to follow the reference and physical
motion is available.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%or
%Enable axis 0 asynchronuously

Version 3.10 124

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

wb = Ch.EnableAsync(AxisDefs.ACSC_AXIS_0);

% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_

ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is commutated during 5 sec
Ch.WaitMotorCommutated(AxisDefs.ACSC_AXIS_0,motorState, timeout);

4.13.3 EnableM
Description
The method activates several motors.
Syntax
object.EnableM(axes);
Async Syntax
wb = object.EnableMAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method activates several motors. After the activation, the motors begin to follow the
corresponding reference and physical motions for the specified motors are available.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefinitions.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_
AXIS_1, AxisDefs.ACSC_NONE);
%Enable of axes 0 and 1
Ch.EnableM(axes);
%or
%Enable axes 0 and 1 asynchronuously
wb = Ch.EnableMAsync(axes);

Version 3.10 125

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.13.4 Disable
Description
The method shuts off an axis.
Syntax
object.Disable(axis);
Async Syntax
wb = object.DisableAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method shuts off a motor. After shutting off the motor cannot follow the reference and
remains at idle.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Disable axis 0
Ch.Disable(AxisDefs.ACSC_AXIS_0);
%or
%Disable axis 0 asynchronuously
wb = Ch.DisableAsync(AxisDefs.ACSC_AXIS_0);

% Set value of motor state to 0 corresponding to MotorStates.ACSC_NONE

motorState = MotorStates.GetValue(MotorStates.ACSC_NONE);
%Wait till axis 0 is commutated during 5 sec
Ch.WaitMotorCommutated(AxisDefs.ACSC_AXIS_0, motorState, timeout);

4.13.5 DisableAll
Description
The method shuts off all axes.
Syntax
object.DisableAll;

Version 3.10 126

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.DisableAllAsync;
Arguments
None.
Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method has no effect.
If the method fails, the Error object is filled with the error description.
Example

%Disable all motors

Ch.DisableAll;
%or
%Disable all motors asynchronuously
wb = Ch.DisableAllAsync;

4.13.6 DisableExt
Description
The method shuts off an axis and defines the disable reason.
Syntax
object.DisableExt(axis, reason);
Async Syntax
wb = object.DisableExtAsync(axis, reason);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis

axis
1, etc. For the axis constants see Axis Definitions.

Integer number that defines the reason of disabling the axis. The specified
reason value is stored in the MERR variable in the controller and so modifies the
state of the disabled motor.

Return Value
None.

Version 3.10 127

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the ability to separate different
DISABLE commands in the application.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
myCode = 10;
%Disable axis 0 with internal customer code
Ch.DisableExt(AxisDefs.ACSC_AXIS_0, myCode);
%or
%Disable axis 0 with internal customer code asynchronuously
wb = Ch.DisableExtAsync(AxisDefs.ACSC_AXIS_0, myCode);
% Set value of motor state to 0 corresponding to MotorStates.ACSC_NONE
motorState = MotorStates.GetValue(MotorStates.ACSC_NONE);
%Wait till axis 0 is commutated during 5 sec
Ch.WaitMotorCommutated(AxisDefs.ACSC_AXIS_0, motorState, timeout);

4.13.7 DisableM
Description
The method shuts off several axes.
Syntax
object.DisableM(axes);
Async Syntax
wb = object.DisableMAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.

Version 3.10 128

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method shuts off several axes. After the shutting off, the axes cannot follow the
corresponding reference and remain idle.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefinitions.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_
AXIS_1, AxisDefs.ACSC_NONE);
%Disable of axes 0 and 1
Ch.DisableM(axes);
%or
%Disable axes 0 and 1 asynchronuously
wb = Ch.DisableMAsync(axes);

4.13.8 Group
Description
The method creates a coordinate system for a multi-axis motion.
Syntax
object.Group(axes);
Async Syntax
wb = object.GroupAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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.

Version 3.10 129

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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
Split.To split all existing groups, use SplitAll.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefinitions.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_
AXIS_1, AxisDefs.ACSC_NONE);
%Group of axes 0 and 1
Ch.Group(axes);
%or
%Group axes 0 and 1 asynchronuously
wb = Ch.GroupAsync(axes);

4.13.9 Split
Description
The method breaks down a previously created axis group.
Syntax
object.Split(axes);
Async Syntax
wb = object.Split(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants seen Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method breaks down an axis group created before by the Group method. Axes must specify
the same axes as for the Group method that created the group. After the splitting up, the group no
longer exists.
If the method fails, the Error object is filled with the error description.

Version 3.10 130

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefinitions.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_
AXIS_1, AxisDefs.ACSC_AXIS_2, AxisDefs.ACSC_NONE);
%Create group of axes 0, 1 and 2
Ch.Group(axes);
%Split the group of axes 0, 1 and 2.
Ch.Split(axes);
%or
%Split axes 0 and 1 asynchronuously
wb = Ch.SplitAsync(axes);

4.13.10 SplitAll
Description
The method breaks down all axis groups created before.
Syntax
object.SplitAll;
Async Syntax
wb = object.SplitAllAsync;
Arguments
None.
Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method breaks down all axis groups created before by the Group method.
The application may call this method to ensure that no axes are grouped. If no groups currently
exist, the method has no effect.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_AXIS_2, AxisDefs.ACSC_NONE);
%Create group of axes 0, 1 and 2
Ch.Group(axes);
%Split all groups created before
Ch.SplitAll;

Version 3.10 131

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%or
%Split all groups created before asynchronuously
wb = Ch.SplitAllAsync;

4.14 Motion Management Methods

The Motion Management methods are:
Table 3-17. Motion Management Methods

Method Description

Go Starts up a motion that is waiting in the specified motion queue.

Synchronously starts up several motions that are waiting in the specified

GoM
motion queues.

Halt Terminates a motion using the full deceleration profile.

HaltM Terminates several motions using the full deceleration profile.

Kill Terminates a motion using the reduced deceleration profile.

KillAll Terminates all currently executed motions.

KillM Terminates several motions using the reduced deceleration profile.

Terminates a motion using reduced deceleration profile and defines the kill
KillExt
reason.

Terminates a motion immediately and provides a smooth transition to the

Break
next motion.

Terminates several motions immediately and provides a smooth transition

BreakM
to the next motions.

4.14.1 Go
Description
The method starts up a motion waiting in the specified motion queue.
Syntax
object.Go(axis);
Async Syntax
wb = object.GoAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Version 3.10 132

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
A motion that was set with the ACSC_AMF_WAIT flag does not start until the Go method is
executed.The 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 Go method initiates the motion waiting in the motion queue of the specified axis. If no motion
waits in the motion queue, the method has no effect.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is commutated during 5 sec
Ch.WaitMotorCommutated(AxisDefs.ACSC_AXIS_0,motorState, timeout);
%Wait till GO command executed on axis 0,target position of 10000
Ch.ToPoint(MotionFlags.ACSC_AMF_WAIT, AxisDefs.ACSC_AXIS_0,10000);
%Motion Start
Ch.Go(AxisDefs.ACSC_AXIS_0);
%or
%Motion Start asynchronuously
wb = Ch.GoAsync(AxisDefs.ACSC_AXIS_0);
%Finish the motion, End of multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.14.2 GoM
Description
The method synchronously starts up several motions that are waiting in the specified motion
queues.
Syntax
object.GoM(axes);
Async Syntax
wb = object.GoMAsync(axes);

Version 3.10 133

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
Axes motions that were set with the ACSC_AMF_WAIT flag do not start until the GoM method is
executed. The motions wait 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 GoM method 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 the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 10000];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Wait till GO command executed on axes 0 and 1 target position of
10000,10000
Ch.ToPointM(MotionFlags.ACSC_AMF_WAIT, axes, points);
%Start the motion of 0 and 1
Ch.GoM(axes);
%or
%Start the motion of 0 and 1 asynchronuously
wb = Ch.GoMAsync(axes);
%Finish the motion, end of the multi-point motion
Ch.EndSequenceM(axes);

4.14.3 Halt
Description
The method terminates a motion using the full deceleration profile.

Version 3.10 134

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
object.Halt(axis);
Async Syntax
object.HaltAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method has no effect.
The terminated motion finishes using the full third-order deceleration profile and the motion
deceleration value.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
%Relative motion of axis 0,target position of 10000
Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_0, 10000);
%Halt executed to axis 0
Ch.Halt(AxisDefs.ACSC_AXIS_0);
%or
%Halt executed to axis 0 asynchronuously
wb = Ch.HaltAsync(AxisDefs.ACSC_AXIS_0);
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

Version 3.10 135

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.14.4 HaltM
Description
The method terminates several motions using the full deceleration profile.
Syntax
object.HaltM(axes);
Async Syntax
wb = object.HaltMAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method has no effect on the corresponding
axis.
The terminated motions finish using the full third-order deceleration profile and the motion
deceleration values.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 10000];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Relative motion of axes 0 and 1 with target position of 10000,10000
Ch.ToPointM(MotionFlags.ACSC_AMF_RELATIVE, axes, points);
%Halt executed on axes 0 and 1
Ch.HaltM(axes);
%or
%Halt executed on axes asynchronuously

Version 3.10 136

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

wb = Ch.HaltMAsync(axes);
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.14.5 Kill
Description
The method terminates a motion using reduced deceleration profile.
Syntax
object.Kill(axis);
Async Syntax
wb = object.KillAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method has no effect.
The terminated motion finishes with the reduced second-order deceleration profile and the kill
deceleration value.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axes 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
%Relative motion of axis 0,target position of 10000

Version 3.10 137

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_0, 10000);

%Kill axis 0
Ch.Kill(AxisDefs.ACSC_AXIS_0);
%or
%Kill axis 0 asynchronuously
wb = Ch.KillAsync(AxisDefs.ACSC_AXIS_0);
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.14.6 KillAll
Description
The method terminates all currently executed motions.
Syntax
object.KillAll;
Async Syntax
wb = object.KillAllAsync;
Arguments
None.
Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method has no effect.
The terminated motions finish with the reduced second-order deceleration profile and the kill
deceleration values.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 10000];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Relative motion of axes 0 and 1 with target position of 10000,10000

Version 3.10 138

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.ToPointM(MotionFlags.ACSC_AMF_RELATIVE, axes, points);

%Kill axes 0 and 1
Ch.KillAll;
%or
%Kill axes asynchronuously
wb = Ch.KillAllAsync;
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.14.7 KillM
Description
The method terminates several motions using reduced deceleration profile.
Syntax
object.KillM(axes);
Async Syntax
wb = object.KillMAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method has no effect on the corresponding
axis.
The terminated motions finish with the reduced second-order deceleration profile and the kill
deceleration values.
If the method fails, the Error object is filled with the error description.

Version 3.10 139

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 10000];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Relative motion of axes 0 and 1 with target position of 10000,10000
Ch.ToPointM(MotionFlags.ACSC_AMF_RELATIVE, axes, points);
%Kill axes 0 and 1
Ch.KillM(axes);
%or
%Kill axes asynchronuously
wb = Ch.KillMAsync(axes);
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.14.8 KillExt
Description
The method terminates a motion using reduced deceleration profile and defines the kill reason.
Syntax
object.KillExt(axis, reason);
Async Syntax
wb = object.KillExtAsync(axis, reason);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis

axis
1, etc. For the axis constants see Axis Definitions.

Integer number that defines the reason of disabling the axis. The specified
reason value is stored in the MERR variable in the controller and so modifies the
state of the disabled motor.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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.

Version 3.10 140

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If no executed motion involves the specified axis, the method 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 the method fails, the Error object is filled with the error description.
Example

myCode = 10;
timeout = 5000;
%Enable axes 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
%Relative motion of axis 0,target position of 10000
Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_0, 10000);
%Kill axis 0 with internal customer code
Ch.KillExt(AxisDefs.ACSC_AXIS_0, myCode);
%or
% %Kill axis 0 with internal customer code asynchronuously
wb = Ch.KillExtAsync(AxisDefs.ACSC_AXIS_0, myCode);
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.14.9 Break
Description
Terminates a motion immediately and provides a smooth transition to the next motion.
Syntax
object.Break(axis);
Async Syntax
wb = object.BreakAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Version 3.10 141

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method 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 in the junction point. To avoid jerk, the
terminated and next motion must be tangent or nearly tangent in the junction point.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axes 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
%Relative motion of axis 0,target position of 10000
Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_0, 10000);
%Executing of break to axis 0
Ch.Break(AxisDefs.ACSC_AXIS_0);
%or
%Executing of break to axis 0 asynchronuously
wb = Ch.BreakAsync(AxisDefs.ACSC_AXIS_0);
%Change the end of the point to point 0 on the fly
Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_0, 0);
%Finish the motion

Version 3.10 142

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%End of the multi-point motion

Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.14.10 BreakM
Description
Terminates several motions immediately and provides a smooth transition to the next motions.
Syntax
object.BreakM(axes);
Async Syntax
wb = object.BreakMAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 method 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 the method fails, the Error object is filled with the error description.

Version 3.10 143

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 10000];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Relative motion of axes 0 and 1 with target position of 10000,10000
Ch.ToPointM(MotionFlags.ACSC_AMF_RELATIVE, axes, points);
%Execute break to axes 0 and 1
Ch.BreakM(axes);
%or
%Execute break to axes asynchronuously
wb = Ch.BreakMAsync(axes);
%Change the end point to -10000 on the fly
points = [-10000, -10000];
Ch.ToPointM(MotionFlags.ACSC_AMF_RELATIVE, axes, points);
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.15 Point-to-Point Motion Methods

The Point-to-Point Motion methods are:
Table 3-18. Point-to-Point Motion Methods

Method Description

ToPoint Initiates a single-axis motion to the specified point.

ToPointM Initiates a multi-axis motion to the specified point.

Initiates a single-axis motion to the specified point using the specified

ExtToPoint
velocity or end velocity.

Initiates a multi-axis motion to the specified point using the specified

ExtToPointM
velocity or end velocity.

4.15.1 ToPoint
Description
The method initiates a single-axis motion to the specified point.
Syntax
object.ToPoint(flags, axis, point);
Async Syntax
wb = object.ToPointAsync(flags, axis, point);

Version 3.10 144

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Bit-mapped parameter that can include one or more of the following flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the Go method is
executed.
flags 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.
For the MotionFlags constants see Motion Flags.

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

point Coordinate of the target point.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 SetVelocity method or
the default velocity if the method was not called.
To execute multi-axis point-to-point motion, use ToPointM. To execute motion with other motion
velocity or non-zero end velocity, use ExtToPoint or ExtToPointM.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method does not wait for the motion end.
To wait for the motion end, use WaitMotionEnd method.
The motion builds the velocity profile using the required values of velocity, acceleration,
deceleration, and jerk of the specified axis.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);

Version 3.10 145

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Move axis 0 relative to target position of 10000

Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_0, 10000);
%or
%Move axis 0 relative to target position of 10000 asynchronuously
wb = Ch.ToPointAsync(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_0,
10000);
%Wait till motion ends
Ch.WaitMotionEnd(AxisDefs.ACSC_AXIS_0,timeout*2);
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.15.2 ToPointM
Description
The method initiates a multi-axis motion to the specified point.
Syntax
object.ToPointM(flags, axes, points);
Async Syntax
wb = object.ToPointMAsync(flags, axes, points);
Arguments

Bit-mapped parameter that can include one or more of the following flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the GoM method 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
flags
coordinate.
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.
For the MotionFlags constants see Motion Flags.

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1

to the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Array of the target coordinates. The number and order of values must
points correspond to the axes array. The point must specify a value for each
element of axes except the last ACSC_AXIS_NONE element.

Return Value
None.

Version 3.10 146

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 SetVelocity method, or
the default velocity if the method was not called.
To execute single-axis point-to-point motion, use ToPoint method. To execute motion with other
motion velocity or non-zero end velocity, use ExtToPoint or ExtToPointM methods.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method does not wait for the motion end. To wait for the motion end, use
WaitMotionEnd method.
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 the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 10000];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Immediately start the motion of the axes X,Y to the absolute target
points
Ch.ToPointM(MotionFlags.ACSC_NONE, axes, points);
%or
%Immediately start the motion asynchronuously
wb = Ch.ToPointMAsync(MotionFlags.ACSC_NONE, axes, points);
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.15.3 ExtToPoint
Description
The method initiates a single-axis motion to the specified point using the specified velocity or end
velocity.
Syntax
object.ExtToPoint(flags, axis, point, velocity, endVelocity);
Async Syntax
wb = object.ExtToPointAsync(flags, axis, point, velocity, endVelocity);

Version 3.10 147

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Bit-mapped parameter that can include one or more of the following

flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the
Go method 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
flags absolute coordinate.
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.
ACSC_AMF_ENDVELOCITY: the motion will come to the end point with
the velocity specified by the EndVelocity argument.
For the MotionFlags constants see Motion Flags

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions.

point Scalar specifying the oordinate of the target point.

Motion velocity. The argument is used only if the

velocity
ACSC_AMF_VELOCITY flag is specified.

Velocity in the target point. The argument is used only if the ACSC_AMF_
endVelocity ENDVELOCITY flag is specified. Otherwise, the motion finishes with zero
velocity.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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
velocity. Otherwise, the required motion velocity is used. The required motion velocity is the
velocity specified by the previous call of SetVelocity, or the default velocity if the method was not
called.
If the ACSC_AMF_ENDVELOCITY flag is specified, the motion velocity at the final point is specified by
the endVelocity. Otherwise, the motion velocity at the final point is zero.

Version 3.10 148

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

To execute a multi-axis point-to-point motion with the specified velocity or end velocity, use
ExtAddPointM. To execute motion with default motion velocity and zero end velocity, use ToPoint
or ToPointM.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method does not wait for the motion end. To wait for the motion end, use
WaitMotionEnd.
The motion builds the velocity profile using the required values of acceleration, deceleration and
jerk of the specified axis.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
% Set motion flags to Ch.ACSC_AMF_VELOCITY Or Ch.ACSC_AMF_ENDVELOCITY
flags = bitor(MotionFlags.ACSC_AMF_VELOCITY, MotionFlags.ACSC_AMF_
ENDVELOCITY);
startMotionVelocity = 5000;
endMotionVelocity = 1000;
targetPoint = 10000;
%Initiate motion with ExtToPoint
Ch.ExtToPoint(flags,AxisDefs.ACSC_AXIS_0, targetPoint,
startMotionVelocity, endMotionVelocity);
%or
%Initiate motion with ExtToPoint asynchronuously
wb = Ch.ExtToPointAsync(flags,AxisDefs.ACSC_AXIS_0, targetPoint,
startMotionVelocity, endMotionVelocity);
%Wait motion motion during 20 sec
Ch.WaitMotionEnd(AxisDefs.ACSC_AXIS_0,timeout*4);
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.15.4 ExtToPointM
Description
The method initiates a multi-axis motion to the specified point using the specified velocity or end
velocity.
Syntax
object.ExtToPointM(flags, axes, points, velocity, endVelocity);

Version 3.10 149

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.ExtToPointMAsync(flags, axes, points, velocity, endVelocity);
Arguments

Bit-mapped parameter that can include one or more of the following

flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the GoM
method 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
flags absolute coordinate.
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.
ACSC_AMF_ENDVELOCITY: the motion will come to the end point with
the velocity specified by the EndVelocity argument.
For the MotionFlags constants see Motion Flags.

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

AXIS_1 to the axis 1, etc. For the axis constants see Axis Definitions.
axes
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Array of the target coordinates. The number and order of values must
points correspond to the axes array. The point must specify a value for each
element of axes except the last ACSC_AXIS_NONE element

Motion velocity. The argument is used only if the ACSC_AMF_VELOCITY

velocity
flag is specified.

Velocity in the target point. The argument is used only if the ACSC_AMF_
endVelocity ENDVELOCITY flag is specified. Otherwise, the motion finishes with zero
velocity.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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
velocity. Otherwise, the required motion velocity is used. The required motion velocity is the

Version 3.10 150

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

velocity specified by the previous call of SetVelocity, or the default velocity if the method was not
called.
If the ACSC_AMF_ENDVELOCITY flag is specified, the motion velocity at the final point is specified by
the endVelocity. 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
ExtToPoint. To execute a motion with default motion velocity and zero end velocity, use ToPoint or
ToPointM.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method does not wait for the motion end. To wait for the motion end, use the
WaitMotionEnd method.
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 the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 20000];
%Enable axes 0 and 1
Ch.EnableM(axes);
% Set motion flags to Ch.ACSC_AMF_VELOCITY Or Ch.ACSC_AMF_ENDVELOCITY
flags = bitor(MotionFlags.ACSC_AMF_VELOCITY, MotionFlags.ACSC_AMF_
ENDVELOCITY);
startMotionVelocity = 5000;
endMotionVelocity = 1000;
%Initiate motion with ExtToPointM
Ch.ExtToPointM(flags, axes, points, startMotionVelocity,
endMotionVelocity);
%or
%Initiate motion with ExtToPointM asynchronuously
wb = Ch.ExtToPointMAsync(flags, axes, points, startMotionVelocity,
endMotionVelocity);
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.16 Track Motion Control Method

The Track Motion Control method is:
Table 3-19. Track Motion Control Method

Method Description

Track The method initiates a single-axis track motion.

Version 3.10 151

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

SetTargetPosition The method assigns a current value of track position.

GetTargetPosition The method retrieves a current value of track position.

4.16.1 Track
Description
The method initiates a single-axis track motion.
Syntax
object.Track(flags, axis);
Async Syntax
wb = object.TrackAsync(flags, axis);
Arguments

Bit-mapped parameter that can include one or more of the following flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the
flags
Go method is executed.
For the MotionFlags constants see Motion Flags

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a single-axis track motion. After the motion is initialized, PTP motion will be
generated with every change in the TPOS value.
The controller response indicates that the command was accepted and the motion was planned
successfully.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE

Version 3.10 152

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
%Controll the motion of the axis 0 with Track
Ch.Track(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0);
%or
%Controll the motion of the axis 0 with Track asynchronuously
wb = Ch.TrackAsync(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0);
%Set target position to 5000
result = Ch.Transaction('TPOS0=5000');

4.16.2 SetTargetPosition
Description
The method assigns a current value of track position.
Syntax
object.SetTargetPosition(axis, targetPosition);
Async Syntax
wb = object. SetTargetPositionAsync(axis, targetPosition);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions..

targetPosition The value specifies the current value of track position.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE

Version 3.10 153

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%Set target position to zero
Ch.SetTargetPosition(AxisDefs.ACSC_AXIS_0, 0);
%OR set target position to zero asynchronuously
Ch.SetTargetPosition(AxisDefs.ACSC_AXIS_0, 0);
Ch.Track(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0);

4.16.3 GetTargetPosition
Description
The method retrieves a current value of track position.
Syntax
position = object.GetTargetPosition(axis);
Async Syntax
wb = object. SetTargetPositionAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions..

Return Value

position ACSC_Scalar specifying a current value of track position.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%Retreive target position to zero

Version 3.10 154

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

position = Ch.GetTargetPosition(AxisDefs.ACSC_AXIS_0);
%OR retreive target position asynchronuously
wb = Ch.GetTargetPosition(AxisDefs.ACSC_AXIS_0);
position = Ch.GetResult(wb, 2000);

4.17 Jog Methods

The Jog methods are:
Table 3-20. Jog Methods

Method Description

Jog Initiates a single-axis jog motion.

JogM Initiates a multi-axis jog motion.

4.17.1 Jog
Description
The method initiates a single-axis jog motion.
Syntax
object.Jog(flags, axis, velocity);
Async Syntax
wb = object.JogAsync(flags, axis, velocity);
Arguments

Bit-mapped parameter that can include one or more of the following flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the
Go method is executed.
flags
ACSC_AMF_VELOCITY: the motion will use velocity specified by the Velocity
argument instead of the default velocity.
For the MotionFlags constants see Motion Flags

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

Version 3.10 155

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the ACSC_AMF_VELOCITY flag is specified, the velocity profile is built using

the value of velocity. The sign of velocity defines the direction of the
motion.
If the ACSC_AMF_VELOCITY flag is not specified, only the sign of velocity is
velocity used in order to specify the direction of motion.
In this case, set motion flags to:
MotionFlags.ACSC_ALL for negative direction
MotionFlags.ACSC_AMF_WAIT for positive direction.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a single-axis jog. To execute multi-axis jog, use 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 defines the 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 method waits for the controller response.
The controller response indicates that the command was accepted and the motion was planned
successfully. No waiting for the motion end is provided.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
%Initiate a single-axis jog motion to axis 0 to positive direction with
%the specified velocity 10000

Version 3.10 156

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.Jog(MotionFlags.ACSC_AMF_WAIT, AxisDefs.ACSC_AXIS_0,10000);
%or
%Initiate a single-axis jog motion asynchronuously
wb = Ch.JogAsync(MotionFlags.ACSC_AMF_WAIT, AxisDefs.ACSC_AXIS_0,10000);
%Finish the motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.17.2 JogM
Description
The method initiates a multi-axis jog motion.
Syntax
object.JogM(flags, axes, direction, velocity);
Async Syntax
wb = object.JogMAsync(flags, axes, direction, velocity);
Arguments

Bit-mapped parameter that can include one or more of the following flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the GoM method
is executed.
flags
ACSC_AMF_VELOCITY: the motion will use velocity specified by the Velocity
argument instead of the default velocity.
For the MotionFlags constants see Motion Flags

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_

1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Array of directions - The number and order of values must correspond to

the axes array. The direction array must specify direction for each element
of axes except the last ACSC_AXIS_NONE element. The value ACSC_
direction POSITIVE_DIRECTION in the direction array specifies the correspondent
axis to move in positive direction, the value ACSC_NEGATIVE_DIRECTION
specifies the correspondent axis to move in the negative direction.
For the GlobalDirection constants see Motion Flags.

If the ACSC_AMF_VELOCITY flag is specified, the velocity profile is built

velocity using the value of velocity.
If the ACSC_AMF_VELOCITY flag is not specified, velocity is not used.

Return Value
None.

Version 3.10 157

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a multi-axis jog motion. To execute single-axis jog motion, use  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 method waits for the controller response.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method cannot wait or validate the end of the motion. To wait for the motion
end, use WaitMotionEnd
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
directions = GlobalDirection.ToNetArray(GlobalDirection.ACSC_POSITIVE_
DIRECTION, GlobalDirection.ACSC_POSITIVE_DIRECTION);
%Enable axes 0 and 1
Ch.EnableM(axes);
%Start immediately the jog motion of axes X,Y to positive directions
%with the specified velocity 5000
Ch.JogM(MotionFlags.ACSC_NONE, axes, directions,5000);
%or
%Start immediately the jog motion asynchronuously
wb = Ch.JogMAsync(MotionFlags.ACSC_NONE, axes, directions,5000);
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.18 Slaved Motion Methods

The Slaved Motion methods are:
Table 3-21. Slaved Motion Methods

Method Description

SetMaster Initiates calculation of a master value for an axis.

Slave Initiates a master-slave motion.

Version 3.10 158

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

SlaveStalled Initiates master-slave motion with limited following area.

4.18.1 SetMaster
Description
The method initiates calculating of master value for an axis.
Syntax
object.SetMaster(axis, formula);
AsyncSyntax
wb = object.SetMasterAsync(axis, formula);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

formula Vector of characters that specifies a rule for calculating master value.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 SetMaster method is called, the controller is calculates the master value for the specified
axis each controller cycle.
The SetMaster method 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 method waits for the controller response.
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 ACSPL+ or user global
variables as its operands.
If the method fails, the Error object is filled with the error description.

Version 3.10 159

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Master value is calculated as feedback position of the axis T with scale

%factor equal 2
mFormula = '2*T_FPOS';
axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_2, AxisDefs.ACSC_AXIS_3,
AxisDefs.ACSC_NONE);
%Enable axes ZT
Ch.EnableM(axes);
%Set master formula “Z_MPOS=2 * T_FPOS”
Ch.SetMaster(AxisDefs.ACSC_AXIS_2, mFormula);
%or
%Set master formula asynchronuously
wb = Ch.SetMasterAsync(AxisDefs.ACSC_AXIS_2, mFormula);
%Set axis Z to slave
Ch.Slave(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_2);
%Relative motion with target position of 10000
Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_3, 10000);
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.18.2 Slave
Description
The method initiates a master-slave motion.
Syntax
object.Slave(flags, axis);
Async Syntax
wb = object.SlaveAsync(flags, axis);
Arguments

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 method Go is
executed.
flags
ACSC_AMF_POSITIONLOCK: the motion will use position lock. If the flag is not
specified, velocity lock is used (see Remarks).
For the MotionFlags constants see Motion Flags

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.

Version 3.10 160

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a single-axis master-slave motion with an unlimited area of following. If the
area of following must be limited, use SlaveStalled
The master-slave motion continues until the motion is killed or the motion fails for any reason. The
method waits for the controller response.
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 SetMaster method.
The SetMaster method 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 method 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 method activates a position-lock mode of
slaved motion. When synchronized, the APOS axis reference strictly follows the MPOS:
APOS = MPOS
If the method fails, the Error object is filled with the error description.
Example

%factor equal 2
mFormula = '2*T_FPOS';
axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_2, AxisDefs.ACSC_AXIS_3,
AxisDefs.ACSC_NONE);
%Enable axes ZT
Ch.EnableM(axes);
%Set master formula “Z_MPOS=2 * T_FPOS”
Ch.SetMaster(AxisDefs.ACSC_AXIS_2, mFormula);
%Set axis Z to slave
Ch.Slave(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_2);
%or
%Set axis Z to slave asynchronuously
wb = Ch.SlaveAsync(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_2);
%Relative motion with target position of 10000

Version 3.10 161

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_3, 10000);

%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.18.3 SlaveStalled
Description
The method initiates master-slave motion within predefined limits.
Syntax
object.SlaveStalled(flags, axis, left, right);
Async Syntax
wb = object.SlaveStalledAsync(flags, axis, left, right);
Arguments

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 method Go is
executed.
flags
ACSC_AMF_POSITIONLOCK: the motion will use position lock. If the flag is not
specified, velocity lock is used (see Remarks).
For the MotionFlags constants see Motion Flags.

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis etc. For the axis constants see Axis Definitions.

left Left (negative) limit of the axis.

right Right (positive) limit of the axis.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates single-axis master-slave motion within predefined limits. Use Slave to initiate
unlimited motion. For sophisticated forms of master-slave motion, use slaved variants of
segmented and spline motions.
The method waits for the controller response.
The controller response indicates that the command was accepted and the motion was planned
successfully.

Version 3.10 162

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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 SetMaster method.
The SetMaster method 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 method 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 method 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 the method fails, the Error object is filled with the error description.
Example

%factor equal 2
mFormula = '2*T_FPOS';
axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_2, AxisDefs.ACSC_AXIS_3,
AxisDefs.ACSC_NONE);
%Enable axes ZT
Ch.EnableM(axes);
%Set master formula “Z_MPOS=2 * T_FPOS”
Ch.SetMaster(AxisDefs.ACSC_AXIS_2, mFormula);
%Left (negative) limit of the following area,right (positive) limit of
the
%following area
%Initiate master-slave motion
Ch.SlaveStalled(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_2,-5000,5000);
%or
%Initiate master-slave motion asynchronuously
wb = Ch.SlaveStalledAsync(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_2,-
5000,5000);
%Relative motion with target position of 10000
Ch.ToPoint(MotionFlags.ACSC_AMF_RELATIVE, AxisDefs.ACSC_AXIS_3, 10000);
%Finish the motion

Version 3.10 163

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%End of the multi-point motion

Ch.EndSequenceM(axes);

4.19 Multi-Point Motion Methods

The Multi-Point Motion methods are:
Table 3-22. Multi-Point Motion Methods

Method Description

MultiPoint Initiates a single-axis multi-point motion.

MultiPointM Initiates a multi-axis multi-point motion.

4.19.1 MultiPoint
Description
The method initiates a single-axis multi-point motion.
Syntax
object.MultiPoint(flags, axis, dwell);
Async Syntax
wb = object.MultiPointAsync(flags, axis, dwell);
Arguments

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 method 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
flags 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.
For the MotionFlags constants see Motion Flags.

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis

axis
1, etc. For the axis constants see Axis Definitions..

dwell Dwell in each point in milliseconds.

Return Value
None.

Version 3.10 164

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a single-axis multi-point motion. To execute multi-axis multi-point motion, use
MultiPointM.
The motion executes sequential positioning to each of the specified points, optionally with dwell in
each point.
The method 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 AddPoint or ExtAddPoint
methods that follow this method.
The motion finishes when the EndSequence method is executed. If the EndSequence call 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 method EndSequence
executes.
The method waits for the controller response.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method cannot wait or validate the end of the motion. To wait for the motion
end, use the WaitMotionEnd.
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 ExtAddPoint methods is used.
If the method fails, the Error object is filled with the error description.
Example

timeout = 5000;
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, timeout);
%Create multi-point motion of axis 0 with default velocity with dwell 1
ms
Ch.MultiPoint(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0, 1)
% or
% Create multi-point motion asynchronuously
wb = Ch.MultiPointAsync(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0, 1);
%Add some points
for index = 0:4
Ch.AddPoint(AxisDefs.ACSC_AXIS_0, 100 * index)
end
%Finish the motion

Version 3.10 165

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%End of the multi-point motion

Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.19.2 MultiPointM
Description
The method initiates a multi-axis multi-point motion.
Syntax
object.MultiPointM(flags, axes, dwell);
Async Syntax
wb = object.MultiPointMAsync(flags, axes, dwell);
Arguments

Bit-mapped parameter that can include one or more of the following flags:
ACSC_AMF_WAIT: plan the motion but do not start it until the GoM method 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
flags 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.
For the MotionFlags constants see Motion Flags.

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

dwell Dwell in each point in milliseconds.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a multi-axis multi-point motion. To execute single-axis multi-point motion, use
MultiPoint.

Version 3.10 166

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The motion executes sequential positioning to each of the specified points, optionally with dwell in
each point.
The method 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 AddPointM or ExtAddPointM, methods that
follow this method.
The motion finishes when the EndSequenceM method is executed. If the call of 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 method EndSequenceM
executes.
The method waits for the controller response.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method cannot wait or validate the end of the motion. To wait for the motion
end, use the WaitMotionEnd method.
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 ExtAddPointM methods is used.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [10000, 10000];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Create multi-point motion of axis 0 and 1 with default velocity without
%dwell in the points
Ch.MultiPointM(MotionFlags.ACSC_NONE, axes, 0);
% or
% Create multi-point motion asynchronuously
wb =Ch.MultiPointMAsync(MotionFlags.ACSC_NONE, axes, 0);
%Add some points
for index = 0:4
points(1) = 100* index;
points(2) = 100* index;
Ch.AddPointM(axes, points);
end
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.20 Arbitrary Path Motion Methods

The Arbitrary Path Motion methods are:

Version 3.10 167

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Table 3-23. Arbitrary Path Motion Methods

Method Description

Initiates a single-axis spline motion. The motion follows an arbitrary path

Spline
defined by a set of points.

Initiates a multi-axis spline motion. The motion follows an arbitrary path

SplineM
defined by a set of points.

4.20.1 Spline
Description
The method initiates a single-axis spline motion. The motion follows an arbitrary path defined by a
set of points.
Syntax
object.Spline(flags, axis, period);
Async Syntax
wb = object.SplineAsync(flags, axis, period);
Arguments

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 method 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.
flags 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.
ACSC_AMF_CYCLIC: use the point sequence as a cyclic array: after the last
point come to the first point and continue.
ACSC_AMF_CUBIC: use a cubic interpolation between the specified points
(third-order spline).
For the MotionFlags constants see Motion Flags.

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis

axis
1, etc. For the axis constants seeAxis Definitions.

Time interval between adjacent points. The parameter is used only if the
period
ACSC_AMF_VARTIME flag is not specified.

Return Value
None.

Version 3.10 168

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a single-axis spline motion. To execute multi-axis spline motion, use SplineM.
The method waits for the controller response.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method cannot wait or validate the end of the motion. To wait for the motion
end, use the WaitProgramEnd method.
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 AddPoint or ExtAddPoint
methods. The EndSequence method terminates the point sequence. After execution of the
EndSequence method, no AddPoint or ExtAddPoint methods for this motion are allowed.
If flag is not specified, linear interpolation is used (first-order spline).
Time intervals between the points are uniform, or non-uniform as defined by the ACSC_AMF_
VARTIME flag. If ACSC_AMF_VARTIME is not specified, the controller builds PV spline motion.
If ACSC_AMF_VARTIME is specified, the controller builds PVT spline motion. The trajectory of the
motion follows through the defined points. Each point presents the instant desired position at a
specific moment.
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 the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%Create the arbitrary path motion to axis 0, use a cubic interpolation
%between the specified points with uniform interval 500 ms
Ch.Spline(MotionFlags.ACSC_AMF_CUBIC, AxisDefs.ACSC_AXIS_0, 500);
% or
% Create the arbitrary path motion asynchronuously
wb = Ch.SplineAsync(MotionFlags.ACSC_AMF_CUBIC, AxisDefs.ACSC_AXIS_0,
500);
%Add some points
for index = 0:4

Version 3.10 169

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

points(1) = 100*index;
points(2) = 20000*index;
Ch.AddPVPoint(AxisDefs.ACSC_AXIS_0, points(1),points(2));
end
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.20.2 SplineM
Description
The method initiates a multi-axis spline motion. The motion follows an arbitrary path defined by a
set of points.
Syntax
object.SplineM(flags, axes, period);
Async Syntax
wb = object.SplineMAsync(flags, axes, period);
Arguments

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 method 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.
flags 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.
ACSC_AMF_CYCLIC: use the point sequence as a cyclic array: after the last
point come to the first point and continue.
ACSC_AMF_CUBIC: use a cubic interpolation between the specified points
(third-order spline).
For the MotionFlags constants see Motion Flags

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1

to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Time interval between adjacent points. The parameter is used only if the
period
ACSC_AMF_VARTIME flag is not specified.

Version 3.10 170

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method initiates a multi-axis spline motion. To execute a single-axis spline motion, use Spline.
The method waits for the controller response.
The controller response indicates that the command was accepted and the motion was planned
successfully. The method cannot wait or validate the end of the motion. To wait for the motion
end, use the WaitMotionEnd method.
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 AddPVPointM or
ExtAddPointM methods. The EndSequenceM method terminates the point sequence. After
execution of the EndSequenceM method, no AddPointM or ExtAddPointM methods 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 the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = AxisDefs.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [0, 0];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Create the arbitrary path motion to axes 0 and 1 with uniform
%interval 10 ms use a cubic interpolation between the specified points
Ch.SplineM(MotionFlags.ACSC_AMF_CUBIC, axes, 10);
% or
% Create the arbitrary path motion asynchronuously
wb = Ch.SplineMAsync(MotionFlags.ACSC_AMF_CUBIC, axes, 10);
%Add some points
for index = 0:4
points(1) = 100*index;
points(2) = 200*index;

Version 3.10 171

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.AddPVPointM(axes, points, points);

end
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.21 PVT Methods

The PVT methods are:
Table 3-24. PVT Methods

Method Description

AddPVPoint Adds a point to a single-axis multi-point or spline motion.

AddPVPointM Adds a point to a multi-axis multi-point or spline motion.

AddPVTPoint Adds a point to a single-axis multi-point or spline motion.

AddPVTPointM Adds a point to a multi-axis multi-point or spline motion.

4.21.1 AddPVPoint
Description
The method adds a point to a single-axis PV spline motion and specifies velocity.
Syntax
object.AddPVPoint(axis, point, velocity);
Async Syntax
wb = object.AddPVPointAsync(axis, point, velocity);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

point Coordinate of the added point.

velocity Desired velocity at the point

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 172

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
Before this method can be used, initiate PV spline motion by calling Spline with the appropriate
flags.
The method 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 AddPVTPointM and ExtAddPointM.
To add a point to a PVT motion with non-uniform time interval, use the AddPVTPoint and
AddPVTPointM methods. The method waits for the controller response.
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, call this method
periodically until the method returns a non-zero value.
If the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%Create PV motion with uniform time interval with uniform interval 500 ms
Ch.Spline(MotionFlags.ACSC_AMF_CUBIC, AxisDefs.ACSC_AXIS_0, 500);
%Add some points
for index = 0:4
points(1) = 100*index;
points(2) = 20000*index;
Ch.AddPVPoint(AxisDefs.ACSC_AXIS_0, points(1),points(2));
% or add point asynchronuously
wb = Ch.AddPVPointAsync(AxisDefs.ACSC_AXIS_0, points(1),points(2));
end
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.21.2 AddPVPointM
Description
The method adds a point to a multiple-axis PV spline motion and specifies velocity.
Syntax
object.AddPVPointM(axes, point, velocities);
Async Syntax
wb = object.AddPVPointMAsync(axes, point, velocities);

Version 3.10 173

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

AXIS_1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Array of the coordinates of added point. The number and order of values
point must correspond to the axes array. point must specify a value for each
element of axes except the last ACSC_AXIS_NONE element.

Array of the velocities of added point. The number and order of values
velocities must correspond to the axes array. The velocity must specify a value for
each element of axes except the last ACSC_AXIS_NONE element.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
Before this method can be used, PVT spline motion must be initiated by calling SplineM with the
appropriate flags.
The method 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 AddPVPoint. To add a point to a PVT motion with non-
uniform time interval, use the AddPVTPoint and AddPVTPointM methods.
The method waits for the controller response.
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
method periodically until the method returns non-zero value.
All axes specified in the Axes array must be specified before calling the MultiPointM or the SplineM
method. The number and order of the axes in the Axes array must correspond exactly to the
number and order of the axes of MultiPointM or the SplineM methods.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [0, 0];
%Enable axes 0 and 1

Version 3.10 174

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.EnableM(axes);
%Create PV motion with uniform time interval with uniform interval 1000
ms
Ch.SplineM(MotionFlags.ACSC_AMF_CUBIC, axes, 1000);
%Add some points
for index = 0:4
points(1) = 100*(index);
points(2) = 200*(index);
Ch.AddPVPointM(axes, points, points);
% or add points asynchronuously
wb = Ch.AddPVPointMAsync(axes, points, points);
end
%Finish the motion
%End of the multi-point motion
Ch.EndSequenceM(axes);

4.21.3 AddPVTPoint
Description
The method adds a point to a single-axis PVT spline motion and specifies velocity and motion time.
Syntax
object.AddPVTPoint(axis, point,  velocity, timeInterval);
Async Syntax
wb = object.AddPVTPointAsync(axis,  point,  velocity, timeInterval);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions.

point Coordinate of the added point.

velocity Desired velocity at the point

If the motion was activated by the Spline method with the ACSC_AMF_
timeInterval VARTIME flag, this parameter defines the time interval between the
previous point and the present one.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
Before this method can be used, PV spline motion must be initiated by calling Spline with the
appropriate flags.

Version 3.10 175

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The method 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 AddPVTPointM. To add a point to a PV motion with
uniform time interval, use the AddPVPoint and AddPVPointM methods.
The method waits for the controller response.
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
method periodically until the method returns non-zero value.
If the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
points = [0, 0];
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%PVT motion and uniform interval is not used
flags = bitor(MotionFlags.ACSC_AMF_CUBIC, MotionFlags.ACSC_AMF_VARTIME);
Ch.Spline(flags, AxisDefs.ACSC_AXIS_0, 0);
%Add some points
for index = 0:4
points(1) = 100*(index);
points(2) = 200*(index);
%Add PVT point with specified position, velocity
%and time interval of 500 ms for each point
Ch.AddPVTPoint(AxisDefs.ACSC_AXIS_0, points(1), points(2),500);
% or initiate motion asynchronuously
wb = Ch.AddPVTPointAsync(AxisDefs.ACSC_AXIS_0, points(1), points
(2),500);
end
%Finish the motion
%End of the multi-point motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.21.4 AddPVTPointM
Description
The method adds a point to a multiple-axis PVT spline motion and specifies velocity and motion
time.
Syntax
object.AddPVTPointM(axes, point, velocities, timeInterval);
Async Syntax
wb = object.AddPVTPointMAsync(axes, point, velocities, timeInterval);

Version 3.10 176

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

AXIS_1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Array of the coordinates of added point. The number and order of

values must correspond to the axes array. The point must specify a
points
value for each element of axes except the last ACSC_AXIS_NONE
element.

Array of the velocities of added point. The number and order of values
velocities must correspond to the axes array. The velocity must specify a value
for each element of axes except the last ACSC_AXIS_NONE element.

If the motion was activated by the Spline method with the ACSC_AMF_
timeInterval VARTIME flag, this parameter defines the time interval between the
previous point and the present one.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
Before this method can be used, PVT spline motion must be initiated by calling SplineM with the
appropriate flags.
The method 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 AddPVTPoint. To add a point to a PV motion with a
uniform time interval, use the AddPVTPoint and AddPVTPointM methods.
The method waits for the controller response.
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
method periodically until the method returns non-zero value.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);

Version 3.10 177

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

points = [0, 0];

%Enable axes 0 and 1
Ch.EnableM(axes);
flags = bitor(MotionFlags.ACSC_AMF_CUBIC, MotionFlags.ACSC_AMF_VARTIME);
%PVT motion and uniform interval is not used
Ch.SplineM(flags ,axes,0);
%Add some pointsfor index = 0:4
points(1) = 100*(index);
points(2) = 200*(index);
%Add PVT points with specified position, velocity
%and time interval of 1000 ms for each point
Ch.AddPVTPointM(axes, points, points,1000);
% or add points asynchronuously
wb = Ch.AddPVTPointMAsync(axes, points, points,1000);
end%Finish the multi-point motion
Ch.EndSequenceM(axes);

4.22 Segmented Motion Methods

The Segmented Motion methods are:
Table 3-25. Segmented Motion Methods

Method Description

ExtendedSegmentedMotionExt Initiates a multi-axis extended segmented motion.

SegmentLine Adds a linear segment to a segmented motion.

Adds an arc segment to a segmented motion and

specifies the coordinates of center point,
SegmentArc1
coordinates of the final point, and the direction of
rotation.

Adds an arc segment to a segmented motion and

SegmentArc2 specifies the coordinates of center point and
rotation angle.

Provides a smooth transition between two

Stopper
segments of segmented motion.

Projection Sets a projection matrix for a segmented motion.

4.22.1 ExtendedSegmentedMotionExt
Description
The method initiates a multi-axis extended segmented motion. Extended segmented motion
provides new features:

> Corner detection

Version 3.10 178

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

> Detection of segments, where required velocity violates axis velocity/acceleration

limits

> Velocity limitation at corners and problematic segments

> Building up velocity profile using multi-segment look-ahead algorithm

Syntax
object.ExtendedSegmentedMotion(flags, axes, point, velocity, endVelocity, junctionVelocity,
angle, starvationMargin, segments);
Async Syntax
wb = object.ExtendedSegmentedMotionAsync(flags, axes, point, velocity, endVelocity,
junctionVelocity, angle, starvationMargin, segments);

Version 3.10 179

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

> ACSC_AMF_VELOCITY: The motion will use velocity

specified for each segment instead of the default velocity
> ACSC_AMF_ENDVELOCITY: This flag requires additional
parameter that specified end velocity. The controller
decelerates to the specified velocity in the end of
segment. The specified value should be less than the
required velocity; otherwise, the parameter is ignored.
This flag affects only one segment. This flag also disables
corner detection and processing at the end of segment. If
this flag is not specified, deceleration is not required.
However, in special case the deceleration might occur due
to corner processing or other velocity control conditions.
> ACSC_AMF_MAXIMUM: Use maximum velocity under axis
limits. With this suffix, no required velocity should be
specified. The required velocity is calculated for each
segment individually on the base of segment geometry
and axis velocities (VEL values) of the involved axes.
> ACSC_AMF_JUNCTIONVELOCITY: Decelerate to corner. This
flag requires additional parameter that specifies corner
velocity. The controller detects corner on the path and
decelerates to the specified velocity before the corner.
flags
The specified value should be less than the required
velocity; otherwise the parameter is ignored. If ACSC_
AMF_JUNCTIONVELOCTY flag is not specified while the
ACSC_AMF_ANGLE flag is specified, a zero value of corner
velocity is assumed. If ACSC_AMF_JUNCTIONVELOCITY and
ACSC_AMF_ANGLE flags are not specified, the controller
provides automatic calculation as described in Automatic
Corner Processing of the SPiiPlus NT Programmer’s Guide.
> ACSC_AMF_ANGLE: Do not treat junction as a corner, if
junction angle is less than or equal to the specified value
in radians. This flag requires additional parameter that
specifies negligible angle in radians. If ACSC_AMF_ANGLE
flag is not specified while ACSC_AMF_JUNCTIONVELOCITY
flag is specified, the controller accepts default value of
0.01 radians that is about 0.57 degrees. If none of the
ACSC_AMF_JUNCTIONVELOCTY and ACSC_AMF_ANGLE
flags are specified, the controller provides automatic
calculation as described in Automatic corner processing.
> ACSC_AMF_WAIT: plan the motion but do not start it until
the GoM method is executed.
> For the MotionFlags constants see Motion Flags.

Version 3.10 180

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0,

ACSC_AXIS_1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included
that contains ACSC_AXIS_NONE and marks the end of the array.

Array of the coordinates of the initial point on the plane. The

number and order of values must correspond to the axes array.
point
The point must specify a value for each element of axes except
the last ACSC_AXIS_NONE element.

If the ACSC_AMF_VELOCITY flag has been specified, this argument

velocity specifies a motion velocity for the current segment.
Set this argument to -1 if not used.

If the ACSC_AMF_ENDVELOCITY flag has been specified, this

endVelocity argument defines the required velocity at the end of the current
segment. Set this argument to -1 if not used.

If the ACSC_AMF_JUNCTIONVELOCITY flag has been specified, this

junctionVelocity argument defines the required velocity at the junction.
Set this argument to -1 if not used.

If the ACSC_AMF_ANGLE flag has been specified, the junction will

angle be treated as a corner if actual junction angle is more than defined.
Set this argument to -1 if not used.

Starvation margin in milliseconds. The controller sets the

AST.#NEWSEGM bit to StarvationMargin milliseconds before the
starvation condition occurs (see SPiiPlus Command & Variable
starvationMargin Reference Guide for details on AST).
Set this argument to -1 if not used. By default, if this argument is
not specified, the starvation margin is 500 milliseconds.

If the Segments parameter is used, then the starvation margin must also be
defined.

Vector of characters specifying the name of a one-dimensional

segments
user-defined array used to store added segments.

Version 3.10 181

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Set this argument to [ ] if not used. By default, if this argument is

not specified, the controller allocates an internal buffer for storing
50 segments only. The argument allows the user application to
reallocate the buffer for storing a larger number of segments. The
larger number of segments may be required if the application
needs to add many very small segments in advanced.
For most applications, the internal buffer size is enough and does
not need to be enlarged. This buffer is for the controller’s internal
use only and should not be used by the user application.
The buffer size calculation rule: each segment requires about 600
bytes, so if necessary to allocate the buffer for 200 segments, it
should be at least 600
* 200 = 120,000 bytes. The following declaration defines a 120,000
bytes buffer:
real buf(15000)
See the XARRSIZE explanation in the SPiiPlus Command & Variable
Reference Guide for details on how to declare a buffer with more
than 100,000 elements.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [1000, 1000];
center = [1000,0];
%Create segmented motion,coordinates of the initial point are (1000,1000)
Ch.ExtendedSegmentedMotion(MotionFlags.ACSC_NONE, axes, points, -1, -1, -
1, -1, -1,[]);
%or
%Create segmented motion asynchronuously
wb = Ch.ExtendedSegmentedMotionAsync(MotionFlags.ACSC_NONE, axes, points,
-1, -1, -1, -1, -1,[]);
points(1) = 1000;
points(2) = -1000;
Ch.SegmentArc1(MotionFlags.ACSC_NONE,axes,center, points,...
RotationDirection.ACSC_CLOCKWISE,1000,-1,[],[],-1,[]);
Ch.EndSequenceM(axes);

Version 3.10 182

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.22.2 SegmentLine
Description
The method adds a linear segment to segmented motion that starts at the current point and ends
at the destination point.
Syntax
object.SegmentLine(flags, axes, point, velocity, endVelocity, values, variables, index, masks);
Async Syntax
wb = object.SegmentLineAsync(flags, axes, point, velocity, endVelocity, values, variables,
index, masks);
Arguments

> ACSC_AMF_VELOCITY: The motion will use the velocity specified

for each segment instead of the default velocity.
> ACSC_AMF_ENDVELOCITY: This flag requires an additional
parameter that specifies the end velocity. The controller
decelerates to the specified velocity at the end of segment.
The specified value should be less than the required velocity;
otherwise, the parameter is ignored. This flag affects only one
segment. This flag also disables corner detection and
flags processing at the end of segment. If this flag is not specified,
deceleration is not required. However, in special cases, the
deceleration might occur due to corner processing or other
velocity control conditions.
> ACSC_AMF_USERVARIABLES: Synchronizes user variables with
segment execution. This flag requires additional parameters
that specify values, user variable and mask.
> For the MotionFlags constants see Motion Flags

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

AXIS_1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

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
point
specify a value for each element of axes except the last ACSC_AXIS_
NONE element.

If the ACSC_AMF_VELOCITY flag has been specified, this argument

velocity specifies a motion velocity for current segment.
Set this argument to -1 if not used

Version 3.10 183

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the ACSC_AMF_ENDVELOCITY flag has been specified, this argument

endVelocity defines required velocity at the end of the current segment. Set this
argument to -1 if not used.

Vector of characters specifying the name of a one-dimensional user-

defined array of integer or real type with a size of 10 elements
maximum.
values If the ACSC_AMF_USERVARIABLES flag has been specified, this
argument defines the user-defined array, which will be written with
values data at the beginning of the current segment execution.
Set this argument to [ ] if not used.

Vector of characters specifying the name of a one-dimensional user-

defined array of the same type and size as values array.
If the ACSC_AMF_USERVARIABLES flag has been specified, this
variables
argument defines the user-defined array, which will be written with
values data at the beginning of the current segment execution.
Set this argument to [ ] if not used.

If the ACSC_AMF_USERVARIABLES flag is specified, this argument

defines the first element (starting from zero) of variables array, which
index Values data will be written to.
Set this argument to -1 if not used.

Vector of characters specifying the name of a one-dimensional user

defined array of integer type and size as values array.
If the ACSC_AMF_USERVARIABLES flag has been specified, this
argument defines the masks that are applied to values before the
masks values are written to the Variables array at the beginning of the current
segment execution. The masks are only applied for integer values:
Variables(n) = values(n) AND mask(n)
If values is a real array, this argument should be [ ]. Set this argument to
[ ] if not used.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The function adds a linear segment that starts in the current point and ends in the destination
point to segmented motion.

Version 3.10 184

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

All axes specified in the axes array must be specified before the call of
theExtendedSegmentedMotionExt method. The number and order of the axes in the axes array
must correspond exactly to the number and order of the axes of the
ExtendedSegmentedMotionExt method.
The point argument specifies the coordinates of the final point. The coordinates are absolute in the
plane.
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.
This function replaces the Line and ExtLine methods which are now obsolete.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [1000, 1000];
center = [1000,0];
%Create segmented motion,coordinates of the initial point are (1000,1000)
Ch.SegmentedMotion(MotionFlags.ACSC_AMF_VELOCITY,axes,points);
points(1) = 1000;
points(2) = -1000;
%Add a linear segment to segmented motion
Ch.SegmentLine(MotionFlags.ACSC_NONE,axes,points,-1,-1,[],[],-1,[]);
%or
%Add a linear segment to segmented motion asynchronuously
wb = Ch.SegmentLineAsync(MotionFlags.ACSC_NONE,axes,points,-1,-1,[],[],-
1,[]);
Ch.EndSequenceM(axes);

4.22.3 SegmentArc1
Description
The method 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.
Syntax
object.SegmentArc1(flags, axes, center,  finalPoint, rotation, velocity, endVelocity, values,
variables, index, masks);
Async Syntax
wb = object.SegmentArc1Async(flags, axes, center,  finalPoint, rotation, velocity, endVelocity,
values, variables, index, masks);

Version 3.10 185

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Bit-mapped parameter that can include one or more of the following

flags:
> ACSC_AMF_VELOCITY: The motion will use velocity specified for
each segment instead of the default velocity.
> ACSC_AMF_ENDVELOCITY: This flag requires additional
parameter that specifies end velocity. The controller
decelerates to the specified velocity in the end of segment.
The specified value should be less than the required velocity;
otherwise the parameter is ignored. This flag affects only one
flags
segment. This flag also disables corner detection and
processing at the end of segment. If this flag is not specified,
deceleration is not required. However, in special case the
deceleration might occur due to corner processing or other
velocity control conditions.
> ACSC_AMF_USERVARIABLES: Synchronize user variables with
segment execution. This flag requires additional parameters
that specify values, user variable and mask.
For the MotionFlags constants see Motion Flags

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

AXIS_1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Array of the center coordinates. The number and order of values must
center correspond to the axes array. The center must specify a value for each
element of the axes except the last ACSC_AXIS_NONE element.

Array of the final point coordinates. The number and order of values
finalPoint must correspond to the axes array. The finalPoint must specify a value
for each element of axes except the last ACSC_AXIS_NONE element.

This parameter defines the direction of rotation.

> If rotation is set to ACSC_COUNTERCLOCKWISE, then the
rotation
rotation is counterclockwise.
> If rotation is set to ACSC_CLOCKWISE, then rotation is clockwise.

If the ACSC_AMF_VELOCITY flag has been specified, this argument

velocity specifies a motion velocity for current segment.
Set this argument to -1 if not used.

Version 3.10 186

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the ACSC_AMF_ENDVELOCITY flag has been specified, this argument

endVelocity defines required velocity at the end of the current segment. Set this
argument to -1 if not used.

Vector of characters specifying the name of a one-dimensional user-

defined array of integer or real type with a size of 10 elements
maximum.
values If the ACSC_AMF_USERVARIABLES flag has been specified, this
argument defines the user-defined array, which will be written with
values data at the beginning of the current segment execution.
Set this argument to [ ] if not used.

Vector of characters specifying the name of a one-dimensional user-

defined array of the same type and size as Values array.
If the ACSC_AMF_USERVARIABLES flag has been specified, this
variables
argument defines the user-defined array, which will be written with
Values data at the beginning of the current segment execution.
Set this argument to [ ] if not used.

If the ACSC_AMF_USERVARIABLES flag is specified, this argument

defines the first element (starting from zero) of variables array, which
index values data will be written to.
Set this argument to -1 if not used.

Vector of characters specifying the name of a one-dimensional user

defined array of integer type and size as values array.
If the ACSC_AMF_USERVARIABLES flag has been specified, this
argument defines the masks that are applied to values before the
masks values are written to the variables array at the beginning of the current
segment execution. The masks are only applied for integer values:
Variables(n) = values(n) AND mask(n)
If values is a real array, this argument should be [ ]. Set this argument to
[ ] if not used.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
All axes specified in the axes array must be specified before the call of the
ExtendedSegmentedMotionExt methods. The number and order of the axes in the Axes array

Version 3.10 187

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

must correspond exactly to the number and order of the axes of

theExtendedSegmentedMotionExt method.
The method waits for the controller response.
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 method periodically until the method returns non-zero value.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [1000, 1000];
center = [1000,0];
%Create segmented motion,coordinates of the initial point are (1000,1000)
Ch.SegmentedMotion(MotionFlags.ACSC_AMF_VELOCITY,axes,points);
points(1) = 1000;
points(2) = -1000;
%Add an arc segment to segmented motion
Ch.SegmentArc1(MotionFlags.ACSC_NONE,axes,center, points,
RotationDirection.ACSC_CLOCKWISE,1000,-1,[],[],-1,[]);
%or
%Add an arc segment to segmented motion asynchronuously
wb = Ch.SegmentArc1Async(MotionFlags.ACSC_NONE,axes,center, points,
RotationDirection.ACSC_CLOCKWISE,1000,-1,[],[],-1,[]);
Ch.EndSequenceM(axes);

4.22.4 SegmentArc2
Description
Syntax
object.SegmentArc2(flags, axes, center, angle, velocity, endVelocity, values, variables, index,
masks);
Async Syntax
wb = object.SegmentArc2Async(flags, axes, center, angle, velocity, endVelocity, values,
variables, index, masks);

Version 3.10 188

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Bit-mapped parameter that can include one or more of the following

flags:
> ACSC_AMF_VELOCITY: The motion will use velocity specified for
each segment instead of the default velocity.
> ACSC_AMF_ENDVELOCITY: This flag requires additional
parameter that specifies end velocity. The controller
decelerates to the specified velocity in the end of segment.
The specified value should be less than the required velocity;
otherwise the parameter is ignored. This flag affects only one
flags segment.
This flag also disables corner detection and processing at the
end of segment.
If this flag is not specified, deceleration is not required.
However, in special case the deceleration might occur due to
corner processing or other velocity control conditions.
> ACSC_AMF_USERVARIABLES: Synchronize user variables with
segment execution. This flag requires additional parameters
that specify values, user variable and mask.
> For the MotionFlags constants see Motion Flags.

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

AXIS_1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Array of the center coordinates. The number and order of values must
center correspond to the axes array. The center must specify a value for each
element of the axes except the last ACSC_AXIS_NONE element.

If the ACSC_AMF_VELOCITY flag has been specified, this argument

velocity specifies a motion velocity for current segment.
Set this argument to -1 if not used.

If the ACSC_AMF_ENDVELOCITY flag has been specified, this argument

endVelocity defines required velocity at the end of the current segment. Set this
argument to -1 if not used.

Vector of characters specifying the name of a one-dimensional user-

values defined array of integer or real type with a size of 10 elements
maximum.

Version 3.10 189

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the ACSC_AMF_USERVARIABLES flag has been specified, this

argument defines the user-defined array, which will be written with
values data at the beginning of the current segment execution.
Set this argument to [ ] if not used.

Vector of characters specifying the name of a one-dimensional user-

defined array of the same type and size as values array.
If the ACSC_AMF_USERVARIABLES flag has been specified, this
variables
argument defines the user-defined array, which will be written with
values data at the beginning of the current segment execution.
Set this argument to [ ] if not used.

If the ACSC_AMF_USERVARIABLES flag is specified, this argument

defines the first element (starting from zero) of variables array, which
index values data will be written to.
Set this argument to -1 if not used.

Vector of characters specifying the name of a one-dimensional user

defined array of integer type and size as Values array.
If the ACSC_AMF_USERVARIABLES flag has been specified, this
argument defines the masks that are applied to values before the
masks values are written to the variables array at the beginning of the current
segment execution. The masks are only applied for integer values:
Variables(n) = values(n) AND mask(n)
If values is a real array, this argument should be NULL. Set this argument
to -1 if not used.

Rotation angle in radians. Positive angle for counterclockwise rotation,

angle[in]
negative for clockwise rotation.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method adds an arc segment to the segmented motion and specifies the coordinates of the
center point and the rotation angle.
All axes specified in the axes array must be specified before the call of the
ExtendedSegmentedMotionExt method. The number and order of the axes in the axes array must
correspond exactly to the number and order of the axes of the ExtendedSegmentedMotionExt
method.
The method waits for the controller response.

Version 3.10 190

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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 method periodically until the method returns a non-zero value.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [1000, 1000];
center = [1000,0];
%Create segmented motion,coordinates of the initial point are (1000,1000)
Ch.SegmentedMotion(MotionFlags.ACSC_NONE,axes,points);
points(1) = 1000;
points(2) = -1000;
%Add an arc segment to segmented motion
Ch.SegmentArc2(MotionFlags.ACSC_NONE, axes, center, -2*3.141529, -1, -1,
[], [], -1, []);
%or
%Add an arc segment to segmented motion asynchronuously
wb = Ch.SegmentArc2Async(MotionFlags.ACSC_NONE, axes, center, -
2*3.141529, -1, -1, [], [], -1, []);
Ch.EndSequenceM(axes);

4.22.5 Stopper
Description
The method provides a smooth transition between two segments of segmented motion.
Syntax
object.Stopper(axes);
Async Syntax
wb = object.StopperAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 191

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The controller builds the motion so that the vector velocity follows a 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 method is used to avoid velocity jump in the inflection points. If the method 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 the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
point = [1000, 1000];
%Create segmented motion,coordinates of the initial point are (1000,1000)
Ch.EnableM(axes);
Ch.SegmentedMotion(MotionFlags.ACSC_NONE,axes,point);
%Add line segment with final point (1000,-1000),vector velocity 25000
point(1) = 1000;
point(2) = -1000;
Ch.SegmentLine(MotionFlags.ACSC_NONE, axes, point, 25000,...
-1, [], [], -1, []);
%Perform a smooth transition between two segments of segmented motion.
Ch.Stopper(axes);
%or
%Perform a smooth transition asynchronuously
wb = Ch.StopperAsync(axes);
%Add line segment with final point (-1000,-1000),vector velocity 25000
point(1) = 1000;
point(2) = -1000;
Ch.SegmentLine(MotionFlags.ACSC_NONE, axes, point,...
25000, -1, [], [], -1, []);
Ch.Stopper(axes);
%Add line segment with final point (-1000,1000),vector velocity 25000
point(1) = -1000;
point(2) = 1000;
Ch.SegmentLine(MotionFlags.ACSC_NONE, axes, point,...
25000, -1, [], [], -1, []);
Ch.Stopper(axes);
%Add line segment with final point (1000,1000),vector velocity 25000
point(1) = 1000;
point(2) = 1000;
Ch.SegmentLine(MotionFlags.ACSC_NONE, axes, point,...
25000, -1, [], [], -1, []);

Version 3.10 192

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Finish the multi-point motion

Ch.EndSequenceM(axes);

4.22.6 Projection
Description
The method sets a projection matrix for segmented motion.
Syntax
object.Projection(axes, matrix);
Async Syntax
wb = object.ProjectionAsync(axes, matrix);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1

to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Vector of characters specifying the name of the matrix that provides the
matrix
specified projection.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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
DeclareVariable method and must be initialized by an ACSPL+ program or by the method. For more
information about projection, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,

Version 3.10 193

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

AxisDefs.ACSC_NONE);
points = [1000, 1000];
center = [1000,0];
matrix = zeros(3,2);
matrix(1,1) = 1;
matrix(2,2) = 1.41421;
matrix(3,2) = 1.41421;
%Declare the matrix that will contain the projection
Ch.DeclareVariable(AcsplVariableType.ACSC_REAL_TYPE,...
'ProjectionMatrix(3)(2)');
%Initialize the projection matrix
Ch.WriteVariable(matrix,'ProjectionMatrix',ProgramBuffer.ACSC_NONE);
Ch.EnableM(axes);
%Create a group of the involved axes
Ch.Group(axes);
%Create segmented motion,coordinates of the initial point are
(10000,10000)
Ch.SegmentedMotion(MotionFlags.ACSC_NONE,axes,points);
%Incline the working plance XY by 45 degrees.
inclAxes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1...
, AxisDefs.ACSC_AXIS_1, AxisDefs.ACSC_NONE);
%Set projection matrix for segmented motion.
Ch.Projection(inclAxes,'ProjectionMatrix');
%or
%Set projection matrix for segmented motion asynchronuously
wb = Ch.ProjectionAsync(inclAxes,'ProjectionMatrix');
%Describe circle with center (1000, 0) clockwise rotation.
%Althought the circle was defined,really on the plane XY we
%will get the ellipse stretched along the Y axis
Ch.SegmentArc2(MotionFlags.ACSC_NONE, axes, center,...
-2*3.141529, -1, -1, [], [], -1, []);
Ch.EndSequenceM(axes);

4.23 Points and Segments Manipulation Methods

The Points and Segments Manipulation methods are:
Table 3-26. Points and Segments Manipulation Methods

Method Description

AddPoint Adds a point to a single-axis multi-point or spline motion.

AddPointM Adds a point to a multi-axis multi-point or spline motion.

Adds a point to a single-axis multi-point or spline motion and

ExtAddPoint
specifies a specific velocity or motion time.

Adds a point to a multi-axis multi-point or spline motion and specifies

ExtAddPointM
a specific velocity or motion time.

Version 3.10 194

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

Informs the controller that no more points will be specified for the
EndSequence
current single-axis motion.

Informs the controller that no more points or segments will be

EndSequenceM
specified for the current multi-axis motion.

4.23.1 AddPoint
Description
The method adds a point to a single axis multi-point or spline motion.
Syntax
object.AddPoint(axis, point);
Async Syntax
wb = object.AddPointAsync(axis, point);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

point Coordinate of the added point.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method adds a point to a single-axis multi-point or spline motion. To add a point to a multi- axis
motion, use AddPVPointM. To add a point with a specified non-default velocity or time interval use
ExtAddPoint or ExtAddPointM.
The method waits for the controller response.
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
method periodically until the method returns a non-zero value.
If the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
points = [0, 0];
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_

Version 3.10 195

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%Create multi-point motion with default velocity and dwell 1 ms
Ch.MultiPoint(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0,1);
for index = 0:4
%Add a point to a single axis multi-point motion.
Ch.AddPoint(AxisDefs.ACSC_AXIS_0,100*index);
% or add a point to a single axis multi-point motion asynchronuously
wb = Ch.AddPointAsync(AxisDefs.ACSC_AXIS_0,100*index);
end
%Finish the motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

4.23.2 AddPointM
Description
The method adds a point to a multi-axis multi-point or spline motion.
Syntax
object.AddPointM(axes, point);
Async Syntax
wbb = object.AddPointMAsync(axes, point);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Array of the coordinates of added point. The number and order of values must
point correspond to the axes array. point must specify a value for each element of
axes except the last  –1 element.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method adds a point to a multi-axis multi-point or spline motion. To add a point to a single- axis
motion, use AddPoint. To add a point with a specified non-default velocity or time interval use
ExtAddPoint or ExtAddPointM.

Version 3.10 196

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The method waits for the controller response.

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
method periodically until the method returns non-zero value.
All axes specified in the axes array must be specified before the call of the MultiPointM or SplineM
method. The number and order of the axes in the axes array must correspond exactly to the
number and order of the axes of MultiPointM or SplineM methods.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [0, 0];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Create multi-point motion with default velocity without dwell
Ch.MultiPoint(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0, 0);
%Add some pointsfor index = 0:4
points(1) = 100 * index;
points(2) = 200 * index;
%Add points to a single axis multi-point motion.
Ch.AddPointM(axes, points);
% or add points asynchronuously
wb = Ch.AddPointMAsync(axes, points);
end%Finish the multi-point motion
Ch.EndSequenceM(axes);

4.23.3 ExtAddPoint
Description
The method adds a point to a single-axis multi-point or spline motion and specifies a specific
velocity or motion time.
Syntax
object.ExtAddPoint(axis, point, rate);
Async Syntax
wb = object.ExtAddPointAsync(axis, point, rate);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

point Coordinate of the added point.

Version 3.10 197

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the motion was activated by the MultiPoint method with the ACSC_AMF_
VELOCITY flag, this parameter defines the motion velocity.
rate If the motion was activated by the Spline method with the ACSC_AMF_
VARTIME flag, this parameter defines the time interval between the previous
point and the present one.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 ExtAddPointM. To add a point to a motion with default
velocity or uniform time interval, the AddPoint and AddPointM methods are more convenient.
The method waits for the controller response.
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
method periodically until the method returns a non-zero value.
If the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
points = [0, 0];
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%Create multi-point motion with default velocity and dwell 1 ms
Ch.MultiPoint(MotionFlags.ACSC_AMF_VELOCITY, AxisDefs.ACSC_AXIS_0,1);
for index = 0:4
%Add a point to a single axis multi-point motion with specified
velocity.
Ch.ExtAddPoint(AxisDefs.ACSC_AXIS_0,100*index, 5000);
% or add a point to a single axis multi-point motion asynchronuously
wb = Ch.ExtAddPointAsync(AxisDefs.ACSC_AXIS_0,100*index, 5000);
end%Finish the motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

Version 3.10 198

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.23.4 ExtAddPointM
Description
The method adds a point to a multi-axis multi-point or spline motion and specifies a specific velocity
or motion time.
Syntax
object.ExtAddPointM(axes, point, rate);
Async Syntax
wb = object.ExtAddPointMAsync(axes, point, rate);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc.
axes For the axis constants see n Axis Definitions.
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Array of the coordinates of added point. The number and order of values must
point correspond to the axes array. The point must specify a value for each element
of axes except the last ACSC_AXIS_NONE element.

If the motion was activated by the MultiPoint method with the ACSC_AMF_
VELOCITY flag, this parameter defines the motion velocity.
rate If the motion was activated by the Spline method with the ACSC_AMF_
VARTIME flag, this parameter defines the time interval between the previous
point and the present one.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method adds a point to a multi-axis multi-point or spline motion. To add a point to a single- axis
motion, use ExtAddPoint. To add a point with to a motion with default velocity or uniform time
interval the ExtAddPoint and ExtAddPointM methods are more convenient.
The method waits for the controller response.
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
method periodically until the method returns a non-zero value.

Version 3.10 199

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

All axes specified in the axes array must be specified before calling the MultiPointM or SplineM
methods. The number and order of the axes in the axes array must correspond exactly to the
number and order of the axes of MultiPointM or SplineM methods.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [0, 0];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Create multi-point motion with default velocity without dwell
Ch.MultiPointM(MotionFlags.ACSC_AMF_VELOCITY, axes, 0);
%Add some points
for index = 0:4
points(1) = 100 * index;
points(2) = 100 * index;
%Add points to a single axis multi-point motion.
Ch.ExtAddPointM(axes, points,5000);
% or add points asynchronuously
wb = Ch.ExtAddPointMAsync(axes, points,5000);
end
%Finish the multi-point motion
Ch.EndSequenceM(axes);

4.23.5 EndSequence
Description
The method informs the controller that no more points will be specified for the current single- axis
motion.
Syntax
object.EndSequence(axis);
Async Syntax
wb = object.EndSequenceAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 200

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The motion finishes when the EndSequence method is executed. If the call of 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 EndSequence method
executes. The method waits for the controller response.This method applies to the single-axis
multi-point or spline (arbitrary path) motions. If the method fails, the Error object is filled with the
error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
points = [0, 0];
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
%Create multi-point motion with default velocity and dwell 1 ms
Ch.MultiPoint(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0,1);
for index = 0:4
%Add a point to a single axis multi-point motion.
Ch.AddPoint(AxisDefs.ACSC_AXIS_0,100*index);
end
%Finish the motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);
% or finish the motion asynchronuously
wb = Ch.EndSequenceAsync(AxisDefs.ACSC_AXIS_0);

4.23.6 EndSequenceM
Description
The method informs the controller that no more points or segments will be specified for the
current multi-axis motion.
Syntax
object.EndSequence(axes);
Async Syntax
wb = object.EndSequenceAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that contains
ACSC_AXIS_NONE and marks the end of the array.

Version 3.10 201

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The motion finishes when the EndSequenceM method is executed. If the call of 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 EndSequenceM
method executes.
The method waits for the controller response.
This method applies to the multi-axis multi-point, spline (arbitrary path) and segmented motions.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
points = [0, 0];
%Enable axes 0 and 1
Ch.EnableM(axes);
%Create multi-point motion with default velocity without dwell
Ch.MultiPoint(MotionFlags.ACSC_NONE, AxisDefs.ACSC_AXIS_0, 0);
%Add some points
for index = 0:4
points(1) = 100 * index;
points(2) = 200 * index;
%Add points to a single axis multi-point motion.
Ch.AddPointM(axes, points);
% or add points asynchronuously
wb = Ch.AddPointMAsync(axes, points);
end
%Finish the multi-point motion
Ch.EndSequenceM(axes);
%Or finish the multi-point motion
Ch.EndSequenceMAsync(axes);

4.24 Data Collection Methods

The Data Collection methods are:
Table 3-27. Data Collection Methods

Method Description

DataCollectionExt Initiates data collection.

Version 3.10 202

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

StopCollect Terminates data collection.

4.24.1 DataCollectionExt
Description
The method initiates data collection.
Syntax
object.DataCollectionExt(DataCollectionFlags flags, Axis axis, string array, int nSample, double
period, string vars);
Async Syntax
wb = object.DataCollectionExtAsync(DataCollectionFlags flags, Axis axis, string array, int
nSample, double period, string vars);
Arguments

Bit-mapped parameter that can include one or more of the following flags:
ACSC_DCF_SYNC – Start data collection synchronously to a motion.
ACSC_DCF_ WAIT – Create the synchronous data collection, but do not start
until the Go method is called. This flag can only be used with the ACSC_DCF_
SYNC flag.
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.

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis axis 1, etc. For the axis constants see Axis Definitions.
This argument is required only for axis data collection (ACSC_DCF_SYNC flag).

Vector of characters specifying the array name that stores the collected
samples.
array
The array must be declared as a global variable by an ACSPL+ program or by
the DeclareVariable method.

nSample Number of samples to be collected.

Sampling period in milliseconds.

period If the ACSC_DCF_TEMPORAL flag is specified, this parameter defines a
minimal period.

Version 3.10 203

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Vector of characters specifying names of the variables, separated by ‘\r’ (13)

character. The values of these variables will be collected in the array. If
vars
variable name specifies an array, the name must be supplemented with
indexes in order to specify one element of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
Data collection started by this method without the ACSC_DCF_SYNC flag is called system data
collection.
Data collection started with the ACSC_DCF_SYNC flag, is called axis data collection.
Data collection started with ACSC_DCF_CYCLIC flag, called cyclic data collection. Unlike the standard
data collection that finishes when the collection array is full, cyclic data collection does not self-
terminate. Cyclic data collection uses the collection array as a cyclic buffer and can continue to
collect data indefinitely. When the array is full, each new sample overwrites the oldest sample in
the array. Cyclic data collection can only be terminated by calling the StopCollect method.
The array that stores the samples can be one or two-dimensional. A one-dimensional array is
allowed only if the variable list contains one variable name.
The number of the array rows must be equal to or more than the number of variables in the
variable list. The number of the array columns must be equal to or more than the number of
samples specified by the nSample argument.
If the method fails, the Error object is filled with the error description.
Example

flags = DataCollectionFlags.ACSC_DCF_WAIT;
vars = 'FPOS(0)\rFVEL(0)\rFACC(0)';
%Initiate data collection.
Ch.DataCollection(flags, AxisDefs.ACSC_AXIS_0, 'MyArrayForDC', 100, 100,
vars);
%or initiate data collection asynchronuously
wb = Ch.DataCollectionAsync(flags, AxisDefs.ACSC_AXIS_0, 'MyArrayForDC',
100, 100, vars);

4.24.2 StopCollect
Description
The method terminates data collection.
Syntax
object.StopCollect;

Version 3.10 204

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.StopCollectAsync;
Arguments
None.
Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The usual system data collection finishes when the required number of samples is collected or the
StopCollect method is executed. The application can wait for data collection end with the
WaitCollectEnd method.
The temporal data collection runs until the StopCollect method is executed.
The method 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 the method fails, the Error object is filled with the error description.
Example

vars = 'FPOS(0) & Chr$(13)& FPOS(1)';

%Matrix with dimensions 2x1000
arrayName = 'DCA(2)(1000)';
%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);
points = [0, 0];
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);
flags = bitor(MotionFlags.ACSC_AMF_VELOCITY, MotionFlags.ACSC_AMF_
ENDVELOCITY);
Ch.ExtToPoint(flags, AxisDefs.ACSC_AXIS_0,10000,5000,1000);
%Array to collect
Ch.DeclareVariable(AcsplVariableType.ACSC_REAL_TYPE, arrayName);
Ch.DataCollection(DataCollectionFlags.ACSC_NONE,...
AxisDefs.ACSC_AXIS_0, arrayName, 1000, 1, vars);
%Stop Collect
Ch.StopCollect;
%or stop collect asynchronuously
wb = Ch.StopCollectAsync;
%Finish the motion
Ch.EndSequence(AxisDefs.ACSC_AXIS_0);

Version 3.10 205

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.25 Status Report Methods

The Status Report methods are:
Table 3-28. Status Report Methods

Method Description

GetMotorState Retrieves the current motor state.

GetAxisState Retrieves the current axis state.

GetIndexState Retrieves the current state of the index and mark variables.

ResetIndexState Resets the specified bit of the index/mark state.

GetProgramState Retrieves the current state of the program buffer.

4.25.1 GetMotorState
Description
The method retrieves the current motor state.
Syntax
motorState = object.GetMotorState(axis);
Async Syntax
wb = object.GetMotorStateAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

motorState Set of Motor State Flags constants specifying the current motor state.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The retrieved value 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
If the method fails, the Error object is filled with the error description.

Version 3.10 206

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous get motor state

state = Ch.GetMotorState(AxisDefs.ACSC_AXIS_0);

%Asynchronous get motor state

wb = Ch.GetMotorState(AxisDefs.ACSC_AXIS_0);
state = Ch.GetResult(wb, 2000);

4.25.2 GetAxisState
Description
The method retrieves the current axis state.
Syntax
axisStates = object.GetAxisState(axis);
Async Syntax
wb = object.GetAxisStateAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

axisStates Set of Axis State Flags constants specifying the current motor state.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The return value can comprise one or more flags. For example, ACSC_AST_LEAD (leading axis),
ACSC_AST_DC (data collection in progress for the axis), etc. For the complete list of flags, see Axis
State Flags If the method fails, the Error object is filled with the error description.
Example

%Synchronous get axis state

states = Ch.GetAxisState(AxisDefs.ACSC_AXIS_0);

%Asynchronous get axis state

wb = Ch.GetAxisStateAsync(AxisDefs.ACSC_AXIS_0);
states = Ch.GetResult(wb, 2000);

4.25.3 GetIndexState
Description
The method retrieves the current set of bits that indicate the index and mark state.

Version 3.10 207

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
indexStates = object.GetIndexState(axis);
Async Syntax
wb = object.GetIndexStateAsync(axis)
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

Set of Index and Mark State Flags constants specifying the current
indexStates
motor state.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The return value 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
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
ResetIndexState to explicitly reset the corresponding bit.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous get index state

states = Ch.GetIndexState(AxisDefs.ACSC_AXIS_0);

%Asynchronous get index state

wb = Ch.GetIndexStateAsync(AxisDefs.ACSC_AXIS_0);
states = Ch.GetResult(wb, 2000);

4.25.4 ResetIndexState
Description
The method resets the specified bit of the index/mark state.

Version 3.10 208

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
object.ResetIndexState(axis, mask);
Async Syntax
wb = object.ResetIndexStateAsync(axis, mask);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

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
mask 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.
For the axis constants see Index and Mark State Flags.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method resets the specified bit of the index/mark state. mask contains a bit that must be
cleared, i.e., the method resets only that bit of the index/mark state, which corresponds to non-
zero bit of mask. To get the current index/mark state, use the GetIndexState method.
If the method fails, the Error object is filled with the error description.
Example

%Reset the specified bit of the index/mark state

Ch.ResetIndexState(AxisDefs.ACSC_AXIS_0,IndexStates.ACSC_IST_IND);
%or reset the specified bit of the index/mark state asynchronuously
wb = Ch.ResetIndexStateAsync(AxisDefs.ACSC_AXIS_0,IndexStates.ACSC_IST_
IND);

Ch.ResetIndexState(AxisDefs.ACSC_AXIS_0,IndexStates.ACSC_IST_IND2);
Ch.ResetIndexState(AxisDefs.ACSC_AXIS_0,IndexStates.ACSC_IST_MARK);
Ch.ResetIndexState(AxisDefs.ACSC_AXIS_0,IndexStates.ACSC_IST_MARK2);
state = Ch.GetIndexState(AxisDefs.ACSC_AXIS_0);

Version 3.10 209

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.25.5 GetProgramState
Description
The method retrieves the current state of the program buffer.
Syntax
prgStates = object.GetProgramState(buffer);
Async Syntax
wb = object.GetProgramStateAsync(buffer);
Arguments

buffer Number of the buffer in which the program resides.

Return Value

prgStates Set of Program State Flags constants specifying the current motor state..

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The retrieved value 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
If the method fails, the Error object is filled with the error description.
Example

%Append one line to buffer 0

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_0, '!Empty buffer;stop');
%Run buffer 0
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_0,[]);
%Retrieve the current state of the program buffer
prgStates = Ch.GetProgramState(ProgramBuffer.ACSC_BUFFER_0);
%or Retrieve the current state of the program buffer asynchronuously
wb = Ch.GetProgramStateAsync(ProgramBuffer.ACSC_BUFFER_0);
prgStates = Ch.GetResult(wb, 2000);

4.26 Inputs/Outputs Access Methods

The Inputs/Outputs Access methods are:

Version 3.10 210

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Table 3-29. Inputs/Outputs Access Methods

Method Description

GetInput Retrieves the current state of the specified digital input.

GetInputPort Retrieves the current state of the specified digital input port.

GetOutput Retrieves the current state of the specified digital output.

GetOutputPort Retrieves the current state of the specified digital output port.

SetOutput Sets the specified digital output to the specified value.

SetOutputPort Sets the specified digital output port to the specified value.

GetAnalogInputNT Retrieves the current value of the specified analog input.

GetAnalogOutputNT Retrieves the current value of the specified analog output.

SetAnalogOutputNT Writes the specified value to the specified analog output.

GetExtInput Retrieves the current state of the specified extended input.

Retrieves the current state of the specified extended input

GetExtInputPort
port.

GetExtOutput Retrieves the current state of the specified extended output.

Retrieves the current state of the specified extended output

GetExtOutputPort
port.

SetExtOutput Sets the specified extended output to the specified value.

SetExtOutputPort Sets the specified extended output port to the specified value.

4.26.1 GetInput
Description
The method retrieves the current state of the specified digital input.
Syntax
state = object.GetInput(port, bit);
Async Syntax
wb = object.GetInputAsync(port, bit);
Arguments

port Number of the input port.

Version 3.10 211

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

bit Number of the specific bit.

Return Value

state Scalar specifying the current state of the specified digital input.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get values of all inputs of the specific port, use the GetInputPort method.
Digital inputs are represented in the controller variable IN. For more information about digital
inputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%Synchronous call example

%The method reads input 0 of port 0 ( IN(0).0 )
state = Ch.GetInput(0,0);

%Asynchronous call example

wb = Ch.GetInputAsync(0,0);
state = Ch.GetResult(wb, 2000);

4.26.2 GetInputPort
Description
The method retrieves the current state of the specified digital input port.
Syntax
state  = object.GetInputPort(port);
Async Syntax
wb = object.GetInputPortAsync(port);
Arguments

port Number of the input port.

Return Value

state Scalar specifying the current state of the specified digital input port.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get the value of the specific input of the specific port, use the GetInput method.

Version 3.10 212

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Digital inputs are represented in the controller variable IN. For more information about digital
inputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

port = zeros(1, 16);

port1 = zeros(1, 16);
%The method reads input port 0 to 15 ( IN(0) to IN(15) )
for index = 1:length(port)
% Get state of input by index
port(index) = Ch.GetInputPort(index-1);
%or get state of input by index asynchronuously
wb = Ch.GetInputPortAsync(index-1);
port1(index) = Ch.GetResult(wb, 2000);
end

4.26.3 GetOutput
Description
The method retrieves the current state of the specified digital output.
Syntax
state = object.GetOutput(port, bit);
Async Syntax
wb = object.GetOutputAsync(port, bit);
Arguments

port Number of the output port.

bit Number of the specific bit.

Return Value

state Scalar specifying the current state of the specified digital output.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get values of all outputs of the specific port, use GetExtOutputPort.
Digital outputs are represented in the controller variable OUT. For more information about digital
outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.

Version 3.10 213

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous call example

%The method reads output 0 of port 0 ( OUT(0).0 )
port = Ch.GetOutput(0,0);

%Asynchronous call example

timeout = 2000;
wb = Ch.GetOutputAsync(0,0);
port = Ch.GetResult(wb, 2000);

4.26.4 GetOutputPort
Description
The method retrieves the current state (0 or 1) of the specified digital output port.
Syntax
state = object.GetOutputPort(port);
Async Syntax
wb = object.GetOutputPortAsync(port);
Arguments

port Number of the output port.

Return Value

state Scalar specifying the current state of the specified digital output.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get the value of the specific output of the specific port, use GetOutput.
Digital outputs are represented in the controller variable OUT. For more information about digital
outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

port = zeros(1, 16);

port1 = zeros(1, 16);
%The method reads output port 0 to 15 ( OUT(0) to OUT(15) )
for index = 1:length(port)
% Get state of output by index
port(index) = Ch.GetOutputPort(index-1);
%or get state of output by index asynchronuously
wb = Ch.GetOutputPortAsync(index-1);

Version 3.10 214

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

port1(index) = Ch.GetResult(wb, 2000);

end

4.26.5 SetOutput
Description
The method sets the specified digital output to the specified value.
Syntax
object.SetOutput(port, bit, value);
Async Syntax
wb = object.SetOutputAsync port, bit, value);
Arguments

port Number of the output port.

bit Number of the specific bit.

The value to be writen to the specified output. Any non-zero value is

value
interpreted as 1.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method sets the specified digital output to the specified value. To set values of all outputs of a
specific port, use the SetOutputPort method.
Digital outputs are represented in the controller variable OUT. For more information about digital
outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%ACSPL+ equivalent: OUT(0).0 = 1

%Set output 0 of port 0 to 1
Ch.SetOutput(0,0,1);
%or set output 0 of port 0 to 1 asynchronuously
wb = Ch.SetOutputAsync(0,0,1);

4.26.6 SetOutputPort
Description
The method sets the specified digital output port to the specified value.

Version 3.10 215

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
object.SetOutputPort(port, value);
Async Syntax
wb = object.SetOutputPortAsync(port, value);
Arguments

port Number of the digital output port.

value The value to be writen to the specified port.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method sets the specified digital output port to the specified value. To set the value of the
specific output of the specific port, use the SetOutput method.
Digital outputs are represented in the controller variable OUT. For more information about digital
outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

for index = 0:15

% Set output port 0 to 15 to 100
Ch.SetOutputPort(index, 100);
%or set output port 0 to 15 to 100 asynchronuously
wb = Ch.SetOutputPortAsync(index, 100);
end

4.26.7 GetAnalogInputNT
Description
The function retrieves the current value of the specified analog input.
Syntax
value = object.GetAnalogInputNT(port);
Async Syntax
wb = object.GetAnalogInputNTAsync(port);
Arguments

Index of analog input port - a number between 0 and up to the maximum

port
number of analog input signals minus one.

Version 3.10 216

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value

Scalar specifying the current value of a specific analog input. Units: in scaling, by
state
percent, of the signal and ranges from -100 to +100 of the maximum level.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The function retrieves the current value of specified analog input.
Analog inputs are represented in the controller variable AIN. For more information about analog
inputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%Get analog input of port 0

value = Ch.GetAnalogInputNT(0);
%Or get analog input of port 0 asynchronuously
wb = Ch.GetAnalogInputNTAsync(0);
value = Ch.GetResult(wb, 2000);

4.26.8 GetAnalogOutputNT
Description
The function retrieves the current value of the specified analog output.
Syntax
value = object.GetAnalogOutputNT(port);
Async Syntax
wb = object.GetAnalogOutputNTAsync(port);
Arguments

Index of analog output port - a number between 0 and up to the maximum

port
number of analog output signals minus one.

Return Value

Scalar specifying the current value of a specific analog output. Units: in scaling,
value
by percent, of the signal and ranges from -100 to +100 of the maximum level.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 217

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method retrieves the current value of the specified analog output. To write a value to the
specific analog outputs use the SetAnalogOutputNT method.
Analog outputs are represented in the controller variable AOUT. For more information about
analog outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
Example

%Get analog output of port 0

value = Ch.GetAnalogOutputNT(0);
%Or get analog output of port 0 asynchronuously
wb = Ch.GetAnalogOutputNTAsync(0);
value = Ch.GetResult(wb, 2000);

4.26.9 SetAnalogOutputNT
Description
The function writes the specified value to the specified analog output.
Syntax
object.SetAnalogOutputNT(port, value);
Async Syntax
wb = object.SetAnalogOutputNTAsync(port, double);
Arguments

Index of analog output port - a number between 0 and up to the maximum

port
number of analog output signals minus one.

The value to be written to the specified analog output. Units: in scaling, by

value
percent, of the signal and ranges from -100 to +100 of the maximum level.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The function writes the specified value to the specified analog outputs. To get a value of the
specific analog output, use the SetAnalogOutputNT method.
Analog outputs are represented in the controller variable AOUT. For more information about
analog outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.

Version 3.10 218

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%The method writes the value 100 to the analog outputs

%of port outputs 0 to 15
for index = 0:15
% Write 100 to analog outputs of ports 0 to 15
Ch.SetAnalogOutputNT(index, 100);
%or write 100 to analog outputs of ports 0 to 15 asynchronuously
wb = Ch.SetAnalogOutputNTAsync(index, 100);
end

4.26.10 GetExtInput
Description
The method retrieves the current state of the specified extended input.
Syntax
value = object.GetExtInput(port, bit);
Async Syntax
wb = object.GetExtInputAsync(port, bit);
Arguments

port Number of the extended input port.

bit Number of the specific bit.

Return Value

Scalar specifying the current state (0 or 1) of the extended input specified by

value
port and bit.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get that states for all the inputs of the specific extended port, use the GetExtInputPort method.
Extended inputs are represented in the controller variable EXTIN. For more information about
extended inputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%Read extended input 0 of port 0 ( EXTIN(0).0 )

value = Ch.GetExtInput(0,0);
%or read extended input 0 of port 0 asynchronuously
wb = Ch.GetExtInputAsync(0,0);
value = Ch.GetResult(wb, 2000);

Version 3.10 219

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.26.11 GetExtInputPort
Description
The method retrieves the current state of the specified extended input port.
Syntax
value = object.GetExtInputPort(port);
Async Syntax
wb = object.GetExtInputPortAsync(port);
Arguments

port Number of the extended input port.

Return Value

value Scalar specifying the current state of the specified extended input port.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get the value of a specific input of the specific extended port, use the GetExtInput method.
Extended inputs are represented in the controller variable EXTIN. For more information about
extended inputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

port = zeros(1, 16);

port1 = zeros(1, 16);
%The method reads input port 0 to 15 ( IN(0) to IN(15) )
for index = 1:length(port)
%Read input of extended input port 0 to 15
%( EXTIN(0) to EXTIN(15) )
port(index) = Ch.GetExtInputPort(index-1);
%or read input of extended input port 0 to 15 asynchronuously
wb = Ch.GetExtInputPortAsync(index-1);
port1(index) = Ch.GetResult(wb, 2000);
end

4.26.12 GetExtOutput
Description
The method retrieves the current state of the specified extended output.
Syntax
value = object.GetExtOutput(port, bit);

Version 3.10 220

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.GetExtOutputAsync(port, bit);
Arguments

port Number of the extended output port.

bit Number of the specific bit.

Return Value

Scalar specifying the current state (0 or 1) of the specified extended output.

value

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get values of all outputs of the specific extended port, use the GetExtOutputPort method.
Extended outputs are represented in the controller variable EXTOUT. For more information about
extended outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%Read extended output 0 of port 0 ( EXTOUT(0).0 )

value = Ch.GetExtOutput(0,0);
%or read extended output 0 of port 0 asynchronuously
wb = Ch.GetExtOutputAsync(0,0);
value = Ch.GetResult(wb, 2000);

4.26.13 GetExtOutputPort
Description
The method retrieves the current state of the specified extended output port.
Syntax
value = object.GetExtOutputPort(port);
Async Syntax
wb = object.GetExtOutputPortAsync(port);
Arguments

port Number of the extended output port.

Version 3.10 221

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value

Scalar specifying the current state (0 or 1) of the specified extended output

value port.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get the value of the specific output of the specific extended port, use the GetExtOutput
method.
Extended outputs are represented in the controller variable EXTOUT. For more information about
extended outputs, see SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

port = zeros(1, 16);

port1 = zeros(1, 16);
%The method reads input extended output port 0 to 15
%( EXTOUT(0) to EXTOUT(15) )
for index = 1:length(port)
%Read input of extended output port 0 to 15
%( EXTIN(0) to EXTIN(15) )
port(index) = Ch.GetExtOutputPort(index-1);
%or read input of extended output port 0 to 15 asynchronuously
wb = Ch.GetExtOutputPortAsync(index-1);
port1(index) = Ch.GetResult(wb, 2000);
end

4.26.14 SetExtOutput
Description
The method sets the specified extended output to the specified value.
Syntax
object.SetExtOutput(port, bit, value);
Async Syntax
wb = object.SetExtOutputAsync(port, bit, value);
Arguments

port Number of the extended output port.

bit Number of the specific bit.

Version 3.10 222

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

The value to be written to the specified output. Any non-zero value is

value
interpreted as 1.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method sets the specified extended output to the specified value. To set values of all outputs
of the specific extended port, use the SetExtOutputPort method.
Extended outputs are represented in the controller EXTOUT variable. For more information about
extended outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%ACSPL+ equivalent: OUT(0).0 = 1

%Set output 0 of extended port 0 to 1
Ch.SetExtOutput(0,0,1);
%or set output 0 of extended port 0 to 1 asynchronuously
wb = Ch.SetExtOutputAsync(0,0,1);

4.26.15 SetExtOutputPort
Description
The method sets the specified extended output port to the specified value.
Syntax
object.SetExtOutputPort(port, value);
Async Syntax
wb = object.SetExtOutputPortAsync(port, value);
Arguments

port Number of the extended output port.

value The value to be written to the specified output port.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 223

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method 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 SetExtOutput method.
Extended outputs are represented in the controller variable EXTOUT. For more information about
extended outputs, see the SPiiPlus ACSPL+ Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%The method sets outputs of extended port 0 to 15 to 100

for index = 0:15
% Set outputs of extended port 0 to 15 to 100
Ch.SetExtOutputPort(index, 100);
%or set outputs of extended port 0 to 15 to 100 asynchronuously
wb = Ch.SetExtOutputPortAsync(index, 100);
end

4.27 Safety Control Methods

The Safety Control methods are:
Table 3-30. Safety Control Methods

Method Description

Retrieves the set of bits that indicate the motor or system

GetFault
faults.

Sets the mask that enables/disables the examination and

SetFaultMask
processing of the controller faults.

Retrieves the mask that defines which controller faults are

GetFaultMask
examined and processed.

EnableFault Enables the specified axis or system fault.

DisableFault Disables the specified axis or system fault.

Sets the mask that defines for which axis or system faults the
SetResponseMask
controller provides default response.

Retrieves the mask that defines for which axis or system

GetResponseMask
faults the controller provides default response.

Enables the default response to the specified axis or system

EnableResponse
fault.

Disables the default response to the specified axis or system

DisableResponse
fault.

Version 3.10 224

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

GetSafetyInput Retrieves the current state of the specified safety input.

GetSafetyInputPort Retrieves the current state of the specified safety input port.

Sets the set of bits that define inversion for the specified
SetSafetyInputPortInv
safety input port.

The method clears the current faults and results of previous

FaultClear
faults stored in the MERR variable.

The method clears the current faults and results of previous

FaultClearM
faults stored in the MERR variable for multiple axis.

4.27.1 GetFault
Description
The method retrieves the set of bits that indicate the motor or system faults.
Syntax
faults = object.GetFault(axis);
Async Syntax
wb = object.GetFaultAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

Set of Safety Control Masks constants specifying the current motor or system
faults
faults.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The motor faults are related to a specific motor, the power amplifier, and 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.
The parameter fault receives the set of bits that indicates the controller faults. To recognize the
specific fault, properties ACSC_SAFETY_*** can be used. See Safety Control Masks for a detailed
description of these properties.
For more information about the controller faults, see the SPiiPlus ACSPL+ Programmer’s Guide.

Version 3.10 225

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the method fails, the Error object is filled with the error description.
Example

%Retrieve the set of bits that indicate the

%motor or system faults
fault = Ch.GetFault(AxisDefs.ACSC_AXIS_0);

%Retrieve the set of bits that indicate the

%motor or system faults asynchronuously
wb = Ch.GetFaultAsync(AxisDefs.ACSC_AXIS_0);
fault = Ch.GetResult(wb, 2000);

4.27.2 SetFaultMask
Description
The method sets the mask that enables or disables the examination and processing of the
controller faults.

Certain controller faults provide protection against potential serious bodily injury and
damage to the equipment. Be aware of the implications before disabling any alarm,
limit, or error.

Syntax
object.SetFaultMask(axis, mask);
Async Syntax
wb = object.SetFaultMaskAsync(axis, mask);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

The mask to be set:

If a bit of the mask is zero, the corresponding fault is disabled.

mask To set/reset a specified bit, use ACSC_SAFETY_*** properties. See Safety

Control Masks or a detailed description of these properties.
If the mask is ACSC_ALL, then all the faults for the specified axis are enabled. If
the mask is ACSC_NONE, then all the faults for the specified axis are disabled.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 226

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Enable all faults of axis 0

Ch.SetFaultMask(AxisDefs.ACSC_AXIS_0, SafetyControlMasks.ACSC_ALL);

%Enable all faults of axis 0 asynchronuously

wb = Ch.SetFaultMaskAsync(AxisDefs.ACSC_AXIS_0, SafetyControlMasks.ACSC_
ALL);

4.27.3 GetFaultMask
Description
The method retrieves the mask that defines which controller faults are examined and processed.
Syntax
mask = object.GetFaultMask(axis);
Async Syntax
wb = object.GetFaultMaskAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

Safety Control Masks constants that defines which controller faults are
mask
examined and processed.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
If a bit of the mask is zero, the corresponding fault is disabled.
Use the ACSC_SAFETY_*** properties to examine a specific bit. See Safety Control Masks for a
detailed description of these properties.

Version 3.10 227

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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 the method fails, the Error object is filled with the error description.
Example

%Retrieves the mask that defines which controller

%faults are examined and processed of axis 0
mask = Ch.GetFaultMask(AxisDefs.ACSC_AXIS_0);

%Retrieves the mask that defines which controller

%faults are examined and processed of axis 0 asynchronuously
wb = Ch.GetFaultMaskAsync(AxisDefs.ACSC_AXIS_0);
mask = Ch.GetResult(wb, 2000);

4.27.4 EnableFault
Description
The method enables the specified axis or system fault.
Syntax
object.EnableFault(axis, fault);
Async Syntax
wb = object.EnableFaultAsync(axis, fault);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

The fault to be enabled. Only one fault can be enabled at a time.

fault To specify the fault, one of the properties ACSC_SAFETY_*** can be used. See
Safety Control Masks for a detailed description of these properties.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method enables the examination and processing of the specified motor or system fault by
setting the specified bit of the fault mask to one.

Version 3.10 228

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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 the method fails, the Error object is filled with the error description.
Example

%Enable fault: Right Limit of axis 0

Ch.EnableFault(AxisDefs.ACSC_AXIS_0,SafetyControlMasks.ACSC_SAFETY_RL);

%Enable fault: Right Limit of axis 0 asynchronuously

wb = Ch.EnableFaultAsync(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_RL);

4.27.5 DisableFault
Description
The method disables the specified axis or system fault.

Certain controller faults provide protection against potential serious bodily injury and
damage to equipment. Be aware of the implications before disabling any alarm, limit,
or error.

Syntax
object.DisableFault(axis, fault);
Async Syntax
wb = object.DisableFaultAsync(axis, fault);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

The fault to be disabled. Only one fault can be enabled at a time.

fault To specify the fault, one of the properties ACSC_SAFETY_*** can be used. See
Safety Control Masks for a detailed description of these properties.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 229

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Disable fault: Right Limit of axis 0

Ch.DisableFault(AxisDefs.ACSC_AXIS_0,SafetyControlMasks.ACSC_SAFETY_RL);

%Disable fault: Right Limit of axis 0 asynchronuously

wb = Ch.DisableFaultAsync(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_RL);

4.27.6 SetResponseMask
Description
The method retrieves the mask that defines the motor or the system faults for which the
controller provides the default response.

Certain controller faults provide protection against potential serious bodily injury and
damage to the equipment. Be aware of the implications before disabling any alarm,
limit, or error.

Syntax
object.SetResponseMask(axis, mask);
Async Syntax
wb = object.SetResponseMaskAsync(axis, mask);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

The mask to be set:

If a bit of the mask is zero, the corresponding fault is disabled.
mask
To set/reset a specified bit, use ACSC_SAFETY_*** properties. See Safety
Control Masks for a detailed description of these properties.

Version 3.10 230

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the mask is ACSC_ALL, then all the faults for the specified axis are enabled.If
the mask is ACSC_NONE, then all the faults for the specified axis are disabled.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Enable all default responses

Ch.SetResponseMask(AxisDefs.ACSC_AXIS_0,SafetyControlMasks.ACSC_ALL);

%Enable all default responses asynchronuously

wb = Ch.SetResponseMaskAsync(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_ALL);

4.27.7 GetResponseMask
Description
The method retrieves the mask that defines the motor or the system faults for which the
controller provides the default response.
Syntax
mask = object.GetResponseMask(axis);
Async Syntax
wb = object.GetResponseMaskAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

Safety Control Masks constants specifying the motor or the system faults for
mask
which the controller provides the default response.

Version 3.10 231

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method retrieves the mask that determines whether the controller will respond to a motor or
system fault with the fault's default response.
For more information about the controller faults and default, responses see the SPiiPlus ACSPL+
Programmer’s Guide.
If the method fails, the Error object is filled with the error description.
Example

%Retrieve the mask of axis 0

mask = Ch.GetResponseMask(AxisDefs.ACSC_AXIS_0);

%Retrieve the mask of axis 0 asynchronuously

wb = Ch.GetResponseMaskAsync(AxisDefs.ACSC_AXIS_0);
mask = Ch.GetResult(wb, 2000);

4.27.8 EnableResponse
Description
The method enables the response to the specified axis or system fault.
Syntax
object.EnableResponse(axis, response);
Async Syntax
wb = object.EnableResponseAsync(axis, response);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

The default response to be enabled. Only one default response can be

enabled at a time.
response To specify the default response, one of the properties ACSC_SAFETY_***
can be used. See Safety Control Masks for a detailed description of these
properties.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 232

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The method enables the default response to the specified axis 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 the method fails, the Error object is filled with the error description.
Example

%Enable the default response to the

%Position Error fault of axis 0
Ch.EnableResponse(AxisDefs.ACSC_AXIS_0,SafetyControlMasks.ACSC_SAFETY_
PE);

%Enable the default response to the

%Position Error fault of axis 0 asynchronuously
wb = Ch.EnableResponseAsync(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_PE);

4.27.9 DisableResponse
Description
The method disables the default response to the specified axis or system fault.

Certain controller faults provide protection against potential serious bodily injury and
damage to equipment. Be aware of the implications before disabling any alarm, limit,
or error.

Syntax
object.DisableResponse(axis, response);
Async Syntax
wb = object.DisableResponseAsync(axis, response);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

The default response to be disabled. Only one default response can be

enabled at a time.
response To specify the default response, one of the properties ACSC_SAFETY_***
can be used. See Safety Control Masks for a detailed description of these
properties.

Version 3.10 233

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method 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 the method fails, the Error object is filled with the error description.
Example

%Disable the default response to the

%Right Limit fault
Ch.DisableResponse(AxisDefs.ACSC_AXIS_0,SafetyControlMasks.ACSC_SAFETY_
RL);

%Disable the default response to the

%Right Limit fault asynchronuously
wb = Ch.DisableResponseAsync(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_RL);

4.27.10 GetSafetyInput
Description
The method retrieves the current state of the specified safety input.
Syntax
sInput = object.GetSafetyInput(axis, input);
Async Syntax
wb = object.GetSafetyInputAsync(axis, input);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

The specific safety input.

The safety input can be one or any combination of the following:
input ACSC_SAFETY_RL
ACSC_SAFETY_LL
ACSC_SAFETY_NETWORK

Version 3.10 234

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

ACSC_SAFETY_HOT
ACSC_SAFETY_DRIVE
ACSC_SAFETY_ES
See Safety Control Masks for a detailed description of these properties.

Return Value

Safety Control Masks constant specifying the current state of the specified
sInput
safety input.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To get values of all safety inputs of the specific axis, use GetSafetyInputPort.
Safety inputs are represented in the controller variables SAFIN and S_SAFIN. For more information
about safety inputs, see SPiiPlus ACSPL+ Programmer’s Guide.

Some safety inputs can be unavailable in specific controller models. 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.

If the method fails, the Error object is filled with the error description.
Example

%The method reads Emergency Stop system safety input

%Read Right Limit Safety input of axis 0
sInput  = Ch.GetSafetyInput(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_RL);
%Read Right Limit Safety input of axis 0 asynchronuously
wb = Ch.GetSafetyInputAsync(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_RL);
sInput = Ch.GetResult(wb, 2000);

4.27.11 GetSafetyInputPort
Description
The method retrieves the current state of the specified safety input port.
Syntax
portState = object.GetSafetyInputPort(axis);
Async Syntax
wb = object.GetSafetyInputPortAsync(axis);

Version 3.10 235

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

Safety Control Masks constant specifying the current state of the specified
portState
safety input port.

Remarks
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
To recognize a specific motor safety input, only one of the following properties can be used:

> ACSC_SAFETY_RL

> ACSC_SAFETY_LL

> ACSC_SAFETY_NETWORK

> ACSC_SAFETY_HOT

> ACSC_SAFETY_DRIVE

To recognize a specific system safety input, only the ACSC_SAFETY_ES property can be used.
See Safety Control Masks for a detailed description of these properties.
To get the state of the specific safety input of a specific axis, use GetSafetyInput.
Safety inputs are represented in the controller variables SAFIN and S_SAFIN. For more information
about safety inputs, see SPiiPlus ACSPL+ Programmer’s Guide.

Some safety inputs can be unavailable in specific controller models. 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.

If the method fails, the Error object is filled with the error description.
Example

%Read safety input port of the axis 0

portState  = Ch.GetSafetyInputPort(AxisDefs.ACSC_AXIS_0);
%Read safety input port of the axis 0 asynchronuously
wb = Ch.GetSafetyInputPortAsync(AxisDefs.ACSC_AXIS_0);
portState = Ch.GetResult(wb, 2000);

Version 3.10 236

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.27.12 SetSafetyInputPortInv
Description
The method sets the set of bits that define inversion for the specified safety input port.
Syntax
object.SetSafetyInputPortInv(axis, value);
Async Syntax
wb = object.SetSafetyInputPortInvAsync(axis, value);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis

axis
1, etc. For the axis constants see Axis Definitions.

The specific inversion.

To set a specific bit, use the following properties:
> ACSC_SAFETY_RL
> ACSC_SAFETY_LL
> ACSC_SAFETY_NETWORK
value
> ACSC_SAFETY_HOT
> ACSC_SAFETY_DRIVE.
To set an inversion for the specific system safety input port, use only the
ACSC_SAFETY_ES property.
See Safety Control Masks for a detailed description of these properties.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method sets the bits that define inversion for the specified safety input port. 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 SAFIN and S_SAFIN. For
more information about safety inputs, see SPiiPlus ACSPL+ Programmer’s Guide.

Version 3.10 237

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Some safety inputs can be unavailable in specific controller models. 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.

If the method fails, the Error object is filled with the error description.
Example

%Set the inversion for safety input port of the axis 0

Ch.SetSafetyInputPortInv(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_RL);
%Set the inversion for safety input port of the axis 0 asynchronuously
wb = Ch.SetSafetyInputPortInvAsync(AxisDefs.ACSC_AXIS_0,...
SafetyControlMasks.ACSC_SAFETY_RL);

4.27.13 FaultClear
Description
The method clears the current faults and the result of the previous fault stored in the MERR
variable.
Syntax
object.FaultClear(axis);
Async Syntax
wb = object.FaultClearAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method clears the current faults of the specified axis and the result of the previous fault
stored in the MERR variable.
If the method fails, the Error object is filled with the error description.

Version 3.10 238

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Clear the current faults and the results of the

%previous faults stored in the MERR variable of axis 0
Ch.FaultClear(AxisDefs.ACSC_AXIS_0);
%Clear the current faults and the results of the
%previous faults stored in the MERR variable of axis 0 asynchronuously
wb = Ch.FaultClearAsync(AxisDefs.ACSC_AXIS_0);

4.27.14 FaultClearM
Description
The method clears the current faults and results of previous faults stored in the MERR variable for
multiple axis.
Syntax
object.FaultClearM(axes);
Async Syntax
wb = object.FaultClearMAsync(axes);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_

1 to the axis 1, etc.
axes For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
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.
If the method fails, the Error object is filled with the error description.
Example

%create axes array, terminate with AxisDefs.ACSC_NONE

axes = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1,
AxisDefs.ACSC_NONE);
%Clear the current faults and results of the previous faults
%stored in the MERR variable of axes 0 and 1
Ch.FaultClearM(axes);

Version 3.10 239

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Clear the current faults and results of the previous faults

%stored in the MERR variable of axes 0 and 1 asynchronuously
wb = Ch.FaultClearMAsync(axes);

4.28 Wait-for-Condition Methods

The Wait-for-Condition methods are:
Table 3-31. Wait-for-Condition Methods

Method Description

WaitMotionEnd Waits for the end of a motion.

WaitLogicalMotionEnd Waits for the logical end of a motion.

WaitCollectEnd Waits for the end of data collection.

WaitProgramEnd Waits for the program termination in the specified buffer.

WaitMotorCommutated Waits for the specified state of the specified motor.

WaitMotorEnabled Waits for the specified state of the specified motor.

WaitInput Waits for the specified state of the specified digital input.

4.28.1 WaitMotionEnd
Description
The method waits for the end of a motion.
Syntax
object.WaitMotionEnd(axis, timeout);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method's time-out interval never elapses.

Return Value
None.
Remarks
The method 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 method differs from the WaitLogicalMotionEnd method. Examining the same motion, the
WaitMotionEnd method will return latter. The WaitLogicalMotionEnd method returns when the

Version 3.10 240

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

generation of the motion finishes. On the other hand, the WaitMotionEnd method returns when
the generation of the motion finishes and the motor has settled in the final position.
If the method fails, the Error object is filled with the error description.
Example

%Wait for the end of motion of axis 0 during 10 sec

Ch.WaitMotionEnd(AxisDefs.ACSC_AXIS_0,10000);

4.28.2 WaitLogicalMotionEnd
Description
The method waits for the logical end of a motion.
Syntax
object.WaitLogicalMotionEnd (axis, timeout);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method's time-out interval never elapses.

Return Value
None.
Remarks
The method does not return while the specified axis is involved in a motion and the specified time-
out interval has not elapsed.
The method differs from the WaitMotionEnd method. Examining the same motion, the
WaitMotionEnd method will return later. The WaitLogicalMotionEnd method returns when the
generation of the motion finishes. On the other hand, the WaitMotionEnd method returns when
the generation of the motion finishes and the motor has settled in the final position.
If the method fails, the Error object is filled with the error description.
Example

%Wait for the logical end of motion of axis 0 during 10 sec

Ch.WaitLogicalMotionEnd(AxisDefs.ACSC_AXIS_0, 10000);

4.28.3 WaitCollectEnd
Description
The method waits for the end of data collection.
Syntax
object.WaitCollectEnd(timeout);

Version 3.10 241

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method's time-out interval never elapses.

Return Value
None.
Remarks
The method does not return while the system data collection is in progress and the specified time-
out interval has not elapsed. The method verifies the S_ST.#DC system flag.
If the method fails, the Error object is filled with the error description.
Example

%Wait data ection ends during 10 sec

Ch.WaitCollectEnd(10000);

4.28.4 WaitProgramEnd
Description
The method waits for the program termination in the specified buffer.
Syntax
object.WaitProgramEnd(buffer, timeout);
Arguments

ProgramBuffer enumeration representing Number of a program buffer in

buffer
the controller.

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method's time-out interval never elapses.

Return Value
None.
Remarks
The method does not return while the ACSPL+ program in the specified buffer is in progress and
the specified time-out interval has not elapsed.
If the method fails, the Error object is filled with the error description.
Example

%Append and run buffer 1

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'ST:');
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'!an empty loop');
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_1,'goto ST');

Version 3.10 242

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_1,[]);
%Wait program ends during 10 sec
Ch.WaitProgramEnd(ProgramBuffer.ACSC_BUFFER_1 , 10000);

4.28.5 WaitMotorCommutated
Description
The method waits for the specified state of the specified motor.
Syntax
object.WaitMotorCommutated(axis, state, timeout);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

state 1 - The method waits for the motor to be commutated.

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method's time-out interval never elapses.

Return Value
None.
Remarks
The method does not return while the specified motor is not in the desired state and the specified
time-out interval has not elapsed. The method examines the MFLAGS.#BRUSHOK flag.
If the method fails, the Error object is populated with the error description
Example

%Commut axis 0
Ch.Commut(AxisDefs.ACSC_AXIS_0);
% Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_
ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is commutated during 5 sec
Ch.WaitMotorCommutated(AxisDefs.ACSC_AXIS_0,motorState, 5000);

4.28.6 WaitMotorEnabled
Description
The method waits until the specified motor is commutated.
Syntax
object.WaitMotorEnabled (axis, state, timeout);

Version 3.10 243

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the

axis
axis 1, etc. For the axis constants see Axis Definitions.

Scalar specifying the value of Motor State Flags constant.

state ACSC_MST_ENABLE – the method waits for the motor to be enabled.
ACSC_NONE – the method waits for the motor to be disabled.

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method's time-out interval never elapses.

Return Value
None.
Remarks
The method does not return while the specified motor is not in the desired state and the specified
time-out interval has not elapsed. The method examines the MST.#ENABLED motor flag.
If the method fails, the Error object is filled with the error description.
Example

%Enable axis 0
Ch.Enable(AxisDefs.ACSC_AXIS_0);

%Set value of motor state to 1 corresponding to MotorStates.ACSC_MST_

ENABLE
motorState = MotorStates.GetValue(MotorStates.ACSC_MST_ENABLE);
%Wait till axis 0 is enabled during 5 sec
Ch.WaitMotorEnabled(AxisDefs.ACSC_AXIS_0, motorState, 5000);

4.28.7 WaitInput
Description
The method waits for the specified state of digital input.
Syntax
object.WaitInput (port, bit, state, timeout)
Arguments

port Number of input port: 0 corresponds to IN0, 1 – to IN1, etc.

bit Selects one bit from the port, from 0 to 31.

state Specifies a desired state of the input, 0 or 1.

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method's time-out interval never elapses.

Version 3.10 244

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Return Value
None.
Remarks

The basic configuration of the SPiiPlus PCI model provides only 16 inputs. Therefore,
Port must be 0, and Bit can be specified only from 0 to 15.

If the method fails, the Error object is filled with the error description.
Example

%Wait for IN0.0 = 1 during 5 sec

%Parameters: 0 – IN0
%            0 – IN0.0
%            1 – wait for IN0.0 = 1
%            timeout – during 5 sec
Ch.WaitInput(0, 0, 1, 5000);

4.29 Event and Interrupt Handling Methods

The Event and Interrupt Handling methods are:
Table 3-32. Event and Interrupt Handling Methods

Method Description

EnableEvent Enables event generation for the specified interrupt condition.

DisableEvent Disables event generation for the specified interrupt condition.

SetInterruptMask Sets the mask for the specified interrupt.

GetInterruptMask Retrieves the mask for the specified interrupt.

4.29.1 EnableEvent
Description
The method enables event generation for the specified interrupt condition.
Syntax
object.EnableEvent(flags);
Arguments

Specifies one of the interrupts such as ACSC_INTR_PEG, ACSC_INTR_MARK1 etc.

flags
For the full list of the interrupts, seeInterrupt Types .

Return Value
None.

Version 3.10 245

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
The library generates an event when the specified Interrupt occurs. SPiiPlus MATLAB Library has
events for all types of interrupts:
PEG (AxisMasks Param), MARK1 (AxisMasks Param) etc. For full list of SPiiPlus MATLAB Library events
see Events.
The bit-mapped event parameter Param identifies which axis/buffer/input the interrupt was
generated for. See Callback Interrupt Masks for a detailed description of the Param argument for
each interrupt.
One event can be associated with each controller interrupt. All events are handled in the main
application thread, therefore the application execution is stopped until the event is handled.
To disable a specific event, call the DisableEvent method with the flags argument equal to the
specified interrupt type.
If the method fails, the Error object is filled with the error description.
Example

%Enable event ACSC_INTR_ACSPL_PROGRAM

Ch.EnableEvent(Interrupts.ACSC_INTR_ACSPL_PROGRAM);
%Enable event ACSC_INTR_PROGRAM_END
Ch.EnableEvent(Interrupts.ACSC_INTR_PROGRAM_END);
%Delete all lines in buffer 5
Ch.Transaction('#5D1,100000');
%Appends a line to buffer 5
Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_5, 'interrupt stop');
%Execute buffer 5
Ch.Transaction('#5X');

4.29.2 DisableEvent
Description
The method disables event generation for the specified interrupt condition.
Syntax
object.DisableEvent (flags);
Arguments

Specifies one of the interrupts such as ACSC_INTR_PEG, ACSC_INTR_MARK1 etc.

flags
For the full list of the interrupts, see Interrupt Types.

Return Value
None.
Remarks
The method disables event generation that was enabled with method EnableEvent
If the method fails, the Error object is filled with the error description.

Version 3.10 246

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Disable event PROGRAM_END

Ch.DisableEvent(Interrupts.ACSC_INTR_PROGRAM_END);

4.29.3 SetInterruptMask
Description
The method sets the mask for specified interrupt.
Syntax
object.SetInterruptMask(Interrupts interrupt, Uint32 mask);
Arguments

Specifies one of the following interrupts:

ACSC_INTR_ACSPL_PROGRAM – an ACSPL+ program has generated the
interrupt by INTERRUPT command
ACSC_INTR_ACSPL_PROGRAM_EX – an ACSPL+ program has generated the
interrupt by INTERRUPTEX command
ACSC_INTR_COMM_CHANNEL_CLOSED - a communication channel has been
closed.
ACSC_INTR_COMMAND – a line of ACSPL+ commands has been executed in
a dynamic buffer
ACSC_INTR_EMERGENCY - an EMERGENCY STOP signal has been generated.
ACSC_INTR_ETHERCAT_ERROR - an EtherCAT error occurred.
ACSC_INTR_LOGICAL_MOTION_END – a logical motion has finished
interrupt
ACSC_INTR_MOTION_FAILURE – a motion has been interrupted due to a
fault
ACSC_INTR_MOTION_PHASE_CHANGE – motion profile changes the phase
ACSC_INTR_MOTION_START – motion starts
ACSC_INTR_MOTOR_FAILURE – a motor has been disabled due to a fault
ACSC_INTR_NEWSEGM - an AST.#NEWSEGM bit is high.
ACSC_INTR_PHYSICAL_MOTION_END – a physical motion has finished
ACSC_INTR_PROGRAM_END – an ACSPL+ program has finished
ACSC_INTR_SOFTWARE_ESTOP - the EStop button was clicked.
ACSC_INTR_SYSTEM_ERROR - a system error occurred.
ACSC_INTR_TRIGGER – AST.#TRIGGER bit goes high

Scalar specifying the mask to be set.

mask If some bit = 0 then the interrupt for the corresponding axis/buffer/input
does not occur – interrupt is disabled.

Version 3.10 247

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Use ACSC_MASK_*** to set/reset a specified bit. See

GetInterruptMask for a detailed description of these enums.
If Mask is ACSC_ALL, the interrupts for all axes/buffers/inputs are enabled.
If Mask is ACSC_NONE, the interrupts for all axes/buffers/inputs are
disabled. As default all bits for each interupts are set to one.

Return Value
None.
Remarks
The method sets the bit mask for specified interrupt. To get current mask for specified interrupt,
call GetInterruptMask.
Using a mask, you can reduce the number of generated events. The event will be generated only if
the interrupt is caused by an axis/buffer/input that corresponds to non-zero bit in the related
mask.
If the method fails, the Error object is filled with the error description.
Example

%Sets the mask for specified interrupt only for  axis 0

mask = AxisMasks.GetValue(AxisMasks.ACSC_MASK_AXIS_0);
Ch.SetInterruptMask(Interrupts.ACSC_INTR_PROGRAM_END, mask);

4.29.4 GetInterruptMask
Description
The method retrieves the mask for specified interrupt.
Syntax
mask = object.GetInterruptMask(interrupt);

Version 3.10 248

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Specifies one of the following interrupts:

ACSC_INTR_ACSPL_PROGRAM – an ACSPL+ program has generated the
interrupt by INTERRUPT command
ACSC_INTR_ACSPL_PROGRAM_EX – an ACSPL+ program has generated the
interrupt by INTERRUPTEX command
ACSC_INTR_COMM_CHANNEL_CLOSED - a communication channel has been
closed.
ACSC_INTR_COMMAND – a line of ACSPL+ commands has been executed in
a dynamic buffer
ACSC_INTR_EMERGENCY - an EMERGENCY STOP signal has been generated.
ACSC_INTR_ETHERCAT_ERROR - an EtherCAT error occurred.
ACSC_INTR_LOGICAL_MOTION_END – a logical motion has finished
interrupt
ACSC_INTR_MOTION_FAILURE – a motion has been interrupted due to a
fault
ACSC_INTR_MOTION_PHASE_CHANGE – motion profile changes the phase
ACSC_INTR_MOTION_START – motion starts
ACSC_INTR_MOTOR_FAILURE – a motor has been disabled due to a fault
ACSC_INTR_NEWSEGM - an AST.#NEWSEGM bit is high.
ACSC_INTR_PHYSICAL_MOTION_END – a physical motion has finished
ACSC_INTR_PROGRAM_END – an ACSPL+ program has finished
ACSC_INTR_SOFTWARE_ESTOP - the EStop button was clicked.
ACSC_INTR_SYSTEM_ERROR - a system error occurred.
ACSC_INTR_TRIGGER – AST.#TRIGGER bit goes high

Return Value

mask Scalar representing the bit mask for the specified interrupt.

Remarks
To set the mask for a specified interrupt, call SetInterruptMask.
If a bit in the return value equals 0, the interrupt for the corresponding axis/buffer/input is
disabled.
Use the ACSC_MASK_*** properties to find the values of specific bits. See Callback Interrupt Masks
for a detailed description of these properties.
By default all the interrupt bits are set to one.
If the method fails, the Error object is filled with the error description.

Version 3.10 249

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%The example shows how to get the mask for specific interrupt
%An ACSPL+ program finished
mask = Ch.GetInterruptMask(Interrupts.ACSC_INTR_PROGRAM_END);

4.30 Variables Management Methods

The Variables Management methods are:
Table 3-33. Variables Management Methods

Method Description

DeclareVariable Creates the persistent global variable.

ClearVariables Deletes all persistent global variables.

4.30.1 DeclareVariable
Description
The method creates a persistent global variable.
Syntax
object.DeclareVariable(type, name);
Async Syntax
wb = object.DeclareVariableAsync(type, name);
Arguments

Type of the variable.

type For an integer variable Type must be ACSC_INT_TYPE.
For a real variable, Type must be ACSC_REAL_TYPE.

name Vector of characters specifying the name of the variable.

Return Value
None.
Return Value (async call)

wait ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method creates the persistent global variable specified by name of type specified by type. The
variable can be used as any other ACSPL+ or global variable.
If it is necessary to declare one or two-dimensional array, name should also contains the
dimensional size in brackets.

Version 3.10 250

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

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
ClearVariables method.
The method waits for the controller response.
If the method fails, the Error object is filled with the error description.
Example

%Create the persistent global variable 'MyVar' as

%integer type.
Ch.DeclareVariable(AcsplVariableType.ACSC_INT_TYPE,'MyVar');
%or create the variable asynchronuously
wb = Ch.DeclareVariableAsync(AcsplVariableType.ACSC_INT_TYPE,'MyVar');

4.30.2 ClearVariables
Description
Deletes all persistent global variables.
Syntax
object.ClearVariables;
Arguments
None.
Return Value
None.
Remarks
The method deletes all persistent global variables created by the DeclareVariable method. The
method waits for the controller response.
If the method fails, the Error object is filled with the error description.
Example

Ch.DeclareVariable(AcsplVariableType.ACSC_INT_TYPE,'MyVar');
%The method deletes all persistent global variables
Ch.ClearVariables;

4.31 Service Methods

The Service methods are:
Table 3-34. Service Methods

Method Description

GetFirmwareVersion Retrieves the firmware version of the controller.

Version 3.10 251

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

GetSerialNumber Retrieves the controller serial number.

SysInfo Retrieves cerain system information.

GetBuffersCount Returns the number of available ACSPL+ programming buffers.

GetAxesCount Returns the number of available axes.

GetDBufferIndex Retrieves the index of the D-Buffer.

GetUMDVersion Retrieves the version number of the User Mode Driver

4.31.1 GetFirmwareVersion
Description
The method retrieves the firmware version of the controller.
Syntax
version = object.GetFirmwareVersion;
Arguments
None.
Return Value

version Vector of characters specifying the controller firmware version.

Remarks
If the method fails, the Error object is filled with the error description.
Example

%Retrieve the firmware version of the controller

version = Ch.GetFirmwareVersion;

4.31.2 GetSerialNumber
Description
The method retrieves the controller serial number.
Syntax
sn = object.GetSerialNumber
Arguments
None.
Return Value

sn Vector of characters specifying the controller serial number.

Version 3.10 252

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Remarks
If the method fails, the Error object is filled with the error description.
Example

%Retrieve the serial number of controller

sn = Ch.GetSerialNumber;

4.31.3 SysInfo
Description
The method returns certain system information based on the argument that is specified.
Syntax
data = object.SysInfo (key);
Async Syntax
wb = object.SysInfoAsync (key);
Arguments

Scalar value representing the configuration key, specifies the configured

Key
feature. Assigns value of key argument in the ACSPL+ SYSINFO function.

Return Value

data Scalar specifying the configuration data.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

key = SystemInfoKey.GetValue(SystemInfoKey.ACSC_SYS_MODEL_KEY);
%Get SPiiPlus Model Number
value = Ch.SysInfo(key);
%Get SPiiPlus Model Number asynchronuously
wb = Ch.SysInfoAsync(key);
value = Ch.GetResult(wb, 2000);

4.31.4 GetBuffersCount
Description
The method returns the number of available ACSPL+ programming buffers.
Syntax
numOfBufs = object.GetBuffersCount;
Async Syntax
wb = object.GetBuffersCountAsync;

Version 3.10 253

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments
None.
Return Value

numOfBufs Scalar specifying the number of available ACSPL+ programming buffers.

Example

%Retrieve the number of available buffers

numOfBufs = Ch.GetBuffersCount;
%Retrieve the number of available buffers asynchronuously
wb = Ch.GetBuffersCountAsync;
numOfBufs = Ch.GetResult(wb, 2000);

4.31.5 GetAxesCount
Description
The method returns the number of available axes.
Syntax
axesCount = object.GetAxesCount;
Async Syntax
wb = object.GetAxesCountAsync;
Arguments
None
Return Value

axesCount Scalar specifying the number of available axes.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Retrieve the number of available axes

axesCount = Ch.GetAxesCount;
%Retrieve the number of available axes asynchronuously
wb = Ch.GetAxesCountAsync;
axesCount = Ch.GetResult(wb, 2000);

4.31.6 GetDBufferIndex
Description
The method returns the index of the D-Buffer.
Syntax
index = object.GetDBufferIndex;

Version 3.10 254

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.GetDBufferIndexAsync;
Arguments
None
Return Value

index Scalar specifying the D-Buffer Index.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Retrieve the D-Buffer index

index = Ch.GetDBufferIndex;
%Retrieve the D-Buffer index asynchronuously
wb = Ch.GetDBufferIndexAsync;
index = Ch.GetResult(wb, 2000);

4.31.7 GetUMDVersion
Description
The method retrieves the User Mode Driver version number.
Syntax
libVersion = object.GetUMDVersion;
Arguments
None.
Return Value

libVersion Scalar representing the UMD version number.

Remarks
The User Mode Driver 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 the version “2.10” has the following binary representation (hexadecimal
format): 0x020A0000.
The 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, or other build.
If the method fails, the Error object is filled with the error description.

Version 3.10 255

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Retrieve the User Mode Driver version number

libVersion = Ch.GetUMDVersion;

4.32 Error Diagnosis Methods

The Error Diagnosis methods are:
Table 3-35. Error Diagnosis Methods

Method Description

GetMotorError Retrieves the reason why the motor was disabled.

Retrieves the termination code of the last executed motion of the

GetMotionError
specified axis.

Retrieves the error code of the last program error encountered in

GetProgramError
the specified buffer.

4.32.1 GetMotorError
Description
The method retrieves the reason for motor disabling.
Syntax
error = object.GetMotorError(axis);
Async Syntax
wb = object.GetMotorErrorAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

error Scalar specifying the reason for the motor becoming disabled.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
If the motor is enabled the method returns zero. If the motor was disabled, the method returns
the reason for the disabling. To get the error explanation, use the GetErrorString method.
See SPiiPlus ACSPL+ Programmer’s Guide for all available motor error code descriptions. If the
method fails, the Error object is filled with the error description.
Example

Version 3.10 256

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

%Retrieve the reason for motor disabling

mError = Ch.GetMotorError(AxisDefs.ACSC_AXIS_0);
%Retrieve the reason for motor disabling asynchronuously
wb = Ch.GetMotorErrorAsync(AxisDefs.ACSC_AXIS_0);
mError = Ch.GetResult(wb, 2000);

4.32.2 GetMotionError
Description
The method retrieves the termination code of the last executed motion of the specified axis.
Syntax
error = object.GetMotionError(axis);
Async Syntax
wb = object.GetMotionErrorAsync(axis);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to the axis 1,

axis
etc. For the axis constants see Axis Definitions.

Return Value

Scalar specifying the termination code of the last executed motion of the
error
specified axis.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
If the motion is in progress, the method returns zero. If the motion terminates for any reason, the
method returns the termination code. To get the error explanation, use the method
GetErrorString.
See the SPiiPlus ACSPL+ Programmer’s Guide for all available motion termination codes description.
If the method fails, the Error object is filled with the error description.
Example

%Retrieve the termination code of the last executed motion of axis 0

mError = Ch.GetMotionError(AxisDefs.ACSC_AXIS_0);
%Retrieve the termination code asynchronuously
wb = Ch.GetMotionErrorAsync(AxisDefs.ACSC_AXIS_0);
mError = Ch.GetResult(wb, 2000);

4.32.3 GetProgramError
Description
The method retrieves the error code of the last program error encountered in the specified buffer.

Version 3.10 257

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Syntax
error = object.GetProgramError(buffer);
Async Syntax
wb = object.GetProgramErrorAsync(buffer);
Arguments

buffer Number of the program buffer.

Return Value

Scalar specifying the error code of the last program error encountered in the
error
specified buffer.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
If the program is running, the method returns zero. If the program terminates for any reason, the
method returns the termination code. To get the error explanation, use GetErrorString.
If the method fails, the Error object is filled with the error description.
Example

%Append one line to buffer 0

Ch.AppendBuffer(ProgramBuffer.ACSC_BUFFER_0,...
'!The program finished without STOP command');
%Run buffer 0
Ch.RunBuffer(ProgramBuffer.ACSC_BUFFER_0, []);
%Retrieve error 3114
pError = Ch.GetProgramError(ProgramBuffer.ACSC_BUFFER_0);
%Retrieve error 3114 asynchronuously
wb = Ch.GetProgramErrorAsync(ProgramBuffer.ACSC_BUFFER_0);
pError = Ch.GetResult(wb, 2000);

4.33 Position Event Generation (PEG) Methods

There are two groups of Position Event Generation (PEG) methods, one specifically for non- SPiiPlus
NT controllers, and one specifically for SPiiPlus NT controllers.
Table 3-36. Non-NT Position Event Generation (PEG) Methods

Method Description

Assigns engine-to-encoder as well as additional digital outputs

AssignPegNT
for use as PEG State and PEG Pulse outputs.

Version 3.10 258

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

Sets output pins assignment and mapping between FGP_OUT

AssignPegOutputsNT
signals to the bits of the ACSPL+ OUT(x) variable.

Used for switching MARK_1 physical inputs to ACSPL+ variables

AssignFastInputsNT
as Fast General Purpose inputs.

PegIncNT Sets the parameters for the Incremental PEG mode.

PegRandomNT Sets the parameters for the Random PEG mode.

Waits for the all values to be loaded and the PEG engine to be
WaitPegReadyNT
ready to respond to movement.

StartPegNT Initiates the PEG process on the specified axis.

StopPegNT Terminates the PEG process immediately on the specified axis.

4.33.1 AssignPegNT
Description
The method is used for engine-to-encoder assignment as well as for assigning additional digital
outputs assignment for use as PEG State and PEG Pulse outputs specifically for the SPiiPlus NT
family controllers.
Syntax
object.AssignPegNT(axis, engToEncBitCode, gpOutsBitCode)
Async Syntax
wb = object.AssignPegNTAsync(axis, engToEncBitCode, gpOutsBitCode)
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1

axis
to the axis 1, etc. For the axis constants see Axis Definitions.

For the bit code for engines-to-encoders mapping, see the

engToEncBitCode
SPiiPlus NT PEG and MARK Operations Application Notes.

For the General Purpose outputs assignment to use as PEG state

gpOutsBitCode and PEG pulse outputs according, see the SPiiPlus NT PEG and
MARK Operations Application Notes.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 259

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

engToEncBitCode = 0;
gpOutsBitCode = hex2dec('0b11');
%Synchronous call to AssignPegNT
Ch.AssignPegNT(AxisDefs.ACSC_AXIS_1, engToEncBitCode, gpOutsBitCode);
%Asynchronous call to AssignPegNT
wb = Ch.AssignPegNTAsync(AxisDefs.ACSC_AXIS_1, engToEncBitCode,...
gpOutsBitCode);

4.33.2 AssignPegOutputsNT
Description
The method is used for setting output pins assignment and mapping between FGP_OUT signals to
the bits of the ACSPL+ OUT(x) variable, where x is the index that has been assigned to the
controller in the network during System Configuration, specifically for the SPiiPlus NT family
controllers.
OUT is an integer array that can be used for reading or writing the current state of the General
Purpose outputs, see the SPiiPlus ACSPL+ Command & Variable Reference Guide.
Syntax
object.AssignPegOutputsNT(axis, outputIndex, bitCode);
Async Syntax
wb = object.AssignPegOutputsNTAsync(axis, outputIndex, bitCode);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions.

outputIndex 0 for OUT_0, 1 for OUT_1, ..., 9 for OUT_9

For the bit code for engine outputs to physical outputs mapping, see
bitCode
the SPiiPlus NT PEG and MARK Operations Application Notes.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

outputIndex = 0;
outputBitCode = hex2dec('0b10');
%Synchronous call to AssignPegOutputNT
Ch.AssignPegOutputsNT(AxisDefs.ACSC_AXIS_1, outputIndex, outputBitCode);
%Asynchronous call to AssignPegOutputNT

Version 3.10 260

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

wb = Ch.AssignPegOutputsNTAsync(AxisDefs.ACSC_AXIS_1,...
outputIndex, outputBitCode);

4.33.3 AssignFastInputsNT
Description
The method is used to switch MARK_1 physical inputs to ACSPL+ variables as fast general purpose
inputs.
The method is used for setting input pins assignment and mapping between FGP_IN signals to the
bits of the ACSPL+ IN(x) variable, where x is the index that has been assigned to the controller in
the network during System Configuration.
IN is an integer array that can be used for reading the current state of the General Purpose inputs,
see the SPiiPlus Command & Variable Reference Guide.
Syntax
object.AssignFastInputsNT(axis, inputIndex, bitCode);
Async Syntax
wb = object. AssignFastInputsNTAsync(axis, inputIndex, bitCode);
Arguments

Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions.

intputIndex 0 for OUT_0, 1 for OUT_1, ..., 9 for OUT_9

For bit code for engine outputs to physical outputs mapping see the
bitCode
SPiiPlus NT PEG and MARK Operations Application Notes.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The function is not related to PEG activity. It is included for the sake of completeness, since many
times fast inputs are used in applications that use PEG functionality.
Example

inputIndex = 1;
bitCode = 7;
%Synchronous call to AssignFastInputsNT
Ch.AssignFastInputsNT(AxisDefs.ACSC_AXIS_1, inputIndex, bitCode);
%Asynchronous call to AssignFastInputsNT

Version 3.10 261

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

wb = Ch.AssignFastInputsNTAsync(AxisDefs.ACSC_AXIS_1,...
inputIndex, bitCode);

4.33.4 PegIncNT
Description
The method is used for setting the parameters for the Incremental PEG mode for SPiiPlus NT family
controllers. Incremental PEG is defined by first point, last point and the interval.
Syntax
object.PegIncNT(flags, axis, width,  firstPoint, interval, lastPoint, tbNumber,  tbPeriod);
Async Syntax
wb = object.PegIncNTAsync(flags, axis, width,  firstPoint, interval, lastPoint, tbNumber,
tbPeriod);
Arguments

Bit-mapped parameter that can include one or more of the following

flags: ACSC_AMF_WAIT - the execution of the PEG is delayed until the
StartPegNT function is executed.
flags ACSC_AMF_INVERT_OUTPUT - the PEG pulse output is inverted. ACSC_
AMF_SYNCHRONOUS - PEG starts synchronously with the motion
sequence.
For the MotionFlags constants see Motion Flags

PEG axis: Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

axis
AXIS_1 to the axis 1, etc. For the axis constants see Axis Definitions..

width Width of desired pulse in milliseconds.

firstPoint Position where the first pulse is generated.

interval Distance between the pulse-generating points.

lastPoint Position where the last pulse is generated.

Number of time-based pulses generated after each encoder-based pulse.

tbNumber
If time-based pulses are not desired, assign -1 to this argument.

Period of time-based pulses. If time-based pulses are not desired, assign -

tbPeriod
1 to this parameter.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 262

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Parameters:
flags = MotionFlags.ACSC_NONE;
axis = AxisDefs.ACSC_AXIS_1;
width = 0.5;
firstPoint = 0;
interval = 200; 
lastPoint = 10000;
tbNumber = -1;
tbPeriod = -1;

%Synchronous call to PegIncNT

Ch.PegIncNT(flags, axis, width, firstPoint, interval,...
lastPoint, tbNumber, tbPeriod);
%Asynchronous call to PegIncNT
wb = Ch.PegIncNTAsync(flags, axis, width, firstPoint, interval,...
lastPoint, tbNumber, tbPeriod);

4.33.5 PegRandomNT
Description
The method is used for setting the parameters for the Random PEG mode for SPiiPlus NT family
controllers. Random PEG function specifies an array of points where position-based events should
be generated.
Syntax
object.PegRandomNT(flags, axis, width, mode, firstIndex, lastIndex, pointArray, stateArray,
tbNumber, tbPeriod);
Async Syntax
wb = object.PegRandomNTAsync(flags, axis, width, mode, firstIndex, lastIndex, pointArray,
stateArray, tbNumber, tbPeriod);
Arguments

Bit-mapped parameter that can include one or more of the following

flags:
ACSC_AMF_WAIT - the execution of the PEG is delayed until the
StartPegNT function is executed.
flags
ACSC_AMF_INVERT_OUTPUT - the PEG pulse output is inverted. ACSC_
AMF_SYNCHRONOUS - PEG starts synchronously with the motion
sequence.
For the MotionFlags constants see Motion Flags

PEG axis: Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

axis
AXIS_1 to the axis 1, etc. For the axis constants see Axis Definitions.

Version 3.10 263

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

width Width of desired pulse in milliseconds.

For the output signal configuration, see SPiiPlus NT PEG and MARK
mode
Operations Application Notes.

firstIndex Index of position in pointArray where the first pulse is generated.

lastIndex Index of position in pointArray where the last pulse is generated.

Vector of charcters specifying the name of the real array that stores
positions at which PEG pulse should be generated.
pointAray
The array must be declared as a global variable by an ACSPL+ program or
by the DeclareVariable method.

Vector of charcters specifying the name of the integer array that stores
the desired output state at each position.
stateArray The array must be declared as a global variable by an ACSPL+ program or
by the DeclareVariable method.
If output state change is not desired, this parameter should be [ ].

Number of time-based pulses generated after each encoder-based pulse.

tbNumber
If time-based pulses are not desired, assign -1 to this argument.

Period of time-based pulses. If time-based pulses are not desired, assign -

tbPeriod
1 to this parameter.

Return Value
None.
Example

%Parameters:
flags = MotionFlags.ACSC_NONE;
axis = AxisDefs.ACSC_AXIS_1;
width = 1.745;
mode = hex2dec('444');
firstIndex = 0;
lastIndex = 4;
pointArray = 'Points';
stateArray = 'States';
tbNumber = -1;
tbPeriod = -1;

%Synchronous call to PegIncNT

Ch.PegRandomNT(flags, axis, width, mode, firstIndex,lastIndex,...
pointArray, stateArray, tbNumber, tbPeriod);
%Asynchronous call to PegIncNT

Version 3.10 264

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

wb = Ch.PegRandomNTAsync(flags, axis, width, mode, firstIndex,...

lastIndex, pointArray, stateArray, tbNumber,  tbPeriod);

4.33.6 WaitPegReadyNT
Description
The method waits for the all values to be loaded and the PEG engine to be ready to respond to
movement on the specified axis for SPiiPlus NT family controllers.
The method can be used in both the Incremental and Random PEG modes.
Syntax
object.WaitPegReadyNT (axis, timeout);
Arguments

PEG axis: Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1

axis
to the axis 1, etc. For the axis constants see Axis Definitions.

Maximum waiting time in milliseconds.

timeout
If timeout is INFINITE, the method’s time-out interval never elapses.

Return Value
None.
Example

%Example call to WaitPegReadyNT

timeout = 2000;
Ch.WaitPegReadyNT(AxisDefs.ACSC_AXIS_1,timeout);

4.33.7 StartPegNT
Description
The method is used to initiate the PEG process on the specified axis for SPiiPlus NT family
controllers.
Syntax
object.StartPegNT(axis);
Async Syntax
wb = object.StartPegNTAsync(axis);
Arguments

PEG axis: Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

axis
the axis 1, etc. For the axis constants see Axis Definitions

Return Value
None.

Version 3.10 265

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Synchronous call to StartPegNT

Ch.StartPegNT(AxisDefs.ACSC_AXIS_1);
%Asynchronous call to StartPegNT
wb = Ch.StartPegNTAsync(AxisDefs.ACSC_AXIS_1);

4.33.8 StopPegNT
Description
The method is used to terminate the PEG process immediately on the specified axis for SPiiPlus NT
family controllers.
The method can be used in both the Incremental and Random PEG modes.
Syntax
object.StopPegNT(axis);
Async Syntax
wb = object.StopPegNTAsync(axis);
Arguments

PEG axis: Axis constant: ACSC_AXIS_0 corresponds to the axis 0, ACSC_AXIS_1 to

Axis
the axis 1, etc. For the axis constants see Axis Definitions.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Synchronous call to StopPegNT

Ch.StopPegNT(AxisDefs.ACSC_AXIS_1);
%Asynchronous call to StopPegNT
wb = Ch.StopPegNTAsync(AxisDefs.ACSC_AXIS_1);

4.34 Application Save/Load Methods

The Application Save/Load methods are:
Table 3-37. Application Save/Load Methods

Method Description

AnalyzeApplication Analyzes the type of application

LoadApplication Loads the applicationi

Version 3.10 266

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

SaveApplication Saves the application

FreeApplication Frees memory after application is taken off

4.34.1 Structures and Classes

The Application Loader methods employ the following structures and classes

4.34.1.1 ApplicationFileInfo
Description
This structure describes data file header, attributes array and file sections array.
Syntax
ApplicationFileInfo(filename, description, isNewFile, errCode, attributes, sections);
Properties

filename file name

description file description

isNewFile 1 - if writing new file, 0 - if adding

errCode Error code from controller

attributes array of ACSC_APPSL_ATTRIBUTE structures

sections array of ACSC_APPSL_SECTION structures

4.34.1.2 ACSC_APPSL_SECTION
Description
This structure describes any sections (or controller files).
Syntax
ACSC_APPSL_SECTION(type, filename, description, size, offset, crc, inuse, error, pData);
Properties

type Section (controller file) type

filename Section (controller file) name

description Section (controller file) description

size Data size

offset Offset in the file data section

Version 3.10 267

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

CRC Data CRC

1 - In use
inuse
0 - Not in use

error Error code

data Pointer to start of data

4.34.1.3 ACSC_APPSL_ATTRIBUTE
Description
This structure defines an attribute key-value pair.
Syntax
ACSC_APPSL_ATTRIBUTE(key, value);
Properties

key Attribute’s key.

value The value of the key.

4.34.1.4 ACSC_APPSL_STRING
Description
This structure used for Application Saver / Loader functions.
Syntax
ACSC_APPSL_STRING(value);
Properties

Value Vector of characters

4.34.2 Enumerations
The Application Loader methods employ the following enums:

4.34.2.1 ACSC_APPSL_FILETYPE
Description
Describes possible file types.
Values

ACSC_ADJ Value 0: File type is an Adjuster

ACSC_SP Value 1: File type is an SP application

ACSC_ACSPL Value 2: File type is a Program Buffer

Version 3.10 268

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

ACSC_PAR Value 3: File type is a Parameters file.

ACSC_USER Value 4: File type is a User file

4.34.3 AnalyzeApplication
Description
The method analyzes application file and returns information about the file components, such as,
saved ACSPL+ programs, configuration parameters, user files, etc.
Syntax
appFileInfo = object.AnalyzeApplication(fileName);
Arguments

fileName Vector of characters that specifies path to host application file.

Return Value

ApplicationFileInfo described in ApplicationFileInfo. If the method fails,

appFileInfo
there is exception thrown.

Example

% AnalyzeApplication method call example

appFileInfo  = Ch.AnalyzeApplication('neededFile');

4.34.4 LoadApplication
Description
The method loads user application file from a host PC to the controller flash.
Syntax
data = object.LoadApplication (string fileName, ApplicationFileInfo info)
Async Syntax
object.LoadApplicationAsync (string fileName, ApplicationFileInfo info);
Arguments

fileName Vector of characters that specifies path to host application file.

ApplicationFileInfo structure specifying application information descriptor.

info
Must be initialized by AnalyzeApplication.

Return Value

data Vector of characters specifying the user application file data.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Version 3.10 269

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

fileName = 'neededFile';
% Analyze Application file
appFileInfo  = Ch.AnalyzeApplication(fileName);
%Load application components from a file
data = Ch.LoadApplication(fileName,appFileInfo);
%Asynchronuously load application components from a file
wb = Ch.LoadApplication(fileName,appFileInfo);
data = Ch.GetResult(wb, 2000);

4.34.5 SaveApplication
Description
The method saves user application from the controller to a file on host PC.
Syntax:
data = object.SaveApplication (fileName, info);
Async Syntax:
wb = object.SaveApplicationAsync (fileName, info);
Arguments

fileName Vector of characters that specifies path to host application file.

ApplicationFileInfo structure specifying application information descriptor.

info
Must be initialized by AnalyzeApplication.

Return Value

data Vector of characters specifying the user application file data.

Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

fileName = 'neededFile';
% Analyze Application file
appFileInfo  = Ch.AnalyzeApplication(fileName);
%Save application components from a file
data = Ch.SaveApplication(fileName,appFileInfo);
%Asynchronuously svae application components from a file
wb = Ch.SaveApplication(fileName,appFileInfo);
data = Ch.GetResult(wb, 2000);

Version 3.10 270

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.34.6 FreeApplication
Description
The method frees memory, previously allocated by the AnalyzeApplication method.
Syntax:
object.FreeApplication(info);
Arguments

ApplicationFileInfo structure specifying application information descriptor. Must

info
be initialized by AnalyzeApplication.

Return Value
None
Example

%Analyze Application file

appFileInfo  = Ch.AnalyzeApplication('neededFile');
%Free memory, previously allocated by the AnalyzeApplication method
Ch.FreeApplication(appFileInfo);

4.35 Load/Upload Data To/From Controller Methods

The Load/Upload Data To/From Controller methods are:
Table 3-38. Load/Upload Data To/From Controller Methods

Method Description

Writes value(s) from text file to SPiiPlus controller

LoadDataToController
(variable or file).

Writes value(s) from SPiiPlus controller (variable or file) to

UploadDataFromController
text file.

4.35.1 LoadDataToController
Description
This method writes value(s) from text file to SPiiPlus controller (variable or file).
Syntax:
object.LoadDataToController(dest, destName, from1, to1, from2, to2, srcFilename,
srcNumFormat, bTranspose);
Async Syntax:
wb = object.LoadDataToControllerAsync(dest, destName, from1, to1, from2, to2, srcFilename,
srcNumFormat, bTranspose);

Version 3.10 271

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Number of program buffer for local variable

-1 for global and ACSPL+ variable
dest
GeneralDefinition.ACSC_FILE for loading directly to file on flash
memory (only arrays can be written directly into controller files)

destName Vector of characters specifying the name of the Variable or File.

from1/to1 Index range (first dimension)

from2/to2 Index range (second dimension)

Vector of characters specifying the filename (including path) of the

srcFilename
source text data file

Format of number(s) in source file.

Use:
srcNumFormat
GeneralDefinition.ACSC_INT_BINARY for integers
GeneralDefinition.ACSC_REAL_BINARY for real

true - array will be transposed before being loaded.

bTranspose
false - this parameter has no affect.

Return Value
None
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method writes to a specified variable (scalar/array) or straight to binary file on controller's flash
memory. The variable can be a ACSPL+ controller variable, user global or user local. The input file
must be ANSI format, otherwise an error 168 (invalid file format) is returned.
ACSPL+ and user global variables have global scope. Therefore, dest must be -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 dest is -1 (-1) and there is no global variable with the name specified by
destName, it will be defined. Arrays will be defined with dimensions (to1+1, to2+1). If performing
loading straight to file, from1, to1, from2 and to2 are meaningless.
If the variable is scalar, all indexes from1, to1, from2, and to2 must be -1. The method writes the
value from file specified by SrcFileName, to the variable specified by name. In this case if the
variable is a one-dimensional array, from1, to1 must specify the index range and from2, to2 must

Version 3.10 272

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

be -1. The text file, pointed to by srcFileName, must contain to1-from1+1 values at least. The method
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 to by srcFileName, must contain ((to1-from1+1) x (to2-from2+1)) values at least. Otherwise,
error will occur.
The method uses the text file as follows: first, the method retrieves the to2-from2+1 values and
writes them to row from1 of the specified controller variable, then retrieves next to2- from2+1
values and writes them to row from1+1 of the specified controller variable, and so forth. If
bTranspose is TRUE, the method actions are inverted. It takes to1-from1+1 values and writes them
to column from2 of the specified controller variable, then retrieves next to1- from1+1 values and
writes them to column from2+1 of the specified controller variable, and so forth.
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.
Example

%Example call LoadDataToController

%Parameters:
dest = GeneralDefinition.GetValue(GeneralDefinition.ACSC_FILE);
destName = 'MyArrayInFile';
from1 = -1;
to1 = -1;
from2 = -1;
to2 = -1;
srcFilename = 'C:\\UserArray.txt';
srcNumFormat = GeneralDefinition.GetValue(GeneralDefinition.ACSC_INT_
BINARY);
bTranspose = false;
%Load data to controller
Ch.LoadDataToController(dest, destName, from1, to1, from2, to2,
srcFilename, srcNumFormat, bTranspose);
%Load data to controller asynchronuously
wb = Ch.LoadDataToControllerAsync(dest, destName, from1, to1, from2, to2,
srcFilename, srcNumFormat, bTranspose);

4.35.2 UploadDataFromController
Description
This method writes value(s) from SPiiPlus controller (variable or file) to text file.
Syntax
object.UploadDataFromController(src, srcName, srcNumFormat, from1, to1, from2, to2,
destFilename, destNumFormat, bTranspose);
Async Syntax
wb = object.UploadDataFromControllerAsync(src, srcName, srcNumFormat, from1, to1, from2,
to2, destFilename, destNumFormat, bTranspose);

Version 3.10 273

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

Number of program buffer for local variable.

-1 for global and ACSPL+ variable,
src
GeneralDefinition.ACSC_FILE for loading directly from file on flash
memory.

srcName Vector of characters specifying the name of the Variable or File.

Format of number(s) in Controller.

Use:
srcNumFormat
GeneralDefinition.ACSC_INT_BINARY for integer,
GeneralDefinition.ACSC_REAL_BINARY for real.

from1/to1 Index range (first dimension)

from2/to2 Index range (second dimension)

Vector of characters specifying the filename (including path) of the

destFilename
destination text data file

Formatting string that will be used for printing into file.

destNumFormat Example for integer type: ‘1:%d\n’.
Example for real type: ‘1:%f\n’.

true - array will be transposed before being loaded.

bTranspose
false - this parameter has no affect.

Return Value
None
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Remarks
The method writes data to file from a specified variable (scalar/array) or straight from a binary file
in the controller’s flash memory. The variable can be an ACSPL+ controller variable, user global or
user local.
ACSPL+ and user global variables have global scope. Therefore src must have the value of -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 there is no variable (or file) with the name specified by srcName, there would be error. If
performing loading straight to file, from1, to1, from2 and to2 are meaningless.

Version 3.10 274

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

If the variable is scalar, all indexes from1, to1, from2 and to2 must be -1. The method writes the
value from variable specified by srcName, to the file specified by destFileName.
If the variable is a one-dimensional array, from1, to1 must specify the index range and from2, to2
must be -1. The method writes the values from the specified variable from index from1 to index to1
inclusively, to the file specified by destFileName.
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 method uses the variable as follows: first, the method retrieves the to2-from2+1 values from
row from1 and writes them to the file specified by destFileName, then retrieves to2- from2+1
values from row from1+1 and writes them, and so forth.
If bTranspose is TRUE, the method actions are inverted. It takes to1-from1+1 values from row from2
and writes them to first column of the specified controller variable, then retrieves the next to1-
from1 values from row from2+1 and writes them to the next column of the specified destination
file.
The destination file’s format will be determined by string specified by destNumFormat. This string
will be used as argument in the *printf function.
Example

%Example call UploadDataFromController

%Parameters:
src = GeneralDefinition.GetValue(GeneralDefinition.ACSC_FILE);
srcName = 'MyGlobalArray';
srcNumFormat = GeneralDefinition.GetValue(GeneralDefinition.ACSC_INT_
BINARY);
from1 = 0;
to1 = 3;
from2 = 2;
to2 = 4;
destFilename = 'C:\\UserArray.txt';
destNumFormat = '%d , ';
bTranspose = false;
%Upload data from controller
Ch.UploadDataFromController(src, srcName, srcNumFormat, from1, to1,
from2, to2, destFilename, destNumFormat, bTranspose);
%Upload data from controller asynchronuously
wb = Ch.UploadDataFromControllerAsync(src, srcName, srcNumFormat, from1,
to1, from2, to2, destFilename, destNumFormat, bTranspose);

4.36 Emergency Stop Methods

The Emergency Stop methods are:
Table 3-39. Emergency Stop Methods

Method Description

RegisterEmergencyStop Enables Emergency Stop function.

Version 3.10 275

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Method Description

UnregisterEmergencyStop Disables Emergency Stop function.

4.36.1 RegisterEmergencyStop
Description
This method initiates the “Emergency Stop” functionality for the calling application.
Syntax
object.RegisterEmergencyStop;
Return Value
None
Remarks
SPiiPlus UMD and Library provide the user application with the ability to open/close the Emergency
Stop button (shown in Figure 3-1). Clicking the Emergency Stop button sends a stop to all motions
and motors command to all channels, which used in calling application, thereby stopping all motions
and disabling all motors.

Figure 3-1. Emergency Stop Button

Calling RegisterEmergencyStop causes the Emergency Stop button icon to appear in the right
bottom corner of the screen. If there is already such a button that is in use by other applications, a
new button does not appear; but all functionality is available for the new application.
Calling RegisterEmergencyStop requires having the local host SPiiPlus UMD running, even if it is
used through a remote connection because the Emergency Stop button is part of the local SPiiPlus
UMD. If there is no local SPiiPlus UMD running, the method fails.
Only a single call is required per application. It can be placed anywhere in code, even before the
opening of communication with controllers.
The application can remove the Emergency Stop button by calling UnregisterEmergencyStop. The
Emergency Stop button disappears if there are no additional registered applications that use it. The
termination of SPiiPlus UMD also removes the Emergency Stop button; therefore, if SPiiPlus UMD is
restarted, RegisterEmergencyStop has to be called again.
Calling RegisterEmergencyStop more than once per application is meaningless, but the method
succeeds anyway. In order to ensure that Emergency Stop button is active, it is recommended
placing a call of RegisterEmergencyStop after each call of any of OpenComm*** functions.

Version 3.10 276

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Example

%Example call Register Emergency stop

Ch.RegisterEmergencyStop;

4.36.2 UnregisterEmergencyStop
Description
This method terminates the “Emergency Stop” functionality for the calling application.
Syntax
object.UnregisterEmergencyStop;
Return Value
None
Remarks
Calling UnregisterEmergencyStop causes an application not to respond if the Emergency Stop
button is clicked. If there are no other applications that registered the Emergency Stop
functionality, the button will disappear.
Calling UnregisterEmergencyStop more than once per application is meaningless, but method will
succeed anyway.
Example

%Example call Unregister Emergency stop

Ch.UnregisterEmergencyStop;

4.37 Reboot Methods

The Reboot methods are:
Table 3-40. Reboot Methods

Method Description

ControllerReboot Reboots controller and waits for process completion.

Reboots controller, restores factory default settings and

ControllerFactoryDefault
waits for process completion.

4.37.1 ControllerReboot
Description
This method reboots controller and waits for process completion.
Syntax
object.ControllerReboot(timeout);

Version 3.10 277

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Arguments

timeout Maximum waiting time in milliseconds.

Return Value
None
Example

%Open Ethernet with TCP protocol communication with the controller

%IP address: 10.0.0.100
port = EthernetCommOption.GetValue(EthernetCommOption.ACSC_SOCKET_STREAM_
PORT);
ip = '10.0.0.100';
Ch.OpenCommEthernetTCP(ip, port);
Ch.ControllerReboot(30000);
Ch.CloseComm;

4.37.2 ControllerFactoryDefault
Description
The method reboots the controller, restores factory default settings and waits for process
completion.
Syntax
object.ControllerFactoryDefault(timeout);
Arguments

timeout Maximum waiting time in milliseconds.

Return Value
None.
Example

%Open Ethernet with TCP protocol communication with the controller

%IP address: 10.0.0.100
port = EthernetCommOption.GetValue(EthernetCommOption.ACSC_SOCKET_STREAM_
PORT);
ip = '10.0.0.100';
Ch.OpenCommEthernetTCP(ip, port);
Ch.ControllerFactoryDefault(30000);
Ch.CloseComm;

4.38 Host-Controller File Operations

Host PC files can be copied to controller's non-volatile memory and user files can be deleted from
the controller's non-volatile memory as described in this section.

Version 3.10 278

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Table 3-41. Host-Controller File Copying Methods

Method Description

The function copies files from the host PC to the

CopyFileToController
controller's non-volatile memory

The function deletes user files from the controller's non-

DeleteFileFromController
volatile memory.

4.38.1 CopyFileToController
Description
The function copies file from host PC to controller’s non-volatile memory.
Syntax
object.CopyFileToController(sourceFileName, destinationFileName);
Async Syntax
wb = object.CopyFileToControllerAsync(sourceFileName, destinationFileName);
Arguments

Vector of characters specifying the name of the source file on

sourceFileName
host PC.

Vector of characters specifying the name of destination file on

destinationFileName
the controller.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Example call CopyFileToController

Ch.CopyFileToController('C:\\tmp.txt','tmp.txt');
%Asynchronuous call CopyFileToController
wb = Ch.CopyFileToControllerAsync('C:\\tmp.txt','tmp.txt');

4.38.2 DeleteFileFromController
Description
The function deletes user files from controller's non-volatile memory.
Syntax
object.DeleteFileFromController(fileName);

Version 3.10 279

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Async Syntax
wb = object.DeleteFileFromControllerAsync(fileName);
Arguments

Vector of characters specifying the name of the user file on controller's

fileName
non- volatile memory.

Return Value
None.
Return Value (async call)

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%Example call DeleteFileFromController

Ch.DeleteFileFromController('tmp.txt');
%Asynchronuous call DeleteFileFromController
wb = Ch.DeleteFileFromControllerAsync('tmp.txt');

4.39 Save to Flash Functions

The Save to flash method is
Table 3-42. Save to Flash Methods

Method Description

The function saves user application to the controller's non-

ControllerSaveToFlash
volatile memory.

4.39.1 ControllerSaveToFlash
Description
The function saves user application to the controller's non-volatile memory.
Syntax
object.ControllerSaveToFlash (parameters, buffers, sPPrograms, userArrays);
Arguments

Array of axis constants: ACSC_AXIS_0 corresponds to the axis 0, ACSC_

AXIS_1 to the axis 1, etc.
parameters For the axis constants see Axis Definitions.
After the last axis, one additional element must be included that
contains ACSC_AXIS_NONE and marks the end of the array.

Version 3.10 280

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

Array of buffer constants. Each element specifies one involved buffer:

ACSC_BUFFER_0 corresponds to buffer 0, ACSC_BUFFER_1 to buffer 1,
etc.

buffers If all buffers need to be specified, ACSC_BUFFER_ALL should be used.

After the last buffer, one additional element must be included that
contains ACSC_NONE and marks the end of the array.
For the buffer constants see Buffer Definitions.

Array of Servo Processor (SP) constants. Each element specifies one

involved SP: ACSC_SP_0 corresponds to SP 0, ACSC_SP_1 to SP 1, etc.
If all SPs need to be specified, ACSC_SP_ALL should be used.
sPPrograms
After the last SP, one additional element must be included that
contains ACSC_NONE and marks the end of the array.
For the SP constants see Servo Processor (SP) Definitions.

Vector of characters containing chained names of user arrays, separated

by '\r'(13) character.
userArrays
If there is no need to save user arrays to controller's non-volatile
memory, this parameter should be [ ].

Return Value

wb ACSC_WAITBLOCK object returned by invocation of asynchronous call.

Example

%The following code sample saves all axes parameters and buffers to
%flash, with two user arrays: 'MyArray' and 'MyArray2'.
parameters = Axis.ToNetArray(AxisDefs.ACSC_AXIS_0, AxisDefs.ACSC_AXIS_1);
buffers = ProgramBuffer.ToNetArray(ProgramBuffer.ACSC_BUFFER_0,...
ProgramBuffer.ACSC_BUFFER_1);
sPPrograms = ServoProcessor.ToNetArray(ServoProcessor.ACSC_SP_0,...
ServoProcessor.ACSC_SP_1);
userArrays = 'MyArray\rMyArray2';
Ch.ControllerSaveToFlash(parameters, buffers, sPPrograms, userArrays);

4.40 SPiiPlusSC Management

The SPiiPlusSC Management methods are:
Table 3-43. SPiiPlusSC Management Methods

Method Description

StartSPiiPlusSC The function starts the SPiiPlusSC controller.

StopSPiiPlusSC The function stops the SPiiPlusSC controller.

Version 3.10 281

 SPiiPlus MATLAB Library Programmer's Guide
4.   Methods

4.40.1 StartSPiiPlusSC
Description
The function starts the SPiiPlusSC controller.
Syntax
object.StartSPiiPlusSC;
Arguments
None
Return Value
None
Example

%Example call StartSPiiPlusSC

Ch.StartSPiiPlusSC;

4.40.2 StopSPiiPlusSC
Description
The function stops the SPiiPlusSC controller.
Syntax
object.StopSPiiPlusSC;
Arguments
None
Return Value
None
Example

%Example call StopSPiiPlusSC

Ch.StopSPiiPlusSC;

Version 3.10 282

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

5. Enumerations
This chapter presents the built-in enumeration types that are used for establishing various
properties during program runtime. For each property, the name of the constant, its value and a
description are given.

5.1 General Definitions

Syntax:
GeneralDefinition
Table 4-1. GeneralDefinitions

Name Value Description

ACSC_VER 0x63F1100

ACSC_INT_BINARY 4 Integer type of the variable

ACSC_REAL_BINARY 8 Real type of the variable

ACSC_FILE -2

ACSC_AXES_MAX_NUMBER 64 Maximum number of axes

ACSC_BUFFERS_MAX_
65 Maximum number of Program buffers
NUMBER

ACSC_SP_MAX_NUMBER 64 Maximum number of Servo Processors

ACSC_DC_VAR_MAX_
10
NUMBER

Maximum number of lines in the program

ACSC_MAX_LINE 100000
buffer

5.2 General Communication Options

Syntax:
CommOptions
Table 4-2. General Communication Options

Name Value Description

ACSC_NONE 0

ACSC_ALL -1

Version 3.10 283

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Name Value Description

The communication mode when each

ACSC_COMM_USE_ command is sent to the controller with
0x00000001
CHECKSUM checksum and the controller also responds
with checksum.

When a hardware error is detected in the

ACSC_COMM_ communication channel and this bit is set, the
AUTORECOVER_HW_ 0x00000002 library automatically repeats the transaction,
ERROR without counting iterations. By default, this
flag is not set.

5.3 Ethernet Communication Options

Syntax:
EthernetCommOption
Table 4-3. Ethernet Communication Options

Name Value Description

ACSC_SOCKET_ The library opens Ethernet communication using the

700
DGRAM_PORT connectionless socket and UDP communication protocol.

The library opens Ethernet communication using the

ACSC_SOCKET_
701 connection- oriented socket and TCP communication
STREAM_PORT
protocol.

5.4 Axis Definitions

Syntax:
AxisDefs
Description
The general format for any axis definition is:
ACSC_AXIS_index
Where index is a number that ranges between 0 and 63, such as ACSC_AXIS_0, ACSC_AXIS_1, ACSC_
AXIS_30, etc. The axis constant contains the value associated with the index, that is, ACSC_AXIS_0
has a value of 0, ACSC_AXIS_1 has a value of 1, and so forth. ACSC_PAR_ALL stands for all
parameters (system and all axes parameters) and ACSC_SYSTEM stands for the system
parameters.ACSC_NONE has a value of -1 and serves as axes array terminator.

5.5 Buffer Definitions

Syntax:
ProgramBuffer

Version 3.10 284

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Description
The general format for any buffer definition is:
ACSC_BUFFER_index
Where index is a number that ranges between 0 and 64, such as ACSC_BUFFER_0, ACSC_BUFFER_1,
ACSC_BUFFER_64, etc. The buffer constant contains the value associated with the index, that is,
ACSC_BUFFER_0 has a value of 0, ACSC_BUFFER_1 has a value of 1, and so forth. ACSC_BUFFER_ALL
stands for all buffers.ACSC_NONE has a value of -1 and serves as buffer array terminator.

5.6 Servo Processor (SP) Definitions

Syntax:
ServoProcessor
Description
The general format for any SP definition is:
ACSC_SP_index
Where index is a number that ranges between 0 and 63, such as ACSC_SP_0, ACSC_SP_1, ACSC_SP_
63, etc. The SP constant contains the value associated with the index, that is, ACSC_SP_0 has a value
of 0, ACSC_SP_1 has a value of 1, and so forth. ACSC_SP_ALL stands for all SPs. ACSC_NONE has a
value of -1 and serves as array terminator.

5.7 EtherCAT Flags

Syntax:
EtherCatFlags
Table 4-4. EtherCAT Flags

Name Value Description

ACSC_NONE 0 Disable all EtherCAT flags

ACSC_ALL -1 Enable all EtherCAT flags

ACSC_ETHERCAT_1BYTE 0x00000001

ACSC_ETHERCAT_2BYTES 0x00000002

ACSC_ETHERCAT_4BYTES 0x00000004

ACSC_ETHERCAT_FLOAT 0x00000008

ACSC_DEFAULT_REMOTE_PORT 9999

5.8 Motion Flags

Syntax:
MotionFlags

Version 3.10 285

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Table 4-5. Motion Flags

Name Value Description

ACSC_NONE 0 Disables all motion flags

ACSC_ALL -1 Enables all motion flags

The controller plans the motion but

ACSC_AMF_WAIT 0x00000001 doesn’t start it until the Go method is
executed.

The value of the point coordinate is

ACSC_AMF_RELATIVE 0x00000002 relative to the end point coordinate of the
previous motion.

The motion uses the specified velocity

ACSC_AMF_VELOCITY 0x00000004
instead of the default velocity.

ACSC_AMF_ The motion comes to the end point with

0x00000008
ENDVELOCITY the specified velocity

ACSC_AMF_ The slaved motion uses position lock. If the

0x00000010
POSITIONLOCK flag is not specified, velocity lock is used.

ACSC_AMF_
0x00000020 The slaved motion uses velocity lock.
VELOCITYLOCK

The motion uses the point sequence as a

cyclic array: after positioning to the last
ACSC_AMF_CYCLIC 0x00000100
point it does positioning to the first point
and continues.

The time interval between adjacent points

of the spline (arbitrary path) motion is non-
ACSC_AMF_VARTIME 0x00000200 uniform and is specified along with an
each added point. If the flag is not
specified, the interval is uniform.

Use a cubic interpolation between the

specified points (third-order spline) for the
spline (arbitrary path) motion. If the flag is
ACSC_AMF_CUBIC 0x00000400
not specified, linear interpolation is used
(first-order spline). [In the present version
third-order spline is not supported].

Version 3.10 286

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Name Value Description

Segmented slaved motion: if a master

ACSC_AMF_ value travels beyond the specified path,
0x00001000
EXTRAPOLATED the last or the first segment is
extrapolated.

Segmented slaved motion: if a master

ACSC_AMF_STALLED 0x00002000 value travels beyond the specified path,
the motion stalls at the last or first point.

Multi-axis motion does not use the motion

parameters from the leading axis but
ACSC_AMF_MAXIMUM 0x00004000 calculates the maximum allowed motion
velocity, acceleration, deceleration and
jerk of the involved axes.

ACSC_AMF_ Position Event Generation (PEG): Start PEG

0x00008000
SYNCHRONOUS synchronously with the motion sequence.

ACSC_AMF_
0x00010000 Decelerate to corner.
JUNCTIONVELOCITY

Do not treat junction as a corner, if junction

ACSC_AMF_ANGLE 0x00020000 angle is less than or equal to the specified
value in radians.

ACSC_AMF_ Synchronize user variables with segment

0x00040000
USERVARIABLES execution.

ACSC_AMF_INVERT_
0x00080000 The PEG pulse output is inverted.
OUTPUT

Syntax:
RotationDirection
Table 4-6. Rotation Directrion Flags

Name Value Description

ACSC_COUNTERCLOCKWISE 1 Counter clockwise rotation

ACSC_CLOCKWISE -1 Clockwise rotation

Syntax:
GlobalDirection

Version 3.10 287

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Table 4-7. Global Directrion Flags

Name Value Description

ACSC_POSITIVE_DIRECTION 1 Axis movement in positive direction

ACSC_NEGATIVE_DIRECTION -1 Axis movement in negative direction

5.9 Data Collection Flags

Syntax:
DataCollectionFlags
Table 4-8. Data Collection Flags

Name Value Description

ACSC_NONE 0 Disables all data collections flags

ACSC_ALL -1 Enables all data collection flags

Temporal data collection. The sampling period is

ACSC_DCF_
0x00000001 calculated automatically according to the collection
TEMPORAL
time.

Cyclic data collection uses the collection array as a

ACSC_DCF_ cyclic buffer and continues infinitely. When the
0x00000002
CYCLIC array is full, each new sample overwrites the
oldest sample in the array.

Starts data collection synchronously to a motion.

ACSC_DCF_
0x00000004 Data collection started with the ACSC_DCF_SYNC
SYNC
flag is called axis data collection.

Creates synchronous data collection, but does not

ACSC_DCF_
0x00000008 start until the Go method is called. This flag can
WAIT
only be used with the ACSC_DCF_SYNC flag.

5.10 Motor State Flags

Syntax:
MotorStates
Table 4-9. Motor State Flags

Name Value Description

ACSC_NONE 0 Disables all motor state flags

Version 3.10 288

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Name Value Description

ACSC_ALL -1 Enables all motor state flags

ACSC_MST_ENABLE 0x00000001 Motor is enabled

ACSC_MST_INPOS 0x00000010 Motor has reached a target position.

ACSC_MST_MOVE 0x00000020 Motor is moving.

ACSC_MST_ACC 0x00000040 Motor is accelerating.

5.11 Axis State Flags

Syntax:
AxisStates
Table 4-10. Axis State Flags

Name Value Description

ACSC_NONE 0 Disables all axis state flags

ACSC_ALL -1 Enables all axis state flags

ACSC_AST_
0x00000001 Axis is leading in a group.
LEAD

ACSC_AST_
0x00000002 Axis data collection is in progress.
DC

ACSC_AST_
0x00000004 PEG for the specified axis is in progress.
PEG

ACSC_AST_
0x00000020 Axis is moving.
MOVE

ACSC_AST_
0x00000040 Axis is accelerating.
ACC

ACSC_AST_ Slave motion for the specified axis is synchronized

0x00000100
VELLOCK to master in velocity lock mode.

ACSC_AST_ Slave motion for the specified axis is synchronized

0x00000200
POSLOCK to master in position lock mode.

5.12 Index and Mark State Flags

Syntax:
IndexStates

Version 3.10 289

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Table 4-11. Index and Mark State Flags

Name Value Description

ACSC_NONE 0 Disables all index state flags

ACSC_ALL -1 Enables all index state flags

ACSC_IST_
0x00000001 Primary encoder index of the specified axis is latched.
IND

ACSC_IST_ Secondary encoder index of the specified axis is

0x00000002
IND2 latched.

ACSC_IST_ MARK1 signal has been generated and position of the

0x00000004
MARK specified axis was latched.

ACSC_IST_ MARK2 signal has been generated and position of the

0x00000008
MARK2 specified axis was latched.

5.13 Program State Flags

Syntax:
ProgramStates
Table 4-12. Program State Flags

Name Value Description

ACSC_NONE 0 Disables all program state flags

ACSC_ALL -1 Enables all program state flags

ACSC_PST_
0x00000001 Program in the specified buffer is compiled.
COMPILED

ACSC_PST_
0x00000002 Program in the specified buffer is running.
RUN

Program in the specified buffer is suspended after

ACSC_PST_
0x00000004 the step execution or due to breakpoint in debug
SUSPEND
mode.

ACSC_PST_ Program in the specified buffer is executed in

0x00000020
DEBUG debug mode, i.e. breakpoints are active.

ACSC_PST_
0x00000080 Auto routine in the specified buffer is running.
AUTO

Version 3.10 290

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

5.14 Safety Control Masks

Syntax:
SafetyControlMasks: uint
Table 4-13. Safety Control Masks

Name Value Description Type

Disables all safety mask

ACSC_NONE 0
flags

Enables all safety mask

ACSC_ALL -1
flags

ACSC_SAFETY_RL 0x00000001 Right Limit Motor fault

ACSC_SAFETY_LL 0x00000002 Left Limit Motor fault

ACSC_SAFETY_ Network
0x00000004 Network Error
NETWORK fault

ACSC_SAFETY_HOT 0x00000010 Motor Overheat Motor fault

ACSC_SAFETY_SRL 0x00000020 Software Right Limit Motor fault

ACSC_SAFETY_SLL 0x00000040 Software Left Limit Motor fault

ACSC_SAFETY_ Primary Encoder Not

0x00000080 Motor fault
ENCNC Connected

ACSC_SAFETY_ Secondary Encoder Not

0x00000100 Motor fault
ENC2NC Connected

ACSC_SAFETY_
0x00000200 Driver Alarm Motor fault
DRIVE

ACSC_SAFETY_ENC 0x00000400 Primary Encoder Error Motor fault

ACSC_SAFETY_ENC2 0x00000800 Secondary Encoder Error Motor fault

ACSC_SAFETY_PE 0x00001000 Position Error Motor fault

ACSC_SAFETY_CPE 0x00002000 Critical Position Error Motor fault

ACSC_SAFETY_VL 0x00004000 Velocity Limit Motor fault

ACSC_SAFETY_AL 0x00008000 Acceleration Limit Motor fault

Version 3.10 291

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Name Value Description Type

ACSC_SAFETY_CL 0x00010000 Current Limit Motor fault

ACSC_SAFETY_SP 0x00020000 Servo Processor Alarm Motor fault

ACSC_SAFETY_PROG 0x02000000 Program Error System fault

ACSC_SAFETY_MEM 0x04000000 Memory Overuse System fault

ACSC_SAFETY_TIME 0x08000000 Time Overuse System fault

ACSC_SAFETY_ES 0x10000000 Emergency Stop System fault

ACSC_SAFETY_INT 0x20000000 Servo Interrupt System fault

ACSC_SAFETY_
0x40000000 Integrity Violation System fault
INTGR

See the SPiiPlus ACSPL+ Programmer’s Guide for detailed explanations of faults.

5.15 Interrupt Types

Syntax:
Interrupts
Table 4-14. Interrupt Types

Name Value Description

ACSPL+ program
has generated the
ACSC_INTR_ACSPL_PROGRAM 22 interrupt by
INTERRUPT
command.

A user has sent the

ACSC_INTR_ACSPL_PROGRAM_EX 21 INTERRUPTEX
Command.

Communication
ACSC_INTR_COMM_CHANNEL_
32 channel has been
CLOSED
closed.

Version 3.10 292

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Name Value Description

A line of ACSPL+
commands has
ACSC_INTR_COMMAND 21
been executed in a
dynamic buffer.

EMERGENCY STOP
ACSC_INTR_EMERGENCY 15 signal has been
generated.

EtherCAT error
ACSC_INTR_ETHERCAT_ERROR 29
occurred.

Logical motion has

ACSC_INTR_LOGICAL_MOTION_END 17
finished.

Motion has been

ACSC_INTR_MOTION_FAILURE 18 interrupted due to
a fault.

ACSC_INTR_MOTION_PHASE_ Motion profile

25
CHANGE changed the phase

Physical motion has

ACSC_INTR_MOTION_START 24
started.

Motor has been

ACSC_INTR_MOTOR_FAILURE 19 disabled due to a
fault.

AST.#NEWSEGM bit
ACSC_INTR_NEWSEGM 27
went high.

Physical motion has

ACSC_INTR_PHYSICAL_MOTION_END 16
finished.

ACSPL+ program
ACSC_INTR_PROGRAM_END 20
has finished.

EStop button was

ACSC_INTR_SOFTWARE_ESTOP 33
clicked.

System error
ACSC_INTR_SYSTEM_ERROR 28
occurred.

AST.#TRIGGER bit
ACSC_INTR_TRIGGER 26
went high

Version 3.10 293

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

5.16 Callback Interrupt Masks

Syntax:
AxisMasks
Table 4-15. Callback Interrupt Axis Masks

Bit Name Bit Desc. Interrupt

ACSC_NONE 0

ACSC_ALL -1

ACSC_INTR_PEG,
ACSC_INTR_
MARK1, ACSC_
INTR_MARK2,
ACSC_INTR_
PHYSICAL_
MOTION_END,
ACSC_INTR_
LOGICAL_
ACSC_MASK_AXIS_0 0 Axis 0
MOTION_END,
... ACSC_INTR_
ACSC_MASK_AXIS_63 63 Axis 63 MOTION_
FAILURE, ACSC_
INTR_MOTOR_
FAILURE, ACSC_
INTR_MOTION_
START, ACSC_
INTR_MOTION_
PHASE_CHANGE,
ACSC_INTR_
TRIGGER

5.17 Configuration Keys

Syntax:
ConfigKey
Table 4-16. Configuration Keys

Key Name Key Description

ACSC_CONF _WORD1_ Bit 6 defines HSSI route, bit 7 defines source for
1
KEY interrupt generation.

Version 3.10 294

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Key Name Key Description

ACSC_CONF _INT_EDGE_
3 Sets the interrupt edge to be positive or negative.
KEY

ACSC_CONF _ENCODER_
4 Sets encoder type: A&B or analog.
KEY

Sets the specified output pin to be one of the

following:
ACSC_CONF_OUT_KEY 29
OUT0 PEG
Brake

ACSC_CONF _MFLAGS9_
204 Controls value of MFLAGS.9
KEY

ACSC_CONF_DIGITAL_ Assigns use of OUT0 signal: general purpose

205
SOURCE_KEY output or PEG output.

ACSC_CONF_SP_OUT_
206 Reads SP output pins.
PINS_KEY

ACSC_CONF_BRAKE_
229 Controls brake method.
OUT_KEY

5.18 System Information Keys

Syntax:
SystemInfoKey
Table 4-17. System Information Keys

Key Name Key Description

ACSC_SYS_MODEL_KEY 1

ACSC_SYS_VERSION_KEY 2

ACSC_SYS_NBUFFERS_KEY 10

ACSC_SYS_DBUF_INDEX_KEY 11

ACSC_SYS_NAXES_KEY 13

ACSC_SYS_NNODES_KEY 14

ACSC_SYS_NDCCH_KEY 15

ACSC_SYS_ECAT_KEY 17

Version 3.10 295

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

5.19 Representation, Variables and Return Types Definitions

Syntax:
ACSC_RETURN_TYPE
Table 4-18. Return Types

Name Value Description

Default_Type 0

String_Type 0

Buffer_Type 1

Integer_Type 2

Real_Type 3

Scalar_Type 4

Vector_Type 5

Matrix_Type 6

Typeless_Type 7

Binary_Type 8

Syntax:
public enum AcsplVariableType
Table 4-19. ACSPL+ Variables Types

Name Value Description

ACSC_INT_TYPE 1 Integer Variable type

ACSC_REAL_TYPE 2 Real Variable type

Syntax:
RepresentationTypes
Table 4-20. Representation Types

Name Value Description

ACSC_NONE 0

ACSC_ALL -1

Version 3.10 296

 SPiiPlus MATLAB Library Programmer's Guide
5.   Enumerations

Name Value Description

ACSC_DEC_REAL_TYPE 8

ACSC_DEC_INT_TYPE 4

ACSC_BIN_INT_TYPE 2

ACSC_OCT_INT_TYPE 1

ACSC_HEX_INT_TYPE 16

5.20 Log Detalization and Presentation Definitions

Syntax:
public enum ACSC_LOG_DETALIZATION_LEVEL
Table 4-21. Log Detalization Definitions

Name Value Description

Minimum 0 Only communication traffic will be logged.

Communication traffic and some internal C Libprocess data

Medium 1
will be logged.

Communication traffic and all internal processdata will be

Maximum 2
logged.

Syntax:
public enum ACSC_LOG_DATA_PRESENTATION
Table 4-22. Log Presentation Definitions

Name Value Description

No more than the first ten bytes of each data string will be
Compact 0 logged. Non-printing characters will be represented in
HexASCII code.

All the binary data will be logged. Non-printingcharacters

Formatted 1
will be represented in Hex ASCII code.

Full 2 All the binary data will be logged as is.

Version 3.10 297

 SPiiPlus MATLAB Library Programmer's Guide
6.   Events

6. Events
SPiiPlus MATLAB Library has events for the following types of interrupts:

The bit-mapped event parameter: Param is an interrupt mask that determines which
axis/buffer/input a given interrupt was generated for. See Callback Interrupt Masks for
a description of Param for each interrupt.

Table 5-1. Events and Interrupts

Event Interrupt

ExACSPLCOMMAND (long Param) ACSC_INTR_COMMAND

ExACSPLPROGRAM (BufferMasks Param) ACSC_INTR_ACSPL_PROGRAM

ExCOMMCHANNELCLOSED ACSC_INTR_COMM_CHANNEL_CLOSED

ExEMERGENCY ACSC_INTR_EMERGENCY

ExETHERCATERROR ACSC_INTR_ETHERCAT_ERROR

ExLOGICALMOTIONEND (AxisMasks Param) ACSC_INTR_LOGICAL_MOTION_END

ExMOTIONFAILURE (AxisMasks Param) ACSC_INTR_MOTION_FAILURE

ExMOTIONPHASECHANGE (AxisMasks Param) ACSC_INTR_MOTION_PHASE_CHANGE

ExMOTIONSTART (AxisMasks Param). ACSC_INTR_MOTION_START

ExMOTORFAILURE (AxisMasks Param) ACSC_INTR_MOTOR_FAILURE

ExNEWSEGM ACSC_INTR_NEWSEGM

ExPHYSICALMOTIONEND (AxisMasks Param) ACSC_INTR_PHYSICAL_MOTION_END

ExPROGRAMEND (BufferMasks Param) ACSC_INTR_PROGRAM_END

ExSOFTWAREESTOP ACSC_INTR_SOFTWARE_ESTOP

ExSYSTEMERROR ACSC_INTR_SYSTEM_ERROR

ExSYSTEMERROR ACSC_INTR_ACSPL_PROGRAM_EX

ExTRIGGER (AxisMasks Param) ACSC_INTR_TRIGGER

Version 3.10 298

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

7. Error Handling
The SPiiPlus MATLAB Library throws ACSException when API function fails to complete the
requested operation successfully. The exception object contains an error code and an error
description that can be used to evaluate the error occurred.
> Error code, received from GetLastError function (see Error Codes).
> A string with a description of the error.
For example: Communication Initialization failure. Error – 132

7.1 Error Handling Example in C#

The following code illustrates error handling in C#:

private void OpenCommSerial

{
try {
Ch.OpenCommSerial(1,115200);
}
catch (ACSException ex)
{
%handle Exception
}
}

7.2 Error Codes

This section provides a breakdown of the Error codes associated with the .NET Library.

Any error code greater than 1000 is a controller error as defined in the SPiiPlus
Command & Variable Reference Guide.

Table 6-1. NET Library Error Codes

Error
Error Message Remarks
Code

Attempt was made to use a method asynchronously

Asynchronous call is
101 that is only support synchronously, for example,
not supported.
Send.

This error is returned by the OpenLogFile method if a

No such file or
102 component of a path does not specify an existing
directory.
directory.

Version 3.10 299

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

Error
Error Message Remarks
Code

The FW version
does not support This error is returned by one of the OpenComm
103
the current COM methods. Upgrade the FW of the controller.
Library version.

Controllers reply is A timeout has occurred due to a lack of response of

104
too long. the controller.

Internal library error:

109
Invalid file handle.

Internal library error:

122 Cannot open Log
file.

Too many open This error is returned by the OpenLogFile method if

124
files. no more file handles available.

This error is returned by the WriteLogFile method if

No space left on
128 no more space for writing is available on the device
device.
(for example, when the disk is full).

This error indicates that during specified timeout the

130 Timeout expired.
controller did not respond or response was invalid.

This error is returned by one of the

Open*** methods in the following cases:
Communication
132 the specified communication parameters are
initialization failure.
invalid,the corresponding physical connection is not
established,the controller does not respond for
specified communication channel.

Internal library error:

Creating
133
communication
object failure.

Invalid
Specified communication handle must be a handle
134 communication
returned by one of the Open*** methods.
handle.

All channels are The maximum number of the concurrently opened

135
busy. communication channels is 10.

Version 3.10 300

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

Error
Error Message Remarks
Code

This error is returned by the OpenLogFile method if

Invalid name of Log
136 the specified log file name is invalid or more than 256
file.
characters.

Received message
is too long (more This error cannot be returned and is present for
137
than size of user compatibility with previous versions of the library.
buffer).

This error is returned by either one of the

The program string
138 AppendBuffer or LoadBuffer method if ACSPL+
is long.
program contains a string longer than 2032 bytes.

Method parameters
139
are invalid.

History buffer is
140
closed.

Name of variable
141
must be specified.

This error is returned by the ReadVariable,

ReadVariableAsScalar, ReadVariableAsVector,
Error in index
142 ReadVariableAsMatrix, WriteVariable methods if the
specification.
From1, To1, From2, To2 arguments were specified
incorrectly.

Controller reply This error is returned by the ReadVariable,

143 contains less values ReadVariableAsScalar, ReadVariableAsVector,
than expected. ReadVariableAsMatrix, WriteVariable methods.

Function is not
145 supported in
current version

Internal error: Error

147 of the history buffer
initialization.

Unsolicited
150 messages buffer is
closed.

Version 3.10 301

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

Error
Error Message Remarks
Code

This error is returned by the EnableEvent method for

Callback registration any of the communication channels.
151
error.
Only PCI Bus communication supports user callbacks.

This error is returned by the EnableEvent method if

Callback method has
the application tries to enable another event for the
152 been already
same interrupt that was already used. Only one
installed.
event can be enabled for each interrupt.

Checksum of the
153 controller response
is incorrect.

Internal library error:

The controller
154
replies sequence is
invalid.

155 Internal library error.

Internal library error:

Error of the
157 unsolicited
messages buffer
initialization.

Non-waiting call has

158
been aborted.

Error of the non-

159 waiting call
cancellation.

Internal error:
Queue of
160
transmitted
commands is full.

The library cannot

send to the
Check physical connection with the controller (or
162 specified
settings) and try to reconnect.
communication
channel.

Version 3.10 302

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

Error
Error Message Remarks
Code

The library cannot

receive from the
Check physical connection with the controller (or
163 specified
settings) and try to reconnect.
communication
channel.

Internal library error:

164 Sending of the chain
is failed.

Specified IP address
165
is duplicated.

There is no
166 Application with
such Handle.

Array name was

167
expected.

168 File is not Data File. Input file is not in ANSI format.

Application Saver
171
Loader CRC Error

Application Saver
172 Loader Header CRC
Error

Application Saver
173 Loader File Size
Error

Application Saver
174 Loader File Open
Error

Application Saver
175 Loader Unknown
File Error

Application Saver
176 Loader Format
Version Error

Version 3.10 303

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

Error
Error Message Remarks
Code

Application Saver
177 Loader Section Size
is Zero

Internal library error:

179 Thread local storage
error.

Returned by the GetPCICards method in the following

cases:
PCI driver SpiiPlus PCI driver is not installed correctly.
180
initialization error.
The version of the SpiiPlus PCI Bus driver is incorrect -
in this case, it is necessary to reinstall the SpiiPlus PCI
driver (WINDRIVER) and the library.

Pointer to the
buffer is invalid or
Null pointer
185
received instead of
user allocated
object

Specified priority for

189 the callback thread
cannot be set

Cannot access
DPRAM directly Returned by DPRAM access methods, when
190 through any attempting to call them with Serial or Ethernet
channel but PCI and channels.
Direct.

Invalid DPRAM
Returned by DPRAM access methods, when
192 address was
attempting to access illegal address
specified

This version of
Returned by DPRAM access methods, when
simulator does not
193 attempting to access old version Simulator that does
support work with
not support DPRAM.
DPRAM.

Version 3.10 304

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

Error
Error Message Remarks
Code

Returned by methods that work with host file system

195 File not found. when a specified filename is not found.
Check the path and filename.

Returned by methods that analyze SPiiPlus

application files when application file format is
196 Not enough data. incorrect.
Check application file and replace with a valid file.

Returned by one of the OpenComm

methods. Check the following:
The application
SPiiPlus UMD is loaded (that is, the UMD icon
cannot establish
197 appears in the Task tray).
communication with
the SPiiPlus UMD. SPiiPlus UMD shows an error message.
In case of remote connection, access from a remote
application is enabled.

The controller does not reply for more than 20

seconds.
Returned by any method that exchanges data with
the controller. Check the following:
198 Not responding. 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.

The DLL and the Returned by one of the OpenComm methods.

199 UMD versions are Verify that the files ACSCL.DLL and ACSCSRV.EXE are of
not compatible. the same version.

Error in array and/or

601
index definition

Communication
602 channel is already
open

Argument Value has

603
incorrect type

Version 3.10 305

 SPiiPlus MATLAB Library Programmer's Guide
7.   Error Handling

Error
Error Message Remarks
Code

Argument Value is
604
not initialized

Variable name must

605
be specified

Wrong call type was

606
specified

607 Wrong return type

Version 3.10 306

5 HaTnufa St.
Yokne'am Illit 2066717
Israel
Tel: (+972) (4) 654 6440 Fax: (+972) (4) 654 6443

Contact us: [email protected] | www.acsmotioncontrol.com