name

ros2-ethercat-bringup

description

Create or extend ROS 2 Humble projects for motors and servo drives controlled over the EtherCAT protocol, using ethercat_driver_ros2, ros2_control, CiA402 drives, PDO YAML, xacro hardware descriptions, controller_manager launch files, and staged safety validation. Use when asked to build an eyou_ethercat_bringup-like EtherCAT motor-control project from zero, generate AI prompts for EtherCAT motor code, map EtherCAT PDO objects to ROS2 joints, configure JointTrajectoryController or direct position/velocity controllers, or explain/modify a ROS2 EtherCAT motor workflow.

Ros2 Ethercat Bringup

Overview

Use this skill for EtherCAT-protocol motor/servo control projects. Build on ethercat_driver_ros2; do not reimplement EtherCAT master, PDO exchange, or CiA402 state handling unless the existing plugin cannot satisfy a documented requirement. Generate the ROS2 integration layer: workspace layout, bringup package, xacro hardware description, slave PDO YAML, ros2_control controllers, launch orchestration, and validation commands.

This skill is not for CANopen, Modbus, serial, PWM, GPIO, or generic motor-control projects unless the user is explicitly porting the same ROS2 structure away from EtherCAT.

Workflow

Inspect the workspace first: run colcon list --base-paths src and read nearby package.xml, CMakeLists.txt, config, launch, and urdf files before proposing edits.
Gather hardware facts before writing motor-specific YAML. Read hardware-intake.md when the user is starting from physical motors, changing PDOs, changing drive modes, or lacks vendor/product IDs, slave positions, encoder scaling, or object dictionary details.
- If required EtherCAT facts are unknown, stop and ask for the missing data first instead of repeatedly trial-and-error editing YAML.
- Give the user a concrete collection checklist: motor/drive model, manual or ESI XML, ethercat slaves -v, ethercat pdos -p <n>, ethercat cstruct -p <n>, encoder counts, gear ratio, drive mode, DC/SYNC requirements, initialization SDOs, and safety/enable conditions.
- Only generate placeholder YAML when the user explicitly wants a scaffold; label all unknown values and do not present it as ready for hardware.
Decide the control surface:
- Use JointTrajectoryController when MoveIt, time-stamped multi-axis motion, synchronized joints, or FollowJointTrajectory actions are needed.
- Use forward_command_controller or a joint group position/velocity controller when the user only wants to publish direct motor/joint setpoints.
Generate or update the bringup package using package-blueprint.md. Keep absolute paths out of generated xacro/launch files; use get_package_share_directory() or xacro $(find package).
Build only the integration layer unless dependencies must also be generated. If robot_model, MoveIt config, or helper scripts are referenced, either create them explicitly or remove the dependency.
Validate in stages:
- Build and source the workspace.
- Verify EtherCAT master and slaves with read-only commands.
- Start ros2_control with controllers inactive or low-risk where possible.
- Check hardware interfaces and /joint_states.
- Send only small, user-approved motion commands after confirming physical safety.

Code Generation Rules

