NAO V6 的开发环境配置这件事我前前后后折腾了不止一次从最初拿到机器人不知道从哪下手到后来帮实验室和几个朋友团队搭建了一套能稳定复用的流程中间踩过的坑比想象中多。今天这篇就把 NAO V6 开发环境配置的全过程拆开来讲从工具选型、Python 环境、网络连接到第一个可运行的脚本该注意的细节全部写在下面。文末我还会把整理好的文件清单和目录结构列出来照着做基本不会出大问题。适合看这篇的读者有三类刚拿到 NAO V6 机器人、正在配环境的实验室新人准备基于 NAO 做二次开发但被 SDK 版本搞晕的开发者以及手头没有实体机器人、想先用模拟器写逻辑的爱好者。不管你是 Windows、macOS 还是 Linux核心思路完全一致我会在关键节点标注三个系统的差异。1. 项目概述NAO V6 开发环境配置的完整思路1.1 为什么要专门梳理一遍开发环境NAO V6 不像普通嵌入式设备那样插上 USB 就能开干。它本身运行着一套基于 Linux 的 NAOqi 操作系统你写的代码要么通过 Choregraphe 图形化编排后上传到机器人要么通过 Python 或 C SDK 在电脑侧连接机器人、调用 NAOqi 提供的各种 API 去控制动作、语音、视觉、传感器。这两条路的前提都一样电脑端必须有一套和机器人端 NAOqi 版本匹配的开发环境。我遇到过不少朋友卡在第一步症状很典型SDK 下载下来了Python 装好了import naoqi 却直接报错或者 Choregraphe 装好了却一直连不上机器人。这些问题十有八九不是机器人坏了而是电脑端环境没配对。版本不匹配、环境变量没配、网络不在同一网段、防火墙拦了端口任何一个环节出问题都会让你怀疑人生。所以把开发环境当成一个独立的小项目来对待按步骤走是最省时间的做法。1.2 NAO V6 的软件栈构成NAO V6 这一代机器人的软件栈其实可以拆成三层来看机器人端系统NAOqi OS基于 Linux 内核负责底层驱动、传感器采集、行为管理和网络服务对外暴露 NAOqi API。V6 出厂搭载的 NAOqi 版本一般是 2.9.x这个版本号直接决定了你电脑端该用哪个 SDK。开发端工具Choregraphe 可视化编程软件支持拖拽式行为框图设计也可以直接内嵌 Python 脚本块同时支持连接实体机器人或启动内置模拟器。开发端 SDKNAOqi Python SDK 和 C SDK本质上是把 NAOqi API 封装成了本地可调用的库。Python SDK 在 2.8.x 时代仍要求 Python 2.72.9.x 开始才逐步支持 Python 3这是个非常重要的坑。明白了这三层结构配置环境就不再是东一榔头西一棒子了。你只需要把电脑端工具链配好再保证电脑和机器人之间的网络通路畅通剩下就是调用 API 写逻辑的问题了。2. 开发环境总体设计与工具选型2.1 选型思路模拟器优先实机验证我的建议是环境搭建阶段就把模拟器和实机两条链路都打通但日常开发默认用模拟器。原因很简单机器人反复开关机、充电、连接调试对硬件寿命和开发效率都不友好。Choregraphe 自带的模拟器能模拟大部分行为模块包括动作、语音、传感器的基础反馈足够你验证逻辑。实机验证则放在两个节点一是环境刚配好时跑一个最简单的“自检脚本”确认电脑能通过 NAOqi API 控制真实机器人二是完成一个完整行为模块后上实机看动作效果和参数调优。这条“模拟器开发、实机验收”的路径能帮你省掉大量无效等待。2.2 工具版本匹配是环境配置的命门NAO V6 配套的工具版本我直接把我实测可用的组合列出来组件推荐版本说明NAOqi OS机器人端2.9.x以机器人内置为准可通过系统设置查看Choregraphe2.8.6 或更高支持 V6自带模拟器Python SDK2.8.x / 2.9.x 对应版本注意区分 Python 2.7 与 3.x 版本包Python 解释器2.7.18 或 3.x按 SDK 决定老 SDK 只认 2.7操作系统Windows 10/11、macOS、Ubuntu三者均支持这里要特别强调版本匹配Choregraphe 的版本号、Python SDK 的版本号和机器人端 NAOqi 的版本号三者之间不能差太远。比如机器人端是 NAOqi 2.9.5你却用 2.1.x 的 Python SDK连上之后大部分 API 的返回结构都对不上排查起来非常痛苦。我在文末整理的文件包里会把对应版本的下载入口和校验方式一并标注清楚。2.3 为什么不建议一上来就选 C SDKNAO 的 C SDK 性能更好但它带来的额外复杂度是需要配置交叉编译工具链、需要在电脑上装对应架构的依赖库、还要处理编译产物和机器人端的兼容性。对于绝大多数实验室项目和课程作业来说Python SDK 已经完全够用NAOqi 的 Python API 覆盖了动作、语音、视觉、对话、导航等几乎所有能力而且写起来直观、改起来快。如果你是做运动控制底层算法或者需要极致性能的实时控制那再考虑 C。我认识的做 NAO 步态算法的朋友确实用 C但那是少数场景。对刚入门的人来说先跑通 Python 链路再决定要不要引入 C是投入产出比最高的路线。3. 分步配置实操从零开始搭建可用环境3.1 第一步下载并整理所需文件配置环境最容易乱的就是文件管理。我建议在工作目录下建一个清晰的目录结构所有工具和脚本都归档好后面排错时能省一半时间nao-dev/ ├── installers/ # Choregraphe 安装包、Python 安装包 ├── sdks/ # Python SDK、C SDK解压后 ├── config/ # 环境变量脚本、网络配置脚本 ├── examples/ # 测试脚本、示例工程 └── docs/ # 官方文档、版本对照表、README下载时注意Choregraphe 和 SDK 都要从官方开发者站点下载认准版本号。有些第三方网站会提供整合包但我不建议用因为你不知道里面是什么版本、有没有被改动过。下载完成后先核对文件 MD5 或 SHA256 值再开始安装这一步虽然啰嗦但能避免很多诡异问题。3.2 第二步安装 Python 并配置虚拟环境如果你的 SDK 是 2.8.x 版本那对应的 Python SDK 包是基于 Python 2.7 编译的这时候必须装 Python 2.7.18。如果拿到的是 2.9.x 版本且标注支持 Python 3那建议装 Python 3.6 到 3.8 之间的版本太新的版本会因为某些依赖库不兼容而出问题。装完 Python 后我强烈建议用虚拟环境隔离 NAO 开发环境避免和系统 Python 冲突。具体操作# 创建虚拟环境 python -m venv naoenv # 激活环境Windows naoenv\Scripts\activate # 激活环境macOS/Linux source naoenv/bin/activate然后把 Python SDK 解压后的路径加入环境变量。以 Windows 为例需要把 SDK 中的lib目录和根目录都加入PYTHONPATH否则import naoqi会找不到模块# Windows 临时设置建议写入系统环境变量 set PYTHONPATHD:\nao-dev\sdks\pynaoqi-python2.7-2.9.x\lib;D:\nao-dev\sdks\pynaoqi-python2.7-2.9.x # macOS/Linux 临时设置 export PYTHONPATH/path/to/naoqi-sdk/lib:/path/to/naoqi-sdk提示把 PYTHONPATH 写入系统环境变量时记得同时保留系统原有的 PYTHONPATH用分号Windows或冒号macOS/Linux拼接不要覆盖。踩过这个坑的人绝对不止我一个。验证 SDK 是否可用打开 Python 交互终端执行import naoqi from naoqi import ALProxy print(naoqi.__file__)如果能看到模块路径打印出来说明 SDK 导入成功Python 环境这一关就过了。3.3 第三步安装 Choregraphe 并配置连接Choregraphe 是图形化开发的核心工具。安装过程不再赘述重点是安装完成后的连接配置。启动 Choregraphe 后先设置机器人 IP。有两种方式在连接面板中直接填入机器人的 IP 地址通过“编辑 - 偏好设置”里配置默认连接参数这样每次启动都会自动尝试连接。实体机器人默认开放 9559 端口给 NAOqi 服务Choregraphe 和 Python SDK 都是通过这个端口通信的。机器人在同一局域网内建议使用静态 IP避免 DHCP 分配变化导致经常改配置。连接之前先做两步确认用 ping 命令测试电脑到机器人的网络连通性ping 192.168.1.100改成你的机器人 IP看丢包率和延迟。检查防火墙是否放行 9559 端口。Windows 系统尤其容易在这里出问题需要在防火墙高级设置里添加入站规则把 Choregraphe 或 Python 的访问权限打开。如果暂时没有实体机器人可以点 Choregraphe 工具栏的模拟器按钮它会启动一个虚拟机器人界面里能看到 NAO 的 3D 模型和传感器反馈面板。模拟器模式下的开发流程和实机几乎一致只是部分硬件相关参数需要后续在实机上重新校准。3.4 第四步编写并运行第一个测试脚本环境配好之后先用一个最简单的脚本验证全链路是否通畅。下面的脚本做了两件事连接 NAO 的语音合成服务让机器人说一句话再读取它的电量证明传感器数据通路正常import time from naoqi import ALProxy ROBOT_IP 192.168.1.100 ROBOT_PORT 9559 # 语音合成 tts ALProxy(ALTextToSpeech, ROBOT_IP, ROBOT_PORT) tts.say(Hello, NAO. This is my first test.) # 读取电量 battery ALProxy(ALBattery, ROBOT_IP, ROBOT_PORT) level battery.getBatteryCharge() print(Battery level: {}%.format(level)) time.sleep(1)如果机器人成功开口说话并且打印出电量数值那恭喜你的 NAO V6 开发环境已经全部打通了。之后你可以在这个基础上继续叠加动作、视觉、对话等模块。再进一步试试让它做一个简单的动作比如点头motion ALProxy(ALMotion, ROBOT_IP, ROBOT_PORT) motion.wakeUp() # 唤醒机器人电机上电 motion.angleInterpolation( [HeadPitch], [0.3, -0.1], [1.0, 2.0], True )注意wakeUp()会让机器人从休眠状态进入待命状态电机全部上电。如果是第一次操作建议把机器人放在地面或者防倾倒的支架上防止它做出意料之外的动作。rest()则会让它回到休眠状态测试完毕记得调用。4. 常见问题与排查技巧实录4.1 问题一import naoqi 报 ModuleNotFoundError这个错误绝大多数情况是 PYTHONPATH 没配对或者 Python 版本和 SDK 不匹配。先确认你用的 Python 版本和 SDK 要求的版本是否一致再看sys.path里有没有 SDK 路径import sys for p in sys.path: print(p)如果 SDK 路径没出现回到 3.2 节重新配置环境变量。如果是版本不匹配去官方站点重新下载对应版本。还有一种情况虚拟环境里装过别的包导致 naoqi 模块被某个同名目录遮蔽检查一下虚拟环境的 site-packages 里有没有残留的 naoqi 目录。4.2 问题二Choregraphe 一直连不上机器人先从下往上排查机器人和电脑是否在同一网段用ipconfigWindows或ifconfigmacOS/Linux查看电脑 IP和机器人 IP 对比前三位是否一致。机器人是否处于可连接状态NAO V6 在休眠状态下网络服务可能仍在运行但如果之前被设定的“飞行模式”之类的策略限制会导致端口不可达。9559 端口是否被防火墙拦截临时关闭防火墙测试一下如果能连上就说明是规则问题再去细化放行规则。是否用了错误的 IP机器人 IP 可以在 Choregraphe 连接面板左下角扫描发现或者在机器人 Web 管理页面查看建议以这两个来源为准不要凭记忆输入。4.3 问题三模拟器能跑实机动作异常这是最典型的环境差异问题。模拟器里 NAO 的运动学和物理反馈是理想模型实机则有电机扭矩、重心偏移、地面摩擦力等因素影响。我的经验是写动作时先把幅度、速度参数调小一半在实机上观察实际表现再逐步逼近目标参数。特别是angleInterpolation这类直接控制关节角度的 API参数差一点实机上的视觉效果就完全不同。另外实机运行时记得调用ALMotion的setStiffnesses把相关关节的刚度打开否则电机会处于松垮状态动作执行会失败或者很怪异。模拟器不会暴露这个问题实机必现。4.4 问题四机器人连接时好时坏如果你的手机、电脑、机器人共用一个 WiFi而且路由器是家用级的很容易出现并发连接数超限导致 NAO 掉线。解决办法是给机器人单独拉一根网线连路由器 LAN 口同时给电脑也走有线或 5G 频段。还有一个容易被忽略的点NAO V6 的 WiFi 天线功率一般和路由器的距离、遮挡物都会影响稳定性别让机器人隔着一堵承重墙和路由器通信。5. 从环境配置到第一个完整行为模块5.1 用行为框图搭一个“自我介绍”流程环境跑通之后我建议用 Choregraphe 搭一个完整的行为流程来巩固对开发流程的理解。比如一个“自我介绍”行为开始事件触发后先用ALTextToSpeech说“大家好我是 NAO”同时让ALMotion执行一个抬手的动作停顿 2 秒播放一段默认动画或再做一个鞠躬动作最后回到闲置状态。在 Choregraphe 里这个流程就是几个盒子Box用连线串起来的事。把语音盒子和动作盒子并联在同一个输入端口下它们就会并行执行。串联则用顺序连线保证一个执行完再执行下一个。这个过程能帮你理解 Choregraphe 的时序模型也方便后续把行为导出成 Python 代码来细看。5.2 配置过程中的几条心得最后分享几个我实际使用中的体会都是文档里不会写的第一环境配置不是一次性的。Choregraphe 和 SDK 升级、机器人 NAOqi 系统重置、电脑系统大版本更新都可能导致之前配好的环境突然失效。建议把 3.1 节的文件包和配置脚本纳入版本管理团队内部共享时新手按照 README 走一遍就能恢复环境不用每次重新摸索。第二所有连接类的配置优先写成配置文件而不是硬编码在脚本里。我习惯在项目里放一个config.yaml或robot_config.py统一管理 IP、端口、用户名密码需要切换机器人的时候只改一处不会因为 IP 散落在各处而出错。第三善用 NAOqi 的日志和调试接口。ALLogger模块可以设置各模块的日志级别当你觉得某个行为表现不正常时把日志级别调到 DEBUG能看到完整的调用链和参数排查效率比对着代码猜高得多。配置 NAO V6 开发环境这件事本质上就是三步版本配对、网络打通、写通一个测试脚本。把这三步按顺序走完后面的开发就是自由的。我整理的文件包里包含了安装包索引、配置脚本、示例代码和版本对照表覆盖了 Windows 和 macOS 两种环境你需要的其实就是按照这篇文章的顺序一步步把环境跑起来。动手吧配好之后你会发现NAO 的世界比想象中有意思得多。