串口工具 HICom 完整使用文档

klk · 2026 年4 月 9 日 10:09

HICom 完整使用文档

1. 软件简介

HICom 是一款面向串口调试场景的 Windows 工具，核心特点是：除了常规串口收发功能外，还内置了 Lua 脚本运行环境。这意味着它不仅能“看数据、发数据”，还能做自动应答、协议解析、定时任务、曲线绘制、网络联调等更高级的工作。

它适合以下场景：

MCU、模组、传感器、工控设备的串口调试
AT 指令、二进制协议、私有协议联调
固件产测、老化测试、自动回包验证
需要用 Lua 做自动化处理、协议桥接或数据转换的场景
同时调试串口、TCP/UDP、MQTT、WinUSB 等多种接口的场景

说明：本文档基于当前仓库中的界面截图与项目源码整理而成，不同版本的按钮位置或文案可能略有差异，但整体功能与使用方式一致。

2. 功能总览

HICom 的主要能力包括：

常规串口收发、日志显示、计数统计
文本与 HEX 双模式发送/显示
RTS / DTR 控制
串口异常断开后自动重连
发送前 Lua 预处理脚本
接收数据显示 Lua 处理脚本
独立 Lua 运行区，支持定时器、任务、日志输出、接口调用
右侧快捷发送区，支持多页独立命令集
导入/导出快捷发送数据，兼容 SSCOM 配置导入
社区脚本浏览与复用
TCP / TCPSSL / UDP / IPv6 / MQTT 测试
编码转换、乱码修复、串口监听、曲线显示、WinUSB 调试

3. 快速开始

如果你第一次使用 HICom，建议按下面 5 步走：

启动软件后，在底部选择目标串口和波特率。
单击左下角的 打开串口。
在中间输入框中填入要发送的数据。
根据需要勾选 发Hex 或 发末尾加回车换行。
单击发送，并在左侧日志区查看设备返回结果。

常见首测建议：

调试 AT 指令时：一般使用文本发送，并勾选 发末尾加回车换行。
调试二进制协议时：勾选 发Hex，按十六进制字符串输入。
串口经常热插拔时：在“更多设置”中开启 自动恢复被断开的串口连接。

4. 主界面总览

4.1 主界面截图

4.2 界面区域说明

主界面大致可以分为 5 个区域：

日志显示区
位置：左上大区域
作用：显示串口收发日志、脚本输出、状态信息
发送控制区
位置：左下中部
作用：输入待发送数据，执行普通发送
串口控制区
位置：左下底部
作用：选择串口、波特率、打开/关闭串口、刷新串口
功能标签区
位置：右侧
作用：在“快捷发送 / 运行脚本 / 小工具 / 关于”等页之间切换
状态栏
位置：最底部
作用：显示当前状态、已发送字节数、已接收字节数

4.3 主界面常用按钮与勾选项

左下按钮

打开串口 / 关闭串口：开启或关闭当前选中的串口。
清空日志：清空左侧日志显示区。
更多设置：打开高级串口设置、发送/接收脚本设置窗口。
刷新串口：重新扫描系统中的串口设备。
发送：发送输入框中的数据，也可使用 Ctrl + Enter 快捷发送。

常用勾选项

RTS / DTR：控制串口相关握手信号。
Hex显示：快速切换日志的 HEX 视图习惯。
发Hex：将输入框内容按十六进制字符串发送。
发末尾加回车换行：在发送末尾自动追加 \r\n。
替换不可见字符：提高日志可读性，避免不可见字符影响观察。
停止打印：暂停界面日志打印/滚动，便于查看之前的数据。

底部状态信息

状态：显示串口当前是否打开。
已发送字节 / 已接收字节：统计当前会话的收发量。
这两个计数文本支持右键清零。

4.4 普通发送说明

文本发送

直接在输入框中输入字符串，例如：

AT

如果设备要求回车换行结尾，可勾选 发末尾加回车换行。

HEX 发送

勾选 发Hex 后，在输入框中输入十六进制字符串，例如：


AA 01 02 0D 0A

建议：

用空格分组，便于阅读
保证输入的是合法 HEX 字符串
若发送失败，优先检查是否误混入中文空格、非十六进制字符或奇数字节长度

4.5 自动重连行为

当串口因为设备拔插或系统事件中断时，如果在“更多设置”中启用了 自动恢复被断开的串口连接，HICom 会在串口重新出现后尝试恢复连接。

注意：

手动关闭串口 后，一般不会再自动重连
自动重连对频繁拔插设备的联调场景非常有用

5. 快捷发送

5.1 功能说明

右侧默认页签就是 快捷发送。它适合放置常用命令、测试帧、初始化指令、产测步骤等内容。

HICom 的快捷发送支持：

