1. 先想清楚这块小熊派 BearPi-HM nano 到底要解决什么我第一次拿到小熊派 BearPi-HM nano 这块板子的时候第一反应是这么小一块能跑什么。后来在它上面折腾了几天从环境装到点灯再到把温湿度数据通过 Wi-Fi 传出去才慢慢理解这块板子的定位——它是那种典型的麻雀虽小、五脏俱全的入门级物联网开发板核心用的是 Hi3861 这颗面向物联网的 Wi-Fi SoC跑的是轻量级开源物联网操作系统。这篇东西我不打算写成官方文档的翻译而是把我自己在前期准备这个阶段踩过的坑、做过的取舍一条条摊开讲。先说清楚前期准备这四个字到底包含多少东西。很多人包括两个多月前的我会下意识觉得前期准备无非就是装个软件、插根线。实际上对这块板子来说前期准备至少横跨三块硬件层面的开箱自检和供电、串口链路主机层面的驱动与烧录工具以及代码层面的 Linux 编译环境、交叉工具链和源码仓库。这三块任何一块没弄利索后面写代码时就一定会莫名其妙地卡住而且报错往往还不在你怀疑的方向上。所以这篇文章面向的读者很明确刚拿到板子、想跑通第一个例程但还在环境里打转的新手以及之前玩过 STM32、Arduino想切过来试试这套开源物联网系统、但对它的构建体系还不熟的人。我会把为什么这么选、为什么要装这个东西讲透而不只是给一堆命令让你复制——因为命令谁都会抄但环境一出错能不能自己定位问题靠的是理解每一层在干嘛。这块板子的价值点在于它把 Wi-Fi 联网能力、一颗够用的主控、一套标准扩展接口压缩到了一个非常小的成本区间里。它不追求算力也不追求外设花哨它追求的是用最低的门槛让你把设备联网这件事完整走一遍。理解了这一点你就明白前期准备里那些看起来繁琐的步骤其实都是在为能联网、能烧录、能调试这条主线服务。2. 硬件开箱与环境认知别急着上电2.1 板载资源逐个数先建立一张地图拆开包装之后第一件事不是插线而是把板子上的东西认全。小熊派 BearPi-HM nano 这块板子的布局相对紧凑但该有的都有主控是 Hi3861板载一颗用户可编程的 LED一个复位按键RESET一个用户按键USER一组按 E53 标准做的扩展接口以及一套 USB 转串口电路。USB 口既负责给板子供电也承载了串口通信这条最重要的调试通道。这里我要特别强调 E53 接口。它是这个系列比较有辨识度的设计本质是把一组 GPIO、电源、地按固定顺序引出成一个标准化排座好处是你后面接温湿度、光照、继电器这类传感器模块时不用每次对着原理图数针脚插上去就能用。对新手来说这省了大量查手册的时间但也埋了个小坑扩展模块的供电能力和电平要跟板子匹配有些模块功耗偏大直接从这个接口取电会导致板子复位或者 Wi-Fi 连不上这个后面排查问题时会再提。Hi3861 这颗芯片的资源你要有个心理预期它的片上 SRAM 只有几百 KB 量级外挂的 SPI Flash 也就在 2MB 上下主频 160MHz 左右。这个配置放在今天的手机芯片面前不值一提但跑一个轻量级实时操作系统、做传感器采集和 Wi-Fi 上报是绰绰有余的。关键在于你要接受一个现实——它跑不了大型框架写代码时要精打细算内存这也是为什么它的开发模式更接近传统嵌入式而不是应用层开发。2.2 上电前的自检清单与供电方式的取舍我见过不少人拿到板子直接怼上电脑 USB 口就开始折腾结果板子时好时坏。上电前有几件事值得花两分钟确认目视检查焊点和排针尤其是 USB 座和排针附近有没有连锡、虚焊这类问题在低价板子上偶有出现。确认 USB 线是数据线而不是纯充电线。这是最容易被忽略的一条很多随手抓来的线只有电源两根插上去板子灯亮但电脑根本识别不到串口你会以为是驱动问题其实是线的问题。优先用电脑的 USB 口直接供电不要一上来就接大功率扩展模块。等串口能正常通信、系统能正常启动之后再接外设。供电这块我个人的经验是调试阶段就用 USB 供电最省事因为串口和供电是一根线解决减少了变量。等你接了多个扩展模块、发现板子偶尔重启时再考虑换独立供电或者加滤波电容。变量越少出问题时越好定位这条原则贯穿整个前期准备。提示如果你手头只有一根不确定能不能传数据的 USB 线最简单的验证办法是插上板子后看电脑设备管理器里有没有新增串口设备。没有新增先换线别急着折腾驱动。2.3 串口链路的底层逻辑与驱动安装串口是这块板子在整个开发周期里最重要的通道——烧录靠它看日志靠它调试也靠它。板子上的 USB 转串口芯片把 USB 协议转成 TTL 串口电脑这边则需要一个对应的驱动程序才能在系统里虚拟出一个 COM 口。Windows 下的操作路径是这样的插上板子打开设备管理器看端口这一栏。如果出现一个带黄色感叹号的未知设备说明驱动没装。这时候去下载对应芯片的驱动装上正常情况下会出现类似USB-SERIAL CH340 (COM3)这样的条目记住这个 COM 号后面烧录和串口助手都要用。如果装完驱动还是感叹号大概率是系统驱动签名策略拦住了需要临时允许未签名驱动或者换一个带签名的驱动版本。Linux 下相对简单大多数发行版内核已经自带这类 USB 转串口芯片的驱动插上之后/dev/ttyUSB0或者/dev/ttyACM0就会自动出现用dmesg | tail能看到识别日志。但这里有个高频坑普通用户默认没有串口设备的读写权限直接打开会报 Permission denied。解决办法是把当前用户加进dialout组然后重新登录生效sudo usermod -aG dialout $USER加完之后一定要重新登录或者重启否则组信息不刷新你会觉得明明加了组怎么还是没权限。这个细节我在第一次配置时卡了十几分钟反复ls -l /dev/ttyUSB0看权限最后才发现是没重新登录。3. 开发环境搭建Windows 与 Linux 的双线配合3.1 为什么这套开发必须有一个 Linux 环境如果你之前只玩过 Arduino可能会疑惑为什么不能像 Arduino 那样装个 IDE 就完事答案在于这套开源物联网系统的构建体系。它的源码编译依赖一整套基于 Python 的构建脚本、Make 体系以及一个专门为这颗芯片准备的交叉编译工具链而这套工具链官方只提供了 Linux 版本。也就是说你最终生成那个可以烧进板子的.bin固件是在 Linux 环境下完成的。于是整个开发就自然分成了两条线Windows 负责烧录、串口调试和日常操作因为烧录工具是图形化的串口助手在 Windows 上也更顺手Linux 负责代码编辑和编译。两条线通过一个共享目录或者文件传输来衔接——你在 Linux 里编译出 bin把它拿到 Windows 里烧进去。理解了这个分工后面配置环境时就不会困惑为什么我要装两个系统的东西。至于为什么工具链只给 Linux这是嵌入式行业的普遍现象交叉编译工具链的构建复杂维护成本高厂商通常优先保证 Linux 版本Windows 原生版本要么没有要么版本滞后。所以与其跟它较劲不如顺着它的设计走。3.2 虚拟机还是 WSL我实测下来的选择要在 Windows 上获得 Linux 环境主流就两条路装一个虚拟机VMware、VirtualBox 之类或者用 Windows 自带的 WSL。这两条路我都走过说说真实感受。虚拟机的优点是隔离彻底、行为最接近一台真实 Linux 机器编译过程稳定几乎不会遇到奇怪的兼容问题。缺点是吃资源编译大工程时风扇狂转而且虚拟机和宿主机之间的文件共享、串口映射都需要额外配置。资源占用上建议至少给虚拟机分配 4GB 内存和 4 核否则编译时容易卡死。WSL 的优点是轻量、启动快、和 Windows 文件系统互通方便命令行体验也顺滑。但它有两个明显的坑一是串口设备映射在早期版本里支持得不好烧录这一步往往还是得回到 Windows 做二是文件系统在跨/mnt访问 Windows 目录时性能很差编译速度会明显变慢。所以如果你用 WSL源码一定要放在 Linux 自己的文件系统里比如~/下的目录不要放在/mnt/c/下面否则编译时间可能翻几倍。我自己的最终方案是虚拟机里跑编译Windows 上跑烧录。这个组合稳定性最好也最符合官方预期。如果你的机器内存紧张WSL 也能用但要记住上面那条源码别放 Windows 盘的原则。注意无论选哪种Ubuntu 版本建议跟官方文档对齐。版本差太多时Python 版本、依赖包名都可能对不上徒增排查成本。3.3 Ubuntu 基础依赖安装与工具链验证环境装好之后Linux 这边要补齐一堆基础依赖。这套构建体系依赖 Python3、git、make、各种编译工具缺一个就会在编译时报错而且报错信息往往指向一个很深的脚本新手很难反推回缺了什么。所以我的建议是一次性把常用依赖装全别等到报错再一个个补。典型的依赖安装命令大致长这样不同 Ubuntu 版本包名略有差异sudo apt update sudo apt install -y git make gcc g python3 python3-pip \ python3-setuptools python3-venv build-essential \ libncurses-dev flex bison装完之后验证一下 Python 版本python3 --version确认是 3.7 以上。这里有个非常经典的坑系统里同时存在 python2 和 python3 时构建脚本可能默认调用了 python2导致一堆语法错误。解决办法是确认python这个命令指向 python3或者干脆在脚本里显式用 python3。工具链这块官方会提供一个针对这颗芯片的交叉编译器包通常是压缩包形式。把它解压到一个固定路径比如~/gcc_toolchain/然后把这个路径加到环境变量 PATH 里。这一步很关键因为构建脚本会去 PATH 里找编译器找不到就报 command not found。验证方式是直接敲编译器名加--version能打印出版本号就说明通了。export PATH$PATH:~/gcc_toolchain/bin记得把这条写进~/.bashrc否则每次开新终端都要重新设一遍。4. 源码获取、编译与烧录工具链的准备4.1 代码目录结构要提前摸清源码拉下来之后别急着编译先花十分钟把目录结构摸清楚。这套代码的组织方式是有规律的理解了之后你改代码、加功能才不会迷路。核心的几个目录大致是这样的applications/应用层代码你自己的业务逻辑、示例程序都放这里日常改得最多的就是它。build/构建系统的脚本编译命令hb就来自这里。device/板级和芯片级的适配代码包括启动流程、外设驱动。vendor/厂商针对具体板子的配置产品名、编译选项、组件裁剪都在这里。out/编译产物输出目录生成的 bin 文件就在这里。新手最容易困惑的是我想加一个自己的程序该放哪、该在哪注册。答案是代码放到applications/下对应的示例目录然后要在同目录的BUILD.gn文件里把你的模块名登记进去否则构建系统根本不知道它的存在编译时会被直接跳过。我第一次加模块时就是漏了这一步编译成功但烧进去没反应排查了半天才发现是没注册。4.2 编译链配置与一次完整的构建验证拿到源码之后标准流程是先设置环境变量、再选产品、再编译。设置环境变量这一步会调用一个脚本把hb工具和工具链路径准备好source build/envsetup.sh然后选产品hb set这一步会列出所有支持的板子用方向键选中小熊派对应的那个产品名回车确认。选完之后会在当前目录生成一个ohos_config.json记录你选的是哪块板子。接着就是编译hb build -f-f表示全量编译第一次一定要用它避免增量编译带来的奇怪问题。编译过程会打印大量日志第一次跑通常要几分钟。编译成功的标志是最后打印出类似 build success 的字样并且在out/目录下生成了那个 allinone 的 bin 文件。找到这个文件把它拷到 Windows 那边留着烧录用。这里我要提醒一个很实在的经验第一次编译千万不要改动任何代码就用原始源码编译一遍。目的是验证环境本身是通的。如果这时就报错那一定是环境问题跟你的代码无关排查范围小很多。等原始代码编译通过了再动代码出问题时就能明确区分是环境问题还是代码问题。这个先跑通再改动的原则能帮你省掉大量无谓的排查。4.3 烧录工具的安装与关键时序Windows 这边的烧录工具有个图形化界面操作不复杂但有几个细节决定成败。工具装好之后打开它选好端口和刚才编译出来的 bin 文件波特率一般设到比较高的值比如 921600以加快速度然后就是最关键的一步——让板子进入下载模式。这个时序是很多人的第一道坎不是点一下下载就完事而是需要先按住板子上的复位或用户按键不放点击工具上的连接/下载按钮然后再松开按键。板子在这个特定时序下才会进入烧录状态。我第一次操作时顺序搞反了工具一直显示等待连接反复试了七八次才反应过来是按键时序的问题。烧录成功之后把工具切到串口助手模式波特率设成 115200这是系统启动日志的默认输出速率复位板子你应该能看到一串启动日志刷出来。看到日志就说明从环境到硬件这条链路彻底通了前期准备算是真正完成。如果没日志先检查波特率、再检查串口是否被其他软件占用、最后检查是不是烧录其实没成功。常见启动日志特征 - 打印芯片信息、版本号 - 打印文件系统挂载信息 - 最后进入一个可交互的命令行或者应用入口5. 常见问题与排查技巧实录5.1 环境类问题依赖、权限、路径环境类问题占了新手期故障的大头而且报错信息往往不直观。我把自己和身边人踩过的几个典型整理一下。编译时报 Python 语法错误十有八九是脚本被 python2 执行了。确认python指向 python3或者直接检查报错行是不是 python2 的 print 语法。编译时报某个模块找不到多半是依赖没装全回头对照依赖清单补。串口权限报错前面说过加dialout组并重新登录。路径里带中文或空格导致编译失败这个非常隐蔽构建脚本在处理路径时遇到空格会截断表现为莫名其妙的文件找不到。所以源码路径一定要用纯英文、无空格。5.2 烧录类问题识别不到、烧不进去烧录环节的故障我整理成下面这张表遇到时按顺序排查现象最可能原因处理办法设备管理器无串口USB 线是纯充电线换一根数据线串口带黄色感叹号驱动未装或签名拦截装驱动或临时放行工具一直等待连接按键时序错误先按键后点下载再松开烧录中途失败波特率过高或线材质量差降低波特率重试烧录成功但无日志波特率不对或串口被占用改 115200、关掉占用软件板子反复重启供电不足或扩展模块功耗大换 USB 口、减少外设这张表是我实际遇到问题后一条条记下来的比死记文档管用。特别是烧录成功但无日志这一条很多人会误以为是固件没功能其实是串口助手波特率没设对。5.3 几条掏心窝子的避坑心得第一变量最小化。每次只改一个东西改完立刻验证。前期准备阶段最容易犯的错是一次性装一堆软件、接一堆外设结果出问题时不知道是哪一环引起的。第二先把原始例程跑通再碰自己的代码。这条前面说过但它值回票价。第三善用串口日志。这套系统的很多问题日志里其实写得很清楚关键是你要会看。系统起不来、应用崩溃第一手信息永远在串口输出里别一上来就怀疑代码写错。第四把成功的环境做一次快照。如果你用虚拟机编译环境彻底跑通之后打个快照。以后环境搞坏了一键回滚比重装一遍快得多。这个习惯我在后面折腾各种依赖时救了自己好几次。第五别迷信最新版本。这套生态迭代很快但开发板和示例代码的兼容性不一定跟得上最新版。遇到玄学问题退回到官方文档明确推荐的版本组合往往就通了。前期的环境准备确实枯燥没有点亮一个 LED 那种立竿见影的成就感。但我的体会是这个阶段花的时间一分都不会白费——后面你每写一个功能、每调一次参数都建立在环境是干净可信的这个前提上。环境不稳你永远分不清是自己代码的问题还是工具链在捣乱。把这条链路一次性打通后面的开发才会顺。