Collaboration diagram for Control Tasking:

Functions
MLPIRESULT	mlpiTaskWaitForEvent (const MLPIHANDLE connection, const MlpiTaskEvent taskEvent, const ULONG timeout)

MLPIRESULT	mlpiTaskSetSystemPriority (const MLPIHANDLE connection, const MlpiSystemTask task, const ULONG priority)

MLPIRESULT	mlpiTaskGetSystemPriority (const MLPIHANDLE connection, const MlpiSystemTask task, ULONG *priority)

MLPIRESULT	mlpiTaskSetCurrentPriority (const MLPIHANDLE connection, const ULONG priority)

MLPIRESULT	mlpiTaskGetCurrentPriority (const MLPIHANDLE connection, ULONG *priority)

MLPIRESULT	mlpiTaskSetTriggerSetup (const MLPIHANDLE connection, const MlpiTaskTriggerSetup *triggerSetup, const ULONG numElements)

MLPIRESULT	mlpiTaskGetTriggerSetup (const MLPIHANDLE connection, MlpiTaskTriggerSetup triggerSetup, const ULONG numElements, ULONG numElementsRet)

MLPIRESULT	mlpiTaskSetTrigger (const MLPIHANDLE connection, const MlpiTaskTrigger *taskTrigger, const ULONG numElements)

MLPIRESULT	mlpiTaskGetTrigger (const MLPIHANDLE connection, MlpiTaskTrigger taskTrigger, const ULONG numElements, BOOL8 cmdActive, ULONG *numElementsRet)

Detailed Description

The following functions are used for controlling task and schedule behavior.

Function Documentation

MLPIRESULT mlpiTaskWaitForEvent	(	const MLPIHANDLE	connection,
		const MlpiTaskEvent	taskEvent,
		const ULONG	timeout
	)

This function pends the calling task until the given event occurs. You can use it to synchronize a task to a system event. This way, you can get for example a task which is activated every time data arrives from the sercos bus. Of course, your task needs to have a priority which is high enough to be activated immediately. Otherwise the time between the event and this function to return is not deterministic.

Parameters

[in]	connection	Handle for multiple connections.
[in]	taskEvent	The event to wait for.
[in]	timeout	The timeout after which the function should return an error if the event did not raise. Use MLPI_INFINITE to wait forever.

Returns: Return value indicating success (>=0) or error (<0).

Example:: See TaskLib

MLPIRESULT mlpiTaskSetSystemPriority	(	const MLPIHANDLE	connection,
		const MlpiSystemTask	task,
		const ULONG	priority
	)

This function sets the priority of tasks inside the system. For example, you can set the priority of the MotionKernel(MOK) here.

Parameters

[in]	connection	Handle for multiple connections.
[in]	task	Enum identifying the internal task.
[in]	priority	The desired priority of the task. This has to be between MLPI_PRIORITY_HIGH_MAX and MLPI_PRIORITY_HIGH_MIN.

Returns: Return value indicating success (>=0) or error (<0).

Example:: 1 MLPIRESULT result = mlpiTaskSetSystemPriority(connection, MLPI_TASK_MOTIONKERNEL, MLPI_PRIORITY_HIGH_MAX);
2 if (MLPI_FAILED(result)) {
3 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
4 return result;
5 }

MLPIRESULT mlpiTaskGetSystemPriority	(	const MLPIHANDLE	connection,
		const MlpiSystemTask	task,
		ULONG *	priority
	)

This function reads back the priority of a task inside the system. For example, you can get the priority of the MotionKernel(MOK) here.

Parameters

[in]	connection	Handle for multiple connections.
[in]	task	Enum identifying the internal task.
[out]	priority	Pointer to a variable which will receive the priority of the task.

Returns: Return value indicating success (>=0) or error (<0).

Example:: 1 ULONG priority = 0;
2 MLPIRESULT result = mlpiTaskGetSystemPriority(connection, MLPI_TASK_MOTIONKERNEL, &priority);
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
5 return result;
6 }
7
8 printf("\nPriority of MotionTask is %d", priority);

MLPIRESULT mlpiTaskSetCurrentPriority	(	const MLPIHANDLE	connection,
		const ULONG	priority
	)

This function sets the priority of the calling task. Use this to set the priority of your own user C/C++ task to a higher level.

Parameters

[in]	connection	Handle for multiple connections.
[in]	priority	The desired priority of the task. This has to be between MLPI_PRIORITY_HIGH_MAX and MLPI_PRIORITY_HIGH_MIN for real-time tasks and MLPI_PRIORITY_BACKGROUND for background tasks.

