# Embodied_Arm **Repository Path**: dyed-string/Embodied_Arm ## Basic Information - **Project Name**: Embodied_Arm - **Description**: No description available - **Primary Language**: Unknown - **License**: GPL-3.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-04-28 - **Last Updated**: 2026-04-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # HorizonArm 项目开发者学习路线(X1/H1系列) 欢迎！您刚拿到 HorizonArm 项目，本文档将帮助您系统性地学习和掌握这个项目。 --- ## 🎯 学习路线总览 ``` 第0步: 了解项目结构 (5分钟) ↓ 第1步: 环境准备和验证 (10分钟) ↓ 第2步: SDK理论学习 (30分钟) ↓ 第3步: 5分钟快速上手 (5分钟) ↓ 第4步: 根据角色选择深入学习路径 (2-8小时) ↓ 第5步: 项目实践和集成 (持续) ``` --- ## 📂 第0步：了解项目结构 (5分钟) ### 项目目录总览 ``` Horizon_Arm/ ├── 📚 example/ ⭐ 从这里开始！ │ ├── README.md - 示例代码总导航和快速开始 │ ├── 示例代码总导航.md - 详细的示例代码导航 │ ├── SDK完全介绍.md - SDK完全介绍文档 │ ├── quickstart_guide.py - 5分钟快速入门 │ ├── control_sdk_examples/ - Control SDK示例 │ ├── ai_sdk_examples/ - AI SDK示例 │ └── developer_tools/ - 开发者工具 │ ├── 🔧 Embodied_SDK/ SDK源码（可查看） │ ├── __init__.py - 电机控制 │ ├── motion.py - 运动控制 │ ├── visual_grasp.py - 视觉抓取 │ ├── joycon.py - 手柄控制 │ ├── io.py - IO控制 │ ├── digital_twin.py - 数字孪生 │ ├── ai.py - AI集成 │ └── ... │ ├── 🔒 Horizon_Core/ 核心库（pyd封装） │ ├── Control_SDK/ - 控制核心（封装） │ ├── AI_SDK/ - AI核心（封装） │ ├── gateway.pyd - 通信网关 │ └── license.pyd - 授权管理 │ ├── ⚙️ config/ 配置文件 │ ├── calibration_parameter.json - 手眼标定参数 │ ├── embodied_config/ - 机械臂配置 │ ├── aisdk_config.yaml - AI SDK配置 │ └── urdf/ - 机械臂模型 │ ├── 📊 data/ 数据文件 │ ├── eye_hand_calibration_image/ - 标定图像 │ └── ... │ ├── 📖 开发者学习路线.md ⭐ 本文档 ├── 📄 requirements.txt 依赖包列表 └── 🔍 verify_sdk_integrity.py SDK完整性验证 ``` ### 核心目录说明 | 目录 | 用途 | 说明 | |------|------|------| | **example/** | 示例代码和文档 | 教学示例和完整文档 | | **Embodied_SDK/** | SDK源码 | 可查看学习，理解实现原理 | | **Horizon_Core/** | 核心库（pyd封装） | 控制核心和AI核心 | | **config/** | 配置文件 | 机械臂参数、AI配置等 | | **data/** | 数据文件 | 标定图像、测试数据等 | --- ## 🔧 第1步：环境准备和验证 (10分钟) ### 1.1 安装Python依赖 ```bash # 进入项目目录 cd Horizon_Arm # 安装基础依赖 pip install -r requirements.txt # 可选：MuJoCo仿真（如需使用数字孪生功能） pip install mujoco # 可选：Joy-Con控制（如需使用手柄） pip install joycon-python hidapi ``` ### 1.2 验证SDK完整性 ```bash python verify_sdk_integrity.py ``` **预期输出：** ``` ✅ Embodied_SDK 模块检查通过 ✅ Horizon_Core 模块检查通过 ✅ 配置文件检查通过 ✅ SDK完整性验证通过 ``` --- ## 📚 第2步：SDK理论学习 (30分钟) **📖 必读文档：** `example/SDK完全介绍.md` ### 阅读重点 1. **SDK架构** (5分钟) - 理解9个核心模块的关系 - 了解设计理念和分层架构 2. **核心模块功能** (15分钟) - 电机控制：单电机底层API - 运动控制：多关节运动学 - 视觉抓取：手眼标定和视觉伺服 - AI集成：LLM/ASR/TTS/多模态 3. **核心概念** (10分钟) - 电机控制器实例化 - 共享接口（单/多电机） - 同步控制三阶段 - 关节空间 vs 笛卡尔空间 - 手眼标定原理 **阅读方法：** - 快速浏览整个文档，了解全貌 - 重点阅读"核心概念"部分 - 看代码示例，理解API调用方式 --- ## 🚀 第3步：5分钟快速上手 (5分钟) **🎯 目标：** 完成第一次电机连接和运动控制 ### 运行快速入门程序 ```bash cd example python quickstart_guide.py ``` ### 您将学会 - ✅ 连接一台电机 - ✅ 读取电机位置和状态 - ✅ 使能电机 - ✅ 执行简单运动 ### 准备工作 1. 至少有一台电机已上电 2. USB-CAN适配器已连接到电脑 3. 确认串口号（Windows: COMx, Linux: /dev/ttyUSBx） --- ## 🎓 第4步：根据角色选择深入学习路径 根据您的开发需求，选择对应的学习路径： ### 🔧 路径A：机械臂控制工程师 (4-6小时) **目标：** 掌握电机控制、运动规划、多轴协同 ``` 第1阶段：单电机控制 (1小时) ├─ example/control_sdk_examples/motor_usage_example.py │ ├─ 基础控制（使能/失能/停止） │ ├─ 运动模式（速度/位置/力矩） │ └─ 参数读取和配置 │ 第2阶段：多关节运动 (1.5小时) ├─ example/sdk_quickstart.py │ ├─ 关节空间运动 │ ├─ 笛卡尔空间运动 │ ├─ 预设动作 │ └─ 夹爪控制 │ 第3阶段：多机同步 (1小时) ├─ example/control_sdk_examples/multi_motor_sync_example.py │ ├─ 同步位置控制 │ ├─ 同步速度控制 │ └─ 同步回零 │ 第4阶段：IO集成 (30分钟) ├─ example/control_sdk_examples/io_control_example.py │ ├─ DI/DO基础 │ └─ 传感器联动 │ 第5阶段：完整API参考 (1-2小时) └─ example/test_interactive.py (40+功能) example/test_multi_motor_sync.py (26+功能) ``` **学习建议：** - 边学边做：每个示例都要运行 - 修改参数：尝试不同的速度、位置值 - 查看源码：理解 `Embodied_SDK/motion.py` 的实现 --- ### 👁️ 路径B：视觉应用开发者 (3-5小时) **目标：** 掌握视觉抓取、手眼标定、AI视觉 ``` 第1阶段：基础控制 (30分钟) ├─ example/quickstart_guide.py └─ example/control_sdk_examples/motor_usage_example.py │ 第2阶段：视觉抓取 (2小时) ├─ example/control_sdk_examples/visual_grasp_example.py │ ├─ 系统自检（验证标定文件） │ ├─ 像素点抓取 │ ├─ 框选抓取 │ └─ 视觉跟随 │ 第3阶段：AI多模态 (1.5小时) ├─ example/ai_sdk_examples/multimodal_usage_example.py │ ├─ 图像理解 │ ├─ 目标识别 │ └─ 场景分析 │ 第4阶段：实战项目 (1-2小时) └─ 结合视觉和AI，完成智能抓取任务 ``` **学习建议：** - 确保已完成相机标定 - 理解坐标转换原理 - 查看源码：`Embodied_SDK/visual_grasp.py` --- ### 🤖 路径C：人机交互开发者 (3-4小时) **目标：** 掌握手柄控制、语音交互、IO联动 ``` 第1阶段：基础控制 (30分钟) ├─ example/quickstart_guide.py │ 第2阶段：手柄遥操作 (2小时) ├─ example/control_sdk_examples/joycon_control_example.py │ ├─ Level 1: 连接测试 │ ├─ Level 2: 数据监控 │ ├─ Level 3: 机械臂控制 │ └─ Level 4: 参数配置 │ 第3阶段：IO联动 (1小时) ├─ example/control_sdk_examples/io_control_example.py │ ├─ 传感器触发 │ ├─ 指示灯控制 │ └─ 气动夹爪 │ 第4阶段：语音交互 (可选，1小时) └─ example/ai_sdk_examples/smart_chat_example.py ``` **学习建议：** - 先确保Joy-Con已配对 - 理解控制映射逻辑 - 查看源码：`Embodied_SDK/joycon.py` --- ### 🧠 路径D：AI集成开发者 (4-6小时) **目标：** 掌握LLM、多模态AI、具身智能 ``` 第1阶段：AI配置 (30分钟) ├─ example/ai_sdk_examples/config_example.py │ ├─ YAML配置管理 │ ├─ 运行时修改 │ └─ 环境变量 │ 第2阶段：大语言模型 (1.5小时) ├─ example/ai_sdk_examples/LLM_usage.py │ ├─ 基础对话 │ ├─ 流式输出 │ ├─ 上下文管理 │ └─ 多模型切换 │ 第3阶段：多模态AI (2小时) ├─ example/ai_sdk_examples/multimodal_usage_example.py │ ├─ 图像理解 │ ├─ 视觉问答 │ └─ 场景描述 │ 第4阶段：语音交互 (1.5小时) ├─ example/ai_sdk_examples/asr_usage_example.py (语音识别) ├─ example/ai_sdk_examples/tts_usage_example.py (语音合成) └─ example/ai_sdk_examples/smart_multimodal_voice_chat_demo.py │ 第5阶段：具身智能集成 (1-2小时) └─ 结合Control SDK，实现AI驱动的机械臂控制 ``` **学习建议：** - 配置好API密钥（LLM服务） - 理解AI SDK的配置系统 - 查看源码：`Embodied_SDK/ai.py` --- ### 🎮 路径E：仿真开发者 (1-2小时) **目标：** 使用MuJoCo数字孪生进行算法验证 ``` 第1阶段：数字孪生 (1小时) ├─ example/control_sdk_examples/digital_twin_example.py │ ├─ 启动仿真 │ ├─ 自动波形演示 │ ├─ 预设动作 │ └─ 随机姿态 │ 第2阶段：算法验证 (1小时) └─ 在仿真中测试您的运动规划算法 ``` **学习建议：** - 安装 mujoco 库 - 无需真实硬件即可开发 - 查看模型文件：`config/urdf/mjmodel.xml` --- ## 🛠️ 第5步：项目实践和集成 (持续) ### 5.1 从示例到生产 **复用示例代码的建议：** 1. **阅读示例，理解逻辑** ```python # 示例代码片段 motor = create_motor_controller(motor_id=1, port="COM14") motor.connect() motor.control_actions.enable() motor.control_actions.move_to_position(90, 500) ``` 2. **复制核心代码** - 直接复制API调用逻辑 - 保留参数计算方法 3. **添加错误处理** ```python try: motor.control_actions.enable() except Exception as e: logging.error(f"使能失败: {e}") # 处理错误 ``` 4. **集成到您的架构** - 使用类封装SDK调用 - 添加状态机管理 - 实现多线程/异步处理 ### 5.2 开发者工具 **调试工具：** `example/developer_tools/` - `joycon_sensor_display.py` - Joy-Con传感器深度监控 - 更多工具持续添加... **完整API参考：** - `example/test_interactive.py` - 单电机40+功能 - `example/test_multi_motor_sync.py` - 多机同步26+功能 ### 5.3 配置文件管理 **主要配置文件：** | 文件 | 用途 | 位置 | |------|------|------| | `preset_actions.json` | 预设动作 | `config/embodied_config/` | | `calibration_parameter.json` | 手眼标定 | `config/` | | `aisdk_config.yaml` | AI SDK配置 | `config/` | | `motor_config.json` | 电机参数 | `config/` | **自定义配置：** ```python # 加载自定义配置 sdk = HorizonArmSDK(config_path="my_config.yaml") ``` --- ## 📊 学习进度自检表 根据您的学习目标，勾选已完成的项目： ### 🎯 基础掌握（所有开发者必须） - [ ] 理解SDK架构和9个核心模块 - [ ] 成功连接一台电机 - [ ] 能够控制电机运动（速度/位置） - [ ] 理解关节空间和笛卡尔空间 - [ ] 能够查阅示例代码并复用 ### 🔧 控制工程师进阶 - [ ] 掌握单电机全部控制模式 - [ ] 实现多机同步控制 - [ ] 理解同步控制三阶段 - [ ] 集成IO传感器和执行器 - [ ] 能够调试电机参数（PID等） ### 👁️ 视觉开发者进阶 - [ ] 理解手眼标定原理 - [ ] 成功执行像素点抓取 - [ ] 实现视觉跟随功能 - [ ] 结合AI进行目标识别 - [ ] 能够独立进行相机标定 ### 🤖 交互开发者进阶 - [ ] 配对并连接Joy-Con - [ ] 实现手柄遥操作 - [ ] 配置自定义按键映射 - [ ] 实现IO联动控制 - [ ] 集成语音交互（可选） ### 🧠 AI开发者进阶 - [ ] 配置AI SDK - [ ] 调用LLM API - [ ] 实现多模态理解 - [ ] 集成语音识别和合成 - [ ] 实现AI驱动的机械臂控制 --- ## 🆘 常见问题和解决方案 ### Q1: 电机连接失败？ **检查清单：** 1. 串口号是否正确（设备管理器查看） 2. 电机ID是否正确 3. 电机是否上电 4. 没有其他程序占用串口 **参考：** `example/SDK完全介绍.md` 的"常见问题"部分或 `example/docs/troubleshooting.md` ### Q2: 多电机控制失败？ **解决方案：** 必须使用 `shared_interface=True`： ```python for mid in [1, 2, 3, 4, 5, 6]: motor = create_motor_controller(motor_id=mid, shared_interface=True) ``` ### Q3: 视觉抓取位置不准？ **检查：** 1. 是否完成手眼标定 2. 标定文件路径是否正确 3. 相机和机械臂位置是否改变 ### Q4: 授权验证失败？ **联系技术支持获取授权文件** --- ## 📖 文档索引 ### 核心文档 | 文档 | 位置 | 用途 | |------|------|------| | **开发者学习路线** | `开发者学习路线.md` | 本文档 - 完整学习路线 | | **SDK完全介绍** | `example/SDK完全介绍.md` | SDK详细文档和架构说明 | | **示例代码总导航** | `example/示例代码总导航.md` 或 `example/README.md` | 示例导航和快速开始 | | **Control SDK指南** | `example/control_sdk_examples/README.md` | Control SDK学习路径 | | **文档中心** | `example/docs/index.md` | 完整文档导航 | ### 示例代码 | 类型 | 位置 | 说明 | |------|------|------| | 快速入门 | `example/quickstart_guide.py` | 5分钟体验 | | Control SDK | `example/control_sdk_examples/` | 7个教学示例 | | AI SDK | `example/ai_sdk_examples/` | 10+个AI示例 | | 完整参考 | `example/test_*.py` | 40+功能完整版 | | 开发工具 | `example/developer_tools/` | 调试工具 | --- ## 🎓 学习建议 ### 时间安排 - **兼职学习**：每天1-2小时，1周内完成基础路径 - **全职学习**：每天4-6小时，2-3天内完成基础路径 - **深入掌握**：持续2-4周，完成所有进阶内容 ### 学习方法 1. **理论与实践结合** - 先看文档理解原理 - 立即运行示例验证 - 修改参数加深理解 2. **循序渐进** - 不要跳过基础内容 - 按推荐顺序学习 - 每个示例都要运行 3. **查看源码** - `Embodied_SDK/` 源码可以查看 - 理解API实现逻辑 - 学习代码组织方式 4. **动手实践** - 完成自检表中的所有项目 - 尝试实现小项目 - 遇到问题主动排查 --- ## 📞 技术支持 遇到问题？按以下顺序解决： 1. **查看文档** - `example/SDK完全介绍.md` 的常见问题部分 2. **查看故障排除** - `example/docs/troubleshooting.md` 详细的故障诊断 3. **运行自检** - 相关示例的系统自检功能 4. **查看完整示例** - `example/test_interactive.py` 等完整版参考 5. **使用调试工具** - `example/developer_tools/` 下的专业工具 6. **联系技术支持** - 提供详细错误信息和日志 --- ## 🎯 学习目标检验 ### 基础能力（所有开发者必备） 完成基础学习后，您应该能够： - ✅ **连接控制** - 独立连接和控制单个或多个电机 - ✅ **理解架构** - 理解SDK的模块组织和调用关系 - ✅ **查阅文档** - 能够快速查阅文档找到需要的API - ✅ **复用代码** - 复用示例代码到自己的项目中 - ✅ **排查问题** - 能够根据错误信息初步排查问题 - ✅ **配置管理** - 理解和修改配置文件 ### 进阶能力（根据专业方向） #### 🔧 控制工程师 - ✅ 掌握三种电机控制模式（速度/位置/力矩） - ✅ 实现多电机精确同步控制 - ✅ 集成IO传感器和执行器 - ✅ 调试和优化运动参数（PID等） - ✅ 处理异常情况和安全保护 #### 👁️ 视觉开发者 - ✅ 理解手眼标定原理和流程 - ✅ 实现像素坐标到机械臂坐标转换 - ✅ 完成视觉引导抓取任务 - ✅ 集成AI进行目标识别和分类 - ✅ 优化视觉处理性能 #### 🤖 交互开发者 - ✅ 配置和使用Joy-Con手柄控制 - ✅ 自定义按键映射和控制参数 - ✅ 实现IO联动和传感器触发 - ✅ 集成语音识别和合成（可选） - ✅ 设计直观的人机交互界面 #### 🧠 AI开发者 - ✅ 配置和调用LLM API - ✅ 实现多模态理解（视觉+语言） - ✅ 集成语音识别和语音合成 - ✅ 实现AI驱动的机械臂控制 - ✅ 设计具身智能应用 ### 专家能力（高级开发者目标） - ✅ **深入理解** - 理解SDK底层实现原理和通信协议 - ✅ **扩展开发** - 自定义扩展功能和新模块 - ✅ **性能优化** - 优化系统性能和稳定性 - ✅ **系统集成** - 集成到复杂的生产系统中 - ✅ **架构设计** - 设计大型机械臂应用的软件架构 - ✅ **问题诊断** - 快速诊断和解决复杂问题 --- ## 📈 进阶学习资源 ### 源码学习 - **Embodied_SDK/** - SDK源码可查看，学习实现原理 - **关键文件**: - `motion.py` - 运动学算法实现 - `visual_grasp.py` - 手眼标定和坐标转换 - `joycon.py` - 手柄控制映射逻辑 - `digital_twin.py` - MuJoCo仿真接口 ### 配置文件 - **config/** - 各种配置示例 - `motor_config.json` - 电机参数配置 - `calibration_parameter.json` - 标定参数 - `aisdk_config.yaml` - AI服务配置 - `preset_actions.json` - 预设动作定义 ### 完整示例 - **test_interactive.py** - 40+功能的完整单电机工具 - **test_multi_motor_sync.py** - 26+功能的多机同步工具 - **sdk_quickstart.py** - 完整的机械臂控制框架 --- ## 🎓 认证与考核（可选） ### 基础认证 完成以下任务即可认为掌握基础能力： 1. 独立编写程序连接并控制6个电机 2. 实现多电机同步运动 3. 集成一个IO传感器 4. 处理连接失败等异常情况 ### 进阶认证 根据您的专业方向完成对应项目： - **控制工程师**: 实现一个完整的自动化流程 - **视觉开发者**: 实现一个视觉引导抓取任务 - **交互开发者**: 实现一个手柄遥操作系统 - **AI开发者**: 实现一个自然语言控制的机械臂 --- ## 🌟 成功案例参考 ### 案例1：自动化生产线 - **应用**: 产品分拣和装配 - **技术栈**: 电机控制 + IO联动 + 视觉检测 - **学习时间**: 2周 - **关键技术**: 多机同步、IO触发、位置精度控制 ### 案例2：智能服务机器人 - **应用**: 物品识别和递送 - **技术栈**: 视觉抓取 + AI识别 + 语音交互 - **学习时间**: 3周 - **关键技术**: 手眼标定、目标检测、自然语言理解 ### 案例3：远程遥操作系统 - **应用**: 危险环境作业 - **技术栈**: 手柄控制 + 视觉反馈 + 力反馈 - **学习时间**: 2周 - **关键技术**: 实时控制、视频传输、安全保护 ### 案例4：算法研究平台 - **应用**: 运动规划算法验证 - **技术栈**: 数字孪生 + 轨迹规划 - **学习时间**: 1周 - **关键技术**: MuJoCo仿真、逆运动学、碰撞检测 --- ## 💪 持续成长建议 ### 技术提升 - 📚 **阅读论文** - 了解机械臂和机器人领域前沿技术 - 💻 **开源贡献** - 参与相关开源项目 - 🎯 **实战项目** - 完成实际应用项目积累经验 - 🤝 **技术交流** - 参加技术社区和开发者交流 ### 知识扩展 - **机械臂运动学** - 深入学习正逆运动学理论 - **计算机视觉** - 学习图像处理和目标识别 - **控制理论** - 学习PID控制和高级控制算法 - **AI技术** - 学习深度学习和强化学习 ### 职业发展 - **机械臂应用工程师** - 负责机械臂系统集成和应用开发 - **机器人视觉工程师** - 专注于视觉引导和AI识别 - **自动化系统架构师** - 设计大型自动化系统 - **具身智能研究员** - 研究AI与机器人结合 --- **版本**: 1.3 **更新日期**: 2025-12 **维护**: HorizonArm Team 祝您学习顺利，成为优秀的机械臂开发者！🚀 如有任何问题，欢迎查阅文档或联系技术支持。