欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

欢迎在 PC 社区平台申请新建项目：https://atomgit.com/OpenHarmonyPCDeveloper

适配开源地址：https://atomgit.com/xiaohong-ai/sscom

一、为什么要适配 SSCom

串口调试工具属于开发现场里使用频率很高、但又很容易被低估的一类软件。调试单片机、模组、网关、开发板或产线测试脚本时，开发者通常需要反复完成串口枚举、参数配置、文本/HEX 收发、编码切换、DTR/RTS 控制和日志保存。传统桌面串口工具在 Windows、Linux、macOS 上已经非常成熟，但鸿蒙 PC 进入开发桌面场景后，也需要一款符合本地窗口、权限、文件访问和设备模型的串口调试助手。

sscom 项目本身已经完成了跨平台方向的重构：桌面端采用 Rust + egui，串口层使用 serialport crate；鸿蒙端则拆成 ArkUI 界面、C++ NAPI 桥接层和 Rust FFI 核心库。这样的结构适合继续做鸿蒙 PC 适配，因为 UI、串口核心和编码转换可以分层维护，不需要把一整套桌面窗口代码硬搬到 HAP 工程里。

本次真机验证的鸿蒙 PC 应用 BundleName 为 com.sscom.serial，应用版本为 1.0.0，Compile SDK 为 HarmonyOS 6.0.2.130，Target API 为 60001021，目标 ABI 为 arm64-v8a。测试设备通过 hdc 连接，系统截图分辨率为 3120×2080。以下图片均为鸿蒙 PC 真机运行截图。

二、适配边界先明确

串口调试助手看起来只是几个输入框和按钮，但真正适配到鸿蒙 PC 时，重点不在界面复刻，而在通信链路和系统边界的重建。桌面端可以依赖 serialport 库统一处理不同系统的串口细节，鸿蒙端则需要面对 HAP 生命周期、USB 串口权限、Native 库装载、ArkTS 与 Rust 之间的数据交换，以及窗口化 PC 体验。

模块	桌面端常见处理	鸿蒙 PC 侧处理
串口枚举	serialport crate 直接枚举	Rust FFI 扫描设备节点并通过 NAPI 返回 ArkTS
串口打开	原生二进制直接访问 COM 或 /dev/tty*	HAP 权限、设备节点、Native 句柄共同约束
数据收发	Rust 线程读写串口	ArkTS 轮询调用 NAPI，底层 Rust 负责读写
HEX 支持	UI 状态和 Rust 解析在同进程内完成	ArkTS 管理模式，Rust 负责字节转换与校验
编码转换	UTF-8/GBK/Latin1 由桌面端处理	通过 Rust 核心库复用 encoding_rs 能力
文件能力	系统文件对话框	使用鸿蒙文件选择器读取发送内容、保存接收内容
控制线	DTR/RTS 由串口库封装	通过 ioctl 暴露给 ArkTS 开关

这次适配没有把串口助手做成“命令行外壳”，而是把串口参数、收发面板、HEX/编码状态、文件操作和底部状态栏放进同一个原生应用窗口里。这样更接近 PC 上日常调试的习惯：先确认连接，再决定收发格式，最后查看日志和统计。

三、真机运行与核心功能

在进入截图说明前，先放一段真机运行录屏，便于直接观察应用在鸿蒙 PC 桌面环境中的启动、窗口展示和核心交互状态。

1. 主界面：串口参数和收发区域同屏呈现

应用启动后，左侧是连接参数与数据格式，右侧是接收日志和发送区，顶部保留当前连接状态和打开串口入口。这个布局适合串口调试的高频操作：波特率、数据位、校验位、停止位、流控、HEX 显示、HEX 发送、编码选择都能在同一屏完成确认。

截图中当前未接入 USB 串口设备，底部状态栏提示“未检测到串口”。这类空态对串口工具很重要，因为真实现场经常先遇到的不是收发成功，而是数据线未连接、设备未授权、串口被占用或设备节点尚未生成。应用没有在空设备状态下崩溃，而是把状态稳定地留在页面底部。

2. 波特率选择：常用档位固定呈现

波特率是串口通信最容易配错的参数之一。鸿蒙 PC 版本将常用档位做成下拉选择，从 300 到 2000000 都可以直接选择，默认保持在常见的 115200。

