Qmix SDK  20180626
The software libraries for integration of all CETONI devices.
Motion Control Library
Slider_MotionControl_API_color.jpg

Introduction

The motion control library offers functions and data structures to work with multi axis positioning systems. The API of the motion control library provides functions to work with

So depending on the requirements of your application, you can work with the single axis interface or with the multi axis interface. For some devices such as the rotAXYS axis system it is much easier to use the multi axis interface for positioning in XY space. Because the rotAXYS axis system has a rotation axis, some translations needs to take place to convert between polar and Cartesian coordinates. If you work with the single axis devices, you need to do these translations for yourself. If you work with the multi axis interface (LCA_MoveToPosXY()), then the axis system handles all the translation stuff internally.

See also
See Devices page for detailed informations about specific motion control devices.

Including

The way how you include the library functions in your own windows program, depends on the compiler and on the programming language you use. In order to access the motion control API, you have to include the library labbCAN_MotionControl_API.dll to your programming environment. You have to copy this file to the working directory of your system or to the application directory that contains your application EXE file. Use the calling convention LCA_CALL for this library. This convention is managing how the parameters are put on the stack and who is responsible to clean the stack after the function execution.

The interface of the library, constant definitions and declarations of the library functions, is defined in the header file interface/labbCAN_MotionControl_API.h


Initialization

Step 1 - Retrieve device handle

To work with axis systems or single axis devices, you need valid device handles. A device handle is simply an opaque pointer to the internal device object created by the labbCAN environment. So the first thing you need do to is obtaining a valid device handle.

You can get a valid axis system handle with the functions LCA_LookupAxisSystemByName() or LCA_GetAxisSystemHandle():

lca_hdl AxisSystemHandle;
Result = LCA_LookupAxisSystemByName("neMAXYS1", &AxisSystemHandle);
lca_hdl AxisSystemHandle2;
Result = LCA_GetAxisSystemHandle(1, &AxisSystemHandle2);

You can get a valid axis handle, if you obtain a certain axis from a given axis system device and a given axis index:

lca_hdl hAxisX;
Result = LCA_GetAxisHandle(hAxisSystem, 0, &hAxisX);

or if you query the global object pool for a registered named axis object:

lca_hdl hNemaxysY;
Result = LCA_LookupAxisByName("neMAXYS1_Y", &hNemaxysY);
lca_hdl hAxisX;
Result = LCA_GetAxisHandle(hAxisSystem, 0, &hAxisX);
Note
You can get the axis names and axis system names from the device configuration files (see Device Configuration Files) that have been shipped with your devices.

Step 2 - Enable devices

If you have valid device handles, you can start to bring your devices into a properly enabled and initialized state. To do this, you need to:

  1. clear all faults (e.g. LCA_ClearAxisFault())
  2. enable all drives (LCA_Enable())
  3. execute the homing procedure to find the device homing positions (LCA_FindHome())

If you work with the multi axis functions, you simply need to call LCA_FindHome(). This function will

  • clear the axis faults of all devices that belong to the given axis system
  • enable all axes of the axis system
  • execute the homing procedure of the given axis system.

After the homing procedure the device is properly initialized an you can start with your normal motion control tasks.

Examples

The following example code snippet shows a valid axis system initialization procedure:

1 //===========================================================================
2 // INCLUDES
3 //===========================================================================
4 #include "labbCAN_Bus_API.h"
6 
7 
8 //===========================================================================
9 // STATIC DATA
10 //===========================================================================
11 static dev_hdl hAxisSystem; // stores axis system handle
12 
13 
14 //===========================================================================
15 // Axis system initialisation
16 //===========================================================================
17 TErrCode InitAxisSystem(void)
18 {
19  TErrCode Result;
20 
21  //
22  // Get the axis system handle for the axis system that is registered with
23  // the name neMAXYS1
24  //
25  hAxisSystem = LCA_LookupAxisSystemByName("neMAXYS1");
26  if (hAxisSystem <= 0)
27  {
28  // handle error properly here
29  return -ERR_NOENT;
30  }
31 
32  //
33  // Now we enable the axis system. Enabling the axis system means, power
34  // will be applied to power stage of all motion control units of this
35  // axis system. If the axis system is in fault state, then this function
36  // clears the fault state first, and then enables the axis device.
37  //
38  Result = LCA_Enable(hAxisSystem);
39  if (Result != ERR_NOERR)
40  {
41  // handle error properly here
42  return Result;
43  }
44 
45  //
46  // We execute a homing move to bring all axes of the axis system into their
47  // home positions and to reset the internal device position counters to
48  // zero. We use the FindHome position ofthe axis system to ensure a proper
49  // order of axis initialisation.
50  //
51  Result = LCA_FindHome(hAxisSystem);
52  if (Result != ERR_NOERR)
53  {
54  // handle error properly here
55  return Result;
56  }
57 
58  //
59  // Give drives some time to start their homing moves
60  //
61  Sleep(100);
62 
63  //
64  // Now we wait, until the positioning system reaches its home position.
65  // The home position is reached, if all axes of this positioning system
66  // reached their home positions.
67  //
68  while (1)
69  {
70  Result = LCA_IsHomingPosAttained(hAxisSystem);
71  //
72  // If all axes reached their homing position stop the loop
73  // and continue
74  //
75  if (Result > 0)
76  {
77  break;
78  }
79 
80  if (Result != ERR_NOERR)
81  {
82  // handle error properly here
83  return Result;
84  }
85  Sleep(50); // do not take all processor time with this loop
86  } // while (1)
87 
88 
89  // now the axis system is properly initialized and we can start positioning
90  return Result;
91 }
LCA_Func long LCA_CALL LCA_LookupAxisSystemByName(const char *AxisSystemName, dev_hdl *AxisSystemHandle)
Lookup an axis system by its name.
#define ERR_NOENT
No such entity.
Definition: err_codes.h:104
LCA_Func long LCA_CALL LCA_FindHome(dev_hdl hAxisSystem)
Move all axis into its home position The axis system should manage the order of the movement and shou...
int32_t TErrCode
Error code type.
Definition: err_codes.h:50
long long dev_hdl
generic device handle
Definition: labbCAN_Bus_API.h:359
LCA_Func long LCA_CALL LCA_IsHomingPosAttained(dev_hdl hAxisSystem)
Check if homing position of the given axis system is attained.
labbCAN Motion Control Application Programming Interface
#define ERR_NOERR
No error.
Definition: err_codes.h:102
LCA_Func long LCA_CALL LCA_Enable(dev_hdl hAxisSystem)
Set all axis of an axis system into enabled (operational) state.
labbCAN Bus Application Programming Interface

Reference

See the Axis System Initialization module for a detailed reference of all motion control functions for initialization.


Programming Interface - API

See the labbCAN Motion Control API module for a detailed reference of the motion control library application programming interface