人形机器人这波浪潮里宇树G1确实让不少开发者第一次摸到了“人形”的门槛。但真正拿到手之后你会发现最头疼的不是电机怎么转而是资料散得太开了官方文档一个版本一个样社区的帖子各说各话GitHub上示例代码的接口命名可能隔了几个月就完全不兼容。我这次折腾G1二次开发踩了不少坑也翻遍了能翻的资料最后干脆把整个过程里真正有用的信息梳理成了一份路线图式的合集。这篇文章不是官方文档的复读而是一个爬过坑的人把路标重新立了一遍。想快速跑通第一个程序的新手、计划做产业项目的团队、想研究具身智能和上层应用的玩家都能在这篇里找到对应自己阶段的内容。1. 先搞清楚G1是什么再想怎么改1.1 硬件平台的基本盘做二次开发第一步永远是吃透硬件而不是急着找接口文档。根据公开信息宇树G1是一台中等尺寸的人形机器人整机自由度在23个以上肩、肘、髋、膝、踝这些关键关节都覆盖到了身高大概在1米3以内重量在35kg上下属于实验室和极客团队都能接受的入门级全尺寸人形平台。关节电机用的是无框力矩电机加谐波减速器方案这个配置决定了它的力矩输出、响应速度和控制的精细程度也直接影响了你二次开发时能做多激进的动作。我建议拿到机器后先做三件事第一把每个关节的编号和运动范围摸清楚哪些是腰、哪些是腿、哪些是臂官方手册里一般都有表格但你最好自己在终端里读一遍实际值因为出厂标定和手册标注经常有细微偏差。第二搞清楚传感器布局尤其是IMU放哪儿、深度相机在什么位置、脚底是否有压力传感器这决定了你后面做力控和视觉的时候数据从哪来。第三了解机载计算单元的算力水平因为上层算法跑本地还是跑远端直接取决于这块板子能不能扛得住。1.2 二次开发的边界在哪G1的二次开发不是“想做多深就做多深”它存在一个清晰的开放层次。最上层是整机遥控用原厂App或遥控器就能操作这不算二次开发中间层是官方SDK接口你可以读取状态、下发目标位置、控制关节速度和力矩大部分应用开发都落在这层再往下是运动控制器内部算法的修改比如步态调度器、稳定性控制、状态机这些官方开放得比较有限只能通过参数配置和有限的自定义接口去调整想从底层重写一套步态算法就得另想办法了。我的建议是绝大多数团队把精力放在SDK层就够了。G1原厂已经帮你解决了“站起来不倒”这个最难的工程问题你要做的是基于它稳定的运动能力去叠加自己的业务功能比如导航、巡检、抓取、交互。如果一上来就想在步态层面动刀子那不仅是工作量的问题是摔机风险和调试周期的急剧上升。1.3 你能拿G1做什么理清楚边界之后才是场景。从我看到的实际案例来看G1的二次开发主要集中在这几类方向一类是商业场景验证比如迎宾导览、安防巡检、展馆讲解这些本质上是用机器人的运动能力加定制化交互逻辑一类是科研平台拿来做双足运动控制算法的验证载体还有一类是具身智能方向把视觉语言大模型接到机器人上让机器人理解指令并执行动作这也是目前热度最高的玩法。不同的场景对开发深度和技术栈的要求差别很大选方向之前先确认项目需求匹配哪一层开放能力能帮你少走很多弯路。2. 资料从哪找SDK、文档与开发者在手把手教你之前2.1 SDK版本管理是第一个大坑G1的SDK其实是在持续迭代的这一点可能和很多人想的不太一样。你以为拿到一个稳定版本就能一直用实际上官方会不定期更新接口定义、消息格式和功能模块有时候是老接口废弃有时候是新增了传感器数据的字段有时候是修改了控制指令的坐标系定义。我见过最坑的情况是一份网上流传的示例代码明明之前能跑换上新的SDK包之后编译直接报错原因是消息结构体的字段名变了。所以你在找资料的时候第一件事不是看教程发布时间而是确认这份资料对应的SDK版本号最好和你设备里的固件版本匹配。我的习惯是从官网开发者入口申请SDK包优先用Release版本而不是最新的main分支源码因为Release版本经过验证稳定性有保障。下载下来之后先看两样东西——CHANGELOG和examples目录前者帮你了解这版改了什么后者是你写自己代码前的活样板。2.2 通信链路选型和实时性认知G1的二次开发通信方式以网口为主也就是通过局域网连接你的开发机整机一般也支持无线网络连接但我强烈建议初期调试阶段用网线直连。理由很简单无线网络存在延迟抖动和丢包而对机器人下发的控制指令恰恰是对延迟极其敏感的一个周期的抖动就可能导致动作不连贯甚至失控。这里要建立几个基本认知。控制周期通常是毫秒级或十毫秒级的你需要关注的是端到端延迟而不是单向网速指令下发频率和状态反馈频率未必一致有的平台反馈可达高频但下发的控制指令如果太密反而会让机器人内部的运动控制器无所适从。我实际测试下来的经验是把状态读取和控制下发放到同一个主循环里固定周期跑比频繁单独读取要稳定得多。通信链路的实时性是所有上层应用的基座一开始设计不好后面每一步都在还债。2.3 SDK的核心构成客户端、消息、回调大部分厂商的SDK设计思路都类似G1一个客户端对象负责连接管理一系列消息结构体承载控制指令和状态反馈再加上事件回调机制处理异常和保护事件。你上手的时候不要急着写控制指令先建立一个最简客户端连接上之后把状态数据打印出来确认你能收到姿态、关节角度、关节速度和电池信息等核心数据这一层通了后面的事情都有基础。我还想提一个很多新手忽略的点SDK通常会内置安全机制比如心跳超时保护、关节软限位、摔倒检测。你调试的时候千万不要为了方便把这些机制关掉尤其是心跳超时保护一旦开着网络不稳定时机器人会自动进入保护状态虽然可能会中断你的程序但它是防止机器人失控的最后防线。我的话放在这里二次开发的第一原则是安全第二原则才是功能。3. 运动控制二次开发最难啃的骨头3.1 状态机思维比调参数更重要人形机器人本质上是一个高度耦合的非线性系统想要稳定控制它靠纯公式推导是玩不转的。G1内部已经有一套完整的状态机站立、行走、蹲起、转身、摔倒恢复这些模式之间的切换逻辑是写好的你二次开发时最重要的工作是理解这套状态机让自定义动作插在正确的状态节点上而不是绕过它。我自己刚开始的时候犯过一个错误想做一个自定义的摆臂动作就直接往关节下发了目标角度结果机器人在站立状态下做出了一个重心严重偏移的姿态触发保护直接坐下。后来才明白任何动作指令都必须考虑当前状态机所处的模式站立模式本来就有重心约束违背约束的动作会被控制器夹生处理。正确的做法是先切换到合适的状态或者把自定义动作拆成一系列符合当前状态约束的小步进指令逐帧下发让它平滑过渡。3.2 关节空间控制与任务的映射G1的SDK层最直观的控制方式是设置各个关节的目标位置、速度和力。这就带来一个问题人类的意图通常是任务空间的比如“手抬到某个高度”“向前走三步”而不是“髋关节转20度”。在做二次开发的时候你一定要在任务空间和关节空间之间建立清晰的映射关系。我的做法是先手工规划关键帧动作用仿真环境确认关节角度合理然后再固化成程序里的动作列表。做这类工作最好是先在仿真里跑通再上真机这一步能省下大量摔机的维修成本。动作设计有几个经验值很值得记关节角速度不要拉满给控制器留出调节余量姿态变化幅度单帧不要太大分多帧渐变关键帧之间做插值平滑而不是直接跳变。这些不是台面上的技术是摔过几次之后换来的。3.3 步态参数调节的玄学与科学如果你要调步态参数比如步频、步幅、抬脚高度、摆腿周期建议一次只改一个参数每次改动幅度控制在10%以内然后放到仿真里验证再上真机。人形机器人的步态系统是一个典型的多参数耦合系统你改了步幅可能重心高度就需要配合调整抬脚高度变化又会影响到地面接触稳定性。这些参数之间有隐性关联官方文档给出的只是默认值不代表是最优值。调步态的时候特别要注意“贴地保护”这个概念。人形机器人行走时如果抬脚过高会显得机械且不稳抬脚过低则可能在摆动相绊到地面。关键是让踝关节在触地前有一个平滑的阻尼过渡而不是硬踩。我调出来的经验是偏稳定的参数组合往往不是看起来最灵活的但长时间运行下来它的鲁棒性是最好的。稳定性优先永远是步态调参的第一原则。3.4 力控与外部扰动从“自己站”到“扛住事”G1的二次开发不可能永远在理想环境下跑。我见过很多项目卡在同一个环节机器人在平地走得好好的一遇到轻微外力推搡就站不稳了。这不仅要靠原厂的姿态控制器也需要你在外部反馈上做文章。一种常见思路是利用臂关节内置的电流数据估算外力把估算出的外力作为扰动项补偿到姿态控制里。另一种思路是做柔顺控制让机器人在受到外力时不是硬扛而是顺着力的方向做小范围让步等外力消失后自动回到目标姿态。这里最关键的是传感器数据的信任度电流信号有噪声IMU加速度计受震动干扰大多源数据的融合时机决定控制的成败。我的建议是从小增益开始调逐步加大反馈力度直到机器人对外力做出适度响应而不产生自激震荡。4. 感知与上层应用把G1变成一个具身智能体4.1 视觉数据流从图像到决策G1的头部通常配备了深度相机或可见光相机这些视觉信息是上层应用的入口。视觉二次开发的链路基本是采集原始图像流做预处理通过目标识别或语义分割得到感知结果再把结果映射为机器人的动作决策指令。我建议你第一步先建立稳定的图像采集通道把深度图和RGB图像同步保存下来做时间戳对齐因为深度相机和RGB相机之间的帧率、延迟不一致不对齐的话会直接影响后续避障和识别的准确性。第二步才是做推理这里你可以先借用现成的模型比如通用目标检测、人体姿态估计这些验证整条链路跑通后再考虑自训练模型。一个常见的误区是直接在机器人端做全部推理其实完全可以把图像流传到开发机上处理再把决策指令传回机器人这样能大大降低机载计算的负载不过延迟会高一些适合非实时性要求高的场景。4.2 建图与自主导航让机器人自己知道在哪要让G1在室内环境自主移动你需要一套完整的导航方案先建图再定位最后规划路径并下发步态指令。建图一般用SLAM算法G1的深度相机可以提供点云数据配合轮式里程计或视觉里程计能构建出环境的二维栅格地图或三维点云地图。定位环节比较成熟的方案是AMCL这类粒子滤波方式或者直接基于点云配准的定位方式。路径规划可以借用成熟框架先做全局规划再叠加局部实时避障。这里我要提醒一个容易踩的坑G1是双足机器人通行能力和轮式机器人完全不同。台阶、坡道、窄缝都可能成为障碍即使全局路径规划出来了局部轨迹也要针对双足运动特性做额外的可通行性约束否则规划出来的路径在图上看着没问题实际走不过去。4.3 语音与大模型对接具身智能的最新玩法G1二次开发目前最火的方向之一就是接入大模型让机器人理解语音指令并转化为动作序列。整体架构一般分成四段语音识别把用户说的话转成文字大模型将文字指令解析为结构化的动作描述动作映射模块把动作描述换成关节指令序列最后由运动控制层执行。这个环节的难点不在模型本身而在“从语言到动作”的映射。比如用户说“往前走一步然后挥挥手”你得把“走一步”和“挥挥手”分别映射为步态控制指令和关节控制指令并且要保证两个动作串联起来不会互相干涉。我的做法是先用一套预设的动作模板库覆盖常见指令大模型只负责从模板库里选择并组织执行顺序等链路稳定后再尝试让模型直接输出参数化的动作指令。模版库加生成式模型结合是目前实操中稳定性和灵活性平衡得最好的方式。5. 实操走通第一个G1二次开发程序5.1 开发环境搭建别在这步省时间我建议用Ubuntu 20.04或22.04系统Python版本3.8以上C项目则用CMake管理。SDK一般同时提供Python和C两种接口Python适合快速原型验证C适合做实时控制或部署到生产环境。安装SDK的时候不要只跑pip install要顺手把examples目录下的依赖也装上。这步最容易被忽略的是环境变量配置。SDK可能需要你指定一些路径变量如果你不配置运行示例程序时会莫名奇妙地提示找不到模块或找不到资源。我的排查经验是先运行SDK自带的示例例如连接测试或状态读取例程能跑通说明环境没问题再开始写自己的代码否则你就一直在自己的代码和环境问题之间找bug。5.2 开发机和G1建立连接与心跳机制连接过程看着简单其实暗藏细节。用网线直连时把开发机的网卡IP配置成和G1同一网段注意不要和G1冲突。用无线方式时确保在同一个局域网内。连接后SDK会维护一个心跳机制客户端要定期向服务端发送心跳包以维持连接的有效性和时效性。我在这里要说一个很具体的经验调试时把心跳超时阈值调大一点先保证能稳定地收发数据跑通主逻辑之后再把阈值调回正常。原因很简单调试的时候你经常会在代码里打断点或临时sleep如果心跳超时设得太短调试过程会频繁触发断开保护让你误以为是自己的业务逻辑写错了。等主逻辑稳定后恢复正常的超时参数再测试长时间运行的可靠性。5.3 读取机器人状态第一个正确性验证程序连接成功后第一步建议写一个简单的状态读取程序。读取内容至少包括机器人当前模式、IMU的欧拉角或四元数、全部关节的角度和速度、电池电压、错误码。下面是一个极简的伪代码框架用来表示一个状态读取主循环# 伪代码示例实际接口名以你所用的SDK版本为准 client create_robot_client() client.connect(192.168.123.xx) while running: state client.get_motion_state() print(state.imu_euler, state.joint_positions[0:5]) time.sleep(0.02)跑通这段代码其实就说明你的通信链路、SDK安装、连接配置全部正确了。我建议把读取到的数据保存到文件里跑一段时间检查数值有没有跳变、有没有不合理的突变。如果状态数据平滑且符合物理常识说明设备端一切正常你可以放心进行下一步。5.4 下发一个简单关节动作让G1“点头”状态通了之后就可以尝试做第一个主动控制动作了。最简单而且风险最低的是头部的俯仰关节——动作幅度小不影响重心就算出错最多是头动一下。流程这样走先读取当前头部关节的角度作为起始点设置一个目标角度通常是通过设置位置加速度限制然后逐帧下发指令让它平滑转动。# 伪代码示例一个“点头”动作 start_angle state.joint_positions[head_pitch_index] for t in range(50): target start_angle - 0.2 * (t / 50) # 缓慢下点头 client.set_joint_position(head_pitch_index, target, speed_limit0.5) time.sleep(0.01)这个循环看起来简单但它把“读取状态-计算目标-下发指令”这个闭环逻辑完整地串起来了。然后你按同样的逻辑把目标角度改成抬起再回来就能做出一个完整的点头动作。把这个基础能力理解透后面的前进后退、蹲起、挥手本质上都只是把目标关节和目标轨迹换了一下而已。5.5 一个完整Demo走三步并挥手当你对单关节控制熟练以后可以尝试做一个组合动作。我的建议是先写一个按序列执行的指令协调器在这个协调器里维护一个动作队列按顺序依次执行每个动作执行前先检查机器人状态是否安全执行完后等稳定了再进入下一个动作。以“走三步然后挥手”为例你只需要把三个子动作按顺序编排先调用步态接口控制前进三步等机器人完全停下来确认姿态稳定再执行手臂关节的挥动动作。如果这里发现动作衔接不稳问题往往不是动作本身而是前一个动作结束后机器人尚未进入稳定状态就开始下一个动作了。在动作之间加延时或者加姿态稳定判定通常能解决大部分衔接问题。这就是为什么说二次开发的本质是“编排”而不是“发明”。6. 常见问题排查手册我踩过的坑都在这里现象可能原因排查方法连接不上机器人IP不在同一网段或防火墙拦截首先ping机器人端看能不能通再检查防火墙放行规则状态数据全部为零或不变客户端没有收到实际数据可能是连接未完全建立检查SDK内部日志确认握手成功查看服务端状态码关节指令下发无响应当前机器人处于保护状态或急停触发确认状态机模式和错误码如果急停触发需要按指示解除急停动作执行时机器人抖动指令频率过高或单帧目标角度变化过大降低下发频率细化插值步长增加速度限制开发机程序崩溃状态回调耗时过长阻塞主线程数据回调里只做取值不做计算把处理逻辑放到主线程长时间的延迟变大网络丢包重传或缓冲区堆积查看SDK是否报告丢包增加丢包补偿逻辑不要盲目调低超时这几类问题里有三条最容易反复折磨人一是连接不上但怎么查都找不出问题最后发现是网线接触不良这种物理层的坑最无语二是机器人被人从背后轻轻推了一下立刻触发摔倒保护然后你写的所有逻辑全部暂停这是好事说明保护机制在工作但你需要在应用层做好保护触发后的恢复流程三是SDK版本与固件不匹配导致某个接口行为异常查了一个晚上最后发现是版本问题。还有一个小技巧机器人的日志信息一定要全量保存不要只看程序输出。SDK一般会输出详细日志包括警告、错误和性能统计真正常出问题的是warning级别的信息它们会在你的主逻辑出错前很久就给出预示。养成看日志的习惯能帮你省出大量的排查时间。另外一个经常被忽略的点是温度对关节特性的影响。机器人长时间运行后关节电机发热会导致响应和默认参数有偏差所以长时间稳定性测试要在合理的温度区间内进行不要在大冬天刚开机就猛跑高强度动作冷机和热机的参数特性确实有差异这一点和人很类似先热身再干重活。7. 资料路线图我现在建议你怎么看资料、怎么查资料7.1 资料分类与优先级市面上关于G1二次开发的资料主要分为几类官方产品手册和开发者文档、官方提供的SDK包与示例代码、ROS2相关的接口包、开源社区里的仿真模型和工具链、第三方博客与视频教程、零散的论坛讨论。这些资料的权威性和时效性完全不同我给它们排个优先级首先是官方开发者文档和SDK包这是唯一真正权威的信息来源。其次是官方示例代码它是你写自己代码之前最好的参考模板优先级非常高。然后是仿真环境相关的模型和工具链比如通用机器人仿真平台里有人上传过G1的URDF描述文件或仿真模型这在做动作预演时价值很高。再往下才是社区博客和视频教程这些内容可以看但一定要对照官方文档校正因为博主可能用的是旧版本接口。最后是论坛和聊天记录类的零散讨论只用来排查特定问题时参考。7.2 一个实用动作建立自己的离线资料库网上的资料会失效会更新会和你的版本不匹配。我强烈建议你拿到一份资料之后立刻同步下载保存到本地按这样分类存放官方文档按版本号分目录SDK包按版本号分目录示例代码注明对应SDK版本号和测试日期仿真模型单独放一个目录博客教程只要截图关键页面并存PDF。这个习惯在项目进行到后期时极其有用你会感谢自己当初做了这个整理。同时建议你在自己的项目仓库里维护一个“接口变更记录”每次升级SDK之后把更新内容、影响的接口、需要改的代码位置记录下来。这个文档刚开始维护的时候会觉得多此一举等项目做了几个月再回来看它就是整个团队最重要的资产——比起重新看一遍SDK源码这份记录能让你在版本变化时一分钟定位到问题。7.3 个人体会二次开发的价值在于“编排”把整个流程走下来之后我最深的感受是G1的二次开发真正让你发挥创造力的地方不是发明新的算法而是把已有的稳定模块编排成新的能力。官方解决了“怎么稳定走路”这个最难的工程问题你的工作是回答“让它走去哪、怎么停下、怎么与人互动”。大量的项目失败不是因为技术不够深而是因为对现有平台能力的边界理解不到位把一个本应由原厂控制器负责的底层问题强行扛到了应用层来解。所以我的最后一个建议是拿到G1先花一周时间只做一件事——把官方示例代码全部跑一遍。每个示例对应一个能力边界跑完一遍之后你会对“这台机器人能做什么、不能做什么”形成一个非常清晰的地图。有了这张地图后面所有的二次开发都只是在这个地图上加新路线而已。最后再分享一个小技巧调试的时候永远在代码里留一个远程急停的“逃生舱”可以是手机上连着的一个独立控制端也可以是键盘上绑定的一个快捷键。人形机器人调试的不确定性远高于普通机械臂看起来再稳的动作也有可能在某个电磁干扰、地面打滑的瞬间出现问题。多一个随时切断指令的手段不是怂而是长期做机器人调试的人骨子里的习惯。