1. 为什么我要做这个树莓派4B的ROS Melodic完整版镜像
树莓派4B跑ROS，这件事在机器人圈子里一直是个又爱又恨的话题。爱的是它便宜、功耗低、体积小，装在移动机器人上几乎不占地方；恨的是从系统安装到ROS环境跑通，中间要踩的坑实在太多了。我自己前前后后折腾过不下十块树莓派，从3B+到4B再到CM4，每次给新板子配环境都要重新走一遍那些繁琐的流程，时间长了就萌生了一个想法：能不能做一个开箱即用的完整版镜像，把ROS Melodic和常用工具链全部预装好，烧录完直接就能跑？
这个v1.0版本镜像就是在这个背景下诞生的。它的核心定位很明确：面向ROS初学者和需要快速部署机器人原型的开发者，基于树莓派4B硬件平台，预装Ubuntu 18.04 + ROS Melodic完整版桌面环境，同时集成常用的机器人开发工具、Python科学计算库、OpenCV、以及一些我平时做项目积累下来的配置脚本。烧录之后，你不需要再折腾源、不需要手动编译cv_bridge、不需要为串口权限发愁，插上电就能开始写节点。
适合谁来用？如果你刚接触ROS，手上正好有一块树莓派4B，想用它做SLAM小车、机械臂控制、视觉识别这类项目，这个镜像能帮你省掉至少两天的环境配置时间。如果你是有经验的开发者，需要批量部署多台树莓派节点，这个镜像也可以作为基础模板，在上面做二次定制。当然，如果你用的是树莓派5或者别的ARM板卡，这个镜像不适用，需要另找方案。
在展开具体内容之前，先说清楚一个前提：这个镜像不是官方发行版，是我个人基于实际项目需求制作的整合版本。里面所有的配置和脚本都经过实机验证，但不同批次的树莓派4B在WiFi模块、USB控制器上可能有细微差异，遇到问题需要具体排查。下面我会从设计思路、核心细节、实操过程、问题排查几个维度，把这个镜像的来龙去脉讲透。
2. 镜像整体设计与方案选型拆解
2.1 为什么选Ubuntu 18.04而不是Raspbian
ROS Melodic的官方支持平台是Ubuntu 18.04，这一点是硬性约束。虽然Raspbian也能通过源码编译的方式装上ROS，但那个过程极其痛苦，依赖冲突、编译错误、Python版本混乱，随便一个问题就能卡住半天。我早期在Raspbian Stretch上编译过ROS Melodic的基础包，光是roscore能跑起来就花了一个通宵，后面装rviz和gazebo更是噩梦。
Ubuntu 18.04 for Raspberry Pi有官方维护的ARM64镜像，内核和驱动支持都比较完善，apt源里的包也齐全。用这个作为基础系统，ROS Melodic可以直接通过apt安装，省去了大量编译时间。而且Ubuntu的软件生态更丰富，很多Python库和工具链都有现成的ARM64包，不用自己从源码构建。
这里有个细节需要注意：树莓派4B有1GB、2GB、4GB、8GB几个内存版本。1GB版本跑Ubuntu桌面会比较吃力，建议用Lite版本加轻量级桌面，或者直接命令行操作。2GB以上版本跑完整桌面环境问题不大，4GB以上就很流畅了。我的镜像默认是针对4GB版本优化的，2GB版本也能用，但开rviz的时候会有点卡。
2.2 桌面环境的选择：LXDE还是GNOME
Ubuntu 18.04默认的GNOME桌面在树莓派4B上跑起来比较重，内存占用高，CPU负载也不低。我试过在4GB版本上跑GNOME，开机后空闲内存只剩2.3GB左右，再开个rviz和几个节点，内存就快满了。后来换成了LXDE桌面，空闲内存能保持在3GB以上，整体响应速度也快不少。
LXDE的另一个好处是资源占用低，对GPU加速的依赖小。树莓派4B的VideoCore VI GPU在Linux下的驱动支持虽然比以前好很多，但跑GNOME的合成器还是有点吃力。LXDE没有复杂的桌面特效，用起来更流畅。当然，如果你习惯GNOME的操作逻辑，也可以自己装，但需要接受性能上的妥协。
镜像里我预装了LXDE，同时保留了轻量级的文件管理器和终端工具。桌面壁纸和主题做了简单定制，看起来不那么简陋，但也没有花哨的效果。毕竟这是用来做机器人开发的，不是用来当桌面PC用的。
2.3 ROS Melodic完整版都包含什么
“完整版”这个词需要定义清楚。ROS Melodic的安装包分为几个层级：ros-melodic-ros-base只包含核心通信库和基础工具；ros-melodic-desktop包含rviz、rqt等可视化工具；ros-melodic-desktop-full在此基础上增加了gazebo仿真、导航包、感知包等。
我的镜像装的是desktop-full，也就是最全的那个版本。具体包含的内容有：
- 核心通信层：roscore、rostopic、rosservice、rosparam、roslaunch等基础工具
- 可视化工具：rviz、rqt全家桶（rqt_graph、rqt_plot、rqt_console等）
- 仿真环境：gazebo 9、gazebo_ros_pkgs
- 导航与SLAM：navigation、gmapping、amcl、cartographer
- 感知与视觉：opencv3、cv_bridge、image_transport、pcl_ros
- 机械臂相关：moveit、robot_state_publisher、joint_state_publisher
- 常用消息包：sensor_msgs、geometry_msgs、nav_msgs、tf2
除此之外，我还额外装了一些常用工具：Python3的numpy、scipy、matplotlib、scikit-learn，以及serial、pyserial用于串口通信，还有git、vim、tmux这些开发必备工具。
2.4 预装脚本和配置的设计逻辑
镜像里我放了几个自己写的脚本，放在/home/pi/scripts/目录下。这些脚本解决的是每次装完系统都要重复操作的问题：
第一个是setup_ros_env.sh，用来配置ROS环境变量。它会自动把source /opt/ros/melodic/setup.bash加到.bashrc里，同时设置ROS_MASTER_URI和ROS_IP的默认值。很多新手第一次装完ROS，运行roscore提示找不到命令，就是因为没source环境变量。这个脚本一步到位。
第二个是setup_serial.sh，用来配置串口权限。树莓派上接激光雷达、STM32、Arduino这些设备时，经常遇到Permission denied的问题。这个脚本会把当前用户加入dialout组，同时创建udev规则，让常见的USB转串口芯片（CH340、CP2102、FTDI）自动获得读写权限。
第三个是setup_workspace.sh，用来创建ROS工作空间。它会自动创建~/catkin_ws/src目录，执行catkin_make初始化，并把工作空间的setup.bash也加到.bashrc里。这样你拿到镜像后，直接就能开始创建功能包。
第四个是check_system.sh，用来做系统自检。它会检查ROS环境是否正常、串口设备是否识别、摄像头是否可用、网络配置是否正确。输出结果用颜色区分，绿色表示正常，红色表示有问题。这个脚本在排查问题时特别有用。
2.5 镜像体积和烧录方式的权衡
完整版镜像的体积肯定小不了。我最终生成的img文件大概8.2GB，压缩成zip后约3.1GB。这个体积对于32GB的TF卡来说完全没问题，16GB的卡也能勉强装下，但剩余空间就不多了，建议至少用32GB的卡。
烧录工具推荐用balenaEtcher，跨平台，操作简单，烧录完会自动校验。不推荐用dd命令，容易写错设备名，把电脑硬盘给格了。烧录完成后，第一次启动会自动扩展文件系统，这个过程大概需要1-2分钟，期间屏幕可能会黑一下，正常现象，不要断电。
镜像默认开启了SSH，用户名是pi，密码是raspberry。第一次登录后建议立刻改密码。WiFi默认没有配置，需要手动设置，或者插网线。这些基础操作后面会详细说。
3. 核心细节解析与实操要点
3.1 系统基础环境的配置细节
Ubuntu 18.04 for Raspberry Pi的初始配置有几个关键点需要处理。首先是软件源，默认的源在国外，更新速度很慢。我换成了国内某高校的镜像源，更新速度能到几MB/s。具体操作是修改/etc/apt/sources.list，把ports.ubuntu.com替换成镜像站地址。注意ARM64架构的源和x86不一样，不能直接抄网上的Ubuntu源配置。
然后是时区和locale设置。默认时区是UTC，国内用的话需要改成Asia/Shanghai。locale默认是en_US.UTF-8，如果不改，中文显示会乱码。我用dpkg-reconfigure locales生成了zh_CN.UTF-8，但系统语言还是保持英文，只是确保中文能正常显示。这样做的好处是终端里不会出现中文提示，避免一些脚本因为编码问题出错。
swap分区也调整过。树莓派4B的TF卡读写速度有限，默认swap只有100MB，编译大包的时候容易内存不足。我把swap扩大到了2GB，放在TF卡上。虽然TF卡做swap会影响寿命，但总比编译到一半OOM强。如果你用的是USB SSD启动，那swap性能会好很多。
3.2 ROS安装过程中的关键决策
ROS Melodic的安装本身不复杂，官方教程走一遍就行。但有几个地方容易出问题：
第一个是rosdep init和rosdep update。这两个命令在国内网络环境下经常失败，因为要访问raw.githubusercontent.com。我的解决办法是提前下载好rosdep的数据库文件，放在本地，然后修改/etc/ros/rosdep/sources.list.d/20-default.list指向本地文件。这样rosdep update就不需要联网了。镜像里已经做好了这一步，你直接用就行。
第二个是gazebo的安装。gazebo 9在ARM64上的支持不算完美，有些模型加载会报错。我测试下来，基本的仿真功能没问题，但复杂的场景可能会卡顿。如果只是做算法验证，建议用stage或者自己写轻量级仿真，gazebo在树莓派上跑起来确实吃力。
第三个是OpenCV的版本冲突。Ubuntu 18.04自带的OpenCV是3.2版本，ROS Melodic的cv_bridge默认链接的是这个版本。但很多视觉项目需要OpenCV 4.x的新特性。我的处理方式是保留系统自带的OpenCV 3.2给ROS用，另外在/usr/local下编译安装了OpenCV 4.5，通过CMake的find_package来区分。这样两套OpenCV共存，互不干扰。需要注意的是，自己编译OpenCV 4.5在树莓派4B上大概需要2-3小时，镜像里已经编译好了，省去了这个时间。
3.3 串口和硬件接口的配置要点
树莓派的串口配置是个老生常谈的问题。默认情况下，/dev/ttyAMA0被蓝牙占用，/dev/ttyS0是mini UART，性能不稳定。要使用硬件串口，需要修改/boot/config.txt和/boot/cmdline.txt。
具体操作是：在/boot/config.txt里加一行dtoverlay=pi3-miniuart-bt，把蓝牙切换到mini UART，硬件串口还给GPIO。然后在/boot/cmdline.txt里删掉console=serial0,115200，避免内核占用串口。重启后，/dev/ttyAMA0就可以用来接外部设备了。
USB串口设备相对简单，插上就能识别成/dev/ttyUSB0或/dev/ttyACM0。但权限问题需要处理，普通用户默认没有读写权限。我的setup_serial.sh脚本会创建/etc/udev/rules.d/99-serial.rules，内容如下：
KERNEL=="ttyUSB[0-9]*", MODE="0666" KERNEL=="ttyACM[0-9]*", MODE="0666"这样所有USB串口设备都会自动获得读写权限，不需要每次都用sudo。注意这个规则比较宽松，如果对安全性有要求，可以改成只对特定VID/PID的设备生效。
I2C和SPI默认是关闭的，需要用raspi-config开启。镜像里我已经通过修改/boot/config.txt开启了I2C和SPI，同时安装了i2c-tools和spidev。你可以直接用i2cdetect -y 1来扫描I2C设备。
3.4 网络配置与多机通信
ROS的多机通信需要设置ROS_MASTER_URI和ROS_IP。在树莓派上，如果WiFi和有线网同时存在，ROS可能会选错网卡。我的做法是在.bashrc里根据当前网络环境动态设置。
具体逻辑是：先检测wlan0是否有IP，如果有就用WiFi的IP；否则用eth0的IP。然后设置ROS_IP为这个IP，ROS_MASTER_URI为http://<master_ip>:11311。如果是单机运行，ROS_MASTER_URI就是http://localhost:11311。
这里有个坑：树莓派的hostname默认是raspberry，如果局域网里有多个树莓派，hostname冲突会导致ROS通信异常。我的建议是每台树莓派都改成不同的hostname，比如pi-robot1、pi-robot2。修改/etc/hostname和/etc/hosts即可。
WiFi配置方面，Ubuntu 18.04用的是netplan，配置文件在/etc/netplan/下。我写了一个模板，你只需要把SSID和密码填进去，然后执行netplan apply就行。注意netplan对缩进敏感，YAML格式写错会导致网络起不来，建议用netplan try先测试。
3.5 镜像裁剪与优化策略
完整版镜像体积大，但很多内容是可以裁剪的。我做了以下几方面的优化：
删除了/var/cache/apt/archives/下的deb包，省了大概1.5GB。清理了/usr/share/doc/下的文档，又省了几百MB。gazebo的模型库只保留了常用的几个，其他的删掉，省了2GB左右。Python的__pycache__目录也清理了一遍。
另外，我把ROS的日志目录~/.ros/log设成了tmpfs，这样日志写在内存里，不占TF卡空间，也减少了读写次数。但缺点是重启后日志就没了，排查问题时需要注意。如果你需要保留日志，可以改回普通目录。
镜像还开启了zram，用内存做压缩交换分区。树莓派4B的内存够大，zram能有效减少TF卡的swap读写，提升系统响应速度。具体配置在/etc/systemd/system/zram.service，我设了1GB的zram设备，压缩算法用lz4。
4. 实操过程与核心环节实现
4.1 从零开始制作镜像的完整流程
虽然你拿到的是最终镜像，但了解制作过程有助于你后续做定制。整个流程分为几个阶段：
第一阶段：基础系统安装。下载Ubuntu 18.04.5 for Raspberry Pi的img文件，用balenaEtcher烧录到TF卡。启动后完成初始配置：扩展文件系统、设置时区、换源、更新系统。这一步大概需要30分钟，主要时间花在apt upgrade上。
第二阶段：桌面环境安装。安装LXDE桌面，配置显示管理器为lightdm。安装中文字体、输入法（可选）、常用软件（vim、git、tmux、htop）。这一步大概20分钟。
第三阶段：ROS安装。添加ROS源、导入密钥、安装ros-melodic-desktop-full。这一步视网络情况，大概30-60分钟。安装完成后执行rosdep init和rosdep update，我用的是本地源方案，所以很快。
第四阶段：额外工具安装。编译安装OpenCV 4.5，安装Python科学计算库，配置串口和I2C，安装MoveIt和Cartographer。这一步最耗时，OpenCV编译就要2-3小时，Cartographer编译也要1小时左右。建议在性能更好的机器上交叉编译，或者直接用预编译包。
第五阶段：脚本和配置。把前面提到的几个脚本放到/home/pi/scripts/，设置可执行权限。配置.bashrc、.vimrc、.tmux.conf等。清理系统垃圾，压缩镜像。
第六阶段：测试和验证。在至少两块不同的树莓派4B上烧录测试，验证ROS核心功能、串口通信、摄像头、WiFi、SSH等。记录所有异常情况，修复后重新制作镜像。
4.2 关键配置文件的详细说明
镜像里有几个配置文件值得单独说明，因为后续定制大概率要改它们。
/boot/config.txt是树莓派的硬件配置文件。我修改的部分包括：
# 开启I2C和SPI dtparam=i2c_arm=on dtparam=spi=on # 串口配置：蓝牙用mini UART，硬件串口给GPIO dtoverlay=pi3-miniuart-bt enable_uart=1 # GPU内存分配，跑桌面和rviz需要多一点 gpu_mem=256 # 超频设置（可选，注意散热） over_voltage=2 arm_freq=1750超频这部分需要谨慎。树莓派4B的默认频率是1.5GHz，我超到了1.75GHz，性能提升大概10%，但发热明显增加。如果没有散热片或风扇，建议不要超频，或者只超到1.6GHz。稳定性比性能重要，跑ROS的时候死机比慢更让人崩溃。
/etc/netplan/50-cloud-init.yaml是网络配置。模板如下：
network: version: 2 ethernets: eth0: dhcp4: true wifis: wlan0: dhcp4: true access-points: "你的WiFi名称": password: "你的WiFi密码"注意YAML的缩进必须是空格，不能用Tab。写完后执行sudo netplan try，确认没问题再sudo netplan apply。
~/.bashrc里我加了几行：
source /opt/ros/melodic/setup.bash source ~/catkin_ws/devel/setup.bash 2>/dev/null export ROS_IP=$(hostname -I | awk '{print $1}') export ROS_MASTER_URI=http://$ROS_IP:11311 export GAZEBO_MODEL_PATH=$GAZEBO_MODEL_PATH:~/catkin_ws/src/modelsROS_IP自动获取本机IP，这样换网络环境也不用改配置。GAZEBO_MODEL_PATH指向工作空间里的模型目录，方便加载自定义模型。
4.3 镜像烧录后的首次启动配置
烧录完镜像，插卡上电，第一次启动会做几件事：扩展文件系统、生成SSH密钥、启动网络服务。这个过程大概1-2分钟，屏幕会显示启动日志。如果接了HDMI显示器，能看到LXDE桌面；如果没接显示器，可以通过SSH连接。
SSH连接的命令是ssh pi@<树莓派IP>，默认密码raspberry。第一次登录后，系统会强制要求改密码。改完后建议做几件事：
第一，运行~/scripts/check_system.sh，看看系统自检结果。如果有红色项，根据提示修复。
第二，运行~/scripts/setup_workspace.sh，创建工作空间。这个脚本会执行catkin_make，大概需要5分钟。
第三，测试ROS核心功能。开一个终端运行roscore，再开一个终端运行rostopic list，如果能看到/rosout和/rosout_agg，说明ROS环境正常。
第四，测试摄像头。接上USB摄像头，运行rosrun usb_cam usb_cam_node，然后rosrun image_view image_view image:=/usb_cam/image_raw，能看到画面就说明摄像头配置没问题。
第五，测试串口。接上串口设备，运行ls /dev/ttyUSB*，如果有设备节点，再运行python3 -c "import serial; s=serial.Serial('/dev/ttyUSB0',115200); print('OK')"，不报错就说明串口权限正常。
4.4 常用ROS功能的快速验证
镜像里预装了一些常用的ROS功能包，我列一下验证方法，方便你快速确认环境是否完整。
rviz：运行rosrun rviz rviz，如果能打开可视化界面，说明桌面环境和OpenGL驱动正常。注意在SSH下无法运行rviz，需要接显示器或者用VNC。
gazebo：运行roslaunch gazebo_ros empty_world.launch，如果能加载出空世界，说明gazebo安装成功。第一次启动会比较慢，因为要下载模型，耐心等几分钟。
导航包：运行roslaunch turtlebot3_navigation turtlebot3_navigation.launch，这是turtlebot3的导航示例，需要提前安装turtlebot3的包。如果没装，可以跳过这个测试。
MoveIt：运行roslaunch moveit_setup_assistant setup_assistant.launch，能打开配置助手就说明MoveIt正常。
Cartographer：运行roslaunch cartographer_ros demo_backpack_2d.launch，这是2D建图的示例，需要下载demo数据包。如果网络不方便，可以跳过。
这些测试不需要全部跑一遍，挑你项目里会用到的功能验证就行。全部跑一遍大概需要1-2小时，主要时间花在gazebo和cartographer的模型下载上。
4.5 镜像的备份与恢复方法
制作好的镜像需要备份，方便后续批量烧录。在Linux下可以用dd命令：
sudo dd if=/dev/sdX of=raspberry_ros.img bs=4M status=progress/dev/sdX是你的TF卡设备名，千万别写错。bs=4M是块大小，status=progress显示进度。备份出来的img文件可以用gzip压缩：
gzip -c raspberry_ros.img > raspberry_ros.img.gz压缩后大概3GB左右。恢复的时候用balenaEtcher直接烧录img.gz文件就行，它会自动解压。
如果你在Windows下，可以用Win32 Disk Imager来备份，操作更直观。但注意Windows下无法直接读取Linux分区，备份出来的img文件需要用balenaEtcher恢复。
注意：备份前最好先清理系统垃圾，执行
sudo apt clean和rm -rf ~/.ros/log/*，这样备份出来的镜像更小。另外，备份前把WiFi配置和SSH密钥清理掉，避免泄露个人信息。
5. 常见问题与排查技巧实录
5.1 系统启动类问题
问题一：烧录后无法启动，屏幕一直黑屏。
这种情况通常是TF卡的问题。树莓派4B对TF卡比较挑剔，一些杂牌卡或者老化卡会出现启动失败。建议用Class 10以上的品牌卡，容量32GB起步。如果卡没问题，检查烧录是否完整，重新烧录一次。还有可能是电源功率不够，树莓派4B需要5V 3A的电源，用手机充电器可能会供电不足。
问题二：启动后卡在random: crng init done。
这是熵池不足导致的，系统在等待足够的随机数。解决方法是在/boot/config.txt里加一行dtparam=random=on，或者安装haveged服务。镜像里已经装了haveged，如果还是卡，可能是TF卡读写太慢，换张好卡试试。
问题三：文件系统扩展失败，根分区还是原来的大小。
第一次启动时，系统会自动扩展文件系统。如果没扩展成功，可以手动执行sudo raspi-config，选择Advanced Options->Expand Filesystem。或者用sudo resize2fs /dev/mmcblk0p2手动扩展。
5.2 ROS运行类问题
问题一：运行roscore提示command not found。
说明ROS环境变量没生效。检查~/.bashrc里有没有source /opt/ros/melodic/setup.bash。如果没有，手动加一行，然后source ~/.bashrc。如果加了还是不行，检查/opt/ros/melodic/目录是否存在，可能ROS没装成功。
问题二：运行rviz提示Segmentation fault。
通常是OpenGL驱动问题。树莓派4B的GPU驱动在Ubuntu 18.04下需要额外配置。检查/boot/config.txt里gpu_mem是否至少256MB。另外，确保安装了mesa-utils和libgl1-mesa-dri。如果还是崩溃，试试用LIBGL_ALWAYS_SOFTWARE=1 rviz强制软件渲染，虽然慢但能跑起来。
问题三：gazebo启动后黑屏或者卡死。
gazebo在树莓派上跑确实吃力。首先确认gpu_mem够大，然后试试降低gazebo的渲染质量。在gazebo的配置里把阴影、反射这些效果关掉。如果还是不行，建议用stage替代，或者直接在PC上跑gazebo，树莓派只跑算法节点。
问题四：串口设备权限不足，提示Permission denied。
运行ls -l /dev/ttyUSB0看看权限。如果是crw-rw----，说明当前用户不在dialout组。执行sudo usermod -aG dialout $USER，然后重新登录。或者运行我预装的setup_serial.sh脚本，它会自动配置udev规则。
5.3 网络通信类问题
问题一：多机通信时，从机无法连接到主机的roscore。
首先确认主机的ROS_IP设置正确，在主机上运行echo $ROS_IP，应该显示主机的局域网IP。然后在从机上ping这个IP，确认网络连通。如果ping不通，检查防火墙和路由器设置。如果ping得通但ROS连不上，检查主机的ROS_MASTER_URI是否是http://<主机IP>:11311，从机的ROS_MASTER_URI是否指向同一个地址。
问题二：WiFi连接不稳定，经常掉线。
树莓派4B的WiFi模块在Ubuntu 18.04下有个省电模式，会导致连接不稳定。解决方法是在/etc/rc.local里加一行iwconfig wlan0 power off，或者创建/etc/systemd/system/wifi-powersave-off.service服务。另外，如果2.4GHz和5GHz同名，树莓派可能会频繁切换，建议把两个频段的SSID分开。
问题三：SSH连接超时或者被拒绝。
检查树莓派的SSH服务是否启动：sudo systemctl status ssh。如果没有启动，执行sudo systemctl enable ssh && sudo systemctl start ssh。如果服务正常但还是连不上，检查IP地址是否变化，树莓派的DHCP租约可能过期了。建议在路由器里给树莓派分配静态IP。
5.4 硬件接口类问题
问题一：I2C设备扫描不到。
首先确认/boot/config.txt里dtparam=i2c_arm=on已经开启，然后sudo i2cdetect -y 1扫描。如果全是--，说明设备没接好或者地址不对。检查SDA和SCL线是否接反，上拉电阻是否接上。有些I2C设备需要3.3V供电，接5V会烧毁。
问题二：摄像头无法识别。
USB摄像头一般免驱，插上就能用ls /dev/video*看到设备节点。如果看不到，换一个USB口试试，或者检查dmesg | tail看内核有没有识别到设备。CSI摄像头需要额外配置，在/boot/config.txt里加start_x=1和gpu_mem=128，然后重启。
问题三：GPIO控制无响应。
树莓派4B的GPIO在Ubuntu下需要用gpiod或者wiringPi来操作。wiringPi已经停止维护，建议用libgpiod。安装gpiod后，用gpiodetect查看GPIO控制器，用gpioinfo查看引脚状态。Python下可以用gpiozero库，API更友好。
5.5 性能优化类问题
问题一：系统运行缓慢，TF卡读写瓶颈明显。
TF卡的读写速度是树莓派最大的性能瓶颈。如果预算允许，建议用USB 3.0的SSD启动，速度能提升好几倍。树莓派4B支持USB启动，需要先更新bootloader，然后在/boot/config.txt里设置boot_order。具体操作可以参考官方文档，这里不展开。
问题二：编译大型ROS包时内存不足。
树莓派4B的4GB内存在编译大型包时确实吃紧。除了扩大swap，还可以用catkin_make -j2限制并行编译任务数，减少内存占用。如果还是不够，可以用交叉编译，在PC上编译好再传到树莓派上。
问题三：rviz运行卡顿，帧率很低。
rviz的渲染依赖GPU，树莓派4B的GPU性能有限。可以尝试降低rviz的刷新率，在rviz的配置里把Frame Rate调到10-15Hz。另外，关闭不必要的显示项，比如点云、图像这些大数据量的topic，能显著提升流畅度。
6. 我在这块镜像上踩过的坑和后续计划
做这个镜像的过程中，踩的坑比我预想的多得多。最折腾的是OpenCV的编译，ARM64架构下有些优化选项和x86不一样，NEON指令集的支持需要手动开启，编译参数调了好几次才通过。还有Cartographer的依赖，ceres-solver在ARM上编译需要打补丁，否则会报Eigen对齐错误。这些问题的解决方案我都记录在镜像的/home/pi/docs/目录下，遇到类似问题可以翻翻。
另一个坑是镜像体积的控制。第一次做出来的镜像有12GB，压缩后5GB多，16GB的卡根本装不下。后来删了gazebo的模型库、清理了apt缓存、压缩了Python的pyc文件，才降到8.2GB。如果你要自己定制，建议在制作过程中就注意清理，不要等到最后再删，有些文件删了会影响系统功能。
后续我计划做几个改进：一是增加对树莓派5的支持，树莓派5的性能提升明显，跑ROS 2更合适；二是做一个Lite版本，只装ROS基础包，体积控制在2GB以内，适合不需要桌面环境的场景；三是把常用的机器人功能包做成Docker镜像，这样部署更灵活，也不受系统版本限制。
如果你在使用过程中遇到问题，可以先看看/home/pi/docs/faq.md，里面整理了大部分常见问题。如果还是解决不了，可以把问题描述和check_system.sh的输出发到社区里，我看到会尽量回复。做这个镜像的初衷就是让更多人能快速上手ROS，少走一些我走过的弯路。
