OmniSocketGo/scripts/boot/README.md

机器人 B 端开机自启说明

这个目录是给机器人端做开机自启用的。

你看到这里多了不少脚本和 systemd 单元，不是为了让你手工一条条执行，而是为了把开机流程拆开管理：

1. 固定启动顺序
2. 某一步失败时可单独重试
3. 所有动作统一写到一个本地日志文件
4. 后面如果要把“固定延时 30 秒”换成“等待机器人原有自检完成”，只改最前面的闸门即可

所以平时真正需要人工执行的，通常只有这两步：

sudo bash scripts/boot/install-systemd.sh
sudo systemctl start blitz-robot.target

以后机器人重启时，就不需要你再手工执行这些脚本了。

启动顺序

当前开机链路如下：

1. blitz-boot-gate.service
2. blitz-5g-dial.service
3. blitz-time-sync.service
4. blitz-ros-receiver.service
5. blitz-b-side-omnid.service

对应业务顺序就是：

1. 先固定等待 30 秒，给机器人原有自检/自启程序让路
2. 运行 5G 自动拨号
3. 运行时钟同步
4. 启动 start-ros-receiver.sh
5. 启动 start-b-side-omnid.sh

日志文件

所有关键操作都会统一写到这个本地文件：

/var/log/blitz-robot/startup.log

每一行日志格式如下：

timestamp | step | action | result | details | exit_code

日志里会记录：

• 做了什么
• 实际执行了什么命令
• 前置检查是否通过
• 成功还是失败
• 失败原因
• 退出码
• 是否发生了重试

这些文件分别是干什么的

