Important Things to Know for MPI 4.0

Introduction

MEI to MPI Prefix

To simplify the programming interface, all methods, macros, structures, and enumerations now use the mpi and MPI prefix. All header files are now located in a single include directory and the stdmei.h header file was eliminated.

Previously, the MPI had two sets of methods (mpi/mei) and structures (MPI/MEI). This split was intended to isolate standard methods/structures from platform specific methods/structures. However, to avoid confusion all MPI and MEI structures were simplified and converted to single MPI structures.

The following table provides the converted MPI structures for the 04.00 release (and later).

The following table provides the converted MPI methods for the 04.00.(release and later).

For more information about MPI naming conventions, see Naming Conventions.

Support for ZMP and eZMP Only

The XMP-Series controllers are no longer supported with version 4.0 (and later). This is due to the inability of the XMP processor to support 64-bit math instructions, limited memory, and FPGA size.

Note: The ZMP and eZMP-Series are supported with version 4.0 (and later).

64-Bit Trajectory Calculations

Double precision variables are limited to 52-bits for the mantissa. If the trajectory parameter values are beyond +/- 52-bits, the MPI and controller double position data will have precision loss in the least significant bits.

64 Nodes/64 Axes

The SynqNet network now supports up to 64 nodes. Additionally, the MPI and controller firmware was expanded to support up to 64 axes (MS, Axis, Filter, and Motor objects).

The memory allocation of the controller was changed from static to dynamic which allows it to scale to fit the motion system. While dynamic memory allocation provides exact fit flexibility, it also requires initial planning for applications that need to support multiple network topologies or need to scale the object counts of the controller during operation. The control object count configuration now has two parts, dynamicMemAlloc and enabled. The dynamicMemAlloc count determines the memory allocated to the number of objects and enabled determines how many objects are processed by the controller.

During SynqNet network initialization, the memory of the controller is dynamically allocated and initialized with dynamicMemAlloc and enabled object counts (MS, Axis, Filter, Motor, etc.) matching the discovered network topology. For example, if 2x nodes are discovered with 2x motors each, then the controller is automatically configured to allocate and enable 4 MS, Axis, Filter, and Motor objects.

If your application uses the discovered object count, then no control object count configuration is necessary. If it is desired to decrease the number of controller objects, reduce the enabled count to reduce the processing load of the controller. To increase the number of controller objects, re-configure the dynamicMemAlloc and enabled object counts of the controller.

WARNING!! Configuring the control dynamicMemAlloc object counts will clear the dynamic memory of the controller and any configurations previously written to the dynamic memory of the controller will be lost.

Note: It is highly recommended to configure the control dynamicMemAlloc object counts first before configuring other objects.

The XMP series and eXMP series controllers are no longer supported with version 4.0
(and later). This is due to the limited memory of the XMP and SynqNet buffers.

Note: The ZMP and eZMP series controllers are supported with version 4.0 (and later).

For more information, see Addressing, MPIControlConfigDynamicMemAlloc, and MPIControlConfigEnabled.

Object creation and validation was simplified. Previously applications needed to create objects and validate them. Now, the creation and validation are handled automatically. For example, to create a motor object:

          MPIMotor motor;
          long motorNumber = 0;


          returnValue =
             mpiMotorCreate(&motor, control, motorNumber);	
          msgCHECK(returnValue);

Controller initialization and control object creation was also simplified. Now control creation, validation, and initialization are handled automatically. For example, to create a control object and initialize the controller:

          MPIControl control;
  
          returnValue =
             mpiControlCreate(&control, MPIControlTypeDEFAULT, NULL);	
          msgCHECK(returnValue);

To initialize the controller without initializing the SynqNet network:

          returnValue =
             mpiControlAccess(&control, MPIControlTypeDEFAULT, NULL);	
          msgCHECK(returnValue);

For more information, see mpiControlCreate(...) and mpiControlAccess(...).

Motion Interface

Commanding Moves

The mpiMotionStart(…) and mpiMotionModify(…) methods and MPIMotionParams{…} structures were replaced with several motion methods to command simple single axis, multi-axis cartesian, multi-axis coordinated, or to define specific behaviors.

double position = 10000.0;
double velocity = 5000.0;
double accel = 50000.0;

          mpiMotionSimpleTrapezoidal(motion,
                                     position,
                                     velocity,
                                     accel,
                                     accel); /* deceleration */

See Also

