Wittenstein attocube AMC100 User manual

Interface Manual
AMC100 & AMC300

Modified:
02/2021
Products:
AMC100 | AMC300 | attoDISCOVERY Software | AMC Webserver Application | MOVE
© 2021 attocube systems AG. Product and company names listed are trademarks or trade names of their respective
companies. Any rights not expressly granted herein are reserved. ATTENTION: Specifications and technical data are
subject to change without notice.

Table of Contents | Page 1
Table of Contents
1System Integration.................................................................................................................2
1.1 Connecting to Third Party Hardware.............................................................................2
1.1.1 Cabling Restrictions............................................................................................2
1.1.2 Pin Assignments .................................................................................................2
2Software communication & interfaces ..................................................................................3
2.1 Introduction...................................................................................................................3
2.1.1 Web Interface.....................................................................................................3
2.1.2 JSON-RPC............................................................................................................3
2.1.3 C/C# DLLs............................................................................................................3
2.1.4 LabVIEW VIs .......................................................................................................4
2.1.5 Matlab Library ....................................................................................................4
2.2 Overview and implementation of the APIs ...................................................................5
2.2.1 JSON-RPC (JRPC2.0)............................................................................................5
2.2.2 C Library .............................................................................................................6
2.2.3 C# Library ...........................................................................................................8
2.2.4 LabVIEW .............................................................................................................9
2.2.5 Matlab ..............................................................................................................11
2.2.6 Python ..............................................................................................................11
2.3 Error handling..............................................................................................................13
2.3.1 C# error handling.............................................................................................. 13
2.3.2 Python error handling ......................................................................................13
2.3.3 LabVIEW error handling ...................................................................................14
3Functions..............................................................................................................................15
3.1 Access 15
3.2 Amcids .........................................................................................................................19
3.3 Control.........................................................................................................................27
3.4 Description ..................................................................................................................70
3.5 Diagnostic ....................................................................................................................74
3.6 Move 78
3.7 Res 99
3.8 Rotcomp ....................................................................................................................107
3.9 Rtin 113
3.10 Rtout 131
3.11 Status 147
3.12 About 156
3.13 System_service..........................................................................................................158
3.14 Network.....................................................................................................................168
3.15 System_service..........................................................................................................194
3.16 Update.......................................................................................................................196

Page 2 | Table of Contents
1System Integration
The AMC100 and the AMC300 can be integrated with external systems or devices by
-combining it with third party hardware
-establishing incoming and outgoing trigger connections (/IO upgrade required)
-controlling it with individual software interfaces
1.1 Connecting to Third Party Hardware
CAUTION
General hazard!
Inadequate hardware connections may cause injury and are likely to damage the device or
interfere with an appropriate functioning.
oAlways contact attocube for technical support, before combining the device with
third party hardware.
oDo carefully observe the information in this section when combining the device
with third party hardware.
NOTE
attocube is not liable for any damages resulting from an unauthorized combination of the
device with third party hardware. Unauthorized combination with third party hardware is
not covered by attocube's warranty.
1.1.1 Cabling Restrictions
For optimal performance, obey the following combination restrictions:
-Do not to connect cabling with a wire resistance > 5 Ω.
-Use EMV housings as enclosure for the D-sub connectors.
-Use extra shielded twisted pair wires for the piezo voltage supply.
-Do not connect any cable > 5 m.
1.1.2 Pin Assignments
The pins of the device’s positioner control cables can be found in the AMC100 or AMC300 User
Manual.

Software communication & interfaces | Page 3
2Software communication & interfaces
You can integrate your attocube Device into complex automated processes via individual
software interfaces. Attocube provides APIs for the programming languages C, C#, LabVIEW,
Python & Matlab as well as short programming examples to get you started.
The following sections provide information on methods, commands and parameters to be used
for calling up device functions with the respective language.
2.1 Introduction
The Device provides a set of software communication interfaces offering a broad set of
functions and options. These can be used to configure the Device as well as to read out data. In
particular, these are:
•Web interface (please also refer to the User Manual)
•JSON-RPC
•C DLL
•C# DLL
•LabVIEW VIs
•Matlab library
•Python Library
Most of the different functions are accessible within every interface. This is why we sort by
functions not by interfaces. For every function, we show how the implementation in the
particular interface is done. Anyway first we give a short explanation of the different interfaces:
NOTE
Part of the conventions mentioned below are specific for the handling of attocube devices
and are not necessarily applicable in other contexts.
2.1.1 Web Interface
The Device runs a built-in webserver. This means that a web interface can be accessed via a
common web browser. A how to set up the IP and a first connection is given in the User
Manual. The web interface is the most straightforward way to communicate with the Device
and almost the full functionality is implemented.
2.1.2 JSON-RPC
The device allows platform-independent communication using JSON-RPC via TCP/IP and
websocket. The JSON commands are the lower level that all other wrappers (e.g. Python or C)
use.
2.1.3 C/C# DLLs
Based on the JSON interface, C/C# libraries are available to implement the functions within
C/C#-based coding environments.

