Configure the settings

KINGSTAR offers a variety of settings that can be configured. To streamline the code, we create individual files for the settings. In this section you'll learn how to create the files and configure the settings.

  1. In Solution Explorer, in the Header Files folder, double-click SystemInitialization.h to open it.
  2. In SystemInitialization.h, we need to configure the KINGSTAR settings that are applied before the Subsystem is started. We use variables to store the values of the settings. All the settings can be changed to meet your needs. The following table are the settings we used in this sample.
    3. Variables API functions or enum types Description
    CYCLE_TIME SetCycleTime Sets the EtherCAT cycle time. Depends on how fast your servo drive supports. If an unsupported cycle time is selected, the update time for each drive is automatically and independently extended.
    ACCESS_MODE

    SetAxisAccessMode

    The KsAccessMode type

    		 Sets the data transfer mode for EtherCAT drives. Depends on what control mode your servo drive supports and what mode you want to use. It can be set to position or velocity. By default, the access mode is accessVelPos.
    VERBOSITY EnableServerLog Enables real-time server messages that are displayed on RtxServer.
    SERVO_INPUT EnableAxisInput Adds the Digital Input variable to the PDO. Not all servo drives support this feature.
    SERVO_OUTPUT EnableAxisOutput Adds the Digital Output variable to the PDO. Not all servo drives support this feature.
    SECOND_ENCODER EnableSecondEncoder Adds the Internal Position variable to PDO.
    ACTUAL_VELOCITY EnableActualVelocity Adds the Actual Velocity variable to PDO.
    ACTUAL_TORQUE EnableActualTorque Adds the Actual Torque variable to PDO.
    ACTUAL_CURRENT EnableActualCurrent Adds the Actual Current variable to PDO.
    FOLLOWING_ERROR EnableFollowingError Adds the Following Error variable to PDO.
    MAX_TORQUE EnableMaxTorque Adds the Max Torque variable to PDO.
    MAX_CURRENT EnableMaxCurrent Adds the Maximum Current variable to PDO.
    SYNCHORNIZED_CONTROL_MODE EnableSynchronizedControlMode Adds the Modes of Operation and Modes of Operation Display variables to PDO. It changes the control mode through PDO instead of SDO, so the control mode can be changed faster (usually in 3-5 cycles). Not all drives support this feature.
    AUTO_RESTART EnableAutoRestart Allows for auto-restart to be enabled. Following a cable disconnected, if auto-restart is enabled, the EtherCAT master restarts automatically after a cable is plugged in.
    AUTO_REPAIR EnableAutoRepair Allows auto-repair to be enabled. If any slave disappears (due to the replacement of a servo drive, cable disconnection, power cut or other issues) or goes to an EtherCAT error state, it restarts automatically. Slaves that are not in an error state are not impacted and continue to function properly.
    AUTO_CONFIG EnableAutoConfig Allows auto-config to be enabled. It automatically configures the EtherCAT settings for your servo drives.
    ENABLE_DC, DC_CHECK, DC_MASTER_SHIFT, 0 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.
    HOT_CONNECT EnableHotConnect Allows new hardware to be added while the EtherCAT network is running.
    REDUNDANCY EnableRedundancy Enables cable redundancy. The last EtherCAT slave is connected to another network interface card on the computer so all the slaves can be communicated even if one cable is broken.

     

    To prevent SystemInitialization.h being repeatedly included in one file, Visual Studio adds the #pragma once directive automatically into the header file.

    Under #pragma once, add the following code:

    //Using instances other than zero requires a special license.
#define INSTANCE 0

//Base cycle time for the EtherCAT network.
//Require the High Speed Timer license if the cycle time is less than 1 millisecond.
#define CYCLE_TIME cycle500

//Available control modes for the axes.
#define ACCESS_MODE accessPos

//Print logs to RtxServer.
#define VERBOSITY FALSE

//Map the axes digital inputs to the PDO.
#define SERVO_INPUT TRUE

//Map the axes digital outputs to the PDO.
#define SERVO_OUTPUT FALSE

//Map the axes internal position to the PDO.
//It works only when two encoders are connected to the axis.
#define SECOND_ENCODER FALSE

//Map the actual velocity variable to the PDO.
#define ACTUAL_VELOCITY TRUE

//Map the actual torque variable to the PDO.
#define ACTUAL_TORQUE TRUE