这里没有让用户手动输入任意数字，是为了减少现场调试时的低级错误。多数开发板、模组和调试固件都使用固定波特率档位，下拉列表比自由输入更适合桌面工具的默认路径；确有特殊波特率时，再在核心层补充支持会更可控。

3. HEX 收发：把字节视图和发送格式同时联动

切换 HEX 显示 和 HEX 发送 后，接收日志标题旁会出现 HEX 标记，发送区也会切换为按空格分隔字节的输入提示。这个联动避免了“接收按文本看、发送按 HEX 发”时状态不清的问题。

HEX 模式是串口调试的核心能力。调试二进制协议、bootloader 握手、寄存器读写或带校验帧的数据包时，文本窗口不足以判断真实字节。适配时将 HEX 状态同时体现在接收区和发送区，让用户一眼能确认当前窗口正在以字节方式工作。

4. 编码选择：兼顾 UTF-8、GBK 和 Latin1

串口设备并不总是按 UTF-8 输出日志。很多存量设备、工控模块和中文固件仍然使用 GBK，部分协议还会混合 Latin1 或直接输出原始字节。鸿蒙 PC 版本保留了接收编码和发送编码选择，其中接收侧支持 UTF-8、GBK、Latin1。

编码能力放在串口工具里，比在日志输出后再做外部转换更实用。Rust 核心库复用 encoding_rs 做转换，ArkTS 侧只负责模式状态和文本展示；这样既避免了 UI 层堆积复杂字节逻辑，也能降低多字节字符截断带来的乱码风险。

5. 执行前拦截：未选择串口时阻止打开

在没有可用串口时点击“打开串口”，应用会弹出提示，要求先连接开发板并刷新扫描结果。这不是一个装饰性弹窗，而是串口工具必须具备的安全路径。

串口调试现场经常会反复插拔设备。与其让底层直接尝试打开空路径，再把错误埋进日志里，不如在 UI 层先完成必要校验。等接入真实 USB 转串口后，用户只需要刷新串口列表、选择设备、确认波特率，再打开连接即可。

四、适配中的主要困难

难点一：桌面串口库不能直接照搬到鸿蒙端

桌面端 Rust 可以使用 serialport crate 统一处理平台差异，但鸿蒙目标并不适合原样依赖这条路径。当前鸿蒙核心库改为 staticlib，底层通过 libc、termios 和 ioctl 处理串口打开、参数配置、读写以及 DTR/RTS 控制。这样做让串口访问更贴近系统能力，但也意味着波特率映射、数据位、校验位、停止位、流控和错误返回都需要自己兜住。

难点二：ArkTS 与 Rust 之间必须控制好数据边界

鸿蒙端的调用链路是 Index.ets → SerialPort.ets → libsscom_napi.so → bridge.cpp → libsscom_core.a。ArkTS 适合管理界面状态和用户交互，Rust 适合处理字节、编码和串口读写；中间的 C++ NAPI 层则要负责类型转换和句柄传递。这里最容易出问题的是指针生命周期、字符串释放、空返回值和异常兜底。项目中为 Rust FFI 提供了 sscom_string_free、最后错误信息和 catch_unwind 保护，目的就是避免底层异常直接拖垮应用。

难点三：串口权限和设备节点比桌面端更敏感

应用已经声明 ohos.permission.ACCESS_DDK_USB 和 ohos.permission.ACCESS_DDK_USB_SERIAL，但声明权限并不等于所有设备都能直接访问。真机上还要考虑 USB 授权、设备热插拔、系统签名、普通应用权限级别和 /dev/tty* 节点可见性。文章中的截图保留了无设备状态，是因为这个路径在现场非常常见，也最能看出应用是否处理得稳定。

难点四：PC 窗口体验需要重新组织

手机应用常见的单列页面并不适合串口调试。PC 用户更习惯一边看接收日志，一边调整参数和发送数据。鸿蒙 PC 版本采用左侧参数、右侧日志和发送区的布局，并把状态栏固定在底部，减少来回切页。适配时还要注意窗口尺寸、系统避让区、桌面任务栏和浮窗模式，保证在真实 PC 桌面上不会遮挡核心控件。

难点五：构建环境要和工程配置严格匹配

