MPLAB Harmony 之基础篇 (01)-- Harmony 3 开发环境搭建 Microchip Technology Inc. MCU32 产品部 一 简介 MPLAB Harmony 3 是 MPLAB 开发工具生态系统的重要组成部分, 适用于 32 位 SAM 和 PIC 微控制器及微处理器 它是一个软件开发框架, 由相互兼容和互操作的模块组成, 包括外设库 ( PLIB) 驱动程序 (driver) 系统服务 (system service) 中间件 (middleware), 第三方软件库 (third-party library) 和大量的应用例程 这个开发框架带了一个 GUI 工具 MPLAB Harmony 3 配置器 (MHC), MHC 提供了一种简易的图形方式来启用 配置和使用各种 MPLAB Harmony 3 的模块, 并生成代码 本文帮助大家在 Windows 平台上搭建一套完整的 Harmony 3 软件开发环境, 包括 MPALB X IDE, 编译器 XC32, MPLAB Harmony 3 配置器以及 Harmony 3 代码库 二 软件平台 操作系统 :Windows 10 MPLAB X IDE:v5.35 或者更新 XC32:v2.30 或者更新 注 : 电脑和 Windows 建议使用 64 位处理器和 64 位操作系统 Windows 用户名使用英文字符 ( 且不含空格 ) 三 详细步骤 ( 一 ) 下载工具安装包 推荐使用最新版本的安装包 MPLAB X IDE: https://www.microchip.com/mplab/mplab-x-ide 1
XC32: https://www.microchip.com/mplab/compilers ( 二 ) 安装 MPLAB X IDE 集成开发环境 下面以 MPLABX-v5.35-windows-installer.exe 安装包为例, 说明 MPLAB X IDE 的安装步骤 1. 双击 MPLAB X IDE 安装包 2. 根据安装提示一步步确认安装 ( 建议按默认选项安装 ) 注 : 1) 安装过程中会遇到如下 Agreement 检查, 接受即可 2) 安装路径建议按默认目录, 如果需要修改目录, 请在遇到如下安装提示时更改至期望目录 2
3) 安装过程中, 确保 MPLAB X IDE 一定要勾选上 4) 等待如下安装进程结束即可 5) 安装进程结束后会弹出如下对话框, 选择安装即可 3
6) 最后, 还会弹出如下对话框, 不用勾选, 直接点击结束即可 ( 三 ) 安装 XC32 编译器 下面以 xc32-v2.30-full-install-windows-installer.exe 安装包为例, 说明 XC32 编译器的安装步骤 1. 双击 XC32 安装包 2. 根据安装提示一步步确认安装完成注 : 1) 建议 Free 安装模式即可 2) 安装路径建议默认目录 4
3) 编译器选项建议默认设置 5
( 四 ) 安装 MPLAB Harmony 3 Launcher 1. 启动 MPLAB X IDE 程序 2. 从 Tools 菜单选择 Plugins Download 3. 若弹出如下对话框, 选择 Go to MPLAB X Plugin Manager 6
4. 从 Available Plugins 里找到 MPLAB Harmony 3 Launcher 选中并单击左下角的 Install 按钮即可安装 安装完毕后选择重启 MPLAB X IDE: 7
5. MPLAB X IDE 重启后, 从 Tools 菜单里的 Embedded 选项里会出现如下菜单 说明 MPLAB Harmony 3 Launcher 已经安装成功! 如需离线安装 MPLAB Harmony 3 Launcher, 可以从 GitHub 获得离线安装版本 (com-microchip-mplab-modules-mh3.nbm): https://github.com/microchip-mplab-harmony/mplabx-plugin/releases ( 五 ) 获取 Harmony 3 代码库 MPLAB Harmony 3 的代码按照功能, 划分成不同的代码仓库, 存放在 GitHub 服务器上 :https://github.com/microchip-mplab-harmony/ 当前在中国访问 GitHub 速度比较慢,MPLAB Harmony 3 的代码库在国内的 Gitee 服务器上有一份镜像, 方便国内用户下载 : https://gitee.com/microchip-mplab-harmony 用户可以根据自己的项目需求下载相应的代码库 使用 MPLAB Harmony 3 时, 以下代码仓库必须下载 : dev_packs: 包含 MPLAB Harmony 3 支持芯片 (PIC 和 SAM) 的相关信息 对于 SAM 芯片, 它包含芯片头文件和 CMSIS 软件标准接口, 这些是编译 Harmony 3 项目必须的文件 mhc:mplab Harmony 3 配置器 (MHC) 的实现 它被 MPLAB Harmony 3 Launcher 调用 csp:mplab Harmony 3 芯片支持包 (CSP) CSP 支持 Microchip 32 位 SAM 和 PIC 芯片的初始化 它提供了芯片外围设备程序库 (PLIB), 用于开发简单应用程序 它具有最小的外部依赖性 以下代码库是可选的, 根据项目需要下载 : core: 包含驱动程序和系统服务 它抽象了 Microchip 32 位 SAM 和 PIC 芯片的外围设备和共享资源, 为上层应用程序提供易于使用和统一的 API 接口 驱动程序和系统服务还可以提供高级功能, 例如缓冲队列 外围设备 8
共享和 RTOS 支持 bsp:microchip 开发板板级支持包 gfx: 这个代码库包含 MPLAB Harmony 图形套件 基本图形例程 驱动程序 工具 库和模板文件 usb: 这个代码库为 Microchip 32 位 SAM 和 PIC 芯片提供 USB 控制器驱动程序, 以及 USB 主从设备常见类的支持 net: 这个代码库为 Microchip 32 位 SAM 和 PIC 芯片提供了一个快速上市的 TCP/IP 协议栈 它包含多个应用程序, 这些应用程序使用常见的协议 ( 如 TCP UDP HTTP SMTP 等 ) 演示通过 TCP/IP 进行通信 audio:mplab Harmony 3 音频支持包 bt:mplab Harmony 3 蓝牙支持包 crypto:mplab Harmony 3 加解密支持包 motor_control:mplab Harmony 3 马达控制支持包 touch:microchip 芯片外设触摸控制器 (PTC) 支持包 wolfssl: 第三方 wolfssl 的嵌入式 TLS 软件库 others:mplab Harmony 3 中还有许多代码库, 请访问 GitHub 并参阅对应仓库的说明文档了解详细信息 下面说明如何用 MPLAB Harmony 3 Content Manager 下载 Harmony 3 代码库 1. 在 MPLAB X IDE 中点击 Tools->Embedded->MPLAB Harmony 3 Content Manager 接下来根据提示一步步往下进行代码库下载 2. 设置 Harmony 3 代码库的本地目录 (Framework Path) 和远端 Git 服务器地址 (Remote URL) 从 Remote URL 下拉框可以选择 Git 服务器的地址 : o GitHub: https://github.com/microchip-mplab-harmony/ o Gitee: https://gitee.com/microchip-mplab-harmony/ 在中国建议选择 Gitee 服务器, 这样下载速度会比较快 9
如果 Harmony 3 代码的本地工作目录不存在, 点击 OK 创建 : 3. 等待连接测试和代码库信息获取 10
4. 若连接成功, 则会显示本地和远端服务器上的代码库 因为此时还没有下载任何代码库, 所以本地库显示为空 下一步, 我们将下载 Harmony 3 的必须代码库 11
5. 下载 MPLAB Harmony 3 必须的代码库 mhc,dev_packs,csp 是必须的代码库, 默认选中, 点击 Download Selected 按钮开始下载 当弹出下载许可时, 先点击 Accept All Licenses, 然后点击 Close 开始下载 如果需要查看每一项的许可说明, 点击 Next 进行查看 12
13
然后等待下载完成 : 下载完成 : 14
在电脑本地可以看到下载好的代码库 : 注意 : 所有的代码库需下载到相同的文件夹内存放, 如上图所示 6. 下载 MPLAB Harmony 3 更多的代码库根据应用项目的需要, 可以下载更多的代码库 下面以 core 代码库为例 首先启动 Harmony 3 Content Manager, 然后选中 core 代码库, 点击 Download 按钮开始下载 core 代码库依赖其他的代码库, 点击 OK 一起下载 : 15
接受所有 License, 开始下载 等待下载完成 : 16
下载完成 : 提示 : 如果要一次启动多个代码库下载, 可以选中相应的代码库, 点击 Download Selected 开始下载 17
( 六 ) 使用 Harmony 3 Content Manager 更新 Harmony 3 代码库 Harmony 3 的代码库的代码会持续迭代更新, 我们可以通过 Harmony 3 Content Manager 进行更新 注意 :Harmony 3 Content Manager 会用第一次下载代码库的 Git 服务器链接进行更新 比如, 第一次下载代码库是用 Github 服务器, 则更新也是用 Github 服务器 在中国, 如果想改用 Gitee 服务器更新, 可以将这个代码库本地删除, 重新从 Gitee 服务器下载 1. 启动 Harmony 3 Content Manager, 点击 Update 按钮开始更新 ( 以下假设 core 代码库有更新 ) 如果更新过程中出现如下界面, 说明本地代码库文件有改动 : 这时鼠标右键点击, 做一个 clean package 的操作 : 注意 : clean package 的操作会将本地文件的修改都丢弃掉 18
等待 clean package 完成, 然后再次点击 Update 按钮开始更新 2. 等待下载完成 3. 下载完成 19
( 七 ) 使用 Harmony Content Manager 切换代码库版本 1. 比如把 core 代码库的版本从 v3.6.1 切换到 v3.5.0, 点相应的下拉框和版本就可以开始切换了 如果更新过程中出现如下界面, 说明本地代码库文件有改动 : 20
这时鼠标右键点击, 做一个 clean package 的操作 : 注意 : clean package 的操作会将本地文件的修改都丢弃掉 等待 clean package 完成, 然后再次选择需要切换的版本开始更新 2. 等待版本切换完成 3. 版本切换完成 ( 八 ) 使用 Harmony Content Manager 查看例程 1. 启动 Harmony 3 Content Manager, 点击 Application Browser 按钮 2. 等待装载例程列表 21
3. 然后就可以查看例程, 并拷贝到自己的工作目录了 22
四 总结 本文通过一步步的图文介绍了 MPLAB X IDE,XC32,MHC 安装以及如何获取 Harmony 3 的代码库, 帮助大家搭建 Harmony 3 的必须的软件开发平台 接下来如何基于 Harmony 3 创建和开发自己的应用, 请参考 MPLAB Harmony 之基础篇的更多其它中文文档和 Harmony 3 wiki 五 参考资料 ( 一 ) How to Setup MPLAB Harmony v3 Software Development Framework ( 二 ) 有关 MPLAB Harmony v3 的更多信息, 请访问以下 Microchip 网站 : https://www.microchip.com/mplab/mplab-harmony https://microchipdeveloper.com/harmony3:start 六 附录 : 使用 Git 命令管理 MPLAB Harmony 3 代码库 如果您熟悉 Git 工具, 通过 Git 命令来下载 更新 MPLAB Harmony 3 代码库也是非常方便快速的 Git 的使用方法可参考 : https://git-scm.com/book/en/v2 ( 英文 ) https://git-scm.com/book/zh/v2 ( 中文 ) ( 一 ) 安装 Git 工具 Git 的安装, 可参考 : 起步 - 安装 -Git 成功安装后, 可以通过 git --version 命令确认 : 23
( 二 ) 使用脚本更新 Harmony 3 代码库 以下提供一个脚本的例子供参考, 脚本功能 : 将已下载的本地 Harmony 3 所有代码库都更新到最新版本 可指定特定代码仓库不更新 ( 需修改脚本, 本例中 wolfssh,wolfmqtt 不更新 ) 在本地的 Harmony 3 代码仓库根目录新建一个批处理文件, 比如 : git_update_all_repos_v2.bat 24
拷贝以下内容到新建的脚本文件中 : @echo off echo This will update your HarmonyFramework (all exist repos) to the latest server version. echo Press Ctrl+C to abort, any key to continue. pause > nul setlocal enabledelayedexpansion for /f "tokens=*" %%G in ('dir /b /A:D') do ( echo. set do_update=1 REM Add your excluded repository here if "%%G" == "wolfssh" ( echo Skipping [%%G] set do_update=0 ) if "%%G" == "wolfmqtt" ( echo Skipping [%%G] set do_update=0 ) ) if!do_update! == 1 ( echo Updating [%%G] cd %%G git fetch git checkout. git checkout master git reset --hard origin/master git clean -fx git clean -fd git log -n 1 --oneline cd.. ) echo. echo Update done. Press any key to exit. pause > nul 25
运行 git_update_all_repos_v2.bat 脚本, 然后按任意键开始更新 Harmony 3 代码库 注意 : 1. 运行脚本前, 请先关闭 Harmony 3 Content Manager 以及其他正在使用 Harmony 3 代码仓库的应用程序 2. 建议把您的工程放到自己的工作目录下, 不要放 Harmony 3 代码仓库目录 该脚本会还原本地文件的修改, 并清理 Git 仓库 如有自己的文件改动, 请一定先备份好 26
( 三 ) 用 Git 命令切换代码库到指定版本以 core 代码库为例, 先鼠标右键 core 目录, 点击 Git Bash Here 启动 Git 命令行工具 : 然后通过 Git 命令查看并切换版本, 比如切换 core 代码库版本从 v3.6.1 到 v3.6.0: 27