Returns: Return value indicating success (>=0) or error (<0).

Example:: See TaskLib

MLPIRESULT mlpiTaskGetCurrentPriority	(	const MLPIHANDLE	connection,
		ULONG *	priority
	)

Read back the priority of the calling task.

Parameters

[in]	connection	Handle for multiple connections.
[out]	priority	Pointer to a variable receiving the current task priority of the calling task.

Returns: Return value indicating success (>=0) or error (<0).

Example:: 1 ULONG priority = 0;
2 MLPIRESULT result = mlpiTaskGetCurrentPriority(connection, &priority);
3 if (MLPI_FAILED(result)) {
4 printf("\ncall of MLPI function failed with 0x%08x!", (unsigned)result);
5 return result;
6 }
7
8 printf("\nPriority of current task is %d", priority);

MLPIRESULT mlpiTaskSetTriggerSetup	(	const MLPIHANDLE	connection,
		const MlpiTaskTriggerSetup *	triggerSetup,
		const ULONG	numElements
	)

This function sets the configuration of the external trigger. Use this function to deactivate cyclic events and configure the behaviour of the external trigger function.
Use the options 'MLPI_TASK_TRIG_OPT_NO_CYCLIC_MOTION' and 'MLPI_TASK_TRIG_OPT_NO_CYCLIC_SERCOS' to activate or deactivate cyclic execution of the events. It is only possible to decouple events if all axis are in standstill. Events are triggered synchronous to theirs specific cycles. To change this behaviour set the option 'MLPI_TASK_TRIG_OPT_IMMEDIATE_EXECUTION'. In this case all events are executed immediately one after the other and not within their cycles.
A warning is set as long as an event is decoupled from cyclic execution. To suppress this warning set the option 'MLPI_TASK_TRIG_OPT_NO_WARNING'. If an fatal error occurs all decoupled events will be reset and coupled again, so that an error reaction can be performed. To deactivate the reset of events set the option 'MLPI_TASK_TRIG_OPT_NO_ERROR_REACTION'. The call of the function 'mlpiTaskSetTrigger' is asynchronous and will return immediately. Set the option 'MLPI_TASK_TRIG_OPT_SYNCHRONOUS' to call the function synchronous. In this case the function will return after all triggers are done.

Parameters

[in]	connection	Handle for multiple connections.
[in]	triggerSetup	Pointer to array of structures to activate and deactivate options.
[in]	numElements	Number of MlpiTaskTriggerSetup elements available in 'triggerSetup' for writing.

Returns: Return value indicating success (>=0) or error (<0).

Example:: 1 //decouple motion from cyclic execution and set option synchronous
2 MlpiTaskTriggerSetup triggerSetup[2];
3 triggerSetup[0].triggerOption = MLPI_TASK_TRIG_OPT_NO_CYCLIC_MOTION;
4 triggerSetup[0].active = TRUE;
5 triggerSetup[1].triggerOption = MLPI_TASK_TRIG_OPT_SYNCHRONOUS;
6 triggerSetup[1].active = TRUE;
7 MLPIRESULT result = mlpiTaskSetTriggerSetup(connection, triggerSetup, _countof(triggerSetup));
8 if (MLPI_FAILED(result))
9 {
10 printf("\ncall of MLPI function failed with 0x%08x", (unsigned)result);
11 return result;
12 }

MLPIRESULT mlpiTaskGetTriggerSetup	(	const MLPIHANDLE	connection,
		MlpiTaskTriggerSetup *	triggerSetup,
		const ULONG	numElements,
		ULONG *	numElementsRet
	)

This function gets the configuration of the external trigger.

Parameters

[in]	connection	Handle for multiple connections.
[in,out]	triggerSetup	Pointer to array of structures to store the actual configured options. The triggerOption is an input parameter. It defines which option is requested. Active is an output parameter. It says if the option is activated or not.
[in]	numElements	Number of MlpiTaskTriggerSetup elements available in 'triggerSetup' for reading.
[out]	numElementsRet	Number of elements used.

Returns: Return value indicating success (>=0) or error (<0).

