Skip to content

AGENTS.md

Latest commit

 

History

History
113 lines (89 loc) · 3.78 KB

AGENTS.md

File metadata and controls

113 lines (89 loc) · 3.78 KB

SO-ARM101 Robot Control

A web-based control and visualization application for the SO-ARM101 robotic arm.

Project Overview

This project provides a React-based interface for controlling and monitoring the SO-ARM101 6-DOF robotic arm via WebSocket communication. It includes:

  • 3D Visualization: Real-time URDF-based robot model rendering using React Three Fiber
  • Joint Control: Individual and synchronized control of all 6 joints
  • Calibration System: Zero position setting, limit recording, and dead zone configuration
  • Torque Control: Freeup/lock motors for manual movement during calibration
  • Mock Server: Node.js WebSocket server that simulates robot behavior for development

Tech Stack

Category Technology
Frontend React 18 + TypeScript
Build Tool Vite
3D Rendering React Three Fiber + Three.js
URDF Loading urdf-loader
State Management Zustand
Styling Tailwind CSS
Mock Server Node.js + ws

Project Structure

robot_control/
├── public/robot/           # URDF and STL mesh files
├── src/
│   ├── components/         # React components
│   │   ├── calibration/    # CalibrationPanel
│   │   ├── connection/     # ConnectionPanel
│   │   ├── controls/       # JointControlPanel, JointSlider, ModeSwitch
│   │   └── viewer/         # RobotViewer, RobotModel, Scene
│   ├── constants/          # Robot joint configurations
│   ├── hooks/              # useWebSocket, useURDFLoader
│   ├── services/           # WebSocket service
│   ├── stores/             # Zustand store (robotStore)
│   ├── types/              # TypeScript type definitions
│   └── utils/              # Unit conversion utilities
├── server/                 # Mock WebSocket server
│   ├── index.js            # Server entry point
│   └── robotSimulator.js   # Robot state simulator
└── protocol.md             # WebSocket protocol documentation

Key Files

  • src/stores/robotStore.ts - Central state management with Zustand
  • src/services/websocketService.ts - WebSocket client implementation
  • src/hooks/useWebSocket.ts - React hook for WebSocket operations
  • src/components/viewer/RobotModel.tsx - URDF 3D model component
  • src/constants/robot.ts - Joint configurations and limits
  • server/robotSimulator.js - Simulates robot arm physics

Robot Configuration

6 joints with motor IDs 1-6:

Motor ID Joint Name Limits (rad)
1 shoulder_pan -1.92 to 1.92
2 shoulder_lift -1.75 to 1.75
3 elbow_flex -1.69 to 1.69
4 wrist_flex -1.66 to 1.66
5 wrist_roll -2.74 to 2.84
6 gripper -0.17 to 1.75

Running the Project

Development

# Start mock WebSocket server
node server/index.js

# Start frontend dev server
npm run dev

Production Build

npm run build

WebSocket Protocol

See protocol.md for complete WebSocket message format documentation.

Key message types:

  • list_motors - Query available motors
  • get_positions / positions - Get/receive joint positions
  • set_position / set_all_positions - Control joint positions
  • subscribe / unsubscribe - Real-time position updates
  • freeup / lock - Motor torque control

Features

Control Mode

  • Readonly: View real-time position data, sliders disabled
  • Control: Send position commands via sliders

Calibration

  • Set current position as zero reference
  • Record min/max limits by moving robot to positions
  • Configure dead zones per joint
  • Save/load calibration to localStorage

Torque Control

  • Freeup: Disable motor torque for manual positioning
  • Lock: Enable motor torque for servo control