Developer Guide


Home | API Reference | Developer Guide | Code Analysis | Usage Examples

Project Overview

Draco4 is a high-performance, real-time EtherCAT motor control system designed for complex robotics applications. This guide will help you understand and use the system to build a ROS2 SDK for humanoid robot control.

System Architecture

Hierarchical Design (3 Layers)

RobotController (Robot-wide coordination)
    ├── NetworkController (per EtherCAT interface) 
    │   ├── MotorController (individual motors)
    │   ├── MotorController 
    │   └── MotorController
    └── NetworkController (another interface)
        ├── MotorController
        └── MotorController

Why this architecture?

Real-Time Operation

Timing Requirements

Critical: The system requires precise timing for stable control.

// Main control loop - MUST run at configured frequency
auto next_cycle = std::chrono::steady_clock::now();
const auto cycle_time = std::chrono::microseconds(4000); // 250Hz = 4ms

while (operational) {
    robot->updateAllNetworks();  // EtherCAT communication
    
    // Your control logic here
    processROS2Messages();
    updateMotorCommands();
    publishFeedback();
    
    // Sleep until next cycle
    next_cycle += cycle_time;
    std::this_thread::sleep_until(next_cycle);
}

Performance Tips

  1. Pre-allocate: Avoid memory allocation in control loop
  2. Batch operations: Update all motors together
  3. Monitor timing: Log if cycles exceed target time
  4. Use RT kernel: For production humanoid systems

Data Structures

PDO (Process Data Objects)

OutputPDO (Commands to motor):

struct OutputPDO {
    uint16_t controlword;      // CIA402 control
    uint8_t modes_of_operation; // Control mode
    uint16_t target_torque;    // Torque command
    uint32_t target_position;  // Position command  
    uint32_t target_velocity;  // Velocity command
    // ... additional fields
};

InputPDO (Feedback from motor):

struct InputPDO {
    uint16_t statusword;       // CIA402 status
    uint32_t position_actual;  // Current position
    uint32_t velocity_actual;  // Current velocity
    uint16_t torque_actual;    // Current torque
    // ... additional fields
};

Network Status

struct NetworkStatus {
    bool initialized;          // EtherCAT master ready
    bool operational;          // Network in OP state
    int slave_count;           // Number of motors found
    int expected_wkc;          // Expected working counter
    int actual_wkc;            // Actual working counter
    uint64_t cycle_count;      // Total cycles completed
    std::string last_error;    // Error message
};

Performance Monitoring

// Monitor cycle timing
auto start = std::chrono::high_resolution_clock::now();
robot->updateAllNetworks();
auto end = std::chrono::high_resolution_clock::now();

auto duration = std::chrono::duration_cast<std::chrono::microseconds>(end - start);
if (duration.count() > 3000) {  // Warn if > 3ms (75% of 4ms cycle)
    std::cout << "Cycle time exceeded: " << duration.count() << "μs" << std::endl;
}

Hardware Setup

Requirements

For Development:

Network Setup:

# Configure EtherCAT interface
sudo ip link set eth0 up
sudo ethtool -s eth0 speed 100 duplex full autoneg off

# Check EtherCAT slaves
sudo ethercat slaves

Troubleshooting

Common Issues

1. “Failed to initialize EtherCAT master”

2. “No slaves detected”

3. “Working counter mismatch”

4. Motor not enabling

Debug Output

Enable detailed logging:

// In motor_controller.hpp, change line 16:
#define MOTOR_DEBUG_LOGGING 1

Building Your ROS2 SDK

  1. Node Structure:
    • Main humanoid controller node
    • Safety monitor node
    • Diagnostic publisher node
  2. Topics:
    • /joint_states - Current robot state
    • /joint_trajectory - Motion commands
    • /emergency_stop - Safety trigger
    • /diagnostics - System health
  3. Services:
    • /enable_motors - Enable/disable motors
    • /home_robot - Move to home position
    • /clear_faults - Reset motor faults
  4. Parameters:
    • Joint names and motor mappings
    • Safety limits per joint
    • Control gains

Next Steps

  1. Start Simple: Single motor, single network
  2. Add Complexity: Multiple motors on one network
  3. Scale Up: Multiple networks for full humanoid
  4. Optimize: Real-time performance tuning
  5. Integrate: Full ROS2 ecosystem integration

The Draco4 system provides a robust foundation for your humanoid robot control. Focus on understanding the hierarchical architecture and building your ROS2 layer incrementally on top of the existing real-time motor control capabilities.