EventMgr Objects
Introduction
An EventMgr object manages the collection and distribution of event messages from the controller to the host. Events include normal motion completion, motor limits, fault conditions, data recorder buffer full, network node faults, etc. The EventNotify methods enable the application to request host notification for specified events, while ignoring other events. The EventMgr receives the event and then distributes the event via the Notify object to the tasks that are waiting for the event. Events that are faults are latched; the fault condition and the event must be cleared before the event can be generated again.
To collect events, the EventMgr must be serviced via the mpiEventMgrService(...) routine. The EventMgr can be polled by periodically by calling the mpiEventMgrService(...) routine or can be placed in an interrupt service routine. For your convenience, there is an apputil module that provides a serviceCreate(...) function that creates an EventMgr service routine for Windows OSs. The Service thread can be configured for polling or interrupts. Sources for the apputil module are included with the software distribution, so you can port it to other OSs.
The controller has a circular buffer which holds up to 128 event messages. If the EventMgr is not serviced within 128 events, event messages will be overwritten as new events occur. For interrupt driven EventMgr service threads, this is not an issue. For a polling EventMgr service thread, this could be an issue if the service thread does not have enough CPU cycles. In the worst-case scenario, events could be lost.
The best way to avoid lost events is to use an interrupt driven EventMgr service routine. If you're using polling, the next best thing is to make sure the EventMgr services the events at a high enough rate to avoid controller message buffer rollover. Determining the worst case EventMgr service latency and the maximum event message rate can be tricky. A simple method is to estimate the event message frequency and make sure each EventMgr can poll at least once for every 32 events (safety factor of 4). If you know that some events occur more frequently than others, then you may want to increase the polling frequency for EventMgrs that process the most frequent events and decrease the polling frequency for EventMgrs that process less frequently.
Generally, use only one EventMgr in your application. Do not use multiple interrupt driven EventMgr service threads to collect the same event. Suppose you configure an EventMgr to service Motion Done events from MS 0 and you configure another EventMgr with MEIEventMgrServiceConfig.allProcesses = TRUE. If one EventMgr collects the event message and acknowledges the interrupt before the other EventMgr can respond, it will miss the event.
If you want to monitor ALL events with MEIEventMgrServiceConfig.allProcesses = TRUE, then use polling (not interrupts). See the sample app EventLog.c for an example.
WARNING
Resetting the motion controller will cause any exising EventMgr objects to become unsynchronized with the motion controller, causing it to miss events. It is recommended that after a controller reset, an application should delete and re-create the EventMgr and Service objects. Then the application should reconnect all Notify objects to the EventMgr and re-enable event reporting by calling ObjectEventNotifySet.
| Error Messages |
Methods
| Create, Delete, Validate Methods | ||
| mpiEventMgrCreate | Create EventMgr object | |
| mpiEventMgrDelete | Delete EventMgr object | |
| mpiEventMgrValidate | Validate EventMgr object | |
| Configuration and Information Methods | ||
| mpiEventMgrConfigGet | Get EventMgr config | |
| mpiEventMgrConfigSet | Set EventMgr config | |
| mpiEventMgrEvent | Request event notification for all Notify objects on EventMgr's list | |
| meiEventMgrServiceConfigGet | Get processes that EventMgr will service | |
| meiEventMgrServiceConfigSet | Set processes that EventMgr will service | |
| Action Methods | ||
| mpiEventMgrFlush | Flush pending EventMgr events | |
| mpiEventMgrService | Get list of all pending asynchronous events | |
| Relational Methods | ||
| List Methods- for Control Objects | ||
| mpiEventMgrControl | Return handle of indexth Control object in list | |
| mpiEventMgrControlAppend | Append Control's handle to list | |
| mpiEventMgrControlCount | Count the number of Control objects associated with EventMgr (in list) | |
| mpiEventMgrControlFirst | Return handle to first Control object in list | |
| mpiEventMgrControlIndex | Return the index of a Control object in list | |
| mpiEventMgrControlInsert | Insert Control handle into list | |
| mpiEventMgrControlLast | Get handle to last Control object in list | |
| mpiEventMgrControlListGet | Get list of Control objects associated with EventMgr | |
| mpiEventMgrControlListSet | Create a list of Control objects associated with EventMgr | |
| mpiEventMgrControlNext | Get handle to next Control object in list | |
| mpiEventMgrControlPrevious | Get handle to previous Control object in list | |
| mpiEventMgrControlRemove | Remove a Control object's handle from list | |
| List Methods- for Notify Objects | ||
| mpiEventMgrNotify | Return handle to a Notify object associated with EventMgr | |
| mpiEventMgrNotifyAppend | Append Notify object to list | |
| mpiEventMgrNotifyCount | Return number of Notify objects in list | |
| mpiEventMgrNotifyFirst | Get first Notify object in list | |
| mpiEventMgrNotifyIndex | Get index value for a Notify object in list | |
| mpiEventMgrNotifyInsert | Place a Notify object after another Notify object in list | |
| mpiEventMgrNotifyLast | Get handle to the Notify object that is last on the list | |
| mpiEventMgrNotifyListGet | Get a list of Notify objects | |
| mpiEventMgrNotifyListSet | Create a list of Notify objects | |
| mpiEventMgrNotifyNext | Get the Notify object just after notify in list | |
| mpiEventMgrNotifyPrevious | Get the Notify object just before notify in list | |
| mpiEventMgrNotifyRemove | Remove a Notify object from list | |
Data Types
| MPIEventMgrConfig | ||
| MPIEventMgrMessage | ||
| MEIEventMgrServiceConfig |