多行快捷命令
每行单独设置是否按 HEX 发送
每行绑定接收处理脚本与参数
多页独立数据列表（适合不同项目、不同设备）
导入 / 导出 / 清空当前页
导入 SSCOM 历史配置

5.2 列说明

编号：当前快捷项的顺序编号。
内容：要发送的文本或 HEX 字符串。
HEX：勾选后，本行内容按 HEX 发送。
脚本：为本行绑定一个“接收处理脚本”，发送本行时自动切换到对应接收脚本。
参数：传给该接收脚本的参数，脚本中可通过 uartPara 获取。
发送按钮：发送当前行内容。

5.3 常用操作

添加新项目：在当前页末尾增加一行。
删除最后一项：删除当前页最后一行。
导入数据到该页：导入 .lclst 格式的 HICom 快捷发送列表。
导出该页数据：将当前页快捷发送内容导出保存。
一键清空该页数据：清空当前页全部内容，需要确认。
一键导入 SSCOM 数据：将 SSCOM 配置导入为 HICom 快捷发送项。

5.4 进阶技巧

1）一页一个设备场景

建议按设备类型或调试阶段拆分不同页，例如：

第 1 页：模组初始化命令
第 2 页：生产测试命令
第 3 页：故障诊断命令

2）给某条命令绑定专属解析脚本

快捷发送的脚本与参数列非常适合做“命令级解析”。

例如：

发送 读取版本号 指令时，切换到“版本解析脚本”
发送 读取传感器 指令时，切换到“传感器数据解析脚本”

这样不同命令可以自动套用不同的接收显示逻辑，减少手工切换。

3）注意全局发送脚本仍然生效

“更多设置”中的 发送处理 Lua 脚本 对快捷发送同样生效。也就是说：

先执行全局发送处理脚本
再根据本行配置发送出去
如本行绑定了接收脚本，则切换对应接收显示处理逻辑

6. 更多设置

点击主界面的 更多设置，可打开高级设置窗口。

该窗口主要分为三部分：

串口基本设置
处理发送数据的脚本
接收页（用于接收数据显示处理）

6.1 串口基本设置

常用设置项说明

自动恢复被断开的串口连接：串口异常断开后尝试自动恢复。
打开串口收发日志目录：快速打开日志保存目录。
串口数据显示方式：选择“文本 / HEX / 同时显示”。
显示串口发送出去的数据：是否在日志中显示发送数据。
显示原始发送数据：用于排查脚本处理前后的差异。
窗口保持置顶显示：软件窗口置顶。
分包数据超时时间：控制收包分帧逻辑；负数表示不分包。
超时时间表示空白间隔：使用“空闲间隔”而不是“从首字节开始计时”。
终端模式：选中日志区后，可直接敲键盘向串口发数据。
数据位长度 / 停止位 / 校验位：配置串口参数。
字符编码：配置文本发送/显示所使用的编码。

关于分包超时的理解

这个选项非常重要，尤其在二进制协议调试中：

正数：按设定超时对接收数据进行分包显示
负数：关闭分包模式，收到什么就直接连续处理

如果你发现日志被拆得太碎，或者一帧数据被分成多段显示，可以尝试调大超时时间。

关于终端模式

开启 终端模式 后，选中日志区即可直接通过键盘发送数据：

普通按键：发送对应 ASCII 字符
Ctrl + A ~ Ctrl + Z：可发送控制字符

这对调试 shell、命令行设备、透传模块时非常方便。

6.2 处理发送数据的脚本

该页用于在数据真正发出之前，通过 Lua 对发送内容进行二次处理。

输入与输出规则

输入变量：uartData
输出结果：脚本 return 的内容

该脚本会作用于：

主界面输入框发送
快捷发送区发送

该脚本不会作用于：

独立运行脚本中主动输出的数据

最简单的脚本


return uartData

常见示例 1：自动加回车换行


return uartData .. "\r\n"

说明：如果你已经勾选了主界面的“发末尾加回车换行”，就不建议再在脚本里重复追加，避免出现双重换行。

常见示例 2：把输入的 HEX 字符串转成真实字节发送


return uartData:fromHex()

例如输入：


30 31 32 33

实际发送结果就是字符串：

常见示例 3：把逗号分隔值包装成 JSON


json = require("JSON")

local t = uartData:split(",")

return json:encode({

key1 = t[1],

key2 = t[2],

key3 = t[3],

})

适合上位机快速构造 JSON 测试报文。

6.3 接收页（接收数据显示处理）

该页用于在数据显示到左侧日志区之前，先用 Lua 做一次处理或格式化。

输入变量

uartData：当前接收到的数据
uartPara：快捷发送条目中传入的参数
uartSendRaw：发送脚本处理前的原始发送字符串

输出规则

