1. 这三板斧到底是什么为什么从它开始做OpenHarmony开发有一阵子的朋友大概都有过这种体验板子拿来系统刷进去屏幕亮了然后……下一步该干嘛日志怎么看程序跑飞了怎么定位外设没反应是驱动问题还是硬件问题新手很容易卡在这一步觉得系统跑起来了就算完事真到要调自己的第一个硬件业务时才发现连门都摸不着。我这套《万物智能之开源鸿蒙OpenHarmony系统实战开发系列教程》写到硬件调试这一篇核心就是想把这层窗户纸捅破。所谓三板斧指的不是什么玄乎的东西就三件事看日志、进Shell、查设备树。听起来简单但你把这三件事做扎实了一个硬件问题从出现到定位基本八九不离十。为什么强调三板斧而不是十八般武艺因为OpenHarmony和传统的Linux开发调试有个很大的不同它有自己的用户态框架、自己的硬件访问接口、自己的编译打包体系很多传统思路不能直接搬。你拿Linux那套dmesg strace的惯性来调OpenHarmony大概率会被它自己的hilog、hdc、设备树机制绕得晕头转向。所以把这三板斧磨利了反而比什么花哨工具都顶用。这篇内容适合谁两类人一是刚接触OpenHarmony、手里有块RK3566/RK3568开发板但不知道从哪下手的新手二是从嵌入式Linux转过来、想快速对齐OpenHarmony调试思路的老手。我会尽量用实际场景讲不整虚的。2. 第一板斧日志系统问题定位的第一现场2.1 hilog不是logcat也不是dmesg你得重新理解先说结论OpenHarmony的日志系统叫hilog它不是安卓的logcat也不是Linux的dmesg它是一套独立设计的分级日志框架。很多人拿到板子第一件事就是敲dmesg然后发现输出寥寥无几甚至什么都没有就开始怀疑系统是不是有问题。其实不是OpenHarmony把内核日志和用户态日志做了区分内核信息还在只是默认的查看方式变了。你要看内核日志得用hilog的底层能力或者直接查看/proc下的节点而不是指望dmesg给你全部答案。hilog的基本用法我用得最多就这几个hilog # 实时输出全部日志 hilog | grep 关键字 # 过滤关键字 hilog -z 500 # 输出最近500条历史日志 hilog -e # 只输出错误级日志这里有个细节默认情况下hilog的输出量非常大尤其是系统刚启动那会儿各种服务初始化日志像洪水一样。你直接裸敲hilog基本啥也看不清。我的习惯是先敲hilog -z 200看最近200条了解当前系统的实时状态然后再用grep去精确过滤。说到过滤这里有个坑hilog的grep和Linux终端里的grep用法不太一样。你直接hilog | grep xxx在某些版本上会提示参数不对因为它自己内置了一套过滤语法。官方推荐的方式是hilog -x 关键字 # 按关键字过滤 hilog -e # 错误级别 hilog -D 0x1234 # 按domain过滤其中-D这个参数挺有用domain是OpenHarmony日志系统里的域概念比如你在代码里写了HILOG_ERROR(APP_DOMAIN, xxx)那个APP_DOMAIN就是你自己的域ID。调试自己代码的时候先给自己代码定义一个独特的domain值然后hilog -D精准过滤其他系统噪音全屏蔽掉。提示在开发板上敲hilog之前先确认你的用户权限。很多系统镜像默认的shell用户权限有限某些domain的日志需要root权限才能看。遇到permission denied别慌切到root或者用hdc shell的root模式就行。这一点我会在后面Shell那部分详细说。2.2 日志级别和格式一眼看出问题在哪hilog的每一条日志都会带级别标识从低到高依次是DEBUG、INFO、WARN、ERROR、FATAL。实际调试中我建议大家养成先看ERROR和FATAL再看WARN最后才翻INFO的习惯。原因很简单OpenHarmony系统服务多、组件杂INFO级别的日志量巨大里面大量是正常启动初始化完成这类安抚人心的消息看多了容易麻痹。反而是ERROR和FATAL虽然也会有一些非致命的错误比如某个服务尝试加载一个不存在的配置但绝大多数情况下第一现场的线索就藏在这里。我说一个我自己的案例。有次一个外接的温湿度传感器模组I2C通信时好时坏。一开始我满屏翻日志看到什么i2c transfer timeout之类的ERROR但具体是哪个驱动报的、哪个地址访问超时光看日志觉得很模糊。后来我打开hilog按domain过滤再配合-e只看错误级一层层剥下去才发现是这个传感器在连续读取时驱动对总线忙状态的重试机制有bug重试三次就放弃了用户态看起来就是偶尔读到偶尔读不到。所以日志不光是看有没有报错还要看报错的上下文。先定位domain再定位具体的代码文件或服务顺着调用链一路摸下去这个习惯能帮你节省大量时间。2.3 日志刷屏怎么办临时降级与定向过滤OpenHarmony跑起来之后尤其是一些开发板公版镜像自带的应用和服务特别多日志刷新速度快到怀疑人生。这里有两个实用技巧强烈建议收藏。第一个是临时降低日志输出级别。你可以通过hilog的配置接口把某个domain的日志级别临时提高比如只输出WARN以上的这样INFO和DEBUG直接被吞掉屏幕瞬间清净。这个操作只对当前运行期有效重启后恢复默认hilog -G 0x1234 -l WARN # 把domain 0x1234的日志级别临时调到WARN第二个技巧是利用hilog的持久化能力。有些问题不是实时复现的你不可能一直盯着屏幕。这时候可以先开好持久化日志指定文件大小和滚动策略然后去复现问题完事后再把日志导出来慢慢分析hilog -w core -f /data/log/hilog -m 1024 -n 10 # 按core模式持久化单文件1024K滚动10个文件导出的日志是二进制格式不能直接cat看需要用hilog -x在板子上回放或者用PC端的工具解析。刚开始用的时候我栽过这个跟头拿着文件在PC上翻半天全是乱码。后来学乖了直接在板子上执行回放hilog -r -f /data/log/hilog这个小细节估计能帮你少走很多弯路。3. 第二板斧Shell与hdc命令行的手术刀3.1 hdc的连接方式与权限模型OpenHarmony的调试命令通道叫hdcHarmonyOS Device Connector对标的就是安卓的adb。它支持两种连接方式USB连接和网络连接。USB连接最简单开发者板用USB线连电脑然后hdc list targets看设备在不在。网络连接一般用于设备已经部署在现场、不方便插USB的场景先在板子上启动hdc服务端并指定端口然后PC端执行hdc tconn 192.168.1.100:8710连上之后hdc shell就能进到板子的命令行。关于权限这里必须多说两句。hdc shell进去默认是普通用户还是root取决于系统镜像的配置。很多公版OpenHarmony镜像默认是非root但会提供一个hdc shell加su提权的途径。我碰到的不少新手上来就hdc shell然后敲各种操作被拒开始怀疑系统是不是坏了。其实只要先执行一下hdc shell su基本上大多数调试操作都能解开权限限制。不过要注意加了su之后你是在root环境里操作有些命令的路径、环境变量和安全策略跟普通用户不一样遇到诡异的command not found可以先echo $PATH看看别急着怪系统。3.2 在Shell里快速巡检硬件状态OpenHarmony的设备节点体系和Linux同源主要都在/dev和/proc下面。拿到一块新板子我建议你按下面这个顺序过一遍几秒钟就能对硬件状态有个基本判断。第一步是看系统基本信息和CPU负载cat /proc/cmdline # 内核启动参数 cat /proc/cpuinfo # CPU信息 uptime # 系统负载第二步是瞄一眼内存占用free -m第三步是检查关键外设节点是否存在。这一步很关键因为OpenHarmony的硬件访问很多是基于HDFHardware Driver Foundation框架的。一个外设驱动如果加载失败可能不会立刻导致系统崩溃但对应的设备节点就不会出现在/dev/hdf/目录下。比如你想看I2C设备有没有被认出来ls /dev/hdf/ | grep i2c ls /dev/i2c-* 2/dev/null如果节点不存在那就说明驱动加载或设备树解析环节出了问题这正好衔接上第三板斧的排查思路。实用技巧在hdc shell里tab键自动补全有时候不好用跟你电脑上的终端体验有差距。这是正常现象别被影响心态。实在记不住路径就多用ls和find去摸找到之后再固化到自己常用的命令清单里。3.3 Shell里改配置、点LED、读传感器一套流程走通调试硬件不能光看得能动。我举个例子你要验证GPIO点灯功能在OpenHarmony里最直接的办法就是通过shell操作GPIO的sysfs节点。如果你的内核开启了GPIO sysfs支持可以这样操作echo 89 /sys/class/gpio/export echo out /sys/class/gpio/gpio89/direction echo 1 /sys/class/gpio/gpio89/value这个89是GPIO编号具体怎么算出来的不同芯片平台规则不一样RK系列一般在设备树里有对应的gpio-bank-pin映射关系换算公式也能在芯片手册里找到。实操中最好对照原理图和数据手册算准别瞎试。还有一个更OpenHarmony原生的玩法是用hdf的shell工具去操作。你可以先hdc shell进去找到HDF对外暴露的测试工具通常在/vendor/bin/下名字带hdf用它们直接调驱动接口比如给某个I2C设备写一个寄存器、读一段数据出来。这种操作方式比直接改sysfs节点更贴近OpenHarmony的驱动模型调试驱动问题的时候尤其好用。不过说实话我个人在早期阶段更推荐先用Linux内核自带的sysfs方式快速验证硬件通不通等确认硬件没问题了再去调HDF驱动的适配层。分两条线走能极大减少到底是硬件坏了还是驱动没写好这类无谓的争论。4. 第三板斧设备树排查硬件拓扑的地图勘误4.1 设备树为什么总是背锅OpenHarmony的硬件平台适配很大程度上依赖于设备树Device Tree。设备树描述了开发板上有什么硬件、接在哪个控制器下、用哪个中断、寄存器地址范围是多少。驱动通过设备树拿到这些参数才能正确地去操作硬件。但设备树恰恰也是新手最容易踩坑的地方。一方面同一颗芯片往往有多个厂商做的开发板比如RK3568市面上就有好多家不同的板子它们的外设连接可能都不一样另一方面OpenHarmony的版本迭代非常快不同分支、不同版本的设备树文件差异很大。网上搜RK3568设备树到底该选哪个一搜一大片求助帖这确实是个很典型的问题。我的建议先别管版本细节先从板厂的出厂SDK入手。一般开发板厂商都会提供对应的OpenHarmony适配包里面带了一份这个板子能正常跑起来的设备树。以此为基准你要做的是理解它、修改它而不是从头写一份。从头写设备树不是不行但复杂度完全不在一个量级新手很容易在各种细微的时序和中断配置上折腾到怀疑人生。4.2 快速定位设备树配没配的思路排查设备树问题我总结了一套三步法。第一步是在系统启动日志里找线索。OpenHarmony启动时内核和HDF框架会解析设备树某个节点解析失败、某种属性缺失很多时候启动日志里就有warning。执行hilog -z 3000 | grep -i dtb\|device-tree\|fdt\|hdf如果看到类似failed to get property之类的关键字基本可以确定问题出在设备树解析阶段。第二步是确认实际生效的设备树文件。OpenHarmony会把编译后的dtb要么打进boot分区要么打包进某个image里。你要先确定系统当前用的到底是哪个dtb。一个比较笨但可靠的方法cat /proc/cmdline看里面有没有显式指定dtb文件名或者用ls /vendor/etc/查看有没有散落的dtb文件。如果没有显式指定那就是固件默认带的那一份想改的话得重新编译打包固件。第三步是拿已知可用和当前出问题的配置做差异对比。比如同一个RK3568平台出厂镜像能亮屏、你改了设备树之后屏幕黑了那就把你改动的地方逐项对比回去重点检查电源域和GPIO的默认电平对不对时钟频率和时钟源选对没有中断号和中断触发方式是不是匹配驱动里写死的逻辑这套方法听着保守但真的能解决绝大多数改了设备树之后硬件不工作的问题。4.3 修改设备树后的编译打包与验证闭环改设备树不是改完就完事你得能把它编进固件里再烧录验证。这里我踩过不少坑说几个关键点。OpenHarmony的编译打包用的是hb工具链。假设你改了某个板级的dts文件通常的流程是hb build -f # 全量编译首次或者改动较大时 hb build # 增量编译编译产物一般在out/product/packages/phone/目录下里面有各种镜像文件。如果你只改了设备树理论上只需要替换对应的image再烧录即可但实际操作中OpenHarmony的打包逻辑有时会把多个模块绑定在一起所以我会习惯性地重新生成整个升级包然后整包烧录彻底避免烧了个寂寞的尴尬。验证的闭环也很重要。收到新设备我的习惯是默认固件先开机确认板子出厂状态是好的备份默认固件和默认设备树留作对照把目标功能比如某个MIPI屏幕的配置加上去重新编译烧录如果出问题先用前三步排查再不行刷回默认固件验证硬件是否完好这样一套流程下来硬件问题、驱动问题、配置问题基本都能区分清楚。硬件的锅、软件的锅、还是你自己改配置改出来的锅一目了然。5. 实战演练从拿到一块陌生RK3568板子到外设点亮5.1 上电前的检查事项别急着通电这一节我用自己的经验串一遍完整流程。拿到一块新的RK3568开发板我第一件事不是急着上电而是看原理图和用户手册。重点看三处供电方式Type-C还是DC接口电压电流范围是多少、串口调试引脚在哪这决定了你能不能看到启动日志、是否带屏幕/触摸等外设接口影响后续功能验证的步骤。确认之后接好串口一般是USB转TTL波特率通常是1500000注意是1500000不是115200这是RK平台一个容易忽略的细节然后再上电。上电的同时在PC端打开串口终端准备抓启动日志。这里插一句串口转接板的质量真的会影响调试体验。便宜的可能丢字节、乱码甚至是电平不匹配导致完全没输出。我手头常备两三根不同方案的USB转串口线遇到乱码先换线排除免得在错误的方向上浪费时间。5.2 串口日志里挖出选哪个设备树的答案很多人在网上纠结RK3568设备树怎么选其实启动日志就会告诉你答案。上电后串口输出中一般会有类似Kernel command line: ... root/dev/mmcblk0p5 ...或者更直接的信息打印出当前使用的dtb文件名。如果日志太快刷过去了可以回放串口工具保存的文件搜索dtb、fdt、model等关键字。/proc/device-tree/model这个节点也很有用它会直接显示当前设备树描述的板卡型号。如果你烧录的镜像支援多个板型但实际生效的model跟你的板子对不上那外设配置大概率是不对劲的。cat /proc/device-tree/model通过这个简单命令划定了设备树范围再配合厂商提供的那份默认配置做差异分析基本就能解决设备树到底选哪个的核心焦虑。5.3 外设点亮全流程记录从确认I2C地址到应用层读取拿一个典型的I2C外设比如温湿度传感器举例把三板斧串起来走一遍。板子上电后先看日志确认I2C控制器有没有正常注册。OpenHarmony下可以用hilog -z 500 | grep i2c看看有没有类似i2c-0、i2c-1的注册信息。然后查设备树确认外设节点挂在哪条I2C总线上、设备地址是多少。接着在Shell里用i2c工具直接探测。OpenHarmony的系统镜像里通常有i2c-tools的移植版本类似Linux里的i2cdetect你可以i2cdetect -y 3 # 扫描i2c-3总线上的设备地址看到有设备响应比如0x38说明硬件链路是通的。I2C不通那是地址错了、总线没配对、还是设备没上电这里面就可以用我之前说的日志分级和Domain过滤去细查。硬件链路确认通了之后再回到应用层。OpenHarmony里访问I2C设备推荐走HDF框架提供的API而不是直接操作设备节点。好处是驱动框架帮你做了权限管理、并发控制和设备管理应用代码更健壮。你可以在自己的业务代码里创建一个HDF I2C客户按文档流程打开设备然后通过I2cRead、I2cWrite等接口读取传感器数据。整个过程就是这样日志确认链路、Shell探测地址、设备树核对配置、应用层调接口验证。三板斧并不是孤立的它们之间是一条完整的侦查链。6. 常见翻车现场与排查速查表6.1 现象一串口完全没有输出先确认串口线接线是否正确TX接RX、RX接TXGND共地波特率对不对RK平台常见1500000个别板子调试口可能是115200USB转串口芯片驱动装了没设备管理器里能不能看到串口号如果以上都正常尝试按一下板子的复位键看有没有瞬间输出极少数情况板子的调试串口默认被复用为其他功能需要改动跳线或进入MaskRom模式6.2 现象二能进Shell但某些节点不存在确认对应硬件在设备树里有没有配置确认驱动有没有编进内核或作为独立模块加载查看hilog是否有HDF init failed之类的报错用hdc shell的root模式执行ls /dev/hdf/有些设备节点只在root视角下可见6.3 现象三改了设备树后系统起不来别慌先确认是不是设备树语法错误用dtc工具做一次反编译检查排查新增节点里的引用是否完整clocks、interrupts、pinctrl有没有写全如果是时钟或电源域配置问题启动日志通常在非常靠前的位置就会报错抓串口日志时别漏了早期输出养成小步修改、快速验证的习惯一次只改一个功能点不要一次性堆一大堆改动6.4 现象四编译打包后烧录功能没有任何变化确认烧录的镜像里包含你修改的那部分在板子上直接cat对应dtb或配置节点对比内容是不是编译缓存导致旧产物被复用适当执行clean后重新编译烧录分区对不对设备树改动可能需要烧boot分区或者单独的dtb分区不是只烧system就行问题排查速查表问题现象优先排查点常用命令串口无输出接线、波特率、驱动、跳线串口工具自检系统无法启动设备树语法、电源时序、早期日志串口抓启动日志外设节点缺失设备树配置、驱动加载ls /dev/hdf/、hilog -z | grep hdfI2C探测不到设备地址错误、上拉电阻、总线编号i2cdetect -y 总线号日志刷屏严重Domain过滤、级别提升hilog -D 0x1234 -l WARN应用层读不到数据HDF接口参数、权限、节点路径cat /proc/device-tree/model7. 从会用到顺手几个经验层面的补充最后一篇不只讲操作我来补充一些不容易写到官方文档里的体会。第一OpenHarmony的调试和Linux有个最大的不同就是分层感更强。内核一层、HDF驱动一层、系统服务一层、应用一层每一层都有自己的日志输出和运行机制。这既是学习门槛也是调试的抓手。出了硬件问题先问自己我的问题发生在哪一层如果连应用都还没跑到就别盯着应用代码去查。第二设备树选择困难症的真正解药是维护一个板级差异记录本。每拿到一块新板子把model信息、关键外设地址、改了哪些设备树节点、踩过什么坑全部记录下来。下次再碰到同样芯片的不同板子拿出来对比几分钟就能定位问题。这个习惯比任何工具都管用。第三调试三板斧本质上是一种探测-确认-验证的思维模型。日志负责探测Shell负责确认设备树负责验证。这种思路不局限于OpenHarmony做任何嵌入式系统、任何硬件平台这套模型都能通用。你建立了这个底层能力之后具体命令和工具的变化都只是皮相换个平台照样能快速上手。现在再回头看网上那些RK3568设备树到底选哪个的求助帖你其实已经有了一套完整的解题思路先看启动日志确认当前用的什么设备树再对照厂商出厂配置和你的板子差异最后小步修改、快速验证。比单纯等别人给一个标准答案要靠谱得多。我自己当初也是从一脸懵的状态走过来的当时就觉得OpenHarmony这个系统看着跟Linux挺像真下手调试的时候处处是新的规则和坑。但把这硬件调试三板斧用熟之后整个人的调试效率提升了一个量级硬着头皮啃源码、翻文档的时间明显少了。希望你也能从这篇里找到自己的切入点少走一些我当年走过的弯路。