很多第一次拿到 NAO V6 的人第一反应是开机、连 Wi-Fi然后打开 Choregraphe 拖几个方块试试。这个流程本身没错但真正到写 Python 脚本、跑通 NAOqi SDK 的时候坑就一个接一个地来了——依赖装不上、IP 不通、SDK 版本对不上、虚拟环境里 import 直接报错。这篇记录我搭 NAO V6 开发环境的完整过程从网线连接、SDK 版本选择、虚拟环境隔离到 Choregraphe 连接和第一个能跑的脚本所有用到的配置文件、依赖清单和验证代码都会整理在最后照着一步步做基本能一次过。适合刚入手 NAO 的开发者、机器人课程助教以及想在自己的笔记本上跑通 NAO 仿真或真机控制的同学参考。1. 配置前置先把硬件和网络环境理清楚1.1 NAO V6 开发到底需要哪些东西NAO V6 是软银/优必选时期典型的 Pepper 系人形机器人开发模式基本沿袭 NAOqi 框架机器人本体跑着一个 NAOqi 操作系统开发者通过局域网把指令发给机器人或者用 Choregraphe 图形化编排行为树或者直接用 Python/C 写 SDK 脚本连接。V6 相比 V5 最大的变化是硬件升级到了 Atom E3845 平台系统镜像也换成了基于 Gentoo 的 OpenNAO但开发接口层面基本还是那套 NAOqi API。所以你要准备的硬件和软件清单我直接列一下一台装有 Windows / macOS / Linux 的笔记本64 位系统内存建议 8GB 以上NAO V6 机器人本体以及配套的电源适配器、网线Choregraphe 套件V6 对应的版本是 Choregraphe 2.8.xPython 2.7 环境注意NAOqi Python SDK 官方版本只支持 Python 2.7这是很多人栽跟头的地方NAOqi Python SDK对应 V6 的 2.8.x 版本一个支持有线连接的局域网环境或者一台无线路由器这里我需要多说一句很多人以为装个 Choregraphe 就够了其实 Choregraphe 只是一个图形化工具真正要写自己的 Python 逻辑、做二次开发必须装 NAOqi Python SDK。这两个是独立的东西后面我会详细拆。1.2 为什么网络连接决定了开发成败NAO 机器人的开发全部基于网络通信本质上是“你的电脑作为客户端机器人 NAOqi 作为服务端”所有指令都是通过 NAOqi API 以 XML-RPC 或长连接的形式发过去的。所以第一步不是装软件而是把网络打通。我推荐刚开箱时用网线直连而不是 Wi-Fi。原因很简单网线直连不需要提前知道路由器的 SSID 和密码也不存在跨网段问题。NAO 默认 IP 是 192.168.1.100或者你可以在机器人上通过语音/触觉菜单查看电脑网卡设成同一网段的静态 IP比如 192.168.1.101插上网线就能 ping 通。有人会问为什么不用 DHCP 自动获取因为很多办公室或实验室路由器开了 AP 隔离设备之间互相 ping 不通或者 NAO 连接 Wi-Fi 后拿到的 IP 和电脑不在同一网段。有线直连最稳也最容易排查问题。等确认有线通了再切换到 Wi-Fi 模式也不迟。具体设置电脑 IP 的方法Windows 和 mac 略有差异但核心思路是一致的把有线网卡的 IPv4 设置为手动IP 地址填 192.168.1.101子网掩码 255.255.255.0网关可以不填。设置完以后用以下命令验证ping 192.168.1.100如果能通说明网络基础已经OK。如果 ping 不通先别急着往下走大概率是 NAO 没开机完成或者网线/网口有问题再或者 NAO 的 IP 不是默认值。V6 开机后可以在头部触觉传感器上短按一次机器人会语音播报当前 IP 地址这个功能非常实用。2. Python 开发环境搭建版本、依赖和虚拟环境2.1 Python 2.7 的选择与原因NAOqi Python SDK 的官方实现基于 Python 2.7这可能是整个配置过程中最反直觉的地方。V6 时代已经是 2019 年前后的产物当时 Python 3 已经普及但 Aldebaran/SoftBank 的 SDK 一直没把 Python 3 支持做完整。你要用官方 SDK 连真机就得老老实实装 Python 2.7。我个人的建议是不要用系统自带的 Python 2.7而是安装 Anaconda 或者 Miniconda然后用 conda 创建一个 Python 2.7 的独立环境。这样做的好处有几个一是不会污染系统 Python二是以后切换其他项目时互不干扰三是在 macOS 上可以绕开系统自带 Python 2.7 被移除的问题。创建独立环境的命令如下conda create -n nao_env python2.7 conda activate nao_env激活后你会看到命令行前面带上了(nao_env)前缀这就说明当前终端已经切到了 Python 2.7 环境。后续的所有 pip 安装和 Python 脚本都在这同一个终端里执行不要另开终端忘记激活。2.2 安装 NAOqi Python SDKNAOqi Python SDK 的官方发布包是一个压缩文件解压后里面会有一个naoqi文件夹以及pynaoqi.pth这样的路径配置文件。你需要把解压后的目录放到一个固定位置例如~/naoqi-sdk/ ├── naoqi ├── pynaoqi.pth ├── libnaoqi.so ├── ...然后关键的一步把 SDK 路径添加到PYTHONPATH环境变量。否则 Python 里执行import naoqi会直接报ImportError: No module named naoqi。以我常用的方式为例在.bashrc或.zshrc里加上export PYTHONPATH/Users/你的用户名/naoqi-sdk:$PYTHONPATH export DYLD_LIBRARY_PATH/Users/你的用户名/naoqi-sdk:$DYLD_LIBRARY_PATH注意macOS 上需要用DYLD_LIBRARY_PATHLinux 上对应的是LD_LIBRARY_PATH。Windows 上则是在系统环境变量的PYTHONPATH里添加 SDK 路径同时在Path里加上 SDK 目录。配置完后重新打开一个终端激活 conda 环境执行验证python -c import naoqi; print(naoqi.__version__)如果输出版本号说明 SDK 安装成功。这一步是很多教程忽略的地方直接复制粘贴代码却发现 import 失败百分之八十是环境变量没配好。2.3 依赖包安装与常见版本冲突除了 NAOqi SDK 本身你还需要安装几个基础依赖比如requests、netifaces等。由于 Python 2.7 已经停止维护pip 默认源可能装不上某些包的新版本建议先指定一个兼容的源比如pip install requests netifaces如果提示找不到包或版本不满足可以考虑使用豆瓣源或阿里源。但在国内内网环境下最稳妥的方式是直接安装官方 SDK 自带的依赖或者使用pip install pi-robot-tools这类辅助包。不过我对这些第三方包持保留态度能用官方 SDK 解决的尽量不引入多余的依赖。我建议在nao_env环境里先装这几个包requestsnetifacespytest用于写测试pyreadlineWindows 下增强交互式命令行可选装完后可以用pip list检查环境确保没有和系统 Python 包混在一起。3. Choregraphe 安装与机器人连接3.1 Choregraphe 的作用与版本选择Choregraphe 是 NAO 的图形化编程工具你可以把它理解成“机器人版的 Scratch”。它支持拖拽行为框来编排动作、语音、动画、传感器事件同时它也是一个调试工具可以实时查看机器人状态、摄像头画面、内存键值、日志流。对新手来说Choregraphe 是最快看到机器人动起来的途径。Choregraphe 的版本必须和 SDK 版本匹配。V6 对应的 Choregraphe 是 2.8.x这个版本可以在官方开发者社区下载如果你用的是优必选在国内提供的 V6 版本一般随机器人附带的授权文件里有对应的安装包光盘或售后网盘链接。安装过程比较简单Windows 上直接双击安装macOS 上拖入 Applications 即可Linux 上解压后运行安装脚本。安装完以后打开 Choregraphe它会自动扫描局域网里的 NAO 机器人。如果扫描不到可以手动输入机器人的 IP 地址进行连接。3.2 连接方式与网络模式切换连接 Choregraphe 之前确保机器人已经开机并完成了系统自检。开机后 NAO 会亮起眼睛发出语音提示进入待机状态。此时你可以在 Choregraphe 右上角的连接区域点击“连接”选择“连接到机器人”输入 IP 地址点击确定。有几个细节值得注意如果机器人和电脑不在同一网段Choregraphe 扫描不到是正常的先解决网络问题。首次连接时Choregraphe 可能会提示你输入 NAO 的账号和密码默认账号是nao密码一般是nao但也有部分 V6 出厂设置了单独的管理密码不确定的可以问供应商。连接成功后Choregraphe 底部状态栏会显示绿色图标并出现机器人的俯视图和传感器数据。如果你的机器人当前连接的是 Wi-Fi而电脑走的是网线直连那么它们是两个不同的网络接口Choregraphe 依然可以连接 Wi-Fi IP。但为了开发调试方便我更推荐把机器人切到有线模式或者让机器人和电脑连接同一个 Wi-Fi避免双网络干扰。切换 Wi-Fi 的操作可以在 NAO 的 Web 管理界面完成用浏览器打开机器人的 IP 地址进入 Network 设置填写 Wi-Fi 的 SSID 和密码保存后机器人会重新连接。等它报出新的 IP 后再用新 IP 连接 Choregraphe。4. 第一个 Python 脚本验证开发环境4.1 编写连接测试脚本环境和工具都就位后我们来写第一个真正的 Python 脚本。这个脚本的目标很简单连接 NAO 机器人读取它的名字和电量再让它说一句话。这样既能验证网络连接也能验证 SDK 是否工作正常。将下面的代码保存为nao_test.py# -*- coding: utf-8 -*- import naoqi from naoqi import ALProxy # 机器人 IP 和端口 ROBOT_IP 192.168.1.100 ROBOT_PORT 9559 # 创建 ALTextToSpeech 代理 try: tts ALProxy(ALTextToSpeech, ROBOT_IP, ROBOT_PORT) tts.say(Hello, I am NAO. Development environment is ready.) print([OK] Text to speech works.) except Exception as e: print([ERROR] Failed to connect or say:, e) exit(1) # 读取机器人的基本状态 try: memory ALProxy(ALMemory, ROBOT_IP, ROBOT_PORT) battery memory.getData(Device/DeviceList/Battery/Charge) print([INFO] Battery level: {}%.format(battery)) except Exception as e: print([WARN] Cannot get battery info:, e)这段代码里有几个关键点值得展开说。首先是ALProxy这是 NAOqi 框架中最核心的类。它封装了远程调用的细节你只需要指定服务名比如ALTextToSpeech、机器人 IP 和端口就能像调用本地函数一样调用机器人上的服务。端口 9559 是 NAOqi 的默认端口一般情况下不要改。其次是ALTextToSpeech服务它负责语音合成。V6 的语音引擎支持中英文默认语言可以在 Choregraphe 或 Web 管理页面设置。如果第一次运行机器人说的是英语但你想让它说中文需要在调用say之前设置语言。最后是ALMemory它是 NAO 的一个共享数据总线机器人的所有传感器数据、系统状态都通过键值对的方式放在这里。上面的代码读取的Device/DeviceList/Battery/Charge就是电量百分比。4.2 运行脚本与预期输出激活 conda 环境然后运行python nao_test.py如果一切正常你会看到类似下面的输出[OK] Text to speech works. [INFO] Battery level: 67%同时NAO 机器人会真的开口说话。如果输出报错先不要慌按照错误信息排查。我把最常见的错误整理成了对照表放在下一节。值得一提的是很多人第一次跑通语音后会误以为开发环境已经大功告成。其实这只是一个起点更常见的需求是控制机器人行走、转头、播放动画、接收摄像头画面。这些功能需要深入学习 NAOqi 框架的各个服务模块但好在你现在的环境已经能跑通任意一个服务模块了后续只是换服务名和参数的问题。5. 常见问题与排查技巧实录5.1 连接失败的十种典型情况我在实际配置和帮别人排错的过程中遇到过非常多的连接失败场景。这里整理成一张速查表你可以直接对照排查。症状可能原因解决办法ping 不通机器人 IP网线没插好 / 机器人未完成启动检查网线接口灯等待机器人眼睛稳定亮起后重试ping 通但 Choregraphe 扫描不到Choregraphe 版本和机器人固件不匹配确认使用 2.8.x 版本或手动填写 IP 连接Python import naoqi 报错PYTHONPATH 没配置或配置错误检查环境变量确认 SDK 解压路径无中文连接后立即断开机器人账号密码错误确认账号nao和密码必要时重置用户密码语音 say 没声音音量过低或语音引擎未初始化在 Choregraphe 的音量面板调高音量或先执行tts.setVolume(80)机器人行动缓慢/卡顿网络延迟高或机器人 CPU 占用满切换到有线连接关闭不必要的后台服务代码报ALError和Proxy creation failed服务名拼写错误或机器人大脑异常检查服务名大小写重启 NAOqi 进程在浏览器后台重启摄像头打不开摄像头被其他应用占用关闭 Choregraphe 中的视觉预览再运行 SDK 代码macOS 上 import naoqi 崩溃DYLD_LIBRARY_PATH 未设置在终端里手动执行 export再运行 PythonWindows 上找不到 DLLSDK 需要 VC 运行库安装 Visual C Redistributable for Visual Studio 2015这张表里的每一条我基本都亲眼见过。其中最隐蔽的是最后一条Windows 上如果缺少 VC 运行库SDK 加载时不会报错说缺库而是直接在import naoqi时崩掉或者弹窗。解决办法是安装微软官方的 VC Redistributable2015-2019 版本都可以。5.2 网络排错的独家心得网络问题是最容易让人抓狂的因为表象都一样连不上、扫描不到、超时。我有几条排查心得分享给你第一先确认机器人的 IP。V6 开机后长按头部触觉传感器大概 3 秒机器人会进入“设置模式”并语音播报当前 IP。如果还是不确定可以连接机器人的 Wi-Fi 热点SSID 一般是NAO_xxxx然后用浏览器打开http://198.51.100.10查看管理页面。不过这个热点模式通常只在初始设置时打开日常开发用得少。第二检查电脑的防火墙。Windows 的防火墙经常会拦截 NAOqi 的 UDP 广播导致 Choregraphe 扫描不到机器人但直接填 IP 连接又能通。解决办法是在防火墙入站规则里放行 Choregraphe 和 Python或者临时关闭防火墙测试。第三如果你在公司或学校的局域网内最好提前确认路由器没有开启“AP 隔离”。这功能会把同一局域网的设备互相隔离导致机器人和电脑无法直接通信。遇到这种情况最简单的方案是拿一个独立的小路由器把 NAO 和电脑都接上去。5.3 版本匹配的坑SDK、Choregraphe、固件不少同学在配置 V6 时手里的 SDK 是 2.1.xChoregraphe 是 2.8.x机器人固件却是 2.4.x结果各种奇怪问题。NAO 的软件开发有一条铁律SDK、Choregraphe、固件三者的主版本号必须保持一致。V6 出厂固件一般是 2.8.x对应的 SDK 和 Choregraphe 也必须是 2.8.x。如果你用的是 V5 的 SDK 去连 V6轻则某些 API 不可用重则直接无法连接。判断方法很简单连接成功后在 Choregraphe 的状态栏里能看到机器人的系统版本号或者在 Web 管理页面的“系统信息”里查看。如果你手里的 SDK 确实版本不对最快的办法是到官方社区或供应商处下载对应 V6 的 SDK 包。这里多说一句题外话NAO 是教育科研领域使用非常广泛的平台国内外很多高校都用它做人机交互和人工智能课程所以相关的版本匹配经验在网上很多搜的时候注意匹配版本号别拿 V4/V5 的教程硬套 V6。6. 附所有文件的配置清单与目录结构6.1 我整理的文件清单“附所有文件”这个部分我把自己实际用到的配置文件和验证脚本整理成了标准目录结构你可以直接把这份当成自己项目的初始模板。nao_v6_workspace/ ├── nao_env_setup.md # 环境配置说明Markdown 文档 ├── requirements.txt # Python 依赖包清单 ├── nao_test.py # 连接与语音验证脚本 ├── nao_motion.py # 动作控制示例 ├── nao_vision.py # 摄像头图像获取示例 ├── config.ini # 机器人 IP、端口、语言等配置 ├── sdk/ # NAOqi Python SDK 解压目录 └── logs/ # 运行日志目录config.ini的内容大致如下[nao] ip 192.168.1.100 port 9559 username nao password nao language Chinese [debug] log_enabled true log_level INFO这样把 IP 和端口从代码里抽离出来后续写多个脚本时统一读取改配置不用改代码。我用的是 Python 内置的ConfigParser模块来读取非常简单import ConfigParser config ConfigParser.ConfigParser() config.read(config.ini) robot_ip config.get(nao, ip) robot_port config.getint(nao, port)6.2 Python 依赖清单requirements.txt里的内容会根据你的需求变化但对于基础开发环境我建议至少包含requests2.22.0 netifaces0.10.9 pytest4.6.11注意这里用的是 Python 2.7 下能兼容的版本号没有写成最新版。如果你不想纠结版本也可以只写包名让 pip 自动解析但 Python 2.7 环境下某些新版本会装不上到时候再根据错误信息回退版本就行。另外很多 NAO 开发者会用到 OpenCV 做视觉处理但 OpenCV 在 Python 2.7 下的安装比较麻烦一般是opencv-python4.2.0.32这类版本我建议先把基础环境跑通之后再按需增加不要一开始就引入重依赖否则环境配置失败时很难区分是哪一步出了问题。6.3 补充一个实用的动作控制脚本除了语音动作控制是 NAO 开发里最常被问到的功能。我贴一个简单的动作控制示例它让 NAO 抬起右手并向前走一小步# -*- coding: utf-8 -*- import time from naoqi import ALProxy ROBOT_IP 192.168.1.100 ROBOT_PORT 9559 # 运动模块 motion ALProxy(ALMotion, ROBOT_IP, ROBOT_PORT) # 让机器人进入“唤醒”状态电机上电 motion.wakeUp() time.sleep(1.0) # 右手抬起 motion.angleInterpolation( RShoulderPitch, 0.5, # 目标角度单位弧度约 28 度 1.0, # 运动持续时间秒 True # 是否等待运动完成 ) # 向前走 20 厘米 motion.move(0.2, 0.0, 0.0)wakeUp和rest是两个很容易被忽略但非常重要的调用。机器人默认处于低功耗待机模式电机没有上电直接调用动作指令不会有反应。每次跑动作脚本前先wakeUp结束后建议调用motion.rest()让机器人回到待机状态否则电机一直保持力矩输出非常耗电。角度换算方面NAOqi 的关节角度单位是弧度不是度。如果你习惯用度数可以先写个简单的转换函数import math def deg_to_rad(x): return x * math.pi / 180.0这样就不用记每个关节的角度范围了。7. 开发环境配置完成后可以做什么环境配置只是第一步真正有意思的是跑通之后的扩展。我把几个值得尝试的方向列出来每个方向都有官方对应的模块你在 SDK 文档里搜索对应模块名就能找到详细 API对话交互ALDialog模块让 NAO 能听懂简单的关键词并做出回应视觉识别ALVideoDevice模块获取摄像头画面配合 OpenCV 做人脸检测或颜色追踪自主导航ALNavigation模块需要机器人配备激光或视觉导航能力V6 主要是视觉导航动画与情感化表达ALAnimationPlayer模块内置了大量预设动画比如鼓掌、思考、挥手传感器数据采集ALTouch、ALSonar、ALMemory组合使用可以做触碰交互和避障以视觉识别为例下面是一段获取摄像头图像的简单代码框架# -*- coding: utf-8 -*- from naoqi import ALProxy ROBOT_IP 192.168.1.100 ROBOT_PORT 9559 video ALProxy(ALVideoDevice, ROBOT_IP, ROBOT_PORT) # 订阅摄像头分辨率 640x480颜色格式 RGB name_id video.subscribeCamera( python_client, 0, # 摄像头索引0 为顶部摄像头 2, # 分辨率 640x480 11, # 颜色格式 RGB 15 # 帧率 ) print(Subscribed with id:, name_id)这段代码跑通后配合video.getImageRemote(name_id)就可以拿到图像数据转成 OpenCV 格式处理。我这里没有贴完整的取图代码因为那部分涉及PIL或numpy的转换容易分散初学者注意力。你先把订阅走通再去官网翻getImageRemote的示例代码就好理解了。8. 最后聊几点实操心得从零起步给 NAO V6 配开发环境我踩过最大的坑不是技术本身而是“先入为主”。很多教程写的是 V4/V5 的老经验下载链接也五花八门照搬之后各种报错。所以我总结了一句话先确认版本三件套固件、SDK、Choregraphe再动其他配置。版本对不上其他全部白搭。另外如果你是在实验室配环境建议把config.ini、requirements.txt和这篇文档一起提交到 Git 仓库里。这样同一个实验室的同学克隆下来只需要改 IP 和密码就能跑不用每个人重复踩一遍网络的坑。我在协助几个高校实验室做同样配置时就是这样把配置模板固化下来的后续新同学上手基本半小时内能跑通第一个语音脚本。最后再分享一个小技巧NAO V6 的系统盘空间不大SDK 开发时尽量把日志和录制的视频存到电脑端不要长期放在机器人上。使用ALLogger模块把日志输出到远程能显著减少机器人端的存储压力也能让日志集中管理。这些经验不是官方文档里直接写的但实际用下来非常有用。配置环境这件事说到底就是“网络、版本、依赖”三个关键词的排列组合。把这三块理顺了NAO 开发的大门就算真正打开了。