Example:: 1 // get configuration of option 'MLPI_TASK_TRIG_OPT_NO_CYCLIC_MOTION'
2 ULONG numElementsRet = 0;
3 MlpiTaskTriggerSetup triggerSetup;
4 triggerSetup.triggerOption = MLPI_TASK_TRIG_OPT_NO_CYCLIC_MOTION;
5 MLPIRESULT result = mlpiTaskGetTriggerSetup(connection, &triggerSetup, 1, &numElementsRet);
6 if (MLPI_FAILED(result))
7 {
8 printf("\ncall of MLPI function failed with 0x%08x", (unsigned)result);
9 return result;
10 }
11
12 printf("\nOption 'MLPI_TASK_TRIG_OPT_NO_CYCLIC_MOTION' is %s", (triggerSetup.active?"active":"not active"));

MLPIRESULT mlpiTaskSetTrigger	(	const MLPIHANDLE	connection,
		const MlpiTaskTrigger *	taskTrigger,
		const ULONG	numElements
	)

This function executes the external trigger. To trigger an event it has to be decoupled from the cyclic execution. Use the 'mlpiTaskSetTriggerSetup' function to decouple the events and to configure the behavior of execution. It is not possible to execute a new trigger if an execution is still active. To check if an execution is active use the 'mlpiTaskGetTrigger' function.

Parameters

[in]	connection	Handle for multiple connections.
[in]	taskTrigger	Pointer to array of structures to activate and deactivate events. Use the parameter numTriggers to define how often an activated events should be triggered.
[in]	numElements	Number of MlpiTaskTrigger elements available in 'taskTrigger' for writing.

Returns: Return value indicating success (>=0) or error (<0).

Attention: According to the operation mode of the real drive connected to the axis, an movement may continue once triggered. If the drive is e.g. in the velocity control mode and the event motion is triggered, the drive keeps this velocity until interrupted by a new command. Error on real drives can not be recognized if motion isn't triggered. So no error reaction can occur.
This function should be used for simulation and not on real machines.

Example:: 1 // execute motion event 20 times
2 MlpiTaskTrigger taskTrigger;
3 taskTrigger.triggerEvent = MLPI_TASK_TRIG_EVT_MOTION;
4 taskTrigger.active = TRUE;
5 taskTrigger.numTriggers = 20;
6 MLPIRESULT result = mlpiTaskSetTrigger(connection, &taskTrigger, 1);
7 if (MLPI_FAILED(result))
8 {
9 printf("\ncall of MLPI function failed with 0x%08x", (unsigned)result);
10 return result;
11 }

MLPIRESULT mlpiTaskGetTrigger	(	const MLPIHANDLE	connection,
		MlpiTaskTrigger *	taskTrigger,
		const ULONG	numElements,
		BOOL8 *	cmdActive,
		ULONG *	numElementsRet
	)

This function gets the configuration of the events of external trigger functionality.

Parameters

[in]	connection	Handle for multiple connections.
[in,out]	taskTrigger	Pointer to array of structures to store configuration of the events. The triggerEvent is an input parameter. It defines which event is requested. The parameter active defines if an event is actual active or not and numTriggers defines how many triggers are left for this event.
[in]	numElements	Number of MlpiTaskTrigger elements available in 'taskTrigger' for reading.
[out]	cmdActive	True if an execution of an external trigger is active.
[out]	numElementsRet	Number of elements used.

Returns: Return value indicating success (>=0) or error (<0).

Example:: 1 // get the configuration of the event 'MLPI_TASK_TRIG_EVT_MOTION' without checking of active execution
2 ULONG numElementsRet = 0;
3 MlpiTaskTrigger taskTrigger;
4 taskTrigger.triggerEvent = MLPI_TASK_TRIG_EVT_MOTION;
5 MLPIRESULT result = mlpiTaskGetTrigger(connection, &taskTrigger, 1, NULL, &numElementsRet);
6 if (MLPI_FAILED(result))
7 {
8 printf("\ncall of MLPI function failed with 0x%08x", (unsigned)result);
9 return result;
10 }
11 printf("\nThe event 'MLPI_TASK_TRIG_EVT_MOTION' is %s; number of triggers: %u", (taskTrigger.active?"active":"not active"), taskTrigger.numTriggers);
12
13 // just check if exection of external tigger is active
14 BOOL8 cmdActive = FALSE;
15 result = mlpiTaskGetTrigger(connection, NULL, 0, &cmdActive, NULL);
16 if (MLPI_FAILED(result))
17 {
18 printf("\ncall of MLPI function failed with 0x%08x", (unsigned)result);
19 return result;
20 }
21 printf("\nThe execution of external trigger is %s", (cmdActive?"active":"not active"));

Functions

Detailed Description

Function Documentation