Treat each motor as a ROS2 joint unless the project already defines a different abstraction.
Put EtherCAT object mapping in config/<drive>_slave.yaml; put ROS controller configuration in config/controllers.yaml; put hardware plugin wiring in urdf/*.ros2_control.xacro; put startup ordering in launch/*.launch.py.
In CSP mode, expose 0x607A Target Position as command_interface: position and 0x6064/0x606C/0x6077 as position/velocity/effort state interfaces. Do not claim velocity command support unless 0x60FF or the chosen mode is actually exposed as a command interface.
Make scaling explicit: document rad-to-count and count-to-rad factors, sign reversals, gear ratios, and joint order.
Keep safety conservative: default auto_fault_reset: false, include a preflight check script only when the user's drive objects are known, and never auto-send large movements.
Prefer small, inspectable packages over generated monoliths.

Field Notes: EYOU ServoModule / PHU20H

When bringing up an EYOU EYOU_ServoModule drive for a PHU20H-style actuator:

The observed EtherCAT identity is vendor_id: 0x00001097, product_id: 0x00010002; the standard identity object 0x1018:2 may report a vendor-specific value, so prefer ethercat slaves -v / ethercat cstruct -p <n> for the product code used by IgH registration.
A working PDO layout uses RxPDO 0x1600 with 0x6040, 0x6060, 0x607A, 0x6081, 0x60FF, 0x240D, 0x6071, 0x6083, 0x6084, 0x6087 and TxPDO 0x1A00 with 0x6041, 0x6061, 0x603F, 0x6064, 0x606C, 0x6077, 0x6074, 0x60F4, 0x6079, 0x60FD. This maps to SM2 33 bytes and SM3 29 bytes.
For a 121:1 gearbox with 524288 counts per motor revolution, use 0x607A factor 10096606.2432554 counts/rad and 0x6064 factor 9.904318103600473e-08 rad/count. Use the negative variants for reversed mechanical direction.
Known good defaults include assign_activate: 0x0300, auto_fault_reset: false, csp_position_sync_tolerance: 0.05, mode 8, and defaults of 1000 for 0x6081, 0x240D, 0x6083, 0x6084, and 0x6087.
If ethercat master reports one slave, the bus position is normally 0; do not expect a Slave 1 section unless there are at least two slaves.

Troubleshooting Notes

Trust ethercat master for the actual IgH master MAC. With ec_igb, the EtherCAT NIC may not appear as a normal ip link interface; a different adjacent MAC may remain visible as a normal Linux NIC.
Last WC: 0 during hardware activation means the process-data domain never became valid. Check kernel logs for SAFEOP/DC messages, confirm PDO bytes with ethercat cstruct -p <n>, verify the master MAC, and compare against a known-good slave YAML.
If the log reaches Domain: WC <nonzero>, Domain: State COMPLETE, slave operational, and Operation Enabled, the hardware layer is up. Controller spawner timeouts at that point are usually launch sequencing issues; delay spawners until hardware activation finishes and increase --service-call-timeout.
If ROS command topics have subscribers, the position command interface is claimed, and 0x607A Target Position changes but the motor does not move, the command reached the drive. Read 0x6041, 0x6061, 0x607A, 0x6064, and 0x603F; a nonzero drive error means the remaining problem is drive-side enable/fault/safety logic.
Stopping a launch can fault a servo if the driver releases the EtherCAT master without first commanding a CiA402 disable/shutdown state. Prefer a staged shutdown: stop motion, deactivate command controllers, confirm the drive is stationary, then stop bringup. Add explicit fault-reset or graceful-disable tooling when the drive supports it.

AI Prompting

When the user wants a reusable prompt rather than immediate code, read prompt-template.md, fill in the known hardware fields, and leave unknowns as explicit questions. Make the prompt ask the AI to generate files, explain assumptions, and provide build/validation commands.

Validation Commands

Use these only after reading the repository's actual package names and launch files:

source /opt/ros/humble/setup.bash
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release
source install/setup.bash
ros2 control list_hardware_interfaces
ros2 control list_controllers
ros2 topic echo /joint_states

For real hardware, require the user to confirm EtherCAT master setup, drive enable conditions, emergency stop availability, and safe motion range before suggesting commands that can move motors.

Ros2 Ethercat Bringup

Overview

This skill is not for CANopen, Modbus, serial, PWM, GPIO, or generic motor-control projects unless the user is explicitly porting the same ROS2 structure away from EtherCAT.

Workflow

Inspect the workspace first: run colcon list --base-paths src and read nearby package.xml, CMakeLists.txt, config, launch, and urdf files before proposing edits.

Gather hardware facts before writing motor-specific YAML. Read hardware-intake.md when the user is starting from physical motors, changing PDOs, changing drive modes, or lacks vendor/product IDs, slave positions, encoder scaling, or object dictionary details.

If required EtherCAT facts are unknown, stop and ask for the missing data first instead of repeatedly trial-and-error editing YAML.
Give the user a concrete collection checklist: motor/drive model, manual or ESI XML, ethercat slaves -v, ethercat pdos -p <n>, ethercat cstruct -p <n>, encoder counts, gear ratio, drive mode, DC/SYNC requirements, initialization SDOs, and safety/enable conditions.
Only generate placeholder YAML when the user explicitly wants a scaffold; label all unknown values and do not present it as ready for hardware.

Decide the control surface:

Use JointTrajectoryController when MoveIt, time-stamped multi-axis motion, synchronized joints, or FollowJointTrajectory actions are needed.
Use forward_command_controller or a joint group position/velocity controller when the user only wants to publish direct motor/joint setpoints.

Generate or update the bringup package using package-blueprint.md. Keep absolute paths out of generated xacro/launch files; use get_package_share_directory() or xacro $(find package).

Build only the integration layer unless dependencies must also be generated. If robot_model, MoveIt config, or helper scripts are referenced, either create them explicitly or remove the dependency.

Validate in stages:

Build and source the workspace.
Verify EtherCAT master and slaves with read-only commands.
Start ros2_control with controllers inactive or low-risk where possible.
Check hardware interfaces and /joint_states.
Send only small, user-approved motion commands after confirming physical safety.

Code Generation Rules

Treat each motor as a ROS2 joint unless the project already defines a different abstraction.

Put EtherCAT object mapping in config/<drive>_slave.yaml; put ROS controller configuration in config/controllers.yaml; put hardware plugin wiring in urdf/*.ros2_control.xacro; put startup ordering in launch/*.launch.py.

In CSP mode, expose 0x607A Target Position as command_interface: position and 0x6064/0x606C/0x6077 as position/velocity/effort state interfaces. Do not claim velocity command support unless 0x60FF or the chosen mode is actually exposed as a command interface.

Make scaling explicit: document rad-to-count and count-to-rad factors, sign reversals, gear ratios, and joint order.

Keep safety conservative: default auto_fault_reset: false, include a preflight check script only when the user's drive objects are known, and never auto-send large movements.

Prefer small, inspectable packages over generated monoliths.

Field Notes: EYOU ServoModule / PHU20H

When bringing up an EYOU EYOU_ServoModule drive for a PHU20H-style actuator:

The observed EtherCAT identity is vendor_id: 0x00001097, product_id: 0x00010002; the standard identity object 0x1018:2 may report a vendor-specific value, so prefer ethercat slaves -v / ethercat cstruct -p <n> for the product code used by IgH registration.

A working PDO layout uses RxPDO 0x1600 with 0x6040, 0x6060, 0x607A, 0x6081, 0x60FF, 0x240D, 0x6071, 0x6083, 0x6084, 0x6087 and TxPDO 0x1A00 with 0x6041, 0x6061, 0x603F, 0x6064, 0x606C, 0x6077, 0x6074, 0x60F4, 0x6079, 0x60FD. This maps to SM2 33 bytes and SM3 29 bytes.

For a 121:1 gearbox with 524288 counts per motor revolution, use 0x607A factor 10096606.2432554 counts/rad and 0x6064 factor 9.904318103600473e-08 rad/count. Use the negative variants for reversed mechanical direction.

Known good defaults include assign_activate: 0x0300, auto_fault_reset: false, csp_position_sync_tolerance: 0.05, mode 8, and defaults of 1000 for 0x6081, 0x240D, 0x6083, 0x6084, and 0x6087.

If ethercat master reports one slave, the bus position is normally 0; do not expect a Slave 1 section unless there are at least two slaves.

Troubleshooting Notes

Trust ethercat master for the actual IgH master MAC. With ec_igb, the EtherCAT NIC may not appear as a normal ip link interface; a different adjacent MAC may remain visible as a normal Linux NIC.

Last WC: 0 during hardware activation means the process-data domain never became valid. Check kernel logs for SAFEOP/DC messages, confirm PDO bytes with ethercat cstruct -p <n>, verify the master MAC, and compare against a known-good slave YAML.

If the log reaches Domain: WC <nonzero>, Domain: State COMPLETE, slave operational, and Operation Enabled, the hardware layer is up. Controller spawner timeouts at that point are usually launch sequencing issues; delay spawners until hardware activation finishes and increase --service-call-timeout.

If ROS command topics have subscribers, the position command interface is claimed, and 0x607A Target Position changes but the motor does not move, the command reached the drive. Read 0x6041, 0x6061, 0x607A, 0x6064, and 0x603F; a nonzero drive error means the remaining problem is drive-side enable/fault/safety logic.

Stopping a launch can fault a servo if the driver releases the EtherCAT master without first commanding a CiA402 disable/shutdown state. Prefer a staged shutdown: stop motion, deactivate command controllers, confirm the drive is stationary, then stop bringup. Add explicit fault-reset or graceful-disable tooling when the drive supports it.

AI Prompting

Validation Commands

Use these only after reading the repository's actual package names and launch files:

source /opt/ros/humble/setup.bash rosdep install --from-paths src --ignore-src -r -y colcon build --symlink-install --cmake-args -DCMAKE_BUILD_TYPE=Release source install/setup.bash ros2 control list_hardware_interfaces ros2 control list_controllers ros2 topic echo /joint_states

For real hardware, require the user to confirm EtherCAT master setup, drive enable conditions, emergency stop availability, and safe motion range before suggesting commands that can move motors.