Skip to content

feat(chap1): 新增小海龟键盘遥控与 ROS 基础实验模块 - #1080

Merged
tianyutu981 merged 1 commit into
OpenHUTB:masterfrom
xinyangtang91:feat/turtlesim_teleop
Nov 13, 2026
Merged

tianyutu981 merged 1 commit into
OpenHUTB:masterfrom
xinyangtang91:feat/turtlesim_teleop

Conversation

@xinyangtang91

@xinyangtang91 xinyangtang91 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

修改目的与内容

第一章现有实验集中在“小海龟自动绘图”,缺少与本次 ROS 基础作业对应的“键盘遥控 + 常用命令 + 桥接源码阅读”环节。学生目前只能直接调用官方 turtle_teleop_key,没有自己编写话题发布节点的练习,也不方便在文档里串起环境验证、调试命令和桥接原理。

本 PR 新增第一章第 10 个实验模块 turtlesim_teleop:

  • src/chap1/turtlesim_teleop/:入口 main.py 读取方向键 / WASD,把按键映射为线速度、角速度后发布到 /turtle1/cmd_vel;支持空格停车、+/- 调速、q/Ctrl+C 退出并在退出前发布零速度。main.launch 一键启动 turtlesim + 遥控节点(用 xterm 承载键盘输入),也可 rosrun 前台运行;另含 package.xml、CMakeLists.txt(安装 main.py)和 README。
  • docs/chapter/chap1/turtlesim_teleop.md:环境验证、控制原理、运行步骤、常用 ROS 命令速查、CARLA-ROS 桥接源码结构阅读笔记、运行截图。
  • 首页 docs/index.md、mkdocs.yml 导航、docs/chapter/chap1/chap1.md 均加入口。
  • tests/test_turtlesim_teleop_local.py:不依赖 ROS 的桩测试,覆盖按键映射、Twist 字段和工程文件。

已知限制:作者本机为 Windows,未安装 ROS,main.py 的 ROS 端实际运行尚未验证;文中截图来自 ROS Noetic 虚拟机中官方 turtle_teleop_key 的运行结果,用于说明实验环境和键盘遥控效果,不是本模块 main.py 的运行截图。合并前需要一名有 ROS Noetic 环境的同学按 README 实际跑一遍。

测试环境与结果

  • 实际系统、ROS、Python、模拟器及关键依赖版本:
    • 文档构建机:Windows 10.0.26200,Python 3.12.14,mkdocs 1.6.1,pandoc 3.9(pypandoc-binary),pymdown-extensions 13.0
    • 截图环境:Ubuntu 20.04 虚拟机,ROS Noetic(rosversion 输出 1.16.0),turtlesim
    • 本机没有 ROS / WSL / Docker,未进行 ROS 端运行
  • 构建与运行命令(注明执行目录):
    • 在仓库根目录执行:python -m mkdocs build
    • 在仓库根目录执行:python -m mkdocs serve --dev-addr 127.0.0.1:8000 --livereload
    • 在仓库根目录执行:python tests/test_turtlesim_teleop_local.py
    • ROS 端(需 Ubuntu + ROS Noetic,本机未执行):cp -r src/chap1/turtlesim_teleop ~/catkin_ws/src/ && cd ~/catkin_ws && catkin_make && source devel/setup.bash && roslaunch turtlesim_teleop main.launch
  • 验证操作、结果及尚未验证的内容:
    • mkdocs build 通过(28.47 秒),新增页面无构建报错;
    • mkdocs serve --livereload 下新页面、导航入口和 turtle_teleop.png 均返回 HTTP 200;
    • 本地测试 25 项全部通过(按键映射 12 项、消息发布 2 项、工程文件 11 项);
    • 尚未验证:main.py 在 ROS 中的键盘输入与话题发布、main.launch 启动、turtlesim 实际运动、catkin_make 编译。

运行效果

小海龟键盘遥控运行截图

截图为 ROS Noetic 虚拟机中同时运行 roscore、turtlesim_node 和 turtle_teleop_key 的效果:左侧终端显示 Reading from keyboard 和方向键提示,右侧小海龟在按键控制下留下三角形轨迹,roscore 参数显示 /rosdistro: noetic、/rosversion: 1.16.0。本模块 main.py 的同类效果待在 ROS 环境复现后补充。

