SetAxisCamSwitch

Uses an axis' position to control a switch that triggers a digital output. When an axis reaches a certain position, a switch is turned on or off. An switch can be controlled by a forward and backward movement of an axis.

Syntax

KsCommandStatus SetAxisCamSwitch(
     int Index,
     int SwitchLength,
     McCamSwitch* Switches,
     int TrackLength,
     McOutput* Outputs,
     McTrack* Tracks,
     DWORD EnableMask,
     McSource ValueSource
);

Parameters

Index [in]: the index of an axis. Indexes are zero based. Aliases affect this parameter.

SwitchLength [in]: how many switches in the switch array. Each track can have up to eight switches.

Switches [in]: controls the switching actions. The track numbers need to be in order. See the McCamSwitch structure.

TrackLength [in]: how many tracks in the track array. The length of the output and track must be the same. For example, if there are two outputs, there must be two tracks. You can have up to 32 tracks.

Outputs [in]: selects which digital output will be controlled by the corresponding track. See the McOutput structure.

Tracks [in]: adds the compensation time and hysteresis to the switches on a track. TrackNumber is defined in Switches. See the McTrack structure.

EnableMask [in]: enables the different tracks. This parameter is 32 bits of BOOL. The corresponding track in the track array is enabled when its BOOL value is set to one.

ValueSource [in]: defines the source for axis values. For example, positions. See the McSource type.

mcCommandedValue, mcSetValue – synchronization on set value. We suggest you use these settings.
mcActualValue – synchronization on actual value. This setting may not be stable.

Return value

Returns the KsCommandStatus structure.

Remarks

McCamSwitch is a vendor-specific structure that defines switches for digital cam.
McOutput is a vendor-specific structure linked to the (physical) outputs. If you are using your servo drive's digital output (DO), you need to use EnableAxisOutput before Start.
McTrack is vendor-specific structure containing the track properties. For example, the compensation time per track (a track is a set of switches related to one output). It can also contain the reference to the output.
This functionality is sometimes called PLS – Phase or Position or Programmable Limit Switch.

Elements within the McCamSwitch structure

B/E	Parameter	Type	Description
B	TrackNumber	INT	The index of a track. Indexes are zero-based.
B	FirstOnPosition [user unit]	LREAL	The position from which the switch is on.
B	LastOnPosition [user unit]	LREAL	The position from which the switch is off.
E	AxisDirection	INT	The direction of an axis. The default value is zero. If you select one or two, the switch is active only when the axis is moving in the specified direction. Both: 0, Positive: 1, Negative: 2.
E	CamSwitchMode	INT	The cam switch is controlled by axis' positions or time. The default value is zero. If choosing Position, you need to set FirstOnPosition and LastOnPosition; if choosing Time, you need to set FirstOnPosition and Duration. Position: 0, Time: 1.
E	Duration	TIME	How long the switch is on. This property is available when CamSwitchMode is Time. The unit is second.

B/E	Parameter	Type	Description
E	OnCompensation	TIME	The length of time with which a switch is turned on (rising edge) before or after a switching point per track. If the value is positive, the switch-on will be delayed; if the value is negative, the switch-on will be advanced.
E	OffCompensation	TIME	The length of time with which a switch is turned off (falling edge) before or after a switching point per track. If the value is positive, the switch-off will be delayed; if the value is negative, the switch-off will be advanced.
E	Hysteresis [unit]	LREAL	The distance from a switching point (in positive and negative direction) in which a switch is not turned on or off until the axis has left this area. This can avoid frequent switching around a switching point.

This definition of a cam has a start and an end position, so the user can define each single cam, which has a FirstOnPosition and a LastOnPosition (or time). This function or function block is similar to a mechanical cam but has the additional advantages that the outputs can be set for a certain time, and to give it a time-compensation and a hysteresis.

CamSwitchMode: it can be position or time.

Duration: time, the output of a time cam is ON. The time compensation (OnCompensation and OffCompensation) can be positive or negative. Negative means the output changes before the switching position is reached.

Hysteresis: this parameter avoids the phenomenon where the output continually switches if the axis is near the switching point and the actual position is jittering around the switching position. Hysteresis is part of McTrack, which means that a different hysteresis is possible for each track.

Example of McCamSwitch

Parameter	Type	Switch01	Switch02	Switch03	Switch04
TrackNumber	INTEGER	1	1	1	2
FirstOnPosition [unit]	LREAL	2000	2500	4000	3000
LastOnPosition [unit]	LREAL	3000	3000	6000	--
AxisDirection	INTEGER	1=Pos	2=Neg	0=Both	0=Both
CamSwitchMode	INTEGER	0=Position	0=Position	0=Position	1=Time
Duration	LREAL	--	--	--	1.35 seconds

The figure below uses the values from the example of McCamSwitch above. It uses neither On/OffCompensation nor Hysteresis. This is the behavior of the outputs, when the axis is moving continuously in the positive direction.

SetAxisCamSwitch – Positive Direction

Detailed description of Switch01

This example uses OnCompensation -125ms and OffCompensation +250ms.

The figure below shows the behavior of the outputs, when the axis is moving continuously in the negative direction without On/OffCompensation and without Hysteresis.

SetAxisCamSwitch – Negative Direction

Example

KsCommandStatus EnableSwitches(INT Index) {
   //Each track will control one output and can contain multiple switches
   /*On compensation is a delay in seconds before the output
     is turned on when a switch becomes active*/
   /*Off compensation is a delay in seconds before the outout
     is turned off when a switch becomes inactive*/
   /*Hysteresis adds a minimum distance in between switches
     to prevent an output from switching on and off*/
   McTrack Tracks[2] = {
      //OnCompensation   OffCompensation   Hysteresis
      {    -0.125,            0.25,            0 },
      {         0,               0,            0 }
      };

   //Defines the output for each track
   //The type selects between axes and modules. TRUE: Axis, FALSE: Module
   //Index of the axis or module
   //Offset of the output bit in the device output buffer
   McOutput Outputs[2] = {
   //Axis        Index       Offset
   { FALSE,        1,          0 },
   { TRUE,       Index,        1 }
   };

   //Defines each switch.
   //Index of the track the switch belongs to.
   //Position at which the switch is enabled.
   //Position at which the switch is disabled for distance switches.
   //Direction in which the switch is triggered. 0: Both, 1: Positive, 2: Negative
   //Switch mode. 0: Distance, 1: Time
   //Duration in seconds the switch stays enabled. For time switches.
   McCamSwitch Switches[4] = {
      //TrackNumber FirstOnPosition LastOnPosition AxisDirection CamSwitchMode Duration
      {     1,            200,            800,            1,            0,         0 },
      {     1,           2500,           3000,            2,            0,         0 },
      {     1,           4000,           6000,            0,            0,         0 },
      {     2,           3000,              0,            0,            1,      1.35 }
      };

   KsCommandStatus camSwitch = SetAxisCamSwitch(
      Index,      //Index
      4,          //SwitchLength
      Switches,   //Switches
      2,          //TrackLength
      Outputs,    //Outputs
      Tracks,     //Tracks
      3,          //EnableMask, enabling track 1 and 2
      mcSetValue  //ValueSource
   );

   return camSwitch;
}

Requirements

	RT	Win32
Minimum supported version	4.0	4.0
Header	ksmotion.h	ksmotion.h
Library	KsApi_Rtss.lib	KsApi.lib