CLW Matcha Robot

ROS 2 workspace for a SCARA “Matcha” robot: simulation and control stack for a 4-DoF arm with MoveIt 2, ros2_control, URDF/Xacro description, waypoint tooling, and a PyQt5 operator GUI.

Repository Note

Robot-Matcha-V2-CLW-

This repository is actively maintained here and follows the current project style and workflow.

GitHub metadata (for repo settings)

Paste these into Settings → General (description) and Topics on GitHub.

Description

ROS 2 workspace for a 4-DoF SCARA Matcha robot: MoveIt 2, ros2_control, URDF/Xacro, waypoint tooling, and a PyQt5 GUI for motion sequences (Home, Safe, Target, Whisk, Clean).

Topics (space-separated for the Topics field)

ros2 moveit2 ros2-control scara robotics manipulator pyqt5 rviz2 urdf xacro trajectory-planning waypoints python simulation ros-jazzy

Adjust ros-jazzy to your ROS 2 distro (ros-humble, ros-iron, etc.) or remove if you support multiple distros.

What’s in this workspace

Package	Role
scara_description	URDF/Xacro, RViz assets, ros2_control configuration
scara_moveit_config	MoveIt 2 planning, SRDF, controllers, kinematics
scara_waypoint_controller	Waypoint / Cartesian tooling, RViz panels, demo scripts
scara_matcha_gui	PyQt5 GUI: joint control in degrees, sequences (e.g. Home / Safe / Target / Whisk / Clean), topics for arm controllers

Typical flow: bring up the robot (or simulation), launch MoveIt or the GUI as needed, and drive trajectories or predefined motions from the GUI or waypoint tools.

Matcha Control Panel (GUI)

The scara_matcha_gui app is organized as tabbed control panels so operators can tune motion, bowl positions, and sequence behavior from one place.

Tabs and features

• ROS 2 GUI — Matcha

  • ROS wire mode selector (publish angles as radians or degrees).
  • Live base-to-target and base-to-clean bowl distance readout.
  • RViz helper line toggle for visual alignment.

• Height Adjustment

  • Home height and safe-zone height controls for joint_3.
  • Safe height is enforced by motion helpers before bowl work.

• Bowl adjustment

  • Target/clean bowl diameter in cm (used by markers and bowl-motion bounds).
  • Direct joint-angle setpoints for target and clean bowls.
  • UV-based placement (0..1) with IK mapping to bowl positions.

• Parameters

  • Whisk speed, motion duration, max angles, and ramp timings.
  • Real-time tuning of motion behavior without code edits.

• Sequence settings

  • Step-level Whisk timing controls (Step 1a/1b, Step 2, Step 3, finish pause).
  • Clean-before-whisk checkbox (default unchecked).
  • Idle clean threshold (default 3.0 min): if no Whisk start for longer than this threshold, clean prelude is forced even when checkbox is unchecked.
  • First Whisk after app start always runs clean prelude (no prior whisk timestamp).

• Maintenance

  • Session uptime.
  • Counters for completed Whisk actions, completed Clean actions, completed clean patterns, and abort count.
  • Reset metrics button.
  • Open logs folder button (opens session log directory in file explorer).

• Actions

  • Main sequence buttons: Home, Safe Zone, Target Bowl, Whisk, Clean, Abort.
  • Execution monitor (countdown + progress bar) for oscillation phases.
  • Progress bar turns green only when full Whisk sequence has completed.
  • Status panel for current sequence state.
  • Action history panel with timestamps and clear-history button.

Sequence behavior summary

• Home: ordered move (joint_3 -> joint_1 -> joint_2).
• Safe Zone: runs Home first, then safe pose.
• Target Bowl: Home -> Safe -> target bowl approach.
• Clean: Home -> Safe -> clean bowl -> clean pattern (Step 1a/1b clean-linear mode).
• Whisk: Home -> Safe -> optional/forced clean prelude -> whisk steps -> mandatory finish (Clean -> Safe -> Home).
• Abort: stop active workers/timers and return Home.

Logging and session files

• Logs are written to logs/ at workspace root.
• A new file is created each app session/boot:
  • logs/session_YYYYMMDD_HHMMSS.txt
• Session log includes:
  • Action/history entries shown in UI.
  • Maintenance metric events (whisk_complete, clean_action_complete, clean_pattern_complete, abort, metrics_reset).

Screenshots

Screenshots are in images/.

File	Description
images/Screenshot1.png	GUI / workspace view 1
images/Screenshot2.png	GUI / workspace view 2

Demonstration Video

Demonstration video:

• images/demo_matcha_robot.mp4

Requirements

• ROS 2 (distribution aligned with your team’s setup)
• Python 3 with PyQt5 for scara_matcha_gui
• MoveIt 2, ros2_control, and related dependencies as declared in each package’s package.xml / CMakeLists.txt

Build

cd matcha_ws
source install/setup.bash
colcon build --symlink-install

Run

cd matcha_ws
source install/setup.bash
ros2 launch scara_matcha_gui matcha_with_robot.launch.py standalone_gui:=false

License

See individual packages (many use Apache-2.0 unless noted otherwise).