脚本 return 的内容会作为最终显示内容。

生效范围

该脚本仅对数据显示页面有效，不会影响运行脚本接口收到的数据。

示例：给每条显示增加长度前缀


return ("len=%d | "):format(#uartData) .. uartData

示例：按不同参数切换显示格式


local para = uartPara and tostring(uartPara) or ""

if para == "hex" then

return uartData:toHex(" ")

end

return uartData

这非常适合配合快捷发送的“参数”列，给不同命令配置不同的接收显示逻辑。

7. 发送脚本、接收脚本、运行脚本的区别

这一点非常重要，很多人第一次上手都会在这里绕两圈——文档先把坑填上。

发送处理脚本
作用时机：发送前
适用范围：主输入框、快捷发送
能力特点：主要用于改写待发送内容
接收处理脚本
作用时机：显示前
适用范围：左侧数据显示区
能力特点：主要用于格式化、解析、显示优化
运行脚本
作用时机：独立运行
适用范围：整个软件运行环境
能力特点：支持任务、定时器、日志、API 调用

请特别注意：

发送处理脚本 不适合做复杂后台任务
运行脚本 才是自动化、协议处理、定时发送的主战场
接收处理脚本 更像一个“显示层解析器”

8. 运行脚本

8.1 截图

8.2 适合做什么

运行脚本页是 HICom 最强大的部分，适合用来做：

串口自动应答
定时发送指令
按协议解析收发数据
自动测试流程
多通道联动（串口、MQTT、TCP 等）
数据采集并绘制曲线

8.3 常用操作

从界面和源码可确认该区域支持以下操作：

新建脚本
运行脚本
打开脚本目录
刷新脚本列表
查看接口文档
打开社区脚本页
停止运行 / 退出运行
重新载入代码并运行
暂停打印或继续打印日志
实时执行一行 Lua 语句

8.4 脚本保存与编辑说明

脚本文件会自动保存，因此建议：

尽量在 HICom 内部编辑脚本
如果同时在外部编辑器中修改同一个文件，注意保存覆盖问题
切换脚本、窗口失焦、程序退出时，HICom 会尝试自动保存

8.5 Lua 环境说明

根据项目文档，HICom 内置：

Lua 5.3 运行环境
基于 xlua，可调用部分 C# 能力
log 日志接口
sys 任务/定时器/消息机制
apiSend、apiSetCb 等软件扩展接口

8.6 推荐入门示例

示例 1：收到串口数据后打印出来


apiSetCb("uart", function(data)

log.info("uart", data)

end)

示例 2：每秒自动发送一次 AT 指令


sys.timerLoopStart(function()

apiSend("uart", "AT\r\n")

end, 1000)

示例 3：串口收包后自动回发 ACK


apiSetCb("uart", function(data)

log.info("recv", data)

apiSend("uart", "ACK\r\n")

end)

8.7 常用接口速查

下面列出最常用的一组接口：

apiSend(channel, data[, table])：向指定通道发送数据
apiSetCb(channel, callback)：订阅某个通道的数据回调
apiUnsetCb(channel, callback)：取消订阅
apiGetPath()：获取软件目录路径
apiQuickSendList(id)：读取快捷发送区某条数据
apiInputBox(...)：弹出输入框
apiAddPoint(num, line)：向曲线页面添加点
log.info / warn / error：输出日志
sys.taskInit(...)：创建任务
sys.wait(...)：任务延时
sys.timerLoopStart(...)：循环定时器
sys.publish / subscribe：消息发布与订阅

9. 社区脚本

9.1 截图

9.2 用途

社区脚本页用于获取他人分享的脚本示例，也可以作为寻找行业协议样例、设备解析脚本、自动化脚本模板的入口。

适合做的事情：

参考别人如何解析某类设备协议
直接复用现成脚本作为起点
学习 HICom Lua 环境下的写法

如果你的场景和截图中的示例相似（如 NMEA、文件传输、MQTT 主题处理等），建议优先从社区脚本开始改，而不是从空白脚本手搓一切。

10. 小工具

10.1 截图

10.2 小工具组成

HICom 的“小工具”并不是点缀，而是一整套联调辅助工具箱：

socket客户端：用于测试 TCP/UDP/SSL 等客户端连接。
socket公共服务端：快速进行网络连通性测试。
本机TCP服务端：在本机启动 TCP 服务端，等待客户端连接。
本机UDP服务端：在本机启动 UDP 服务端接收数据。
编码转换工具：进行 ASCII / HEX / 文本等互转。
MQTT：进行 MQTT 连接、订阅、发布测试。
乱码修复：尝试恢复字符编码错乱后的文本。
串口监听：监听其他软件正在使用的串口通信。
曲线：以图形方式展示数据变化。
WinUSB：调试 WinUSB 设备收发端点。

10.3 几个常见用法

1）socket客户端

适合验证：

TCP 服务是否在线
UDP 数据是否能正常发出
SSL/TCPSSL 连接是否成功
IPv6 场景是否通畅

2）MQTT

适合验证：

Broker 地址、端口、Client ID 是否正确
主题订阅是否成功
发布的数据格式是否正确
TLS / WebSocket / 认证参数是否有效

3）乱码修复

当你拿到一串已经“看起来像乱码”的文本时，可在这里尝试：

指定原编码
指定被误当成的编码
查看恢复结果

4）串口监听

用于观察其他软件对串口的收发情况，适合定位：

某个厂家工具到底发了什么指令
同一设备在官方工具下的通信流程
第三方软件是否真的把数据发出去了

5）曲线

如果你的脚本需要显示实时数据趋势，可通过 Lua 接口：


apiAddPoint(12.3, 0)

apiAddPoint(15.8, 1)

将不同数据绘制到不同线条上，便于观察传感器或设备状态变化。

11. 典型使用场景

11.1 调试 AT 指令设备

建议配置：

文本发送
勾选 发末尾加回车换行
开启发送日志显示
需要时把常用命令放入快捷发送

例如可建立一页包含：

AT
ATI
AT+CSQ
AT+CGSN

11.2 调试二进制协议

建议配置：

勾选 发Hex
显示方式改为“同时显示 Hex 和文本数据”
根据协议特征调整分包超时时间
需要时在接收页写脚本，把二进制数据解析为可读文本

11.3 做自动回包测试

推荐使用“运行脚本”页：

订阅串口接收
判断报文内容
自动回复 ACK 或构造回包
记录通过/失败日志

11.4 做产测或重复性测试

推荐组合：

快捷发送：存放测试步骤命令
运行脚本：控制流程、判断结果
曲线页：观察关键数值变化
日志目录：留存测试记录

12. 日志、脚本与数据文件

12.1 日志

串口收发日志可在“更多设置”中点击 打开串口收发日志目录 查看
Lua 运行日志会在运行脚本页实时显示
当日志过多时，界面可能自动清理部分内容以保证流畅性

12.2 脚本目录

通常会涉及以下脚本类别：

user_script_run：运行脚本页使用的脚本
user_script_send_convert：发送处理脚本
user_script_recv_convert：接收显示处理脚本

如果你不想手动找路径，可直接使用界面中的“打开脚本目录”或对应按钮。

12.3 快捷发送数据

HICom 自有导出格式：.lclst
支持导入 SSCOM 配置文件
建议将常用列表按项目或设备分类备份

13. 常见问题与排查建议

13.1 串口打不开

请优先检查：

串口是否被其他软件占用
设备是否刚插入，还没枚举完成
串口号是否变化，先点 刷新串口
参数是否正确（波特率、数据位、校验位、停止位）

13.2 发送了但设备没反应

请检查：

是否需要勾选 发末尾加回车换行
是否误开了 发Hex
发送脚本是否修改了原始数据
字符编码是否正确
设备是否需要 RTS / DTR 特定状态

13.3 日志看起来像乱码

建议依次尝试：

在“更多设置”里更换字符编码
将显示模式切换为同时显示 HEX 和文本
使用“小工具”中的 乱码修复 功能

13.4 发送处理脚本报错

常见原因：

Lua 语法错误
返回值类型不符合预期
把运行脚本页的接口直接照搬到发送处理脚本里使用

请记住：发送处理脚本 与 运行脚本 的能力边界不同。

13.5 快捷发送某行的脚本没生效

请检查：

是否已为该行选择脚本
脚本文件是否仍存在
参数是否正确传入
你想要的是“接收显示处理”，还是“发送前处理”

很多时候，问题不是“没生效”，而是脚本类型选错了。

14. 使用建议

如果你希望用得更顺手，推荐以下实践：

文本协议：主输入框 + 快捷发送
二进制协议：HEX 发送 + 接收显示脚本
自动化测试：运行脚本 + 日志 + 快捷发送
联调网络业务：串口 + TCP/UDP/MQTT 组合使用
协议解析展示：接收脚本 + 曲线页 + 参数列

15. 结语

HICom 的学习曲线主要集中在 Lua 相关能力上；一旦理解了“发送脚本 / 接收脚本 / 运行脚本”三者的分工，它就不再只是串口工具，而是一个可扩展的调试工作台。

建议你的上手顺序是：

先熟悉普通串口收发
再使用快捷发送整理常用命令
接着尝试发送脚本与接收脚本
最后进入运行脚本，实现自动化调试

如果你需要进一步开发自动化能力，建议继续深入了解 HICom 的 Lua 接口与脚本能力。