提交前检查

  • 已检查 Files changed 和冲突,无无关生成文件、重复内容或误删公共文件。(GitHub PR 页面 Files changed 共 11 个文件,与本地 git diff 一致;mergeable 为 true,无冲突;分支已 rebase 到最新 master ac75bdb。)
  • 源码与教程按模块分别放在 src、docs,文件使用英文下划线命名。
  • 模块提供 main.* 和 launch,依赖及安装路径正确,README 步骤已实际运行。(main.py、main.launch、package.xml、CMakeLists.txt 已提供,依赖与安装路径已检查;但 README 的 ROS 运行步骤未在本机执行,因为本机没有 ROS,待另一台机器验证。)
  • 新模块已添加首页和导航链接;已运行 mkdocs serve --livereload 检查相关页面。
  • 功能描述与验证证据一致;PNG 小于 3 MB,GIF 小于 5 MB。(截图 1415×905,451 KB;文档已注明截图为官方 turtle_teleop_key 的运行效果。)

大模型使用声明

  • 使用工具:DeepSeek 助手(DeepSeek Harness)。
  • 辅助范围:文档结构整理与文字润色、README 与本地测试初稿、构建和运行命令核对;运行截图、实验环境信息不是模型生成的。
  • 作者已逐项核对上述内容,并对提交内容的正确性负全部责任;ROS 端的复验项见“尚未验证”和未勾选的检查项。

@tianyutu981

Copy link
Copy Markdown
Contributor
  1. 【launch 未安装】CMakeLists.txt 只安装了 main.py,没有安装 main.launch。同级 chap1 包(如 turtle_hutb、turtle_text)都是把 launch 文件放进 launch/ 子目录并用 install(DIRECTORY launch ...) 安装。请同样把 main.launch 移到 launch/main.launch 并补安装规则,否则 catkin_make install / 发布场景下 roslaunch turtlesim_teleop main.launch 会找不到文件(当前"复制到 catkin_ws/src 后 rosrun/roslaunch"靠源码目录能跑通,但不算完整安装)。

第一章现有实验集中在自动绘图,缺少与课堂作业对应的键盘遥控、常用命令
练习和桥接源码阅读环节,学生只能直接调用官方 turtle_teleop_key,无法
练习自己编写话题发布节点。

- 新增 src/chap1/turtlesim_teleop:main.py 读取方向键 / WASD 并发布
  geometry_msgs/Twist 到 /turtle1/cmd_vel,支持空格停车、+/- 调速,
  退出时发布零速度;提供 main.launch 一键启动和 rosrun 两种运行方式。
- 新增 docs/chapter/chap1/turtlesim_teleop.md:环境验证、控制原理、运行
  步骤、常用 ROS 命令速查、CARLA-ROS 桥接源码结构阅读笔记和运行截图。
- 在首页、mkdocs 导航和第一章页面加入口,方便检索。
- 新增 tests/test_turtlesim_teleop_local.py(25 项桩测试),不依赖 ROS。

验证:mkdocs build 通过;mkdocs serve --livereload 下页面、导航和截图
链接均返回 200。本机为 Windows 且未安装 ROS,ROS 端实际运行未验证,
仅验证了按键映射、消息字段和工程文件。

评审修复:
- main.launch 移到 launch/main.launch,与同级 chap1 包的目录约定一致;
- CMakeLists.txt 补 install(DIRECTORY launch DESTINATION
  ${CATKIN_PACKAGE_SHARE_DESTINATION}),catkin_make install 后
  roslaunch turtlesim_teleop main.launch 能找到 launch 文件;
- 文档目录树、CMakeLists 职责说明同步更新;
- 替换文档中误粘贴的 CARLA 桥接小节,改为 turtlesim 遥控的实际
  数据流与安装说明;
- 测试改用 launch/main.launch,并新增 launch 安装规则检查;本地
  26 项测试通过。
@xinyangtang91

Copy link
Copy Markdown
Contributor Author

已按评审意见修改并重新推送:

  • main.launch 移到 launch/main.launch,与同级 chap1 包(turtle_hub、turtle_text)的目录约定一致;
  • CMakeLists.txt 补上安装规则:
    install(DIRECTORY launch
      DESTINATION ${CATKIN_PACKAGE_SHARE_DESTINATION}
      USE_SOURCE_PERMISSIONS)
    catkin_make install 或发布场景下 roslaunch turtlesim_teleop main.launch 可以从 share 目录找到 launch 文件;
  • 文档目录树、CMakeLists 职责说明同步更新;文档里误粘贴的 CARLA 桥接小节(5.2–5.4 和总结中的一段)已替换为 turtlesim 遥控的实际数据流与安装说明;
  • 测试改用 launch/main.launch,并新增“CMakeLists 安装 launch 目录”检查,本地 26 项全部通过;
  • 分支已重建到最新 master,PR 现在 mergeable=true(11 个文件)。

@tianyutu981
tianyutu981 merged commit a879b24 into OpenHUTB:master Nov 13, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants