图形化编程与 AI 编程 · XGO-Ranger

8.1 认识编程功能

Ranger 的「图像化编程」提供 XGO-Blockly 网页编辑器。可以拖动积木编排机器人动作、屏幕显示和 AI 交互，也可以使用「AI写代码」生成并编辑 Python 程序。

基本流程：设备进入编程页面 → 电脑打开编辑器 → 搭建积木或编写代码 → 运行调试 → 保存程序。

编程方式	适合的用途
Blockly 图形化编程	将积木连接在「开始」块中，组合顺序、条件和循环，控制 Ranger 或处理识别结果。
AI写代码	用文字描述需求，获得 Python 代码，再检查、修改和运行。
展示代码	在积木编辑器中查看生成的 Python 代码和执行日志，学习积木与代码之间的对应关系。

8.2 进入编程界面

将电脑与 Ranger 连接到同一个局域网。尚未联网时，先完成无线网络配置。
在 Ranger 主界面用 A / B 键选择「图像化编程」卡片，按 D 键进入。设备屏幕显示「图形编程」和访问地址。
在电脑浏览器中输入屏幕上的 IP 地址和端口 8000。例如本次设备为 http://192.168.31.208:8000/，实际使用时请替换为自己的设备地址。
编辑和运行期间，保持 Ranger 的编程应用开启。

设备界面

图形编程入口

中间显示网页访问地址，下方显示编程软件版本。

D 键打开「程序列表」，C 键退出编程应用。电脑连接时，优先使用屏幕显示的 IP 地址与端口。

8.3 认识编辑器

左侧是积木分类，中间是工作区，顶部是文件和运行工具栏。本次 Ranger 在左上角显示固件 RA-0.0.3，编程软件版本为 v1.0.6.10；版本号以自己的设备为准。

网页编辑器

Ranger 的 XGO-Blockly 编辑器，包含顶部工具栏、分类和开始积木

Blockly 工作区

从左侧选择积木，拖到黄色「开始」块内并连接起来。

右下角可居中工作区、缩放视图或删除积木。

顶部按钮	用途
新建 / 打开 / 保存	新建工程、打开本地文件、选择保存到电脑或 Ranger。新建前先保存当前工作。
截图	导出积木工作区图片，便于记录和分享。
运行 / 停止	在 Ranger 上执行当前程序；运行中可停止执行。
恢复	让机器人恢复初始状态。
状态	打开机器人状态面板。
展示代码 / 隐藏代码	展开或收起 Python 代码与执行日志区域。
AI写代码 / Blockly	切换 AI 代码编辑与积木编辑。切换前请保存当前工程。
工具	在新页面打开 SSH 终端、色域编辑、摄像头标定和手柄映射。
API Key	配置 AI 功能所需的服务密钥。
EN	切换编辑器语言。

8.4 按功能选择积木

Ranger 机器人积木

连接 Ranger 后，「机器人」分类显示 XGO-RA 专用积木。运动模式可选择轮足模式或小车模式。

Ranger 积木界面

机器人分类

提供前后移动、旋转、身高、横滚、俯仰、模式切换及预设动作等积木。

向下滚动还可找到 LED、自稳定、电池和姿态数据读取。

积木组	可编排的功能
恢复与移动	恢复初始状态，设置前后移动速度、旋转速度；带「持续…秒」的积木可填写运行时间。
姿态调节	设置身高、横滚角和俯仰角，按积木显示的范围填写数值。
模式与动作	切换轮足 / 小车模式，选择预设动作，开启或关闭表演模式。
灯光与自稳定	设置 LED 的 RGB 颜色，开启或关闭机器人姿态自稳定。自稳定仅在轮足模式下生效。
读取数据	获取电池电量、固件版本、姿态角度和 IMU 数据，再连接判断、显示或打印积木使用。

其他分类

分类	内容
编程基础	逻辑、循环、变量、函数。
数据处理	数学、文本、列表、JSON 数据、类型转换。
系统工具	打印信息、等待、日期时间、随机数等。
交互与AI	屏幕、媒体、按键、遥控器、AI视觉、智能体、豆包大模型、语音对话。
高级	需要进一步编写自定义逻辑时使用，结合「展示代码」检查生成结果。

从一个简单程序开始

选择「系统工具」，将 print 积木连接到「开始」块中，把文本改为 Hello Ranger。
接上 time.sleep 积木，等待时间设为 1 秒，再接一个 print 积木，文本设为 完成。
点击「展示代码」查看 Python 代码，再点击「运行」，在执行日志中观察两次输出。

熟悉连接方式后，再加入 Ranger 运动积木。编排移动动作时，明确设置速度、持续时间和结束后的停止或恢复操作。

8.5 运行、停止与文件管理

运行与恢复

在网页点击「运行」后，程序由 Ranger 执行。使用执行日志查看输出和报错；需要中断时点击「停止」。程序结束后，可按需要点击「恢复」，让机器人回到初始状态。

两种保存位置

点击顶部「保存」，填写文件名后选择保存位置。本地积木工程与设备端程序用途不同，建议分别保存。

保存窗口

保存文件「保存到树莓派」写入当前 Ranger；「保存到本地」下载到正在使用的电脑。

当前编辑方式	保存到本地	保存到树莓派
Blockly	.json 积木工程，之后在 Blockly 中点击「打开」可继续编辑积木。	将积木生成的 Python 程序保存到 Ranger，供设备端运行。
AI写代码	.py Python 文件；此模式的「打开」支持 .py 和 .txt 文件。	将代码编辑区的 Python 程序保存到 Ranger。

