RoArm-M2-S — Teleoperation & VLM Agent

Control stack for the Waveshare RoArm-M2-S 4-DoF robotic arm.

Two modes: manual (Xbox / YOLO visual servoing) and autonomous (VLM agent — give it a task in plain English, it figures out the arm movements).

Direct ESP32 serial control — no ROS2 required.

---

Choose Your Platform

Platform	Folder	Notes
macOS	macos/	Native USB serial, no VM needed
Linux / Ubuntu	linux/	Full ROS2 support, Parallels docs

---

Shared SDK

roarm_controller.py — cross-platform Python SDK covering every ESP32 command (arm control, gripper, missions, WiFi, servos, file system). Both platform stacks import from this.

from roarm_controller import RoArmController

with RoArmController("/dev/cu.usbserial-0001") as arm:  # or /dev/ttyUSB0 on Linux
    arm.move_init()
    arm.joints_rad_ctrl(base=0, shoulder=0, elbow=1.57, hand=3.14)
    print(arm.get_feedback())

---

VLM Agent (macOS)

Autonomous arm control via local vision-language model. No training required.

python3 macos/agent/agent.py "pick up the red cup"
python3 macos/agent/agent.py --interactive
python3 macos/agent/agent.py --dry-run --no-arm "describe the scene"

See macos/agent/README.md for full setup and usage.

---

Manual Control Scripts

Script	Description
connect_arm.py	Test serial connection + print firmware feedback
routine.py	Pre-choreographed wave / bow / LED sequence
xbox_teleop.py	Real-time Xbox controller teleoperation
vision_teleop.py	YOLOv11 Nano visual servoing (tracks a target object)

---

Hardware Notes

• Power: 12V 5A supply required. USB alone cannot drive servos.
• Port: Use the middle USB-C port on the driver board (not the radar port on the edge).
• Protocol: ESP32 accepts newline-terminated JSON at 115200 baud.
• Conflict: Do not run roarm_driver or ros2_control simultaneously with these scripts.