mpiMotionTrapezoidalMove | mpiMotionTrapezoidalCartesianMove | mpiMotionTrapezoidalCoordinatedMove | mpiMotionSCurveJerkPercentMove | mpiMotionSCurveJerkPercentCartesianMove | mpiMotionSCurveJerkPercentCoordinatedMove | mpiMotionVelocityJerkPercentMove | mpiMotionMultiAxisVelocityJerkPercentMove | mpiMotionPTMove | mpiMotionPVTMove

Motion:Axis Maps and Default Value Changes

Motion:Axis maps are now only located in the controller and 1:1 by default. Additionally, the host motion objects no longer contain associations with host axis objects and the mpiMotionAxisList methods to manage axis object lists were eliminated. The MS (motion supervisor) to axis maps are now stored in the memory of the controller only. The MS and axis objects are mapped by their number (0, 1, 2, etc.) and not by their object handle. This change simplifies MS to axis map management and reduces conflicts between multiple host applications, specifically when running local and client/server applications.

By default, the MS and axis objects are now mapped one-to-one in the memory of the controller (MS0:Axis0, MS1:Axis1, etc.). To modify an MS to axis map, use mpiMotionAxisMapGet(…) to read the axis count and array of axis numbers from the controller, change the count and/or axis numbers array, and use mpiMotionAxisMapSet(…) to write the new map into the controller.

Note: It may be required to un-map the MS:Axis mappings, if the default 1:1 mapping is not appropriate for your application.

For example to map axes 4 and 5 to a MS:

          /* Map axis to the Motion Supervisor */
          returnValue = 
             mpiMotionAxisMapGet(motion,
                                 &motionAxisMap);
          msgCHECK(returnValue);

          motionAxisMap.count = 2;
          motionAxisMap.number[0] = 4;
          motionAxisMap.number[1] = 5;
  
          returnValue =
             mpiMotionAxisMapSet(motion,
                                 &motionAxisMap);
          msgCHECK(returnValue);

For more information, see mpiMotionAxisMapGet(...) and mpiMotionAxisMapSet(...).

The path motion interface for linear and arc segments were incorporated into the motion object.

Note: This functionality is the same as in previous versions.

Event Interface

The programming interface for event handling was simplified and the features were expanded. This section provides a list of changes and new features for the event interface.

Changes

New Features

          /* Create event notification object for events from all sources */
          mpiEventMaskCLEAR(eventMask);
          mpiEventMaskALL(eventMask);


          /* Create event notification object for motion */
          returnValue =
               mpiControlNotifyCreate(control,
                                      &notify,
                                      eventMask,
                                      motion);
          msgCHECK(returnValue);

          /* Configure the Motion Event Mask */
          returnValue =
               mpiMotionEventNotifySet(motion,
                                       eventMask,
                                       NULL);
          msgCHECK(returnValue);

          /* Create the event service */
          returnValue =
               mpiControlEventServiceStart(control,
                            MPIThreadPriorityHIGHEST,
                            MPIWaitFOREVER, /* FOREVER => enable interrupts */
                            NULL);
          msgCHECK(returnValue);

   
          /* Wait for motion done event from MS 0 */
          returnValue =
               mpiNotifyEventWaitSpecific(notify,
                                          &eventData,
                                          MPIModuleIdMOTION,
                                          0,     /* MS number */
                                          MPIEventTypeMOTION_DONE,
                                          MPIWaitFOREVER);
          msgCHECK(returnValue);

For more information, see Event Objects.

Capture

The capture was expanded to support two modes, single shot and auto-arm. The single shot mode provides similar functionality as previous releases. The auto-arm mode provides the ability to trigger and buffer multiple captures per controller sample period. The auto-arm mode replaces the probe object, which was removed.

The capture now supports up to 32 input trigger sources. The motor dedicated inputs and general inputs are currently supported and SynqNet node inputs were added for time-based capture. The FPGA and SynqNet node module define which inputs are available for triggers. A new capture trigger source information method provides a list of supported trigger inputs.

Also new for this release is a optional pre-conditional input and logic configuration. The capture trigger can be configured to wait for the pre-condition input edge or for a particular pre-condition input state. This feature is useful for homing routines that want to trigger on the first encoder index input when the home input signal is active. Also, a configurable digital input filter was added to support two different filter rates.

Support for events in captures were added. When a capture is triggered, the controller can generate an event message which contains a buffer of captured positions and times (for time-based captures). If using single shot captures, poll the status and read the captured position value (as in previous releases). If using auto-arm, it is required to use events so the buffered capture data is not lost by multi-triggers.

