HorizonArm 项目开发者学习路线

欢迎！您刚拿到 HorizonArm 项目，本文档将帮助您系统性地学习和掌握这个项目。

🎯 学习路线总览

第0步: 了解项目结构 (5分钟)
    ↓
第1步: 环境准备和验证 (10分钟)
    ↓
第2步: SDK理论学习 (30分钟)
    ↓
第3步: 5分钟快速上手 (5分钟)
    ↓
第4步: 根据角色选择深入学习路径 (2-8小时)
    ↓
第5步: 项目实践和集成 (持续)

📂 第0步：了解项目结构 (5分钟)

项目目录总览

Horizon_Arm1.3/
├── 📚 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依赖

# 进入项目目录
cd Horizon_Arm1.3

# 安装基础依赖
pip install -r requirements.txt

# 可选：MuJoCo仿真（如需使用数字孪生功能）
pip install mujoco

# 可选：Joy-Con控制（如需使用手柄）
pip install joycon-python hidapi

1.2 验证SDK完整性

python verify_sdk_integrity.py

预期输出：

✅ Embodied_SDK 模块检查通过
✅ Horizon_Core 模块检查通过
✅ 配置文件检查通过
✅ SDK完整性验证通过

📚 第2步：SDK理论学习 (30分钟)

📖 必读文档： example/SDK完全介绍.md

阅读重点

SDK架构 (5分钟)
- 理解9个核心模块的关系
- 了解设计理念和分层架构
核心模块功能 (15分钟)
- 电机控制：单电机底层API
- 运动控制：多关节运动学
- 视觉抓取：手眼标定和视觉伺服
- AI集成：LLM/ASR/TTS/多模态
核心概念 (10分钟)
- 电机控制器实例化
- 共享接口（单/多电机）
- 同步控制三阶段
- 关节空间 vs 笛卡尔空间
- 手眼标定原理

阅读方法：

快速浏览整个文档，了解全貌
重点阅读"核心概念"部分
看代码示例，理解API调用方式

🚀 第3步：5分钟快速上手 (5分钟)

🎯 目标： 完成第一次电机连接和运动控制

运行快速入门程序

cd example
python quickstart_guide.py

您将学会

✅ 连接一台电机
✅ 读取电机位置和状态
✅ 使能电机
✅ 执行简单运动

准备工作

至少有一台电机已上电
USB-CAN适配器已连接到电脑
确认串口号（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 从示例到生产

复用示例代码的建议：

阅读示例，理解逻辑

# 示例代码片段
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()
except Exception as e:
    logging.error(f"使能失败: {e}")
    # 处理错误

