故障排除

这份文档整理了 SDK 使用中常见的问题。排查时请先做“通用检查”，确认机器人处于可工作前提，再进入状态/版本确认和具体问题定位。

快速定位

如果你的问题暂未在下方列表中找到，可直接跳转到文末的仍未解决？获取进一步支持渠道。

建议先按这个统一顺序排查：

1. 通用检查项：先确认急停已松开，再确认当前工作模式是否进入 ABNORMAL，确保机器人处于正常工作模式（这是所有功能正常工作的前提）。
2. 系统与配置：在确认工作模式正常后，再查看机器人与SDK版本信息是否对应。
3. 具体故障现象：最后进入对应问题章节做专项排查。

如果你是“想确认机器状态或版本”，看这里：

• 如何查看当前工作模式
• 如何查看机器人系统版本
• 如何检查机器人系统版本与 SDK 兼容性
• 机器人紧急开关（急停按钮）说明
• 机器人机载算力单元介绍（HPU + XCU）
• 如何进入 HPU 与 XCU
• 如何查看机器 SN 号
• 如何检查关节是否正常

如果你是“机器人不动/不响应”，再看这里：

• 发送控制指令无响应
• 机器人上运行 SDK 程序可用，但有线连接不行
• 机器人关节无法运动
• 机器人进入异常模式，重启服务
• 机器人进入异常模式：定位服务异常
• 机器人底盘无法移动
• 末端执行器控制失败
• 机器人扬声器无声音

如果你是“系统配置相关”，看这里：

• 如何启用末端实时控制指令
• 关节限位在哪里配置
• 启用/禁用某个系统服务
• 重启后 embosa IP 配置被改回去

如果你是“相机相关问题”，看这里：

• 如何修改相机分辨率
• 如何查看相机帧率
• 如何查看相机内外参和标定信息

如果你是“其他问题”，看这里：

• SDK log 在哪里
• 如何开启 core 文件并调试
• 在 Robot 上执行 Python 找不到 module
• 执行 Python 示例报错：numpy 没有 typeDict
• SDK Docker 启动方式
• 如何使用感知服务（GBS 1.15.16+）

开始前先确认

• 日志和进程命令要在对应端执行，先判断问题属于哪一类服务：
  • HPU：定位、导航、规划、感知等服务（例如 localization、navigation、mps、perception）。
  • XCU：运动控制相关服务（例如 singorix、末端控制、模式管理等）。
  • 快速判断方法：机器人“能连上但不动/动作异常”优先查 XCU；“能动但地图、路径、避障、感知结果异常”优先查 HPU。
• 路径、服务名、配置字段区分大小写。
• 如果是 PC 端远程部署，先确认网络和 IP 配置已正确生效。

通用检查项（建议先做）

1. 急停状态：先确认机器人背部红色急停按钮已松开/已弹出。
2. 工作模式：在 XCU 执行 /data/bin/sys_tool，确认当前模式不是 ABNORMAL。
3. 异常服务定位：若当前模式是 ABNORMAL，先查看 /userdata/log/mission_manager/mission_manager.INFO 并搜索 abnormal_service，恢复到正常模式后再继续后续排查。
4. 状态/版本确认：仅在模式正常后，再检查 SN、系统版本、当前模式详情等基础信息。
5. 服务状态：按问题类型检查 singorix、galbot_chassis_service 等关键服务是否在线。

控制与运动

发送控制指令无响应

先按上面的通用检查项走完，再继续看控制链路。

先看主日志：

tail -f /userdata/log/SingoriX/info/singorix_wbcs_main.INFO

再检查 singorix 进程：

ps -ef | grep singorix | grep -v grep

如果 singorix 在，但控制还是没响应，再看底盘相关进程：

ps -ef | grep chassis

若是 PC 端部署，重启后配置容易被改回去，这时要检查 HPU 和 XCU 上 /data/config/system.cfg 里的 enable_modify_embosa_cfg。它为 false 时，embosa_ip_config.json 才不会在重启流程里被覆盖。

机器人上运行 SDK 程序可用，但有线连接不行

问题现象：SDK 程序在机器人本机运行正常，但通过 PC 有线连接运行失败。
常见原因：embosa_ip 未正确配置，或配置被重置。

处理建议：

1. 先检查网络配置是否正确，重点核对 PC、XCU、HPU 的 IP 与 embosa_ip_config.json。
2. 配置参考文档：
   PC端部署 - Ubuntu / 2. 配置网络
3. 如果已经配置正确但再次检查发现被重置，按以下小节处理：
   重启后 embosa IP 配置被改回去

机器人关节无法运动

本问题适用于头部、腿部或手臂的某个关节无响应的情况。

先查看 singorix 日志确认具体错误类型：

