在机器人部署现场，拖着显示器、键盘和网线进行调试既不方便也不安全。本页将指导你为主控板开启独立的 WiFi 热点，并通过 SSH 与 screen 实现完全脱离有线束缚的远程调试。阅读完本页后，你将能够在办公室或实验室里，仅用笔记本电脑无线连接到机器人主控，完成代码部署、节点启停和日志查看。Sources: README_CN.md

网络架构与工作原理

本项目在 tools/create_ap 目录中集成了 create_ap 工具，它利用 Linux 的 hostapd 创建无线接入点（AP），并通过 dnsmasq 为接入设备分配 IP 地址。主控板上的无线网卡充当 AP，而有线网卡（eth0/enP3p49s0）可选择性地通过 NAT 共享外网。由于嵌入式主控通常只有单张 WiFi 网卡，开启 AP 模式后，该网卡将专注于广播热点，不再用于连接家用路由器；因此如果需要临时下载软件包，应依赖有线网口或临时关闭热点服务。Sources: create_ap_orangepi.conf, create_ap_sunrise.conf

下图展示了典型的远程调试网络拓扑：你的笔记本电脑无线接入名为 atom 的热点，主控板作为网关（默认 192.168.12.1），两者之间通过 WPA2 加密通信。在此拓扑下，你可以直接 SSH 登录主控，并借助 screen 管理后台运行的 ROS2 节点。

graph LR
    A[笔记本电脑<br/>SSH 客户端] -->|WiFi<br/>SSID: atom| B[主控板<br/>192.168.12.1]
    B -->|NAT| C[有线网络/外网<br/>可选]
    B -->|本地回环| D[screen 会话<br/>inference_session]
    B -->|本地回环| E[screen 会话<br/>joy_session]

Sources: create_ap.service

开启 WiFi 热点

部署热点分为四个步骤：安装 create_ap 可执行文件、部署 systemd 服务、复制对应主控板的配置文件、启用并启动服务。以下流程图给出了完整的操作路径，其中分支节点根据你的硬件型号（Orange Pi 5 Plus 或 RDK X5）选择不同的配置文件。

flowchart TD
    A[进入项目根目录] --> B[复制 create_ap 到 /usr/bin/ 并赋予执行权限]
    B --> C[复制 create_ap.service 到 /etc/systemd/system/]
    C --> D{主控板型号}
    D -->|Orange Pi 5 Plus| E[复制 create_ap_orangepi.conf 到 /etc/create_ap.conf]
    D -->|RDK X5| F[复制 create_ap_sunrise.conf 到 /etc/create_ap.conf]
    E --> G[执行 daemon-reload]
    F --> G
    G --> H[systemctl enable create_ap.service]
    H --> I[systemctl start create_ap.service]
    I --> J[笔记本电脑搜索 atom 热点并连接]

按照上述流程，依次执行以下命令。请注意，所有操作均在主控板的终端中完成，首次配置时你可能仍需要通过网线或显示器登录。

# 1. 安装 create_ap
sudo cp tools/create_ap/create_ap /usr/bin/
sudo chmod +x /usr/bin/create_ap

# 2. 部署 systemd 服务
sudo cp tools/create_ap/create_ap.service /etc/systemd/system/

# 3. 根据主控型号选择配置文件（二选一）
# Orange Pi 5 Plus:
sudo cp tools/create_ap/create_ap_orangepi.conf /etc/create_ap.conf
# RDK X5:
# sudo cp tools/create_ap/create_ap_sunrise.conf /etc/create_ap.conf

# 4. 启用开机自启并立即启动
sudo systemctl daemon-reload
sudo systemctl enable create_ap.service
sudo systemctl start create_ap.service

Sources: README_CN.md

两张默认配置文件的核心差异在于网卡接口命名。Orange Pi 5 Plus 使用 wlP2p33s0 作为无线接口、enP3p49s0 作为有线接口；而 RDK X5 使用更传统的 wlan0 与 eth0。其余参数如 SSID、密码、网关和信道均保持一致，方便你在多型号设备间切换时减少记忆负担。

Sources: create_ap_orangepi.conf, create_ap_sunrise.conf

如果你希望自定义热点名称或密码，只需在复制配置文件后，使用文本编辑器（如 nano 或 vim）修改 /etc/create_ap.conf 中的 SSID 和 PASSPHRASE 字段，然后执行 sudo systemctl restart create_ap.service 即可生效。Sources: README_CN.md

远程连接与节点调试

热点启动后，你的笔记本电脑即可像连接普通路由器一样连接 atom 热点。连接成功后，主控板的固定 IP 为 192.168.12.1，你可以直接使用 SSH 远程登录：

ssh orangepi@192.168.12.1   # Orange Pi 5 Plus 默认用户
# 或
ssh sunrise@192.168.12.1    # RDK X5 默认用户

登录后，你便拥有了与直接插入显示器完全等效的终端环境。项目的启动脚本 tools/start_robot.sh 会借助 screen 在后台创建独立的会话（inference_session 与 joy_session），这意味着即使 SSH 断开，ROS2 节点仍会持续运行。这种设计非常适合远程部署：你可以在本地笔记本上启动机器人，关闭电脑带去开会，回来后重新 SSH 连接并恢复查看日志。Sources: start_robot.sh

下图展示了远程调试时的典型交互流程：从 SSH 登录到启动机器人，再到通过 screen 切换查看不同节点输出。

sequenceDiagram
    participant U as 用户笔记本
    participant B as 主控板
    U->>B: ssh user@192.168.12.1
    B-->>U: 认证通过，进入 shell
    U->>B: ./tools/start_robot.sh
    B->>B: screen 创建 inference_session
    B->>B: screen 创建 joy_session
    B-->>U: 提示启动成功
    U->>B: screen -r inference_session
    B-->>U: 实时显示推理节点日志
    U->>B: Ctrl+A, D  detach
    B-->>U: 回到 shell
    U->>B: screen -r joy_session
    B-->>U: 实时显示手柄节点日志

Sources: README_CN.md

对于初学者来说，掌握以下几条 screen 命令即可覆盖 90% 的远程调试场景。建议将这些命令记录在你的备忘录中，因为在没有显示器的现场调试时，它们是你观察程序运行状态的唯一窗口。

Sources: start_robot.sh

如果你需要临时恢复主控板的 WiFi 客户端功能（例如连接实验室路由器下载依赖），可以通过以下命令停止热点服务。注意，执行此命令后你的笔记本会断开与 atom 的连接，因此需要提前通过有线或显示器登录主控。

sudo systemctl stop create_ap.service

待下载完成后，再执行 sudo systemctl start create_ap.service 即可重新开启热点。Sources: README_CN.md

常见问题排查

在首次配置无线热点和远程调试时，初学者容易遇到接口名错误、服务启动失败或 SSH 连接不通等问题。下表整理了典型现象与对应的排查思路，帮助你快速定位故障。

Sources: create_ap_orangepi.conf, create_ap_sunrise.conf

下一步

完成 WiFi 热点与远程调试配置后，你已经具备了无线操作机器人的基础环境。接下来，请确保机器人硬件已正确连接，并按以下顺序继续阅读：

• 如果你尚未对电机进行零点标定，请参考 电机零点标定 完成首次校准。
• 零点确认无误后，即可阅读 启动机器人与推理节点 了解如何通过远程终端启动整个软件栈。
• 如果你希望从代码层面理解启动脚本背后的设计，可后续阅读 启动脚本与 DDS 优化配置。