Page 4 | Table of Contents
2.1.4 LabVIEW VIs
We offer ready-made VIs to have a fast and easy implementation in National Instrument’s
LabVIEW environment.
2.1.5 Matlab Library
Based on the JSON interface, we offer ready-made Matlab functios to have a fast and easy
implementation in Mathwork’s Matlab environment.

Software communication & interfaces | Page 5
2.2 Overview and implementation of the APIs
2.2.1 JSON-RPC (JRPC2.0)
Your attocube Device allows platform-independent communication using JSON-RPC via TCP/IP.
When using JSON-RPC, the following conventions apply.
Transport protocols
TCP
Uses communication port 9090.
Calling a JSON RPC
2.0 method
A JSON RPC method is called by sending a message to the device.
{ "jsonrpc": "2.0", "method": "<method>", "params": [<param [0]>,
<param [1]>, …], "id": <call id>, “api”: <api version>}
<method>: String defined in chapter 2.2.
<param x>: Parameter for the method call if the PARAM is put
between two “, it is a string. Without “ it is a number
<call id>: A unique id to find the corresponding
answer
<api version>: A version identifier for backward compatibility,
please set to 2
Example
Example:
{ "jsonrpc": "2.0", "method":
"com.attocube.ids.displacement.getAxisDisplacement", "params":
[1], "id": 1, “api”: 2}
Receiving a JSON
RPC 2.0 response
The JSON RPC method answer is then sent back as payload to the
OK message:
{ "jsonrpc": "2.0", "result": [<return values [0]>, <return values
[1]>, …], "id": <call id>}
<return values [x]>: The return parameters
<call id>: The unique id of the method call
Example
Example:
{ "jsonrpc": "2.0", "results": [0, 4], "id": 1}
Example
Example:
Communication via PuTTY

Page 6 | Table of Contents
2.2.2 C Library
The C API is provided to integrate the Device with all its functionality within your C programs.
Open a Telnet connection with PuTTY.
Sending Json-Rpc commands in the command line interface.
Overview
The C API contains of following files:
Standard C API:
attocubeJSON.dll (x64 and x86 versions for a windows
environment)
attocubeJSON.lib (x64 and x86 versions for a windows
environment)
attocubeJSON.so (x64 and x86 versions for a linux
environment)
attocubeJSONCall.h (header file for the general functions)
generatedAPI.h (header file for the device specific
functions)
Disovery C API:
attocube-discovery-dll.dll
attocube discovery-dll.lib
attocube-discovery.h (header file)

Software communication & interfaces | Page 7
Using the .dll’s with
different systems
Note that if you want to use the .dlls within x64 based systems
outside the framework of Visual C, you might need to convert the
library into a static .a format.
Establishing a
connection
To connect to a device, please use (part of attocubeJSONCall.h):
int ATTOCUBE_API Connect(const char *deviceAddress, int*
deviceHandle)
The device handle is the reference to the connection and the device
and is input to all other device functions that are following.
To close the connection, please use:
int ATTOCUBE_API Disconnect(int * deviceHandle)
Both functions are included in the API.
For a TCP/IP connection, the port 9090 is used.
Discovering devices
within the same
network
The discovery function can be used:
It searches your network for available attocube devices and
returns a list of properties. This is done by a SSDP broadcast. If no
devices are found, please check the device connection via TCP/IP
(e.g. via the websever). The device must be in the same subnet
than the requesting PC.
IMPORTANT NOTE: These functions are part of an additional
discovery .dll –the “attocube discovery dll”, which is also part of
the standard delivery content.
Therefore, following functions are available:
int DLL_EXP AD_GetDeviceInfos(int index, DeviceInfo* info)
(Get informations about a discovered device)
void DLL_EXP AD_ReleaseInfo();
(Release memory allocated by AD_Check)
int DLL_EXP AD_Check(deviceType)
(Checks discoverable devices on the network and retrieves
informations)
Special data types:
typedef struct {
char ipAddress[32];