flex_wait_on_event |
Wait on Event
Usage
status = flex_wait_on_event(u8 boardID, u8 resource, u16 waitType, u16 condition, u16 mustOn, u16 mustOff, u16 matchType, u16 timeOut, u8 returnVector);
Purpose
Inserts a conditional wait in a program.
Parameters
| Name | Type | Description |
|---|---|---|
| boardID | u8 | assigned by Measurement & Automation Explorer (MAX) |
| resource | u8 | axis control or other resource |
| waitType | u16 | selector for type of wait |
| condition | u16 | qualifying condition to end the wait |
| mustOn | u16 | bitmap of bits that must be True |
| mustOff | u16 | bitmap of bits that must be False |
| matchType | u16 | selector for type of match required |
| timeOut | u16 | timeout value in 100 millisecond increments |
| returnVector | u8 | destination for the return data |
Parameter Discussion
resource is the axis control or other resource involved in the condition.
waitType is the selector for the type of wait to perform.
| waitType Constant | waitType Value |
| NIMC_WAIT | 0 |
| NIMC_WAIT_OR | 1 |
NIMC_WAIT_OR allows you to combine multiple, unrelated wait conditions into one wait where the program is waiting for condition 1 OR condition 2 OR condition 3 and so on.
condition is the qualifying condition to end the wait.
| condition Constant | condition Value | Valid resource |
|---|---|---|
| NIMC_CONDITION_HOME_FOUND | 7 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_INDEX_FOUND | 8 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_HIGH_SPEED_CAPTURE | 9 | NIMC_AXIS_CTRL (0) or NIMC_ENCODER_CTRL (0x20) |
| NIMC_CONDITION_POSITION_BREAKPOINT | 10 | NIMC_AXIS_CTRL (0) or NIMC_ENCODER_CTRL (0x20) |
| Reserved | 11 | N/A |
| NIMC_CONDITION_VELOCITY_THRESHOLD | 12 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_MOVE_COMPLETE | 13 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_PROFILE_COMPLETE | 14 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_BLEND_COMPLETE | 15 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_MOTOR_OFF | 16 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_HOME_INPUT_ACTIVE | 17 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_LIMIT_INPUT_ACTIVE | 18 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_SOFTWARE_LIMIT_ACTIVE | 19 | NIMC_AXIS_CTRL (0) |
| NIMC_CONDITION_PROGRAM_COMPLETE | 20 | program |
| NIMC_CONDITION_IO_PORT_MATCH | 21 | I/O port 1–8 |
| NIMC_CENTER_FOUND | 22 | NIMC_AXIS_CTRL (0) |
| NIMC_FORWARD_LIMIT_FOUND | 23 | NIMC_AXIS_CTRL (0) |
| NIMC_REVERSE_LIMIT_FOUND | 24 | NIMC_AXIS_CTRL (0) |
 |
