General Definitions

MPI

The Motion Programming Interface (MPI) defines a set of object-oriented, C-language functions and data types that you can use to develop motion control applications. The MPI is designed to be independent of the motion controller hardware used, as well as the platform (operating system & compiler) on which the motion control application is built. To support the MPI, a platform must be 32-bit (e.g. Windows NT). Most 32-bit platforms are capable of multi-threading and multi-tasking, and the MPI has built-in features that simplify the design and development of these types of applications.

Platform

A platform is the combination of the host computer, operating system, and C compiler. A platform must be 32-bit, i.e., the operating system must be able to execute 32-bit programs

MPI Installation Directory

The MPI installation directory is the location into which the MPI software has been installed. The installation procedure suggests a default location, but you can choose to install it wherever you desire. It is highly recommended that you use the default location. The installation directory contains:

Version 4.0 (and higher):

Directory	Contains
\controller	Controller’s firmware, firmware address map, and FPGA files
\node	Node FPGA and drive parameter map (.dm) files
\Win32	Libraries, utility programs, device driver, and executable programs for the Windows platform
\MPI	MPI header files, apputil sources, examples, and utility program sources

Version 3.4 (and lower)

MPI Subdirectories

Directory \ MPI	Contains
\doc	Documentation - User and Reference Guides
\include	MPI header files

XMP Subdirectories

Directory \ MPI	Contains
\app	Sample applications
\bin	XMP firmware
\bin\WinNT	Windows NT utilities (from util)
\include	XMP header files
\lib	XMP libraries
\util	XMP utility source

Object

An object is an instance of a data structure. The data structure is typically not directly accessible by an application.

When an application calls a function (also called a method) to create an object, the function returns a handle to the object. The object handle is then passed as the first argument to all other functions (methods) that are associated with that object. These functions provide indirect access to the object's data structure. When it is finished using an object, an application simply calls another function to delete it.

Example

The MPI defines an Axis object. An Axis object is created by the mpiAxisCreate(...) function, which returns a handle of type MPIAxis. The mpiAxisStatus(...) function takes an Axis handle as its first argument and returns the status of the hardware axis with which the Axis object is associated. An Axis object is deleted by calling the mpiAxisDelete(...) function.

Handle

A handle is returned by the function that creates an object, and the handle uniquely identifies that object. A handle is simply a pointer to a pointer to an object. The MPI defines the type MPIHandle to be a generic handle. The symbol MPIHandleVOID is used to represent an invalid handle. The MPI functions that create and delete objects typically allocate and free memory from a heap; in this case a handle is generally a pointer to the allocated object data structure. However, an MPI implementation could define a handle to be a pointer into a static array of data structures, or an index into such an array. Regardless, an application MUST NOT do anything with a handle other than to pass it as an argument to other functions. In cases where a handle is a pointer, the pointer cannot be dereferenced, because the object data structure to which the handle points is not directly available to the application.

Example

The MPI defines an Axis handle to be of type MPIAxis. An axis handle named axisHandle can be declared as follows:

MPIAxis axisHandle;

Method

A function associated with an object is called a method. The first argument of a method is always the handle of the object with which it is associated. A function that is not associated with an object is called a function. Throughout the MPI documentation, the term function refers to methods and functions, whereas the term method only refers to methods.

Example

The following functions are all considered to be methods:

mpiAxisCreate(...)
mpiAxisStatus(...)
mpiAxisDelete(...)

MPIAxis axis;
mpiAxisCreate(&axis, );
mpiAxisStatus(axis, .);
mpiAxisDelete(axis);

Module

A module is a source file (module.c) whose interface is declared in a header file (module.h). A module contains code symbols (methods, functions, macros) and data symbols (data, data types and constants) that together implement an object. However, a module may also contain functions that have a logical connection without being associated with an object.

MPI Module	Header
Axis	axis.h
Capture	capture.h
Client	client.h
Command	command.h
Compensator	compensator.h
Control	control.h
Drive Map	driveMap.h
Element	element.h
Event	event.h
Filter	filter.h
Firmware	firmware.h
List	list.h
Map	map.h
Message	message.h
Motion	motion.h
Motor	motor.h
MpiDef	mpidef.h
MPI Map	mpimap.h
Notify	notify.h
Object	object.h
Packet	packet.h
Platform	platform.h
Recorder	recorder.h
Server	server.h
Sequence	sequence.h
SqNode	sqNode.h
SynqNet	synqNet.h
User Limit	userLimit.h
Trace	trace.h

Example

The axis module consists of a source file called axis.c and a header file called axis.h. The axis.c source file contains the definitions of all Axis code and data symbols, in particular the Axis object data structure. The axis.h header file contains the declarations for the code and data symbols in axis.c.

Introduction | Motion Concepts | General Definitions | Naming Conventions | Object Descriptions