一、项目背景与目标
OpenLoong 是由开放原子开源基金会孵化、人形机器人（上海）有限公司运营的核心开源项目。其愿景在于打破技术壁垒，推动人形机器人在工业、服务及家庭全场景的落地，助力具身智能（Embodied AI）时代的到来。对于开发者而言，接入 OpenLoong 不仅是学习机器人控制的机会，更是参与构建通用智能体生态的起点。
本入门项目旨在帮助开发者快速熟悉 OpenLoong 的开发流程。我们将构建一个名为"Hello Loong"的基础应用，实现两个核心功能：一是控制机器人右臂完成标准的"挥手致意"动作；二是实时读取并打印机身 IMU（惯性测量单元）的姿态数据。通过该项目，你将掌握环境配置、SDK 调用、运动控制及传感器数据读取的关键技能。
二、开发环境搭建
在开始编码前，需构建稳定的开发环境。OpenLoong 原生支持 ROS2（Robot Operating System 2）架构，推荐在 Ubuntu 22.04 LTS 系统下进行开发。
-
系统依赖安装 ：
首先更新软件源并安装基础构建工具：bashsudo apt update && sudo apt install -y python3-pip git cmake build-essential -
ROS2 环境配置 ：
OpenLoong 基于 ROS2 Humble 版本。安装后需配置环境变量：bashsource /opt/ros/humble/setup.bash echo "source /opt/ros/humble/setup.bash" >> ~/.bashrc -
OpenLoong SDK 部署 ：
从官方 Gitee 仓库克隆 SDK，并安装 Python 接口依赖：bashgit clone https://gitee.com/openatom/openloong_sdk.git cd openloong_sdk/python pip3 install -r requirements.txt python3 setup.py install -
硬件连接 ：
确保开发主机与机器人控制器处于同一局域网，通过 SSH 测试连通性，并记录机器人 IP 地址。
三、核心代码实现
我们将使用 Python 编写控制脚本。代码结构分为初始化、动作执行、传感器读取三部分。请新建文件 hello_loong.py。
python
import openloong_sdk as ol
import time
import signal
import sys
class LoongController:
def __init__(self, robot_ip):
self.robot = ol.Robot()
self.is_running = True
# 1. 初始化连接
print(f"正在连接机器人：{robot_ip}...")
if not self.robot.connect(robot_ip):
print("连接失败，请检查网络或电源。")
sys.exit(1)
print("连接成功，系统自检中...")
self.robot.enable_motor() # 使能电机
def wave_hello(self):
"""执行挥手动作"""
print("开始执行挥手动作...")
# 定义关节角度轨迹 (示例：右肩、右肘)
trajectory = [
{'time': 0.0, 'joint_pos': [0.5, 0.0]},
{'time': 1.0, 'joint_pos': [0.5, 1.5]}, # 抬起
{'time': 2.0, 'joint_pos': [0.5, 0.0]}, # 放下
{'time': 3.0, 'joint_pos': [0.5, 1.5]},
{'time': 4.0, 'joint_pos': [0.5, 0.0]}
]
# 调用 SDK 运动接口
self.robot.play_trajectory(arm='right', data=trajectory)
time.sleep(4.5)
def monitor_imu(self):
"""读取 IMU 数据"""
print("开始监测姿态数据 (Ctrl+C 停止)...")
try:
while self.is_running:
imu_data = self.robot.get_imu()
# 打印 Roll, Pitch, Yaw
print(f"\r姿态 - Roll: {imu_data.roll:.2f}, "
f"Pitch: {imu_data.pitch:.2f}, "
f"Yaw: {imu_data.yaw:.2f}", end='')
time.sleep(0.1)
except KeyboardInterrupt:
pass
def shutdown(self, sig, frame):
"""安全关闭"""
print("\n正在停止机器人...")
self.is_running = False
self.robot.disable_motor() # 禁用电机，进入零力矩模式
self.robot.disconnect()
sys.exit(0)
if __name__ == "__main__":
# 配置机器人 IP
ROBOT_IP = "192.168.1.100"
# 注册退出信号，确保安全
signal.signal(signal.SIGINT, LoongController(ROBOT_IP).shutdown)
controller = LoongController(ROBOT_IP)
controller.wave_hello()
controller.monitor_imu()代码解析：
- 初始化 ：
ol.Robot()实例化对象，connect建立通信，enable_motor是关键步骤，未使能电机无法运动。 - 轨迹控制 ：
play_trajectory展示了 OpenLoong 对关节空间插值的支持，开发者只需定义关键点，底层控制器会自动规划平滑路径。 - 安全机制 ：注册了
SIGINT信号捕获，确保用户按下 Ctrl+C 时，机器人能立即执行disable_motor，防止意外动作造成伤害。
四、调试与安全规范
人形机器人开发，安全第一。在真机运行前，强烈建议使用 OpenLoong 提供的 Gazebo 仿真环境进行测试。
- 仿真验证 ：
在终端启动仿真器：openloong_sim launch. 将代码中的 IP 改为仿真接口地址，验证动作逻辑是否符合预期，观察是否有关节超限或碰撞风险。 - 真机调试 ：
- 急停按钮：操作时手不离急停开关，一旦机器人姿态异常，立即拍下。
- 工作空间：确保机器人周围 1.5 米内无障碍物及人员。
- 电源管理：调试过程中密切监控电池电压，低电量时机器人可能会强制停机。
- 数据日志 ：
利用 ROS2 的rosbag工具录制传感器数据，便于后续分析机器人运动时的稳定性，为具身智能算法提供训练数据。
五、总结与展望
通过"Hello Loong"项目，你已完成从环境搭建到真机控制的全流程。这不仅是简单的运动控制，更是通向具身智能的基石。OpenLoong 的开源特性允许你深入底层，未来你可以尝试接入多模态大模型（LLM），让机器人通过语音指令理解"挥手"的语义；或引入强化学习（RL），让机器人在复杂地形中自适应行走。