//Map the actual current variable to the PDO.
#define ACTUAL_CURRENT TRUE

//Map the following error variable to the PDO.
#define FOLLOWING_ERROR TRUE

//Map the max torque variable to the PDO.
/*If your drive has the Max Torque object and you set this value
  to TRUE, you must use WriteAxisMaxTorque to set its value, or 
  the axis won't move.*/
#define MAX_TORQUE FALSE

//Map the max current variable to the PDO.
/*If your drive has the Max Current object and you set this value
  to TRUE, you must use WriteAxisMaxCurrent to set its value, or
  the axis won't move.*/
#define MAX_CURRENT FALSE

//Map the Modes of Operation to the PDO.
//It works only when the control mode is changed while the axis is enabled.
#define SYNCHORNIZED_CONTROL_MODE TRUE

//Automatically restart the master when the EtherCAT cable is reconnected.
#define AUTO_RESTART TRUE

//Automatically restart individual slaves when they are powered back on.
#define AUTO_REPAIR TRUE

//Use the automatic EtherCAT configuration feature.
//If this is disabled, most of KINGSTAR feature are disabled.
#define AUTO_CONFIG TRUE

//Use distributed clocks (DC) to synchronize the slaves.
#define ENABLE_DC TRUE

//Wait for the slaves to be synchronized before going to OP.
#define DC_CHECK TRUE

//Use Master shift instead of Bus shift for DC.
//The slave synchronization jitter will be reduced but the master may be less stable.
#define DC_MASTER_SHIFT FALSE

//Allow slaves to be added while in OP.
//Require the Hot Connect license.
#define HOT_CONNECT FALSE

//Connect the last slave back to the computer for cable redundancy.
//Require the Cable Redundancy license.
#define REDUNDANCY FALSE
  3. Next, we are adding simulated axes and I/O modules. It's optional to add them. The benefit to add simulated devices is that you can test the settings before applying them to real devices. Simulated devices are created when real ones are not enough or not connected.
    4. Variable API functions or enum types Meaning
    AXES_COUNT SetConfiguredAxesCount Configures a number of simulated axes. The number of simulated axes is determined by how much the given value outnumbers the real hardware. If the given number is greater than the number of the real axes, KINGSTAR will display all real axes plus simulated ones. For example, if you have five real axes and you give the number seven, you'll get five real axes plus two simulated axes. If the given number is less than or equal to the number of the real axes, KINGSTAR will display all real axes without simulated ones.
    IO_COUNT SetConfiguredIoCount Configures a number of simulated I/O modules. The number of simulated I/Os is determined by how much the given value exceeds the number of the real hardware. If the given number is greater than the number of the real I/Os, KINGSTAR will display all real I/Os plus simulated ones. For example, if you have five real I/Os and you give the number seven, you'll get five real I/Os plus two simulated I/Os. If the given number is less than or equal to the number of the real I/Os, KINGSTAR will display all real I/Os without simulated ones.
    IO_INPUT_LENGTH InputLength in the SlaveStatus structure For I/O modules only. Length of the input data read from the device.
    IO_OUTPUT_LENGTH OutputLength in the SlaveStatus structure For I/O modules only. Length of the output data sent to the device.

    When you use simulated I/O modules, you need to fill the InputLength and OutputLength in the SlaveStatus structure, because they determine how many inputs and outputs for a simulated I/O. Other fields will be filled with the default values. If you are using real I/O modules, KINGSTAR will automatically detect their inputs and outputs and fill all fields.

    Under #define REDUNDANCY TRUE, press Enter to add an empty line and add the following code:

    //Minimum number of axes in the system.
//Simulated axes will be added if there is not enough hardware connected.
#define AXES_COUNT 2

//Minimum number of I/O modules in the system.
//Simulated modules will be added if there is not enough hardware connected.
#define IO_COUNT 3

//Length in bits of the input buffer of simulated modules.
#define IO_INPUT_LENGTH 16

//Length in bits of the output buffer of simulated modules.
#define IO_OUTPUT_LENGTH 16
  4. Finally, we declare two BOOL functions: StartKingstar and StopKingstar. These two functions contain the functions relevant to starting and stopping the KINGSTAR Subsystem and identify whether they are run successfully.

    5. Under #define IO_OUTPUT_LENGTH 16, press Enter to add an empty line and add the following code:

    BOOL StartKingstar();
BOOL StopKingstar();