到手一台香橙派5 Plus或者Max第一件事想干点啥多半是先配个中文环境再点个灯。这几乎是每个刚接触这块开发板的人都会踩的两个坎系统装好了但全是英文输入法不知道装哪个GPIO引脚看着密密麻麻但不知道哪根针是哪个点个LED半天没反应。我也看到最近满屏都是“ubuntu 24.04 shurufa”“ubuntu 24.04 怎么升级到24.04”这类搜索词说明好多人都在折腾这套环境。这篇文章不是从官网复制说明书而是把我实际折腾香橙派5 Plus跑Ubuntu 24.04 LTS的过程完整捋一遍从镜像下载、系统烧录、中文环境配置到GPIO控制LED闪烁和呼吸灯每一步都给出可复现的命令和代码。适合刚拿到板子想快速建起桌面环境的新手也适合要做GPIO小项目的进阶玩家参考。我会把关键原理、参数计算和踩过的坑一并说清楚尽量让你照着做就能成。1. 这套实战的完整思路与准备1.1 香橙派5 Plus/Max到底能干什么香橙派5 Plus搭载瑞芯微RK3588是一块8核处理器带NPU算力双2.5G网口最大支持32GB内存接口上有PCIe、USB3.1、HDMI 2.1等等。香橙派5 Max算是Plus的加强版主频更高散热和内存配置也更好。这样的硬件配置跑一个桌面版Ubuntu 24.04完全没难度日常当个小主机、做NAS、跑Docker、跑点AI推理都能胜任。但配置强归强软件生态才是关键。Ubuntu 24.04 LTS是2024年4月发布的长期支持版本对RK3588的支持已经相当成熟。很多朋友直接用官方给的镜像装完之后发现默认界面是英文看中文文档全是方块输入法更是无从下手。这倒不是说系统的功劳不够而是我们需要的是一套适合中文用户的完整环境配置思路。1.2 硬件和软件清单在开工之前先把要用的东西列清楚免得中途缺东少西。硬件方面香橙派5 Plus或Max开发板一块一个可靠的TF卡建议16GB以上C10/A2速度级别或者eMMC模块5V/4A或更高规格的USB Type-C电源适配器香橙派5 Plus官方建议是PD协议电源供电不足容易出现随机重启一台电脑用来烧录系统Linux、macOS或Windows都行LED二极管一个220Ω到1kΩ电阻一个杜邦线若干面包板一块如果需要看串口日志准备一个USB转TTL工具软件方面Ubuntu 24.04 LTS桌面版arm64镜像网上搜“ubuntu 24.04 lts 桌面版下载”注意选对架构一定要选arm64或aarch64版本不要下成x86的烧录工具Windows下可以用balenaEtcher或者Win32DiskImagerLinux下直接用dd命令SSH工具Windows上可以用MobaXtermmacOS/Linux直接终端一个能编辑代码的编辑器VSCode就可以1.3 方案选型为什么是Ubuntu 24.04而不是官方系统或其他发行版香橙派官方也提供了基于Debian的Orange Pi OS和Debian桌面版那为什么还要折腾Ubuntu 24.04我个人的体会是Ubuntu的社区资料太丰富了问题遇到报错基本都能搜到解决办法软件源里预编译的软件包多中文字体和输入法安装也方便而且24.04 LTS对RK3588的支持在主线内核里已经很成熟系统稳定性比早期版本好了很多。另外多说一句如果你用的是香橙派5 Plus其实也可以试试把旧版本从22.04原地升级到24.04命令就是sudo do-release-upgrade但我个人不推荐在生产环境下这么干还是干净安装最靠谱省得升级过程中依赖冲突。这里我会按全新安装来写。2. Ubuntu 24.04系统安装与初始化2.1 从下载到烧录三个常见坑一次避开先下载镜像。香橙派5 Plus官方下载页面或者Ubuntu官网都能找到适用于Orange Pi 5 Plus的24.04镜像。下载完第一件事是校验SHA256官方页面会提供校验值千万别跳过这一步。我试过不止一次下载中途断网导致镜像损坏烧录完成之后系统在启动阶段就崩溃排查起来非常头疼。校验命令在Linux下是这样echo 官方给的SHA256值 下载的镜像文件名.img.xz | sha256sum -c -输出OK就说明镜像完整。烧录方式就看你的目标介质了。如果用TF卡启动Windows下用balenaEtcher选镜像选卡一键完成Linux下更推荐用dd# 先用 lsblk 确认TF卡设备名假设是 /dev/sdb sudo dd if香橙派ubuntu24.04镜像.img of/dev/sdb bs4M statusprogress oflagsync convfsync这里有个容易踩的坑dd出来的设备名必须是你TF卡对应的那个千万别写错盘符把电脑硬盘给冲了那就欲哭无泪了。convfsync会让dd强制把数据落盘避免出现烧录完成但是启动不了的情况。如果你用的是eMMC模块烧录方式不一样不能在系统正在从eMMC启动时直接写入一般要用瑞芯微的RKDevTool进入MaskROM模式烧写或者先把系统写到TF卡再从TF卡启动后用dd把镜像写到eMMC设备。最简单的还是TF卡起步等系统跑通之后再考虑迁移到eMMC。2.2 首次开机与基础初始化TF卡插好接上网线插上电源开机。第一次启动会比之后慢一些因为要扩展根分区、初始化硬件耐心等一两分钟。Ubuntu 24.04的安装向导会引导你设置用户名密码、选择时区、配置Wi-Fi等。这里有个技巧在向导的语言选择页面如果你决定后面要彻底中文化那可以先选英文完成安装后面我提供切换方法当然也可以在向导里直接选简体中文但等系统装完你会发现中文界面只有一部分显示正常输入法大概率还是没有所以后面Step 3那一套还是逃不掉。如果手头没有显示器可以直接用SSH连进来。默认情况下香橙派5 Plus的Ubuntu镜像开了SSH服务先查一下开发板的IP可以用路由器的DHCP客户端列表或者用nmap -sn 192.168.1.0/24扫一下局域网。然后ssh 用户名开发板IP首次登录后第一件事就是更新软件源和系统sudo apt update sudo apt full-upgrade -y2.3 软件源优化与必需工具安装Ubuntu 24.04的默认源在国外国内访问速度可能不太理想建议换成国内速度更快的镜像站。改源之前先备份一下配置文件sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak24.04开始软件源配置从/etc/apt/sources.list换到了/etc/apt/sources.list.d/ubuntu.sources这个新格式文件。用你喜欢的编辑器打开它把里面的http://archive.ubuntu.com/ubuntu/或者http://ports.ubuntu.com/ubuntu-ports/这些地址替换成国内镜像源的地址。ARM架构下Ubuntu 24.04使用的是ports.ubuntu.com这个要注意。替换完成之后sudo apt update然后再安装基础工具sudo apt install -y git curl wget vim htop net-tools build-essential python3-pip到这里系统本身已经干干净净、可以正常使用了。但离“中文环境”还有几步要走。3. 中文环境配置全流程3.1 locale设置与安装中文语言包很多朋友直接搜“ubuntu 24.04 中文怎么设置”然后照着教程跑一遍locale-gen就以为完事了结果界面还是英文。根本原因在于你只是生成了locale但没有安装对应语言的翻译包。Ubuntu 24.04下需要明确安装language-pack-zh-hans命令如下sudo apt install -y language-pack-zh-hans然后看一下当前系统的localelocale如果输出里LANG不是zh_CN.UTF-8就手动修改全局环境变量。在Ubuntu 24.04桌面版上最直接的方式是写进/etc/default/locale文件sudo bash -c echo LANGzh_CN.UTF-8 /etc/default/locale sudo bash -c echo LC_ALLzh_CN.UTF-8 /etc/default/locale再执行sudo update-locale重启系统就能看到中文界面了。如果你不想重启可以不开新终端的情况下执行source /etc/default/locale但有些桌面组件还是得重启后才生效。这里多说一句如果在图形界面里想切换语言可以打开“设置 - 系统 - 区域和语言”在“语言”下拉框中选择“简体中文”然后注销重新登录。图形界面设置会自动生成上面那几个文件效果是一样的。3.2 中文字体真正解决“方块字”问题系统语言切成中文之后经常遇到一个问题浏览器里能正常显示中文但某些界面字体会变成一个个小方块或空白。这是因为系统里缺中文字体。Ubuntu 24.04自带的字体主要针对拉丁字符对中文支持有限。安装Noto CJK字体一步到位sudo apt install -y fonts-noto-cjk fonts-noto-cjk-extra安装完刷新字体缓存fc-cache -fv然后注销重新登录整个世界就正常了。如果你还想要微软雅黑类似的渲染效果可以安装fonts-wqy-microhei文泉驿微米黑虽然不算特别精良但胜在轻量老机器上用起来很流畅sudo apt install -y fonts-wqy-microhei浏览器里的中文字体也可以在设置里强制指定首选“Noto Sans CJK SC”或“WenQuanYi Micro Hei”。3.3 输入法框架fcitx5还是ibus这是中文环境里最容易被劝退的一步。Ubuntu 24.04默认输入法框架是IBus但国内用户绝大多数更推荐Fcitx 5原因很简单Fcitx 5在GTK和Qt程序下的兼容性都很好中文拼音的词库质量也更高候选词顺序更符合国内习惯。想一步到位直接上Fcitx 5。安装命令sudo apt install -y fcitx5 fcitx5-chinese-addons fcitx5-config-qtfcitx5-chinese-addons这个包包含了拼音和五笔输入法是必不可少的。装好之后还需要做两件事第一把Fcitx 5设为默认输入法框架。编辑环境变量文件sudo nano /etc/environment在文件里加上这两行GTK_IM_MODULEfcitx QT_IM_MODULEfcitx XMODIFIERSimfcitx如果你用的是Wayland会话可能不需要设这些但如果用的是Xorg会话这步必须做否则在GTK程序里呼不出输入法。第二设置开机自启动。Ubuntu 24.04桌面的“启动应用程序”里添加一条命令写fcitx5或者直接在终端里执行sudo cp /usr/share/applications/org.fcitx.Fcitx5.desktop /etc/xdg/autostart/重启之后右上角会出现一个小键盘图标用Ctrl空格就能切换中英文输入。按CtrlShift可以切换拼音和五笔。我实际用了几天Fcitx 5最明显的感觉是候选词条目的排版舒服模糊拼音的选项也藏得不深整体体验比IBus好不少。如果你是从Windows转过来的第一次呼出输入法时可能会觉得快捷键不太顺手可以在Fcitx 5配置界面里把切换键改成左Shift就跟微信输入法的习惯对齐了。3.4 终端与常用软件的字体调校中文环境不只包含系统界面和输入法终端里如果之前安装的是纯英文环境某些支持中文的程序可能在SSH会话中显示乱码。解决方法是确保SSH客户端的字符编码是UTF-8Windows的MobaXterm里默认就是UTF-8macOS终端也默认是UTF-8一般不用改。但终端的显示字体得换成支持中文的等宽字体。Ubuntu的GNOME终端设置里字体默认是“Monospace”这个字体族里如果没有中文fallback中文注释就会乱。建议把字体改为“Noto Sans Mono CJK SC”gsettings set org.gnome.desktop.interface monospace-font-name Noto Sans Mono CJK SC 12另外很多朋友在Ubuntu里装完VSCode写代码时中文注释显示为细条或者方块。VSCode里把终端的字体和编辑器字体都改成“Noto Sans Mono CJK SC”即可。注意编辑器字体和终端字体要分开设置在settings.json里加上editor.fontFamily: Noto Sans Mono CJK SC, monospace, terminal.integrated.fontFamily: Noto Sans Mono CJK SC, monospace到这里中文环境算是彻底搭建完成了。不管是桌面、文件管理器、浏览器还是代码编辑器都能正常显示中文并用拼音输入。4. GPIO与LED灯控制实操4.1 LED硬件连接与电路计算中文环境搞定接下来就是很多人最感兴趣的GPIO操作。从这里开始我们要真正跟硬件打交道了。先看香橙派5 Plus的40Pin排针。引脚定义和树莓派40Pin排针基本兼容但需要注意物理引脚的编号和GPIO内部的编号是两回事香橙派的引脚图可以在官方文档里查到。我们要点LED一般选择一个普通GPIO即可比如物理引脚7也就是GPIO4_C3这个引脚在系统里对应的编号要看GPIO控制器的寄存器计算这个我后面详细说。LED接法的基本电路是这样GPIO引脚 - 限流电阻 - LED正极 - LED负极 - GND。千万别把LED直接接到3.3V和GPIO之间也别跳过电阻否则电流过大会烧掉LED甚至损坏引脚。电阻的阻值怎么算GPIO输出高电平时是3.3V常见的红色LED正向压降约1.8到2.0V正常工作电流取10mA。根据欧姆定律R (3.3V - 2.0V) / 0.01A 130Ω手头常见电阻取220Ω或330Ω都很安全虽然亮度会稍微低一点但保护引脚更稳妥。我的习惯是用330Ω实测LED亮度足够肉眼清楚观察而且即使接线短路也不太容易烧引脚。接线顺序也很重要。先断电再接杜邦线接好确认无误后再上电。确认的标准是LED长脚阳极通过电阻接到GPIO短脚阴极接到GND不要接反。如果你用的是带板载电阻的LED模块那就省事了直接插引脚就行。4.2 GPIO控制工具链怎么选香橙派5 Plus跑Ubuntu 24.04控制GPIO的方式有几种但最容易踩坑的是网上搜出来的教程很多是树莓派专用的RPi.GPIO库在香橙派上根本不能用。香橙派5的GPIO控制是基于内核的gpiochip子系统推荐工具是libgpiod和配套的命令行工具。libgpiod是Linux内核官方GPIO用户空间API的核心库它直接跟/dev/gpiochip*交互不依赖特定的板卡SDK。只要内核支持GPIO字符设备接口就能用。安装方法sudo apt install -y gpiod libgpiod-dev python3-libgpiod如果要用C语言开发libgpiod-dev提供头文件和库如果Python开发装python3-libgpiod就够。另一个选择是香橙派官方的wiringOP它是对树莓派wiringPi的移植接口风格类似但对Ubuntu 24.04这种较新内核的支持时好时坏我试着编过一版编译步骤比较繁琐对于只点个灯的需求来说没必要。我建议直接用libgpiod干净、官方、跨板卡通用。4.3 用gpioset命令直接点亮LED先用gpioinfo看看系统里有哪些GPIO控制器gpioinfo正常会看到类似这样几个chipgpiochip0 - 32 lines: line 0: PIN_02 unused input active-high line 1: PIN_04 unused input active-high ... gpiochip1 - 32 lines: ...香橙派5的40Pin排针被分配到多个gpiochip上每个芯片管理32个引脚。你需要从输出中找到对应物理引脚的名字比如我们要用的PIN_07它会显示成类似这样line 3: PIN_07 unused input active-high假设PIN_07在gpiochip0的line 3上那么点亮LED的命令就是# 将gpiochip0 line3设为输出并输出高电平 gpioset gpiochip0 31熄灭gpioset gpiochip0 30注意不同批次的小板或者运行不同内核时引脚在gpiochip上的索引可能偏移所以别死记硬背务必先用gpioinfo查到正确编号再操作。我用香橙派5 Plus的Ubuntu 24.04官方镜像PIN_07在gpiochip0的line 3但换了另一个内核版本后变成了line 4排查了很久才定位到是编号漂移的问题。4.4 用Python控制LED闪烁和呼吸灯命令行点灯只能验证硬件是否正常要做出效果还得写代码。用Python操作GPIO安装好python3-libgpiod之后写一个闪烁脚本#!/usr/bin/env python3 import time import gpiod # 打开gpiochip0 chip gpiod.Chip(gpiochip0) # 拿到对应line对象这里以PIN_07为例 line chip.get_line(3) line.request(consumerled_blink, typegpiod.LINE_REQ_DIR_OUT, default_vals[0]) try: while True: line.set_value(1) time.sleep(0.5) line.set_value(0) time.sleep(0.5) except KeyboardInterrupt: pass finally: line.set_value(0) line.release()这是最基础的GPIO输出逻辑。但要提醒一下gpiod库的新版本API有变化老教程里的gpiod.LineRequest已经废弃上面这种chip.get_line()的写法在python3-libgpiod新版本下是正常的。实际运行时如果报module gpiod has no attribute LINE_REQ_DIR_OUT说明版本比较新需要改用gpiod.line_request(consumer...)方式具体可以参考官方文档。再进一步做一个呼吸灯效果。呼吸灯的关键是改变LED的亮度也就是改变PWM的占空比。香橙派5的硬件PWM可以配置在特定引脚上但配置过程需要操作设备树比较复杂。对于新手来说用软件PWM的方式也完全够用效果肉眼看上去很平滑#!/usr/bin/env python3 import time import gpiod chip gpiod.Chip(gpiochip0) line chip.get_line(3) line.request(consumerled_breath, typegpiod.LINE_REQ_DIR_OUT) try: while True: # 亮度渐强 for duty in range(0, 101, 2): line.set_value(1) time.sleep(duty / 10000.0) line.set_value(0) time.sleep((100 - duty) / 10000.0) # 亮度渐弱 for duty in range(100, -1, -2): line.set_value(1) time.sleep(duty / 10000.0) line.set_value(0) time.sleep((100 - duty) / 10000.0) except KeyboardInterrupt: pass finally: line.set_value(0) line.release()软件PWM的原理是在一个很短的时间周期里高电平和低电平的比例决定了灯的平均亮度。sleep的单位是秒duty / 10000.0在duty50时等于0.005秒也就是5毫秒一个周期大约10毫秒频率100Hz。LED在这100Hz下不会有明显的闪烁感人会看到稳定的亮度。如果频率太低比如20Hz眼睛就会明显看出闪烁所以注意别把周期调太长。如果你以后做项目确实需要硬件PWM比如驱动舵机或者调光灯建议去研究香橙派5的设备树overlay把PWM复用到需要的引脚上原理和树莓派的dtoverlaypwm-2chan类似。这块内容展开又是一大篇这篇文章里先点到为止。4.5 让LED控制脚本开机自启点灯脚本写好之后如果希望开发板一开机就运行这个脚本可以借助systemd服务。先给脚本加可执行权限chmod x /home/你的用户名/led_blink.py然后创建服务文件sudo nano /etc/systemd/system/led-blink.service内容如下[Unit] DescriptionLED Blink Service Aftermulti-user.target [Service] Typesimple ExecStart/usr/bin/python3 /home/你的用户名/led_blink.py Restarton-failure User你的用户名 [Install] WantedBymulti-user.target启动并设置开机自启sudo systemctl daemon-reload sudo systemctl enable led-blink.service sudo systemctl start led-blink.service如果想停掉服务再手动控制LEDsudo systemctl stop led-blink.service这个小技巧很适合做开机指示灯、状态指示灯一类的场景比用壳子里的系统LED灵活得多。5. 常见问题与排查技巧实录5.1 问题速查表在这套环境搭建和GPIO调试过程中我实际踩过不少坑整理成一张表方便你对照排查。现象可能原因解决办法系统启动卡在logo处镜像损坏或TF卡速度太慢重新校验镜像并烧录换A2级别TF卡中文界面显示方块缺少中文字体sudo apt install -y fonts-noto-cjk后刷新字体缓存系统语言是中文但输入法呼不出Fcitx5没有设为默认框架或环境变量没设确认/etc/environment里有XMODIFIERSimfcitx注销重登gpioset提示权限不足当前用户不在gpio组或设备节点权限不对sudo usermod -aG gpio 用户名注销重新登录gpiod找不到引脚内核版本不同导致引脚编号偏移用gpioinfo重新查询实际编号Python导入gpiod报错新旧API不兼容检查gpiod.__version__按版本调整代码写法LED不亮但系统正常接线方向反了或电阻过大检查LED正负极用万用表确认GPIO输出高电平风扇转速声音大温控策略未启用安装orangepi-config工具配置风扇模式5.2 几个容易踩的硬件坑GPIO调试过程中最容易烧硬件的操作就是把5V接到GPIO引脚上。香橙派的GPIO大部分是3.3V逻辑电平如果你用了一个5V输出的传感器模块直接怼到GPIO上轻则损坏引脚重则可能损坏整个SoC的GPIO控制器。如果需要跟5V设备通信必须加电平转换模块。另一个坑是电源问题。香橙派5 Plus在满负荷运行时整板功耗不低如果你用的电源适配器只是5V/2A的手机充电头系统运行时会出现莫名其妙的断电重启尤其是在GPIO控制外设增加负载的时候。官方推荐5V/4A以上我实际用的是5V/5A的PD电源从开机到全速编译都很稳定。还遇到过一种情况用面包板插杜邦线时线序看反了。面包板内部是横向连通的插错一列就会短接到旁边的电源引脚。网上很多LED点不亮的求助帖最后都是接线错误。建议第一次接线前用万用表的通断档测试一遍各插针和排针之间的导通关系别上来就通电。5.3 GPIO权限问题背后的原理用普通用户跑gpioset时提示Permission denied这个问题很典型原因也不难理解/dev/gpiochip*设备节点默认归属root用户普通用户没有读写权限。解决办法有两个。临时方案是给设备节点加权限sudo chmod 666 /dev/gpiochip0但重启之后权限会重置每次都要执行。正规做法是把你的用户加到gpio组sudo usermod -aG gpio 用户名如果系统里没有gpio组就先创建一个sudo groupadd gpio然后还要确保udev规则把/dev/gpiochip*的组设为gpio。Ubuntu 24.04默认自带/etc/udev/rules.d/下相关的GPIO权限规则如果你用的是官方镜像一般不用额外配置加到gpio组、重新登录就能直接用。收尾分享几个我自己的操作习惯这套流程跑完之后香橙派5 Plus对我来说就不再是一块“开发板”了而是一台可以日常使用的Linux主机。中文环境稳了输入法顺手了GPIO也能自由控制后面再去接传感器、做自动化基础就都打牢了。再分享一点实际操作中的体会调试GPIO时我习惯一次只碰一根线改一根线测一次。不要一口气把LED、按钮、传感器全接上再上电一旦出问题根本不知道是哪个环节引起的。先把单颗LED点亮确认引脚、权限、代码整条链路没问题再逐步加复杂度。这个做法看着慢实际上排查问题最快。如果你用的是香橙派5 Max硬件引脚定义和5 Plus是一样的这套流程可以完全照用。后续你还可以把Python脚本换成C语言基于libgpiod重写响应更即时或者接一个温湿度传感器结合cron定时采集数据做成一个简易的环境监测站。写这篇文章的时候我最想传达的是开发板玩得转的核心不是某个特定命令而是遇到问题时能顺着“硬件 - 系统 - 软件”的链路一层层定位。照着这篇文章把基础环境跑通一次后面你就有自己的排查直觉了。
