ConfigureDc

Configures distributed clock (DC) options. Distributed clocks allow the synchronization of the slave cycles with the KINGSTAR cycle. It is highly recommended for any motion application to avoid vibrations.

• Master Shift: the reference clock is the clock of the first slave on the EtherCAT network.
• Bus Shift: the reference clock is the master's clock.

Syntax

KsError ConfigureDc(
     BOOL Active,
     BOOL CheckStatus,
     BOOL MasterShift,
     int ReferenceIndex
);

Parameters

Active: TRUE to enable, and FALSE to disable DC synchronization. By default, it is TRUE.

CheckStatus: enables checking of the DC jitter during startup. The devices will go to the operational state (Op) once the synchronization is done. This slows the startup around 15 seconds. By default, it is TRUE.

MasterShift: chooses the shift mode. TRUE: Master Shift. FALSE: Bus Shift. By default, it is FALSE.

Bus Shift means that the EtherCAT slaves follows the Master (computer) clock. Master Shift means the slaves and the Master follow one of the slaves called "Reference Clock." By default, the Reference Clock will be the first slave on the bus that supports DC.

NOTE:  The slave clocks may be more precise than the computer clock so Master Shift is more stable. However, Master Shift modifies the computer clock's speed which impacts all time stamps done on the computer. This can be a problem if there are other protocols used on the same computer.

ReferenceIndex: selects which device is the reference clock. This parameter is a slave ID, which is the EtherCAT ID of a device. It corresponds to the position of the device in the EtherCAT loop. The ID is zero based and is not affected by aliasing.

NOTE:  ReferenceIndex has not been implemented yet.

Return value

If the function succeeds, it returns errNoError, otherwise an error code. For more information about the error code, see the KsError list.

Remarks

• Disabling DC checks can reduce the startup time by 10 seconds, but no longer guarantee that the synchronization is ready once the system is started. It takes about 1 minute for the clocks to synchronize after the system is in the operational state (Op). We suggest you keep it enabled.
• In Master Shift, the slaves are more stable but the master is less stable. Master Shift should be used only if needed.
• This function must be called after Create and before Start.

Usable EtherCAT states

ecatOffline

Example

BOOL StartKingstar() {
   //Launch or connect to the KINGSTAR Subsystem process
   KsError nRet = errNoError;
   nRet = Create(INSTANCE, 0);

   SubsystemStatus Subsystem = { ecatOffline, ecatOffline, 0, 0, 0, 
	{ecatOffline}, {ecatOffline}, {axisOffline} };
   GetStatus(&Subsystem, NULL);
   if (Subsystem.State == ecatOP) {
      RtPrintf("Subsystem already started: %x\n", nRet);
      return TRUE;
   }
   else if (Subsystem.State != ecatOffline) {
      RtPrintf("Subsystem in unexpected state: %d\n", Subsystem.State);
      return FALSE;
   }

   //Configure the Subsystem settings
   nRet = SetCycleTime(cycle500);
   nRet = SetAxisAccessMode(accessPos);
   nRet = EnableServerLog(FALSE);
   nRet = EnableAxisInput(TRUE);
   nRet = EnableAxisOutput(FALSE);
   nRet = EnableSecondEncoder(FALSE);
   nRet = EnableActualVelocity(TRUE);
   nRet = EnableActualTorque(TRUE);
   nRet = EnableActualCurrent(TRUE);
   nRet = EnableFollowingError(TRUE);
   nRet = EnableMaxTorque(TRUE);
   nRet = EnableMaxCurrent(TRUE);
   nRet = EnableTorqueOffset(FALSE);
   nRet = EnableProfilePosition(FALSE);
   nRet = EnableSynchronizedControlMode(TRUE);
   nRet = EnableAutoRestart(TRUE);
   nRet = EnableAutoRepair(TRUE);
   nRet = EnableAutoConfig(TRUE);
   nRet = ConfigureDc(TRUE, TRUE, FALSE, 0);
   nRet = EnableHotConnect(TRUE);
   nRet = EnableRedundancy(TRUE);
   nRet = SetConfiguredAxesCount(1);
   nRet = SetConfiguredIoCount(3);
   SlaveStatus simulatedIo = { 0 };
   simulatedIo.InputLength = 16;
   simulatedIo.OutputLength = 16;
   for (int i = 0; i < IO_COUNT; i++) {
      nRet = ConfigureIo(i, simulatedIo);
   }

   SlaveStatus axisDefinition = { "Simulated Axis", 0 };
   ConfigureAxis(0, axisDefinition, 131072);

   //Start the EtherCAT network
   //This function is asynchronous so the network is not started yet when it returns
   KsCommandStatus status = WaitForCommand(30, TRUE, Start());

   return TRUE;
}

Requirements

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

See also

Create

Start