If using captures for homing, be aware that the motor's dedicated home limit block no longer exists and the capture is no longer motor specific. In 03.04.xx (or earlier), if the motor's dedicated home limit was configured for an action (Stop, E-Stop, Abort, etc.) and the capture was configured for a home input, the home input would trigger the capture which would trigger the home limit block generating a home limit action and an event. Now the dedicated home input can be configured to trigger the capture directly and generate a capture event. To trigger a capture on a home input, configure the capture input source for the dedicated home input. When the capture triggers, it generates a capture event to wake a host thread and then the host thread can command an action (Stop, E-Stop, Abort, etc.). This methodology simplifies the application logic and potential race conditions.

Node FPGAs

New SynqNet Node FPGA Runtime images are available in version x500. These images contain support for the new SynqNet Capture features and 64 node networks. Due to the new Capture features, the 500 FPGAs are NOT backwards compatible with previous MPI software releases (03.04.xx or earlier), nor are previous FPGAs (4xx or earlier) compatible with the 04.xx.xx MPI. The MPI automatically checks the FPGA version compatibility. If the FPGA is NOT compatible, the MPI returns an error. For example, an RMB-10V2 node causes the following message:

ERROR 0x1730 - network in asynq mode :: Please Download  C0FE0029_0500.sff

SynqNet cyclic operation is NOT allowed until compatible FPGAs are downloaded to all the nodes. For more information, see Node Runtime Image Files.

User Limit

A new user limit object is now available. The user limit is a general purpose logic block that executes in the background cycle of the controller. It can be configured to trigger on 1 or 2 input conditions (with a logical AND or OR), generate an action on a specified axis, generate an event, and write to an output (digital, analog, user buffer, or address). There are pre-defined configurations for common conditional inputs for things like motor dedicated/general digital inputs, axis position, axis velocity, axis position error, other user limits, user buffers, drive monitors, captures, etc. The user limit is not associated with a motor. The event message contains the values of the input conditions at the time the user limit was triggered. Up to 128 user limits per controller are supported.

In previous releases, the motor object had an internal XMP configuration structure for the user limit of the firmware. The previous interface required programming directly to the internal structures and configuring pointers to memory locations.

For more information, see User Limit objects.

Simplified Flash

The MPI flash object was eliminated and its functionality was integrated into the control object. Applications do not need to create or manage flash objects. The controller’s flash provides non-volatile storage for the controller’s executable code (firmware and FPGA) and configurations. The control object contains methods to determine the default firmware files, download or upload firmware, save configurations to flash, and reset the flash configurations to default.

To change controller configurations, call mpiObjectConfigGet(…), modify the configuration structure elements, and call mpiObjectConfigSet(…) to write the configurations to the dynamic memory of the controller After setting your configurations you can save them to flash by using mpiControlFlashSaveAll(…). The mpiControlFlashSaveAll(…) copies the entire contents of the dynamic memory configuration including the SynqNet network topology to flash.

In previous releases, the configurations are set to dynamic memory using mpiObjectConfigGet/Set(…), then the application sets the flash memory using an equivalent mpiObjectFlashConfigGet/Set(…). Due to the dynamic controller memory allocation, flash configurations are saved (or reset) in their entirety instead of on a per object basis.

Save/Clear topology to and from flash is now integrated into the control flash and is not required as an additional step. mpiControlFlashSaveAll(…) copies the entire contents of the dynamic memory configuration including the SynqNet network topology to flash.

To clear (reset to default) the dynamic memory configurations, use the new method mpiControlResetToDefault(…). To clear (reset to default) the flash memory configurations, call mpiControlResetToDefault(…), followed by mpiControlFlashSaveAll(…).

For more information, see the diagram Saving/Clearing a SynqNet Topology and mpiControlFlashSaveAll.

Backlash Compensation

A new backlash compensation feature was added that is useful for motion systems with poor mechanical coupling between the motor/feedback and the load. When backlash compensation is configured properly, the controller automatically compensates by adding or subtracting a feedback offset when the commanded motion changes direction.

As an example, a motor that is connected to a poor quality lead screw with a one-quarter revolution of backlash. When the motor rotation is reversed, the motor shaft must move one-quarter of a turn before the lead screw threads engage the nut and moves the load. To compensate, the axis backlash compensation width and rate can be configured in the controller. Afterwards when the commanded motion changes direction, the controller automatically adjust the position offset to correct the mechanical position error.

Map Module

The MPI map module contains functions to convert between string representations of firmware structures and the controller address. The map module was expanded to allow users to obtain addresses for commonly referenced firmware memory such as axis trajectory information, I/O states, and motor demands by specifying a location enumeration value and associated indices. It will also be possible to translate the firmware addresses back into the enumeration and indices.

For more information, see the Map module.

User Unit Storage