设备端程序目录为 /opt/luwu-os/xgoBlocklyProjects。需要继续拖动积木编辑时，请保留本地的 .json 工程。

在设备屏幕上运行已保存的程序

完成「保存到树莓派」后，在 Ranger 的「图形编程」入口按 D 键进入「程序列表」。列表显示已保存的 Python 程序，文件名以自己的工程为准。

按键	程序列表中的操作
A 键	向上选择程序。
B 键	向下选择程序。
D 键	运行选中的程序；程序运行中按 D 键可停止。
C 键	返回图形编程入口。

8.6 使用 AI 编程

配置 API Key

点击顶部「API Key」。当前界面提供两组配置：通义千问用于智能体、AI写代码和语音对话；豆包大模型用于对应的豆包功能。按需配置所使用的服务，并点击「保存配置」。

配置窗口

分别配置服务密钥

可从窗口中的「获取API Key」入口前往对应服务平台。

图中密钥栏保持空白。分享截图、工程或代码前，请检查并隐藏 API Key。

首次点击「AI写代码」而未配置通义千问密钥时，会出现「需要配置API Key」提示，点击「去配置」完成配置后再进入。

用文字需求生成 Python 代码

保存当前积木工程，点击顶部「AI写代码」。
在右侧下方的输入框中描述需求，说明机器人型号为 XGO-Ranger / XGO-RA，并写清运动模式、动作顺序、速度和持续时间。
选择可用的模型，点击输入区的发送按钮。根据 AI 的回复检查并整理左侧 Python 代码。
确认代码内容后点击「运行」，在执行日志中查看结果；需要调整时继续描述修改要求或直接编辑代码。
完成后点击「保存」，按需要保存到电脑或 Ranger。点击顶部「Blockly」可返回积木编辑。

AI 代码编辑界面

代码、对话和日志

左侧编辑 Python，右侧查看对话；右下方输入需求并选择模型。

下方执行日志用于查看输出与报错。

入门需求示例：“为 XGO-Ranger 编写 Python 程序，先打印 Hello Ranger，等待 1 秒，再打印完成。请添加中文注释。”熟悉生成、运行和保存流程后，再尝试运动控制。

在积木程序中加入 AI

「交互与AI」中还可以把 AI 能力直接接入积木程序：

分类	主要能力	使用要点
智能体	配置模型、系统提示词、任务内容、长期记忆和工具集；还有千问图片识别、语音合成与缓存语音播放。	将任务内容改成 Ranger 的需求，选择设备支持的动作。
豆包大模型	文字与图片等输入、模型参数、工具调用和图片识别。	先配置豆包 API Key，按实际需求选择输入方式和模型。
语音对话	单次语音对话、连续语音对话，可配置提示词、音色、模型和工具调用。	连续对话还可设置最大轮数及退出关键词；开启机器人控制工具后，对话可以触发动作。

若只想直接使用机器人的语音聊天与角色配置，可阅读AI 对话。

8.7 使用视觉积木

展开「交互与AI」→「AI视觉」，选择识别积木，再根据输出结果连接判断、屏幕显示或 Ranger 动作积木。

AI 视觉积木

识别与数据处理

提供手势、物体、人脸、二维码、AprilTag、颜色和线条等识别入口。

识别结果需要结合程序逻辑，才能控制后续动作。

积木组	界面提供的功能
人物与物体	手势识别、物体识别（YOLO）、人脸检测、情绪识别、年龄性别识别、骨骼识别。
标记与形状	二维码识别、AprilTag 码识别与位姿检测、圆形识别。
颜色与线条	颜色识别、色块识别、线识别；色块识别可填写目标位置、色域范围和最小区域点等参数。
辅助功能	镜像显示、语音合成文本和定时语音识别。

需要直接体验 Ranger 的人脸跟随、手势等示例时，见视觉功能。其中人脸跟随和手势识别示例仅在轮足模式下有动作反馈。

8.8 工具箱

点击顶部「工具」会打开新的工具页面，按需要切换以下功能：

工具入口	用途
SSH 终端	查看设备端程序文件与终端。当前程序目录为 `/opt/luwu-os/xgoBlocklyProjects`。
色域编辑	调试颜色识别所需的色域参数，配合色块识别积木使用。
摄像头标定	进入摄像头标定工具。
手柄映射	查看和配置手柄输入映射。

8.9 调试与常见问题

遇到的情况	检查方法
电脑打不开编辑器	确认电脑与 Ranger 在同一局域网，设备仍处于编程应用中；按设备当前 IP 访问，保留端口 8000。
积木与 Ranger 不对应	检查左上角固件标识及「机器人」分类是否显示 XGO-RA。确认连接的是自己的 Ranger，再刷新编辑器。
程序没有按预期执行	检查积木是否连接到「开始」中，点击「展示代码」查看代码和执行日志，再检查参数与执行顺序。
设备程序列表找不到工程	确认选择了「保存到树莓派」且保存成功，再返回编程入口重新进入「程序列表」。仅下载本地 .json 不会把程序写入设备。
AI写代码提示配置密钥	在当前浏览器的「API Key」窗口配置通义千问服务并保存，再点击「AI写代码」。
AI 请求失败	检查网络、对应服务的 API Key 和所选模型是否可用，再根据返回信息调整。

8.10 转入 Python 开发

熟悉积木与生成代码后，可以继续查看 Ranger 的 Python 开发环境、运动控制接口和应用开发，编写更完整的程序。