unity2moveit2/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Unity-MoveIt2 integrated robotic arm simulation system supporting 1-9 DOF (degrees of freedom) manipulators. The system combines Unity's visualization capabilities with MoveIt2's path planning, designed for assembly task feasibility analysis in confined spaces.

Architecture: Unity frontend (Windows) + ROS2 Jazzy backend (Ubuntu/Docker) communicating via ROS-TCP-Connector.

Build & Run Commands

ROS2 Backend (Docker)

# Start ROS2 services (PowerShell/CMD on Windows)
cd docker
docker-compose up -d

# Check service status
docker-compose ps

# View logs
docker-compose logs -f ros2-unity

# Enter container for ROS2 commands
docker exec -it unity-ros2-system bash

# Stop services
docker-compose down

# Optional: Start with monitoring service
docker-compose --profile monitoring up -d

Unity Project

• Open unity-project/ in Unity Hub (Unity 2022.3 LTS recommended, specifically 2022.3.57f1c2)
• The project uses the Unity Test Framework for testing
• Main scene: Open the primary scene and press Play

Development Scripts (PowerShell)

Located in scripts/:

• quick-deploy.ps1 - Quick deployment script
• start-ros2-docker.ps1 - Start ROS2 Docker container
• configure-ros-connection.ps1 - Configure Unity-ROS connection
• unity-check.ps1 - Validate Unity environment

System Architecture

Communication Flow

Unity Frontend (Windows)
    ↕ ROS-TCP-Connector (Port 10000)
ROS2 Jazzy Backend (Ubuntu/Docker)
    ↕ MoveIt2 Planning
Robot Control & Simulation

Key Components

Unity Side (unity-project/Assets/Scripts/):

• Core/UniversalRobotAdapter.cs - Handles 1-9 DOF robot configuration and joint control
• Core/InteractiveEndEffectorController.cs - 6DOF drag-and-drop end-effector control
• Core/VisualizationEngine.cs - Trajectory and collision visualization (uses partial classes split across multiple files: Trajectory, Collision, JointState, Workspace, Utils)
• Communication/ROSTCPBridge.cs - ROS2 TCP communication bridge with automatic reconnection
• Communication/MessageConverter.cs - Unity ↔ ROS message conversion
• Managers/RobotManager.cs - Overall robot state management

ROS2 Side (ros2-workspace/src/unity_moveit2_bridge/):

• MoveIt2 integration for path planning
• IK/FK computation services
• Collision detection services
• Trajectory execution monitoring

Assembly Definitions

The project uses Unity Assembly Definitions (.asmdef):

• Core.asmdef - Core robot control and adaptation
• Communication.asmdef - ROS communication layer
• Tests.asmdef - Testing infrastructure
• UnityMoveIt2.RosMessages.asmdef - ROS message types

When modifying scripts, ensure they're in the correct assembly and reference dependencies properly.

Configuration

Network Configuration

ROS2 Connection:

• Default IP: 127.0.0.1 (localhost)
• Default Port: 10000
• Configurable in Unity Inspector on ROSTCPBridge component
• Ensure Windows Firewall allows port 10000-10002

Docker Network:

• Bridge network on subnet 172.20.0.0/16
• Exposed ports: 9090 (Rosbridge), 10000-10002 (ROS-TCP-Endpoint)
• ROS_DOMAIN_ID: 0 (configurable in docker/docker-compose.yml)

Robot Configuration

Robots are configured with:

• DOF (1-9 supported)
• URDF/SRDF paths
• Joint limits, velocity/acceleration constraints
• Planning group names

Configuration is set in Unity Inspector or via YAML files in configs/robots/.

Coordinate System & Units

