跳到主要内容

XenseConsole

XenseConsole 是运行在 Xense 设备上的本地 Web 控制台，集中提供软件更新、固件升级、设备诊断和网络维护能力。
三类更新Wheel、Console 和 MCU 固件
设备诊断DDS 探测、夹爪运动测试和任务日志
系统维护网卡配置和 Python 环境包查看

界面概览​

页面顶部包含：

  • XenseConsole 品牌与标题。
  • 语言切换：中文 / EN。
  • 全局状态标签。
  • 刷新按钮：同时刷新 Wheel、Console、MCU、网卡、DDS 等状态。
  • 页签：更新、信息。

更新页按任务拆成 Wheel、Console 和 MCU 三张功能卡片，每张卡片从上到下依次是上传区、文件信息、安装选项、进度状态和日志。

更新页​

更新页用于执行三类更新任务：Wheel 更新、Console 服务更新、MCU 固件更新。

Wheel 更新​

Wheel 更新：上传、安装和验证 Python 业务包

Wheel 更新用于上传、安装并验证 Python 业务包。

支持文件：*.whl

基本流程：

  1. 将 .whl 文件拖入上传区域，或点击区域选择文件。
  2. 点击「上传 Wheel」。
  3. 上传成功后检查表格中的已上传文件、包名、Wheel 版本、环境当前版本和存储路径。
  4. 按需调整安装选项。
  5. 点击「安装 Wheel」。
  6. 查看进度条、状态表格和 Wheel 日志。

安装选项说明：

选项默认值说明
安装后删除上传文件开启安装结束后删除上传目录里的 wheel 文件。
重启 xense 服务开启安装后停止并重新启动 xense.service。
重启后运动测试关闭安装并重启后执行 DDS 夹爪运动验证。
DDS 服务空留空时自动发现 gripper_* 服务；也可填写指定服务名。
测试序列75 -> 65 -> 75 mm运动测试的固定目标序列。
Wheel 安装后端行为

激活目标 Python 环境 → 执行 python -m pip install <wheel> --force-reinstall --no-deps → 按选项重启 xense.service → 按选项执行 DDS 运动验证。状态接口返回进度、退出码、消息、标准输出和错误输出。

注意事项：

  • 只接受 .whl 文件。
  • 如果 wheel 含 native 扩展，需要匹配目标机 Python 和架构。
  • 目标设备已知环境为 aarch64、Python 3.10、glibc 时，应准备 manylinux/aarch64 wheel，不应因为后端是 musl 静态二进制就使用 musllinux wheel。

Console 服务更新​

Console 更新：上传新版本并安全重启 Web 服务

Console 服务更新用于从网页上传新版 XenseConsole 二进制，并重启当前 Web 服务。

支持文件名：

XenseConsole
xense-console-backend-*

基本流程：

  1. 拖入或选择 Console 二进制。
  2. 点击「上传 Console」。
  3. 上传成功后查看已上传文件和存储路径。
  4. 按需保持「安装后删除上传文件」开启。
  5. 点击「安装并重启 Console」。
  6. 等待服务安装、健康检查和重启。

自更新保护机制：

  • 新二进制安装到 XENSE_CONSOLE_BIN_PATH，默认 /usr/local/bin/XenseConsole。
  • 旧版本保留备份，默认 /usr/local/bin/XenseConsole.bak。
  • 新服务重启后检查 XENSE_CONSOLE_HEALTH_URL，默认 http://127.0.0.1:8080/health。
  • 健康检查失败时尝试回滚备份并重启旧版。

注意事项：

  • 上传文件必须是 AArch64 ELF64 小端二进制。
  • 安装过程中当前页面可能短暂断连，这是服务重启的正常现象。
  • 如果地址或端口不变，稍等后刷新页面即可。

MCU 固件更新​

MCU 更新：通过串口和 YMODEM 协议升级固件

MCU 固件更新用于上传 .bin 固件，通过串口和 YMODEM 协议执行升级，并可选执行 DDS 运动闭环验证。

支持文件：*.bin

基本流程：

  1. 拖入或选择 .bin 固件。
  2. 点击「上传 .bin」。
  3. 上传成功后查看已上传文件、存储路径和串口。
  4. 按需开启「安装后运动验证」。
  5. 点击「安装 MCU 固件」。
  6. 查看进度、发送字节数、状态和 MCU 日志。

安装选项说明：

选项默认值说明
安装后删除上传文件开启安装结束后删除上传的 .bin 文件。
安装后运动验证关闭固件发送完成并恢复服务后，执行 DDS 运动验证。
DDS 服务空留空时自动发现 gripper_* 服务。
测试序列75 -> 65 -> 75 mm固定验证序列。
速度上限40运动测试速度上限。
力上限10运动测试力上限。
超时秒20单次运动等待超时时间。
误差 mm1位置反馈允许误差。

注意事项：

  • 更新期间不要断电。
  • 如果串口被其他服务占用，先确认 xense.service 是否能被正常停止。
  • 如果启用运动验证，DDS 服务和夹爪状态 topic 必须可用。

信息页​

信息页用于查看设备运行状态，并执行非升级类维护操作：DDS 设备探测、夹爪运动测试、网卡配置、Python 环境包列表。

DDS 设备探测​

DDS 探测：查看 EzROS/DDS 节点、话题和服务

