 |
|
|
| |
|
|
This page gives an overview of the available events. Plug-ins with the "monitor" capability (see Required Specifications) receive an event by way of calling the API function MV_TryGetEvent(), optionally retrieving data from the parameters associated with that event using MV_Event_GetParameter() (for scalar-valued parameters) or MV_Event_Tuple_GetParameter() (for tuple-valued parameters), and finally disposing of the memory held by the event using MV_Event_Clear(). Failing to retrieve and clear events in a plug-in with the "monitor" capability will effectively leak the memory occupied by the events to a certain point before silently dropping events.
For more detailed information about the events and their respective parameters refer to the reference documentation of mv_event_def.h.
In addition to the event-specific parameters that are listed in the following subsections, each event carries the following three parameters:
| Parameter |
|---|
| MV_PARAM_ACTION_ID: UInt32 |
This parameter identifies the action that caused the event. Plug-ins can use this information to verify that a certain behavior of MERLIC is due to a particular action they may have been sent previously. The action ID is assigned by MERLIC. It is returned in the final parameter of the MV_QueueAction() function and is guaranteed to be unique. Some events may be caused by internal actions which are sent by MERLIC itself rather than any of the plug-ins. |
| MV_PARAM_ACTION_USER_ID: any scalar value type |
This parameter is available only if a parameter of the same name has been set on the action that caused the event. The action user ID may hold any scalar type and its value must be retrieved using the correct API function to match the type to which it was set. If no action user ID had been set, an attempt to retrieve it will result in the return code MV_CODE_UNSET_PARAM. See the documentation of MV_PARAM_ACTION_USER_ID as an action parameter in the topic Available Actions for further information. |
| MV_PARAM_PLUGIN_ID: UInt32 |
This parameter identifies the plug-in which sent the action that caused the event. A value of 0 indicates that the cause of the event is internal or was triggered spontaneously by MERLIC rather than being in response to any particular trigger by the plug-in. Plug-in IDs from 1 onwards are assigned by the Communicator to its plug-ins in the order of registration. IDs from 1000 onwards are reserved for the existing MERLIC RTE modules for communication devices where 1000 corresponds to |
This event notifies the plug-in about a change of the MERLIC state. It gives information about the previous state and the new state. This transition can be used by the plug-ins to detect whether MERLIC RTE was restarted because it will automatically change from a "null" state to the "Preoperational" state on startup.
| Parameter |
|---|
| MV_PARAM_STATE_ACTION_CAUSE: UInt32 |
This parameter represents the numeric value of the enum MVActionType_t corresponding to the type of the action which triggered the state change, i.e., the action which is referenced by the action ID as obtained from MV_PARAM_ACTION_ID. This information may help plug-ins in deciding in which way they wish to react to a state change, particularly since some state changes, e.g., from "Ready" to "Initialized", may be caused by several different actions, e.g., PrepareRecipe or UnprepareRecipe. |
| MV_PARAM_STATE_FROM_STATE: UInt32 |
This parameter represents the value corresponding to the state MERLIC has transitioned from. In case of a self-transition, which is allowed in the "Halted" and "Preoperational" state, the parameter value corresponds to the value of the parameter |
| MV_PARAM_STATE_TO_STATE: UInt32 |
This parameter represents the value corresponding to the state MERLIC has transitioned to. In case of a self-transition, which is allowed in the "Halted" and "Preoperational" state, the parameter value corresponds to the value of the parameter |
Both parameters are numeric values of either the entries in the enum type MVVisionState_t, or the bitwise conjunction between eMVVisionState_Operational and any of the values in either MVAutomaticModeState_t or MVFrontendAccessModeState_t.
For example, the "Ready" state, a sub-state of "Operational", would be encoded as eMVVisionState_Operational | eMVAutomaticModeState_Ready, or 0x22.
This event is sent if the PrepareRecipe action has been processed. It notifies the plug-in that the specified recipe has been loaded.
| Parameter |
|---|
| MV_PARAM_RECIPE_ID: String |
This parameter represents the recipe ID of the recipe that has been prepared. While the IDs of MERLIC recipes are numeric, this parameter requires their string representations, e.g. "0", "1". |
This event notifies the plug-in that the recipe has been unloaded and the respective MERLIC Vision App has been closed, i.e., due to either an UnprepareRecipe action or due to a PrepareRecipe action while another recipe was still loaded. The RecipeUnprepared event only indicates that the unloading commenced and the formerly prepared recipe is no longer available for execution.
| Parameter |
|---|
| MV_PARAM_RECIPE_ID: String |
This parameter represents the recipe ID of the recipe that is no longer prepared. While the IDs of MERLIC recipes are numeric, this parameter requires their string representations, e.g. "0", "1". |
This event is emitted whenever the image acquisition from all ISM image sources is finished. The image processing job may still be in progress at that time. "AcquisitionDone" should be expected once for a "SingleExecution" job and multiple times for a "ContinuousExecution" job. The corresponding job ID can be retrieved from the event. "AcquisitionDone" is only supported for recipes which use the new Image Source Management (ISM) and will not be emitted for MVApps which contain the tool "Acquire Image from Camera".
| Parameter |
|---|
| MV_PARAM_JOB_ID: UInt32 |
| This parameter represents the ID of the job which completed the image acquisition. |
| MV_PARAM_ACQ_DURATION_MILLIS: Double |
This parameter represents the total duration of the image acquisition of the present execution. It is given in milliseconds with the fractional part indicating submillisecond resolution. The duration encompasses the (potentially parallel or repeated) acquisition from one or more image sources, according to the active configuration, including the time it takes to transfer the images from the camera, as well as any waiting times incurred due to hardware-triggered cameras, delays, and synchronization between image sources as prescribed by the acquisition sequence. In continuous executions, the images themselves may have already been captured prior to the start of the execution, potentially during a previous execution, depending on camera configuration. For this reason, the acquisition duration may be shorter than the actual time spent to capture the image, including the exposure time. |
This event is sent when the result of an execution has been made available by MERLIC. It is emitted independently from the MERLIC RTE state machine and you should not rely on any particular order relative to other events. Use the JobStarted, Ready, or StateChanged events to synchronize with the state machine instead.
| Parameter |
|---|
| MV_PARAM_RECIPE_ID: String |
This parameter represents the recipe ID of the recipe that was executed to obtain the result. While the IDs of MERLIC recipes are numeric, this parameter requires their string representations, e.g. "0", "1". |
| MV_PARAM_JOB_ID: UInt32 |
| This parameter represents the ID of the job which this result was obtained from. The job IDs are also specified in the JobStarted and Ready events. |
| MV_PARAM_RESULT_ID: UInt32 |
| This parameter represents the ID of the individual result. It is assigned to the result once it is available and can be used to recall the result at a later point. |
| MV_PARAM_RESULT_STATE: UInt32 |
This parameter represents the numeric value of the enum MVResultState_t and indicates the state of completion of the result. Currently, MERLIC only delivers complete results. |
| MV_PARAM_RESULT_CONTENT: MVTuple_t |
This parameter represents the actual result tuple. The number and type of the elements contained inside correspond to the MVApp Results output by the MERLIC Vision App referenced in the recipe that was executed to obtain the result. See the topic Result Format for a description of the conventions employed. |
| MV_PARAM_ACQ_DURATION_MILLIS: Double |
This parameter represents the total duration of the image acquisition of the present execution. It is given in milliseconds with the fractional part indicating submillisecond resolution. The duration encompasses the (potentially parallel or repeated) acquisition from one or more image sources, according to the active configuration, including the time it takes to transfer the images from the camera, as well as any waiting times incurred due to hardware-triggered cameras, delays, and synchronization between image sources as prescribed by the acquisition sequence. In continuous executions, the images themselves may have already been captured prior to the start of the execution, potentially during a previous execution, depending on camera configuration. For this reason, the acquisition duration may be shorter than the actual time spent to capture the image, including the exposure time. |
| MV_PARAM_PROC_DURATION_MILLIS: Double |
This parameter represents the duration of the data processing to produce the result of the present execution. It is given in milliseconds with the fractional part indicating submillisecond resolution. The duration encompasses the image processing according to the recipe, but it does not include the acquisition of the images from image sources according to the active configuration. |
| MV_PARAM_EXEC_START_TIMESTAMP: String |
This parameter represents the time when the execution of the recipe which produced the result started. The timestamp is given in ISO-8601 / RFC 3339 format. In continuous executions, this marks a rather arbitrary time at which the vision system starts to wait for images to be transferred from the cameras' buffer; the images themselves may have already been captured prior to this point in time, potentially during a previous execution, depending on camera configuration. |
| MV_PARAM_EXEC_END_TIMESTAMP: String |
| This parameter represents the time when the execution of the recipe which produced the result ended. The timestamp is given in ISO-8601 / RFC 3339 format. |
| MV_PARAM_MEAS_ID: String |
This parameter represents the measurement ID that was defined for the inspection when calling StartSingleJob or StartContinuous, respectively. If no measurement ID was specified for the execution, the value will be empty. It is not guaranteed that measurement IDs are unique as they are provided by the caller. |
| MV_PARAM_PART_ID: String |
| This parameter represents the part ID that was defined for the part to be inspected when calling StartSingleJob or StartContinuous, respectively. When multiple inspections were carried out for the same part, they share the same part ID but they have different associated measurement IDs. If no part ID was specified for the execution, the value will be empty. |
This event notifies the plug-in that MERLIC returned to the "Ready" state after an execution finished and carries the job ID of said execution. It is neither emitted when MERLIC initially enters "Ready" after preparing a new recipe nor when an execution finishes due to a call to Halt or Reset.
| Parameter |
|---|
| MV_PARAM_JOB_ID: UInt32 |
| This parameter represents the ID of the job which was completed prior to becoming "Ready" again. |
This event notifies the plug-in that a new execution has started and carries its associated job ID. Thus, this event may be waited for by the caller of StartSingleJob to retrieve the job ID of the job they just started such that they know which job ID to look for in forthcoming ResultReady events.
| Parameter |
|---|
| MV_PARAM_JOB_ID: UInt32 |
This parameter represents the ID of the job that has been started by the action which caused this event and is referenced by the action ID stored as parameter MV_PARAM_ACTION_ID. |
| MV_PARAM_RECIPE_ID: String |
| This parameter represents the ID of the recipe for which the job that has been started is being executed. |
| MV_PARAM_IS_CONTINUOUS_JOB: Bool |
| This parameter indicates whether the job that has been started is a single job (false) or a continuous job (true). |
| MV_PARAM_START_PARAMS: Tuple |
| This parameter holds the job parameter tuple of the job that has been started. If the tuple is empty, the recipe's default input parameters are used to execute the job. Different job parameters can be passed when setting MV_PARAM_START_PARAMS on a StartSingleJob or StartContinuous action. The respective values will be reflected in the JobStarted event if they are accepted by the vision system. The job parameters may be rejected by the vision system if their number and data types do not match the recipe's interface. In this case, the vision system may still execute the job with the recipe's default parameters and this would manifest itself here by yielding an empty tuple. |
| MV_PARAM_MEAS_ID: String |
This parameter represents the measurement ID that was defined for the inspection when calling StartSingleJob or StartContinuous, respectively. If no measurement ID was specified for the execution, the value will be empty. It is not guaranteed that measurement IDs are unique as they are provided by the caller. |
| MV_PARAM_PART_ID: String |
| This parameter represents the part ID that was defined for the part to be inspected when calling StartSingleJob or StartContinuous, respectively. When multiple inspections were carried out for the same part, they share the same part ID but they have different associated measurement IDs. If no part ID was specified for the execution, the value will be empty. |
This event is sent if an error occurred. It gives information about the error code and an error message.
Depending upon the severity of the error, this event may be accompanied by a state change to the "Error" state if the error condition is deemed irrecoverable or if the internal state of MERLIC or that of any of the prepared recipes became corrupted.
| Parameter |
|---|
| MV_PARAM_ERROR_CAUSE: UInt32 |
This parameter represents the numeric value of the enum MVActionType_t corresponding to the type of the action which caused the Error event, i.e., the action which is referenced by the action ID as obtained from MV_PARAM_ACTION_ID. This information is useful since the same error code, e.g., code 4 indicating an invalid recipe ID, may be caused by several different types of actions, e.g., PrepareRecipe or StartSingleJob. |
| MV_PARAM_ERROR_MESSAGE: String |
| A human-readable string representation of the error condition. |
| MV_PARAM_ERROR_CODE: UInt32 |
| The error code. |
The error codes and messages correspond to the ones that are defined for MERLIC's plug-in for Hilscher PCI Cards.
See the description of ActionResponse in the MERLIC manual for a list of the possible error causes, that is, the error codes and the respective error messages.
This event is sent only once when the execution of the plug-in is stopped. It is guaranteed to be the final event that plug-ins can receive by way of calling MV_TryGetEvent(). Unlike all of the other events, the Shutdown event is not sent by MERLIC RTE but is enqueued by the host process of the plug-in itself after severing its connection to MERLIC RTE when shutting down and just prior to invoking the MVStop function of the plug-ins. Beyond that, this event does not carry any parameters.
Plug-ins with the "monitor" capability will typically have a dedicated thread which receives events from the queue and reacts to them. The Shutdown event thus serves to indicate that the plug-in has completely drained its event queue and encountered the final event; it can thus break from its event loop and terminate the event thread.
 |
|
| MERLIC 5.7.1 - API Version 2.2.2 | © 2025 MVTec Software GmbH - All rights reserved |