tail -f /userdata/log/SingoriX/info/singorix_wbcs_main.INFO

可能原因一：关节超出运动范围限制

关节位置可能已达到或超出其机械限位。此问题在手臂关节上较为常见，可通过目视观察到关节姿态异常，同时 singorix 会输出相应报错信息。

关节超限处理

建议按以下顺序处理：

1. 先尝试按住示教按钮，直接拖动机械臂回到关节限位范围内。
2. 如果无法拖动，先观察是哪个关节超限；二、三关节位置有隐藏抱闸按钮，可按下述方法处理。
3. 拔下活塞，按下急停按钮，然后戳下隐藏抱闸按钮并拖动机械臂回到限位内。
4. 旋开急停按钮复位，观察关节是否恢复正常。

如果超限关节没有隐藏抱闸按钮，使用方法 2：

1. 通过 service_display 进入后台：连续点击机器人胸前屏幕右下角，直到出现后台登录窗口，输入密码 996996。
2. 登录后进入：左臂电机或右臂电机 -> 电机操作（见图示例）。
3. 在电机操作页面的第一个输入框输入对应关节序号（例如 4 号关节）。
4. 拍下急停按钮，再旋开急停按钮，等待 10s。
5. 依次点击：空闲模式 -> 扩限位 -> 清错 -> 清错 -> 清错 -> 清错 -> 上使能 -> 电流模式（每个按钮间隔至少 1s）。
6. 查看机械臂对应关节是否可转动；如果仍不行，重复步骤 4 和步骤 5。
7. 处理完成后，在 XCU 执行以下命令重启 launcher，退出该界面并恢复常规运行状态：

systemctl restart launcher

可能原因二：关节初始化失败

机器人启动过程中，关节未成功释放制动器（无抱闸释放声）。singorix 会输出初始化失败的错误信息。

以下截图为头部关节初始化失败的示例：

处理建议：重启机器人并留意启动时是否有抱闸释放声。

可能原因三：MCU 故障

微控制单元（MCU）可能出现错误或停止响应。检查以下目录下的最新日志文件，确认日志是否持续更新且无错误信息输出：

• /userdata/log/mp_core/
• /userdata/log/secure_core/

机器人进入异常模式：定位服务异常

问题现象：机器人进入 ABNORMAL，并提示定位服务异常。
常见场景：新机器人首次使用时较常见。

常见原因：未完成建图，导致定位服务无法正常运行。

处理建议：

1. 确认当前是否已完成建图。
2. 若未建图，先完成建图与定位流程。
3. 建图完成后，在 HPU 执行以下命令重启服务：

sudo systemctl restart launcher.service

4. 完成后再次查看工作模式，确认是否恢复为 WORKING_MODE。

参考建图文档：

• 建图流程
• 定位流程

机器人进入异常模式，重启服务

如果机器人进入异常模式，尝试重启所有服务进行恢复，可以重启 launcher。

• XCU 执行：

systemctl restart launcher

• HPU 执行：

sudo systemctl restart launcher

机器人底盘无法移动

底盘不动，先按通用检查项确认急停和工作模式，再看服务和电量。

检查底盘服务：

ps -ef | grep galbot_chassis_service | grep -v grep

再看 SOC：

tail -f /userdata/log/galbot_chassis_service/galbot_chassis_service.INFO | grep soc

SOC 低于 25% 时，底盘会停机保护，先充电再试。

末端执行器控制失败

先按通用检查项确认急停和工作模式，再做末端专项判断：急停按下再释放，看看末端有没有最基本的响应。如果完全没有动作，先按硬件故障方向查。

如果有响应但行为不对，再看配置是否一致。配置文件在：

/data/config/SingoriX/galbot_one_golf/real/robot_config.toml

1.16 及以后版本使用 overlay，配置路径改为：

/data/config/default/SingoriX/galbot_s1-v2.0/robot_config.toml

默认是左手夹爪、右手吸盘。请确认实物安装和配置一致（例如 right_suction_cup 与 right_gripper），修改后重启 launcher 生效：

systemctl restart launcher

机器人扬声器无声音/启用音频服务 galbot_vtn

在 Orin/HPU 上编辑：

/data/config/launcher.cfg

把对应 enable 从 false 改成 true，然后：

sudo systemctl restart launcher
systemctl status launcher

系统与配置

如何查看当前工作模式

可通过 XCU 上的 sys_tool 查询当前整机工作模式。

1. 登录 XCU：

ssh root@192.168.xxx.xx
# password: 12345678

2. 进入工具目录并启动：

cd /data/bin
./sys_tool

sys_tool 是 XCU 系统工具，用于查询基线版本、切换/查询整机模式。工具路径：/data/bin/sys_tool。

