Vicverse
Published on

水下机器人 Day1：先把工程地基打稳

Authors
  • avatar
    Name
    Vic Wu
    Twitter

水下机器人项目的第一天，目标不是马上做出一个会动的机器人。

Day1 真正要完成的事，是把工程地基打稳。

如果没有清楚的目录、日志、环境检查、版本管理和仿真工具链，后面做控制、视觉、建模和任务规划时，问题会混在一起。到那时很难判断，到底是代码错了、环境没装好、目录混乱，还是实验过程没有记录清楚。

所以第一天先做最基础、也最容易被低估的部分：

  • 建立工程仓库
  • 整理目录结构
  • 准备日志和文档
  • 验证 ROS2 与 Gazebo 环境
  • 接入 Git 和 GitHub
  • 写下后续协作规则

这篇文章是水下机器人专题的第一篇日志。

它记录的不是炫目的成果，而是一个长期项目开始时应该拥有的最小秩序。

项目从哪里开始

当前项目放在：

/home/civ/桌面/水下机器人研究/underwater-inspection-robot

外层 水下机器人研究/ 用来放学习资料、临时记录和探索内容。

内层 underwater-inspection-robot/ 才是真正的工程仓库。

这个区分很重要。

学习资料可以发散，工程仓库必须收束。一个长期项目如果从第一天就把资料、脚本、日志、源码和临时文件混在一起，后面每推进一步都会付出整理成本。

Day1 先把仓库边界划清楚。

第一版目录结构

项目现在保留了这几个核心目录：

underwater-inspection-robot/
├── assets/
├── control/
├── docs/
├── launch/
├── logs/
├── scripts/
├── simulation/
├── src/
└── vision/

它们不是为了看起来完整，而是为了让后续内容有稳定归宿。

assets/ 放图片、视频、模型和演示素材。

control/ 留给控制算法和控制说明。

docs/ 保存项目文档、任务记录、环境记录和工作流说明。

launch/ 放 ROS2 launch 文件。

logs/ 记录每日进展、运行输出和环境检查结果。

scripts/ 放辅助脚本，目前最重要的是环境检查脚本。

simulation/ 留给 Gazebo world、模型和仿真配置。

src/ 是后续 ROS2 package 的代码入口。

vision/ 用来承接视觉和感知模块。

第一版目录不追求复杂，但要足够明确。后续无论新增仿真模型、控制节点、视觉模块，还是实验记录，都不需要重新问“这个文件该放哪里”。

文档和日志先行

Day1 同时整理了几类文档：

  • README.md
  • docs/day1_第一层_任务总结.md
  • docs/day1_task_list.md
  • docs/environment_check.md
  • docs/codex_workflow.md
  • docs/github_setup.md
  • logs/daily/2026-05-28.md
  • logs/runtime/day1_environment_check.txt

这些文件的作用不同。

README.md 是入口，让以后回来时能快速知道项目是什么、怎么跑、现在在哪里。

docs/ 负责保存稳定文档，比如环境记录、任务总结、GitHub 状态和协作规则。

logs/ 负责保存过程。它不要求每句话都完美，但要留下当天做过什么、遇到什么问题、怎么解决的证据。

对这个项目来说，日志不是形式主义。

水下机器人会同时牵涉机械结构、推进方式、控制系统、传感器、视觉、仿真、通信和任务设计。任何一个环节没有记录，后面都可能变成重复踩坑。

Day1 的一个重要决定是：以后不仅写代码，也记录决策。

环境检查结果

环境检查脚本已经跑通。

当前通过项包括：

  • Git
  • Python
  • CMake
  • Colcon
  • ROS2
  • ros_gz_bridge
  • Gazebo gz 命令
  • ROS launch 参数加载
  • GitHub CLI

ROS2 和 Gazebo 相关命令需要先加载环境：

source /opt/ros/lyrical/setup.bash

环境检查脚本是：

./scripts/check_environment.sh

这个脚本的价值，是把“我的机器现在能不能继续开发”变成一个可以重复验证的问题。

只靠记忆不可靠。

工具链一旦变多，环境状态就必须能被检查、能被记录、能被复现。

Day1 遇到的问题

第一天并不是一条直线。

主要问题集中在环境和基础设施上：

  • 初始环境缺少 ROS2、Gazebo、CMake、Colcon 和 GitHub CLI
  • ROS 官方源下载速度慢
  • ROS 安装中出现 Python 包文件归属冲突
  • apt 和 dpkg 一度处于半安装状态
  • 默认 ROS launch 日志路径在当前执行环境中不可写
  • 普通 git push 受到网络代理和 TLS 问题影响

这些问题没有直接产生“机器人功能”，但它们决定项目能不能继续走下去。

最后的处理方式也被记录下来：

  • 使用清华 ROS2 镜像完成安装
  • 保留 ROS 源需要的 Python 模块并修复包冲突
  • 修复 apt 和 dpkg 状态
  • 将 ROS 日志路径指向项目内 logs/runtime/ros
  • 使用 GitHub API 完成远程仓库内容写入和验证

这些都属于工程地基的一部分。

解决一次，记录一次，后面就少一层不确定性。

Git 和远程仓库

本地 Git 仓库已经初始化，并有 Day1 提交记录。

远程仓库地址：

https://github.com/vicwu9709-code/underwater-inspection-robot

仓库目前是私有仓库，默认分支是 main。

Day1 的提交历史记录了项目从空结构到可继续开发的过程。

这件事本身也很重要。

一个长期工程不能只靠最终结果展示。它需要能回看每一步为什么发生、哪些文件在什么时候出现、哪些问题曾经被修复。

版本历史不是装饰，它是工程记忆。

为什么第一天不做复杂功能

水下机器人听起来很容易让人直接跳到酷的部分：

推进器、控制算法、摄像头识别、路径规划、三维仿真、自动巡检。

但如果第一天就冲进这些内容，反而容易把项目做散。

更稳的顺序是：

先让工程能记录。

再让环境能验证。

再让 ROS2 和 Gazebo 的基础链路跑通。

然后才进入模型、控制、视觉和任务。

Day1 的成果不是“已经做出机器人”，而是“项目现在有能力持续做下去”。

这比一个临时 demo 更重要。

Day2 要做什么

下一步不急着写复杂控制算法。

Day2 的重点应该是把 ROS2 和 Gazebo 的基础运行链路跑稳：

  1. 运行 ROS2 talker/listener 通信 Demo。
  2. 启动 Gazebo 空世界或官方示例世界。
  3. 验证 ROS2 与 Gazebo 的桥接通信。
  4. 创建第一版水下机器人仿真模型。
  5. 建立 topic 命名规范。
  6. 开始记录 Day2 日志。

如果 Day2 能把通信、仿真和桥接稳定跑起来，后面才有资格讨论更复杂的控制和感知。

Day1 的结论

Day1 第一层任务已经完成。

现在项目已经具备进入 Day2 的基础条件：

  • 工程目录清楚
  • 文档和日志开始建立
  • Git 和 GitHub 可用
  • ROS2、Gazebo、Colcon 和桥接工具已验证
  • 环境检查脚本可以重复运行

这不是一个完成品。

这是一个起点。

水下机器人专题后续会继续记录从工程基础、仿真链路、机器人模型、运动控制到视觉感知的推进过程。

第一天先把地基打稳。

后面才有东西可以真正长出来。

Discussion

评论

还可输入 1200 字

正在加载评论...