DDS 设备探测用于扫描 EzROS/DDS 节点、话题和服务。

可配置项：

字段默认值说明
超时秒5扫描等待时间，前端限制 1 到 30 秒。
Domain ID0DDS Domain ID，前端限制 0 到 232。

结果表格包含：节点、类型、话题数、服务数。展开每一行可查看该节点的话题列表、类型名、服务列表和服务动作。

设备类型推断规则：

  • 节点名以 gripper_ 开头：类型为 gripper。
  • 节点名以 master_ 开头：类型为 master。
  • 其他节点：类型为 sensor。

夹爪运动测试​

运动测试：通过 DDS 验证夹爪运动和位置反馈

夹爪运动测试用于直接通过 DDS 驱动夹爪执行固定序列：75 mm -> 65 mm -> 75 mm。

可配置项：

字段默认值说明
Domain ID0DDS Domain ID。
DDS 服务空留空自动发现 gripper_*，也可手动填写服务名。
速度上限40发送给运动服务的速度上限。
力上限10发送给运动服务的力上限。
超时秒20等待目标位置的超时时间，前端限制 3 到 60 秒。
误差 mm1闭环确认允许误差。
闭环确认关闭开启后等待状态 topic 到达目标位置。

使用建议：

  • 先在 DDS 设备探测中确认有 gripper_* 设备。
  • 不确定服务名时保持 DDS 服务为空，让系统自动发现。
  • 开启闭环确认可以获得更可靠的验证结果，但依赖状态 topic 正常发布。

网卡配置​

网卡配置：查看并维护设备的 IPv4 地址

网卡配置用于查看并持久化维护 eth0 的 IPv4 地址。

页面会展示：网卡名称（固定管理 eth0）、MAC 地址、网卡状态、IPv4 地址列表、默认网关、DNS、MTU、IPv6 地址。

可修改项：

  • IPv4 地址列表。
  • 新增 IPv4/CIDR，例如 192.168.99.3/24。
  • 网关，例如 192.168.99.1。

应用配置时后端会写入 /etc/systemd/network/eth0.network，执行 networkctl reload 和 networkctl reconfigure eth0，立即刷新运行时 IPv4 地址，并按需替换默认路由。

修改 IP 的安全事项
  • 修改设备 IP 时必须先新增新 IP，再删除旧 IP。
  • 新增 IP 前应确认该 IP 所在网段在当前维护网络中可达（维护电脑或上级网关能访问该网段）。
  • 新 IP 应使用正确的 CIDR 前缀（如 192.168.110.134/24），并确认网关与该网段匹配。
  • 新增 IP 后，先从维护电脑验证新地址可访问 XenseConsole，再删除旧地址。
  • 至少需要保留一个 IPv4 地址。
  • 只管理 eth0，其他网卡不会出现在前端配置列表中。
  • 如果删除当前正在访问的 IP，网页连接会断开，需要使用保留或新配置的 IP 重新访问。
  • 当前服务通常以 root 运行，因此不依赖普通用户免密 sudo。

Python 环境包​

环境包：查看目标 Python 环境中的包名和版本

Python 环境包面板展示目标 Python 环境中已安装的发行包列表。表格字段：包名、版本。点击刷新按钮可以重新读取环境包信息；Wheel 上传成功后，系统也会尝试刷新对应包的环境当前版本。

状态、进度和日志​

三类更新任务都有统一的状态概念：

状态含义
空闲 / idle当前没有任务运行。
安装中 / installing后端正在执行更新任务。
成功 / success任务完成且退出状态成功。
失败 / failed任务失败，消息和日志中会显示原因。

进度条用于展示后端任务进度。日志区把后端输出整理成带时间、模块和级别的格式，例如：

[2026-06-08 12:00:00.000] [wheel/python] running pip install ...

如果任务失败，优先查看：

  1. 状态表格中的「消息」。
  2. 对应更新模块的日志。
  3. 后端服务日志。

后端日志可通过接口读取尾部内容：GET /api/logs/tail?max_bytes=65536。

英文界面​

页面支持中文和英文，语言设置保存在浏览器本地存储键 xense-console-locale。切换到英文后，功能布局保持一致。

英文信息页
英文更新页

常见问题​

现象可能原因与处理
scp 提示无权限或目录不存在确认 REMOTE_DIR 存在且当前账号可写，可先执行 mkdir -p
启动提示 Permission denied忘记 chmod +x，或文件平台不匹配（如把 Windows 可执行文件传到 ARM 设备）
启动后进程立即消失先将日志重定向到文件，检查缺少的依赖库或配置错误
程序已运行但连接不上检查进程是否真的监听端口，以及设备防火墙（ufw status / firewall-cmd --list-all）
Wheel 安装失败确认 .whl 与目标机 Python 版本和架构匹配（aarch64 / Python 3.10 / glibc 用 manylinux wheel）
Console 更新后页面连不上服务重启属正常现象，稍等后刷新；仍失败可查看 /usr/local/bin/XenseConsole.bak 备份与健康检查日志
修改 IP 后网页断开使用了正在访问的 IP 或网关不匹配；用保留或新配置的 IP 重新访问
运动测试不通过先确认 DDS 探测中有 gripper_* 设备，再检查状态 topic 与 DDS 服务名