启动后会进入交互式命令行，常用命令：

• v：查询基线软件版本信息（含序列号、软硬件版本）。
• q：查询当前整机模式（用于判断是否处于正常工作模式）。

模式判断：

• 正常情况下应看到 mode_type: WORKING_MODE。
• 若不是 WORKING_MODE（例如进入 ABNORMAL），先按通用检查项第 3 步定位 abnormal_service，恢复后再继续其他排查。

示例（q 查询关键字段）：

current mode:
mode_type: WORKING_MODE
mode_switch_state {
  status: SUCCESS
}

如何查看机器人系统版本

推荐优先使用 SDK 命令快速查看：

galbot_sdk check-version

如果机器人使用非默认 IP 地址：

galbot_sdk check-version --robot-ip <机器人IP>

如果当前环境没有该命令，再在 XCU 或 HPU 上执行：

cat /data/config/system.cfg

看 CUR_VERSION 字段即可。

如何检查机器人系统版本与 SDK 兼容性

使用以下命令快速检查当前 SDK 与机器人系统版本（GBS）是否匹配：

galbot_sdk check-version

常用参数：

# 指定非默认机器人 IP 地址
galbot_sdk check-version --robot-ip <机器人IP>

# 查看完整兼容性对照
galbot_sdk check-version --list

# 离线手工校验
galbot_sdk check-version --sdk-version 1.8.0 --robot-version GBS_1.16.0

兼容性对照（参考 output/check_robot_compat.py）：

SDK 版本范围	对应机器人系统版本（GBS）
1.5.0 ~ 1.7.99	GBS_1.15.x
1.8.0 ~ 1.8.99	GBS_1.16.x

如果检查结果不匹配，优先升级机器人系统版本到 SDK 要求范围；只有在必须保持当前机器人版本时，再选择降级 SDK。

机器人紧急开关（急停按钮）说明

急停按钮位于机器人本体背部醒目位置，为红色蘑菇头按钮 遥控急停按钮位于遥控器中间，为红色按钮

使用方法：

1. 一旦发现设备异常或人身危险，立即按下急停按钮。
2. 急停触发后，机器人即刻终止全部运动；设备不断电，仅锁定运动与执行机构。
3. 急停按钮按下后会自锁，如果是按机器人背部急停，需要旋转释放，如果是按遥控器急停，需要再次点击按钮释放。
4. 释放后，需要在机器人屏幕上点击恢复，机器人就可以恢复运动和控制。

机器人机载算力单元介绍（HPU + XCU）

Galbot G1 的机载计算单元采用双计算单元协同设计，由 HPU（High-Performance Unit）和 XCU（X Computing Unit）共同组成。其中 HPU 主要负责视觉感知、AI 推理、运动规划、导航等高算力任务，XCU 主要负责底层电机控制、关节执行与实时控制任务。该设计遵循高可靠性、实时性与扩展性原则，是理解通信延迟、部署架构和故障排查的基础。

计算单元	全称	职责	典型任务
HPU	High-Performance Unit	高算力任务	视觉感知、AI 推理、运动规划、导航、SLAM
XCU	X Computing Unit	实时控制任务	底层电机控制、关节执行、实时控制

• 硬件配置：HPU 搭载 NVIDIA Jetson Orin 平台（64GB，275 TOPS），XCU 为实时控制侧处理器。
• 系统软件：运行定制化 Linux，集成实时内核补丁，保障运动控制的确定性执行。
• 架构注意：HPU 与 XCU 均为 ARM64 (aarch64) 架构，在这两个平台上运行的程序需使用 aarch64 工具链交叉编译。

为什么拆成两个计算单元？

• 实时性隔离：电机控制需要微秒级确定性响应，视觉推理可能一次性占用 GPU 几百毫秒；放在同一计算单元会互相抢占资源，导致关节卡顿甚至整机失控。
• 故障隔离：HPU 侧 AI 模型异常时，XCU 仍可维持底层控制与站立姿态，避免单点故障扩散为整机失效。
• 扩展性：后续升级算力时可优先替换 Orin 模块，XCU 的实时控制逻辑与固件保持稳定，降低硬件迭代成本。

如何进入 HPU 与 XCU

可通过以下方式获取登录 IP：

1. 在机器人 Network 界面查看当前无线 IP。
2. PC 与机器人有线直连时，使用固定 IP：
   • XCU：192.168.100.66
   • HPU（Orin）：192.168.100.88

登录方式与账号密码如下：

• 登录 HPU（Orin）：

ssh galbot@<Orin_IP>
# 密码：gb@2023

• 登录 XCU：

ssh root@<XCU_IP>
# 密码：12345678

建议先 ping 验证连通性，再执行 ssh 登录。

