TurtleBot3(Burger / Waffle Pi) 复刻全流程
TurtleBot3(Burger / Waffle Pi) 从采购、打印、组装到装软件、标定和训练的 217 个步骤,附物料表、购买链接与官方出处。
Burger(树莓派 4 4GB)783.50 美元,Waffle Pi(树莓派 4 2GB)1,908.31 美元、(4GB)1,933.61 美元(robotis.us,2026‑10‑31,均显示有货;运费结账时计算,页面未提税);套件含树莓派、激光雷达、电池、充电器与电源,未给自购物料总价
采购
- 选购兼容 DYNAMIXEL 与 ROBOTIS 传感器
OpenCR1.0 控制板除可控制 DYNAMIXEL 执行器外,也可连接 ROBOTIS 传感器,包括触摸、红外、颜色等传感器。
- 准备 microSD 卡和读卡器
如果电脑没有 microSD 卡插槽,请使用 microSD 卡读卡器烧录恢复镜像。读卡器不包含在 TurtleBot3 套装中。
打印与加工
- 下载 Onshape 上的 3D CAD 数据用于打印
TurtleBot3 零件的 3D CAD 数据通过 Onshape 发布,可用桌面、笔记本甚至便携设备的浏览器访问并获取。
- 下载 OpenCR1.0 板卡设计文件自制
若想自行制作或修改 OpenCR1.0 板卡,可在开源许可下获取其原理图、PCB Gerber 文件、BOM 与固件源代码。
组装
- 连接 OpenCR 与树莓派
使用 micro USB 数据线将 OpenCR 连接到 Raspberry Pi。
- 连接 HDMI 线缆
在给树莓派上电前连接 HDMI 线缆,否则树莓派 HDMI 端口将被禁用。
软件与固件
- 连接 SBC 电源和外设
使用壁式电源为 SBC 供电,不要使用电池。
- 连接显示器和输入设备
连接 HDMI 显示器、键盘和鼠标以完成设置。
- 准备 microSD 卡和读卡器
如果电脑没有 microSD 卡插槽,请使用 microSD 卡读卡器刻录恢复镜像。
- 下载或更新 Raspberry Pi Imager
下载 Raspberry Pi Imager,用于在 Raspberry Pi 上安装 Ubuntu Server 22.04;如果已经安装,请更新至最新版本。
- 选择 deb 或 apt 安装方式
安装 deb 或 apt 版本的 rpi-imager。
- 下载 deb 文件
下载 Raspberry Pi Imager 的 deb 文件。
- 安装 deb 版本
进入下载目录,并使用 dpkg 安装下载的 deb 文件。
- 解决 deb 依赖错误
如果出现依赖错误,使用 apt-get 强制完成安装,然后运行 rpi-imager。
- 通过 apt 安装并启动
使用 apt 安装 rpi-imager,然后启动它。
- 运行 Raspberry Pi Imager
运行 Raspberry Pi Imager,为 Raspberry Pi 安装 Ubuntu。
- 选择操作系统
在 Raspberry Pi Imager 中点击 CHOOSE OS。
- 选择通用型操作系统
选择 Other gerneral-purpose OS。
- 选择 Ubuntu
从可用操作系统中选择 Ubuntu。
- 选择 Ubuntu Server 22.04.5
选择支持 RPi 3、4 和 400 的 Ubuntu Server 22.04.5 LTS(64 位),不要选择桌面版。
- 选择 micro SD 卡
点击 CHOOSE STORAGE,然后选择 micro SD 卡。
- 开始安装 Ubuntu
点击 Next,开始将 Ubuntu 安装到所选的存储设备。
- 编辑 Wi-Fi 和 SSH 设置
点击 Edit Setting,配置 Wi-Fi 和 SSH。
- 设置账户、Wi-Fi 和 SSH
设置用户名和密码、无线 LAN、无线 LAN 国家;在 SERVICES 标签中启用 Enable SSH,并选择 Use password authenication。
- 跳过后续 Wi-Fi 配置
完成此配置后,可以跳过文档中直到第 4 步的 Wi-Fi 配置。
- 通电前连接 HDMI 线
Raspberry Pi 通电前必须连接 HDMI 线,否则 HDMI 端口会被禁用。
- 编辑网络配置文件
使用 nano 编辑 /etc/netplan/50-cloud-init.yaml。
- 打开自动升级配置
使用 nano 编辑 /etc/apt/apt.conf.d/20auto-upgrades。
- 关闭自动更新设置
按照 TurtleBot3 SBC 的设置,将软件包列表更新和无人值守升级设为 0。
- 屏蔽网络在线等待服务
在 Raspberry Pi 上屏蔽 systemd-networkd-wait-online.service。
- 禁用挂起和休眠
在 TurtleBot3 SBC 上禁用 sleep、suspend、hibernate 和 hybrid-sleep 目标。
- 重启 Raspberry Pi
重启 Raspberry Pi,使配置生效。
- 从远程电脑连接 SSH
重启后,从远程电脑终端使用 Ubuntu 用户名和 Raspberry Pi 的 IP 地址建立 SSH 连接。输入第 1 步中设置的密码。
- 编辑 SSH 配置
在 Raspberry Pi 上使用 nano 编辑 /etc/ssh/sshd_config.d/50-cloud-init.conf。
- 安装 net-tools 并检查 IP
在 Raspberry Pi 上安装 net-tools,然后使用 ifconfig 检查 IP 地址。
- 再次从远程电脑连接
在远程电脑上运行 SSH 命令,并输入 Ubuntu 系统密码。
- 创建2GB交换空间
使用TurtleBot3 2GB时,创建2GB交换空间,以避免构建软件包时内存不足或失败。
- 开机自动启用交换空间
将交换文件写入/etc/fstab,使系统在重启后自动激活。
- 安装基础构建依赖
安装python3-argcomplete、python3-colcon-common-extensions、libboost-system-dev和build-essential。
- 安装ROS驱动和消息包
安装HLS-LFCD-LDS驱动、TurtleBot3消息、Dynamixel SDK、Xacro和libudev-dev。
- 克隆TurtleBot3软件仓库
在~/turtlebot3_ws/src中克隆humble分支的turtlebot3、ld08_driver和coin_d4_driver仓库。
- 移除未使用的软件包
进入TurtleBot3仓库,删除turtlebot3_cartographer和turtlebot3_navigation2目录。
- 构建TurtleBot3工作空间
返回工作空间,加载ROS Humble环境,并使用符号链接安装和1个并行工作进程进行构建。
- 保存并加载工作空间环境
将TurtleBot3工作空间的安装环境添加到.bashrc并立即加载。
- 配置OpenCR的USB端口
复制TurtleBot3 CDC udev规则,重新加载规则并触发udev。
- 设置ROS域ID
远程PC和TurtleBot3的ROS_DOMAIN_ID必须一致,才能在同一网络环境中通信。
标定与测试
- 确认 Burger 模型输出
检查终端输出,确认 TURTLEBOT3_MODEL 已设置为 burger。
- 设置 BURGER 机型
将 TURTLEBOT3_MODEL 环境变量设为 burger,以选择 TurtleBot3 BURGER。
- 设置 ROS 域 ID
在远程 PC 和 TurtleBot3 SBC 上将 ROS_DOMAIN_ID 设置为 30,确保两者使用相同的 ROS_DOMAIN_ID。
- 匹配 RMW 实现
在远程 PC 和 TurtleBot3 SBC 上将 RMW_IMPLEMENTATION 设置为 rmw_fastrtps_cpp,确保两者使用相同的 ROS 中间件实现。
- 允许 Wi-Fi 组播
确认 Wi-Fi 路由器支持组播;如果支持,请在路由器上配置为允许组播。
- 列出 ROS 主题
运行主题列表命令,检查 battery_state、cmd_vel、imu、joint_states、magnetic_field、odom、parameter_events、robot_description、rosout、scan、sensor_state、tf 和 tf_static 等主题。主题列表可能因安装的 ROS 软件包版本而异。
- 列出 ROS 服务
运行服务列表命令,检查 diff_drive_controller、hlds_laser_publisher、launch_ros、motor_power/reset、sound 和 turtlebot3_node 等服务及参数接口。
- 选择速度消息类型
Jazzy 版本默认在 cmd_vel 话题中使用 TwistStamped 类型。要使用 Twist 类型,请在 bringup 包中将 enable_stamped_cmd_vel 参数设为 false。
- 通过 SSH 连接 Raspberry Pi
在远程 PC 上按 Ctrl + Alt + T 打开新终端,使用 Raspberry Pi 的 IP 地址通过 SSH 连接,并输入 Raspberry Pi 中 Ubuntu OS 的密码。
- 启动 TurtleBot3 基本软件包
在 Raspberry Pi 终端中指定 TurtleBot3 型号,然后启动 bringup 机器人以运行基本应用。
- 检查 Burger 型号启动输出
当 TURTLEBOT3_MODEL 设置为 burger 时,检查终端输出是否与文档所示的启动输出相符。
- 确认陀螺仪自校准与设备初始化
在终端输出中确认 DynamixelSDKWrapper 成功打开端口 /dev/ttyACM0 并更改波特率,陀螺仪校准结束,且电池、IMU、传感器、关节状态发布器与电机电源服务器均创建成功。
- 确认差速驱动里程计运行
最后确认 diff_drive_controller 初始化里程计并显示 Run!,表示机器人已就绪。
- 匹配 ROS_DOMAIN_ID
确认远程 PC 和 TurtleBot3 SBC 使用相同的 ROS_DOMAIN_ID,并在两端设置为 30。
- 匹配 RMW 实现
确认远程 PC 和 TurtleBot3 SBC 使用相同的 RMW 实现,并在两端设置为 rmw_fastrtps_cpp。
- 检查 Wi-Fi 路由器组播支持
检查 Wi-Fi 路由器是否支持多播;如果支持,则配置路由器允许多播。
- 显示主题列表
运行主题列表命令;显示内容可能因已安装的 ROS 包版本而异。
- 显示服务列表
运行服务列表命令;显示内容可能因已安装的 ROS 包版本而异。
- 确认 Burger 模型启动消息
如果 TurtleBot3 模型是 burger,终端会显示文档中所示的消息。
- 确认 OpenCR 已连接
启动 bringup 后,系统连接 OpenCR 控制板,并报告 core(v1.2.1) 与 TB3 Burger 兼容。
- 完成陀螺仪自动校准
连接 OpenCR 后,系统自动开始陀螺仪校准,并在日志显示“Calibration End”时结束。
- 检查交换空间
运行free -h命令检查交换空间。
- 确认默认ROS域ID
TurtleBot3的默认ROS_DOMAIN_ID为30。
- 将ROS域ID配置为30
建议将Remote PC和TurtleBot3 SBC的ROS_DOMAIN_ID都设置为30,并在.bashrc中添加该设置。
- 启用旧版摄像头驱动
运行 raspi-config,在 Interface Options 中选择 I1,并启用旧版摄像头支持,以使用 bcm2835 MMAL。完成后 camera-ros 包的摄像头节点将无法检测摄像头;再次使用 camera-ros 时必须禁用旧版驱动。
- 修改旧版摄像头配置
添加 camera_auto_detect=0、start_x=1,以及启用 bcm2835-v4l2 旧版摄像头栈的说明。若之后使用 camera-ros 包,请删除或注释 camera_auto_detect=0、start_x=1 和 dtoverlay=imx219。
- 检查摄像头设备名称
运行 v4l2-ctl --list-devices 检查摄像头名称。本例中的摄像头名称是 mmal_service_16.1。
- 查看摄像头图像输入
在远程 PC 上运行 rqt_image_view,通过显示 ROS 2 图像主题来验证摄像头节点是否正确发布图像数据。
- 按链接校准相机
如果计划使用相机校准等高级视觉功能,请按照链接中的详细说明进行校准。
- 排查相机校准文件错误
If the “Unable to open camera calibration file” error appears, check the solution provided in the linked troubleshooting guide.
- 选择 Other general-purpose OS
在操作系统选择窗口中,点击 Other gerneral-purpose OS。
- 选择 Ubuntu Server 24.04.2
选择 Ubuntu,然后选择支持 RPi 3/4/400 的 Ubuntu Server 24.04.2 LTS 64 位版本。应选择 Server OS,而不是 desktop OS。
- 选择 microSD 卡
点击 CHOOSE STORAGE,并选择用于安装 Ubuntu 的 microSD 卡。
- 配置 Wi-Fi 和 SSH
点击 Edit Setting,设置用户名和密码、Configure wireless LAN、Wireless LAN country,并在 SERVIES 标签页启用 Enable SSH,使用密码认证。
- 跳过重复的 Wi-Fi 配置
完成 Imager 中的配置后,可以跳过随后 Wi-Fi 配置部分的前四步。
- 给 OpenCR 供电并开机
组装完成后,将电源连接到 OpenCR 并打开电源开关。红色 Power LED 会亮起。
- 将机器人放在平坦空旷区域
将机器人放在平坦地面和宽阔开放区域。测试建议保持 1 米(40 英寸)的安全半径。
- 测试前进动作
按住 PUSH SW 1 几秒,命令机器人向前移动 30 厘米(约 12 英寸)。
- 测试原地旋转动作
按住 PUSH SW 2 几秒,命令机器人原地旋转 180 度。
- 给 OpenCR 供电并启动机器人
组装完成后连接 OpenCR 电源并打开电源开关,红色 Power LED 随即亮起。
用起来
- 在 Rviz 中加载 TurtleBot3
运行 TurtleBot3 的 Rviz2 启动文件,并在 Rviz 中显示机器人。
- 在 Rviz 中加载 TurtleBot3
运行 TurtleBot3 的 rviz2 启动文件。
- 在远程 PC 上运行 roscore
在远程 PC 上运行 roscore。
- 通过 SSH 连接 Raspberry Pi
在远程 PC 上按 Ctrl + Alt + T 打开新终端,然后通过 SSH 连接 Raspberry Pi。默认密码为 turtlebot。
- 启动 TurtleBot3 应用程序
在 TurtleBot3 SBC 上启动基础软件包,以运行所需的 TurtleBot3 应用程序。
- 查阅 RViz 启动指南
阅读文档中链接的 RViz 启动指南。
- 使用键盘控制机器人
节点成功启动后,使用 w/a/s/d 移动;w/x 增减线速度,a/d 增减角速度,space 或 s 强制停止,CTRL-C 退出。Burger 的速度约为线速度 0.22、角速度 2.84,Waffle 和 Waffle Pi 约为线速度 0.26、角速度 1.82。
- 使用 RC-100B 控制机器人
使用 RC-100B 的上/下键增减线速度,使用左/右键增减角速度。
- 使用 RC-100B 遥控器
将 RC-100B 与 BT-410 蓝牙模块配合 OpenCR 固件使用;Waffle Pi 套装包含遥控器和蓝牙模块。
- 启用 TurtleBot3 遥控
通过遥控器操作 TurtleBot3;在桌面测试时要小心,机器人可能从边缘掉落。
- 使用键盘控制运动
使用 w、a、s、d 移动;使用 w/x 增减线速度,使用 a/d 增减角速度,按空格键或 s 强制停止,按 CTRL-C 退出。
常见问题
- SBC 安装因依赖、架构检测或代理安装错误而失败。 #702 #304 #461 #401 #455
- SBC 无法与 PC 通信,或更新后 ROS 停止响应。 #703 #431
- ROS 2 因操作系统、时钟或版本不兼容而崩溃或失败。 #593 #1079 #546
- 摄像头、OpenCR 上传或机器人启动在设置期间失败。 #863 #240 #149
- SLAM 未生成地图,或建图时机器人位置停滞不动。 #80 #83 #195 #307
- 导航定位及 RViz 的变换、位置或方向错误。 #78 #266 #362 #99 #203
- 里程计数值或坐标系变得不合理、不一致或不稳定。 #926 #847 #880
- 遥控或速度命令未能更新机器人运动。 #809 #1028
物料
- 树莓派 4(Burger 4GB;Waffle Pi 2GB 或 4GB)+ OpenCR 1.0(STM32F746,Cortex‑M7 216 MHz)
- 2 个 DYNAMIXEL 驱动轮:Burger 用 XL430‑W250‑T(11.1V 时堵转 1.4 N·m),Waffle Pi 用 XM430‑W210‑T
- 360° 激光雷达 LDS‑03 与 USB2LDS;Waffle Pi 另有树莓派摄像头 v2.1、RC‑100B 遥控器与 BT‑410 蓝牙
- 11.1V 1,800 mAh 锂聚合物电池(19.98 Wh)与充电器、12V 5A 电源;续航约 2.5 小时(Burger)/ 2 小时(Waffle Pi),充电约 2.5 小时
- Burger 138×178×192 mm、1 kg、最高 0.22 m/s、载重 15 kg;Waffle Pi 281×306×141 mm、1.8 kg、0.26 m/s、载重 30 kg
- 注塑华夫板、支柱、轮胎与万向球、螺丝与铆钉(e-Manual 零件表)
工具
- 套件附螺丝刀与铆钉工具(零件表)
- 装 Ubuntu 22.04 或 24.04 的远程 PC,并给树莓派烧录 microSD 镜像
- 改结构可从 Onshape CAD 自行 3D 打印零件
技能
- Linux 与 ROS 2(Humble / Jazzy)
- SLAM(Cartographer)、Nav2 导航与 Gazebo 仿真
- 可选:Arduino IDE 开发 OpenCR 固件
软件
- turtlebot3 ROS 2 软件包(最新 2.3.7,2026‑06‑15;humble、jazzy 与 rolling 分支)
- turtlebot3_simulations(Jazzy 配 Gazebo Harmonic)与 Docker 环境(2.3.4 起)
- e-Manual 示例:自动驾驶 AutoRace、加装 OpenMANIPULATOR‑X 的移动操作、家庭服务挑战赛
- OpenCR 固件(OpenCR 仓库的 turtlebot3_ros2 库)与 LDS‑03 驱动 coin_d4_driver