How carpit680/giraffe works
Project Type and Purpose
• This is a full-stack, open-source ROS2 robotic manipulator project (“Giraffe v1.1”) that spans CAD assets, embedded firmware, hardware control scripts, ROS2 packages (description, control, hardware interface, MoveIt! config), and simulation. Its goal is to provide a low-cost, leader-follower robotic arm with both real-hardware and Gazebo/MoveIt! simulation support.
File Structure Analysis
• Top-level directories:
• CAD/ – all CAD models (MuJoCo XML, Gerber PCB, STEP/STL files)
• STservo_sdk/ – Python library for low-level servo communication
• giraffe_ws/src/ – ROS2 workspace containing four main packages:
– giraffe_description (URDF/XACRO, meshes, launch)
– giraffe_control (ROS2 node “giraffe_driver”, scripts, configs)
– giraffe_hardware (ros2_control SystemInterface plugin)
– giraffe_moveit_config (MoveIt! SRDF/URDF, planners, controllers)
• scripts/ – calibration and test scripts for servos
• requirements.txt, setup.py – Python packaging and dependencies
• assets/ – README images
Key README Insights
• Four ROS2 launch flows: display, simulation (Gazebo + rviz), moveit_sim, moveit_interface
• STservo_sdk drives Feetech motors via serial bus
• giraffe_control bridges ROS2 ↔ servos (subscribes to /command, publishes /feedback)
• giraffe_hardware implements ros2_control plugin for real-hardware drivers
• MoveIt! config package for motion planning
Main Components
A. CAD & Physical Components (hardware layer)
• 3D-printed parts (common, leader, follower)
• PCB (I²C mux, AS5600 encoders, Wemos D1 Mini MCU) for leader arm
• Feetech serial-bus servos and Servo Driver Board
B. Embedded Controller (firmware layer)
• Wemos D1 Mini + AS5600 encoders + TCA9548A mux
• Firmware that reads encoders and streams data / receives commands (via Wi-Fi or serial)
C. Low-Level Python SDK
• STservo_sdk (port_handler, protocol handler, sync read/write modules)
• scripts (st_configurator.py, sync_read/write examples)
D. ROS2 Software Layer
1. giraffe_description – URDF/XACRO + meshes + robot_state_publisher + joint_state_publisher
2. giraffe_hardware – hardware_interface::SystemInterface plugin (“GiraffeInterface”)
3. giraffe_control – ROS2 node “giraffe_driver” subscribing to /command, publishing /feedback
4. giraffe_moveit_config – MoveIt! planners, controllers, RViz config
E. Simulation Environment
• Gazebo Ignition Fortress + model spawner
• ros2_control controllers spawned for simulation
• RViz for visualization
F. Teleoperation / External Interfaces
• Teleop Tongs integration (Dex Teleop) via fiducials, separate project
Relationships & Data Flows
• Application Layer (user CLI / teleop GUI) → publishes JointTrajectory (or custom /command topic)
• giraffe_control node → uses STservo_sdk to send commands over serial to servo driver board → servos
• Servos & encoders → position feedback over bus → STservo_sdk → giraffe_control publishes /feedback
• giraffe_hardware plugin → also subscribes /command and publishes /feedback for ros2_control controllers
• move_group (MoveIt! 2) → executes trajectories via ros2_control controller_manager → giraffe_hardware
• Gazebo simulation: gazebo_ros2_control plugin binds model to controller_manager → mimics hardware
• URDF/XACRO → robot_state_publisher publishes transforms → RViz visualizes
Architectural Patterns & Principles
• Layered architecture: hardware → firmware → SDK → ROS2 middleware → planning/visualization
• Plugin pattern: ros2_control SystemInterface for hardware abstraction
• Publisher–Subscriber: ROS2 topics for decoupling nodes
• Configuration as code: YAML parameters for controllers, kinematics, joint limits
Essential Elements
• Layer separation: CAD/physical, firmware/embedded, SDK, ROS2 middleware, simulation/planning
• Notes on config: YAML files feed into nodes (annotate configuration inputs)