如何查看机器 SN 号

在 XCU 上执行：

/data/bin/sys_tool

按工具提示查看设备信息。

如何检查关节是否正常

登录 XCU 后进入关节诊断工具，输入 r 看状态。
No Errors 一般就说明关节正常。若提示急停或关节速度过快相关错误，先复位再测。

如何启用末端实时控制指令

在 XCU 上把：

/data/config/default/SingoriX/galbot_s1-v2.0/robot_config.toml

里的 using_wbc 改成 true，然后重启 launcher。

关节限位在哪里配置

IK、规划和控制用的是同一套关节限位，来源是 URDF：galbot_one_golf.urdf。
路径如下：

• XCU：/data/config/galbot_description/galbot_one_golf_description
• HPU：/data/galbot/config/galbot_description/galbot_one_golf_description

启用/禁用某个系统服务

根据目标服务运行在 HPU 还是 XCU，登录对应平台后编辑：

/userdata/user_config/mode_service_config_default.toml

注释或取消注释对应服务项后，在对应平台重启 launcher：

systemctl restart launcher

重启后 embosa IP 配置被改回去

在 XCU 和 HPU 上分别把 /data/config/system.cfg 里的 enable_modify_embosa_cfg 设为 false，然后分别重启 launcher。

相机与标定信息

如何修改相机分辨率

在 Orin 上改这几个文件：

• /data/galbot/config/right_arm_camera.cfg
• /data/galbot/config/left_arm_camera.cfg
• /data/galbot/config/front_head_camera.cfg

改完重启机器就会生效。多传感器同时开的时候，适当降分辨率会稳一些。

如何查看相机帧率

可以先看 /data/galbot/config/xxx.cfg 里的配置，再用 HPU 上 /data/galbot/bin/embosa_topic_tool 统计话题频率。

如何查看相机内外参和标定信息

XCU 上直接看文件：

cat /userdata/config/robot_config/eyehand_calib.toml
cat /userdata/config/robot_config/stereo_camera_intrinsic.toml

也可以直接用 SDK 接口读，内参和外参都能拿到。例如获取左臂相机外参：

transform = robot.get_transform(
    target_frame="base_link",
    source_frame="left_arm_camera_color_optical_frame",
)

或者：

transform = robot.get_sensor_extrinsic(sensor_id=SensorType.LEFT_ARM_CAMERA)

日志与调试

底层服务日志在哪里

底层服务按平台区分：

• HPU：定位、导航、规划、感知等服务。
• XCU：控制、底盘等服务。

对应日志都在本平台的 /userdata/log/<服务名>/ 下，例如：

• HPU：/userdata/log/localization_server/、/userdata/log/service_navigation_plan/、/userdata/log/service_motion_plan/、/userdata/log/Perception_Algorithm_Service/
• XCU：/userdata/log/SingoriX/、/userdata/log/galbot_chassis_service/、/userdata/log/service_display/、/userdata/log/mission_manager/

排查时先确认服务跑在哪个平台，再去对应平台查看对应服务目录。

SDK log 在哪里

PC 或 Robot 侧运行 SDK 后，日志默认在：

~/galbot_sdk_log/

如果在 PC 上看到 get info failed 或 PUBLISH FAIL，优先查两端的 embosa_ip_config.json。

如何开启 core 文件并调试

core 文件通常用来定位服务崩溃。开启 core、设置路径、重新登录 shell 之后，文件一般会落在：

/userdata/core

例如 mps 服务可以这样看：

gdb /data/galbot/bin/service_motion_plan [core_file]

进 gdb 后执行 bt -full。

在 Robot 上执行 Python 找不到 module

在 ~/.bashrc 里加一行：

export PYTHONPATH=/data/galbot/lib:$PYTHONPATH

重新登录后生效。

执行 Python 示例报错：numpy 没有 typeDict

一般是 scipy 版本太低，升级一下：

pip install --upgrade scipy

安装与环境

SDK Docker 启动方式

gunzip -c galbot_sdk_image_1.8.0.tar.gz | docker load
cd output/docker
./run.sh

如何使用感知服务（GBS 1.15.16+）

在 HPU 上修改：

/data/galbot/config/galbot_perception_moduleConfig.yaml

把 sensor_data_sync_max_diff_tolerance 改成 500000（纳秒），重启 launcher 后再跑 examples/g1/python/galbot_perception 下的示例验证。

仍未解决？

如果你的问题没有在本文档中列出，可以在 GitHub 提交 issue：
https://github.com/GalaxyGeneralRobotics/GalbotSDK/issues

提交时请标注你的 SDK/机器人版本和具体问题现象，我们会尽快协助恢复；也可以直接联系售后技术支持人员。