Home | API Reference | Developer Guide | Code Analysis | Usage Examples —
The Draco4 Multi-Motor EtherCAT Control Framework is a sophisticated real-time control system designed for complex robotic applications. The architecture provides layered abstraction from individual motor control up to multi-network robot coordination, with comprehensive safety systems, automatic motor detection, and configuration-driven parameter management.
The framework implements a hierarchical multi-layer control architecture:
robot_controller.cpp
)network_controller.cpp
)motor_controller.cpp
)Provides configuration-driven motor constants and parameters with fallback defaults.
Key Functions:
getCountsPerRev()
(line 15): Returns encoder resolution from config or default 524288 counts/revgetGearReductionRatio()
(line 22): Returns gear ratio from config or default 7.75:1getRatedTorqueMNm()
(line 29): Returns rated torque from config or default 6000 mNm (6 Nm)getMaxTorqueMNm()
(line 36): Returns maximum torque limit from config or default 3000 mNmgetMinTorqueMNm()
(line 43): Returns minimum torque (negative of max) for bidirectional controlgetTorqueRampRate()
(line 50): Returns torque ramping rate from config or default 200 mNm/cyclegetMaxPositionChangePerCycle()
(line 57): Calculates maximum safe position change per cycle (4 revolutions worth of encoder counts)Purpose: Acts as a safety layer providing fallback constants when configuration files aren’t available while allowing motor-specific tuning when configs are loaded.
Implements comprehensive CSV configuration file parsing for motor parameters.
Core Classes:
MotorConfigParser::Parameter
(line 23): Parses and stores individual parameter values with automatic type detection (hex, decimal, float, string)MotorConfigParser
(line 82): Main configuration parser classKey Functions:
parseCSV()
(line 88): Main entry point that reads and parses entire CSV configuration fileparseLine()
(line 139): Parses individual CSV lines in format: INDEX, SUBINDEX, VALUEvalidateParameters()
(line 173): Validates critical parameters like encoder resolutiongetControlGains()
(line 216): Extracts PID gains for position, velocity, and current control loopsgetMotorSpecs()
(line 255): Extracts motor hardware specifications (encoder resolution, max speed, rated current)getSafetyLimits()
(line 281): Extracts position and torque safety limitscalcVelScale()
(line 309): Calculates velocity scaling factor based on encoder and velocity resolutiongetGearReductionRatio()
(line 321): Calculates gear ratio from motor/shaft revolution parametersgetRatedTorqueMNm()
(line 346): Converts internal torque units to millinewton-metersprintSummary()
(line 420): Displays comprehensive configuration summaryPurpose: Enables motor-agnostic operation by loading motor-specific parameters from CSV files, supporting different motor models (JD8, JD10, JD12) with their unique characteristics.
Main motor control class implementing EtherCAT-based control for individual motors.
Constructor & Lifecycle:
MotorController()
(line 19): Initializes motor controller with network reference, slave index, and update frequency~MotorController()
(line 43): Cleanup that stops motor safelyCore Control Functions:
update()
(line 50): Main control loop called every cycle - handles torque ramping, position/velocity updates, and fault recoveryenable_motor()
(line 68): Implements CIA402 state machine to transition motor from shutdown to operational statedisable_motor()
(line 100): Safely shuts down motor and clears all commandsControl Mode Functions:
set_velocity_rpm()
(line 120): Sets target velocity with safety checks and mode switchingset_position_counts()
(line 158): Sets target position with gear ratio compensation (user commands output shaft, PDO controls motor shaft)set_torque_millinm()
(line 199): Sets target torque with validation and mode switchingFeedback Functions:
getMotorRPM()
(line 257): Returns motor shaft RPM with gear ratio scaling to output shaftgetOutputRPM()
(line 284): Returns output shaft RPM directlygetPosition()
(line 298): Returns motor shaft position in encoder countsgetOutputPos()
(line 308): Returns output shaft position with gear ratio compensationgetTorque()
(line 320): Returns actual torque in millinewton-metersState Management:
getStateStr()
(line 236): Returns human-readable CIA402 state stringget_motor_state()
(line 364): Returns structured motor state enumhas_fault()
(line 344): Checks for motor fault conditionsclear_faults()
(line 352): Resets motor faultseStop()
(line 393): Emergency stop with immediate torque ramp to zeroInternal Control Logic:
enable_motor_sequence()
(line 412): Implements CIA402 state machine transitions (shutdown→ready→switched on→operational)ramp_torque_command()
(line 501): Implements safe torque ramping to prevent mechanical shockupdate_position_command()
(line 534): Handles position control with maximum step limitingupdate_velocity_command()
(line 558): Handles velocity control with gear ratio scalinghandle_fault_recovery()
(line 594): Initiates fault recovery by ramping torque to zeroConfiguration Management:
loadConfig()
(line 603): Loads motor configuration from CSV fileuploadConfig()
(line 642): Uploads complete configuration to motor via SDOuploadCriticalParam()
(line 681): Uploads only critical parameters for faster startupPurpose: Implements the complete control stack for a single motor, handling real-time control, safety systems, and motor-specific configuration.
Provides motor type detection and configuration management.
Core Functions:
MotorManager()
(line 14): Initializes with default motor type mappingsinitializeDefaultMappings()
(line 20): Sets up product ID to motor type mappings for JD8, JD10, JD12detectMotorType()
(line 40): Identifies motor type from EtherCAT product IDgetMotorInfo()
(line 53): Returns complete motor information including config file pathgetConfigFilePath()
(line 64): Returns appropriate configuration file for motor typeregisterMotorType()
(line 85): Registers new motor types with product IDs and config filesPurpose: Enables automatic motor detection and configuration file selection based on detected motor hardware, supporting seamless multi-motor setups with different motor types.
Handles EtherCAT SDO (Service Data Object) communication for uploading configuration parameters.
Core SDO Operations:
upload32()
(line 28): Uploads 32-bit parameters with validation and verificationuploadFloat()
(line 76): Uploads floating-point parameters with motor format conversiondownload32()
(line 124): Downloads 32-bit parameters for verificationverify32()
(line 144): Verifies uploaded parameters by reading them backverifyFloat()
(line 163): Verifies uploaded floating-point parametersHigh-Level Configuration Upload:
uploadControlGains()
(line 184): Uploads all PID control gains (position, velocity, current)uploadMotorSpecs()
(line 256): Uploads motor specifications (encoder resolution, max speed)uploadSafetyLimits()
(line 289): Uploads position and torque safety limitsuploadComplete()
(line 313): Uploads complete configuration in priority orderuploadCriticalParameters()
(line 348): Uploads only critical parameters for faster startupInternal Helpers:
performSDOWrite()
(line 443): Low-level SOEM SDO write operationperformSDORead()
(line 462): Low-level SOEM SDO read operationvalidateParameter()
(line 489): Validates parameter values for safetyfloatToMotorFormat()
(line 521): Converts floating-point to motor’s internal formatPurpose: Provides the communication layer between the configuration system and the motor hardware, ensuring parameters are safely uploaded and verified.
Implements the EtherCAT network management layer.
Network Lifecycle:
NetworkController()
(line 19): Initializes EtherCAT master with interface and timing parametersinitialize()
(line 46): Initializes EtherCAT master on specified network interfacescanNetwork()
(line 76): Scans for EtherCAT slaves on the networkconfigureSlaves()
(line 100): Maps process data and configures distributed clocksstartOperation()
(line 149): Transitions all slaves to operational statestopOperation()
(line 232): Safely stops network operationReal-Time Communication:
performCommunicationCycle()
(line 287): Executes one EtherCAT communication cycle (send/receive PDO data)flushControlWordUpdate()
(line 556): Forces immediate PDO update for control word changesData Access:
getOutputPDO()
(line 318): Returns output PDO pointer for specific slavegetInputPDO()
(line 327): Returns input PDO pointer for specific slavegetNetworkStatus()
(line 336): Returns comprehensive network statusgetSlaveInfo()
(line 363): Returns detailed information about specific slaveInternal Management:
initializeSlaveInfo()
(line 430): Collects slave information after network scansetupPDOPointers()
(line 459): Maps PDO structures to slave memory regionscheckSlaveStates()
(line 372): Verifies all slaves remain operationalMotor Detection Integration:
getDetectedMotorInfo()
(line 500): Returns motor type information for specific slavegetAllDetectedMotors()
(line 531): Returns motor information for all detected slavesPurpose: Manages the complete EtherCAT network infrastructure, providing real-time communication and slave management services to motor controllers.
Provides multi-network coordination for complex robotic systems.
Network Management:
RobotController()
(line 19): Initializes robot controller with global timing parametersaddNetwork()
(line 42): Adds new EtherCAT network with configuration validationremoveNetwork()
(line 86): Safely removes network from robot systemgetNetwork()
(line 107): Returns network controller by nameRobot-Level Operations:
initializeAllNetworks()
(line 134): Initializes all networks in parallelstartAllNetworks()
(line 192): Starts operation on all networks with coordinated timingupdateAllNetworks()
(line 278): Performs parallel communication cycles across all networksemergencyStopAll()
(line 330): Emergency stop across entire robot systemshutdownAll()
(line 358): Graceful shutdown of all networksStatus and Diagnostics:
allNetworksOperational()
(line 416): Checks if all networks are operationalgetRobotStatus()
(line 432): Returns comprehensive robot system statusgetAllNetworkStatus()
(line 458): Returns status of all individual networksInternal Coordination:
updateNetworkParallel()
(line 524): Updates individual network in parallel threadupdateTimingStatistics()
(line 548): Tracks timing performance across networksvalidateNetworkConfig()
(line 490): Validates network configuration parametersPurpose: Orchestrates multiple EtherCAT networks with synchronized timing, enabling complex robotic systems with distributed motor control across multiple network segments.
Configuration Data Flow:
Real-Time Control Data Flow:
Safety Data Flow:
Phase 1: Robot Controller Initialization
RobotController()
constructor (line 19)
Phase 2: Network Configuration
addNetwork()
(line 42)
Phase 3: Network Infrastructure Setup
initializeAllNetworks()
(line 134)
NetworkController::initialize()
(line 46)
Phase 4: EtherCAT Network Discovery
startAllNetworks()
(line 192)
NetworkController::scanNetwork()
(line 76)
NetworkController::configureSlaves()
(line 100)
Phase 5: Motor Detection and Configuration
initializeSlaveInfo()
(line 430)
MotorController::loadConfig()
(line 603)MotorConfigParser::parseCSV()
(line 88)
MotorController::uploadConfig()
(line 642)
Phase 6: EtherCAT Operational State
NetworkController::startOperation()
(line 149)
Main Control Cycle (typically 250Hz)
RobotController::updateAllNetworks()
(line 278)
Per-Network Communication Cycle
NetworkController::performCommunicationCycle()
(line 287)
Per-Motor Control Update
MotorController::update()
(line 50)
Control Mode Execution:
ramp_torque_command()
(line 501)
update_position_command()
(line 534)
update_velocity_command()
(line 558)
CIA402 State Machine Implementation:
MotorController::enable_motor()
(line 68)
enable_motor_sequence()
(line 412) implements:
Fault Detection:
MotorController::has_fault()
(line 344)Emergency Stop Sequence:
RobotController::emergencyStopAll()
(line 330)
Graceful Shutdown:
RobotController::shutdownAll()
(line 358)
Parameter Upload Sequence:
MotorConfigParser
validates and organizes parametersMotorSDOManager
uploads in priority order:
Real-Time Parameter Validation:
The Draco4 Multi-Motor EtherCAT Control Framework represents a comprehensive solution for high-performance robotic control applications. Its hierarchical architecture, robust safety systems, and configuration-driven approach make it suitable for complex multi-motor systems requiring precise, synchronized control with real-time performance guarantees.
The framework’s design emphasizes:
This makes it an excellent foundation for advanced robotic systems requiring reliable, high-performance motor control.