欢迎！您刚拿到 HorizonArm 项目，本文档将帮助您系统性地学习和掌握这个项目。
第0步: 了解项目结构 (5分钟)
↓
第1步: 环境准备和验证 (10分钟)
↓
第2步: SDK理论学习 (30分钟)
↓
第3步: 5分钟快速上手 (5分钟)
↓
第4步: 根据角色选择深入学习路径 (2-8小时)
↓
第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/ | 数据文件 | 标定图像、测试数据等 |
# 进入项目目录cd Horizon_Arm
# 安装基础依赖
pip install -r requirements.txt
# 可选：MuJoCo仿真（如需使用数字孪生功能）
pip install mujoco
# 可选：Joy-Con控制（如需使用手柄）
pip install joycon-python hidapipython verify_sdk_integrity.py预期输出：
✅ Embodied_SDK 模块检查通过
✅ Horizon_Core 模块检查通过
✅ 配置文件检查通过
✅ SDK完整性验证通过
📖 必读文档：example/SDK完全介绍.md
SDK架构 (5分钟)
- 理解9个核心模块的关系
- 了解设计理念和分层架构
核心模块功能 (15分钟)
- 电机控制：单电机底层API
- 运动控制：多关节运动学
- 视觉抓取：手眼标定和视觉伺服
- AI集成：LLM/ASR/TTS/多模态
核心概念 (10分钟)
- 电机控制器实例化
- 共享接口（单/多电机）
- 同步控制三阶段
- 关节空间 vs 笛卡尔空间
- 手眼标定原理
阅读方法：
- 快速浏览整个文档，了解全貌
- 重点阅读"核心概念"部分
- 看代码示例，理解API调用方式
🎯 目标： 完成第一次电机连接和运动控制
cd example
python quickstart_guide.py- ✅ 连接一台电机
- ✅ 读取电机位置和状态
- ✅ 使能电机
- ✅ 执行简单运动
- 至少有一台电机已上电
- USB-CAN适配器已连接到电脑
- 确认串口号（Windows: COMx, Linux: /dev/ttyUSBx）
根据您的开发需求，选择对应的学习路径：
目标： 掌握电机控制、运动规划、多轴协同
第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的实现
目标： 掌握视觉抓取、手眼标定、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
目标： 掌握手柄控制、语音交互、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
目标： 掌握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
目标： 使用MuJoCo数字孪生进行算法验证
第1阶段：数字孪生 (1小时)
├─ example/control_sdk_examples/digital_twin_example.py
│ ├─ 启动仿真
│ ├─ 自动波形演示
│ ├─ 预设动作
│ └─ 随机姿态
│
第2阶段：算法验证 (1小时)
└─ 在仿真中测试您的运动规划算法
学习建议：
- 安装 mujoco 库
- 无需真实硬件即可开发
- 查看模型文件：
config/urdf/mjmodel.xml
复用示例代码的建议：
阅读示例，理解逻辑
# 示例代码片段motor=create_motor_controller(motor_id=1, port="COM14") motor.connect() motor.control_actions.enable() motor.control_actions.move_to_position(90, 500)
复制核心代码
- 直接复制API调用逻辑
- 保留参数计算方法
添加错误处理
try: motor.control_actions.enable() exceptExceptionase: logging.error(f"使能失败: {e}") # 处理错误
集成到您的架构
- 使用类封装SDK调用
- 添加状态机管理
- 实现多线程/异步处理
调试工具：example/developer_tools/
joycon_sensor_display.py- Joy-Con传感器深度监控- 更多工具持续添加...
完整API参考：
example/test_interactive.py- 单电机40+功能example/test_multi_motor_sync.py- 多机同步26+功能
主要配置文件：
| 文件 | 用途 | 位置 |
|---|---|---|
preset_actions.json | 预设动作 | config/embodied_config/ |
calibration_parameter.json | 手眼标定 | config/ |
aisdk_config.yaml | AI SDK配置 | config/ |
motor_config.json | 电机参数 | config/ |
自定义配置：
# 加载自定义配置sdk=HorizonArmSDK(config_path="my_config.yaml")根据您的学习目标，勾选已完成的项目：
- 理解SDK架构和9个核心模块
- 成功连接一台电机
- 能够控制电机运动（速度/位置）
- 理解关节空间和笛卡尔空间
- 能够查阅示例代码并复用
- 掌握单电机全部控制模式
- 实现多机同步控制
- 理解同步控制三阶段
- 集成IO传感器和执行器
- 能够调试电机参数（PID等）
- 理解手眼标定原理
- 成功执行像素点抓取
- 实现视觉跟随功能
- 结合AI进行目标识别
- 能够独立进行相机标定
- 配对并连接Joy-Con
- 实现手柄遥操作
- 配置自定义按键映射
- 实现IO联动控制
- 集成语音交互（可选）
- 配置AI SDK
- 调用LLM API
- 实现多模态理解
- 集成语音识别和合成
- 实现AI驱动的机械臂控制
检查清单：
- 串口号是否正确（设备管理器查看）
- 电机ID是否正确
- 电机是否上电
- 没有其他程序占用串口
参考：example/SDK完全介绍.md 的"常见问题"部分或 example/docs/troubleshooting.md
解决方案：
必须使用 shared_interface=True：
formidin [1, 2, 3, 4, 5, 6]:
motor=create_motor_controller(motor_id=mid, shared_interface=True)检查：
- 是否完成手眼标定
- 标定文件路径是否正确
- 相机和机械臂位置是否改变
联系技术支持获取授权文件
| 文档 | 位置 | 用途 |
|---|---|---|
| 开发者学习路线 | 开发者学习路线.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周，完成所有进阶内容
理论与实践结合
- 先看文档理解原理
- 立即运行示例验证
- 修改参数加深理解
循序渐进
- 不要跳过基础内容
- 按推荐顺序学习
- 每个示例都要运行
查看源码
Embodied_SDK/源码可以查看- 理解API实现逻辑
- 学习代码组织方式
动手实践
- 完成自检表中的所有项目
- 尝试实现小项目
- 遇到问题主动排查
遇到问题？按以下顺序解决：
- 查看文档 -
example/SDK完全介绍.md的常见问题部分 - 查看故障排除 -
example/docs/troubleshooting.md详细的故障诊断 - 运行自检 - 相关示例的系统自检功能
- 查看完整示例 -
example/test_interactive.py等完整版参考 - 使用调试工具 -
example/developer_tools/下的专业工具 - 联系技术支持 - 提供详细错误信息和日志
完成基础学习后，您应该能够：
- ✅ 连接控制 - 独立连接和控制单个或多个电机
- ✅ 理解架构 - 理解SDK的模块组织和调用关系
- ✅ 查阅文档 - 能够快速查阅文档找到需要的API
- ✅ 复用代码 - 复用示例代码到自己的项目中
- ✅ 排查问题 - 能够根据错误信息初步排查问题
- ✅ 配置管理 - 理解和修改配置文件
- ✅ 掌握三种电机控制模式（速度/位置/力矩）
- ✅ 实现多电机精确同步控制
- ✅ 集成IO传感器和执行器
- ✅ 调试和优化运动参数（PID等）
- ✅ 处理异常情况和安全保护
- ✅ 理解手眼标定原理和流程
- ✅ 实现像素坐标到机械臂坐标转换
- ✅ 完成视觉引导抓取任务
- ✅ 集成AI进行目标识别和分类
- ✅ 优化视觉处理性能
- ✅ 配置和使用Joy-Con手柄控制
- ✅ 自定义按键映射和控制参数
- ✅ 实现IO联动和传感器触发
- ✅ 集成语音识别和合成（可选）
- ✅ 设计直观的人机交互界面
- ✅ 配置和调用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 - 完整的机械臂控制框架
完成以下任务即可认为掌握基础能力：
- 独立编写程序连接并控制6个电机
- 实现多电机同步运动
- 集成一个IO传感器
- 处理连接失败等异常情况
根据您的专业方向完成对应项目：
- 控制工程师: 实现一个完整的自动化流程
- 视觉开发者: 实现一个视觉引导抓取任务
- 交互开发者: 实现一个手柄遥操作系统
- AI开发者: 实现一个自然语言控制的机械臂
- 应用: 产品分拣和装配
- 技术栈: 电机控制 + IO联动 + 视觉检测
- 学习时间: 2周
- 关键技术: 多机同步、IO触发、位置精度控制
- 应用: 物品识别和递送
- 技术栈: 视觉抓取 + AI识别 + 语音交互
- 学习时间: 3周
- 关键技术: 手眼标定、目标检测、自然语言理解
- 应用: 危险环境作业
- 技术栈: 手柄控制 + 视觉反馈 + 力反馈
- 学习时间: 2周
- 关键技术: 实时控制、视频传输、安全保护
- 应用: 运动规划算法验证
- 技术栈: 数字孪生 + 轨迹规划
- 学习时间: 1周
- 关键技术: MuJoCo仿真、逆运动学、碰撞检测
- 📚 阅读论文 - 了解机械臂和机器人领域前沿技术
- 💻 开源贡献 - 参与相关开源项目
- 🎯 实战项目 - 完成实际应用项目积累经验
- 🤝 技术交流 - 参加技术社区和开发者交流
- 机械臂运动学 - 深入学习正逆运动学理论
- 计算机视觉 - 学习图像处理和目标识别
- 控制理论 - 学习PID控制和高级控制算法
- AI技术 - 学习深度学习和强化学习
- 机械臂应用工程师 - 负责机械臂系统集成和应用开发
- 机器人视觉工程师 - 专注于视觉引导和AI识别
- 自动化系统架构师 - 设计大型自动化系统
- 具身智能研究员 - 研究AI与机器人结合
版本: 1.3
更新日期: 2025-12
维护: HorizonArm Team
祝您学习顺利，成为优秀的机械臂开发者！🚀
如有任何问题，欢迎查阅文档或联系技术支持。