正在连接信源…

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

文档