集成到您的架构
- 使用类封装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/`

自定义配置：

# 加载自定义配置
sdk = HorizonArmSDK(config_path="my_config.yaml")

📊 学习进度自检表

根据您的学习目标，勾选已完成的项目：

🎯 基础掌握（所有开发者必须）

理解SDK架构和9个核心模块
成功连接一台电机
能够控制电机运动（速度/位置）
理解关节空间和笛卡尔空间
能够查阅示例代码并复用

🔧 控制工程师进阶

掌握单电机全部控制模式
实现多机同步控制
理解同步控制三阶段
集成IO传感器和执行器
能够调试电机参数（PID等）

👁️ 视觉开发者进阶

🤖 交互开发者进阶

🧠 AI开发者进阶

🆘 常见问题和解决方案

Q1: 电机连接失败？

检查清单：

串口号是否正确（设备管理器查看）
电机ID是否正确
电机是否上电
没有其他程序占用串口

参考： example/SDK完全介绍.md 的"常见问题"部分或 example/docs/troubleshooting.md

Q2: 多电机控制失败？

解决方案： 必须使用 shared_interface=True：

for mid in [1, 2, 3, 4, 5, 6]:
    motor = create_motor_controller(motor_id=mid, shared_interface=True)

Q3: 视觉抓取位置不准？

检查：

是否完成手眼标定
标定文件路径是否正确
相机和机械臂位置是否改变

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周，完成所有进阶内容

学习方法

理论与实践结合
- 先看文档理解原理
- 立即运行示例验证
- 修改参数加深理解
循序渐进
- 不要跳过基础内容
- 按推荐顺序学习
- 每个示例都要运行
查看源码
- 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联动和传感器触发
✅ 集成语音识别和合成（可选）
✅ 设计直观的人机交互界面

🧠 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 - 完整的机械臂控制框架

🎓 认证与考核（可选）

基础认证

完成以下任务即可认为掌握基础能力：

独立编写程序连接并控制6个电机
实现多电机同步运动
集成一个IO传感器
处理连接失败等异常情况

进阶认证

根据您的专业方向完成对应项目：

控制工程师: 实现一个完整的自动化流程
视觉开发者: 实现一个视觉引导抓取任务
交互开发者: 实现一个手柄遥操作系统
AI开发者: 实现一个自然语言控制的机械臂

🌟 成功案例参考

案例1：自动化生产线

应用: 产品分拣和装配
技术栈: 电机控制 + IO联动 + 视觉检测
学习时间: 2周
关键技术: 多机同步、IO触发、位置精度控制

案例2：智能服务机器人

应用: 物品识别和递送
技术栈: 视觉抓取 + AI识别 + 语音交互
学习时间: 3周
关键技术: 手眼标定、目标检测、自然语言理解

案例3：远程遥操作系统

应用: 危险环境作业
技术栈: 手柄控制 + 视觉反馈 + 力反馈
学习时间: 2周
关键技术: 实时控制、视频传输、安全保护

案例4：算法研究平台

应用: 运动规划算法验证
技术栈: 数字孪生 + 轨迹规划
学习时间: 1周
关键技术: MuJoCo仿真、逆运动学、碰撞检测

💪 持续成长建议

技术提升

📚 阅读论文 - 了解机械臂和机器人领域前沿技术
💻 开源贡献 - 参与相关开源项目
🎯 实战项目 - 完成实际应用项目积累经验
🤝 技术交流 - 参加技术社区和开发者交流

知识扩展

机械臂运动学 - 深入学习正逆运动学理论
计算机视觉 - 学习图像处理和目标识别
控制理论 - 学习PID控制和高级控制算法
AI技术 - 学习深度学习和强化学习

职业发展

机械臂应用工程师 - 负责机械臂系统集成和应用开发
机器人视觉工程师 - 专注于视觉引导和AI识别
自动化系统架构师 - 设计大型自动化系统
具身智能研究员 - 研究AI与机器人结合

版本: 1.3
更新日期: 2025-12
维护: HorizonArm Team

祝您学习顺利，成为优秀的机械臂开发者！🚀
如有任何问题，欢迎查阅文档或联系技术支持。

Name		Name	Last commit message	Last commit date
Latest commit History 26 Commits
Embodied_SDK		Embodied_SDK
Horizon_Core		Horizon_Core
config		config
data		data
example		example
LICENSE		LICENSE
readme.md		readme.md
requirements.txt		requirements.txt
verify_sdk_integrity.py		verify_sdk_integrity.py

License

xaio6/Embodied_AI_Arm_open

Folders and files

Latest commit

History

Repository files navigation

HorizonArm 项目开发者学习路线

🎯 学习路线总览

📂 第0步：了解项目结构 (5分钟)

项目目录总览

核心目录说明

🔧 第1步：环境准备和验证 (10分钟)

1.1 安装Python依赖

1.2 验证SDK完整性

📚 第2步：SDK理论学习 (30分钟)

阅读重点

🚀 第3步：5分钟快速上手 (5分钟)

运行快速入门程序

您将学会

准备工作

🎓 第4步：根据角色选择深入学习路径

🔧 路径A：机械臂控制工程师 (4-6小时)

👁️ 路径B：视觉应用开发者 (3-5小时)

🤖 路径C：人机交互开发者 (3-4小时)

🧠 路径D：AI集成开发者 (4-6小时)

🎮 路径E：仿真开发者 (1-2小时)

🛠️ 第5步：项目实践和集成 (持续)

5.1 从示例到生产

5.2 开发者工具

5.3 配置文件管理

📊 学习进度自检表

🎯 基础掌握（所有开发者必须）

🔧 控制工程师进阶

👁️ 视觉开发者进阶

🤖 交互开发者进阶

🧠 AI开发者进阶

🆘 常见问题和解决方案

Q1: 电机连接失败？

Q2: 多电机控制失败？

Q3: 视觉抓取位置不准？

Q4: 授权验证失败？

📖 文档索引

核心文档

示例代码

🎓 学习建议

时间安排

学习方法

📞 技术支持

🎯 学习目标检验

基础能力（所有开发者必备）

进阶能力（根据专业方向）

🔧 控制工程师

👁️ 视觉开发者

🤖 交互开发者

🧠 AI开发者

专家能力（高级开发者目标）

📈 进阶学习资源

源码学习

配置文件

完整示例

🎓 认证与考核（可选）

基础认证

进阶认证

🌟 成功案例参考

案例1：自动化生产线

案例2：智能服务机器人

案例3：远程遥操作系统

案例4：算法研究平台

💪 持续成长建议

技术提升

知识扩展

职业发展

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages