AxisModule

Preface

This is a draft of the Axis Module API and Reference documentation. Although not complete, the API, FSM, and documentation provide sufficient content upon which to do an evaluation. Notable omissions or problems due to a lack of consensus in the Axis module documentation include:

1. distinguishing linear from rotary axis. For example, a Length data type may be used instead of more specific type.
2. handling measures and units in a STEP compliant way has not been fully assimilated, instead most parameters are handled as typedef doubles, which directly affects the handling of issue 1;
3. resolving the correlation of events to FSM states is still under discussion and has not been firmly resolved. Whether to use a pure Mealy model (actions only associated on state transitions - thus most states require an update event to do a self-transition) or Moore model (only actions associated with state updates) or a hybrid model of the two has not been resolved. At this point, either the Mealy or hybrid model is a candidate solution. 

   The hybrid model would consider the notion of an "Action" being associated with a state transition, and an "Activity " being associated with state update (equivalent to an internal "update" self-transition.)  A state change causes an Action associated with the state transition and an Activity associated with the new state to both  be executed (or should it only be the action?) FSM cyclic updates involve executing the Activity associated to the current state. The distinction between Action and Activity may cause more confusion. Comments are welcome.

   The following API exclusively uses the Action "label". Actions associated with a state update (or self-transition) have an "update" prefix attached to the method.

4. refining the homing API to handle the variety of homing options. 

Background

The Axis module is responsible for control of a single axis of motion. An axis is any movable part of a machine or system that requires controlled motion.  The Axis module models a basic servo-controller to control a single variable, X, so that the Axis module transforms incoming motion setpoints into setpoints for the corresponding actuators. In the case of an axis of motion, X is its position. However, the Axis module API is general enough to support many other common single-input, single-output servo-control applications. The following list itemizes some basic capabilities inherent in the Axis Module API:

• nesting of control loops (e.g. position and velocity) using either derived feedback or additional sensors (e.g. encoders and tachometers)
• ability to perform backlash compensation
• provide information for cross-axis corrections (e.g straightness, squareness, etc.) calculated elsewhere
• ability to use any appropriate sensors and actuators available in the system
• provide settable error limits and "clamping" of various quantities in the loop. If error limits are exceeded, it is expected that the loop will "safe" itself, and inform of an error condition.
• provide data access to be used by external tools for system identification or tuning. Although these tools are not specified in the API, the interfaces allow the potential for on-line integration.

Component Hierarchy

The Axis module defines interfaces that encapsulate the functionality pertaining to a single axis of motion in a standalone or multi-axis control system. The Axis module contains interfaces defining Servoing, Parametric, IO Interfacing, Device Managing and Interpolator components. The Servoing components offer functionality for setpoint motion servoing.  The Parametric components package values defining motion and device limits, dynamics and rates. The IO Interfacing components provide pluggable customization to handle input and output of  setpoint information involving different IO devices and physical setups. The Device Managing components provide functionality to manage the FSM for handling power management, errors, estopping, fault recovery, etc. The Interpolator components provide functionality for trajectory-based motion and includes a Inteperpolator module that acts as a container for these components. The Interpolator components are included as part of the Axis module so that an Axis can be packaged as a standalone single-axis system. If the Axis module is part of a coordinated multi-axis system, the functionality of the Interpolator components would be subsumed by services provided within an Axis Group. The relationship between Axis Module components is shown in the Figure labeled "Axis Module Interface Hierarchy" , and includes interface inheritance (i.e., hollow triangle arrows) and association relationships (i.e., -> arrows) between components.

 
Figure: Axis Module Interface Hierarchy

Below is a description of Axis module interfaces shown in the UML diagram:

IAxis

is a container to manage a collection of axis objects, including basic motion servoing objects, parameter objects, and interfacing objects. The Axis class acts as a container of Axis components by providing a means of storing object references and then providing access to the object references. The IAxis class manages single instances of the each object. (Is there any reason to manage more than one instance of each object?) The IAxis class provides set and get methods to assign(set) or access(get) references to the current instance of each object. A component realization of an IAxis interface would also include an implementation of an Axis FSM as defined in the section describing Axis Behavior.

IAxisCommandedInput

Clients interface to Axis for controlling desired position, velocity and torque.

IAxisCommandedOutput

Services for commanding actuator setpoint.

IAxisDisabling

Services for disabling axis.

IAxisEnabling

Services for enabling axis.

IAxisLimits

Limits to motion ranges.

IAxisPositioningServo

Services for position servoing.

IAxisResetting

Services for resetting axis.

IAxisSetup

Services preparatory to cyclic operation that can be supplied before arrival of commanded values, and contains the capability limits specified classes AxisLimits and AxDyn.

IAxisSensedState

Services to handle sensor data (such as position and velocity feedback) and provides values derived from raw, measured, filtered, and other knowledge.

IAxisTorqueServo

Services for torque servoing.

IAxisVelocityServo

Services for velocity servoing.

Axis Interpolator components are defined within the Axis Module to allow deployment of a standalone Axis. The packaging of these services in the Axis module allows users to a buy a deployment-ready Axis that may not be part of a large multi-axis controller. The Axis Interpolator provides primitive trajectory responsibilities when the axis is not expected to coordinated by an Axis Group module. Should an Axis Group be part of a deployed controller, it would subsume the functionality defined by these interfaces. If an Axis Group is not part of the deployed controller, components that implement these interfaces would typically be part of the Human Machine Interface subsystem.

IAxisSupervisor

is a container to manage a collection of interpolation objects, including homing, continuous jogging, incremental jogging and absolute positioning. The interpolation is done by coordinating the activity of an Axis. The IAxisSupervisor controls an Axis via an IAxis reference.

IAxisAbsolutePositioning

Services for absolute position jogging.

IAxisHoming

Homing service.

IAxisJogging

Jogging service.

IAxisIncrementing

Incremental jogging service.

IAxisRates

Motion profile description.

These above interfaces allow deployment of plug-and-play components adhering to these interfaces that are customized to accommodate different axis functionality, as well as to accommodate axis integration with different hardware. To accommodate different hardware, a user would plug in different AxisCommandOutput and AxisSensedState components to work with varying hardware. For example, one set of components would be suited for interfacing with a D/A interface card as opposed to another set of components suited for interfacing with hardware based on a SERCOS network.

Behavior

The Axis module is responsible for coordinating among several control strategies for managing motion. Each control strategy has an associated Axis motion control component that implements the control strategy. Motion control components model a basic servo-controller in order to control a single variable X. In the case of the AxisPositioningServo component, X is position. Internally, motion control components implement a servoing strategy, such as, open loop, closed loop, bang-bang, or fuzzy logic. It is assumed a motion control component instance would implement one servoing strategy. Motion control components are not restricted from implementing multiple servo strategies, however, the Axis module API does not have any methods for supporting this. In order to change a servo strategy, the component is replaced in the Axis container with a new component and servo strategy.

Motion control components operate cyclically. Assuming closed loop control, each cycle a motion control component gets the desired X, reads the actual X, uses a Control Law component to calculate a new commanded setpoint Xdot, and then writes the new setpoint Xdot. We assume each cycle is bounded by a worst-case time period, although this performance time is not explicitly specified nor accessible by the Axis API. The worst-case time period measured using a typical CPU benchmark is expected to be part of the component data sheet.

To increase flexibility and modularity, the motion control components delegate operation to other assisting components for services that include calculating the setpoint transform, handling actuator and sensor IO, and determining motion control parameters. The Axis class acts as a container for these Axis components. All Axis components, including motion control components, use the Axis class container to access other assisting Axis component. For this to work, all Axis components inherit the interface IOmacAxis, which contains a method setAxisReference(IAxis * axis) for setting the reference of the Axis container. The control system configuration will use this method to set the proper Axis reference.

The assisting components include:   AxisCommandedInput, AxisCommandedOutput, AxisDyn, AxisKinematics, AxisLimits, AxisMaintenance, AxisRates, AxisSensedState, and AxisSetup.

