Actuator control and Feetech drivers

Control layers

The actuator node translates animation PAU and direct posture commands through the selected motor mappings and hardware factories. Feetech handles serial hardware transport, torque and register-level behavior. Waist and arm support can be launched separately. A browser command passes through several layers before a motor moves; inspect each layer independently.

ActuatorsNode waits briefly for /hr/motors_init, then loads /hr/motors. Missing motor configuration is logged and prevents normal actuator startup. The configuration service controls combined/separate/synchronized modes, animation/direct topics, groups and startup animation control. Do not infer successful calibration from node existence.

Main ROS interfaces

Interface	Type / role
/hr/animation/current_state	hr_msgs/msg/Pau, animation input by default
/hr/actuators/pose	hr_msgs/msg/TargetPosture, direct named values
/hr/actuators/offsets	TargetPosture, updates named offset settings
/hr/actuators/set_control	hr_msgs/srv/SetActuatorsControl, select control mode for names/groups
/hr/actuators/current_state	Pau, current actuator representation
/hr/actuators/set_torque_enable	Named motor torque service used by WebUI
/hr/actuators/set_all_torque	Global torque topic used by WebUI
/hr/actuators/feetech_reload	Request driver reload after configuration change

Names can be overridden through configuration; use the running graph. The actuator declaration reference, Feetech reference and message definitions include exact types and registration expressions.

Read-only inspection:

ros2 node list
ros2 topic info -v /hr/actuators/current_state
ros2 interface show hr_msgs/msg/TargetPosture
ros2 interface show hr_msgs/srv/SetActuatorsControl
ros2 service list -t

Units, bounds and acknowledgements

PAU coefficients, mapped joint values and raw servo steps are different representations. Limits and conversion rules come from the selected assembly's motor settings and mapper configuration. Use calibrated profile values, not copied coordinates from another head/body.

The WebUI's single-motor endpoint publishes a posture and returns immediately. That acknowledgement does not verify hardware feedback. Torque control differs from choosing animation/direct control. Releasing torque can let unsupported mechanisms move under gravity.

Offset updates can persist through the configuration backend. Neutral reset changes servo reference/calibration and must not be conflated with setting a temporary pose. Back up motor settings before changing either.

Hardware write suppression and development

The current stack contains fake-hardware support and a Feetech write-disable environment option (HR_FEETECH_DISABLE_WRITES). Determine which drivers and writes that option covers from the active node and launch; do not treat it as a certified whole-robot isolation switch. Main-stack launch defaults can still enable waist/arms and infer head actuation from robot identity.

Actuator profiling is optional through HR_ACTUATORS_PROFILE; output can be a file or directory. HR_ACTUATORS_PROFILE_LIMIT controls summary length. Profiling writes host/container files and should use an appropriate writable diagnostics location.

Failure diagnosis

1. Confirm robot identity, selected assemblies and loaded /hr/motors state.
2. Check serial device paths, permissions and exclusive bus access.
3. Inspect command publication, control-mode service results and hardware driver logs.
4. Check actual torque, configured bounds and register feedback before repeating commands.
5. If config reload fails, compare saved assembly files, merged motor parameters and driver startup state.

No movement, torque changes, register writes or neutral changes were executed to author this guide.

Evidence: head-ros-nodes/ros/hr_actuators/scripts/actuators_node.py, actuator sources/config nodes, ros_feetech/scripts/feetech_node.py, WebUI ROS adapter and hr_ros2/launch/main_stack.launch.py.