拿到宇树Go2之后我身边不少Python开发者的第一反应不是让它走直线而是问能让它跳个舞吗说实话这个问题看起来像玩闹但底层牵扯的东西一点也不简单。让机器狗跳舞本质上是短时间内连续、有序地调佣运动控制接口中间还要处理通信延迟、状态切换、时序容错——这些恰好就是unitree_sdk2_python最核心的用法。这篇文章我会从零开始把Go2跳舞这个项目完整拆开覆盖环境准备、动作设计、完整可运行代码和实测避坑看完你完全可以在自己那台狗上复现出来。1. 为什么让Go2跳舞能检验你对SDK的真实理解1.1 从官方Demo到“自定义动作”之间差着整个思维层级宇树官方SDK仓库里其实不缺demo跑一圈下来你会发现里面全是“站立”“前进”“后退”“恢复初始姿态”这种单个动作。这些demo给你的体验是什么按文档敲一遍狗动了然后呢你还是不知道该怎么让它像视频里那样连贯地做一个动作组合。这就是跳舞这个场景的价值所在——它是把单个运动指令编排成有节奏、有变化、有观赏性的动作序列。你不再只是调用一个接口而是要处理动作之间的衔接、执行时长的控制、异常中断的处理这些恰恰是真实机器人项目里躲不开的问题。我见过不少朋友拿到Go2后的流程是这样的连上WiFi跑通官方demo高兴五分钟然后不知道干什么了。而“让狗跳一段舞”这个目标会倒逼你去搞清楚三个问题通信链路是怎么建立起数据的收发运动控制指令的语义到底是什么多指令之间的时序应该如何设计这三个问题搞明白了你才算真正会用unitree_sdk2_python而不是单纯“跑通了别人的代码”。1.2 跳舞这个场景替你做完了什么抽象有人可能会说跳舞不就是挪步子加转圈嘛有啥了不起。但你把“走路变快”和“跳舞”放在一起对比就知道了。走路本身是一个低耦合动作你告诉狗一个速度它会自己完成步态规划、关节解算、姿态维持。而跳舞需要的是“多个连续目标的切换”——狗不能等上个动作完全静止再执行下一个那跳出来就是机器人广播体操毫无节奏感。你需要了解SDK运动控制接口的“非阻塞”特性了解它发完指令后狗的实际执行曲线了解什么参数组合能产生“舞蹈感”而不是“机械感”。说白了跳舞是对SDK能力边界的一次压力测试。跳完之后你再回去做工业巡检、视觉巡线、物品搬运这些正经项目处理时序和控制逻辑时心态会完全不一样——因为你已经知道SDK的“脾气”了。2. 环境准备这台狗和你的电脑怎么“对上话”2.1 硬件与网络拓扑先说硬件清单别小看这一步后面百分之八十的“连不上”问题都出在这。宇树Go2一台标准版或带图传版本都行一台PCUbuntu或Windows皆可我日常用Ubuntu但Windows下的流程也验证过一个无线路由器或者直接用Go2自带的AP热点模式网线一根推荐用有线连路由器无线丢包率在关键时刻够你喝一壶网络拓扑其实很简单Go2有一条WiFi链路开机后它会通过DHCP从路由器获取一个IP或者你手动把PC和Go2放进同一个局域网。Go2的默认IP通常是192.168.123.161PC端一般在192.168.123.18这个网段。不同固件版本可能不一样所以第一步永远是打开官方App在设备信息里看清楚你手上这台狗的IP而不是全网搜一个“默认IP”就埋头开干。然后你在PC上执行一个简单的ping命令确认连通ping 192.168.123.161能收到稳定回复说明网络层通的。如果ping不通请先去检查两台设备的网段和防火墙别急着往下走这条路不通后面一切免谈。2.2 安装unitree_sdk2pySDK2的Python版本已经打包上传到了PyPI安装比老一代SDK省心不少pip install unitree-sdk2py如果你喜欢源码方式也可以从宇树官方仓库克隆后用pip install -e .安装。我建议普通开发者直接用pip省时省力。安装完成后验证一下python -c from unitree_sdk2py.core.channel import ChannelFactoryInitialize; print(ok)不报错就说明包已经进入你的Python环境。这里提醒一句SDK的版本更新比较频繁不同版本之间接口名称可能有微调。我手头验证过的代码基于2.x版本如果你用的版本接口名对不上优先去翻阅你本地site-packages里的示例文件而不是在互联网上大海捞针。这个方法几乎每次都能解决问题。2.3 用一条电池电量指令验证通信链路在写舞蹈代码之前我强烈建议你先花五分钟确认SDK到Go2的链路是通的。方法很简单跑一个读取状态的官方示例比如订阅BMS电量话题看能不能读到电池数据。如果这一步能读到数据说明SDK和机器狗之间的DDS话题已经建立起来了。如果读不到那问题大概率出在你传入的网卡接口名上。ChannelFactoryInitialize(0, eth0)这里的第二个参数必须是你PC实际使用的网卡名。Ubuntu有线通常是eth0无线可能是wlan0Windows倒是直观直接写“WLAN”或“以太网”。很多人上来就写eth0结果自己的笔记本用的明明是WiFi那当然收不到任何数据。这种低级错误我见过不下十次。3. 舞蹈动作的三个基本功Move、Euler与状态切换3.1 Move走位和转圈靠它Go2的移动控制核心接口是Move(x, y, yaw)三个参数分别是x方向速度、y方向速度侧移和偏航角速度。对大多数舞蹈编排来说你主要用x前进后退和yaw原地转圈y方向侧移在定点舞步里偶尔会用但频率不高。注意一点Move发的是速度指令而不是位置指令。也就是说你告诉狗“前进0.4m/s”它会一直往前跑直到你再次发Move(0, 0, 0)把它停下来。很多第一次玩的人在这里会翻车——发了一个前进指令后看狗一直在走慌了不知道怎么让它停。正确的做法是每次都把“停止”纳入动作封装里发完一个方向的Move跑够时间后立刻发全零的Move让它定住再给一点缓冲时间进入下一个动作。3.2 Euler身体倾斜是“舞蹈感”的关键如果只靠Move走位和转圈那狗跳出来的舞充其量算“巡逻步”完全没有观赏性。真正让你觉得“这狗好像在跳舞”的是它的身体姿态变化——往左倾一下、往右斜一下配合音乐节拍那种“律动感”立刻就出来了。Euler(yaw, pitch, roll)就是干这个的。三个参数分别控制偏航角、俯仰角和横滚角单位是弧度。对跳舞来说最常用的是roll横滚角也就是身体左右倾斜pitch俯仰角偶尔用在“点头”这个动作上yaw已经被Move覆盖了这里一般保持0。这里必须强调参数单位是弧度不是角度。你把roll传成30狗会以为自己要侧翻了——实际上cos30和cos30rad完全是两码事。我记得第一次测试时直接传了一个“看起来合理”的角度值结果狗猛得一歪差点原地倒下。后来老老实实按弧度算15度大约0.25rad这个幅度在跳舞里已经很明显了。3.3 状态切换Begin、StandUp、Sit与DampGo2的运动控制状态机是一个绕不开的话题。你不能在狗还趴着的时候直接发Euler也不能在它跑动中突然要求Sit——这些指令会被忽略或者引发意料外的动作。我在舞蹈编排里用到的状态指令有四个指令作用在舞蹈中的用途StandUp从趴卧状态起身开场准备动作BalanceStand进入稳定站立状态动作之间的安全过渡态Sit坐下结束动作Damp电机松劲阻尼模式异常中断时让狗软掉一个基本原则是每次动作切换之间插入一个BalanceStand稳定期。别小看这个细节它能让机器狗的姿态控制滤波器收敛到稳态下一个动作执行起来会准确很多。直接从一个大幅度倾斜切到另一个大幅移动很容易引起狗的姿态震荡。另外Go2的客户端SDK在连接建立后是有心跳机制的。如果机器狗在设定时间内没收到新的控制指令它会自动进入安全保护状态。这对舞蹈来说其实是好事——你写时序时故意在每个动作间留出停止间隙狗不会因此在原地发疯。3.4 为什么SDK指令不能连续猛发控制Go2和写普通HTTP接口不一样。你发一个请求得到返回下一个请求再发这是“一问一答”模型。但SDK的DDS通信模型是“发布-订阅”你发的每一条指令都会进入一个话题队列机器狗按接收顺序执行。问题在于如果你把几十条动作指令在一瞬间全部发出去狗不会排队逐条执行而是会丢弃前面来不及处理的指令只认最新一条。这就是为什么很多第一次编舞的人发现“狗只做了一个动作就不动了”——不是狗坏了而是指令通道被“冲垮”了。正确做法是在每条指令之间加适当的sleep。我的经验值是最短间隔不小于0.3秒给DDS通信留出处理余量。这个值不是拍脑袋定的而是多次实验后得到的下界小于0.3秒时偶尔会出现指令丢失大于等于0.3秒时基本稳定。4. 舞蹈编排先把节奏画成表再写成代码4.1 选定节拍和动作库很多人拿到SDK第一件事就是打开代码编辑器狂写这是最糟糕的做法。编舞和写程序一样先设计再编码能省掉后面好几轮调试。第一步选一段BPM每分钟节拍数在110到130之间的音乐。这个区间比较适合四足机器人展示动作太快了狗的步态切换跟不上太慢了又没有舞蹈感。BPM确定后一拍的时间就是60除以BPM——比如120BPM每拍0.5秒。第二步整理你能用的“动作库”。我把前三章讲的动作整理成六个常用语汇左右摇摆通过Euler的roll正负值切换前进步Move正向x速度维持0.5-1秒后退步Move负向x速度原地左转/右转Move的yaw参数点头Euler的pitch动态变化定住Move全零维持BalanceStand这六个动作基本能支撑起一段30秒的编舞了。如果你想更炫可以研究关节层的控制直接操作腿部关节角度但那是另一个量级的复杂度不在本文范围内。4.2 一个8秒demo的时序表拿120BPM的一段音乐来举例每拍0.5秒四拍一小节两小节构成一个“八拍”。下面这张表是一个可以直接落到代码里的动作时序时间点动作参数持续时间0.0sStandUp—2.0s2.0sBalanceStand全零1.0s3.0s左倾斜Euler yaw0, pitch0, roll0.250.8s3.8s回中Euler roll00.6s4.4s右倾斜Euler roll-0.250.8s5.2s回中Euler roll00.6s5.8s前进Move x0.4, y0, yaw01.0s6.8s停止Move(0, 0, 0)0.3s7.0sSit—1.5s这套动作总共8.5秒正好踩在大多数流行音乐的两小节上。你仔细观察就会发现我在两个大动作之间都塞了“回中”和“停止”的过渡这是为了保证狗的稳定性也方便你在后期替换其他动作时不至于让前后动作打架。4.3 从时序表到函数封装的思路时序表确定后写代码就水到渠成了。我建议把每个基础动作封装成独立的函数比如left_lean()、right_lean()、forward_step()然后在主流程里按顺序调用。这样做的好处是后续想调整动作幅度或者时长只需要改函数内部参数主流程完全不用动。更进阶一点的做法是做一个“动作名到函数”的映射表然后通过一个计划列表驱动舞蹈dance_plan [ (left_lean, 0.8), (center, 0.6), (right_lean, 0.8), (center, 0.6), ]这对后期做“音乐节拍对动作”的自动同步特别有帮助。不过对于第一次跑通来说简单的顺序调用已经足够了别过度设计。5. dance_go2.py完整代码逐段拆解5.1 初始化与工具函数代码的第一步是初始化SDK通信。ChannelFactoryInitialize(0, NETWORK_INTERFACE)里面的两个参数第一个是DDS的domain_idGo2默认是0一般不用改第二个是PC端网卡名。我在代码里用了一个变量方便你在不同操作系统间切换。接着创建SportClient设置超时时间并调用Init()。这一步会在后台开启通信线程让狗进入可接收指令的状态。工具函数我写了两个execute_move负责通用移动指令的封装——发指令、等待、停止、再等待safe_stop负责在任意异常时让狗安全停下来。这两个函数在整段舞蹈主流程里会被反复调用。5.2 舞蹈主流程主流程按章节4.2的时序表逐行落实。每一步动作之间留足了稳定时间确保狗有充分响应。动作幅度我按照实测经验值设置得比较保守roll控制在正负0.25弧度前进速度0.4m/s转向速度0.8rad/s。代码最后的安全收尾很重要先发Sit让狗坐下等它稳定后再发Damp让电机松劲这样你可以直接搬动它或者关机关闸。如果不做这一步狗保持站立状态直接关机关节会像被锁住一样强行搬有损坏风险。5.3 完整代码 dance_go2.py 使用 unitree_sdk2py 控制宇树 Go2 执行一段基础舞蹈动作。 适用环境 - Python 3.8 - unitree-sdk2py 2.x - Go2 出厂固件版本2024年之后 使用方式 1. 先确认PC与Go2处在同一局域网且能ping通Go2的IP。 2. 修改下方 NETWORK_INTERFACE 为你的实际网卡名称。 3. 运行python dance_go2.py import time from unitree_sdk2py.core.channel import ChannelFactoryInitialize from unitree_sdk2py.go2.sport_client import SportClient # 网卡名 # Ubuntu有线常用 eth0无线常用 wlan0 # Windows 可用 WLAN 或 以太网按实际调整。 NETWORK_INTERFACE eth0 def execute_move(client, x0.0, y0.0, yaw0.0, duration1.0, settle0.3): 下发Move指令并保持duration秒然后停止停稳settle秒。 client.Move(x, y, yaw) time.sleep(duration) client.Move(0.0, 0.0, 0.0) time.sleep(settle) def safe_stop(client): 安全停止原地停稳然后坐下并松劲。 client.Move(0.0, 0.0, 0.0) time.sleep(0.5) client.Sit() time.sleep(1.5) client.Damp() time.sleep(0.5) def main(): print([1/5] 初始化SDK通道...) ChannelFactoryInitialize(0, NETWORK_INTERFACE) print([2/5] 创建运动控制客户端...) client SportClient() client.SetTimeout(10.0) client.Init() print([3/5] 让狗站立...) client.StandUp() time.sleep(2.0) client.BalanceStand() time.sleep(1.0) print([4/5] 开始舞蹈动作...) # 动作1身体左右摇摆两个来回 for _ in range(2): client.Euler(0.0, 0.0, 0.25) time.sleep(0.8) client.Euler(0.0, 0.0, 0.0) time.sleep(0.6) client.Euler(0.0, 0.0, -0.25) time.sleep(0.8) client.Euler(0.0, 0.0, 0.0) time.sleep(0.6) # 动作2向前一步再后退一步 execute_move(client, x0.4, y0.0, yaw0.0, duration1.0) execute_move(client, x-0.4, y0.0, yaw0.0, duration1.0) # 动作3原地左转半圈右转半圈 execute_move(client, x0.0, y0.0, yaw0.8, duration1.2) execute_move(client, x0.0, y0.0, yaw-0.8, duration1.2) # 动作4小幅快速前进模拟连续踏步的感觉 execute_move(client, x0.3, y0.0, yaw0.0, duration0.5) execute_move(client, x0.3, y0.0, yaw0.0, duration0.5) print([5/5] 舞蹈结束安全收尾...) safe_stop(client) print(Done.) if __name__ __main__: main()这段代码跑起来后你会看到Go2依次完成站立、左右摇摆、前后移动、原地转圈、小步前移最后坐下并松劲。整套流程大约30秒作为第一版“机器狗舞蹈”的demo完全够用。想进一步丰富动作也没问题在“动作2”和“动作3”之间再插入一个Euler点头序列或者在“动作4”之后加一段快速左右转向都能明显提升舞蹈的层次感。改动的核心就是遵循“发指令—等待—停止—再等待”这个节奏不打破狗的动作稳定性。6. 实测最容易翻车的5个细节以及我的调参方法6.1 连接层绕不开的网络接口名和防火墙先说最让我头疼的网络接口名。SDK的ChannelFactoryInitialize(0, eth0)这里的eth0不是随便写的。你PC上有多少个网卡就有多少个候选名——有线网卡、WiFi网卡、虚拟机的虚拟网卡、Docker网桥全都算。我在一次调试中明明SDK已经提示“init success”但就是收不到狗的状态数据。查了大半天才发现系统里有多个网络接口SDK用的默认路由不是连接Go2的那一条。解决办法也简单用ifconfig或ip addr看清所有网卡名把连接Go2的那张网卡名显式填进去问题立刻消失。Windows下还有个隐藏坑防火墙默认会拦截DDS的UDP广播。第一次跑的时候如果SDK日志显示“publisher opened”但狗没反应先检查Windows Defender防火墙是否放行了Python进程或直接把当前网络配置文件设为“专用网络”。6.2 控制层指令被吞、死区和安全状态机指令被吞是我在编舞过程中遇到最多的现象。表现是某一拍的动作偶尔没有执行狗直接跳到下一个动作。原因是这一拍的动作指令距离上一条太近了DDS队列里还没来得及处理就互相覆盖。我的排查链路是这样的先把所有sleep统一改成0.5秒以上如果不再丢指令说明是时序间隔问题如果还是丢就检查代码里有没有多线程同时调用client.Move因为SportClient不是线程安全的。多个线程抢同一把“控制锁”也会导致指令被覆盖。还有一个容易被忽略的点当狗处于Damp模式下时你发任何Move或Euler指令都是无效的。Damp意味着电机松劲、状态机重置必须重新执行StandUp之后才能继续跳舞。所以如果你在程序中途调用了Damp制造“断电躺平”效果后面想接继续跳一定记得先StandUp。6.3 参数层幅度、时长和地面阻尼怎么调跳舞效果好不好七成取决于参数调得对不对。我总结了一套比较实用的调参顺序适合新手从零起步先把所有动作幅度缩小到“安全值”Euler角的roll不超过0.15弧度Move的x速度不超过0.2m/syaw速度不超过0.5rad/s。在这个幅度下把整套舞蹈跑通确认狗不会失稳然后逐步放大。放大的顺序也有讲究先加时长再加幅度。一个动作如果执行时长太短狗还没走到位就被切走了表现起来就像“抽搐”先增加到1.2秒左右看动作是否完整再放大幅度看稳定性。这两步的优先级是延时时长优先幅度大小次之。地面阻尼这个变量很容易被忽略。地毯上狗的步态会显得“软绵绵”木地板上则更容易打滑瓷砖地面最危险——转向时打滑概率很高。实测下来短毛地毯或粗粝的PVC运动垫效果最好。如果你只能在家里瓷砖地上测试务必把yaw速度降到0.4以下否则转弯时视觉上像在溜冰。6.4 安全层第一次实测的建议流程最后说安全这部分比代码更重要。我第一次让Go2完整跑舞蹈流程之前做了一件事把狗带到一块四周无遮挡的空地旁边放了一个软垫墙然后把遥控器放在触手可及的位置一旦出现异常立刻切回遥控器模式接管控制。注意遥控器和SDK是有控制权竞争的——如果你没有把手柄关机它的指令优先级会高于SDK指令导致SDK的动作被“顶掉”。所以正式测试前要么把遥控器放远一点要么确认没有其他设备连上了狗的WiFi。如果狗在跳舞过程中突然失去平衡不要跑过去硬扶。最安全的处理是等它自己触发跌倒保护或者切遥控器让它趴下再手动检查有没有损伤。飞跑过去接住狗反而可能被它甩动的腿部打到。另外建议每次舞蹈测试控制在两分钟内。Go2的关节电机在高频动作下发热很快连续跳太久轻则动作变形重则触发电机过热保护需要冷却很久才能恢复。我的习惯是跳完一段后让狗在Sit状态下休息两三分钟再继续省下的电机维修费可比省下的时间值钱多了。6.5 我实测后留下的三个编舞心法第一个心法先跑通再编花活。我第一次编的舞蹈动作列表是十五个动作的“宏大计划”结果第一次测试到第三个动作就翻车了。后来改成先把三个基础动作——站立、前后移动、左右摇摆——跑顺再逐步添加新动作整个过程的挫败感少了很多。第二个心法每个动作之间都要给“呼吸感”。所谓呼吸感就是动作与动作之间不要无缝衔接留出0.3到0.5秒的BalanceStand稳定期。这个间隔不仅让狗执行更稳定舞蹈本身也更有节奏感——像人跳舞一样动作之间永远有微小停顿。第三个心法把每一次修改都落到代码版本里。调参过程会伴随大量“把0.3改成0.5”“把0.8改成1.0”的细碎改动不记录的话半小时后你会完全忘记哪组参数是目前最优的。我现在会在代码文件头部写一个“调参日志”注释块每次改动都追加一行。这个小习惯在长时间调试场景下救了我无数次。