当前工程的 build-profile.json5 面向 HarmonyOS SDK 6.1.0(23) 配置，真机构建验证时也能看到已安装版本使用的是 HarmonyOS 编译链和 arm64-v8a ABI。鸿蒙项目对 SDK、签名材料、Hvigor、CMake、NDK linker 和 Rust target 的匹配要求比较高；只要本机 SDK 缺少对应 compatibleSdkVersion，构建阶段就会被拦截。因此，工程化适配时需要把 SDK 版本、签名配置和 Rust 交叉编译环境提前固定，避免临近打包才暴露问题。

五、当前鸿蒙端架构

项目中的鸿蒙端采用三层结构：

ArkUI 页面
  entry/src/main/ets/pages/Index.ets
  负责界面、状态、参数选择、文件选择和按钮交互

ArkTS 模型层
  entry/src/main/ets/model/SerialPort.ets
  负责封装 NAPI 调用、轮询接收、统计字节数和编码状态

Native 核心层
  entry/src/main/cpp/bridge.cpp
  rust-core/src/lib.rs
  负责 NAPI 注册、Rust FFI、串口读写、HEX 工具和 GBK/UTF-8 转换

主要 NAPI 能力包括：

接口	说明
listPorts	枚举可用串口并返回字符串数组
openSerial / closeSerial	打开和关闭串口句柄
readSerial	从串口读取数据并返回 HEX 字符串
writeSerial / writeSerialHex	按文本或 HEX 写入串口
setDtr / setRts	控制 DTR、RTS 线路
reconfigure	在线更新波特率、数据位、校验位、停止位和流控
gbkToUtf8 / utf8ToGbk	在中文串口日志和发送内容之间做编码转换

六、构建与安装建议

鸿蒙端源码位于 ohos/ 目录，推荐使用仓库内脚本完成 Rust 静态库和 HAP 的分段构建：

cd ohos

# 完整构建：Rust staticlib -> 复制 .a -> 清理缓存 -> 打包 HAP
bash build.sh

# 只编译 Rust 核心库
bash build.sh --rust

# 只构建 HAP
bash build.sh --hap

构建成功后，产物路径为：

ohos/entry/build/default/outputs/default/entry-default-signed.hap

安装到真机可以使用：

hdc install ohos/entry/build/default/outputs/default/entry-default-signed.hap
hdc shell aa start -a EntryAbility -b com.sscom.serial

需要注意的是，串口访问必须在真机上验证。模拟器通常无法提供真实 USB 串口链路，最多只能验证 UI、文件选择和基础状态流转。

七、当前能力和边界

当前真机版本已经覆盖以下能力：

• 鸿蒙 PC 上的 HAP 安装、启动和窗口展示；
• 串口扫描、刷新和无设备空态展示；
• 波特率、数据位、校验位、停止位、流控等连接参数选择；
• DTR、RTS 控制入口；
• HEX 显示、HEX 发送和 CRLF 自动追加；
• UTF-8、GBK、Latin1 接收编码选择；
• 文本/HEX 发送区、接收日志区、复制、清空、保存和打开文件入口；
• 底部状态栏同步 RX/TX 字节数、编码、波特率和串口参数。

后续继续推进时，建议重点补充这些验证：

• 接入真实 USB 转串口设备后的枚举、授权、打开和关闭稳定性；
• 文本模式与 HEX 模式下的长时间收发压力测试；
• GBK 中文日志、多字节截断和混合编码设备的兼容性；
• DTR/RTS 对目标开发板复位、进入下载模式等场景的实测；
• 文件发送、接收保存和异常中断后的数据完整性校验。

八、总结

SSCom 的鸿蒙 PC 适配不是简单把桌面串口工具换一个外壳，而是把串口访问、编码转换、HEX 字节处理、文件能力和窗口交互重新放到 HarmonyOS 的应用模型里。项目用 ArkUI 承接桌面操作体验，用 C++ NAPI 做边界桥接，用 Rust 保留底层字节处理和跨平台可维护性，这条路线比较适合开发工具类应用继续演进。

从真机截图可以看到，应用已经能在鸿蒙 PC 上稳定启动，并完成参数选择、HEX 模式、编码选择、无设备拦截和状态展示。后续接入真实串口硬件后，重点应放在权限、热插拔、长时间收发和异常恢复上。串口工具的好用程度，往往不只体现在成功收发那一刻，更体现在设备没接好、参数选错、编码不一致时，能不能让开发者迅速判断问题卡在哪里。