• AxisCommandedOutput and AxisSensedState components act as IOPoint module intermediaries by providing a uniform IO interface and hiding specialized hardware service. The CommandedOutput component interfaces to the actuator and the SensedState component interfaces to the feedback sensor(s).
• AxisCommandedInput provides an interface for Axis clients to specify new desired setpoints. This component may provide interpolation service if necessary to map Axis clients update rates (such as an Axis Group's updating at 10 milliseconds intervals) into Axis servo rate (such as 1 millisecond interval updates).
• AxisDyn, AxisKinematics, AxisLimits, AxisRates provide modular parameterization. AxisDyn is responsible for the dynamic parameters of the control algorithm. AxisKinematics is responsible for the kinematic parameters that one would find in describing a robotic joint. AxisLimits defines the limits to the range of motion parameters. Motion that violates these limits signals an error. Error detection is the responsibility of the currently active Axis control strategy component. AxisRates defines the limits to trajectory parameters. Some of these parameterizations are used by clients to interrogate the Axis of its capabilities, limits, or features. For example, an Axis Group may need to understand the acceleration limit of a group of Axes it is coordinating for use in it trajectory calculations.

Within the Axis components that follow position, velocity, acceleration, or torque, ControlLaw components can be used to do loop closure. Assignment of a ControlLaw component to a Position/Velocity/Acceleration/Torque servo, is done through Specialization of the servo Base Class. For example, AxisVelocityServo may not need a ControlLaw component for loop closure if the Axis is connected to SERCOS drive configured to accept velocity setpoints. In this case, the implementation class is simply:

 
    class CAxisVelocityServo : public IAxisVelocityServo;

However, AxisVelocityServo may need a ControlLaw component if it is doing software servoing, and would require an association to the IControlLaw interface:

 
    class CAxisVelocityServo() : public IAxisVelocityServo 
    {
      IControlLaw * velocityControlLaw;
    };
    

Assignment of velocityControlLaw is done at configuration time. (See Omac Module Description for more information concerning configuration. )

Each cycle the motion control component is also responsible for testing for error conditions such as limit violations or hardware failures.

The Axis class, coordinates between the different servoing motion control strategies by means of a Finite State Machine (FSM). The FSM, including events, states, and state transitions, is predefined for the Axis module and is shown in the following diagram.

Switching between servoing  motion control strategies is achieved by sending events to the Axis FSM. The internal FSM implementation is itself hidden (which is an area of debate), but the Axis interface provides methods for event propagation and state query. The Axis FSM corresponds to the READY state of the OMAC Module FSM. The OMAC module defines a deployment FSM for activating and deactivating a component/module in the system. All Axis components inherit the event methods from the IOmac interface, and must implement the FSM corresponding to the OMAC deployment FSM. Once a component has been activated and is in the READY state, it can then delegate to its functional-specific FSM. Thus, the READY state in the OMAC FSM is the superstate of the subordinate Axis FSM.

The Axis-specific FSM event propagating methods, which can lead to state transitions and may result in changing control strategies, include:    disableAxis, enableAxis, estopAxis, followCommandedTorque, followCommandedAbsPosition, followCommandedRelPosition, followCommandedTorque, followCommandedVelocity, resetAxis, and stopAxis. Note that each pluggable component has seperate stopping actions associated with the pluggable component and that there is not a generic "Stopping" pluggable component. The relationship between state, events, next state and action associated with the state transition in the Axis module FSM is given in the following table.

First  State = Disabled

Stop and and internal Failed events can occur in any state. The occurrence is valid, i.e., a transition should be defined for these events in all states, with the following special situations:

• Failed occurring in Failed state: Transitions to the Failed state, but issue notification event that can be used to log for later diagnosis.
• Stop occurring in Failed state: Transitions to the Failed state, but issue notification event that can be used to log for later diagnosis.
• Stop occurring in Stopped state: Transitions to the Stopped state, but issue notification event that could be used to notify user that Axis is already stopped.

The State Definitions and Query Table supplements the behavior model described above by the state table. This table provides a detailed description of each state and identifies the query mechanism for determining if the Axis module is in that state. The Axis FSM states, state description, and query methods is described in the following table.

First  State = disabled

Operational Scenario

A typical multi-axis control system, such as a CNC or robot, would require an Axis module for each axis of motion. Although common enough, a system containing axis with multi-actuators, such as a robot with a parallel link joint, is not directly addressed and would require a specialization of the Axis module. Assume the application requiring to illustrate the various components within an Axis Module is a NC programmable, two-axis lathe. We will assume that both axis components are the same for each axis and consist of a PWM motor drive, an amplifier enable control, an amplifier fault status signal, an A-QUAD-B encoder with marker pulse and switches for home and axis limits. The Figure labeled "Sample Architecture Implementing Axis Module"  illustrates the relationship of the Axis Module, the internal consummate parts of the Axis Module (such as CommandedInput, CommandedOutput, SensedState, FollowingPosition,etc.) and the interaction with external objects such as IO points.

Figure 4. Sample Architecture Implementing Axis Module

As an illustration of Axis module operation, a typical scenario will be walked through. Assume that the scenario has an Axis Group in control of several axes, but to keep matters simple, we will only consider the Axis Group interaction with one axis. Further assume in the scenario, that the startup deployment phase has completed and the Axis Group and Axis module have been configured, integrated and enabled. At this point, the Axis Group would have an object reference to the Axis module, and all object references between the Axis components would have been resolved. Now, the Axis module should be in the MAC FSM READY state that corresponds to the Axis Module DISABLED state. 

To start the Axis position servoing, the Axis Group would issue an enable, a holdPosition and a followingPosition series of events to the put the Axis in followingPosition servoing. To do this, Axis Group uses an object reference to the Axis module to call the  IAxis methods enable(), holdPosition(), and followPosition() . For the followPosition() method case, this method causes the Axis module to internally queue a FOLLOW_POSITION event in the Axis module FSM. It is expected that an Axis module implementation would queue events, but not required, so that event queuing cannot be syntactically represented, only semantically annotated, for the Axis module API. (Note, the queue could be of length one, in which case, the queue acts like a communication mailbox.)

Although not required, event queuing may be preferred for the following reasons:

1. To shorten the response, not necessarily the operation. If the Axis module actually performed the followAcceleration service upon receiving this command, it would tie up both the Axis and the Axis Group module execution.

2. To prevent deadlocks. If Axis actually performed the followPosition service, it could require a call on the Axis Group which could result in deadlock if the Axis Group's methods are not thread-safe.

3. Use events since multiple threads are running in the system and it is desirable to protect the queuing of the event through mutual exclusion. An example of concurrent threads is the Task Coordinator sending Homing Events and the Axis FSM receiving the events. But HMI, or Axis Group could also send events and be in other threads. Some OMAC modules are typically aperiodic, such as Task Coordinator and HMI, and can run as separate threads.

External to the Axis and Axis Group, some scheduling mechanism causes the Axis module to cyclically execute by calling the update() method inherited from IOmac. The Axis module updates assisting Axis components and then uses the Axis module FSM to determine what Axis control strategy component action to invoke. For this case, the Axis FSM invokes action methods in the AxisPositioningServo component interface. After initially receiving the followPosition, the Axis FSM will invoke startFollowingPositionAction(). For subsequent cycles, the Axis FSM will invoke updateFollowingPositionAction() until a stopMotion() causes a StopFollowingPosition event. For the StopFollowingPosition event, the Axis FSM will invoke stopFollowingPositionAction() and updateStoppingFollowingPositionAction() until the following position has returned to holding position, most likely within one cycle. Any errors during following position control would result in invoking errorFollowingPositionAction() that the Axis module is responsible for monitoring and then responding to an error.

In lieu of an object interaction diagram, the following code illustrates the calling sequence to involved in following position servo control:

AxGrp->anAxis->followPosition()
Updater->anAxis->update()
  anAxis->AxisFSM->AxisPositioningServo->startFollowingPositionAction()
AxGrp->anAxis->getAxisCommandedInput()->setCommandedPosition(value)
Updater->anAxis->update()
     AxisSensedState->update()
     AxisCommandedInput->update()
     AxisFSM->AxisPositioningServo->updateFollowingPositionAction()
          AxisCommandedInput->getPositionCommand()
          AxisSensedState->getActualPosition()
          ControlLaw->(load parameters)
          ControlLaw->calcControlCmd()
          ControlLaw->(get results)
          AxisCommandedInput->setVelocityCommand()
          AxisCommandedOutput->setPositionCommand()
          AxisVelocityServo->updateFollowingVelocityAction() ...
              // Now perform velocity control loop
              AxisCommandedInput->getVelocityCommand()
              AxisSensedState->getActualVelocity()
              ...     
              AxisCommandedInput->setAccelerationCommand()
              AxisCommandedOutput->setVelocityCommand()
            
   AxisCommandedOutput->update() (acceleration goes to SERCOS drivers)          


Source

Axis Module IDL

Comments?

Comments concerning this module are solicited on the following topics. The split of Axis module into servoing and interpolating objects warrants an opinion. Is the coverage of all potential control strategies sufficient.  Comments on other issues are also welcome.

Submit Feedback

Issues/FAQ/TBD

Last Updated September 01, 2000 08:46:58

Interface IAxis

The Axis class is a container to manage a collection of axis submodule objects that also provides higher level FSM management of these submodules. Containers are as "a class that holds objects of some (other) type". The Axis class is a container that provides a means of storing Axis submodule references and then providing access to the references of the axis submodule objects. In addition, the Axis class coordinates motion using different motion control submodule depending on the commanded control strategy. The Axis submodule objects include: AxisCommandedInput, AxisCommandedOutput, AxisDyn, AxisEnabling, AxisKinematics, AxisLimits, AxisMaintenance, AxisPositioningServo, AxisRates, AxisSensedState, AxisSetup, AxisTorque Servo, and AxisVelocityServo.

The Axis class has an association with a FSM to manage several different motion control strategies. Each control strategy has an associated Axis motion control submodule that implements the control strategy. The motion control submodules include: AxisAccelerationServo, AxisEnabling, AxisPositioningServo, AxisTorque Servo, and AxisVelocityServo. Depending on the state, a different submodule is active, and the methods associated with each object are executed depending on the motion state. When active, a submodule is updated each cycle, by calling its update function.

The type of motion alogrithm that is controlling the axis is dependent on the state of the Axis FSM. The FSM itself is hidden, but the Axis interface offer methods for state query and for propogating events. The state query methods include: abort, Disable, disableAxis, Enable, enableAxis, estop, execute, followCommandedForce, followCommandedPosition, followCommandedTorque, followCommandedVelocity, home, jog, resetAxis, stopMotion, startup, stop, terminate, update, and updateAxis.

Method Detail

currentStateName

Axis module state accessor method that returns a BSTR containing current state name.

Parameters:

str - is a reference to a BSTR. Client (calling object) must SysFreeString() the returned BSTR wide character string.

Returns:

S_OK - successful execution string returned.

E_OUTOFMEMORY failed to allocate BSTR buffer.

disableAxis

Method to trigger event to disable a module. Upon handling, event will cause a transition from the disabled state to the enabled state within the Axis Module FSM. Note, there is a naming collision with Windows disable enumeration. This is the reason for the capitalization of the Disable method.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

enableAxis

Method to trigger event to enable a module. Upon handling, event will cause a transition from the disabled state to the enabled state within the Axis Module FSM. Note, there is a naming collision with Windows enable enumeration. This is the reason for the Capitalization of the Enable method.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue. FIXME.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

See Also:

IOmac

endCommandedPosition

Method to trigger a EndCommandedPosition event. Upon handling, event will cause a transition from a HoldingPosition state to an Enabled state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

endCommandedTorque

Method to trigger a EndCommandedTorque event. Upon handling, event will cause a transition from a HoldingTorque state to an Enabled state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

endCommandedVelocity

Method to trigger a EndCommandedVelocity event. Upon handling, event will cause a transition from a HoldingTorque state to an Enabled state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

estopAxis

Method to trigger an estop event. Upon handling, event will cause a transition from any state to an estop state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since estop event Upon handling, event will be placed at the front of the queue to be handled immediately.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

followCommandedAbsPosition

Method to trigger a followCommandedAbsPosition event. Upon handling, event will cause a transition from a HoldingPosition state to a FOLLOWINGABSPOSITION state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

followCommandedRelPosition

Method to trigger a followCommandedRelPosition event. Upon handling, event will cause a transition from a HoldingPosition state to a FOLLOWINGRELPOSITION state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

followCommandedTorque

Method to trigger a FollowCommandedTorque event. Upon handling, event will cause a transition from a HoldingTorque state to a FOLLOWINGTORQUE state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

followCommandedVelocity

Method to trigger a FollowCommandedVelocity event. Upon handling, event will cause a transition from a HoldingTorque state to a FOLLOWINGVELOCITY state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

getCommandedInput

Gets the current commanded input OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the commanded input interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getCommandedOutput

Gets the current commanded output OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the commanded output interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getDisabling

Gets the current disabling COM object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the disabling interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the Axis Supervisor does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getDynamics

Gets the current dynamics setup OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the dynamics setup interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getEnabling

Gets the current error and enabling COM object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the error and enabling interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the Axis Supervisor does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getHomeOffset

Get the homed offset for the axis.

Parameters:

pOffset - pointer to double variable, with units in millimeters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - homing offset not implemented.

getKinematics

Gets the current kinematics setup OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the axis kinematics interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getLimits

Gets the current axis limits definition OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the axis limits definition interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getMaintenance

Gets the current axis maintenance OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the axis maintenance interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getPositionControlLaw

Get the current axis position control law OMAC object reference.

Parameters:

ppIControlLawObject - is the address of the pointer variable that receives the position control law interface pointer requested. Upon successful return, ppIControlLawObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIControlLawObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getPositioningServo

Gets the current axis position servoing OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the axis position servoing interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getResetting

Gets the current resetting COM object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the resetting interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the Axis Supervisor does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getSensedState

Gets the current axis sensed state OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the axis sensed state interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getSetup

Gets the current axis setup OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the axis setup interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getTorqueControlLaw

Get the current axis torque control law OMAC object reference.

Parameters:

ppIControlLawObject - is the address of the pointer variable that receives the torque control law interface pointer requested. Upon successful return, ppIControlLawObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIControlLawObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getTorqueServo

Gets the current torque servoing OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the torque servoing interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getVelocityControlLaw

Get the current axis velocity control law OMAC object reference.

Parameters:

ppIControlLawObject - is the address of the pointer variable that receives the velocity control law interface pointer requested. Upon successful return, ppIControlLawObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIControlLawObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getVelocityServo

Gets the current axis velocity servoing OMAC object reference.

Parameters:

ppIAxisObject - is the address of the pointer variable that receives the velocity servoing interface pointer requested. Upon successful return, ppIAxisObject contains the requested interface pointer to the object. If the AxisModule does not have a reference to this object, ppIAxisObject is set to NULL, and an error code is returned.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

holdCommandedPosition

Method to trigger a HoldCommandedPosition event. Upon handling, event will cause a transition from an Enabled state to a holdingPosition state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

holdCommandedTorque

Method to trigger a HoldCommandedTorque event. Upon handling, event will cause a transition from an Enabled state to a holdingTorque state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

holdCommandedVelocity

Method to trigger a HoldCommandedVelocity event. Upon handling, event will cause a transition from an Enabled state to a holdingVelocity state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

homed

Set axis homed. Axis can now do absolute positioning.

Returns:

S_OK - successful.

E_FAIL - unsuccessful.

isDisabled

Axis module state accessor method to determine if in disabled state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isDisabling

Axis module state accessor method to determine if in disabling state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isEnabled

Axis module state accessor method to determine if in enabled state as well as if in any state past enabled?

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isEnabling

Axis module state accessor method to determine if in enabling state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isEstopped

Axis module state accessor method to determine if in "estopped" state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isEstopping

Axis module state accessor method to determine if in "estopping" state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isFaulted

Axis module state accessor method to determine if in "faulted" state after detecting internal error.

Parameters:

b -  boolean [out] flag, with true indicating in faulted state, false not in faulted state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isFollowingPosition

Axis module state accessor method to determine if in "followingPosition" state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isFollowingTorque

Axis module state accessor method to determine if in followingTorque state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isFollowingVelocity

Axis module state accessor method to determine if in "followingVelocity" state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isHoldingPosition

Axis module state accessor method to determine if in holdingPosition state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isHoldingTorque

Axis module state accessor method to determine if in holdingTorque state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isHoldingVelocity

Axis module state accessor method to determine if in holdingVelocity state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isHomed

Axis module state accessor method to determine if Axis is homed.

Parameters:

b -  boolean [out] flag, with true indicating axis homed, false axis not homed.

Returns:

S_OK - successful homed determination.

E_FAIL - unsuccessful homed determination. Unspecified reason.

isReady

Axis module state accessor method to determine if in "ready" state. Ready state is equivalent to enabled state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

isResetting

Axis module state accessor method to determine if in "resetting" state.

Parameters:

b -  boolean [out] flag, with true indicating in state, false not in state.

Returns:

S_OK - successful state determination.

E_FAIL - unsuccessful state determination. Unspecified reason.

loseHome

Set not homed. Axis can no longer do absolute positioning.

Returns:

S_OK - successful.

E_FAIL - unsuccessful.

processServoLoop

The primary method. Runs a servo loop. Reads commanded input from AxisCommandedInput object. Reads current status from AxisSensedState. Computes the next setpoint using a combination of position, velocity, and acceleration control laws. Writes output to AxisCommandedOutput.

Returns:

S_OK - if successful.

E_FAIL - if servo loop failed.

resetAxis

Method to trigger a reset event. Upon handling, event will cause a transition from what state to a reset state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

setCommandedInput

Sets the current axis commanded input OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle input commands.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisCommandedInput REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setCommandedOutput

Sets the current axis commanded output OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle output commands.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisCommandedOutput REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setDisabling

Sets the current axis disable handling OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle enable states.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisEnabling REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setEnabling

Sets the current axis enable handling OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle enable states.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisEnabling REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setHomeOffset

Set the homed offset for the axis.

Parameters:

offset - is a double variable, with units in millimeters.

Returns:

S_OK - if successful.

E_FAIL - if unsuccessful.

E_NOTIMP - homing offset not implemented.

setKinematics

Sets the current axis kinematics setup OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle kinematic representation.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisKinematics REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setLimits

Sets the current axis limits setup OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle physical and motion limits.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisLimits REFID interface of the supplied object.

E_NOTIMP - if not implemented. .

setMaintenance

Sets the current axis maintenance OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle maintenance.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisMaintenance REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setPositionControlLaw

Sets the current axis position control law OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle positioning control law.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IControlLaw REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setPositioningServo

Sets the current axis positioning servo OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle position-base servoing.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisPositioningServo REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setResetting

Sets the current axis resetting handling OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle resetting states.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisEnabling REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setSensedState

Sets the current axis sensed state OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle IO status.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisSensedState REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setSetup

Sets the current axis setup OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle setup of values of current rates, maximum physical limits, and dynamic rates.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisSetup REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setTorqueControlLaw

Sets the current axis torque control law OMAC object reference.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IControlLaw REFID interface of the supplied object.

E_NOTIMP - if not implemented (or required?).

setTorqueServo

Sets the current axis torque servoing OMAC object reference.

Parameters:

val - contains a reference to a OMAC object to replace the currently assigned object to handle torque servoing.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisForceServo REFID interface of the supplied object.

E_NOTIMP - if not implemented.

setVelocityControlLaw

Sets the current axis velocity control law OMAC object reference.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IControlLaw REFID interface of the supplied object.

E_NOTIMP - if not implemented (or required?).

setVelocityServo

Sets the current axis velocity servoing OMAC object reference.

Parameters:

val - contains a reference to OMAC object to replace the currently assigned object to handle velocity-based servoing.

Returns:

S_OK - if successful.

E_INVALIDARG - if type mismatch. Method not required to do type checking based on IAxisVelocityServo REFID interface of the supplied object.

E_NOTIMP - if not implemented.

stopAxis

Method to trigger a stopMotion event. Upon handling, event will cause a transition from any motion state (jogging, moving_to, incrementing, homing, following position, following velocity, following acceleration, and following force) state to a stopping state within the Axis Module FSM.

Returns:

S_OK - sucessful event delivery. Generally, assume no real error checking since events can be queued, regardless of current state or event preceding this event in queue.

ERROR_BUFFER_OVERFLOW - assuming queuing of events, couldn't queue event.

E_INVALIDARG - invalid event based upon current or anticipated state when event is expected to be handled. (Should it be queued anyway?)

Interface IAxisCommandedInput

Services for commanding desired setpoints. Setpoints can be position, velocity, acceleration, and force.

A new addition to the interface to handle the case that the Axis cannot do absolute servo positioning until the Axis has been "homed" the IAxisCommandedInput interface is the addition of a setAbsolutePositioning and setRelativePositioning method for commanded input position. Unclear if this is the wrong place for these methods.

Method Detail

getAbsolutePositioning

Query to determine if in absolute positioning mode. Can be in either absolute positioning mode or relative positioning mode, but not both at same time. Default is relative positioning. Cannot do absolute positioning until Axis is homed.

Parameters:

pBoolean -  boolean [out] flag, with true indicating in absolute positioning mode, false not in absolute positioning mode.

Returns:

S_OK - successful positioning determination.

E_FAIL - unsuccessful positioning determination.

See Also:

getRelativePositioning, setAbsolutePositioning, setRelativePositioning, IAxis::setHomed

getAccelerationCmdInput

Get the commanded input (or desired) acceleration for the axis.

Parameters:

pVal - pointer to AxisAccelCmd variable, with units in meters per second squared. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getForceCmdInput

Get the commanded input (or desired) force for the axis.

Parameters:

pVal - pointer to AxisForceCmd variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getPositionCmdInput

Get the commanded input (or desired) position for the axis.

Parameters:

pVal - pointer to AxisPositionCmd variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getRelativePositioning

Query to determine if in relative positioning mode. Can be in either absolute positioning mode or relative positioning mode, but not both at same time. Default is relative positioning. Cannot do absolute positioning until Axis is homed.

Parameters:

pBoolean -  boolean [out] flag, with true indicating in relative positioning mode, false not in relative positioning mode.

Returns:

S_OK - successful positioning determination.

E_FAIL - unsuccessful positioning determination.

See Also:

getAbsolutePositioning, setAbsolutePositioning, setRelativePositioning, IAxis::setHomed

getVelocityCmdInput

Get the commanded input (or desired) velocity for the axis.

Parameters:

pVal - pointer to AxisVelocityCmd variable, with units in meters per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

setAbsolutePositioning

Set absolute positioning mode flag. Can be in either absolute positioning mode or relative positioning mode, but not both at same time. Setting absolute positioning to false, means setting relative positioning mode. Default is relative positioning. Cannot do absolute positioning until Axis is homed.

Parameters:

b -  boolean [in] flag, with true indicating set absolute positioning mode, false setting relative positioning mode.

Returns:

S_OK - successful positioning determination.

E_FAIL - unsuccessful positioning determination.

See Also:

getAbsolutePositioning, getRelativePositioning, setRelativePositioning, IAxis::setHomed

setAccelerationCmdInput

Set the commanded input (or desired) acceleration for this axis.

Parameters:

accelerationCmd - is the new AxisAccelCmd value for this limit, with units in meters per second squared.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setForceCmdInput

Set the commanded input (or desired) force for this axis.

Parameters:

forceCmd - is the new AxisForceCmd value for this limit, with units in Newtons.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setPositionCmdInput

Set the commanded input (or desired) position for this axis.

Parameters:

positioningCmd - is the new AxisPositionCmd value for this limit, with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setRelativePositioning

Set relative positioning mode flag. Can be in either absolute positioning mode or relative positioning mode, but not both at same time. Setting relative positioning to false, means setting absolute positioning mode. Default is relative positioning. Cannot do absolute positioning until Axis is homed.

Parameters:

b -  boolean [in] flag, with true indicating set relative positioning mode, false setting absolute positioning mode.

Returns:

S_OK - successful positioning determination.

E_FAIL - unsuccessful positioning determination.

See Also:

getAbsolutePositioning, getRelativePositioning, setAbsolutePositioning, IAxis::setHomed

setVelocityCmdInput

Set the commanded input (or desired) velocity for this axis.

Parameters:

velocityCmd - is the new AxisVelocityCmd value for this limit, with units in meters per second.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

updateCommandedInput

Method to run an Axis Commanded Input module cycle. So far, this does nothing. FIXME: add cubic interpolation here?

Returns:

S_OK - cycle ran sucessfully

E_FAIL - cycle failed.

Interface IAxisCommandedOutput

Services for commanding actuator setpoints.

Method Detail

getForceCmdOutput

Get the commanded output force for the axis.

Parameters:

pVal - pointer to AxisForceCmd variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getPositionCmdOutput

Get the commanded output position for the axis.

Parameters:

pVal - pointer to AxisPositionCmd variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getTorqueCmdOutput

Get the commanded output torque for the axis.

Parameters:

pVal - pointer to AxisTorqueCmd variable. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getVelocityCmdOutput

Get the commanded output velocity for the axis.

Parameters:

pVal - pointer to AxisVelocityCmd variable, with units in meters per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

setForceCmdOutput

Set the commanded force for this axis.

Parameters:

forceCmd - is the new AxisForceCmd value for this limit, with units in Newtons.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setPositionCmdOutput

Set the commanded output position for this axis.

Parameters:

positioningCmd - is the new AxisPositionCmd value for this limit, with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setTorqueCmdOutput

Set the commanded output torque for this axis.

Parameters:

torqueCmd - is the new AxisTorqueCmd value for this limit, with units in meters per second squared.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setVelocityCmdOutput

Set the commanded output velocity for this axis.

Parameters:

velocityCmd - is the new AxisVelocityCmd value for this limit, with units in meters per second.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

updateCommandedOutput

Method to run an Axis Commanded Output module cycle. Before writing output, clamp the servo output. The IO will scale output values and convert to raw units. Update will actually writing to output IO points. FIXME: does this module need to know if IO is enabled. IO writing will be done whether IO is enabled or not, although if not enabled, the outputs are all zero unless manually overridden. Assume output will not be set by any calculations if IO not enabled.

Returns:

S_OK - cycle ran sucessfully

E_FAIL - cycle failed.

Interface IAxisDyn

Note, much of the information accessible in this interface would not typically be used by the Axis module itself, but rather by clients of the Axis module, in querying the axis to determine its characteristics.

Method Detail

getAccelerationLimit

Get the acceleration limit of this axis.

Parameters:

pVal - pointer to Acceleration variable, with units in meters per second squared. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getAxmass

Get the mass of the axis.

Parameters:

pVal - pointer to Mass variable, with units in Newtons. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getBacklash

Get the backlash length of the axis. Backlash describes relative movement between interacting mechanical parts, resulting from looseness.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getDamping

Get the current damping value for this axis.

Parameters:

pVal - pointer to Force variable, with units in Newtons. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getDeadband

Get the deadband value for this axis. Deadband is defined as the range of values of the controlled variable in which no corrective response is initiated.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getDecelerationLimit

Get the deceleration limit.

Parameters:

pVal - pointer to Acceleration variable, with units in meters per second squared. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getInertia

Get the inertia damping value of the axis. Inertial damping used as a means of providing a stabilizing force for servomechanisms, the force being opposite to that of the servomotor or main drive member and proportional to the acceleration of the system. (Differs from damping in that in the usual sense since inertia is proportional to velocity.) Inertial damping force is effective only during periods of acceleration and has no effect on the output speed under constant velocity conditions.

Parameters:

pVal - pointer to Mass variable, with units in Newtons. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getJerkLimit

Get the jerk limit of this axis.

Parameters:

pVal - pointer to Jerk variable, with units in meters per second cubed. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getLoadedCaseSpringRate

Get the stiffness/spring/compliance of the axis under load.

Parameters:

pVal - pointer to Stiffness variable, with units in Newtons per meter. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getMaxVelAccLim

Get the maximum velocity acceleration limit. Why is this here?

Parameters:

pVal - pointer to Stiffness variable, with units in Newtons per meter. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getOvershootStepInput

Get the overshoot step input of this axis.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getQuasiStaticLoadLimit

Get the quasi static load limit of this axis.

Parameters:

pVal - pointer to Force variable, with units in Newtons. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getRisingTimeStepInput

Get the rising time step input of this axis.

Parameters:

pVal - pointer to Time variable, with units in seconds. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getRunFriction

Get the running friction of this axis. Running friction represents the retarding force that is a linear relationship between the applied force and velocity. FIXME: is this viscous or Coloumb friction?

Parameters:

pVal - pointer to Force variable, with units in Newtons per meter per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getStaticFriction

Get the static friction of this axis. Static friction represents the retarding force that tends to prevent motion from the beginning.

Parameters:

pVal - pointer to Force variable, with units in Newtons per meter per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getTimeConstant

Get the time constant for this axis. The time constant is defined as the time factor in the transfer function to model the dynamic response.

Parameters:

pVal - pointer to Time variable, with units in seconds. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getWorstCaseSpringRate

Get the worst case stiffness/spring/compliance of the axis.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getZeroVelAccLim

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

setAccelerationLimit

Set the acceleration limit of this axis.

Parameters:

newVal - is the new Acceleration value for this limit, with units in meters per second squared.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setAxmass

Set the mass of the axis.

Parameters:

newVal - is the new Mass value for this limit, with units in kilograms.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setBacklash

Set the backlash length of the axis. Backlash describes relative movement between interacting mechanical parts, resulting from looseness.

Parameters:

newVal - is the new Length value for this limit, with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setDamping

Set the current damping value for this axis.

Parameters:

newVal - is the new Force value for this limit, with units in Newtons.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setDeadband

Set the deadband value for this axis. Deadband is defined as the range of values of the controlled variable in which no corrective response is initiated.

Parameters:

newVal - is the new Length value for this limit, with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setDecelerationLimit

Set the deceleration limit of this axis.

Parameters:

newVal - is the new Acceleration value for this limit, with units in meters per second squared.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setInertia

Set the inertia damping value of the axis. Inertial damping used as a means of providing a stabilizing force for servomechanisms, the force being opposite to that of the servomotor or main drive member and proportional to the acceleration of the system. (Differs from damping in that in the usual sense since inertia is proportional to velocity.) Inertial damping force is effective only during periods of acceleration and has no effect on the output speed under constant velocity conditions.

Parameters:

newVal - is the new Mass value for this limit, with units in kilograms.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setJerkLimit

Parameters:

newVal - is the new Jerk value for this limit, with units in meters per second cubed.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setLoadedCaseSpringRate

Set the jerk limit of this axis.

Parameters:

newVal - is the new Stiffness value for this limit, with units in Newtons per meter.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setMaxVelAccLim

Set the acceleration limit at maximum velocity. FIXME: Why is this here?

Parameters:

newVal - is the new value for this limit, with units in meters per second squared.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setOvershootStepInput

Set the overshoot step input of this axis.

Parameters:

newVal - is the new value for this limit, with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setQuasiStaticLoadLimit

Set the quasi static load limit of this axis.

Parameters:

newVal - is the new value for this limit, with units in Newtons.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setRisingTimeStepInput

Set the rising time step input of this axis.

Parameters:

newVal - is the new value for this limit, with units in seconds.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setRunFriction

Set the running friction of this axis. Running friction represents the retarding force that is a linear relationship between the applied force and velocity. FIXME: is this viscous or Coloumb friction?

Parameters:

newVal - is the new value for this limit, with units in Newtons.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setStaticFriction

Set the static friction of this axis. Static friction represents the retarding force that tends to prevent motion from the beginning.

Parameters:

newVal - is the new value for this limit, with units in Newtons.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setTimeConstant

Set the time constant for this axis. The time constant is defined as the time factor in the transfer function to model the dynamic response.

Parameters:

newVal - is the new value for this limit, with units in seconds.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setWorstCaseSpringRate

Set the worst case stiffness/spring/compliance of the axis.

Parameters:

newVal - is the new value for this limit, with units in Newtons per meter.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

setZeroVelAccLim

Set the acceleration limit of this axis at zero velocity.

Parameters:

newVal - is the new value for this limit, with units in meters per second squared.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is not within valid numeric range.

E_NOTIMP - if not implemented (or required?).

Interface IAxisKinematics

Interface to define a lower kinematic model and upper kinematic model consistent with ISO STEP standard services, which is close to the Denavit Hartenberg model. The Denavit-Hartenberg model is extended to model kinematic errors of motion, with variables posFeedBackGain and velFeedBackGain for characterizing geometric errors of motion, such as thermally induced errors. Note, this information would not typically be used by the Axis module itself, but by clients of the Axis module, in querying the axis to determine its characteristics.

Method Detail

getKs

getLowerKinematicModel

getPlacement

getPosFeedBackGain

getUpperKinematicModel

getVelFeedBackGain

setKs

setLowerKinematicModel

setPlacement

setPosFeedBackGain

setUpperKinematicModel

setVelFeedBackGain

Interface IAxisLimits

Limits to motion ranges.

Method Detail

getCutOffPosition

Get the cutoff value for filtering position.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getFollowingErrorViolationLim

Get the violation limit for following error. Following error is defined as the difference between the desired process value and the actual process value.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getFollowingErrorWarnLim

Get the warning limit for following error. Following error is defined as the difference between the desired process value and the actual process value.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getHardFwdOTravelLim

Get the value for the physical hard limit of axis travel in the forward direction.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getHardRevOTravelLim

Get the value for the physical hard limit of axis travel in the reverse direction.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getJerkLimit

Get the value of the jerk limit for axis motion.

Parameters:

pVal - pointer to Jerk variable, with units in meters per second cubed. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getMaxForceLimit

Get the limit or maximum force value of the axis motion.

Parameters:

pVal - pointer to Force variable, with units in Newton. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getMaxVelocity

Get the limit or maximum value of velocity for axis motion.

Parameters:

pVal - pointer to Velocity variable, with units in meters per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getOvershootViolationLim

Get the value of the maximum overshoot permitted. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Overshoot occurs when the system is underdamped and the output process variable value exceeds the setpoint.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getOvershootWarnLevelLimit

Get the warning level limit for the overshoot difference between the error of the process variable (e.g., pos, vel) the desired setpoint, that when exceeded in a steady state condition causes a warning to be issued. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Overshoot occurs when the system is underdamped and the output process variable value exceeds the setpoint. FIXME: what happens upon error.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getSoftFwdOTravelLim

Get the value for the software detected axis over travel limit in the forward direction.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getSoftRevOTravelLim

Get the value for the soft axis over travel limit in the forward direction.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getUndershootViolationLim

Get the violation limit for the undershoot that signals an error condition. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Undershoot occurs when the system is overdamped and the output process variable value falls below the setpoint. FIXME: what happens upon error.

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getUndershootWarnLevelLimit

Get the warning limit for the undershoot that signals an error condition. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Undershoot occurs when the system is overdamped and the output process variable value falls below the setpoint. FIXME: how is warning signalled?

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getUsefulTravel

Get the length for the useful axis travel in the forward and reverse directions?

Parameters:

pVal - pointer to Length variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

setCutOffPosition

Set the cutoff value to filter position.

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setFollowingErrorViolationLim

Set the violation limit for following error. Following error is defined as the error between the process variable (e.g., pos, vel) and the desired setpoint. FIXME: ferror only for position What is done when a violation occurs?

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setFollowingErrorWarnLim

Set the warning limit for following error. Following error is defined as the error between the process variable (e.g., pos, vel) and the desired setpoint. FIXME: what is done when a warning is exceeded?

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setHardFwdOTravelLim

Set the value for the physical hard limit of axis travel in the forward direction.

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setHardRevOTravelLim

Set the value for the physical hard limit of axis travel in the reverse direction.

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setJerkLimit

Set the value of the jerk limit for axis motion.

Parameters:

newVal - is the new value for the maximum jerk limit, with units in meters per second cubed.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setMaxForceLimit

Set the limit or maximum value of the force for axis motion.

Parameters:

newVal - is the new value for the maximum force limit with units in Newtons.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setMaxVelocity

Set the limit or maximum value of velocity for axis motion.

Parameters:

newVal - is the new value for the velocity limit with units in meters per second.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setOvershootViolationLim

Set the violation limit for overshoot. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Overshoot occurs when the system is underdamped and the output process variable value exceeds the setpoint. FIXME: what happens upon error.

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setOvershootWarnLevelLimit

Set the warning limit for overshoot. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Overshoot occurs when the system is underdamped and the output process variable value exceeds the setpoint.

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setSoftFwdOTravelLim

Set the value for the software detected axis travel limit in the forward direction.

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setSoftRevOTravelLim

Set the value for the software detected axis travel limit in the reverse direction.

Parameters:

newVal - is the new value for this limit.

Returns:

S_OK - if value set successfully with units in meters.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setUndershootViolationLim

Set the violation limit for the undershoot that signals an error condition. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Undershoot occurs when the system is overdamped and the output process variable value falls below the setpoint. FIXME: what happens upon error.

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setUndershootWarnLevelLimit

Set the violation limit for the undershoot that signals an error condition. The axis is expected to reduce error in the controlling process variable as fast as possible in order to achieve a critically damped response. Undershoot occurs when the system is overdamped and the output process variable value falls below the setpoint. FIXME: how is warning signalled?

Parameters:

newVal - is the new value for this limit with units in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

setUsefulTravel

Set the length for the useful axis travel in the forward and reverse directions?

Parameters:

newVal - is the new value for the travel length with unis in meters.

Returns:

S_OK - if value set successfully.

E_INVALIDARG - if value is outside valid numeric range.

E_NOTIMP - if not implemented (or required?).

Interface IAxisMaintenance

This is a placeholder interface to define methods to run when the Axis is in a maintenance operation.

Method Detail

Interface IAxisPositioningServo

Services for position servoing. Methods are used corresponding to the following FSM. There is no internal FSM. Methods are called by an external FSM corresponding to events it processes.

In the table below, external events are in bold font. The internal events are in italic font.  It it the clients responsibility to query the component to determine if an internal event has occurred. Upon detection of internal event, action associated with transition to new state should be executed.

First  State = idle

Beginning State	Event	Ending State	Action
ErrorFollowingPosition	reset	ResettingFollowingPosition	to resolve error or estop
EstoppingFollowPosition	completed	EstoppedFollowPosition	estoppedFollowingPositionAction
EstoppingFollowingPosition	update	EstoppingFollowingPosition	updateEstoppingFollowingPositionAction
FollowingPosition	update	FollowingPosition	updateFollowingPositionAction
FollowingPosition	stop	StoppingFollowingPosition	stopFollowingPositionAction
FollowingPosition	estop	EstoppingFollowingPosition	estopFollowingPositionAction
HoldingPosition	update	HoldingPosition	updateHoldingFollowingPositionAction
HoldingPosition	lose hold	Idle	loseFollowingPositionAction
HoldingPosition	start servoing	FollowingPosition	startFollowingPositionAction
Idle	holdPosition	HoldingPosition	holdFollowingPositionAction
StoppingFollowingPosition	update	StoppingFollowingPosition	updateStoppingFollowingPositionAction
StoppingFollowingPosition	completed	HoldingPosition	updateHoldingFollowingPositionAction
*	error	ErrorFollowingPosition
Resetting	update	Resetting	resettingAxisFollowingPositionAction
Resetting	completed	Idle

The following table represents the states and its associated query method.

State	Query	Comments
errorFollowingPosition	isFollowingPositionError()	Clients should query component each cycle to determine if internal error occurred.
*	isCompleted()	Clients should query component each cycle to determine if internal completion has occurred. Transition to next state, and associated action can be performed.
estoppedFollowPosition	isEstopped()	If estopped is true, then estopping completed. Power can now be disabled.
estoppingFollowPosition	isEstopping()	If true, performing panic stop. ESTOP is mapped into two events, first a hard stop event, then a disable power event after motion has ceased. Estopping may or may not take more than one cycle.
Idle	isIdle()	Following Position idle waiting to start.
followingPosition	isFollowingPosition	Component is following position to generate new motion setpoints.
holdingPosition	isHolding()	Component is maintaining current position setpoint.
Resetting	isResetting()	Component is resetting the following position operation.
stoppingFollowingPosition	isStoppingFollowingPosition()	Component is stopping the following of new position setpoints.

Method Detail

endFollowingPositionAction

Action to be taken when end following torque control. A endPosition event triggers this action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

estopFollowingPositionAction

Action to be taken upon estop transition while under following position control. An estop event causes this action to be undertaken. Emergency but safe shutdown action will be expected.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

holdFollowingPositionAction

Action to be taken on hold transition to start following torque control. A holdPosition event triggers this action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isCompleted

Determine if following positioning control intermediate state is done.

Parameters:

b - return true if done, false if not done.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isEstopped

Determine if following positioning control is now estopped.

Parameters:

b - return true if estopped, false if not estopped.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isEstopping

Determine if following positioning control is estopping.

Parameters:

b - return true if estopping, false if not estopping.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFailed

Query to see if error occurred while servoing.

Parameters:

b - return true if error occurred while disabling, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFollowingPosition

Determine if following positioning control is in following position state.

Parameters:

b - return true if following position state, false if not following position state.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFollowingPositionError

Query to see if an error has occurred during following positioning control cycle.

Parameters:

b - return true if error has occurred, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isHoldingPosition

Determine if following positioning control is holding position.

Parameters:

b - return true if holding position, false if not holding position.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isStoppingFollowingPosition

Determine if following positioning control is stopping following position.

Parameters:

b - return true if stopping following position, false if not stopping following position.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

resetFollowingPositionAction

Action to be taken to reset following position control after error occurred.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

startFollowingAbsPositionAction

Action to start following absoplute position motion control. If Axis FSM is in the holding state, a startFollowingPosition event causes this action to be undertaken and a transition to the FollowingPosition state. The Axis must be homed before following absolute position.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

startFollowingRelPositionAction

Action to start following relative position motion control. If Axis FSM is in the holding state, a startFollowingPosition event causes this action to be undertaken and a transition to the FollowingPosition state.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

stopFollowingPositionAction

Action taken to stop following position motion control. If in the followingPosition state, a stopFollowingPosition event causes this action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateEstoppingFollowingPositionAction

Action to be taken in estopping state while under following position control. Emergency but safe shutdown action will be expected. Time limit?

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateFollowingPositionAction

Action associated to update axis motion in followingPosition state. There is debate as to whether calling this method requires an update event to be sent to the FSM (pure Mealy) or this method is called upon every FSM evaluation (Moore machine), while position servoing state is active, only extra actions would be associated with transitioining into and out of the state.
COM object dependencies include axis sensed state, position control law, axis commanded input and axis commanded output.
This method will get the sensed actual position, and use this as the actual position to the position control law. Will get the commanded position from the axis input command, and use this as the position control law setpoint. The position control law will be updated, and the new output will be read from it. The new output commanded velocity will be set in the AxisCommandOutput object.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateHoldingFollowingPositionAction

Action to be taken while in holding position state under following position control.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateResettingFollowingPositionAction

State-based action update to be taken in reseting following position control after error occurred. Emergency but safe shutdown action will be expected. Time limit?

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateStoppingFollowingPositionAction

Action to be taken in stopping state while under following position control.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

Interface IAxisSensedState

Services for determining actual or sensed axis state. Feedback data is handled by this component which is then shared among all classes requiring sensed data within the AxisModule purview. Determines operating conditions and values derived from raw measured data and other knowledge. For example, reads encoder data and may filter the data if required.

To handle different motion sensor hardware, a different AxisSensedState component would be used to interface to that hardware.

Method Detail

getActualAcceleration

Get the actual setpoint acceleration of the axis.

Parameters:

pVal - pointer to AxisAccelCmd variable, with units in meters per second per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getActualForce

Get the actual setpoint force of the axis.

Parameters:

pVal - pointer to AxisForceCmd variable, with units in Newtons per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getActualPosition

Get the actual setpoint position of the axis.

Parameters:

pVal - pointer to AxisPositionCmd variable, with units in meters. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getActualVelocity

Get the actual setpoint velocity of the axis.

Parameters:

pVal - pointer to AxisVelocityCmd variable, with units in meters per second. Returned value is numeric_limits::quiet_NaN() if undefined or not implemented.

Returns:

S_OK - if successful.

E_FAIL - if implemented but not defined.

E_NOTIMP - if not implemented.

getEnablingPrecondition

Query to determine if the axis has power enabled.

Parameters:

pVal - pointer to boolean variable in which to store enabled flag. True means axis enabled, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

inPosition

Query to determine if the axis has attained desired setpoint, within tolerance.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means axis in position, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

isEnablingPrecondition

isFollowingErrorViolation

Query to determine if following error has occurred. Following error is defined as the difference between the desired process value and the actual process value.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means following error violation, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

isFollowingErrorWarn

Query to determine if approaching following error violation. Following error is defined as the difference between the desired process value and the actual process value.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means following error warning, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

isHardFwdOTravel

Query to determine if the value for the physical hard limit of axis travel in the forward direction has been exceeded.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means following limit exceeded, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

isHardRevOTravel

Query to determine if the value for the physical hard limit of axis travel in the reverse direction has been exceeded.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means following limit exceeded, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

isOverShootViolation

Query to determine if overshoot has occurred. Overshoot occurs when the system is underdamped and the output process variable value exceeds the setpoint.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means overshoot violation, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

isSoftFwdOTravel

Query to determine if the value for the software limit of axis travel in the forward direction has been exceeded.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means following limit exceeded, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

isSoftRevOTravel

Query to determine if the value for the software limit of axis travel in the reverse direction has been exceeded.

Parameters:

pVal - pointer to boolean variable in which to store flag. True means following limit exceeded, false not.

Returns:

S_OK - if successful.

E_FAIL - if not implemented.

Interface IAxisSetup

Services preparatory to operation that can be supplied before arrival of current command values. Includes capability and limits specified through AxisLimits and AxisDyn.

Clients of the Axis would prepare several setup components, and change setups to handle different applications needs, e.g., stiff versus compliant axis control. It has not determined under what states and conditions the setup can be changed.

Method Detail

getCurrentRates

getDynamicRates

getPhysicalLimits

setCurrentRates

setDynamicRates

setPhysicalLimits

Interface IAxisTorqueServo

Services for torque servoing. Methods are used corresponding to the following FSM. There is no internal FSM. Methods are called by an external FSM corresponding to events it processes.

In the table below, external events are in bold font. The internal events are in italic font.  It it the clients responsibility to query the component to determine if an internal event has occurred. Upon detection of internal event, action associated with transition to new state should be executed.

First  State = Idle

Beginning State	Event	Ending State	Action
ErrorFollowingTorque | estoppedFollowTorque	reset	ResettingFollowingTorque	use resetAxisFollowingTorqueAction to resolve error or estop.
EstoppingFollowTorque	completed	EstoppedFollowTorque	estoppedFollowingTorqueAction
EstoppingFollowingTorque	update	EstoppingFollowingTorque	updateEstoppingFollowingTorqueAction
FollowingTorque	update	followingTorque	updateFollowingTorqueAction
FollowingTorque	stop	StoppingFollowingTorque	stopFollowingTorqueAction
FollowingTorque	estop	EstoppingFollowingTorque	estopFollowingTorqueAction
HoldingTorque	update	HoldingTorque	updateHoldingFollowingTorqueAction
HoldingTorque	lose hold	Idle	loseFollowingTorqueAction
HoldingTorque	start servoing	FollowingTorque	startFollowingTorqueAction
Idle	holdTorque	HoldingTorque	holdFollowingTorqueAction
*	error	ErrorFollowingTorque
Resetting	update	Resetting	resettingAxisFollowingTorqueAction
Resetting	completed	Idle
StoppingFollowingTorque	update	StoppingFollowingTorque	updateStoppingFollowingTorqueAction
StoppingFollowingTorque	completed	HoldingTorque	updateHoldingFollowingTorqueAction

The following table represents the states and its associated query method.

State	Query	Comments
ErrorFollowingTorque	isFollowingTorqueError()	Clients should query component each cycle to determine if internal error occurred.
*	isCompleted()	Clients should query component each cycle to determine if internal completion has occurred. Transition to next state, and associated action can be performed.
EstoppedFollowTorque	isEstopped()	If estopped is true, then estopping completed.  Power can now be disabled.
EstoppingFollowTorque	isEstopping()	If true, performing panic stop. ESTOP is mapped into two events, first a hard stop event, then a disable power event after motion has ceased. Estopping may or may not take more than one cycle.
FollowingTorque	isFollowingTorque()	Component is following new torque setpoints to define motion.
HoldingTorque	isHolding()	Component is holding torque, no motion, but is generating new setpoints.
Idle	isIdle()	Following Torque component idle waiting to start.
Resetting	isResetting()	Component is resetting the following Torque operation.
StoppingFollowingTorque	isStoppingFollowingTorque()	Component will stop following torque motion, and return to holding torque.

Method Detail

endFollowingTorqueAction

Action to be taken when end following torque control. A end event triggers this action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

estopFollowingTorqueAction

Action to be taken on estop transition while under following torque control. Emergency but safe shutdown action will be expected. Time limit? An estop event triggers this action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

holdFollowingTorqueAction

Action to be taken on hold transition to start following torque control. A holdTorque event triggers this action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isCompleted

Determine if following torque control is done.

Parameters:

b - return true if done, false if not done.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isEstopped

Query to see if following torque control mode has completed estopping.

Parameters:

b - return true if estopped, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isEstopping

Query to see if following torque control mode is estopping.

Parameters:

b - return true if estopping, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFailed

Query to see if error occurred while servoing.

Parameters:

b - return true if error occurred while disabling, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFollowingTorque

Query to see if performing motion under following torque control.

Parameters:

b - return true if following torque state, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFollowingTorqueError

Query to see if error has occurred during following torque control.

Parameters:

b - return true if error has occurred, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isHoldingTorque

Query to see if holding motion under following torque control.

Parameters:

b - return true if holding motion under torque control, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isStoppingFollowingTorque

Query to see if in stopping following torque motion.

Parameters:

b - return true if stopping following torque motion, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

resetFollowingTorqueAction

Action to be taken to reset following torque control after error occurred.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

startFollowingTorqueAction

Action to start following torque motion control. If Axis FSM is in the holdingTorque state, a startFollowingTorque event causes this action to be undertaken and a transition to the FollowingTorque state.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

stopFollowingTorqueAction

Action taken to stop following torque motion control. If in the following torque state, a stopFollowingTorque event causes this action to be undertaken, and the next state to holdingTorque state.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateEstoppingFollowingTorqueAction

Action to be taken while in estopping state under following torque control. Emergency but safe shutdown action will be expected. Time limit?

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateFollowingTorqueAction

Action to update axis motion under in followingTorque state. Action associated to a state precludes the need for an update event while in the following torque state to cause an update action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateHoldingFollowingTorqueAction

Action to be taken while in holding torque state under following torque control.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateResettingFollowingTorqueAction

Action to be taken while in resetting error state under following torque control.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateStoppingFollowingTorqueAction

Action to be taken while in stopping state under following torque control.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

Interface IAxisVelocityServo

Services for velocity servoing. Methods are used corresponding to the following FSM. There is no internal FSM. Methods are called by an external FSM corresponding to events it processes.

In the table below, external events are in bold font. The internal events are in italic font.  It it the clients responsibility to query the component to determine if an internal event has occurred. Upon detection of internal event, action associated with transition to new state should be executed.

First  State = idle

Beginning State	Event	Ending State	Action
ErrorFollowingVelocity | EstoppedFollowVelocity	reset	ResettingFollowingVelocity	use resetAxisFollowingVelocityAction to resolve error or estop.
EstoppingFollowVelocity	completed	EstoppedFollowVelocity	estoppedFollowingVelocityAction
EstoppingFollowingVelocity	update	EstoppingFollowingVelocity	updateEstoppingFollowingVelocityAction
FollowingVelocity	update	FollowingVelocity	updateFollowingVelocityAction
FollowingVelocity	stop	StoppingFollowingVelocity	stopFollowingVelocityAction
FollowingVelocity	estop	EstoppingFollowingVelocity	estopFollowingVelocityAction
HoldingVelocity	update	holdingVelocity	updateHoldingFollowingVelocityAction
HoldingVelocity	lose hold	Idle	loseFollowingVelocityAction, either enabled or change servoing mode
HoldingVelocity	start servoing	followingVelocity	startFollowingVelocityAction
Idle	holdVelocity	HoldingVelocity	holdFollowingVelocityAction
StoppingFollowingVelocity	update	StoppingFollowingVelocity	updateStoppingFollowingVelocityAction
StoppingFollowingVelocity	completed	HoldingVelocity	updateHoldingFollowingVelocityAction
*	error	ErrorFollowingVelocity
Resetting	update	Resetting	resettingAxisIFollowingVelocityAction
Resetting	completed	Idle

The following table represents the states and its associated query method.

State	Query	Comments
errorFollowVelocity	isFollowingVelocityError()	Clients should query component each cycle to determine if internal error occurred.
*	isCompleted()	Clients should query component each cycle to determine if internal completion has occurred. Transition to next state, and associated action can be performed.
estoppedFollowVelocity	isEstopped()	If estopped is true, then estopping completed. Power can now be disabled.
estoppingFollowVelocity	isEstopping()	If true, performing panic stop. ESTOP is mapped into two events, first a hard stop event, then a disable power event after motion has ceased. Estopping may or may not take more than one cycle.
Idle	isIdle()	Idle, waiting to start.
followingVelocity	isFollowingVelocity	Component is following velocity setpoint to generate motion.
holdingVelocity	isHolding()	Component is holding the current velocity setpoint.
Resetting	isResetting()	Component is resetting the following Velocity operation.
stoppingFollowingVelocity	isStoppingFollowingVelocity()	Component is stopping the velocity following motion.

Method Detail

endFollowingVelocityAction

Action to be taken to upon loss of following velocity control. An endVelocity event causes this transition action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

estopFollowingVelocityAction

Action to be taken to estop while under following velocity control. An estop event causes this transition action to be undertaken. Emergency but safe shutdown action will be expected.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

holdFollowingVelocityAction

Action to be taken to hold to begin following velocity control. An holdVelocity event causes this transition action to be undertaken.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isCompleted

Determine if following velocity intermediate (...ing) control state is done.

Parameters:

b - return true if done, false if not done.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isEstopped

Query to see if following velocity control mode has completed estopping.

Parameters:

b - return true if estopped, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isEstopping

Query to see if following velocity control mode is estopping.

Parameters:

b - return true if estopping, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFailed

Query to see if error occurred while servoing.

Parameters:

b - return true if error occurred while disabling, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFollowingVelocity

Query to see if in following velocity state.

Parameters:

b - return true if following velocity, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isFollowingVelocityError

Query to see if an error has occurred during following velocity control cycle.

Parameters:

b - return true if error has occurred, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isHoldingVelocity

Query to see if in holding following velocity state.

Parameters:

b - return true if holding following velocity, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

isStoppingFollowingVelocity

Query to see if in stopping following velocity motion.

Parameters:

b - return true if stopping following velocity motion, false if not.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

resetFollowingVelocityAction

Action to be taken to reset when error occurred when in following velocity control.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

startFollowingVelocityAction

Action to start following velocity motion control. If Axis FSM is in the holdingVelocity state, a startFollowingVelocity event causes this action to be undertaken and a transition to the FollowingVelocity state.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

stopFollowingVelocityAction

Action taken to stop following velocity motion control. If in the followingVelocity state, a stopFollowingVelocity event causes this action to be undertaken, and the next state is the holdingVelocity state.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateEstoppingFollowingVelocityAction

Action to be taken while in estopping state while under following velocity control. Emergency but safe shutdown action will be expected.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateFollowingVelocityAction

Action to update axis motion in follow velocity state. An update event causes this action to be undertaken.
COM object dependencies include axis sensed state, position control law, axis commanded input and axis commanded output.
Will get the sensed actual velocity from the AxisSensedState object. This actual velocity will be set within the velocity ControlLaw object. Next, the commanded velocity from the AxisCommandedInput object, will be used so set the velocity ControlLaw setpoint. The velocity ControlLaw will be updated, and the new output acceleration will be read from velocity ControlLaw. The new commanded acceleration will be set in the AxisCommandedOutput object.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateHoldingFollowingVelocityAction

Action to be taken while in holding velocity state under following velocity control. Emergency but safe shutdown action will be expected.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateResettingFollowingVelocityAction

Action to be taken while in resetting state while under following velocity control. Emergency but safe shutdown action will be expected.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

updateStoppingFollowingVelocityAction

Action to be taken while in stopping state while under following velocity control.

Returns:

S_OK - if successful.

E_FAIL - if unsucessful.

Interface IAxisSupervisor

The IAxisSupervisor interface is defined within the Axis Module in order to allow Axis modules to be deployed in standalone Axis operation under manual control. For autonomous control, the axis is expected to have an Axis Group module managing it and providing it trajectory-based setpoints. The reason this interpolator functionality was not just assimilated as part of the Axis Group was that it was not considered practical to expect vendors of Axis modules to include a complete realization of Axis Group module interfaces in deployment of "One-Axis" Axis Group - even if these interfaces were "stubbed" out. It was felt that if an Axis and Supervisor were bundled together, it would be a more practical commercial packaging. Axis bundled as part of a larger control system could assume that his functionality has been subsumed as part of the Axis Group module responsibility. (This is the current thinking.)

Realizations of Axis Supervisor handle single-axis trajectory responsibilities by managing a collection of interpolation "plugs", including homing, continuous jogging, incremental positioning and absolute positioning. Interpolation is achieved by coordinating the servoing activity of an Axis via an IAxis reference. The IAxisSupervisor interface defines a container mechanism to provide a means of storing interpolated-motion component references and then providing access to the interpolated-motion component references.

An IAxisSupervisor realization uses a FSM to coordinate among the different interpolated-motion control strategies, and then manages a selected interpolation strategy to achieve axis motion based on the FSM. Each control strategy has an associated "pluggable" Axis motion control component that implements the control strategy. See also the associated interpolated-motion control component interfaces:

• IAxisAbsolutePos
• IAxisHoming
• IAxisIncrementPos
• IAxisJogging
• IAxisRates

IAxisSupervisor coordinates between the different servoing motion control strategies by means of a FSM. Based on the selected motion control strategy, a different plug is used to control the motion. (See the OmacModule for details on component realization and how the AxisSupervisor and each plug are connected.) These interpolated-motion plugs could provide their own interpolation service or could be share an underlying profile generator as illustrated in the following Figure Axis .

Behavior

An IAxisSupervisor component manages a set of interpolated-motion control components that implement basic single-axis motion trajectory strategies. Trajectory motion consists of a sequence of desired positions, velocities, and accelerations of an axis over time. An Axis Supervisor generates a time sequence of intermediate desired configurations for an axis that matches the given rates to attain the desired position, velocity or acceleration goal. For example, to achieve continuous jogging, the IAxisJogging component would place the axis in followingAbsPosition seroving and then update new positions for the axis to follow based on attaining the jogging velocity. All interpolated-motion control components must comply with underlying Axis state. Thus, for example, moving an axis to an absolute position could not be done until the Axis positioning has been calibrated by a homing sequence.

IAxisSupervisor coordinates between the different servoing motion control strategies by means of a FSM, including events, states, and state transitions, defined by the following diagram:

Switching between interpolated motion control strategies is achieved by sending events to the Axis FSM. The FSM itself is hidden, but the Axis interface provides methods for event propagation and state query. The event propagating methods that cause FSM state transitions, which may result in changing control strategies, are: disableAxis, enableAxis, estopAxis, home, jog, resetAxis, and stopAxis. The relationship between state, events, next state and action associated with the state transition in the FSM is given in the following table, where XXX is a member of {AbsPositioning, Homing, Jogging, Incrementing}.

First State = Disabled

Beginning State	Event	Ending State	Action
Disabled	enable()	Enabling	IAxisEnabling::enablingAction
Disabled	hardStop()	HardStopping	IAxisDisabling::hardStoppingAction
Enabled	hardStop()	HardStopped	IAxisErrorAndEnable::hardStopAction
HardStopped	reset()	Disabled	IAxisResetting::resetHardStopAction
Enabling	completed	Enabled	IAxisEnabling::enabledAction
Enabled	startXXX()	XXX	IAxisXXX::startXXXAction
XXX	stop()	XXXStopping	IAxisXXX::stopXXXAction
XXX	hardStop()	XXXHardStopping	IAxisXXX::hardStoppingXXXAction
XXX	completed	Enabled	IAxisXXX::finishedXXXAction except Jogging which can only be stopped
XXXStopping	completed	Enabled	n/a
XXXHardStopping	completed	HardStopped	n/a
XXX	(state update)	XXX	IAxisXXX::updateXXXAction
XXXStopping	(state update)	XXXStopping	IAxisXXX::updateXXXStoppingAction
XXXAbnormalStopping	(state update)	XXXAbnormalStopping	IAxisXXX::updateXXXAbnormalStoppingAction
XXXHardStopping	(state update)	XXXHardStopping	IAxisXXX::updateXXXHardStoppingAction

The State Definitions and Query Table supplements the behavior model described above by the state table. This table provides a detailed description of each state and identifies the query mechanism for determining if the Axis Interpolation component is in that state. The Axis Interpolation FSM states, state description, and query methods is described in the following table where XXX is a member of {AbsPositioning, Homing, Jogging, Incrementing}.

State	Definition	Query for State
AbsolutePositioning	Module is moving to an absolute position.	isAbsolutePositioning()
Disabled	Module is Disabled. Connections and IO points are not enabled.	isDisabled()
Enabled	Module is enabled. Power on to amplifiers.	isEnabled()
HardStopped	Module is HardStopped. Power to equipment is off.	isHardStopped()
Homing	Module is Homing.	isHoming()
IncrementingPosition	Module is incrementally Jogging.	isIncrementing()
Jogging	Module is under Jogging control.	isJogging()
Ready	Module is ready. Part of outer OMAC API state definition.	isReady()
Resetting	Module is resetting hard or abnormal stop or resolving fault.	isResetting()
StoppingXXX	Module is stopping XXX.	isStoppingXXX()
AbnormalStoppingXXX	Module is abnormal stopping XXX.	isAbnormalStoppingXXX()
HardStoppingXXX	Module is hard stopping XXX.	isHardStoppingXXX()

The Axis interpolator plugs provide a packaging mechanism for encapsulating the FSM functionality for a specific service: homing, jogging, incremental jogging, or absolute positioning. These plugs derive from IOmac so that they are connectable and could provide event service if necessary. To simplify develop and integration these plugs are simple. Each plug provides event and activity methods for transitioning and updating the varying states motion control in a generic FSM: start, stop, update, hardstop, abnormalstop, fail and completion. The Axis Supervisor controls the life of the plug by invoking the appropriate method given the current state of the FSM. For example, to start a homing sequence, the method startHomingAction is invoked on the AxisHoming plug. Subsequently, for each cycle the AxisSupervisor is in the Jogging state, the method updateAxisHomingAction is invoked until the isCompleted method returns true. Several modes of stopping are defined for each plug to accommodate different circumstances for velocity servoing to zero. The stopping modes that have been defined are:

• normal stop - stop under current commanded deceleration limits.
• hard stop - hard or panic stop means exceed any limits, break any rules, stop as soon as possible.
• abnormal stop - safe stop as quickly as possible, save the hardware. This case typically involves some detection of an internal failure or safety violation that can be resolved. As examples of this stopping mode, suppose it has been detected that someone has entered the safety area or that someone has opened the coolant door in a CNC. These cases would cause an abnormal stop. Motion can resume by invoking a resettingAction.

Appropriate states, events and actions are associated with each state. The event stopping methods are: hardStopXXXAction, abnormalXXXStopAction, or stopXXX where XXX indicates the functionality provided by the plug. The stopping states are: hardStopping, hardStopped abornmalStopping, abornmalStopped, normalStopping and normalStopped. The stopping state queries are: isHardStopping, isHardStopped, isAbornmalStopping, isAbornmalStopped, isNormalStopping and isNormalStopped. as well as isStopping and isStopped to detect any stopping state. The updating actions are: updateHardStopping, updateAbornmalStopping, and updateStopping .

Estop is not a separate stopping mode, instead it is Resident Task that maps an Estop event into several events that can be tailored to accommodate domain-specific safety codes. For example, estop could be mapped into "stop as fast on each limit using the software limits as configured by OEM, put brakes on, cut power", or "cut power after certain time limit" depending on pertinent safety codes. To allow for the different domain-specific forms of estop, this functionality has been abstracted into a Resident Task and would use either a hard or abnormal stop to a achieve safe emergency stop as predicated by the domain-specific safety code.

As a final note, it is not encumbant on the system integrator or end-user to develop the Axis interpolator plugs. It would be expected that preconfigured Axis interpolator plugs would be provided by the axis vendor so that default functionality is available. End-users would only be expected to develop a new plug in response to satisfying some special need.