HARTLink 是一套基于 CH32L103 的便携式 HART 调试固件，集成本地 SSD1306 OLED 菜单、旋转编码器操作、基础 HART 只读命令、设备轮询、USB CDC 透传和 USB HID IAP 升级。
项目定位是“小手操器完成简单查看，上位机完成复杂操作”。本机菜单只开放安全、无输入的读取功能；参数写入、维护命令和 DD 相关复杂解析交给上位机，减少现场误操作风险。
本项目采用源码开放、非商业许可。个人学习、研究、实验及非商业组织可以按许可证使用；商业生产、销售、付费集成或用于商业产品需要取得书面授权。详见 LICENSE。
 连接 HART 回路，读取现场设备过程变量 |
 掌上尺寸与本机 OLED 操作界面 |
前往 GitHub Releases 下载已编译固件。
| 文件 | 用途 |
|---|---|
HARTLink.hex |
完整固件，包含 Bootloader 和应用程序；用于首次烧录或完整恢复 |
HARTLink_app.hex |
仅应用程序；用于设备的 USB HID IAP 升级 |
HARTLink.bin |
应用程序 Bin，供其他烧录工具使用 |
HARTLink_boot.hex / HARTLink_boot.bin |
独立 Bootloader，通常仅开发和维护时使用 |
当前稳定版本：v1.0.1
| 功能 | 说明 |
|---|---|
| 本地手操 | 128×64 SSD1306 OLED、旋转编码器、蜂鸣器、中英文菜单 |
| HART 通信 | 1200 baud、8O1，支持短地址发现、长地址读命令和自适应前导数 |
| 基础命令 | Cmd0/1/2/3/7/9/12/13/14/15/20/48 等安全只读命令 |
| 设备发现 | 扫描轮询地址 0-15，缓存设备身份和长地址 |
| 数据显示 | PV/SV/TV/QV、环路电流、量程、状态和常用工程单位 |
| 结果滚动 | 长结果先停留 0.8 秒，再循环滚动，适配小尺寸 OLED |
| USB 上位机 | USB CDC 虚拟串口，原始 HART 帧双向透传 |
| 总线保护 | 上位机通信活跃时本机显示 HOST BUSY，不会抢占 HART 总线 |
| 在线升级 | 常驻 Bootloader，支持 USB HID IAP 和备用 USART1 IAP |
| 参数保存 | 亮度、蜂鸣器音量和语言保存到独立 Flash 设置区 |
| 自动发布 | GitHub Actions 自动编译；版本标签自动创建 Release 和固件资产 |
| 项目 | 配置 |
|---|---|
| MCU | CH32L103C8T6，RISC-V，48 MHz |
| 显示 | SSD1306 OLED |
| 操作 | A/B 相旋转编码器、按键、蜂鸣器 |
| HART 物理层 | USART2，1200 baud，8 数据位、奇校验、1 停止位 |
| 上位机接口 | USB CDC，设备名 HARTLink CDC |
| IAP 接口 | USB HID 1A86:FE17，设备名 CH32L103 IAP |
| 备用 IAP | USART1，PA9/PA10，115200 8N1 |
应用与 Bootloader 均使用 48 MHz HSI + USBCLK Div1。HART 串口位于 PCLK1 24 MHz 域，由硬件分频产生 1200 baud。
方案 A 中，HARTLink 的红、黑表笔跨接在 250 Ω 回路电阻两端；方案 B 中，表笔并联在 HART 现场仪表两端。接线前请确认回路极性、设备供电、回路负载和现场安全条件。
- 首次使用时，用 WCH-Link 或常规下载器烧录完整固件
HARTLink.hex。 - 连接 HART 回路并给设备上电，等待 OLED 显示
HARTLink V1.0.1。 - 长按编码器进入主菜单，选择
Device -> Scan 0-15搜索现场设备。 - 找到设备后，可在
HART Cmds、Polling和Diagnostics中查看基础变量和状态。 - 需要 DD、写参数或维护操作时，通过 USB 连接 ModeSignal 网页上位机，由上位机发送完整 HART 帧。
| 场景 | 旋转 | 短按 | 长按 |
|---|---|---|---|
| 主页 | 切换底部快捷操作 | 执行当前操作 | 进入主菜单 |
| 主菜单 | 移动选中项 | 进入页面/执行 | 返回主页 |
| 子页面 | 移动选中项或调节数值 | 确认/执行 | 返回或放弃修改 |
编码器按键每 5 ms 采样，消抖 30 ms，长按阈值 800 ms。A/B 相通过双边沿 EXTI 和 Gray 状态表解码，机械抖动产生的反向边沿会抵消，每个完整卡点对应菜单一步。
| 页面 | 功能 |
|---|---|
| HART Cmds | Cmd0/1/2/3/7/12/13/14/15/20 等安全读命令 |
| Device | 扫描地址 0-15、刷新身份、修改本地轮询地址、清除缓存 |
| Polling | 开关本地轮询、选择 Cmd1/Cmd3、调整周期和轮询地址 |
| Diagnostics | Cmd48 附加状态、Cmd9 设备变量状态、清除缓存 |
| System | 亮度、蜂鸣器、语言、保存设置、版本信息、IAP 模式 |
Cmd11/21 需要 Tag 或 Long Tag 输入；Cmd6/17/18/19/22/38 会修改设备状态。本机菜单不提供这些命令，上位机透传仍可发送完整 HART 帧。
本机执行 Cmd1/2/3/9/48 等长地址命令前，必须先通过 Cmd0 或扫描取得设备长地址。尚未发现设备时会显示 SCAN FIRST，避免使用短地址直接读取变量导致无效 ACK。
结果使用清晰的字段名和常用缩写：PV、SV、TV、QV 表示四个动态变量；过程值、环路电流、量程、设备状态等信息会按页面空间组合显示。常用 HART 单位会转换为 kPa、MPa、bar、psi、degC、mA、%、L/min、m3/h 等工程单位，未识别的厂商扩展单位显示为 unit#N。
| 提示 | 含义 |
|---|---|
TX CMDx |
本机命令已发送 |
ACK OK |
收到对应 ACK，响应码为 0 |
ACK WARN |
收到带数据的设备警告响应，继续显示可解析结果 |
ACK ERROR |
收到非零错误响应 |
NO RESPONSE |
等待 ACK 超时 |
HOST BUSY |
上位机透传活跃，本机命令未发送 |
SCAN FIRST |
尚未取得长地址，需先执行 Cmd0 或扫描 |
结果超过底部显示宽度时，会先停留 0.8 秒，再以每 0.25 秒一个字符循环滚动，中间保留 3 个空格。
推荐使用 ModeSignal 网页上位机。无需安装桌面客户端，使用支持 Web Serial 的 Chrome 或 Edge 即可连接 HARTLink。
- 使用 USB 数据线连接电脑与 HARTLink，等待系统识别
HARTLink CDC虚拟串口。 - 在 Chrome 或 Edge 中打开 https://modusignal.cn/。Web Serial 需要 HTTPS 或
localhost环境。 - 点击页面的串口连接按钮，在浏览器授权窗口中选择
HARTLink CDC对应的 COM 口。 - 连接成功后设置轮询地址，先执行设备扫描或 Cmd0，再进行变量读取、轮询或其他上位机操作。
- 使用本机菜单前先停止上位机轮询；上位机仍在通信时 OLED 会显示
HOST BUSY。
正常运行时设备枚举为 HARTLink CDC。除版本查询外，CDC 收到的数据会按原始字节透传到 HART 物理层，HART 返回数据也会原样上传。
查询型号和版本：
TX: HARTLINK:VERSION?\r\n
RX: HARTLINK:VERSION=V1.0.1;MODEL=HARTLinkM1\r\n
命令末尾可使用 \r\n、\n 或不带换行。只有整段数据精确匹配查询命令时才由本机响应，其余内容保持透传。建议在当前 HART 请求/响应结束后查询，避免设备信息与现场响应混在同一数据流中。
上位机通信优先级高于本机命令。USB 最近有输入或仍有待转发数据时，本机不会抢占总线，也不会执行 Flash 擦写。
推荐使用仓库内的 WCHMcuIAP_WinAPP.exe 或 WCH 官方 IAP 工具：
- 在
System -> IAP Mode进入升级模式；也可以按住编码器上电。 - 设备重新枚举为
CH32L103 IAP，VID/PID 为1A86:FE17。 - 工具选择
USB HID，加载HARTLink_app.hex并下载。 - 下载完成后 Bootloader 自动启动应用，设备重新枚举为
HARTLink CDC。
不要用 WCHISPStudio 下载 HARTLink_app.hex。WCHISPStudio 使用芯片 BootROM ISP 协议，本项目的应用升级使用自带 Bootloader 的 IAP 协议。
按住编码器进入 IAP 后，蜂鸣器短响两次，Bootloader 会一直停留在升级模式，直到下载完成或设备重新上电。
USART1 备用通道使用 PA9/PA10、115200 8N1。若串口 IAP 工具在擦除阶段提示读取长度错误，可先关闭占用串口的软件，再运行：
powershell -NoProfile -ExecutionPolicy Bypass -File tools/iap_probe.ps1 -Port COM17正常返回：
RX(6): AA 55 00 00 55 AA
ACK OK
| 区域 | 地址 | 说明 |
|---|---|---|
| Bootloader | 0x0000-0x4FFF |
常驻启动和 IAP |
| 应用程序 | 0x5000-0xF7FF |
HARTLink 主固件 |
| 设置区 | 0xF800-0xFFFF |
亮度、音量、语言 |
| IAP 请求页 | 0x08004F00，256 B |
Bootloader 分区内的升级请求标志 |
设置区与应用区分离，保存参数和应用升级不会相互覆盖。
- Windows 10/11
- MounRiver Studio 2 自带的 WCH RISC-V Embedded GCC，或兼容的
riscv-none-embed-*工具链 - GNU Make
- PowerShell 5 或更高版本
默认 Makefile 使用以下工具链目录：
C:/MounRiver/MounRiver_Studio2/resources/app/resources/win32/components/WCH/Toolchain/RISC-V Embedded GCC/bin
编译完整固件：
make all使用其他工具链目录：
make all TOOLCHAIN="D:/toolchains/riscv/bin"当前验证的固件大小：
app: text=42884 data=96 bss=6908
boot: text=7440 data=56 bss=1856
GitHub Actions 在每次 push、Pull Request 和手动触发时构建固件，并上传 Actions Artifact。推送 v* 标签会自动创建 GitHub Release，并发布完整固件、应用固件和 Bootloader 文件。
git tag -a v1.0.2 -m "Release v1.0.2"
git push origin v1.0.2工作流配置见 .github/workflows/firmware.yml。
Bootloader/ 常驻 Bootloader 与 IAP
Core/ WCH RISC-V 核心支持代码
Debug/ 调试支持
Ld/ 应用和 Bootloader 链接脚本
Peripheral/ WCH CH32L103 外设库
Startup/ 启动文件
User/App/ HART 协议、业务逻辑和 UI
User/Bsp/ OLED、编码器、蜂鸣器、USB、HART 物理层
User/Drv/ SSD1306 驱动与字体
User/Sys/ 系统初始化、时钟和任务调度
tools/ 固件合并和 IAP 诊断脚本
欢迎提交 Issue 和 Pull Request。建议修改保持以下原则：
- 小手操器只承担简单、明确、低风险的查看操作。
- 写入、维护、DD 解析等复杂操作保留给上位机。
- 不降低上位机透传优先级，不让本机 UI 抢占现场总线。
- 修改 Flash 布局、Bootloader 或 HART 写命令时，需要说明兼容性和现场风险。
HARTLink 自研固件、软件、文档、图片、硬件设计文件及衍生产品资料采用 PolyForm Noncommercial License 1.0.0，仅允许非商业用途。商业使用、生产销售、转售、付费集成或用于商业产品/服务，需获得版权所有者的单独书面授权。
Core/、Peripheral/、Startup/ 及其他带 WCH 版权头的文件属于南京沁恒微电子提供的第三方代码，继续适用文件内原始声明，不因本项目许可证而重新授权；相关代码仅可用于南京沁恒生产的微控制器。
本项目按“现状”提供，不附带任何保证。HART 设备可能连接实际工业过程，使用前应确认回路、设备地址、命令类型和安全条件。涉及参数写入、量程修改、回路测试或维护模式的操作，应由具备相应权限和经验的人员执行。