Considerations¶
The motion API provides an abstraction from the physical interface of the motion controller. As an example, the user application using the motion API does not have to be aware whether the motion controller has a physical EtherCAT or Ethernet interface. In designing an API decisions need to be made that affect the way a user application interacts with it.
This section describe the general decisions. Language specific considerations are elaborated in C++ and C#.
Software component compatibility¶
PMP uses semantic versioning (major.minor.patch) to indicate software compatibility:
A major version increase marks incompatibility.
A minor version increase marks added functionality in a backward compatible manner.
A patch version increase marks fully backward compatible changes.
The PMP version is the main indicator for compatibility between software releases.
PMP consists of several software components. Components from the same release are always compatible. When mixing components from different PMP releases the compatibility should be verified. This section describes how the compatibility between these components can be assessed.
Software component compatibility shows the individual components and their interfaces, where blocks are files or devices and dashed lines are interfaces.
Software component compatibility¶
For simulation additional software components are used. Simulator software component compatibility shows the additional components and interface that ensure the simulator executable is compatible with the controller descriptions and with the sub-controller simulation libraries.
Simulator software component compatibility¶
The compatibility between components from different releases can be checked using the interface version numbers. The interface version numbers are stated in the release notes document of a software release and the rules for compatibility are stated in Interface version numbers.
Interface |
Description |
|---|---|
ABI |
The compatibility between the PMP C++ ABI wrapper (in a compiled application) and a PMP client library. Compatible when PMP client library ABI minor \(\ge\) PMP C++ ABI wrapper minor and major versions are equal. |
RPC |
The compatibility between the PMP client library and a (simulated) PMP top-controller. Compatible when (simulated) PMP top-controller RPC minor \(\ge\) PMP client library RPC minor and major versions are equal. |
Simulink |
The compatibility between a (Simulink) processing block template and a (simulated) PMP controller. Compatible when (simulated) PMP controller Simulink minor \(\ge\) Processing block template Simulink minor and major versions are equal. |
Controller XSD |
The compatibility between a PMP top-controller and a sub-controller and between a controller description file and simulator. (Simulated) sub-controllers are compatible with a (simulated) PMP top-controller when:
A controller description file is compatible with a simulator when simulator XSD minor \(\ge\) controller description file minor and major versions are equal. |
Dynamic library |
The compatibility between a simulated PMP top-controller and simulated sub-controller. Compatible when simulated PMP top-controller minor \(\ge\) Simulated sub-controller minor and major versions are equal. |
Behavior |
A change in the behavior of a PMP controller without changes to the API that may require user-application changes. |
Multi-client access¶
PMP supports multi-client access:
A single user application can connect to multiple controllers
Multiple user applications can connect to the same controller
Multiple simulated controllers can run on the same client
Multiple versions of the API can be used on the same system (but not in the same user application)
Installation of multiple versions is supported when using the Windows OS, see Multiple versions (Windows OS only)
The motion API allows simultaneous access from multiple clients/threads. Please note that this can result in outdated information or depleted resources when multiple clients are connected that interact with the controller. For example:
One client can destroy an object which is still referenced by another client. After destruction the reference is not valid anymore and will throw a CObjectDestroyedException (C++) or ObjectDisposedException (C#) when accesssed.
Other clients can claim finite resources (e.g. acquisition instances). When all acquisition instances are already claimed by other clients a COutOfResourcesException (C++) or OutOfResourcesException (C#) will be thrown when trying to claim one.
State machine transition priorities¶
In a situation with potential conflicting state transitions, priorities are defined to determine which transition is executed. Alphabetic characters are used to indicate a transitions’ priority and alphabetic ordering distinguishes the priority levels. Where “A” defines the highest priority, followed by “B”, etcetera. The priorities are visualized at the start of a transition arrow with capital letters. See State machine transition priority definitions for an example.
State machine transition priority definitions¶
Units¶
This document stipulates that the user configures scale factors (which are used to translate between product units and user units) such that the user units are SI units where applicable. Time signals are always expressed in seconds and are not scalable.