SPiiPlus Ut i l i t i e s

U ser’s Guide
Version 4.20
V e r s i o n 4 . 2 0 , October 30, 2006
COPYRIGHT
Copyright ® 1999 - 2006 ACS Motion Control Ltd.
Changes are periodically made to the information in this document. Changes are published as release
notes and are be incorporated into future revisions of this document.
No part of this document may be reproduced in any form without prior written permission from ACS
Motion Control.
TRADEMARKS
ACS Motion Control, PEG and SPii are trademarks of ACS Motion Control Ltd.
Visual Basic and Windows are trademarks of Microsoft Corporation.
Any other companies and product names mentioned herein may be the trademarks of their respective
owners.

Website: http://www.AcsMotionControl.com
Information: [email protected]
Tech Support: [email protected]

ACS Motion Control, Inc.

14700 28th Ave North - Suite 25
Plymouth, MN 55447
Tel: 800-545-2980
Tel. 763-559-7669
Fax. 763-559-0110

ACS Motion Control, Ltd.

Ramat Gabriel Industrial Park
POB 5668
Migdal HaEmek, 10500
ISRAEL
Tel: (972) (4) 6546440
Fax: (972) (4) 6546443
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.

October 30, 2006 ii User’s Guide

User’s Guide

Changes in Version 4.20

Page Change
Cover Updated logo and company name

Version 4.20, October 30, 2006 iii User’s Guide

SPiiPlus Utilities Version 4.20 Software Guide

