Skip to main content

DS402 drives

The CiA 402 profile (usually referred to as DS402) standardizes the control of motion control devices, such as servo/stepper drives, over fieldbuses like EtherCAT. It defines a state machine that all compliant drives must implement. To transition the drive between states (e.g., from "Switched On" to "Operation Enabled"), a controller sends commands via a "control word." The drive, in turn, reports its current status through a "status word." This control/status word mechanism is the foundation for enabling, disabling, and resetting drives.

Homing is the process of establishing a known, absolute position for a drive. It defines the zero or "home" position, which is crucial for accurate and repeatable movements. DS402 drives support various homing methods. For instance, a drive can be homed at its current position, or it can perform a homing routine by moving towards a physical end-stop or an external sensor.

Configuration section​

Configuring the control of DS402 drives and their homing feature involves setting up the EtherCAT hardware module, the real-time controller (ICON), and finally, the Homing skill that executes the operation.

Configuration of the EtherCAT hardware module​

The configuration of the EtherCAT hardware module is done through the UI or by editing the Textproto configuration file. It consists of two main parts:

  • ds402_bus_devices: Configures the low-level interface for each DS402 drive, including control, status, and homing-specific variables.
  • robot_arm_bus_devices: Groups one or more drives into a logical "robot arm," defining the command and state interfaces for joint-level control (position, velocity).
  • sdo_writes: Configures SDO parameters (i.e. calibration values) to be written during initialization.

Select the EtherCAT Hardware Module from the Services tab in the Flowstate Editor and open its configuration view.

ds402_bus_devices Configuration​

In the module's configuration, find or create the ds402_bus_devices list. Each entry in this list configures a single DS402 drive.

The four most important fields are:

  • control_word_variable_name: The name of the PDO variable for the drive's control word.
  • status_word_variable_name: The name of the PDO variable for the drive's status word.
  • error_code_variable_name: The name of the PDO variable for reading the drive's error code.
  • digital_outputs_variable_name: The name of the PDO variable used to control the drive's digital outputs, which often includes brake control.

Additionally, you need to configure:

  • device_name: A required, unique name for the drive. This name is used to generate the homing command and state interface names for the real-time controller (e.g., my_drive_homing_command).
  • bus_position: The integer position of the device on the EtherCAT bus, starting from 0. You can find the correct position in the EtherCAT status UI. This is crucial for sending SDO commands during initialization.
  • brake_release_bit_value: An optional integer that defines the bitmask sent to the digital_outputs_variable_name to release the drive's brakes.

For homing, the modes_of_operation_config and homing_config fields must be present. If the drive is configured to use PDOs for setting the homing method and mode of operation, you must specify the PDO variable names here. If these fields are left empty, Flowstate will fall back to using default SDOs to configure homing, which is slower but more common. If your drive deviates from the default SDOs, you can also overwrite them here, using sdo_variable instead of pdo_variable.

important

If one of the homing or mode of operation variables is configured as a PDO in the ENI file, it also has to be configures as a pdo_variable here. Otherwise, the PDO variable will keep overwriting the value set via SDO and homing will fail.

Here is an example configuration for a single drive. Note that we set main_device_synchronization_mode to BUS_SHIFT to keep the clocks synchronized. You'll likely get rattling noises without this, due to clock drift:

[type.googleapis.com/intrinsic_proto.icon.HardwareModuleConfig]: {
  module_config: {
    [type.googleapis.com/intrinsic_proto.icon.EtherCatModuleConfig]: {
      bus: {
        network_device: {
          link_layer_preferences: [RTL8169]
        }
        distributed_clock: {
          # To compensate for clock drift, we strongly recommend enabling `BUS_SHIFT`.
          main_device_synchronization_mode: BUS_SHIFT
        }
        main_device: {
          eni_file: "/data/custom_ethercat.eni"
        }
      }

      # Configuration of other devices, such as `adio_bus_devices`.

      ds402_bus_devices: [
        {
          # The `device_name` will become the prefix of the homing command
          # and status hardware interfaces.
          device_name: "joint_v1"  
          control_word_variable_name: "V1.Module 1.Outputs.Control word"
          status_word_variable_name: "V1.Module 1.Inputs.Status word"
          error_code_variable_name: "V1.Module 1.Inputs.Error code"
          modes_of_operation_config: {
            output_variable: {
              pdo_variable: {
                variable_name: "V1.Module 1.Outputs.Modes of operation"
              }
            }
            display_variable: {
              pdo_variable: {
                variable_name: "V1.Module 1.Inputs.Modes of operation display"
              }
            }
          }
          homing_config: {
            homing_method: {
              sdo_variable: {
                index: 0x6098
                subindex: 0
              }
            }
          }
          # Adjust the drive internal interpolation to the configured cycle time.
          # Overwrites any such value defined in the ENI.
          # Strongly recommended unless the value in the ENI is correctly set.
          enable_automatic_interpolation_window: true
          # Required. Can be obtained from the EtherCAT Status UI.
          bus_position: 1
          # Optional, but recommended. Will expose drive internal limit violations as an error.
          treat_internal_limits_active_as_error: true
        }
      ]
    }
  }
}

