1. 开篇从零开始与HarmonyOS的第一次亲密接触作为一名在嵌入式领域摸爬滚打了十多年的老工程师我见证了从8位机到32位MCU再到如今各种RTOS和轻量级操作系统的演进。当华为推出HarmonyOS并面向IoT领域开放时我意识到这不仅仅是又一个操作系统它背后承载的“一次开发多端部署”理念对于解决当前碎片化严重的物联网开发生态可能是一剂良药。但理念再好也需要一个落脚点。对于广大开发者特别是学生和嵌入式爱好者而言如何低成本、低门槛地迈出HarmonyOS开发的第一步是大家最关心的问题。小熊派推出的BearPi-HM_Nano开发板正是这样一个绝佳的“敲门砖”。它基于海思Hi3861V100这颗Wi-Fi SoC价格亲民资源够用官方配套资料也相对齐全。然而官方文档往往侧重于步骤罗列对于环境搭建中可能遇到的“坑”以及背后的原理着墨不多。很多新手朋友照着文档操作常常在某个环节卡住耗费大量时间排查挫败感很强。今天我就以一名一线开发者的视角结合我实际搭建环境的全过程为你拆解BearPi-HM_Nano开发环境搭建的每一个细节。我会告诉你每一步在做什么为什么这么做以及我踩过哪些坑、总结出哪些技巧。我们的目标很明确让你能一次成功把开发板跑起来为后续真正的应用开发扫清障碍。2. 开发环境全景解析为什么是“Linux服务器Windows工作台”在开始动手之前我们必须先理解HarmonyOS特别是针对Hi3861这类轻量级设备的典型开发模式。它并非像在Windows上开发STM32程序那样所有工作都在一台电脑上完成。官方推荐的是“Linux编译服务器 Windows工作台”的分布式开发模式。这个架构选择背后有深刻的工程考量理解它有助于我们后续排查问题。2.1 核心架构拆解各司其职效率至上这种架构将编译构建这类消耗大量计算资源、对操作系统环境有特定要求的工作与代码编写、调试、烧录等人机交互频繁的工作分离开来。Linux编译服务器构建引擎角色它是整个开发流程的“动力车间”。HarmonyOS的编译构建系统基于Gn和Ninja以及针对RISC-V架构的交叉编译工具链gcc_riscv32在Linux环境下拥有最好的兼容性和性能。为什么是Linux首先很多开源构建工具和链工具原生就是为Linux/Unix环境设计的在Windows上通过Cygwin或WSL模拟总会遇到一些边界问题。其次服务器通常拥有更强的CPU和更大的内存可以显著缩短大型项目的编译时间。最后统一的Linux环境便于团队协作和持续集成CI。硬件要求一台独立的电脑可以是旧笔记本、台式机甚至是树莓派或者一台云服务器如阿里云、腾讯云的ECS。对于个人学习在Windows上使用虚拟机如VMware Workstation或VirtualBox安装Ubuntu也是一个非常普遍且可行的方案。Windows工作台交互中心角色它是开发者的“主控台”。我们在这里使用VS Code编写和阅读代码通过MobaXterm等终端工具远程连接并控制Linux服务器通过串口工具与开发板通信以及运行Windows下的烧录工具。为什么是Windows纯粹出于习惯和工具生态。大多数工程师更熟悉Windows下的图形化操作VS Code等编辑器的体验也更好。这个工作台本质上是一个强大的客户端。BearPi-HM_Nano开发板目标设备角色最终代码运行的硬件平台也是我们所有工作的价值体现。连接关系开发板通过USB Type-C线连接到Windows工作台。这根线同时承担了两个重要职责一是为开发板供电二是通过板载的CH340芯片转换为串口实现工作台与开发板的调试信息交互和程序烧录。我的经验之谈对于个人学习者我强烈推荐使用“Windows主机 VMware Ubuntu虚拟机”的方案。它兼顾了便利性和性能。将虚拟机设置为“桥接模式”这样Ubuntu虚拟机就会获得一个与Windows主机同网段的独立IP地址Windows工作台可以像访问一台真实服务器一样访问它。务必为虚拟机分配足够的资源建议至少2核CPU、4GB内存、40GB硬盘否则编译过程会非常缓慢。2.2 软件工具链选型背后的逻辑官方文档给出了工具列表但为什么要装这些它们之间是如何协作的了解这个流水线能让你在出问题时快速定位。代码编辑 (VS Code)这只是个编辑器你可以用任何你喜欢的但VS Code的远程开发插件连接Linux服务器和C/C插件体验非常好。远程连接与终端 (MobaXterm/PuTTY)MobaXterm是我的首选因为它集成了SSH客户端、SFTP文件传输、串口终端于一身一个工具搞定所有连接需求比分开使用PuTTY和WinSCP方便得多。构建系统核心 (Gn Ninja SCons Python)Gn (Generate Ninja)这是一个元构建系统它的作用是读取项目中的BUILD.gn等配置文件生成高效的build.ninja文件。你可以把它理解为一个高级的、描述构建规则的语言。Ninja这是一个专注于速度的小型构建系统。它直接执行build.ninja文件中描述的具体编译、链接命令。GnNinja的组合是Chromium项目带来的先进构建理念比传统的Makefile在大型项目上构建更快。SCons在HarmonyOS的构建流程中SCons似乎用于一些更上层的构建任务驱动或历史遗留模块。我们需要安装它以确保兼容性。Python 3.7以上很多工具如Gn的脚本、一些构建脚本都是Python编写的因此它是基础依赖。交叉编译工具链 (gcc_riscv32)我们的开发板Hi3861的CPU核心是RISC-V架构。我们Windows/Mac的电脑通常是x86架构。交叉编译就是指在A架构的机器上编译生成能在B架构的机器上运行的代码。gcc_riscv32就是专门为32位RISC-V架构生成代码的GCC编译器套件。烧录与驱动 (Hiburn CH341SER)CH341SER.EXE这是USB转串口芯片CH340/CH341的Windows驱动程序。安装后Windows才能识别连接开发板的USB口为一个串行端口如COM3。Hiburn这是海思提供的专用烧录工具。它通过串口与开发板上的Bootloader通信将编译好的二进制文件.bin写入到开发板的Flash存储中。3. Linux服务器环境搭建实战与避坑指南这是整个搭建过程中最复杂、最容易出错的一环。我们一步一步来我会把每个命令的作用和可能遇到的问题都解释清楚。3.1 基础系统准备Shell与网络假设你已经安装好了一个Ubuntu 18.04或20.04的Linux环境实体机或虚拟机。第一步确保Shell是Bash在终端中执行ls -l /bin/sh。如果显示/bin/sh - bash或/bin/sh - /bin/bash那么恭喜这一步跳过。 如果不是很可能指向了dash。dash是一个更轻量、更严格的Shell但HarmonyOS的一些构建脚本可能依赖Bash的特定语法。修改方法如下# 交互式选择推荐 sudo dpkg-reconfigure dash在弹出的蓝色文本界面中用键盘方向键选择“No”然后回车。系统会自动将/bin/sh重新链接到bash。踩坑记录我曾在一个精简版的Docker镜像里构建默认就是dash导致运行./build.py脚本时报出一堆语法错误排查了半天才发现是Shell的问题。所以这是必须检查的第一步。第二步配置软件源与基础工具为了后续安装顺畅建议先更新软件源并安装一些基础开发包。sudo apt-get update sudo apt-get upgrade -y sudo apt-get install -y vim git curl wget build-essentialbuild-essential包含了gcc, g, make等最基础的编译工具是很多其他软件编译的前提。3.2 Python环境部署细节决定成败HarmonyOS构建要求Python 3.7。Ubuntu 18.04默认可能是3.620.04默认是3.8。先检查python3 --version。情况一版本已满足如果显示3.7或更高可以直接安装pip和必要的Python模块。情况二需要安装或升级Python 3.8以安装Python 3.8为例# 1. 安装编译依赖 sudo apt-get install -y gcc g make zlib1g-dev libffi-dev libssl-dev libncurses5-dev libsqlite3-dev libreadline-dev libbz2-dev # 2. 下载Python 3.8.5源码包 (如果服务器下载慢可以在Windows下载后用MobaXterm的SFTP功能拖过去) wget https://www.python.org/ftp/python/3.8.5/Python-3.8.5.tgz # 或者使用官方文档给的链接 # 3. 解压、配置、编译、安装 tar -xzvf Python-3.8.5.tgz cd Python-3.8.5 # --enable-optimizations 选项会进行一些优化但编译时间很长。对于开发环境可以不加。 ./configure --prefix/usr/local/python3.8 --enable-optimizations make -j$(nproc) # 使用所有CPU核心并行编译加快速度 sudo make install关键步骤创建软链接安装后系统的python3和pip3可能还是指向旧版本。我们需要让它们指向新安装的3.8。# 备份旧的链接如果有 sudo mv /usr/bin/python3 /usr/bin/python3.bak sudo mv /usr/bin/pip3 /usr/bin/pip3.bak # 创建新的软链接指向我们安装的版本 sudo ln -s /usr/local/python3.8/bin/python3.8 /usr/bin/python3 sudo ln -s /usr/local/python3.8/bin/pip3.8 /usr/bin/pip3 # 验证 python3 --version # 应显示 Python 3.8.5 pip3 --version # 应显示对应版本安装必要的Python模块# 升级pip本身 sudo pip3 install --upgrade pip # 安装setuptools和kconfiglib (用于图形化配置) sudo pip3 install setuptools kconfiglib # 安装加密相关依赖用于签名等操作 sudo pip3 install pycryptodome six ecdsa重要提示安装kconfiglib或pycryptodome时如果遇到关于lsb_release的错误Command (lsb_release, -a) returned non-zero exit status 1这是因为某些最小化系统缺少这个命令。解决方法sudo apt-get install -y lsb-release如果还是不行可以按文档所说找到并删除有问题的lsb_release文件通常不推荐但安装包是最正本清源的方法。3.3 构建工具三剑客Gn, Ninja, SCons安装SCons最简单的方式是使用apt安装sudo apt-get install -y scons scons -v # 验证应输出版本号如3.0.1如果软件源版本太低才需要从源码编译一般不需要。安装Gn和Ninja官方文档提供了百度网盘的链接。如果下载不便也可以尝试从其他开源镜像站寻找预编译的二进制文件。这里假设你已经下载了gn.1523.tar和ninja.1.9.0.tar。# 1. 创建工具目录并解压我习惯放在用户主目录下 cd ~ tar -xvf gn.1523.tar # 这会解压出一个 gn 目录 tar -xvf ninja.1.9.0.tar # 这会解压出一个 ninja 目录 # 2. 配置环境变量 # 编辑 ~/.bashrc 文件 vim ~/.bashrc # 在文件末尾添加以下两行请根据你的实际解压路径调整 export PATH~/gn:$PATH export PATH~/ninja:$PATH # 3. 让环境变量立即生效 source ~/.bashrc # 4. 验证安装 gn --version # 应输出版本信息 ninja --version # 应输出 1.9.0安装交叉编译工具链 gcc_riscv32同样假设你已经下载了gcc_riscv32-linux-7.3.0.tar.gz。# 1. 解压到 /opt 目录通常用于存放第三方软件 sudo tar -xvf gcc_riscv32-linux-7.3.0.tar.gz -C /opt/ # 2. 配置环境变量 vim ~/.bashrc # 在文件末尾添加注意路径是解压后的具体文件夹名 export PATH/opt/gcc_riscv32/bin:$PATH # 保存退出后执行 source ~/.bashrc # 3. 验证安装 riscv32-unknown-elf-gcc -v如果成功你会看到一长串GCC版本信息和配置详情。这里有个大坑官方文档里解压路径是~/但环境变量配置却写了/opt/gcc_riscv32前后不一致。我建议统一解压到/opt下因为这是更标准的做法。你需要确保~/.bashrc中的路径和工具链的实际存放路径完全一致。4. Windows工作台配置打通任督二脉Linux服务器准备就绪后我们回到熟悉的Windows环境进行客户端的配置。4.1 远程连接MobaXterm的强大之处安装MobaXterm从官网下载免费的家庭版Home Edition即可功能足够。建立SSH会话打开MobaXterm点击左上角的“Session”。选择“SSH”。Remote host栏输入你的Linux服务器的IP地址虚拟机的话在Ubuntu里用ip addr命令查看。Specify username栏输入你的Linux用户名。点击OK。首次连接会保存主机密钥点击Yes。输入密码即可登录。强烈建议勾选“Remember password”这样下次就不用再输了。使用SFTP传输文件MobaXterm左侧边栏会自动显示一个SFTP文件浏览器列出了你Linux家目录下的文件。你可以像在Windows资源管理器里一样直接拖拽文件在Windows和Linux之间传输这比用scp命令方便太多了。4.2 串口驱动与终端听见开发板的声音安装CH340/CH341驱动将BearPi-HM_Nano通过USB线连接到Windows电脑。打开设备管理器右键“此电脑”-“管理”-“设备管理器”。你应该会看到一个带黄色感叹号的“USB2.0-Serial”或未知设备。运行CH341SER.EXE点击“安装”。成功后设备管理器里会出现一个新的“端口COM和LPT”下面会有一个“USB-SERIAL CH340 (COMx)”记住这个COM号比如COM3。配置串口终端在MobaXterm中再次点击“Session”。选择“Serial”。在“Serial port”下拉菜单中选择你刚才记下的COM口如COM3。“Baud rate”设置为115200这是Hi3861默认的串口波特率。其他参数Data bits: 8, Stop bits: 1, Parity: None, Flow control: None保持默认。点击OK。这会打开一个串口终端窗口。给开发板重新上电按一下RST键你应该会在串口终端里看到海思Bootloader的启动日志最后可能停在hisilicon的命令行提示符下。这说明串口通信正常。4.3 代码编辑器的选择与配置安装VS Code直接从官网下载安装。安装有用插件C/C(Microsoft)提供代码跳转、智能提示。Code Runner可以快速运行单个文件虽然HarmonyOS项目不直接这样用但很方便。可选Remote - SSH(Microsoft)如果你希望直接在VS Code里远程编辑Linux服务器上的代码可以安装这个插件。但对于初学者先用MobaXterm的SFTP下载代码到Windows编辑再传回去流程更清晰。5. 获取源码、编译与烧录全流程实录环境全部配好终于到了最激动人心的环节让代码在板子上跑起来。5.1 获取HarmonyOS源码对于BearPi-HM_Nano最方便的是从小熊派官方的Gitee仓库获取适配好的代码。 在MobaXterm的Linux终端中操作# 1. 找一个合适的目录比如家目录下创建一个workspace cd ~ mkdir harmonyos cd harmonyos # 2. 使用git克隆代码仓库如果网速慢可以在Windows用下载工具下zip包再用SFTP上传解压 git clone https://gitee.com/bearpi/bearpi-hm_nano.git --recursive # --recursive 参数很重要它会同时下载子模块比如内核源码。 cd bearpi-hm_nano这个仓库已经为BearPi-HM_Nano做好了适配包含了许多示例程序。5.2 首次编译从命令行到bin文件HarmonyOS LiteOS-M内核使用hb工具进行构建。我们需要先安装hb。# 在bearpi-hm_nano根目录下执行 python3 -m pip install --user ohos-build # 安装后将hb工具所在路径通常是 ~/.local/bin添加到PATH echo export PATH~/.local/bin:$PATH ~/.bashrc source ~/.bashrc # 验证hb安装 hb --help现在开始编译一个最简单的示例——hello_world。# 1. 设置目标开发板Hi3861 hb set执行hb set后会出现一个图形化界面如果没出现检查kconfiglib是否安装成功。用方向键选择bearpi-hm_nano然后回车。# 2. 选择要编译的应用程序路径 # 此时会再次出现一个菜单让你选择产品。对于BearPi通常选择 bearpi_hm_nano 或类似的选项回车确认。 # 不同的仓库可能稍有不同请根据屏幕提示选择。 # 3. 开始编译 hb build -f-f表示全量编译会清理之前的编译产物。第一次编译必须加这个参数。编译过程会持续几分钟你会看到大量的编译命令滚动。如果一切环境配置正确最终会看到“BUILD SUCCESS”的字样并在out/bearpi_hm_nano/bearpi_hm_nano/目录下找到生成的Hi3861_wifiiot_app_allinone.bin文件。这个文件就是我们最终要烧录到开发板的固件。编译过程常见问题排查gn: command not found或ninja: command not found环境变量没生效。请确认~/.bashrc中的路径正确并执行了source ~/.bashrc。可以在终端直接输入echo $PATH查看路径是否包含。riscv32-unknown-elf-gcc: command not found同上交叉编译工具链路径未正确设置。Python模块缺失仔细检查kconfiglib,pycryptodome,ecdsa,six是否都已安装成功。内存不足虚拟机内存分配过小编译可能失败。建议增加到4GB或以上。5.3 烧录程序让开发板“活”过来烧录需要在Windows下进行使用我们之前准备好的Hiburn工具。准备固件文件将Linux服务器上编译生成的Hi3861_wifiiot_app_allinone.bin文件通过MobaXterm的SFTP功能拖拽到Windows的某个文件夹例如桌面。连接开发板确保开发板通过USB线连接电脑且串口驱动已安装好。配置Hiburn打开Hiburn以管理员身份运行可能更稳妥。在Project-Setting或直接在界面上选择COM Port: 选择你的开发板对应的串口如COM3。Baud设置为921600这是Hi3861的烧录波特率与串口调试的115200不同。点击Select file按钮选择你刚才下载到桌面的.bin文件。勾选Auto burn复选框。进入烧录模式这是最关键的一步Hi3861芯片需要在上电的瞬间进入烧录模式。先按住开发板上的“FLASH” 按键或标注为BOOT的按键不放。然后短暂地按一下“RST” 复位按键。此时松开“FLASH”键。这个操作让芯片从系统Flash启动转为从USB烧录接口启动。开始烧录在Hiburn中点击Start按钮。如果操作正确你会看到进度条开始走动并且下方的日志框显示“Connecting...”“Erasing...”“Programming...”“Verifying...”等字样。烧录成功当进度条走完并显示“Execution Successful”或类似的成功提示时表示烧录完成。运行程序点击Hiburn的Stop按钮然后按一下开发板的“RST” 按键。芯片将正常从Flash启动刚烧录的程序。5.4 验证成果串口终端里的“Hello World”回到MobaXterm之前打开的串口终端窗口波特率115200。如果串口终端之前有内容可以清空一下。按下开发板的RST键复位。你将在终端里看到Hi3861的启动日志最后应该会出现来自你应用程序的打印信息。对于hello_world示例你就能看到熟悉的“Hello World!”打印出来。至此恭喜你你已经成功完成了从环境搭建、源码编译到程序烧录、运行的全过程BearPi-HM_Nano开发板已经在你的掌控之中了。6. 环境搭建中的典型问题与解决思路速查表即使按照指南操作也难免会遇到问题。这里我总结了一份速查表涵盖了从环境配置到编译烧录的常见“坑”。问题现象可能原因排查步骤与解决方案MobaXterm SSH连接失败1. Linux服务器IP地址错误。2. Linux SSH服务未开启。3. 防火墙阻止。1. 在Linux终端用ip addr或ifconfig确认IP。2. 运行sudo systemctl status ssh检查服务状态未安装则sudo apt-get install openssh-server。3. 检查虚拟机网络是否为桥接模式或主机防火墙是否放行了22端口。hb set无图形化界面1.kconfiglib未安装或版本不对。2. 终端不支持图形如纯SSH。1. 确认已安装kconfiglibpip3 list编译报错gn: not foundGn/Ninja环境变量未正确设置。1.echo $PATH查看路径。2. 检查~/.bashrc中路径是否正确特别是路径中不能有中文或特殊字符。3. 执行source ~/.bashrc后重试。编译报错riscv32-unknown-elf-gcc相关错误交叉编译工具链问题。1. 确认工具链已解压且路径正确添加到PATH。2. 在工具链的bin目录下直接执行./riscv32-unknown-elf-gcc -v看是否正常。3. 检查工具链是否为32位版本64位系统可能需要安装32位兼容库sudo apt-get install lib32z1。烧录时Hiburn无法连接1. 串口号选择错误。2. 波特率不是921600。3. 未正确进入烧录模式。4. 驱动问题。1. 在设备管理器中确认COM口。2. 确认Hiburn波特率为921600。3.严格按照步骤先按住FLASH键再点按RST键然后松开FLASH键。4. 重新安装CH340驱动或尝试换一个USB口。烧录成功但串口无输出1. 串口终端波特率不是115200。2. 程序本身无打印或打印被关闭。3. 开发板供电不足。1. 检查MobaXterm串口会话的波特率是否为115200。2. 确认烧录的固件是包含应用程序的allinone.bin并检查代码中是否有打印语句如printf。3. 使用质量好的USB线并直接连接电脑后置USB口避免使用扩展坞。Python模块安装超时或失败网络问题连接PyPI官方源慢。更换为国内镜像源如阿里云、清华源。pip3 install [模块名] -i https://mirrors.aliyun.com/pypi/simple/最后我想分享一个最重要的心得嵌入式开发尤其是环境搭建本质上是一个“精确”的活儿。任何一个路径错误、一个版本不匹配、一个步骤顺序颠倒都可能导致失败。我的建议是严格按照一份可靠的指南操作并充分理解每一步的目的。当遇到报错时不要慌张仔细阅读错误信息它通常已经给出了线索。善用搜索引擎但要在搜索时加上关键错误代码和关键词如“Hi3861”、“HarmonyOS”、“hb build error”。这个从零开始搭建环境并点亮第一盏灯的过程虽然曲折但却是你深入理解HarmonyOS开发体系最扎实的第一步。希望这篇超详细的指南能帮你少走弯路顺利开启你的HarmonyOS之旅。