板子到手那一周我基本没碰代码插上电灯亮了然后就不知道该干什么了。后来才发现小熊派 BearPi-HM nano 开发板这类跑轻量级物联网系统的模组真正劝退新手的从来不是业务逻辑而是前期那一堆看不见摸不着的准备工作环境装在哪、编译器从哪来、源码怎么拉、烧录工具认不认串口、日志为什么不打印。这些问题单个拎出来都不难可一旦交织在一起能让人从天亮折腾到天黑还找不到北。这篇是我自己踩完一圈坑后整理的前期准备笔记。它不讲框架、不讲 API只解决一个问题让你在最短时间内把一块刚拆封的板子变成一台能编译、能烧录、能看日志、能改代码跑起来的可开发设备。适合完全没接触过这类轻量级开发板的新手也适合从单片机转过来、第一次面对源码树 构建系统 交叉编译这套组合拳的人。文章里的参数、路径、步骤都是可复现的你照着敲基本能走通我知道的几个坑也会在对应位置直接标出来省得你重复踩。1. 开发板到手先别急着上电硬件盘点与认知地图很多人买板子的第一反应是插电看灯这没错但在动手之前花十分钟把板子的资源认一遍后面能省下好几个小时。原因很朴素你后面写代码、配置引脚、选外设、判断报错全靠对硬件资源的准确记忆。记错一个串口号或者把某个引脚当成普通 GPIO 去驱动编译能过、烧录能过跑起来就是不亮这种问题排查起来最耗神。BearPi-HM nano 这块板子的定位很清晰——一块为轻量级物联网系统教学与原型验证设计的 WiFi 开发板。它把主控、天线、USB 转串口、按键、指示灯、扩展接口、近场标签全都塞进了一张比名片略大的板子上属于出厂就能直接玩的形态。下面这张表是我自己整理的板载资源速查建议你也照着做一份贴在手边。资源项说明前期准备阶段要关注什么主控芯片集成 WiFi 的物联网 SoC2MB Flash、352KB SRAM、288KB ROMFlash 容量决定了你能塞多少代码2MB 听着不少扣掉系统和参数分区后留给应用的其实紧张无线能力2.4GHz WiFi注意它不带蓝牙别照着别的板子教程去配蓝牙服务USB 接口Type-C板载 USB 转串口芯片这是唯一的供电与通信入口电脑识别为串口设备用户按键一个 USER 键、一个 RESET 键USER 键可做普通输入RESET 键是烧录流程里的关键动作指示灯板载 LED接在主控某个 GPIO 上这是你第一个验证实验的对象扩展接口标准 E53 类扩展排针后期接传感器全靠它前期不用管但要确认排针没弯近场标签板载 NFC 标签芯片天线已集成手机贴上去能读到信息属于验证板子是否正常的旁路手段1.1 认准版本与丝印文档对不上的第一嫌疑人这块板子出过不止一个批次不同批次的丝印位置、按键布局、甚至 USB 转串口芯片型号都可能有细微差别。我手上这块的 USB 转串口是常见的那几款之一但我见过同好拿到的板子型号不同导致驱动装的不是同一个。这件事的后果很直接驱动装错设备管理器里就是一个带黄色感叹号的未知设备串口工具列表里一个口都没有你会以为是线坏了、板子坏了其实是驱动的事。所以拆封后第一件事是拿手机把板子正反面拍清楚重点拍三个位置主控芯片上的丝印、USB 接口旁边那颗小芯片上的丝印、以及排针旁的型号标识。照片存好出问题时对着丝印去查驱动比盲目试错快得多。丝印上的型号通常字体很小用手机微距或者放大镜看别靠猜。第二件事是确认你手上的教程版本和板子版本对不对得上。这类开发板的资料更新很快早期文档里的目录结构、编译命令、甚至工具名称在后期版本里可能已经变了。我的经验是优先看源码包自带的那份说明文档网络教程只当参考。因为源码包里的文档至少和代码是同一个时间点发布的而网络文章你永远不知道作者写于哪个版本。1.2 配件清单里那些隐形依赖盒子里一般就一块板、一根线有时候连数据线都不给足但真正的前期准备清单远不止这些。我列一下自己实际用到的东西一根靠谱的 Type-C 数据线。这是最容易翻车的配件。市面上大量 Type-C 线是只供电不传数据的充电线插上去板子的电源灯亮得很欢电脑那边却毫无反应。判断方法很简单换一根你确定能给手机传文件的线试试。一台 Windows 电脑。烧录工具基本是 Windows 下的绿色程序这一步绕不开。哪怕你打算用 Linux 编译烧录环节通常还是要回到 Windows。一个 Linux 环境。可以是虚拟机也可以是实体机或者云端主机后面单独讲选型。一张容量不大的 SD 卡或者一个 U 盘。用来在 Windows 和 Linux 之间倒腾文件虚拟机装了增强工具的话这步可以省。一部带 NFC 功能的手机。非必需但拿来快速判断板子是不是活的很好用。注意数据线的问题占比高得离谱。我统计过自己遇到过的板子没反应案例超过一半最后都归因到线材。前期准备阶段就把线材问题排除掉后面能少怀疑人生。2. 开发环境怎么选三条路的取舍与实操心法环境选型是前期准备里第一个真正的决策点也是分歧最大的地方。我见过三种主流做法各有拥趸下面把我实际用过的感受摊开讲。方案具体形态优点代价方案 AWindows 装虚拟机跑 Linux一台电脑全搞定资料互通方便快照能随时回滚编译吃内存虚拟机配置低了会卡USB 透传偶尔抽风方案 BWindows Linux 双系统性能无损编译飞快切系统麻烦一旦把 Linux 搞崩了恢复成本高方案 C纯 Linux 实体机或独立主机环境干净长时间编译稳定需要额外设备跨系统传文件要多一步我自己长期走的是方案 A理由很实在前期准备阶段你会反复折腾环境而快照功能让你敢于瞎搞。装错一个包、改坏一个配置文件回滚三十秒的事。双系统或者实体机出问题重装一次就是半天。至于性能编译这类轻量级系统工程量并不大只要虚拟机的内存和核心数给够体验和实体机差别不明显。2.1 虚拟机参数到底给多少才合适这个问题被问过很多次我的建议是给一个下限再加一点余量具体看你的宿主机配置内存虚拟机至少 4GB推荐 8GB。构建系统会并行拉起多个编译进程内存不够会直接触发 OOM报错信息往往是一句莫名其妙的internal compiler error或者进程被 killed非常难联想到是内存不足。CPU 核心分配宿主机物理核心数的一半到三分之二。给太少编译慢给太多宿主机自己卡。磁盘至少 60GB。源码树本身不算大但构建产物、工具链、系统更新加起来很占地方磁盘满了的表现是编译到一半突然写不进去。虚拟化引擎开启 BIOS 里的虚拟化支持虚拟机设置里勾选虚拟化 Intel VT-x/EPT 或 AMD-V/RVI否则跑起来会慢一个数量级。系统版本这块我建议选一个长期支持版本不要追新。原因很实际源码树里带的预编译工具链、脚本里的 Python 版本判断都是按当时的主流发行版写的。系统太新Python 默认版本跳到 3.10 以上一些老脚本会直接语法报错系统太老apt 源里连基础编译包都装不上。我实测比较稳的组合是长期支持版里偏中间的那个版本装完先别急着升级内核。2.2 环境搭建的完整落地步骤下面是我自己的一套从零开始的流程按顺序执行基本不会出错。第一步装系统并做第一次快照。系统装完先别装任何东西直接打一个纯净系统快照。这一步的价值在于后面无论怎么折腾崩了都能回到一个确定干净的起点而不是凭记忆去卸载一堆包。第二步换软件源并更新索引。默认源在国内网络下速度可能有波动换成就近的镜像源然后执行一次索引更新。这一步如果卡住或者报错先解决它别带着问题往下走。sudo apt update sudo apt upgrade -y第三步装基础编译依赖。这一串包看着多但基本都是一次性的sudo apt install -y build-essential gcc g make git curl wget sudo apt install -y zlib1g-dev libc6-dev-i386 lib32z1-dev sudo apt install -y python3 python3-pip python3-setuptools sudo apt install -y minicom picocom逐个说明一下为什么装build-essential提供 gcc/g/make 这三位主角zlib1g-dev是很多构建工具链的隐式依赖缺了会报找不到头文件两个 32 位兼容库libc6-dev-i386、lib32z1-dev是因为工具链里有 32 位可执行文件缺了会报 No such file or directory但文件明明就在那儿这个报错极具迷惑性minicom和picocom是串口终端二选一即可我两个都装着picocom 轻量、minicom 功能全。第四步处理 Python 版本。这一步是重灾区。构建脚本里有相当一部分依赖特定的 Python 小版本行为系统自带的版本如果不是脚本预期的那个会报各种ModuleNotFoundError或者语法错误。我的处理办法是先看清楚源码包说明里要求的版本然后在系统里准备对应版本并通过软链接把python、python3指向它。python3 --version # 如果和文档要求不符安装对应版本后调整优先级 sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.8 1提示不要用rm /usr/bin/python3然后重新软链这种粗暴做法。系统里不少工具依赖它删了可能连带出一堆问题。用update-alternatives管理多版本才是正路。第五步安装构建辅助工具。这类系统的构建流程一般由几层工具串起来底层是真正的编译器和链接器中间是构建系统生成器最上层是一个统一的构建入口脚本。你需要在系统里准备好中间那层通常叫scons、gn、ninja之类python3 -m pip install --user scons export PATH$HOME/.local/bin:$PATH那行export PATH特别关键。pip install --user会把可执行文件装到用户目录下的.local/bin而这个目录默认不在 PATH 里。表现出来就是明明装成功了敲命令却提示command not found。我当时在这卡了快四十分钟一度怀疑是 pip 装到了别处。记得把这条写进~/.bashrc不然每开一个新终端就要重新 export 一次。2.3 环境变量与目录规划给自己留条后路统一入口脚本要能找到工具链靠的是环境变量。不同版本要求不一样常见的几个是export PATH$HOME/.local/bin:$PATH export OHOS_ROOT_PATH$HOME/workspace export PATH$OHOS_ROOT_PATH/tools/bin:$PATH我一个一个说意图。第一条刚才讲过了是为了让 pip 装的工具能找到。第二条是给构建系统一个根路径它内部有些脚本会拼路径没有这个变量会报找不到某个目录。第三条是把工具链目录加进去这一步视你拿到的工具链形式而定——有的是压缩包直接解压有的需要通过脚本下载。这里有个经验不要把所有东西都堆在 home 目录根下。我的做法是建一个~/workspace里面分src源码、tools工具链、out构建产物、doc笔记。这样出问题时一眼能看出是源码的问题、工具链的问题还是产物的问题卸载重装也不会把无关文件带进去。新手最常见的状态是 home 目录下散落着三份不同版本的源码、两个工具链目录自己也说不清哪个在用。3. 源码与工具链从拿到代码到第一次编译通过环境就绪之后下一步是把源码拿到手并让它编译通过。编译通过这四个字是前期准备的分水岭——在它之前你面对的全是环境和配置问题在它之后你才真正开始接触代码。3.1 源码目录结构怎么读第一次展开源码树绝大多数人的反应是目录太多不知道从哪看起。其实这类系统级源码的组织逻辑是有规律的抓住几个关键目录就够了。目录作用你什么时候会进去applications应用层示例与业务代码写自己的功能前期大部分时间在这base基础能力比如外设访问、通信接口封装调用传感器、GPIO 等接口时查头文件build构建框架与入口脚本编译报错时定位是哪一层出的问题device具体芯片/板级的适配代码改引脚定义、启动配置时进来kernel轻量级内核前期基本不用碰了解存在即可third_party第三方组件用到某个库时再来找vendor厂商适配层产品配置在这切换目标产品配置、改分区时要用utils通用工具库偶发性依赖问题可能出在这前期最有价值的一条经验是拿到源码先花十分钟看根目录的说明文件和示例应用目录。示例目录里通常有几个现成的 demo构建配置也写好了你的第一个动作不是写新代码而是把最简的那个 demo 编译出来、烧进去、看它跑。这一步能验证整条链路包括工具链、构建配置、产物路径全都是对的。链路通了之后再写自己的东西出了问题就能确定是代码本身的事。3.2 一次完整的编译与产物解读构建入口一般是一个 shell 脚本不同版本名字不同常见的是build.sh。最基本的用法是直接执行让它按默认产品配置构建./build.sh如果构建框架带了统一命令行工具流程会是两步hb set # 交互式选择产品配置选到对应开发板那一项 hb build -f # 强制全量编译第一次编译建议就用强制全量不要图快用增量。全量编译能一次性暴露所有环境问题增量编译可能因为缓存绕过某些检查反而让问题更隐蔽。全量编译耗时通常在几分钟到十几分钟取决于虚拟机配置。编译成功的标志是产物目录里出现了一个.bin文件名字一般带allinone字样。这个文件就是把引导、系统、应用打包在一起的完整镜像烧录时选的就是它。同时构建日志末尾会打印一张内存占用表长这样text data bss dec hex xxxxx xxxx xxxxx xxxxx xxxxx这三个数字的含义值得讲清楚因为它们直接关系到你后面能不能加功能text是代码段放指令data是已初始化的全局和静态变量bss是未初始化的全局和静态变量运行时才分配。真正占用 Flash 空间的是text data而bss占的是 RAM。主控的 Flash 只有 2MB还要分给引导、系统、参数区留给应用的余量并不宽裕。我做过一个小实验往示例里加一段几百字节的字符串常量text段立刻涨上去。这意味着后面写业务代码时字符串和常量表要克制尤其别把大段日志文本直接写死在代码里。提示第一次编译完成后立刻把产物文件复制一份保存。之后改代码出了问题至少有一个已知能跑的镜像可以回烧用来判断是代码问题还是板子问题。3.3 常见编译报错从现象定位到根因编译阶段的报错看着吓人但前期遇到的其实集中在几类。我把印象最深的几个写下来。第一个command not found类。这基本只有两种可能包没装或者装了但不在 PATH 里。先确认包装没装再 echo 一下 PATH 看看。第二个No such file or directory但文件确实存在。这是 32 位库缺失的典型症状因为它报的文件其实是动态链接器。装那两个兼容库就能解决。这个问题特别浪费时间因为你所有的直觉都会指向路径写错了。第三个ModuleNotFoundError: No module named xxx。Python 依赖没装齐。注意用pip3 install而不是pip很多机器上pip指向的是 Python 2。第四个内存不足被系统杀掉报错可能只有一句Killed。看到这个词先看虚拟机内存不要去想代码问题。第五个权限问题。构建脚本里如果有chmod或者需要写系统目录的操作可能会被拦。我的习惯是不要用 sudo 跑整个构建只在明确需要装包的步骤用 sudo。用 root 跑构建会生成一堆 root 所有的产物文件后面用普通用户改代码就改不动了还得回头 chown非常烦。4. 烧录与串口让板子真正跑起来的三十分钟编译通过只是证明环境对了板子上跑的还是出厂固件。要看到自己的代码运行得走完烧录和串口这两步。4.1 驱动与工具准备回到 Windows 电脑第一步是让系统认串口。插上板子打开设备管理器看端口那一栏有没有出现新的 COM 口。出现了说明驱动正常记下号码没出现或者显示感叹号就要装驱动。装哪个驱动取决于板载那颗 USB 转串口芯片的型号这也是为什么第 1 节强调要拍丝印照片。驱动装好后把烧录工具准备好。这类工具通常是免安装的绿色程序解压就能用。工具界面上主要就那么几个控件端口选择、波特率、文件选择、连接按钮、发送按钮。4.2 烧录流程与那个必须按的复位键这是我踩坑最多的一环把正确顺序写清楚板子通过数据线连到电脑确认设备管理器里能看到 COM 口打开烧录工具端口选中对应的 COM 号波特率设为921600。这个值不是随便定的波特率越高烧录越快921600 是这类工具和芯片在烧录模式下能稳定工作的常用上限。如果烧录过程中频繁失败可以降到 115200 试代价是时间变长点选择文件选中刚才编译出来的那个allinone.bin勾选自动烧录Auto burn之类的选项这样后续反复烧录不用每次手动点发送点连接然后按一下板子上的复位键。第六步是整个流程里最容易漏的动作。原因在于芯片正常运行时串口是用来输出日志的只有在上电/复位的那一瞬间它才会短暂进入烧录模式等待握手。所以顺序必须是工具先进入等待状态再复位板子反了就永远握不上手表现是工具一直显示等待连接、进度条不动。烧录启动后进度条会走正常几十秒内完成最后提示成功。这时再按一次复位键程序才会真正开始跑。注意如果反复烧录失败先别怀疑板子。按这个顺序查串口号是不是选错了插拔之后 COM 号会变别的串口工具是不是还占着这个口串口是独占的最小化不算关闭数据线是不是只能供电最后才考虑板子。我遇到过一次就是因为开着串口助手没关烧录工具一直握不上手。4.3 串口日志怎么读烧录成功后打开串口工具连上同一个 COM 口波特率设成115200——这个是运行日志的波特率和烧录的 921600 不是一回事很多人在这里配错了看到一堆乱码误以为固件坏了。串口助手的基础配置115200 波特率、8 数据位、1 停止位、无校验、无流控。连上之后按复位正常会看到一串启动信息从引导打印开始一直打到系统启动完成中间会包含版本号、内存信息等。看到类似启动完成的字样并且后面有应用输出基本可以确定整条链路都通了。如果串口输出全是乱码九成是波特率配错改回 115200 就好。如果一片空白什么都没有先检查是不是没按复位有些板子上电即启动有些要手动复位再检查 TX/RX 是不是接反了用板载 USB 转串口的话不存在这个问题最后检查串口工具是不是真的打开了端口。4.4 第一个验证实验把示例改一行再烧一遍链路验证的最后一环我建议做一个最小改动实验而不是直接跑现成 demo。原因是跑 demo 只能证明能跑不能证明你改的代码能生效而后者才是开发的前提。具体做法找到示例应用目录里控制板载 LED 的那段代码把延时时间从默认值改成一个明显不同的值比如从几百毫秒改成几十毫秒或者两秒。改完重新编译重新烧录复位观察 LED 闪烁频率有没有变化。这个实验的价值在于它同时验证了四件事源码改动能被构建系统识别、编译产物被正确覆盖、烧录确实烧进了新固件、应用逻辑真的在跑。任何一环出问题现象都会不同——比如改了代码但频率没变很可能你烧的还是旧文件或者改的是另一个产品配置下的代码路径。这种改了一行但没生效的情况在后面开发中出现的频率比你想象的高提前建立这个判断习惯很有必要。如果板载上有近场标签芯片还可以拿手机贴一下能读出内容说明板子供电和基础外设正常这是个很快的旁路验证手段不依赖串口。5. 前期准备的排查速查表与几条真心话前面几节讲的是正确路径长什么样但实际操作中人是会走岔的所以这一节把我遇到过的典型症状集中列出来方便你对着现象找原因。症状最可能的原因处理方向插上板子电脑无反应设备管理器无新设备数据线只供电不传数据换一根确认能传文件的线设备管理器出现带感叹号设备USB 转串口驱动未装或装错型号看板载芯片丝印装对应驱动串口工具列表里没有 COM 口同上驱动层问题先解决驱动别在工具里找烧录工具一直等待连接没有按复位键进入烧录模式点连接后按复位烧录中途失败串口被其他工具占用波特率过高关掉串口助手降波特率重试串口日志全是乱码日志波特率配错改回 115200串口一片空白端口未真正打开未复位重新打开端口按复位编译报command not found包装了但不在 PATH检查并导出 PATH编译报文件不存在但文件在缺 32 位兼容库装对应兼容包编译被 Killed虚拟机内存不足加内存减少并行度改了代码烧录后行为没变烧的是旧产物或改错了代码路径确认产物时间戳确认产品配置构建产物一大堆属主是 root用 sudo 跑了构建chown 改回来之后不用 sudo 构建5.1 几个我反复验证过的小技巧给每个阶段打快照。虚拟机装好系统一个快照环境配好一个快照第一次编译通过一个快照。这三个快照能把绝大多数灾难性问题的恢复时间压到一分钟以内。我有一次误操作把一个环境变量改坏了导致构建系统死活找不到工具链折腾半小时没头绪回滚快照两分钟解决。日志不要只看最后几行。构建失败时真正的错误往往在中间最后几行可能是某个汇总脚本的失败提示。我的习惯是把构建输出重定向到文件然后用搜索去找error关键字./build.sh 21 | tee build.log grep -n -i error build.log | head -20保持一份能跑的镜像。每次编译成功都把产物另存一份命名带上日期。这个习惯在后期改动变多时价值巨大——出了问题先回烧旧镜像能跑就说明是代码问题不能跑就说明是环境或硬件问题一下子把范围砍掉一半。笔记比记忆可靠。我前期踩的坑当时的判断过程记得清清楚楚过两周就只剩好像遇到过。所以每解决一个问题,我就往笔记里写三行现象是什么、原因是什么、怎么解决的。这份笔记后来成了我排查问题时最先翻的东西。5.2 前期准备阶段最容易被低估的三件事第一件是理解构建链路的分层。很多人把编译当成一个黑盒动作一报错就懵。其实它至少分三层最上层是入口脚本负责读配置、设环境变量中间层是构建系统负责生成实际的构建指令最底层才是编译器和链接器。报错信息里的路径能告诉你在哪一层——如果报错路径在build目录下那是框架层的问题大概率是环境变量或配置如果报错路径在源码目录那才是代码问题。学会这个判断排查效率能翻倍。第二件是把能不能烧录和能不能编译当成两个独立问题。这两个环节用的是两套环境、两个系统、甚至两台机器故障域完全不同。我见过有人编译失败了十几次一直在改代码其实是环境问题也见过有人烧录不上一直在重装编译环境其实是串口被占用。分清楚边界就不会在两个域之间来回横跳。第三件是时间预算。我给自己定的前期准备时间是半天实际花了一天半。多出来的时间全耗在线材、驱动、Python 版本这三件事上。如果你打算周末开工建议把前期准备单独安排出去别把它和写第一个功能挤在同一天。带着环境还没通的焦虑去写代码写出来的东西大概率是错的。5.3 走到这里之后下一步往哪走当你能做到这几件事——编译成功、烧录成功、串口看到日志、改一行代码能看到行为变化——前期准备就结束了。这时候你手上其实已经有了一个完整的开发闭环后面无论是接扩展传感器、连无线网络、还是做低功耗实验都只是在这个闭环里加内容不会再有从零开始的茫然。我个人最推荐的下一个动作是把示例应用从头读一遍重点看两处一是它怎么引用外设接口的头文件二是它的构建配置是怎么写的。这两处是新手最容易卡住的地方——前者决定你能调用什么后者决定你的新文件能不能被编译进去。很多人写好了代码却编译不进去问题就出在构建配置文件里没登记新源文件这个坑几乎人人踩一次。至于扩展接口能接什么、无线怎么配网、近场标签怎么用那些是后面的事。前期准备阶段唯一的目标就是把板子 - 电脑 - 工具链这三者之间的连接关系彻底弄清楚弄清楚之后剩下的都是在这条已经打通的路上往前走。