• robot-boot.env：开机自启默认配置
• robot-boot.env.local：本机覆盖配置，建议把你自己的配置写这里
• common.sh：公共环境加载和统一日志函数
• boot-gate.sh：启动闸门，当前逻辑是固定等待 30 秒
• 5g-dial.sh：等待 5G 串口出现，执行 rndis_dial.py，删除 5G 默认路由并补齐目标主机路由，然后检查路由是否真的起来
• time-sync.sh：把 chrony 指向白名单服务器 IP 和端口，并执行一次同步
• start-ros-receiver-service.sh：开机版 ROS receiver 启动包装
• wait-for-unix-socket.sh：等待 ROS receiver 建好本地 unix socket
• start-b-side-omnid-service.sh：开机版 b_side_omnid 启动包装
• install-systemd.sh：把 systemd 单元安装到 /etc/systemd/system
• systemd/*.service.in、systemd/*.target.in：systemd 模板文件

前置条件

你前面说过，除了时钟同步以外，其他程序环境都应该已经配好了。按这个前提，这里只强调必须确认的前置条件。

1. 机器人侧必须已有的条件

默认认为下面这些已经具备：

• 系统是 Ubuntu，且使用 systemd
• OmniSocketGo 仓库已经放在机器人上
• scripts/dev/start-ros-receiver.sh 原本就能正常启动
• scripts/dev/start-b-side-omnid.sh 原本就能正常启动
• bin/b_side_omnid 已经提前编译好
• 5G 拨号脚本存在：/home/nvidia/5g-test/5G/rndis_dial.py
• 5G 串口设备是：/dev/ttyUSB7

注意：

• 开机模式下不会自动编译 b_side_omnid
• 如果 bin/b_side_omnid 不存在，服务会直接报错并写日志

2. 时钟同步需要的前置安装

时钟同步这一步依赖 chrony。

如果机器人侧没有安装，请先安装：

sudo apt update
sudo apt install -y chrony

安装后建议确认：

systemctl status chrony
chronyc tracking

3. 云服务器侧需要的前置条件

因为你的 5G 是白名单网络，所以时钟同步不能依赖公网域名或默认 NTP 池，必须只用你的白名单云服务器 IP。

云服务器侧需要满足：

• 服务器上运行 chronyd
• 安全组 / 防火墙放通你实际使用的 UDP 端口
• 机器人能访问这台服务器的 IP

如果云服务器还没有安装 chrony，可以参考：

sudo apt update
sudo apt install -y chrony
sudo systemctl enable chrony
sudo systemctl restart chrony

如果你不能使用标准的 123/udp，完全可以改成你自己的端口，例如 10910/udp。

例如云服务器 /etc/chrony/chrony.conf 里改成监听 10910：：

port 10910
allow 0/0

然后重启：

sudo systemctl restart chrony

机器人端则在 robot-boot.env.local 里配置：

BLITZ_TIME_SERVER_IP="你的云服务器IP"
BLITZ_TIME_SERVER_PORT="10910"

这样 time-sync.sh 会自动生成：

server 你的云服务器IP port 10910 iburst

注意：这里必须是你自己可控的 chronyd 服务端。公网标准 NTP 服务通常只监听 123/udp，不能要求它们改到 10910。

需要改哪些配置

不要直接改 robot-boot.env，更推荐新建：

scripts/boot/robot-boot.env.local

常见要改的是这些：

BLITZ_BOOT_DELAY_SEC="30"
BLITZ_LOG_FILE="/var/log/blitz-robot/startup.log"

BLITZ_5G_DIAL_DIR="/home/nvidia/5g-test/5G"
BLITZ_5G_SERIAL_PORT="/dev/ttyUSB7"
BLITZ_5G_GATEWAY="192.168.225.1"
BLITZ_5G_REMOVE_DEFAULT_ROUTE="1"
BLITZ_5G_ROUTE_TARGETS="106.55.173.235"

BLITZ_TIME_SERVER_IP="你的白名单云服务器IP"
BLITZ_TIME_SERVER_PORT="10910"

BLITZ_ROS_USER="nvidia"

如果 BLITZ_TIME_SERVER_IP 留空，脚本会自动回退到 ROBOT_SIDE_OMNISOCKET_SERVER_ADDR 的 IP 部分。

当 BLITZ_5G_REMOVE_DEFAULT_ROUTE="1" 时，脚本会在 5G 拨号完成后删除该接口上的默认路由，避免整机默认出口切到 5G。此时 BLITZ_TIME_SERVER_IP 和 BLITZ_5G_ROUTE_TARGETS 中的目标 IP 会显式走 5G，其它流量继续走有线或 Wi-Fi 的默认路由。

如何安装和使用

下面假设你当前目录就在 OmniSocketGo 仓库根目录。

第一步：准备本机配置

建议先创建：

cp scripts/boot/robot-boot.env scripts/boot/robot-boot.env.local

然后编辑：

vim scripts/boot/robot-boot.env.local

至少确认这几个值是对的：

• BLITZ_5G_DIAL_DIR
• BLITZ_5G_SERIAL_PORT
• BLITZ_TIME_SERVER_IP
• BLITZ_TIME_SERVER_PORT
• BLITZ_ROS_USER

第二步：安装 systemd 单元

执行：

sudo bash scripts/boot/install-systemd.sh

这个安装脚本会做这些事情：

1. 创建日志目录和日志文件
2. 渲染 systemd 模板
3. 把 unit 文件复制到 /etc/systemd/system
4. 执行 systemctl daemon-reload
5. 执行 systemctl enable blitz-robot.target

第三步：立刻启动一次

执行：

sudo systemctl start blitz-robot.target

第四步：以后重启自动生效

因为安装脚本已经做了 enable，所以后续机器人重启时会自动拉起，不需要你再手工执行。

如果想手工确认，也可以执行：

sudo systemctl enable blitz-robot.target

如何查看是否正常

看总日志文件

最直接：

tail -f /var/log/blitz-robot/startup.log

看各个服务状态

systemctl status blitz-robot.target
systemctl status blitz-boot-gate.service
systemctl status blitz-5g-dial.service
systemctl status blitz-time-sync.service
systemctl status blitz-ros-receiver.service
systemctl status blitz-b-side-omnid.service

看 journal

journalctl -u blitz-robot.target -u blitz-boot-gate.service -u blitz-5g-dial.service \
  -u blitz-time-sync.service -u blitz-ros-receiver.service \
  -u blitz-b-side-omnid.service -f

当前时钟同步会做什么

time-sync.sh 当前逻辑是：

1. 读取 BLITZ_TIME_SERVER_IP
2. 读取 BLITZ_TIME_SERVER_PORT
3. 修改 /etc/chrony/chrony.conf
4. 注释掉原有的 pool 和 server 项
5. 保留一个备份文件：/etc/chrony/chrony.conf.blitz-bak
6. 写入：

/etc/chrony/sources.d/blitz-robot.sources

7. 生成类似下面这一行：

server 你的云服务器IP port 10910 iburst

8. 重启 chrony
9. 执行 chronyc burst
10. 执行 chronyc waitsync

注意：

• 如果同步超时，会记日志为 soft_fail
• 但不会阻塞后面的 ROS 和 b_side_omnid 启动

常见问题

1. 为什么会突然多出这么多脚本？

因为把开机流程拆成了多个稳定的小步骤：

• 更容易排查哪一步失败
• 更容易让 systemd 自动重启
• 更容易记录完整日志
• 后续更容易替换“30 秒延时”为真正的机器人 ready 条件

你平时不需要手工逐个执行这些脚本。

2. 我是不是要手工跑 5g-dial.sh、time-sync.sh、start-ros-receiver-service.sh？

正常情况下不用。

你只需要：

sudo bash scripts/boot/install-systemd.sh
sudo systemctl start blitz-robot.target

3. 如果时钟同步失败怎么办？

先看：

tail -f /var/log/blitz-robot/startup.log
systemctl status blitz-time-sync.service
chronyc sources -v
chronyc tracking

优先检查：

• BLITZ_TIME_SERVER_IP 是否填对
• BLITZ_TIME_SERVER_PORT 是否填对
• 云服务器是否真的跑了 chronyd
• 云服务器防火墙 / 安全组是否放通你配置的 UDP 端口，例如 10910
• 5G 白名单是否确实允许访问这个服务器 IP

4. 如果 ROS receiver 没起来怎么办？

先看：

systemctl status blitz-ros-receiver.service
tail -f /var/log/blitz-robot/startup.log

再检查：

• /opt/ros/${ROS_DISTRO}/setup.bash 是否存在
• ${ROS_CONTROL_PY_DIR}/install/setup.bash 是否存在
• ROBOT_RECEIVER_LOCAL_SOCKET_PATH 对应的 socket 是否出现

5. 如果 b_side_omnid 没起来怎么办？

先看：

systemctl status blitz-b-side-omnid.service
tail -f /var/log/blitz-robot/startup.log

再检查：

• bin/b_side_omnid 是否已经提前编译好
• 摄像头设备是否存在
• robot-remote.env / robot-boot.env.local 里的地址配置是否正确