1. 项目概述为什么要在 reTerminal 上折腾 Yocto如果你手头有一块 reTerminal大概率和我一样是被它那块 5 英寸的 IPS 电容触摸屏、树莓派 CM4 核心模块的灵活性以及内置的 IMU、RTC 等丰富传感器所吸引。它是个绝佳的嵌入式人机交互HMI设备原型平台。但当你拿到手刷入官方提供的基于 Raspberry Pi OS 的镜像后可能会隐隐觉得哪里不对系统有点“胖”启动不够快后台服务一堆自己想深度定制个啥从内核驱动到根文件系统都感觉隔着一层纱无从下手。这时候Yocto 就该登场了。简单说Yocto 不是一个现成的 Linux 发行版而是一个构建自定义 Linux 系统的框架和工具集合。你可以把它想象成一个高度自动化的“Linux 系统厨房”你提供“菜谱”Layer 和配置文件它就能帮你从源代码开始编译出完全贴合你硬件比如 reTerminal和软件需求比如只包含 Qt 应用框架和你的一个前台程序的精简、高效、可复现的 Linux 系统镜像。为 reTerminal 构建 Yocto 镜像核心价值在于“掌控力”和“优化”。你不再是被动接受一个通用系统而是主动定义从 U-Boot 引导程序、Linux 内核、驱动、库、到最终应用程序的每一个环节。这对于产品化开发、追求极致启动速度、严格控制系统资源占用、或需要长期稳定维护的工业场景来说几乎是必经之路。这个过程虽然前期有学习成本但一旦跑通后续的迭代、裁剪、问题定位都会变得清晰无比。2. 核心思路与方案选型如何为 reTerminal “定制菜谱”直接从头开始为一块板子构建 Yocto 支持是极其复杂的。幸运的是开源社区和硬件厂商通常会提供基础“菜谱”即 Yocto 的 Layer。我们的策略是“站在巨人的肩膀上进行针对性改造”。2.1 基础 Layer 选型Poky Meta-RaspberryPiYocto 项目的核心是Poky它提供了构建系统最基础的元数据、构建工具如 BitBake和参考配置。但 Poky 本身不包含对具体硬件的支持。对于树莓派生态包括基于 CM4 的 reTerminal社区维护的meta-raspberrypi层是我们的不二之选。它包含了树莓派系列板子的 BSPBoard Support Package内核配置、U-Boot、启动引导方式、GPU 固件等。这是我们的硬件适配基石。2.2 关键决策内核与启动引导reTerminal 的官方系统使用树莓派内核和标准的config.txt启动方式。在 Yocto 世界里我们有两种主流选择沿用 RaspberryPi 的启动流程使用树莓派基金会提供的linux-raspberrypi内核配合bootfilesstart.elf 等 GPU 固件和config.txt。这是meta-raspberrypi层默认的方式兼容性最好能直接使用树莓派生态的闭源 GPU 驱动VC4以实现硬件加速。使用主线 U-Boot 主线内核这是一个更“嵌入式”、更开放的选择。通过 U-Boot 来引导一个更接近主线或特定版本的内核。这种方式对启动流程的控制力更强但 GPU 加速、某些外设驱动可能需要更多移植工作。对于 reTerminal 的初次 Yocto 化我强烈建议选择方案一。我们的首要目标是“跑起来”并确保显示屏、触摸屏、传感器等关键外设正常工作。meta-raspberrypi已经为我们铺好了大部分的路。后续若有极致定制需求再考虑方案二。2.3 我们的构建方案架构因此我们的 Yocto “菜谱”将由以下核心层构成Poky 构建系统骨架。meta-raspberrypi 树莓派硬件支持。meta-openembedded 一个庞大的、社区维护的软件包集合层meta-oe,meta-python,meta-networking等为我们提供成千上万个现成的软件包配方recipes。自定义层例如meta-reterminal 这是我们工作的核心。将包含机器配置文件conf/machine/reterminal.conf 定义 reTerminal 的硬件特性如 CPU 架构、内核类型、UBOOT_MACHINE如果使用 U-Boot、包含的硬件特性如蓝牙、wifi。镜像配方文件recipes-core/images/ 定义我们要构建的系统镜像里具体包含哪些软件包如 Qt5、触摸屏驱动、我们的应用。自定义配方文件 为 reTerminal 特有的组件如特定的传感器驱动、屏幕校准工具或我们的应用程序编写构建规则。这个架构确保了我们在一个稳定、社区支持良好的基础上进行精准的、针对 reTerminal 的定制。3. 环境搭建与 Layer 配置实操理论说再多不如动手搭环境。下面是一步步的实操指南。3.1 准备构建主机环境Yocto 构建对主机有一定要求。推荐使用 Ubuntu 22.04 LTS 或 20.04 LTS。你需要一块至少 100GB 空闲空间的硬盘SSD 最佳能极大缩短构建时间以及足够的内存建议 16GB 或以上8GB 会很吃力。首先安装必要的宿主机构建工具sudo apt update sudo apt install gawk wget git diffstat unzip texinfo gcc build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils iputils-ping python3-git python3-jinja2 libegl1-mesa libsdl1.2-dev pylint xterm python3-subunit mesa-common-dev zstd liblz4-tool file locales libacl1确保你的 locale 设置为 UTF-8否则构建过程中可能会报错sudo locale-gen en_US.UTF-8 export LANGen_US.UTF-83.2 获取 Yocto 核心源码Poky和基础层我们选择 Yocto 的长期支持版本kirkstone4.0作为起点它相对稳定成熟。# 创建一个工作目录并进入 mkdir ~/yocto-reterminal cd ~/yocto-reterminal # 克隆 Poky (kirkstone 分支) git clone -b kirkstone https://git.yoctoproject.org/poky.git # 克隆 meta-openembedded (kirkstone 分支) git clone -b kirkstone https://github.com/openembedded/meta-openembedded.git # 克隆 meta-raspberrypi (kirkstone 分支) git clone -b kirkstone https://github.com/agherzan/meta-raspberrypi.git3.3 创建并配置自定义层meta-reterminal这是专属于我们项目的层。# 在 yocto-reterminal 目录下 source poky/oe-init-build-env build # 这条命令会创建一个 build 目录并切换进去同时设置好必要的环境变量。 # 注意每次新开终端进入构建环境都需要执行此命令。 # 退出当前构建目录回到 yocto-reterminal 根目录 cd ~/yocto-reterminal # 创建自定义层的骨架 mkdir -p meta-reterminal/conf/machine mkdir -p meta-reterminal/recipes-core/images mkdir -p meta-reterminal/recipes-kernel/linux mkdir -p meta-reterminal/recipes-graphics/raspberrypi-firmware # 创建层的配置文件 cat meta-reterminal/conf/layer.conf EOF # 定义我们层的路径 BBPATH . :\${LAYERDIR} # 定义此层中的配方文件.bb和.bbappend的路径 BBFILES \${LAYERDIR}/recipes-*/*/*.bb \ \${LAYERDIR}/recipes-*/*/*.bbappend # 定义此层的优先级数字越大优先级越高后添加的层会覆盖先添加层中的同名配置。 BBFILE_COLLECTIONS reterminal BBFILE_PATTERN_reterminal ^ \${LAYERDIR}/ BBFILE_PRIORITY_reterminal 10 EOF3.4 编写 reTerminal 机器配置文件这是最关键的文件之一它告诉 Yocto 我们正在为 reTerminal 构建系统。cat meta-reterminal/conf/machine/reterminal.conf EOF #TYPE: Machine #NAME: reterminal #DESCRIPTION: Machine configuration for the reTerminal device based on Raspberry Pi CM4 # 继承 meta-raspberrypi 中为 CM4 定义的基础配置 require conf/machine/include/rpi-base.inc # 特别包含 CM4 的配置它会设置正确的 DTB 等 require conf/machine/include/rpi-cm4.inc # 定义机器名称会在镜像文件名等地方用到 MACHINE reterminal # 内核配置使用树莓派提供的内核 PREFERRED_PROVIDER_virtual/kernel linux-raspberrypi # 指定内核版本这里使用 kirkstone 分支兼容的 5.15 版本 PREFERRED_VERSION_linux-raspberrypi 5.15.% # 启动引导配置使用树莓派标准的 bootfiles 方式而非U-Boot RPI_USE_U_BOOT 0 # 启用 VC4 图形驱动KMS这是 HDMI 和 DSI 显示所必需的包括 reTerminal 的屏幕 # 注意reTerminal 的 5寸屏通过 DSI 接口连接需要此驱动 VC4GRAPHICS 1 # 启用 KMSKernel Mode Setting现代图形栈的基础 ENABLE_SPI_BUS 1 ENABLE_I2C 1 # GPU 内存分配对于 5寸屏和可能的硬件加速建议分配至少 128MB GPU_MEM 128 # 定义镜像安装的额外空间单位 KB。reTerminal eMMC 通常有 8GB 或 32GB这里预留一些空间。 IMAGE_ROOTFS_EXTRA_SPACE 65536 # 系统特性启用 wifi 和蓝牙reTerminal CM4 模块通常带有 MACHINE_FEATURES wifi bluetooth # 添加触摸屏支持特性 MACHINE_FEATURES touchscreen # 为 reTerminal 指定额外的内核启动参数如果需要 # 例如可以强制使用特定的 DSI 显示参数但通常树莓派内核能自动识别 # KERNEL_DEVICETREE_OVERLAYS \${THISDIR}/files/overlays/reterminal-dsi.dtbo EOF注意上面的配置假设树莓派内核能正确驱动 reTerminal 的屏幕。实际上reTerminal 的 5 寸屏可能需要特定的设备树覆盖Device Tree Overlay或内核参数。这通常需要从 reTerminal 官方资料或社区中寻找dtoverlay配置。如果找不到一个常见的方法是分析官方 Raspberry Pi OS 镜像中/boot/config.txt里关于屏幕的配置并将其转换到 Yocto 的配置中。我们稍后在问题排查章节会详细讨论。3.5 配置构建目录build/conf/local.conf初始化构建环境后build/conf/local.conf是主要的用户配置文件。我们需要修改它。cd ~/yocto-reterminal/build # 使用编辑器如 nano 或 vim打开 local.conf nano conf/local.conf找到并修改以下关键行如果不存在则添加# 指定我们定义的机器类型 MACHINE ?? reterminal # 选择构建的镜像类型。我们先从一个基础镜像开始例如 core-image-base # 后续我们会创建自己的镜像配方。这里先注释掉默认的我们会在后面自定义。 # IMAGE_FSTYPES rpi-sdimg # 更改为我们自定义的镜像类型例如 # IMAGE_FSTYPES tar.bz2 ext4 rpi-sdimg # 并行构建线程数根据你的 CPU 核心数设置可以显著加快构建速度。 # 例如 8 核 CPU 可以设置为 10略大于核心数以利用 I/O 等待时间 BB_NUMBER_THREADS ? 8 PARALLEL_MAKE ? -j 8 # 下载目录存放所有下载的源码包。可以指向一个大的公共目录避免重复下载。 # DL_DIR ? \${TOPDIR}/downloads # 构建缓存目录SSTATE可以加速后续构建。多个项目可以共享。 # SSTATE_DIR ? \${TOPDIR}/sstate-cache3.6 将各层添加到构建系统中我们需要编辑build/conf/bblayers.conf文件告诉 BitBake 我们的层结构。nano conf/bblayers.conf修改BBLAYERS变量添加我们所有的层路径请根据你的实际路径调整BBLAYERS ? \ /home/your-username/yocto-reterminal/poky/meta \ /home/your-username/yocto-reterminal/poky/meta-poky \ /home/your-username/yocto-reterminal/poky/meta-yocto-bsp \ /home/your-username/yocto-reterminal/meta-openembedded/meta-oe \ /home/your-username/yocto-reterminal/meta-openembedded/meta-python \ /home/your-username/yocto-reterminal/meta-openembedded/meta-networking \ /home/your-username/yocto-reterminal/meta-raspberrypi \ /home/your-username/yocto-reterminal/meta-reterminal \ 确保路径正确并且meta-reterminal在最后因为它的优先级我们在 layer.conf 中设为 10较高可以覆盖前面层的配置。4. 创建自定义镜像与软件包集成基础环境搭好了现在我们来定义最终要烧录到 reTerminal 里的系统镜像。4.1 创建基础镜像配方我们不直接使用core-image-base而是创建一个包含 reTerminal 基础功能的镜像。cd ~/yocto-reterminal/meta-reterminal/recipes-core/images nano reterminal-base-image.bb输入以下内容# 这是一个为 reTerminal 定制的基础镜像配方 SUMMARY A basic console image for the reTerminal device LICENSE MIT # 继承 core-image 类它提供了构建镜像的基础功能 inherit core-image # 设置镜像的额外功能特性 IMAGE_FEATURES ssh-server-openssh # 定义要安装的软件包 # 首先包含一些基础系统工具 CORE_IMAGE_BASE_INSTALL \ packagegroup-core-boot \ packagegroup-base-extended \ kernel-modules \ linux-firmware-rpidistro-bcm43455 \ wpa-supplicant \ iw \ crda \ tzdata \ e2fsprogs \ parted \ dosfstools \ util-linux \ vim \ # 添加树莓派相关的工具和固件 CORE_IMAGE_BASE_INSTALL \ rpi-config \ raspi2fb \ userland \ # 添加 I2C 工具方便调试传感器reTerminal 有多个 I2C 设备 CORE_IMAGE_BASE_INSTALL \ i2c-tools \ # 添加 Python3 及一些基础库很多应用和脚本会用到 CORE_IMAGE_BASE_INSTALL \ python3 \ python3-pip \ python3-modules \ # 清理镜像移除不必要的文档和包管理器数据库减小体积 IMAGE_INSTALL:remove packagegroup-core-standalone-sdk-target ROOTFS_RO_UNNEEDED ${bb.utils.contains(DISTRO_FEATURES, usrmerge, ${ROOTFS_RO_UNNEEDED_USRMERGE}, , d)}这个镜像配方定义了一个带有 SSH 服务、网络工具、文件系统工具、Python3 环境和基础调试工具的控制台系统。它还没有图形界面。4.2 构建并测试基础镜像现在我们可以尝试第一次构建。cd ~/yocto-reterminal/build # 设置好环境变量 source ../poky/oe-init-build-env . # 开始构建我们的自定义镜像 bitbake reterminal-base-image警告第一次构建会非常漫长数小时到十几小时取决于网络和主机性能因为它需要从网络下载所有源代码Linux 内核、工具链、各类库等并从头编译。请确保网络通畅并且有足够的耐心。构建成功后生成的镜像文件位于build/tmp/deploy/images/reterminal/目录下。我们需要的通常是reterminal-base-image-reterminal.rpi-sdimg如果IMAGE_FSTYPES包含了rpi-sdimg。你可以使用dd命令或Raspberry Pi Imager将这个.img文件烧录到 SD 卡插入 reTerminal 的 CM4 模块如果使用 eMMC可能需要通过 USB 烧录工具然后上电启动。4.3 集成图形界面与触摸屏支持如果 reTerminal 的亮点在于其屏幕那么一个图形界面是必不可少的。在嵌入式领域Qt 是一个流行的选择。我们可以创建一个带 Qt 和触摸屏支持的镜像。首先确保meta-raspberrypi层支持我们选择的图形后端Wayland 或 X11。meta-raspberrypi通常对wayland和vc4graphics有较好的集成。创建新的镜像配方cd ~/yocto-reterminal/meta-reterminal/recipes-core/images nano reterminal-qt-image.bb输入内容SUMMARY A Qt5 image with Weston/Wayland for reTerminal touchscreen LICENSE MIT # 继承我们之前的基础镜像并添加图形特性 require recipes-core/images/reterminal-base-image.bb # 添加对 Wayland 和 Qt5 的支持 DISTRO_FEATURES:append wayland opengl # 如果使用 X11则改为 DISTRO_FEATURES:append x11 opengl # 安装 Qt5 相关的软件包组 IMAGE_INSTALL:append \ packagegroup-qt5-wayland \ qtwayland \ qtwayland-plugins \ qtbase-fonts \ qtbase-plugins \ qtdeclarative \ qtdeclarative-qmlplugins \ # 安装 WestonWayland 合成器作为我们的窗口系统 IMAGE_INSTALL:append \ weston \ weston-init \ weston-examples \ # 安装触摸屏校准工具可选但建议 IMAGE_INSTALL:append \ tslib \ tslib-calibrate \ tslib-tests \ # 安装一个简单的 Qt 示例应用用于测试 IMAGE_INSTALL:append \ qt5everywheredemo \ # 设置 Weston 自动启动通过 systemd 或 inittab这里以 systemd 为例 # 我们需要创建一个 systemd service 文件但这通常可以通过 weston-init 包处理。 # 更常见的做法是在镜像构建后手动修改根文件系统或创建一个 bbappend 文件来配置 weston.ini。这个配方构建的镜像将包含 WestonWayland 合成器和 Qt5 应用框架。qt5everywheredemo是一个很好的测试程序可以验证图形栈和触摸是否正常工作。4.4 配置 Weston 和触摸屏为了让 Weston 能正确识别 reTerminal 的触摸屏我们需要配置weston.ini。创建一个配方来提供自定义配置。mkdir -p ~/yocto-reterminal/meta-reterminal/recipes-graphics/wayland nano ~/yocto-reterminal/meta-reterminal/recipes-graphics/wayland/weston-ini_%.bbappendbbappend文件用于修改或追加到已有配方。我们为weston-ini配方添加我们的配置# 此文件用于追加配置到 weston.ini FILESEXTRAPATHS:prepend : \${THISDIR}/files: # 安装我们自定义的 weston.ini SRC_URI file://weston.ini # 确保我们的配置文件被安装到正确位置 do_install:append() { install -d \${D}\${sysconfdir}/xdg/weston install -m 0644 \${WORKDIR}/weston.ini \${D}\${sysconfdir}/xdg/weston/ }然后创建对应的配置文件mkdir -p ~/yocto-reterminal/meta-reterminal/recipes-graphics/wayland/files nano ~/yocto-reterminal/meta-reterminal/recipes-graphics/wayland/files/weston.ini在weston.ini中我们需要指定输入设备。reTerminal 的触摸屏通常通过 I2C 连接在 Linux 输入子系统中可能是event0或类似。最可靠的方法是在第一次启动基础镜像后通过evtest或cat /proc/bus/input/devices来确认触摸屏设备节点。一个示例配置如下[core] # 取消注释以禁用屏幕保护 # idle-time0 # 取消注释以保持屏幕常亮 # dpms-onfalse [shell] # 设置背景色 background-color0x002040 # 使用 kiosk-shell 可以全屏运行一个应用适合 HMI # shellkiosk-shell.so [output] nameDSI-1 # 设置屏幕分辨率和刷新率reTerminal 屏幕是 720x1280 (竖屏) 或 1280x720 (横屏) mode720x128060 # 如果需要旋转屏幕可以使用 transform 选项例如旋转90度 # transform90 [input] # 配置触摸屏device 需要根据实际情况修改如 /dev/input/event0 namereterminal-touchscreen device/dev/input/event0 # 指定触摸屏的坐标变换如果需要旋转触摸坐标以匹配屏幕旋转 # calibration_matrix0 1 0 -1 0 1 0 0 1重要提示device/dev/input/eventX中的X不是固定的它取决于内核加载驱动的顺序。在生产环境中更好的做法是使用udev规则通过设备的属性如供应商ID、产品ID来创建静态符号链接例如/dev/input/touchscreen然后在weston.ini中引用这个符号链接。这需要额外的udev规则配方。4.5 构建 Qt 镜像并烧录测试更新build/conf/local.conf将MACHINE设置为reterminal并指定构建我们的 Qt 镜像cd ~/yocto-reterminal/build # 确保 MACHINE 设置正确 echo MACHINE reterminal conf/local.conf # 开始构建 bitbake reterminal-qt-image构建完成后烧录新的reterminal-qt-image-reterminal.rpi-sdimg到 SD 卡启动 reTerminal。如果一切顺利你应该能看到 Weston 桌面启动并且可以通过触摸屏与qt5everywheredemo交互。5. 深度定制与优化内核、驱动与启动速度当基础系统跑通后我们就可以进行更深度的定制以满足特定产品需求。5.1 内核配置与设备树覆盖reTerminal 的某些特定硬件如精确的屏幕参数、额外的 GPIO 功能可能需要调整内核配置或使用设备树覆盖Device Tree Overlay。添加自定义内核配置片段创建一个.cfg文件启用或禁用特定的内核模块。mkdir -p ~/yocto-reterminal/meta-reterminal/recipes-kernel/linux/files nano ~/yocto-reterminal/meta-reterminal/recipes-kernel/linux/files/reterminal.cfg例如增加 SPI 缓冲区大小或启用某个驱动# 增加 SPI 缓冲区大小 CONFIG_SPI_SPIDEVy CONFIG_SPI_SPIDEV_MAX_SIZE4096 # 启用某个传感器驱动 CONFIG_INV_MPU6050_IIOy然后创建一个bbappend文件来应用到linux-raspberrypi内核nano ~/yocto-reterminal/meta-reterminal/recipes-kernel/linux/linux-raspberrypi_%.bbappend内容# 添加我们的内核配置片段 SRC_URI file://reterminal.cfg FILESEXTRAPATHS:prepend : \${THISDIR}/files: # 将我们的配置片段合并到内核配置中 do_configure:append() { cat \${WORKDIR}/reterminal.cfg \${B}/.config }使用设备树覆盖如果 reTerminal 官方提供了.dtbo文件我们可以将其集成到 Yocto 构建中。通常需要将其放在meta-reterminal/recipes-bsp/rpi-firmware/files/overlays/目录下并修改rpi-firmware的配方来包含它。这是一个更高级的主题需要参考meta-raspberrypi中处理 overlays 的方式。5.2 系统服务与自启动应用对于 HMI 设备我们通常希望系统启动后自动运行我们的主应用程序。这可以通过systemd服务实现。创建你的应用程序配方假设应用名为my-hmi-appmkdir -p ~/yocto-reterminal/meta-reterminal/recipes-apps/my-hmi-app nano ~/yocto-reterminal/meta-reterminal/recipes-apps/my-hmi-app/my-hmi-app_1.0.bb编写配方内容定义如何获取源码本地文件、Git 等、编译和安装。然后创建一个systemd服务文件mkdir -p ~/yocto-reterminal/meta-reterminal/recipes-apps/my-hmi-app/files nano ~/yocto-reterminal/meta-reterminal/recipes-apps/my-hmi-app/files/my-hmi-app.service服务文件示例[Unit] DescriptionMy reTerminal HMI Application Afterweston.service Requiresweston.service [Service] Typesimple # 假设你的应用安装在 /usr/bin ExecStart/usr/bin/my-hmi-app Restarton-failure Userroot [Install] WantedBymulti-user.target在应用的配方中安装这个服务文件并启用它do_install:append() { install -d \${D}\${systemd_system_unitdir} install -m 0644 \${WORKDIR}/my-hmi-app.service \${D}\${systemd_system_unitdir}/ } SYSTEMD_SERVICE:\${PN} my-hmi-app.service SYSTEMD_AUTO_ENABLE:\${PN} enable最后在你的镜像配方如reterminal-qt-image.bb中添加my-hmi-app包。5.3 启动速度优化嵌入式设备对启动速度往往有要求。Yocto 提供了多种优化手段Initramfs与Initrd对于简单的系统可以考虑将根文件系统构建进内核Initramfs避免单独的根文件系统挂载延迟。但这会增加内核大小。Systemd 优化分析systemd-analyze blame输出禁用不必要的服务。在 Yocto 中可以通过DISTRO_FEATURES和IMAGE_INSTALL来裁剪服务。文件系统选择ext4是平衡性能和可靠性的选择。对于只读根文件系统可以考虑squashfs它压缩率高加载快。tmpfs可用于/var和/tmp等易变目录。并行初始化确保systemd的DefaultDependenciesno和After/Before关系设置合理允许更多服务并行启动。内核裁剪使用bitbake -c menuconfig virtual/kernel进入内核配置菜单移除所有不需要的驱动和模块生成一个更小的内核。优化是一个迭代过程需要结合systemd-analyze plot boot.svg生成的图表进行分析找出瓶颈。6. 常见问题排查与实战心得在 reTerminal 上构建 Yocto 的过程中我踩过不少坑这里总结几个最常见的问题和解决思路。6.1 屏幕不亮或显示异常这是最可能遇到的问题。症状系统似乎启动了串口有输出但 reTerminal 屏幕黑屏或白屏。排查检查内核日志通过串口reTerminal 有调试串口引脚连接查看内核启动日志关注drm、vc4、panel相关的信息。是否有加载失败或错误确认设备树确保使用的 DTB 文件正确。对于 CM4通常是bcm2711-rpi-cm4.dtb。检查config.txt中dtoverlay的配置。reTerminal 屏幕可能需要特定的 overlay例如vc4-kms-dsi-7inch或类似。你需要从 reTerminal 的官方资料中确认正确的 overlay 名称和参数。在 Yocto 中配置在reterminal.conf机器配置文件中可以通过RPI_EXTRA_CONFIG变量来追加config.txt的内容。例如RPI_EXTRA_CONFIG \n\ # 强制使用特定 DSI 显示参数\n\ dtoverlayvc4-kms-dsi-7inch\n\ # 如果需要旋转屏幕\n\ display_rotate1\n\ 检查 GPU 内存确保GPU_MEM设置足够如 128 或 256。过小的 GPU 内存可能导致帧缓冲区分配失败。6.2 触摸屏无响应或坐标错误症状屏幕显示正常但触摸没反应或者触摸点与显示位置不对应。排查确认输入设备节点在系统启动后通过ls /dev/input/by-path/或evtest命令找到触摸屏对应的eventX。检查是否有事件输出。Weston 配置确保weston.ini中的device指向正确的设备节点。考虑使用udev规则固定设备节点。坐标校准如果触摸有反应但坐标不对需要使用tslib进行校准。在镜像中安装tslib-calibrate启动后运行ts_calibrate进行五点校准。校准数据会保存在/etc/pointercal。你可以创建一个启动脚本在首次启动时自动运行校准或者将校准好的文件打包进镜像。内核驱动确认触摸屏的 I2C 驱动是否正确加载。检查内核日志中关于ft5x06、edt-ft5x06或goodix等常见触摸芯片驱动的信息。6.3 构建失败配方解析错误或下载失败症状bitbake命令执行失败报错关于parse或fetch。排查层依赖和路径仔细检查bblayers.conf确保所有层的路径都正确并且没有拼写错误。确保meta-reterminal的layer.conf语法正确。配方语法Yocto 的.bb和.bbappend文件对空格和制表符非常敏感。确保使用空格缩进而不是制表符。检查变量赋值和函数调用的语法。网络问题下载失败通常是因为网络连接问题或源地址不可用。Yocto 会从多个源如 GitHub、Kernel.org 等下载代码。可以尝试配置代理或者使用premirror功能将常用源码缓存到本地服务器。许可问题某些软件包需要接受许可协议。例如树莓派的 GPU 固件。你可能需要在local.conf中添加LICENSE_FLAGS_ACCEPTED commercial等。6.4 镜像过大症状生成的.rpi-sdimg文件远超预期。优化裁剪IMAGE_INSTALL仔细检查镜像配方中安装的每一个包移除所有非必需的包。使用bitbake -g image-name生成依赖图分析哪些包被引入。使用rm_work在local.conf中启用INHERIT rm_work这会在构建完成后删除每个配方的临时工作目录虽然不能减小最终镜像但能节省构建空间。压缩根文件系统考虑使用squashfs或ubifs针对 NAND Flash等压缩文件系统作为只读根文件系统。移除调试符号在local.conf中设置INHIBIT_PACKAGE_DEBUG_SPLIT 1和INHIBIT_PACKAGE_STRIP 0来移除调试符号但会使得问题调试困难。6.5 无线网络WiFi/蓝牙无法使用症状iwconfig看不到wlan0或蓝牙设备未出现。排查固件确保镜像中包含了正确的固件。对于 CM4 上的 Cypress CYW43455 芯片需要linux-firmware-rpidistro-bcm43455包已在我们的基础镜像配方中包含。内核配置确认内核配置中启用了CONFIG_BRCMFMAC用于 WiFi和CONFIG_BT_HCIUART及CONFIG_BT_BCM用于蓝牙。meta-raspberrypi通常已经配置好。设备树CM4 的 WiFi/BT 是通过 SDIO 和 UART 连接的设备树中需要正确启用。bcm2711-rpi-cm4.dtb应该已经包含。检查内核启动日志是否有brcmfmac和hci_uart相关的错误。用户空间工具确保安装了wpa-supplicant、iw、bluez5等工具。实战心得迭代构建不要试图一次就构建完美的最终镜像。采用迭代方式先构建一个最小能启动的系统甚至只是内核和 busybox通过串口确认基础功能。然后逐步添加图形、触摸、网络、应用。每步都测试能快速定位问题所在层。善用开发 shellbitbake -c devshell virtual/kernel可以进入内核源码目录进行手动配置和编译测试非常方便调试内核问题。维护自己的层将所有的自定义配置、补丁、配方都放在meta-reterminal层中。这样当上游的poky、meta-raspberrypi更新时你可以相对容易地合并更新并保持你的定制内容独立、清晰。版本控制将整个yocto-reterminal目录包括downloads和sstate-cache可以排除置于 Git 版本控制之下。这能完美复现每一次构建是团队协作和项目维护的生命线。为 reTerminal 构建 Yocto 系统是一个典型的嵌入式 Linux 定制过程涉及 BSP 适配、驱动集成、系统裁剪和性能优化。虽然入门有门槛但一旦掌握了 Yocto 的工作流你将获得对嵌入式系统前所未有的控制力能够打造出真正符合产品需求的、高效稳定的专属系统。这个过程本身就是对嵌入式 Linux 系统架构一次深刻的理解和实践。