Note Conditions 0 through 6 are not applicable to waits and generate an error. |
mustOn is the bitmap of bits that must be True to satisfy the condition.
| D15 | ... | D10 | D9 | D8 | D7 | D6 | D5 | D4 | D3 | D2 | D1 | D0 |
| XXX | ... | XXX | XXX | mustOn 8 | mustOn 7 | mustOn 6 | mustOn 5 | mustOn 4 | mustOn 3 | mustOn 2 | mustOn 1 | mustOn 0 |
For D0 through D8:
1 = Bit must be True
0 = Don't care (default)
mustOff is the bitmap of bits that must be False to satisfy the condition:
| D15 | ... | D10 | D9 | D8 | D7 | D6 | D5 | D4 | D3 | D2 | D1 | D0 |
| XXX | ... | XXX | XXX | mustOff 8 | mustOff 7 | mustOff 6 | mustOff 5 | mustOff 4 | mustOff 3 | mustOff 2 | mustOff 1 | mustOff 0 |
For D0 through D8:
1 = Bit must be False
0 = Don't care (default)
matchType selects the type of match required for the bitmap:
| matchType Constant | matchType Value |
| NIMC_MATCH_ALL | 0 |
| NIMC_MATCH_ANY | 1 |
NIMC_MATCH_ANY means that a match of any bit (logical OR) is sufficient to satisfy the condition while NIMC_MATCH_ALL requires a complete pattern match (logical AND) of all bits.
timeOut is the wait timeout value in 100 millisecond increments. The range is 0 to 65,535. If you specify a timeout of 65,535, it is treated as an infinite timeout and waits until the condition is met.
returnVector indicates the destination for the return data generated by this function. Available return vectors include return data to the host (0xFF), to a variable (0x01 through 0x78), to an indirect variable (0x81 through 0xF8), and return no data (0). Refer to Input and Return Vectors for more detailed information.
Using This Function
This function controls the flow of execution in a stored program. It suspends program execution and waits until the specified condition is met or the timeout expires. When the condition is met, program execution is resumed with the next function after the Wait on Event.
If the timeout expires before the condition is met, an error is generated and the program goes into the paused state. Refer to the Pause/Resume Program function for information about resuming a paused program.
If you set a timeout of zero, the condition must already be true or an error is generated. You can wait on virtually any instantaneous status of axes, encoders, programs, motion I/O, or general-purpose I/O. Where applicable, you can select the specified resource with the resource parameter.
When waiting on a program with the NIMC_CONDITION_PROGRAM_COMPLETE condition, mustOn, mustOff, and matchType parameters are not required and their values are ignored. You set resource equal to the specified program number to wait on. The balance of the conditions test status bitmaps and function similar to each other as described in the remainder of this section.
The mustOn, mustOff, and matchType parameters work together to define a bitmap of True and False bits that must be matched to satisfy the condition. Depending on the type of event, the mustOn and mustOff bitmaps are either one based or zero based. If the event is tied to an I/O port resource the bitmaps start at bit 0 to correspond with line 0 on an I/O port. If the event is tied to an axis-based resource, such as an encoder or an axis, the bitmaps start at bit 1 to correspond with axis 1. The matchType parameter allows you to select between an OR match, where any matching bit is sufficient, and an AND match, where all status bits must match the True/False bitmap defined by MustOn and MustOff.
Using the MustOn/MustOff protocol gives you tri-state control over each match bit: True, False or Don't care. A one (1) in a bit location of the MustOn bitmap sets the match bit to True, while a one (1) in the corresponding location of the MustOff bitmap resets the match bit to False. A zero (0) in either bitmap has no affect, so leaving both the MustOn and MustOff bits at zero defines the bit as Don't care. If you set both the MustOn and MustOff bits to one (1), it is interpreted as a MustOn condition and the match bit is set to True.
The NIMC_CONDITION_LIMIT_INPUT_ACTIVE and NIMC_CONDITION_SOFTWARE_LIMIT_ACTIVE conditions create a combined status bitmap where if either the forward or reverse limit is active, the bit is True.
When the returnVector is set to anything other than zero (0), the condition code and status bitmap that satisfied the condition are returned to the destination specified, either to a variable or the host computer, as two 16-bit words (u16).
Waits are one of the most powerful and useful features on the NI motion controller. While a program is suspended waiting for a condition, NI-Motion is not wasting CPU cycles on it. The preemptive multitasking real-time operating system (RTOS) on the NI motion controller suspends the task until the condition is met or the timeout expires. This feature allows up to 10 programs to be running simultaneously with little impact on function execution performance.
To perform a conditional wait on two unrelated conditions, store the Wait on Condition function twice—the first with waitType = NIMC_WAIT_OR and the second with waitType = NIMC_WAIT.
|
Note Two sequential Wait on Condition functions both with waitType = NIMC_WAIT emulates a Wait AND, because both wait conditions must evaluate successfully before program execution is resumed. However, both wait conditions do not have to occur at the same time. The first wait could pass before the second wait is reached. When the second wait passes, the first wait may or may not be True. |
Example
In program one, you want to wait until axes 1 through 3 have found home or until program two is complete. To accomplish this, store a Wait on Event function with the following parameters:
waitType = NIMC_WAIT_OR
condition = NIMC_CONDITION_HOME_FOUND (7)
mustOn = 0x0E, which corresponds to the following bitmap:
| D15 | ... | D10 | D9 | D8 | D7 | D6 | D5 | D4 | D3 | D2 | D1 | D0 |
| XXX | ... | XXX | XXX | mustOn 8 | mustOn 7 | mustOn 6 | mustOn 5 | mustOn 4 | mustOn 3 | mustOn 2 | mustOn 1 | XXX |
| 0 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 1 | 1 | 0 |
|
Note Because you are waiting on axes, the bitmap uses bits one through eight. |
mustOff = 0x00, which corresponds to the following bitmap:
| D15 | ... | D10 | D9 | D8 | D7 | D6 | D5 | D4 | D3 | D2 | D1 | D0 |
| XXX | ... | XXX | XXX | mustOff 8 | mustOff 7 | mustOff 6 | mustOff 5 | mustOff 4 | mustOff 3 | mustOff 2 | mustOff 1 | XXX |
| 0 | ... | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
|
Note Because you are waiting on axes, the bitmap uses bits one through eight. |
matchType = NIMC_MATCH_ALL (0)
timeOut = 100 (timeout after 10 s)
returnVector = 0 (throw the status away)
Immediately follow this with a second Wait on Condition function with the following parameters:
resource = 2 (for program two)
waitType = NIMC_WAIT
condition = NIMC_CONDITION_PROGRAM_COMPLETE (20)
timeOut = 100 (timeout after 10 s)
returnVector = 0 (throw the status away)
In this example, the home found status of axis 4 is do not care.