robot_arm_bus_devices Configuration​

This section groups the position and velocity interfaces of one or more drives into a single "robot arm" interface for ICON.

Find or create the robot_arm_bus_devices section. The configuration consists of several repeated fields, and it's critical that all defined fields have the same number of entries, ordered consistently from the robot's base to its tip.

  • The minimum required fields are position_command_variables and position_state_variables. For smoother control, it is recommended to also configure velocity_state_variables.
  • Each entry is a BusVariableWithScale, which maps a variable_name (the PDO name) to a scale factor.
  • The scale is used to convert between the drive's internal units (typically encoder ticks) and SI units (radians or radians/second).
    • For state variables (position_state_variables, velocity_state_variables), the value read from the bus is multiplied by the scale. The unit should be radians / tick.
    • For command variables (position_command_variables), the commanded value in radians is multiplied by the scale to get encoder ticks. The unit should be ticks / radian.
    • Typically, the command scale for a joint is the inverse of its state scale. You can find the correct conversion factors in your drive's or gearbox's documentation.
  • If you are configuring multiple arms, you must specify a unique device_prefix for each RobotArmBusDeviceConfig entry. This prefix will be added to the hardware interface names (e.g., robot1_joint_position_command).

After modifying the configuration, save it to apply the changes and restart the module.

Configuration of the real-time controller ICON​

Next, configure the real-time controller to use the newly defined homing interfaces.

  • Select or add the real-time controller service from the Services view in Flowstate and open its configuration.
  • Follow the Arm part configuration guide to set up a HalArmPart. Use the name of your EtherCAT hardware module asset as the module_name.
  • If you used a device_prefix in the EtherCAT module's robot_arm_bus_devices section, prepend it to the interface_name for the arm's joints (e.g., robot1_joint_position_command).
  • Follow the new homing configuration guide to configure the homing map within the HalArmPartConfig.
  • Make sure that the control frequency of ICON matches any potentially set distributed clock cycle time in the ENI file.

Performing the homing operation​

With both the hardware module and ICON configured, you can now use the Homing skill to perform the homing operation.

  1. In the Flowstate process editor, add an instance of the Homing skill.
  2. Configure the skill's parameters:
    • drive_name: The logical name you defined as the key in the homing map in the HalArmPartConfig (e.g., "drive_1").
    • timeout: A duration after which the skill will fail if homing is not complete. A timeout of 10 seconds is a safe starting point.
    • icon_part: The ICON part that corresponds to the arm containing the drive to be homed.
  3. The homing_method parameter is optional and defaults to 37 (home at the current position). Some older drives may expect method 35 for the same action. Refer to your drive's manual for a list of supported homing methods and their meanings. Some of these methods might also require special wiring, i.e. of endstop sensors to the digital inputs of the drive.
  4. Other optional parameters include:
    • search_speed: The speed for seeking a switch or end-stop.
    • creep_speed: The slower speed for approaching the final zero position.
    • acceleration: The acceleration used during the homing move.
    • offset: A final position offset applied after homing is complete.
    • ignore_is_settled_condition: If true, the skill will not wait for the drive to be stationary before starting the homing move.

To perform the homing, execute the skill in Flowstate. Note, that the real-time controller ICON must be enabled for homing to succeed.

Potential error sources​

  • Mismatched names: Double-check that the drive_name in the Homing skill exactly matches a key in the homing map of the HalArmPartConfig.
  • Unsupported Homing Method: If the skill fails with an "out of range" error, the homing_method is likely not supported by the drive.
  • Incorrect Units: The units for search_speed, creep_speed, and acceleration are manufacturer-specific and are not necessarily SI units. Always consult the drive's manual for correct units and reasonable value ranges.