Table of Contents
1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Organization of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Related SPiiPlus Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 The SPiiPlus Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.4 Conventions Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.5 Statement Text and Icons Used in this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 General Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1 Operation Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 C Library Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.3 Communication Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Controller Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.5 Programming Languages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.6 Supplied Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.7 Highlights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
2.8 Use of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2.9 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.10 Timing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.11 Hardware Interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.12 Dual-port RAM (DPRAM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.13 Non-waiting Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

October 30, 2006 iv Table of Contents

SPiiPlus Utilities Version 4.20 Software Guide

List of Figures
Figure 1 C Library Concept 5

October 30, 2006 v List of Figures

SPiiPlus Utilities Version 4.20 Software Guide

List of Tables
Table 1 Related SPiiPlus Tools 1
Table 2 Collateral Documentation 2
Table 3 Document Conventions 3
Table 4 Hardware Interrupt Generation 10

October 30, 2006 vi List of Tables

SPiiPlus Utilities Version 4.20 User’s Guide

1 Introduction
The SPiiPlus C Library supports the creation of a user application that operates in a PC host
computer and communicates with SPiiPlus motion controllers. The SPiiPlus C Library
implements a rich set of controller operations and conceals from the application the complexity
of low-level communication and synchronization with the controller.

1.1 Organization of this Guide

• “General Information” on Page 5
• “Operation Environment” on Page 5
• “Use of Functions” on Page 8

1.2 Related SPiiPlus Tools

Table 1 Related SPiiPlus Tools

Tool Description
SPiiPlus MMI A multipurpose user interface with the controller including:
Program management, Motion management, Communication
terminal, Four channel digital oscilloscope, Safety and I/O
signals monitor, Signal tuning and adjustment, and a fully
interactive simulator.
SPiiPlus MultiDebugger An interactive tool for SPiiPlus ACSPL+ multiprogramming
that includes: Progress window for monitoring the status and
simultaneous debugging of up to 10 programs, normal and
step-by-step execution, programmable breakpoints, and a
fully interactive simulator.
SPiiPlus SPiiDebugger A developing and debugging environment for real-time
motion control algorithms inside of SPii processor.
SPiiPlus Utilities The SPiiPlus Upgrader allows upgrading or downgrading of
the controller firmware.
The SPiiPlus Emergency Wizard allows firmware recovery in
case of damage or loss of communication to the controller.

1.3 The SPiiPlus Documentation

Table 2 Collateral Documentation (page 1 of 2)

Document Description
SPiiPlus PCI-4-8 Hardware Installation and hardware connection with the SPiiPlus PCI 4
Guide or 8 axes
SPiiPlus CM Hardware Guide Installation and hardware connection with the SPiiPlus
Control Module

Version 4.20, October 30, 2006 1 Introduction

SPiiPlus Utilities Version 4.20 User’s Guide

Table 2 Collateral Documentation (page 2 of 2)

Document Description
SPiiPlus Setup Guide Communication, configuration and adjustment procedures
for SPiiPlus motion control products.
SPiiPlus ACSPL+ Command set and high level language for programming
Programmer's Guide SPiiPlus controllers.
SPiiPlus MMI User’s Guide Software tools reference guide.
SPiiPlus MultiDebugger User’s Multiprogramming and debugging environment for ACSPL+
Guide programs.
HSSI Expansion Modules High-Speed Synchronous Serial Interface (HSSI) for
Guide expanded I/O, distributed axes, and nonstandard devices.
SPiiPlus Library Reference C++ and Visual Basic® libraries for host PC applications.
This guide is applicable for all the SPiiPlus motion control
products
SPiiPlus Utilities User’s Guide Firmware upgrade and recovery procedures.
SPiiPlus COM Library COM Methods, Properties, and Events for Communication
Reference Guide with the Controller
SPiiPlus FRF Analyzer User’s The SPiiPlus FRF (Frequency Response Function)
Guide Analyzer™ is a powerful servo analysis GUI for ACS-Tech80
SPiiPlus motion controllers.
SPiiPlus SA and SA-LT Installation and hardware connection with the SPiiPlus SA
Hardware Guide and SPiiPLus SA-LT Controllers
SPiiPlus 3U Hardware Guide Installation and hardware connection with the SPiiPlus 3U
Controller

1.4 Conventions Used in this Guide

Several text formats and fonts, illustrated in Table 3, are used in the text to convey information
about the text.

Table 3 Document Conventions (page 1 of 2)

Document Description
Bold ACSPL+ command names. Software tool menus, menu
items, dialog box names, and dialog box elements.
Italic Emphasis or an introduction to a key concept. In a command
syntax, specifies a variable name or other information that the
user provides.
Monospace Code examples.
Italic monospace Information in code examples that the user provides.
ALL CAPS Names of keys on the keyboard. For example, SHIFT.
blue italic Names of other documents.

Version 4.20, October 30, 2006 2 Introduction

SPiiPlus Utilities Version 4.20 User’s Guide

Table 3 Document Conventions (page 2 of 2)

Document Description
blue underlined Cross references, web pages, and e-mail addresses.
| Symbol used in nested menu items and dialog box options
leading to a final action. For example, the sequence
Debug | New Watch | Real-time |
directs the user to open the Debug menu, choose the New
Watch command, and select the Real-time option.

1.5 Statement Text and Icons Used in this Guide

Note
Highlights an essential operating or maintenance procedure,
condition, or statement

Model
Model Dependent Text Here!

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

A warning describes a condition that may result in serious

bodily injury, or death!

Version 4.20, October 30, 2006 3 Introduction

SPiiPlus Utilities Version 4.20 User’s Guide

2 General Information

2.1 Operation Environment

The SPiiPlus C Library supports Windows® 9/x, NT, 2000, XP and Windows ME.

2.2 C Library Concept

The C Library is a software package that allows Host-based applications to communicate with
the SPiiPlus controller in order to program, send commands, and query controller status.
The C Library includes user-mode and kernel-mode drivers that perform various
communication tasks.
The host application is provided with a robust C Function API to make calls the C Library
which in turn communicates with the SPiiPlus Controller through the controller drivers. The
controller then returns the reply to the to the caller application.
The host application may contact C Library from remote location by setting its IP address or
the machine name. Set the IP address with the acsc_SetServer function.
Up to four host applications may communicate with the controller simultaneously via a single
physical connection.

Host Computer Remote Computer

Host
Application 1

Host
Application 2

Remote
C Library Application

SPiiPlus SPiiPlus SPiiPlus SPiiPlus

spiiplushost

Figure 1 C Library Concept

2.3 Communication Channels

The SPiiPlus C Library supports all communication channels provided by SPiiPlus motion
controllers:
• Serial (RS-232)

October 30, 2006 5 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

• Ethernet (point-to-point and Network)

• PCI Bus

2.4 Controller Simulation

The SPiiPlus C Library includes the controller simulator operating on the same PC as the user
application. The simulator provides execution of the user application without the physical
controller for debugging and demonstration purposes.

2.5 Programming Languages

The library directly supports development of C/C++ applications. Visual Basic® or other
languages can also be used with little additional effort. For languages other then C/C++, the
SpiiPlus COM library is recommended.

2.6 Supplied Components

The library includes a DLL, a device driver, an import library, and a header file for C/C++
compilers.

2.7 Highlights
• Unified support of all communication channels (Serial, Ethernet, PCI Bus)
All functions except acsc_OpenComm*** functions are identical for all communication
channels. The user application remains substantially the same and works through any of the
available communication channels.
• Controller simulator as an additional communication channels
All library functions can work with the Simulator exactly as with the actual controller. The
user application activates the simulator by opening a special communication channel. The
user is not required to change his application in order to communicate with the Simulator.
• Support of multi-threaded user application
The user application can consist of several threads. Each thread can call SPiiPlus C Library
functions simultaneously. The library also provides special functions for the
synchronization SPiiPlus C functions called from concurrent threads.
• Automatic synchronization and mutual exclusion of concurrent threads
Both waiting and non-waiting calls of SPiiPlus C functions can be used from different
threads without any blocking or affect one to another. The library provides automatic
synchronization and mutual exclusion of concurrent threads so the threads are not delayed
one by another. Each thread operates with its maximum available rate.
• Concurrent support of up to 10 communication channels in one application
One application can open up to 10 communication channels simultaneously. Different
communication channels are usually connected to different controllers. However, two or

October 30, 2006 6 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

more communication channels can be connected to one controller. For example, one
application can communicate with one controller through both Ethernet and serial links.
• Acknowledgement for each controller command
The library automatically checks the status of each command sent by the user application to
the controller. The user application can check the status to confirm that the command was
received successfully. This applies for both waiting and non-waiting calls.
• Communication history
The library supports the storage of all messages sent to and received from the controller in
a memory buffer. The application can retrieve the full or partial contents of the buffer and
can clear the history buffer.
• Separate processing of unsolicited messages
Most messages sent from the controller to the host are responses to the host commands.
However, the controller can send unsolicited messages, for example, because of executing
the disp command. The library separates the unsolicited messages from the overall message
flow and provides special function for handling unsolicited messages.
• Rich set of functions for setting and reading parameters, motion, program
management, I/O ports, safety controls, and other.
• Two calling modes
Most library functions can be called in either waiting or non-waiting mode. In waiting
mode, the calling thread does not continue until the controller acknowledges the command
execution. In non-waiting mode, a function returns immediately and the actual work of
sending the command and receiving acknowledgement is performed by the internal thread
of the library.
• Debug Tools
The library provides different tools that facilitate debugging of the user application. The
simulator and the communication history mentioned above are the primary debugging
tools. The user can also open a log file that stores all communications between the
application and the controller.
• Setting user callback functions for predefined events
The possibility exists to set a callback function that will be called when a specified event
occurs in the controller. This lets you define a constant reaction by the user host application
to events inside the controller without polling the controller status. See “Callbacks” on
Page 9,
• Wait-for-Condition Functions
To facilitate user programming, the library includes functions that delay the calling thread
until a specific condition is satisfied. Some of the functions periodically pole the relevant
controller status until the condition is true, or the time out expired. Some of these functions
are based on the callback mechanism, see “Callbacks” on Page 9. The functions with this
option are:
• acsc_WaitMotionEnd
• acsc_WaitLogicalMotionEnd

October 30, 2006 7 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

• acsc_WaitProgramEnd
• acsc_WaitInput
These functions will use the callback mechanism if the callback to the relevant event is set,
otherwise polling is used.
• Support for Windows 9/x/NT/2000/ME
The user application that communicates through the library takes no notice of the
operational environment. The library itself chooses the proper device driver and conceals
all differences between the operating systems from the user application.

2.8 Use of Functions

Each library function performs a specific controller operation. To perform its task, the function
sends one or more commands to the controller and validates the controller responses.
Because the SPiiPlus C functions follow the C syntax and have self-explaining names, the
application developer is not required to be an expert in ACSPL+ language. However, the most
time-critical part of an application often needs to be executed in the controller and not in the
host. This part still requires ACSPL+ programming.
To use the SPiiPlus C Library functions from C/C++ environment, it is necessary to include the
header file ACSC.h and the import library file ACSC.lib to the project.
For example, the following function implements a motion to the specified point:

int acsc_ToPoint(HANDLE Handle, int Flags, int Axis, double

Point, ACSC_WAITBLOCK* Wait)

Where:
• Handle is a communication handle returned by one of the acsc_OpenComm*** functions.
• Flags are a bit-mapped parameter that can include one or more motion flags.
For example:
ACSC_AMF_WAIT Plan the motion, but don’t start until the acsc_Go function is
called
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.

• Axis is an axis of the motion where ACSC_AXIS_X corresponds to X, ACSC_AXIS_Y –

to Y, and so on.
• Point is a coordinate of the target point.
• Wait is used for non-waiting calls. Non-waiting calls are discussed in the next section.

October 30, 2006 8 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

2.9 Callbacks
There is an option to define an automatic response in the user application to several events
inside the controller. The user specifies a function that will be called when certain event occurs.
This approach helps user application to avoid polling of the controller status and only to execute
the defined reaction when it is needed.
The library may set several callbacks in the same time. Every one of them runs in its own thread
and doesn’t delay the others.
Callbacks are supported in all communication channels. The library hides the difference from
the application, so that the application handles the callbacks in all channels in the same way.
The events that may have a callback functions are:
• Hardware detected events
• PEG
• MARK1 and MARK2
• Emergency Stop
• Software detected events
• Physical motion end
• Logical motion end
• Motion failure
• Motor failure
• ACSPL+ program end
• ACSPL+ line execution
• ACSPL + “interrupt” command execution
• Digital input goes high
• Motion start
• Motion profile phase change
• Trigger function detects true trigger condition
• Controller sent complete message on a communication channel

2.10 Timing
When working with PCI bus, the callbacks are initiated through physical interrupts generated
by the controller. In the Simulator, the interrupt mechanism is emulated with OS mechanisms.
In all other kinds of communication, the controller sends an alert message over the
communication channel in order to inform the host about the event.
Although the implementation is transparent, the timing is different varies for each
communication channel as follows:
• In PCI communication, the callbacks are based upon PCI interrupts and response is very fast
(sub-millisecond level).
• In all other channels, callback operation includes sending/receiving a message that requires
much more time. Specific figures depend on the communication channel rate.

October 30, 2006 9 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

From the viewpoint of the Callback Mechanism, all communication channels are functionally
equivalent, but differ in timing.

2.11 Hardware Interrupts

Hardware events (Emergency Stop, PEG and MARK) are detected by the controllers HW and
an interrupt on PCI bus is generated automatically, while on other communication channels
those events are recognized by the Firmware and only then an alert message may be sent. That
is why there is a difference in the definition of the Event condition for different communication
channels.

Table 4 Hardware Interrupt Generation

Callback Condition of PCI Condition of Alert Message (all
Interrupt channels except PCI)
Emergency stop The interrupt is The message is sent when bit S_FAULT.#ES
generated on positive or changes from zero to one.
negative edge of the The message is disabled if S_FMASK.#ES is
input ES signal. zero.
The edge is selected by
S_SAFINI.#ES bit.
Mark 1 and Mark 2 The interrupt is The message is sent when corresponding
generated on positive IST.#MARK or IST.#MARK2 bit changes
edge of the from zero to one.
corresponding Mark
signal.
PEG The interrupt is The message is sent when corresponding
generated on negative AST.#PEG bit changes from one to zero.
edge of PEG pulse.

2.12 Dual-port RAM (DPRAM)

The DPRAM is a memory block that is accessible from the host and from the controller. This
feature provides fast data exchange between the host and the controller.
The SPiiPlus controller provides 1024 bytes of dual-port ram memory (DPRAM). Relative
address range of DPRAM is from byte 0 to byte 0x3FF.
First 128 bytes (relative addresses from 0 to 0x080) are reserved for system use. The rest of the
memory is free for the user needs.
The DPRAM functions are available with any communication channel, however it is important
to remember that only PCI bus communication provide real physical access to controllers
DPRAM and works very fast (sub-millisecond level).
In all other channels, the DPRAM operation is simulated. Each operation includes
communication with the controller. Specific figures depend on the communication channel rate.

October 30, 2006 10 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

• Using of DPRAM communication in non-PCI communication channel is recommended if

an application is primarily intended for PCI channel, but requires full compatibility with
other communication channels.

2.13 Non-waiting Calls

There are three possible approaches regarding when a library function returns control to the
calling thread:
• Waiting call
The function waits for the controller response and then returns. For many commands, the
controller response does not signal the completion of the operation. The controller response
only acknowledges that the controller accepted the command and started the process of its
execution. For example, the controller responds to a motion command when it has planned
the motion, but has not executed yet.
• Non-waiting call
The library function initiates transmission of the command to the controller and returns
immediately without waiting for the controller response. An internal library thread sends the
command to the controller and retrieves the result. To get the result of operation the
application calls the acsc_WaitForAsyncCall function.
• Non-waiting call with neglect of operation results
The same as the previous call, only the library does not retrieve the controller response. This
mode can be useful when the application ignores the controller responses.
Most library functions can be called in either waiting or non-waiting mode. The pointer Wait
to the ACSC_WAITBLOCK structure provides the selection between waiting and non-waiting
modes as follows:
• Zero Wait (NULL character) defines a waiting call. The function does not return until the
controller response is received.

Note
Do not use ‘0’ as the Null character.

• If Wait is a valid pointer, the call is non-waiting and the function returns immediately.
• If Wait is ACSC_IGNORE, the call is non-waiting and will neglect of the operation result.
ACSC_WAITBLOCK is defined as follows:
Structure: ACSC_WAITBLOCK { HANDLE Event; int Ret; };
When a thread activates a non-waiting call, the library passes the request to an internal thread
that sends the command to the controller and then monitors the controller responses. When the
controller responds to the command, the internal thread stores the response in the internal

October 30, 2006 11 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

buffers. The calling thread can retrieve the controller response with help of the
acsc_WaitForAsyncCall function and validate the completion result in the Ret member of the
structure.
Up to 256 non-waiting calls can be activated before any acsc_WaitForAsyncCall is called. It
is important to understand that acsc_WaitForAsyncCall must be called for every non-waiting
call. Otherwise, the response will be stored forever in the library’s internal buffers. A call,
which is called when more then 256 calls are already activated is delayed for a certain time and
waits until acsc_WaitForAsyncCall is called by one of the previous calls. If the time expires,
an ACSC_COMMANDSQUEUEFULL error is returned.
By default, this time-out is zero. This means that the call number 257 immediately returns with
the ACSC_COMMANDSQUEUEFULL error.

If you work with multiple non-waiting calls and the

Note ACSC_COMMANDSQUEUEFULL error pops up all the time, the
structure of your application is too demanding. This means that you are
trying to activate more than 256 calls without retrieving the results.
If the error message pops up occasionally, try increasing the timeout.

Time-out is controlled by acsc_GetQueueOverflowTimeout and

acsc_SetQueueOverflowTimeout functions.
The following example shows how to perform waiting and non-waiting calls. In this example
the acsc_WaitForAsyncCall function was used. Any function that has Wait as a parameter can
be used to perform waiting and non-waiting calls.

Char* cmd = “?$\r”; // get motors state

char buf[101];
int Received;
ACSC_WAITBLOCK wait;
// example of the waiting call of acsc_Transaction
if (!acsc_Transaction( Handle, // communication handle
cmd, // pointer to the buffer that
// contains command to be executed
strlen(cmd), // size of this buffer

October 30, 2006 12 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

buf, // input buffer that receives

// controller response
100, // size of this buffer
&Received, // number of characters that were
//actually received

October 30, 2006 13 General Information

SPiiPlus Utilities Version 4.20 User’s Guide

NULL // waiting call

{
printf(“transaction error: %d\n”, acsc_GetLastError());
}
// example of non-wainig call of acsc_Transaction if
(acsc_Transaction(Handle,cmd,strlen(cmd),buf,100,&Received,&wait))

{
// something doing here
….
// retrieve controller response
if (acsc_WaitForAsyncCall(Handle, buf, &Received, &wait, 5000))
{
buf[Received] = ‘\0’;
printf(“Motors state: %s\n”, buf);
}
else
{
acsc_GetErrorString(Handle, wait.Ret, buf, 100, &Received);
buf[Received] = ‘\0’;
printf(“error: %s\n”, buf);
}
}
else
{
printf(“transaction error: %d\n”, acsc_GetLastError());
}
// example of non-waiting call of acsc_Transaction with neglect of the
// operation result. Function does not wait for the controller response.
// The call of acsc_WaitForAsyncCall has no sense because it does not
// return the controller response for this calling mode.

If (acsc_Transaction( Handle,cmd,strlen(cmd),buf,
100, &Received, ACSC_IGNORE))
{
printf(“transaction error: %d\n”, acsc_GetLastError());
}

October 30, 2006 14 General Information