nodectl

nodectl 是一个面向机器人业务的 进程编排与生命周期控制平面（Control Plane）。 它通过 配置 + 规范 的方式，将 camera / rosbag / SLAM / pipeline 等业务进程 纳入确定性、可远程控制的生命周期管理，并与 systemd 协作（不替代）。

定位：systemd 是系统级守护者；nodectl 是机器人业务级编排器。 边界：nodectl 只对 “进程是否存在 ⇔ RUNNING” 负责，且只管理 它自己 fork 出来的子进程 PID；不保证业务正确性。

---

功能

• 确定性生命周期（进程级）：fork() + exec() 启动模块脚本，追踪 child PID，支持 START/STOP，用 waitpid() 做崩溃/退出检测。
• 配置驱动模块化：YAML 声明模块；支持 enable/disable；按 /opt/robot/os_type 做板型过滤。
• 远程控制：通过 DDS service topic（默认 /NODECTL_CMD）接收命令；通过 DDS status topic（默认 /NODECTL_STATUS/<module>）发布模块状态。
• 生产部署模型：作为长期运行的 systemd 服务存在；systemd 管 nodectl，nodectl 管业务模块。

---

架构

---

责任边界

维度	systemd	nodectl	模块脚本
系统启动/拉起策略	✅	❌	❌
业务进程启动/停止	❌	✅（按 PID）	❌
PID 权威	❌	✅（仅它 fork 出来的 child PID）	❌
业务正确性（ROS topic、算法健康）	❌	❌	✅
环境准备（source ROS2/workspace）	❌	❌	✅

明确不做（Non-goals）：

• nodectl 不扫 /proc，不猜 进程名，不解析 脚本内容。

---

nodectl vs systemd

维度	systemd	nodectl
作用层级	操作系统级	机器人业务级
是否感知业务	否	是（模块、板型过滤）
ROS2 友好度	低（unit 里拼环境）	高（脚本里 source 环境）
动态控制	弱	强（DDS 命令）
用户接口	unit 文件	CLI + DDS

结论：nodectl 不替代 systemd，而是作为 systemd 托管的长期运行服务存在。

---

快速开始（本地编译运行）

编译

mkdir -p build && cd build
cmake ..
make -j"$(nproc)"

运行（指定配置）

./build/nodectl --config ./config/nodectl.yaml

说明：

• 如果配置文件不存在，nodectl 会回退到内置默认配置，并依然会读取 /opt/robot/os_type 做模块过滤。
• 配置中的脚本路径使用生产路径（例如 /opt/robot/share/nodectl/scripts/...）。
• 注意：nodectl 不要求模块脚本具备 daemon 能力，脚本 必须 exec 成长期进程。

---

生产部署模型（systemd 托管）

nodectl 安装路径规范：

/opt/robot/share/nodectl/
├── bin/nodectl
├── conf/nodectl.yaml
├── scripts/
└── systemd/nodectl.service

systemd unit（模板）：

[Service]
ExecStart=/opt/robot/share/nodectl/bin/nodectl --config /opt/robot/share/nodectl/conf/nodectl.yaml
Restart=always

---

文档

• 项目概览：1.项目概述.md
• 架构总览：2.架构总览.md
• 部署与运维手册：3.部署与运维手册.md
• 扩展接入手册（平台化交付）：4.扩展接入手册.md
• 脚本接入规范（平台与模块的契约）：5.脚本接入规范.md
• 配置参考（nodectl.yaml）：6.配置参考.md
• FAQ：7.FAQ.md

建议阅读顺序：01 → 02 → 03 → 04 → 05 → 06 → 07

---

DDS 协议（以当前实现为准）

• 命令服务：topic 名来自配置（默认 /NODECTL_CMD），payload 为 int32 命令枚举。
• 状态发布：base topic 来自配置（默认 /NODECTL_STATUS），按模块发布到 /NODECTL_STATUS/<module>。

完整命令映射与错误码见：2.架构总览.md。