The new user unit storage feature allows applications to store conversion factors and labels for position, velocity, acceleration, and jerk in the controller for each axis. This feature is useful for applications that want to provide engineering units (inches, meters, meters/sec, etc.) at the user interface layer. The user units are not applied to the MPI/Controller values for position, velocity, acceleration, and jerk. This capability may be added in a future release.

SynqNet Network Diagnostics

The SynqNet diagnostic features can identify issues during installation and operation. For failed systems, the diagnostic and analysis features can determine the cause and recommend corrective actions.

At installation time, the SynqNet network cables can be tested for integrity using the method mpiSynqNetCableQuality(…) or with the new utility program sqCableQuality. Cables can be exercised with a specified packet load and statistical data is collected to determine the cables performance.

During network operation the sqLogger utility can be used to monitor and log network status and events (packet errors, CRCs, faults, etc.) with time stamps to a text file. Later, the history of network behavior can be viewed to locate marginal or failing equipment.

mpiSynqNetDiagnosticsInfo(…) can check the network condition during operation or after a failure. The diagnostic information contains a comprehensive snapshot of the network characteristics and status. The diagnostic information can be passed to mpiSynqNetAnalyze(…), which analyzes the diagnostic information to determine if the network and node conditions are good, fair, or bad. It also describes the problem and recommends corrective actions.

For more information, see sqCableQuality, mpiSynqNetCableQuality, sqLogger, mpiSynqNetDiagnosticsInfo(…), and mpiSynqNetAnalyze(…).

SynqNet Topology Discovery

The new SynqNet topology discovery feature provides topology information for a network that fails to initialize due to a network topology mismatch error. This feature is useful for comparing the actual network topology discovered during SynqNet initialization with the expected network topology. From the comparison it can be determined where the network is incorrectly wired, or the location of missing or added nodes.

Helpful Tip! When creating your desired network topology, use mpiSynqNetTopologyDiscovered(…) and store the topology information. This allows you to compare the stored expected network topology with the discovered network topology to identify the mismatched nodes if a topology mismatch error occurs

SynqNet Packet Schedule Improvements

There are two changes that may affect the packet scheduling when upgrading your system to 4.0. The controller FPGA logic was optimized to reduce delays required for packet error handling and the capture module was improved. The new capture module may increase the FEEDBACK packet size for some nodes.

Whenever your SynqNet system configuration changes or MPI software is upgraded, it is recommended to verify the control latency. SynqNet schedules adapt to hardware changes (controller type, number of nodes, node types, topology, and cable length). Future software releases may include improvements to the schedule algorithms. To ensure hardware and/or software changes, do not change the control loop behavior; verify that the overall control latency remains identical.

For more information, see SynqNet Timing Values. For more information about SynqNet timing values, see the SqTiming1.c sample application.

Installation (Directories, Device Driver, and Environment Variables)

The InstallShield distribution package was updated to support future multiple MPI version installations and new installation directories. If a new version is being installed, the InstallShield package provides an option to uninstall the old version or install the new version to a different directory. If multiple versions are required, the shortcuts and environment variables are updated to reflect the latest installation. If switching between versions is desired, it is required to configure the environment variables manually.

The default installation directory was changed to:

C:\Program Files\Danaher Motion\MDK\xx.xx.xx

Note: Where xx.xx.xx is the version number.

The new directory structure and contents are as follows:

\controller – Controller’s firmware, firmware address map, and FPGA files

\node – Node FPGA and drive parameter map (.dm) files

\Win32 – Libraries, utility programs, and executable programs for the Windows platform

\MPI – MPI header files, apputil sources, examples, and utility program sources

The Windows XP device driver was updated to support additional interrupt features and is backwards compatible with MPI 03.01 to MPI 03.04 releases.

Note: The InstallShield package automatically upgrades your device driver during installation.

There are two new environment variables, set by the InstallShield during installation:

MEI_MDK_DIR – MPI installation directory for active version (latest installation)

Note: Where xx_xx_xx is the version number.

For more information about installation, see Software Installation Instructions.

Software Runtime License

The controllers are configured during manufacturing to enable features that are specified by the order. The number of axes, MechaWare, and motion control (filter and data recorder objects) features are enabled by the controller runtime license. The MPI verifies the controller’s runtime license and automatically restricts usage to the licensed features.

Note: Enabling an unlicensed feature returns a runtime license error.

To view the licenses for your controller, use the version.exe utility program or call the mpiLicenseInfoText(…) method.

Note: It is strongly recommended to purchase a full-featured runtime license for your development controllers. Once your machine transitions to the manufacturing stage and specific details are finalized such as how many axes and whether MechaWare will be used, you can then purchase future controllers with only the features your machine requires.

For more information, see Controller Runtime License.