具深部署工具箱 · 用户使用手册
版本 v2.0.3 | 最后更新：2026 年 6 月 | 适用平台：Windows 10 / 11、macOS
本手册系统说明具深部署工具箱各功能模块的用途、操作流程与注意事项，供设备部署与维护人员参考。
一、产品概述
具深部署工具箱是面向具深舞蹈系统的桌面端远程部署与管理工具。软件通过 SSH 协议连接目标设备，集中提供设备信息读取、文件部署、配置管理、网络配置、日志采集及软件更新等功能，实现目标设备的远程维护，无需在设备本地进行命令行操作。
功能模块
运行环境
| 项目 | 要求 |
|---|
| 操作系统 | Windows 10 / 11 或 macOS |
| 网络 | 本机与目标设备处于同一网络（网线直连或同一 WiFi） |
| 目标设备 | 已开机且为具深舞蹈系统支持的机型 |
连接方式
| 方式 | 连接方法 | 适用场景 |
|---|
| 网线直连（推荐） | 通过网线将本机与目标设备直连 | 首次配置、现场调试，连接最稳定 |
| 无线（WiFi） | 本机与目标设备接入同一 WiFi | 设备已完成 WiFi 配置后的日常使用 |
注意：网线直连需预先设置静态 IP
采用网线直连时，需将本机网卡 IP 设置为 192.168.123.xxx 网段，否则无法建立连接。目标设备网口默认 IP 为 192.168.123.164。设置方法见第二章。
二、使用前准备
本章说明建立连接前的网络准备工作。设备连接失败的多数情况由网络配置不当导致，请按顺序完成。
2.1 准备清单
- 确认目标设备已开机。
- 准备网线一根（首次部署建议采用网线直连）。
- 确认设备登录凭据（默认：用户名
unitree，密码 123）。
- 确认设备 IP 地址（网线直连默认
192.168.123.164）。
2.2 方式 A：网线直连（推荐）
网线直连时设备 IP 固定为 192.168.123.164。为实现同网段通信，需将本机网卡 IP 设置为 192.168.123.xxx（xxx 取 1～253 内任意值，例如 100，但不可为 164，以免与设备地址冲突）。
Windows 10 / 11 设置静态 IP（通过控制面板）
- 用网线连接本机与目标设备。
- 按
Win + R 打开运行窗口，输入 ncpa.cpl 回车，打开「网络连接」（控制面板）。
- 右键当前使用的「以太网」连接，选择「属性」。
- 在列表中双击「Internet 协议版本 4 (TCP/IPv4)」。
- 选择「使用下面的 IP 地址」，填写：
IP 地址：192.168.123.100
子网掩码：255.255.255.0
默认网关：留空
- 点击「确定」保存。
macOS 设置静态 IP
- 用网线连接本机与目标设备（如需，使用网口转接器）。
- 打开「系统设置」→「网络」→ 选择「以太网（USB LAN / 雷雳网桥）」。
- 点击「详细信息…」→ 进入「TCP/IP」标签页。
- 将「配置 IPv4」改为「手动」。
- 填写：
IP 地址：192.168.123.100
子网掩码：255.255.255.0
路由器：留空
- 点击「好」→「应用」。
说明：网段要求
IP 地址前三段（如 192.168.123）标识网段，设备间需处于同一网段方可通信。目标设备位于 192.168.123.164，故本机也需处于 192.168.123 网段；最后一段不可与目标设备重复。
2.3 方式 B：无线（WiFi）
- 目标设备需已完成 WiFi 配置（首次配置通常通过网线直连后使用「网络配置」功能完成）。
- 确认本机与目标设备接入同一 WiFi。
- 使用目标设备的 WiFi IP 建立连接。
2.4 连通性测试
完成本机网络配置后，建议使用系统 ping 命令验证连通性。
Windows
- 按
Win 键，输入 cmd，打开「命令提示符」。
- 执行
ping 192.168.123.164。
- 显示「来自 192.168.123.164 的回复」表示连通；显示「请求超时」表示不可达。
macOS
- 打开「终端」（启动台 → 其他 → 终端）。
- 执行
ping 192.168.123.164。
- 显示
64 bytes from 192.168.123.164 表示连通；按 Control + C 停止。
警告：ping 不通
网线方式：通常为本机静态 IP 设置有误，请按 2.2 重新检查。无线方式：确认两设备确属同一 WiFi；部分公共或企业 WiFi 会隔离设备，需更换网络或改用网线。
三、主界面说明
启动应用后，界面由以下区域构成：
IP用户名密码端口
连接设备
检查更新
主内容区（随左侧导航切换）
顶部显示操作结果提示（成功 / 错误）
📋 操作日志（可展开 / 收起，记录各操作的执行结果）
| 区域 | 功能 |
|---|
| 左侧导航栏 | 切换 5 个功能模块：设备信息、文件部署、配置管理、网络配置、日志获取。底部提供语言切换与版本号显示。 |
| 顶部连接栏 | 填写 IP / 用户名 / 密码 / 端口，点击「连接设备」建立连接。所有功能均需在已连接状态下使用。 |
| 主内容区 | 根据左侧导航显示对应功能页面，操作结果以顶部提示条形式反馈（绿色表示成功，红色表示错误）。 |
| 操作日志 | 记录各操作的详细执行过程（含时间与级别）。默认收起，点击「操作日志」展开，含未读计数，可清空。 |
操作顺序
先在顶部连接栏建立连接，再通过左侧导航进入功能模块执行操作。所有功能模块均以「已连接」为可用前提。
四、连接设备
连接为使用各项功能的前置条件，通过顶部连接栏完成。
4.1 填写连接信息
| 字段 | 说明 | 默认值 |
|---|
| IP | 目标设备 IP 地址 | 192.168.123.164 |
| 用户名 | 设备登录账号 | unitree |
| 密码 | 设备登录密码 | 123 |
| 端口 | SSH 端口，通常无需修改 | 22 |
- 在顶部连接栏确认或修改 IP、用户名、密码、端口。
- 点击 连接设备。
- 查看右侧状态提示的变化。
4.2 连接状态说明
| 状态 | 含义 | 处理方式 |
|---|
| ○ 未连接 | 初始状态，功能不可用。 | 填写信息后连接。 |
| 连接中… | 正在建立连接。 | 等待完成；如需中止可点击 取消。 |
| ● 已连接: 192.168.123.164 | 连接成功，自动刷新文件列表与服务状态。 | 可使用各功能模块。 |
| 红色错误提示 | 连接失败，并显示原因。 | 参照常见问题 Q1排查。 |
4.3 断开连接
连接状态下，输入框锁定，「连接设备」按钮切换为 断开连接。需更换设备或修改连接信息时，先点击「断开连接」解除锁定。
注意：常见连接失败原因
- 本机静态 IP 设置有误（网线方式，见 2.2）；
- IP 地址填写错误；
- 用户名或密码不正确；
- 本机与目标设备不在同一网络。
五、设备信息
读取目标设备的唯一标识 ID。设备 ID 具有唯一性。
- 确认已显示「已连接」状态。
- 点击左侧「设备信息」。
- 点击 获取设备 ID。
- 读取完成后，设备 ID 显示于下方结果区。
提示：自动复制
获取成功后，设备 ID 自动复制至系统剪贴板（旁侧短暂显示「已复制」），可直接粘贴使用。
六、文件部署
文件部署为核心功能模块，采用左右布局：左侧为远程文件列表，右侧为操作区域。点击左侧「文件部署」进入。
6.1 远程文件列表
显示目标设备 /home/unitree/ 目录下的文件与文件夹。连接成功后自动刷新一次。
| 列 | 说明 |
|---|
| 文件名 | 文件夹以 📁 标识，文件以 📄 标识。部署相关文件（deploy_、models_、Atom- 开头）以荧光绿高亮。 |
| 大小 | 文件大小（B / KB / MB）。 |
| 修改时间 | 最后修改时间。 |
点击 刷新 可手动重新加载列表。
6.2 一键更新
将依赖包与模型包上传至目标设备并自动解压，为程序与内容更新的标准操作。
包类型说明
| 类型 | 文件名前缀 | 内容 |
|---|
| 依赖包（程序） | deploy_ | 程序本体 |
| 模型包（内容） | models_ | 舞蹈动作与音乐文件 |
上述文件可从 DanceBot-X 网站获取或由具深团队提供，格式为 .tar.gz。
说明：压缩包无需手动解压
获取到的依赖包与模型包保持 .tar.gz 原文件即可，无需手动解压。在「一键更新」中选择压缩包，软件会自动完成上传与解压。
注意：依赖包与模型包均需部署
设备正常运行需同时具备依赖包与模型包，二者缺一不可，仅部署依赖包无法工作。其中模型包为每台设备专属，包含该设备专用的舞蹈动作内容，不同设备之间不通用，部署时须使用对应设备的模型包。
操作步骤
- 在「依赖包」行点击 浏览，选择
deploy_ 开头的压缩包（可选）。
- 在「模型包」行点击 浏览，选择
models_ 开头的压缩包（可选）。
- 至少选择一个包后，一键更新 按钮启用。
- 点击 一键更新，软件自动执行上传与解压，进度条实时显示。
- 完成后提示「一键更新完成」，并弹窗引导重启服务。
说明：更新后重启服务
一键更新完成文件传输与解压后，软件会自动弹窗引导重启服务，按提示操作即可使新程序生效。
说明：清除已选文件
已选文件右侧显示 ✕，点击可清除该选择并重新选取。文件名须严格以 deploy_ 或 models_ 开头，否则将提示错误。
6.3 文件操作
解压文件
- 在「解压」下拉框中选择目标设备上的
.tar.gz / .tgz 压缩包。
- 点击 解压，确认后执行。
删除文件
- 在「删除」下拉框中选择待删除的文件或
deploy/ 目录。
- 点击 删除。
- 在二次确认弹窗中确认。
警告：删除不可恢复
删除操作无法撤销。删除 deploy/ 目录将清空整个程序，操作前请确认，并确保本地保有可重新部署的安装包。
6.4 文件上传
将本地单个文件上传至目标设备主目录（/home/unitree/）。
- 点击 选择文件，选取本地文件（建议
.tar.gz 压缩包）。
- 点击 上传，进度条显示进度。
- 上传完成提示「上传成功」，列表自动刷新。
说明：与一键更新的区别
「文件上传」仅传输文件、不执行解压，适用于任意文件；「一键更新」专为 deploy_ / models_ 包设计，传输后自动解压至对应目录。程序更新应优先使用「一键更新」。
6.5 服务管理
管理目标设备上的具深舞蹈系统服务（设备主程序，支持开机自启与后台运行）。连接后自动检测当前状态。
服务状态
| 状态 | 含义 |
|---|
| ● 运行中 | 服务正常运行。 |
| ◉ 启动中 | 服务正在启动。 |
| ○ 已停止 | 服务已安装但未运行。 |
| ✕ 运行失败 | 服务启动失败，需查阅日志排查。 |
| ○ 已停用 | 服务被手动停用。 |
操作按钮
| 按钮 | 作用 | 说明 |
|---|
| 启动服务 | 安装并启动 | 首次部署后使用。创建系统服务 → 启动 → 设置开机自启。前置条件：已完成依赖包与模型包的部署（两者缺一不可）。 |
| 重启服务 | 重启运行中的服务 | 更新文件或修改配置后使用，使改动生效。 |
| 删除服务 | 卸载服务 | 停止运行并移除服务。不可恢复。 |
| 刷新状态 | 重新检测 | 手动重新读取服务状态。 |
七、配置管理
管理目标设备配置，包含三个标签页：按键配置、串口配置、温度配置。点击左侧「配置管理」进入。
通用规则
三个标签页共用顶部操作按钮。修改任意标签页均需：先「读取配置」加载当前值 → 修改 → 「保存配置」写回设备。未读取前保存按钮为禁用状态。
7.1 读取 / 保存 / 备份 / 恢复
| 按钮 | 作用 | 使用时机 |
|---|
| 读取配置 | 从设备加载当前配置至界面 | 每次进入页面或设备配置被他人修改后 |
| 保存配置 | 将界面修改写回设备 | 确认修改并需生效时（前置：已读取） |
| 备份配置 | 将当前配置保存为带时间戳的 .bak 备份 | 修改前备份，便于回退 |
| 恢复配置 | 从备份文件还原配置 | 配置异常需回退至历史版本时 |
推荐工作流
读取配置 → 备份配置 → 修改 → 保存配置。若修改异常，使用「恢复配置」选择对应备份还原。保存后需重启服务方可生效。
7.2 按键配置
配置遥控器 / 手柄按键与设备动作的映射关系。表格包含三列：
| 列 | 说明 |
|---|
| 描述 | 动作名称。 |
| 触发按键 | 触发该动作的按键组合。 |
| 播放音乐 | 勾选后执行动作时同步播放对应音乐。 |
设置按键组合
- 定位目标动作行（灰显的「固定动作」为系统锁定，仅可查看，不可编辑）。
- 在「触发按键」下方点选按键，支持多选：
L1 L2 R1 R2 A B X Y UP DOWN LEFT RIGHT
- 选择完成后点击 + 添加，组合以绿色标签显示。
- 删除某组合时，点击对应标签上的 ✕。
- 按需勾选「播放音乐」。
- 修改完成后点击顶部 保存配置。
7.3 串口配置
注意：仅群控场景适用
串口配置服务于群控功能，需搭配具深与机时租提供的专用硬件。未使用群控功能时，请勿修改本项配置，保持默认即可。
包含三部分，各部分均设独立开关。使用时需先开启「全局开关」，再按需开启串口 1 或串口 2，各开关仅在开启状态下生效。
开关样式如下（左为关闭，右为开启）：
| 分组 | 可配置项 |
|---|
| 全局 | 总开关；设备 ID；重试次数；重试间隔（秒） |
| 串口 1（主） | 开关；端口（如 /dev/ttyUSB0）；波特率（如 115200） |
| 串口 2（备） | 开关；端口（如 /dev/ttyUSB1）；波特率（如 115200） |
修改后同样需点击顶部 保存配置 并重启服务生效。
7.4 温度配置
配置设备温度保护阈值。共 4 个参数（单位 °C）：
| 参数 | 默认值 | 触发后的设备行为 |
|---|
| 预警温度 | 80.0 | 仅记录日志 |
| 报警温度 | 110.0 | 语音提醒 |
| 临界温度 | 200.0 | 强制躺下保护 |
| 急剧上升阈值 | 15.0 | 10 秒内温度上升超过此值视为急剧上升并记录 |
警告：宇树 G1 机型温度限值
宇树 G1 机型温度达到 120°C 即进入危险范围，达到 130°C 时机器人将直接失去控制、软倒在地。当温度超过 120°C 时，请立即停止使用机器人，待其充分散热后再继续运行。
八、网络配置
为目标设备配置 WiFi 连接与静态 IP，便于后续无线访问。采用左右布局。点击左侧「网络配置」进入。
8.1 WiFi 扫描
- 点击 扫描 WiFi，设备搜索周边网络。
- 列表显示 WiFi 名称与信号强度（强 / 中 / 弱 + 百分比）。
- 点击目标 WiFi 所在行完成选中（高亮显示）。
8.2 配置静态 IP
- 「WiFi 名称」自动填入所选网络（不可手动输入）。
- 在「WiFi 密码」中输入对应 WiFi 密码。
- 在「IP 段」中输入数字，例如
211（设备最终 IP 为 192.168.x.211）。
- 点击 配置，软件自动执行：连接 WiFi → 设置静态 IP → 应用配置。
警告：配置完成后 IP 将变更
配置成功后，设备启用新的 WiFi IP。请务必记录所设 IP（尤其是「IP 段」数值），否则将无法再次连接。如遗忘，需通过网线直连（192.168.123.164）登录设备查询。
推荐流程
首次通过网线直连建立连接 → 在本页完成 WiFi 与静态 IP 配置 → 记录新 IP → 此后即可使用 WiFi IP 进行无线连接。
九、日志获取
将目标设备运行日志下载至本地，可用于运行异常排查，联系技术支持时建议一并提供。点击左侧「日志获取」进入。
- 点击 获取日志列表，加载设备上的日志文件。
- 列表显示文件名、大小、修改时间，每行含勾选框。
- 勾选待下载文件（支持点击表头勾选框全选）。
- 点击 下载选中 (N)。
- 在弹出的对话框中选择本地保存目录。
- 等待下载完成（含进度提示），提示成功。
说明：日志为空
若列表为空，表示设备尚未产生日志（通常因服务未运行）。请确保服务已启动并运行一段时间后重新获取。
十、软件更新
本章所指为具深部署工具箱软件自身的版本更新（非设备程序更新，后者见第六章）。
更新方式
- 顶部连接栏右侧设有 检查更新 按钮，支持手动触发。
- 软件每次启动时亦会自动检查更新。
- 检测到新版本时，弹出更新对话框，显示版本号与更新内容。
- 点击「立即更新」→ 自动下载（含进度）→ 下载完成后点击「重启安装」。
- 软件自动关闭、安装新版本并重新启动。
说明
- 「以后再说」不持久化跳过，下次启动仍会提醒。
- 检查更新需本机具备网络连接。
十一、常见问题
Q1：连接设备失败
- 网线方式：检查本机静态 IP 是否已设为
192.168.123.xxx（见第二章）。
- 使用
ping 设备IP 验证网络连通性（见 2.4）。
- 确认 IP、用户名（默认为
unitree）、密码（默认为 123）填写正确。
- 确认设备已开机、网线连接正常。
- 无线方式：确认本机与设备接入同一 WiFi，且使用设备的 WiFi IP。
Q2：一键更新后设备无响应
一键更新完成后，软件会自动弹窗引导重启服务，按提示操作即可。若状态为「运行失败」，请下载日志并联系技术团队排查。
Q3：修改配置后未生效
配置保存后需重启服务方可生效，请在服务管理中执行「重启服务」。
Q4：配置 WiFi 后无法连接
使用新设置的 IP 重新连接。如遗忘新 IP，可通过网线直连（192.168.123.164）重新查询，或外接显示器 / 串口。详见第八章。
Q5：误删文件
删除操作不可恢复，可通过「一键更新」重新上传最新的 deploy_ / models_ 包恢复。
Q6：文件上传失败
检查网络稳定性；确认设备磁盘空间充足；断开连接后重新连接再试。
Q7：配置修改异常需还原
在配置管理顶部点击 恢复配置，选择历史备份还原。建议修改前先执行备份。
Q8：检查更新无响应
检查更新需本机联网方可检测到新版本。
Q9：操作记录查看位置
主界面底部设有「操作日志」面板，点击可展开，记录各操作的时间与结果（普通 / 警告 / 错误三级颜色区分），支持「清空」。
Q10：服务状态显示「运行失败」
表示程序启动过程出错。请下载运行日志（第九章）查看具体报错，常见原因包括：配置文件格式错误、依赖包未完整传输、模型缺失。修正后执行「重启服务」。
十二、附录
默认连接信息（宇树 G1 机型）
| 项目 | 默认值 |
|---|
| 网线 IP 地址 | 192.168.123.164 |
| 用户名 | unitree |
| 密码 | 123 |
| SSH 端口 | 22 |
术语表
- IP 地址
- 设备在网络中的标识地址，例如
192.168.123.164。设备间需处于同一网段方可通信。
- 网段
- IP 地址前三段相同即为同一网段，如
192.168.123。本机与目标设备须处于同一网段。
- SSH
- 远程登录协议，本软件基于该协议连接并控制目标设备。
- 局域网（LAN）
- 同一路由器或同一 WiFi 下设备构成的内部网络。
- 静态 IP / 固定 IP
- 手动指定、不随时间变化的 IP 地址。设备建议采用静态 IP，避免重启后地址变更导致无法连接。
- 服务（service）
- 设备开机自动运行的后台程序。
- tar.gz
- 一种压缩包格式，部署包均采用此格式。
技术支持
如遇本手册未涵盖的问题，请联系具深技术支持，并尽量提供：设备 ID、操作步骤、操作日志截图及运行日志。
JuShen Deploy Toolbox · User Manual
Version v2.0.3 | Last Updated: June 2026 | Platforms: Windows 10/11, macOS
This manual documents the purpose, procedures, and notes for each module of the JuShen Deploy Toolbox, intended for personnel responsible for device deployment and maintenance.
1. Overview
The JuShen Deploy Toolbox is a desktop remote deployment and management tool for the JuShen dance system. It connects to target devices over SSH and provides device identification, file deployment, configuration management, network configuration, log collection, and software update — enabling remote maintenance without local command-line access on the device.
Modules
System Requirements
| Item | Requirement |
|---|
| Operating System | Windows 10/11 or macOS |
| Network | The local machine and target device on the same network (Ethernet cable or same WiFi) |
| Target Device | Powered on; a model supported by the JuShen dance system |
Connection Methods
| Method | How | Suitable for |
|---|
| Ethernet cable (recommended) | Connect the machine and device directly with a cable | First-time setup and on-site work; most stable |
| WiFi | Machine and device on the same WiFi | Daily use after WiFi is configured |
Note: Ethernet requires a static IP first
When using Ethernet, set the local adapter IP to the 192.168.123.xxx subnet, otherwise the connection cannot be established. The device's default Ethernet IP is 192.168.123.164. See Section 2.
2. Before You Start
This section covers network preparation prior to connecting. Most connection failures result from incorrect network configuration; complete these steps in order.
2.1 Checklist
- Confirm the device is powered on.
- Prepare an Ethernet cable (recommended for first-time deployment).
- Confirm the device credentials (default: user
unitree, password 123).
- Confirm the device IP (Ethernet default
192.168.123.164).
2.2 Method A: Ethernet Cable (recommended)
With Ethernet, the device IP is fixed at 192.168.123.164. To communicate on the same subnet, set the local adapter IP to 192.168.123.xxx (any value 1–253, e.g. 100, but not 164, to avoid conflicting with the device address).
Windows 10 / 11 (via Control Panel)
- Connect the machine and device with the cable.
- Press Win + R, type
ncpa.cpl, and press Enter to open Network Connections (Control Panel).
- Right-click the active Ethernet connection and select Properties.
- Double-click Internet Protocol Version 4 (TCP/IPv4) in the list.
- Select "Use the following IP address" and enter:
IP address: 192.168.123.100
Subnet mask: 255.255.255.0
Default gateway: leave empty
- Click OK to save.
macOS
- Connect the cable (use an adapter if needed).
- Open System Settings → Network → select Ethernet (USB LAN / Thunderbolt Bridge).
- Click Details… → TCP/IP tab.
- Set Configure IPv4 to Manually.
- Enter:
IP address: 192.168.123.100
Subnet mask: 255.255.255.0
Router: leave empty
- Click OK → Apply.
Note: Subnet requirement
The first three octets of an IP (e.g. 192.168.123) identify the subnet; devices must share a subnet to communicate. The device is at 192.168.123.164, so the local machine must also be in 192.168.123; the last octet must not duplicate the device's.
2.3 Method B: WiFi
- The device must already have WiFi configured (first configured via Ethernet + the Network feature).
- Confirm the machine and device are on the same WiFi.
- Connect using the device's WiFi IP.
2.4 Connectivity Test
After configuring the local machine's network, verify connectivity with the system ping command.
Windows
- Press Win, type
cmd, open Command Prompt.
- Run
ping 192.168.123.164.
- "Reply from 192.168.123.164" indicates reachable; "Request timed out" indicates unreachable.
macOS
- Open Terminal (Launchpad → Others → Terminal).
- Run
ping 192.168.123.164.
64 bytes from 192.168.123.164 indicates reachable; press Control+C to stop.
Warning: ping unreachable
Ethernet: usually an incorrect static IP on the local machine — recheck per 2.2. WiFi: confirm both devices are truly on the same WiFi; some public or corporate networks isolate devices — switch networks or use Ethernet.
3. Interface
The interface consists of the following areas:
IPUserPassPort
Connect
Check Update
Main area (switches with the left nav)
Top banners show operation results (success / error)
📋 Operation log (expand / collapse; records results of each action)
| Area | Function |
|---|
| Left navigation | Switch between 5 modules: Device Info, File Deploy, Configuration, Network, Log Fetch. Bottom: language switch and version. |
| Top connection bar | Enter IP / user / password / port and click Connect. All features require an active connection. |
| Main area | Displays the selected module; results are shown as top banners (green = success, red = error). |
| Operation log | Records detailed execution of each action (with timestamp and level). Collapsed by default; expandable; with unread count and clear. |
Order of operations
Establish a connection in the top bar first, then navigate to a module. All modules require the "Connected" state.
4. Connecting
A connection is a prerequisite for all features and is established via the top connection bar.
4.1 Enter connection info
| Field | Description | Default |
|---|
| IP | Device IP address | 192.168.123.164 |
| Username | Login account | unitree |
| Password | Login password | 123 |
| Port | SSH port, typically unchanged | 22 |
- Confirm or edit IP, username, password, and port in the top bar.
- Click Connect.
- Observe the status text on the right.
4.2 Connection states
| Status | Meaning | Action |
|---|
| ○ Disconnected | Initial state; features unavailable. | Enter info and connect. |
| Connecting… | Establishing connection. | Wait; click Cancel to abort. |
| ● Connected: 192.168.123.164 | Connected; file list and service status auto-refresh. | Modules are available. |
| Red error | Connection failed, with reason shown. | Refer to FAQ Q1. |
4.3 Disconnect
While connected, inputs are locked and Connect becomes Disconnect. Click it to unlock inputs before switching devices or changing info.
Note: Common connection failures
- Incorrect static IP on the local machine (Ethernet, see 2.2);
- Incorrect IP address;
- Incorrect username or password;
- Machine and device not on the same network.
5. Device Info
Reads the device's unique ID. The device ID is unique.
- Confirm the "Connected" state.
- Click Device Info in the left nav.
- Click Get Device ID.
- The ID appears in the result area below.
Tip: Auto-copy
On success, the ID is automatically copied to the clipboard (shows "Copied" briefly) and can be pasted directly.
6. File Deployment
The core module, using a left–right layout: remote files on the left, actions on the right. Click File Deploy in the left nav.
6.1 Remote Files
Lists files and folders in /home/unitree/. Auto-refreshed once on connect.
| Column | Description |
|---|
| Name | Folders shown with 📁, files with 📄. Deploy files (deploy_, models_, Atom-) are lime-highlighted. |
| Size | B / KB / MB. |
| Modified | Last modification time. |
Click Refresh to reload.
6.2 One-Click Update
Uploads the deploy package and/or models package to the device and extracts them automatically — the standard procedure for program and content updates.
Package types
| Type | Filename prefix | Contents |
|---|
| Deploy (program) | deploy_ | The program itself |
| Models (content) | models_ | Dance moves and music |
These files are available from DanceBot-X or the JuShen team, in .tar.gz format.
Note: No manual extraction needed
Keep the deploy and models packages as the original .tar.gz files — do not extract them manually. Select the archive in One-Click Update and the software handles upload and extraction automatically.
Note: Both deploy and models packages are required
The device requires both the deploy package and the models package to operate; neither can be omitted, and the device will not function with the deploy package alone. The models package is dedicated to each device and contains that device's dance content; it is not interchangeable between devices — use the models package matching the target device.
Procedure
- In the Deploy row, click Browse and select a
deploy_ archive (optional).
- In the Models row, click Browse and select a
models_ archive (optional).
- Select at least one package to enable One-Click Update.
- Click One-Click Update; upload and extraction run automatically with a live progress bar.
- "Done" appears, followed by a prompt to restart the service.
Note: Restart the service after updating
After One-Click Update completes the transfer and extraction, the software automatically prompts to restart the service; follow the prompt to apply the new program.
Note: Clearing a selection
A red ✕ appears next to a chosen file; click it to clear and reselect. Filenames must start exactly with deploy_ or models_, otherwise an error is shown.
6.3 File Operations
Extract
- Select a
.tar.gz / .tgz archive from the Extract dropdown.
- Click Extract and confirm.
Delete
- Select a file or the
deploy/ directory from the Delete dropdown.
- Click Delete.
- Confirm in the dialog.
Warning: Deletion is irreversible
Deletion cannot be undone. Deleting deploy/ clears the entire program. Confirm before proceeding and keep a backup package available.
6.4 File Upload
Uploads a single local file to the device home directory (/home/unitree/).
- Click Select File and choose a local file (
.tar.gz recommended).
- Click Upload; progress is shown.
- "Success" appears and the list auto-refreshes.
Note: Difference from One-Click Update
File Upload transfers without extracting and accepts any file; One-Click Update is purpose-built for deploy_/models_ and extracts to the correct locations. Use One-Click Update for program updates.
6.5 Service Management
Manages the JuShen dance system service on the target device (the device's main program, with auto-start on boot and background execution). Status is auto-checked on connect.
Service status
| Status | Meaning |
|---|
| ● Running | Service running normally. |
| ◉ Starting | Service is starting. |
| ○ Stopped | Installed but not running. |
| ✕ Failed | Failed to start; check logs. |
| ○ Disabled | Manually disabled. |
Buttons
| Button | Action | Notes |
|---|
| Start | Install & start | Used after first deployment. Creates the service → starts → enables on boot. Prerequisite: both the deploy and models packages have been deployed (both required). |
| Restart | Restart running service | Used after updating files or config to apply changes. |
| Remove | Uninstall | Stops and removes the service. Irreversible. |
| Refresh | Re-check | Manually re-read the status. |
7. Configuration
Manages the device configuration across three tabs: Key Config, Serial Config, Temperature. Click Configuration in the left nav.
General rule
All tabs share the top buttons. Editing any tab follows: Read Config → edit → Save Config. Save is disabled until a read has been performed.
7.1 Read / Save / Backup / Restore
| Button | Action | When to use |
|---|
| Read Config | Load current config from the device | On entering the page, or after someone else modified it |
| Save Config | Write edits back to the device | To apply changes (requires a prior read) |
| Backup | Save a timestamped .bak backup | Before making changes, for rollback |
| Restore | Restore from a backup file | When config is broken and needs rollback |
Recommended workflow
Read → Backup → Modify → Save. If something goes wrong, use Restore with the corresponding backup. Restart the service after saving for changes to take effect.
7.2 Key Config
Maps controller buttons to device actions. Table columns:
| Column | Description |
|---|
| Description | Action name. |
| Trigger Key | The button combination that triggers the action. |
| Play Music | Check to play music with the action. |
Setting a combination
- Locate the target action row (grayed "fixed actions" are locked and read-only).
- Click key buttons under Trigger Key; multiple selection is supported:
L1 L2 R1 R2 A B X Y UP DOWN LEFT RIGHT
- Click + to add; the combination appears as a lime chip.
- Click a chip's ✕ to remove it.
- Toggle Play Music as needed.
- Click Save Config at the top.
7.3 Serial Config
Note: Group-control scenarios only
Serial config serves group control and requires dedicated hardware from JuShen & JiShiZu. If group control is not in use, do not modify this configuration; leave defaults.
Three groups, each with its own toggle. Enable the Global toggle first, then enable Port 1 or Port 2 as needed; each toggle takes effect only when enabled.
Toggle appearance (left: off, right: on):
| Group | Settings |
|---|
| Global | Master toggle; Device ID; Retry count; Retry interval (s) |
| Port 1 (Primary) | Toggle; Port (/dev/ttyUSB0); Baud (115200) |
| Port 2 (Backup) | Toggle; Port (/dev/ttyUSB1); Baud (115200) |
After editing, click Save Config and restart the service.
7.4 Temperature
Configures the device's temperature protection thresholds. 4 parameters (°C):
| Parameter | Default | Device behavior when reached |
|---|
| Warning | 80.0 | Log only |
| Alert | 110.0 | Voice reminder |
| Critical | 200.0 | Forced lie-down protection |
| Spike threshold | 15.0 | A temperature rise exceeding this within 10s is treated as a spike and logged |
Warning: Unitree G1 temperature limits
For the Unitree G1, 120°C is already dangerous; at 130°C the robot will lose control and collapse. If the temperature exceeds 120°C, stop using the robot immediately and allow it to cool fully before resuming operation.
8. Network
Configures the device's WiFi connection and static IP for wireless access. Left–right layout. Click Network in the left nav.
8.1 WiFi scan
- Click Scan WiFi to search nearby networks.
- The list shows SSID and signal strength (Strong/Medium/Weak + %).
- Click the target WiFi row to select it (highlighted).
8.2 Configure static IP
- WiFi Name auto-fills from the selection (not manually editable).
- Enter the WiFi password.
- Enter the IP segment, e.g.
211 (final IP becomes 192.168.x.211).
- Click Configure; the tool connects WiFi → sets static IP → applies.
Warning: The IP changes after configuration
After success, the device uses the new WiFi IP. Record the configured IP (especially the IP segment value), otherwise reconnection is impossible. If forgotten, reconnect via Ethernet (192.168.123.164) or via a display/serial console.
Recommended workflow
First connect via Ethernet → configure WiFi and static IP here → record the new IP → subsequently connect wirelessly using the WiFi IP.
9. Log Fetch
Downloads device runtime logs to the local machine; useful for troubleshooting and recommended when contacting support. Click Log Fetch in the left nav.
- Click Get Log List to load files.
- The list shows name, size, and modified time, each with a checkbox.
- Check the files to download (header checkbox selects all).
- Click Download Selected (N).
- Select a local destination folder.
- Wait for completion (progress shown); success is reported.
Note: Empty logs
If the list is empty, the device has produced no logs (typically because the service has not run). Ensure the service is running for a while, then retry.
10. Software Update
This section refers to updates of the toolbox itself (not the device program; see Chapter 6).
Update method
- A Check Update button in the top bar supports manual triggering.
- The application also checks automatically on each launch.
- When a new version is found, a dialog shows the version and release notes.
- Click Update Now → automatic download (with progress) → Restart & Install when complete.
- The application closes, installs the new version, and restarts automatically.
Note
- "Later" is not persistent; the reminder appears again on next launch.
- Checking requires an internet connection.
11. FAQ
Q1: Connection fails
- Ethernet: verify the local static IP is set to
192.168.123.xxx (Section 2).
- Verify reachability with
ping <device IP> (2.4).
- Confirm IP, username (default
unitree), and password (default 123).
- Confirm the device is powered on and the cable is connected.
- WiFi: confirm both are on the same WiFi and that the device's WiFi IP is used.
Q2: No response after One-Click Update
After One-Click Update completes, the software automatically prompts to restart the service; follow the prompt. If the status is "Failed", fetch the logs and contact the technical team.
Q3: Configuration changes not taking effect
The service must be restarted after saving for changes to take effect. Use Restart in Service Management.
Q4: Cannot connect after WiFi setup
Reconnect with the newly configured IP. If forgotten, reconnect via Ethernet (192.168.123.164) or a display/serial console. See Chapter 8.
Q5: Accidentally deleted files
Deletion is irreversible. Re-upload the latest deploy_ / models_ packages via One-Click Update to restore.
Q6: File upload fails
Check network stability; confirm sufficient disk space on the device; disconnect and reconnect, then retry.
Q7: Broken configuration needs rollback
Use Restore in Configuration and select a previous backup. Back up before editing whenever possible.
Q8: Check Update does nothing
Checking requires an internet connection to detect new versions.
Q9: Where to view operation records
The Operation log panel at the bottom of the main window — click to expand. It records each action's time and result (normal/warning/error), with a Clear button.
Q10: Service shows "Failed"
The program errored during startup. Fetch the runtime logs (Chapter 9) to inspect the cause. Common causes: malformed config file, incomplete deploy package, missing models. Fix and then Restart.
12. Appendix
Default Connection Info (Unitree G1)
| Item | Default |
|---|
| Ethernet IP | 192.168.123.164 |
| Username | unitree |
| Password | 123 |
| SSH Port | 22 |
Glossary
- IP address
- A device's network address, e.g.
192.168.123.164. Devices must share a subnet to communicate.
- Subnet
- The first three octets of an IP, e.g.
192.168.123. The local machine and device must be in the same subnet.
- SSH
- A remote login protocol the toolbox uses to connect to and control the device.
- LAN
- A local network formed by devices on the same router or WiFi.
- Static IP
- A fixed, manually assigned IP that does not change. Recommended for devices to keep the address stable across reboots.
- Service
- A background program that runs automatically on boot.
- tar.gz
- A compressed archive format; deploy packages use it.
Technical Support
For issues not covered here, contact JuShen support and provide: the device ID, the steps taken, an operation-log screenshot, and the runtime logs.