• Units: Meters (m) for position, radians (rad) for rotation
• Coordinate Frame: Right-handed coordinate system
  • Base frame: base_link (Z-up convention in ROS, converted to Unity's Y-up)
  • End-effector: tool0 or ee_link
• Unity ↔ ROS Conversion: Handled by MessageConverter.cs
  • Unity uses Y-up, ROS uses Z-up
  • Quaternions are normalized during conversion

Common Development Tasks

Adding a New Robot

1. Create URDF/SRDF files in configs/robots/<robot_name>/
2. Use MoveIt Setup Assistant to generate MoveIt configuration
3. Update UniversalRobotAdapter configuration in Unity Inspector:
   • Set DOF
   • Assign base_link and end_effector transforms
   • Configure joint limits
4. Test IK/FK and collision detection

Modifying Communication

When adding new ROS messages or services:

1. Generate C# message classes using ROS-TCP-Connector tools
2. Place generated files in unity-project/Assets/RosMessages/
3. Update ROSTCPBridge.cs to register new topics/services
4. Update MessageConverter.cs if custom conversions are needed

Testing

Run tests from:

• Unity Test Runner (Window → General → Test Runner)
• Test scripts in unity-project/Assets/Scripts/Tests/:
  • ConnectionTest.cs - ROS connection validation
  • IntegrationTest.cs - End-to-end integration tests
  • PerformanceBenchmark.cs - Performance metrics

Debugging Connection Issues

1. Check Docker container status: docker-compose ps
2. Verify ROS2 endpoint is running: docker logs unity-ros2-system
3. Check Unity console for connection errors
4. Test network connectivity (PowerShell): Test-NetConnection -ComputerName 127.0.0.1 -Port 10000
5. Verify ROS_DOMAIN_ID matches between Unity and ROS2
6. Check firewall rules on Windows
7. Inside Docker container, verify ROS2 nodes: docker exec -it unity-ros2-system bash -c "ros2 node list"

Critical Implementation Details

Asynchronous Operations

Many ROS operations are asynchronous:

• IK/FK service calls use Unity coroutines or Tasks
• Trajectory planning has timeout handling (default 5s)
• ROSTCPBridge includes retry logic with exponential backoff

Performance Considerations

• Update Rate: Joint states publish at ~50 Hz (configurable via publishRate in ROSTCPBridge)
• Message Buffering: Max 100 messages queued (configurable via messageBufferSize)
• Frame Budget: Process max 10 messages per Unity frame to avoid blocking
• For large-scale planning operations, use background threads to avoid Unity main thread blocking

Collision Detection

• Real-time collision checking via MoveIt2's FCL integration
• Collision objects synchronized from Unity to ROS via planning_scene topic
• Collision visualization handled by VisualizationEngine.cs

Feasibility Analysis (Assembly Tasks)

The system includes extensions for confined-space assembly analysis:

• Workspace reachability heatmaps
• Collision clearance analysis
• Base pose optimization
• Environment sensitivity scanning

See SYSTEM_DESIGN.md sections 1060-1160 for detailed API.

Important Files to Review

• README.md - Project overview and features
• SYSTEM_DESIGN.md - Detailed system architecture (includes coordinate systems, message definitions, deployment configs, and assembly analysis extensions)
• DEPLOYMENT_GUIDE.md - Step-by-step deployment for Windows + Ubuntu
• DOCKER_DEPLOYMENT_GUIDE.md - Docker-specific deployment
• docker/docker-compose.yml - Container orchestration config

Known Issues & Limitations

• Windows 10 supported but Windows 11 recommended for better WSL2 support
• ROS2 Jazzy recommended; Humble also supported but not fully tested
• Maximum 9 DOF due to planning complexity constraints
• WebGL builds require additional CORS configuration for ROS communication

Dependencies

Unity Packages:

• ROS-TCP-Connector (for ROS2 communication)
• Unity Robotics URDF Importer
• Unity Test Framework
• TextMeshPro (UI)

ROS2 Packages (installed in Docker):

• ros-jazzy-ros-tcp-endpoint
• ros-jazzy-moveit
• ros-jazzy-ros2-control
• ros-jazzy-ros2-controllers
• ros-jazzy-robot-state-publisher

Docker:

• Docker Desktop 20.10+
• WSL2 (Windows only)

Project-Specific Conventions

• Namespaces: All Unity scripts use UnityMoveIt2.<Module> (e.g., UnityMoveIt2.Core, UnityMoveIt2.Communication)
• Logging: Use Unity's Debug.Log with prefixes like [ROSTCPBridge] for component identification
• Error Handling: Critical errors invoke events (e.g., OnRobotError) for UI feedback
• Code Style: Follow C# naming conventions (PascalCase for public, camelCase for private)
• All ROS message types use Msg suffix (e.g., JointStateMsg, PoseStampedMsg)
• Scripts are bilingual with Chinese comments - maintain both English and Chinese documentation where present
• Partial Classes: Large components like VisualizationEngine use partial classes to maintain the 900-line limit per file

Claude Code 工作规范 (Working Guidelines)

语言与沟通 (Language & Communication)

• 响应语言: 始终使用中文回答用户问题和提供说明
• 代码注释: 保持现有的双语注释风格（中英文并存），新增注释时遵循相同模式
• 文档编写: 技术文档可使用英文，但解释性内容优先使用中文

MCP 服务器使用 (MCP Server Usage)

项目已配置以下 MCP 服务器，请根据场景合理使用：

Context7 MCP (mcp__context7_*)

• 用途: API 版本查询、技术文档检索、最佳实践查找
• 适用场景:
  • 查询 Unity API 版本兼容性
  • 检索 ROS2 Jazzy 特定功能文档
  • 查找 MoveIt2 规划器配置示例
  • 解决技术栈版本冲突问题
• 使用时机: 当遇到 API 版本问题或需要查阅官方文档时

代码文件管理 (Code File Management)

文件大小限制

• 硬性规则: 每个代码文件不得超过 900 行
• 重构触发条件:
  • 单个文件接近 800 行时，主动建议重构
  • 发现功能耦合严重时，提出拆分方案
• 拆分策略:
  • 按功能模块拆分（如将 ROSTCPBridge.cs 拆分为连接管理、消息处理、状态同步等）
  • 使用部分类（partial class）保持逻辑连贯性
  • 遵循单一职责原则（SRP）
• 重构流程:
  1. 分析文件结构，识别独立功能模块
  2. 提出拆分方案并征得用户同意
  3. 创建新文件并迁移代码
  4. 更新 Assembly Definitions 和引用关系
  5. 验证编译和功能完整性

文档创建权限

• 禁止擅自创建: 未经用户明确允许，不得创建新文档文件（.md, .txt, .pdf 等）
• 需要授权的场景:
  • 新增设计文档
  • 创建 API 说明
  • 添加使用指南
  • 生成报告文件
• 允许的操作:
  • 修改现有文档
  • 更新 CLAUDE.md 等已存在的指导文件
  • 在代码中添加注释和 XML 文档
• 请求流程: 当需要创建文档时，先向用户说明原因和内容概要，获得明确许可后再执行

测试代码管理 (Test Code Management)

禁止创建新测试文件

• 硬性规则: 不得创建新的测试脚本或测试文件
• 原因: 确保测试体系的一致性、完整性和可维护性

允许的测试操作

• ✅ 修改现有测试: 在 Assets/Scripts/Tests/ 下已有的测试文件中添加或修改测试用例
• ✅ 扩展测试覆盖: 在现有测试类中增加新的测试方法
• ✅ 修复测试问题: 更新失败的测试用例
• ✅ 优化测试逻辑: 改进现有测试的断言和验证逻辑

现有测试文件

项目当前包含以下测试文件，所有测试工作应在这些文件基础上进行：

• ConnectionTest.cs - ROS 连接测试
• IntegrationTest.cs - 端到端集成测试
• PerformanceBenchmark.cs - 性能基准测试
• EndToEndTest.cs - 完整流程测试
• SystemOptimizer.cs - 系统优化测试
• TestRunner.cs - 测试运行器

测试修改原则

1. 保持测试结构: 维护现有的测试组织和命名规范
2. 兼容性优先: 新增测试不应破坏现有测试的运行
3. 充分注释: 新增测试用例必须包含清晰的中文注释说明
4. 独立性: 确保测试用例之间相互独立，不依赖执行顺序

代码质量要求 (Code Quality Standards)

• 编译验证: 修改代码后必须确保项目能够编译通过
• 功能完整性: 重构或修改时保持原有功能不受影响
• 性能考虑: 注意 Unity 主线程阻塞，合理使用异步操作
• 错误处理: 所有异步操作和 ROS 通信必须包含异常处理
• 日志规范: 使用统一的日志前缀，便于调试和追踪

工作流程建议 (Workflow Recommendations)

1. 阅读优先: 修改代码前先充分阅读相关文件和依赖
2. 小步迭代: 每次修改范围适中，便于验证和回滚
3. 主动沟通: 遇到重大架构决策时，先与用户讨论方案
4. 文档同步: 代码变更后及时更新相关文档和注释
5. 使用 TodoWrite: 对于复杂任务，使用待办事项工具跟踪进度