目录
一快速入门（零基础 7 步上手）
本章节面向第一次使用“unixbuslink配置工具”的人员。按下面 7 步依次操作，即可完成 “连接网关 → 接入设备 → 看到数据 → 映射成 Modbus-TCP 从站 → 通过 MQTT 上传”的完整流程。
unixbuslink配置工具.exe（或打包后的同名程序）；若使用源码，双击
unixbuslink配置工具.pyw。软件无需安装，打开即用。1打开软件并连接网关
软件顶部为连接栏，填写网关连接信息：
| 序号 | 字段 | 填写说明 |
|---|---|---|
| ① | 网关地址 | 网关 IP，如 192.168.1.230 |
| ② | 端口 | 固定 8080 |
| ③ | 用户 | admin |
| ④ | 密码 | admin123 |
| ⑤ | 点击“连接” | 连接成功后提示“已连接”，并自动刷新各页面；可点“断开连接”断开 |
2新增设备
点击顶部“设备列表”页签，再点左侧上方的“新增设备”，右侧“设备编辑”区会清空为待录入状态。
3编辑设备参数
在右侧“设备编辑”表单填写设备参数（以 Modbus-TCP 为例）。表单按 Web 同样的行列布局，字段含义与 Web 完全一致。
| 序号 | 字段 | 说明 |
|---|---|---|
| ① | 设备名称 | 如 demo_meter |
| ② | 协议（大类） | 下拉与协议库关联，如 Modbus |
| ③ | 协议（小类） | 如 Modbus-TCP；选小类后通讯模式自动切换 |
| ④ | IP 地址 | TCP 填设备 IP；串口时此处变为 COM 下拉 |
| — | 端口 / 从站 / 轮询 / 超时 / 重试 | 按设备实际填写 |
| ⑤ | 点击“保存设备(新增/修改)” | 保存后设备出现在表格中 |
4配置采集点位
选中设备后点“采集点位配置”，弹出点位窗口（与 Web 点位页一致）。
| 序号 | 操作 | 说明 |
|---|---|---|
| ① | 在点位表维护点位 | 名称、描述信息、地址、数据类型、长度、缩放 k/差值 a、变化发布 |
| ② | 点“添加点位”新增 | 可复制点位；支持点位模板与 Excel 的导入导出 |
| ③ | 点“保存点位” | 回到设备列表，点“重新加载配置”使网关生效 |
5数据监控验证
点“数据监控”页签，选择设备并刷新，确认采集成功。
| 序号 | 操作 | 说明 |
|---|---|---|
| ① | 设备下拉选择 | 选择刚配置的设备（显示设备 ID 与名称） |
| ② | 点“刷新” | 手动读取一次 |
| ③ | 勾选“监控” | 按刷新频率(秒)周期刷新；切换页签后监控自动停止 |
| ④ | 查看实时值表 | 值正确即采集成功 |
6数据映射（Modbus-TCP 从站）
点“数据映射”页签，把采集数据映射为网关内部的 Modbus-TCP 从站。
| 序号 | 操作 | 说明 |
|---|---|---|
| ① | 勾选“启用数据映射” | 必须启用才生效 |
| ② | 设备下拉选择来源设备 | 选择后左侧自动加载该设备点位 |
| ③ | 点“全选点位添加 / 选中点位添加” | 勾选点位加入右侧映射表，地址自动分配 |
| ④ | 设置 IP / 端口 | IP 为网关本机，端口默认 502 |
| — | 从站地址 / 数据格式 / 首地址 | 按需要设置 |
| ⑤ | 点“保存配置” | 映射生效 |
7MQTT 数据发布
点“系统配置”页签 → 左侧选“MQTT 配置” → 内层选“MQTT 通道1”，配置并保存。字段与 Web MQTT 完全一致。
| 序号 | 字段 | 说明 |
|---|---|---|
| ① | 启用 | 勾选开启通道 |
| ② | Broker 地址 | 域名或 IP，如 59.110.231.49 |
| ③ | 端口 | 1883 |
| ④ | 发布周期(ms) | 如 1000 |
| ⑤ | 单设备前缀 | 如 updata/YCX8FDF9C32/（末尾保留斜杠） |
| ⑥ | 上传模式 | 单网关 / 单设备（二选一） |
| ⑦ | 点“保存配置（生效）” | 开始发布 |
downdata/网关编号）。平台下发写点指令后，网关直接写入对应设备点位，
写入值自动按该点位缩放公式反向换算。写点载荷 {"data":"设备名/点位名","value":"目标值"}；
OTA 可下发 {"action":"ota","url":"升级包地址"}。二网络配置
点“网络配置”页签。页面内容与 Web 一致，分以太网、WiFi、4G/5G 三部分，区域上下对齐、宽度固定， 内容较多时可用鼠标滚轮上下滑动。底部为“读取网络配置 / 保存配置 / 系统重启”按钮（固定在最下方，不会被遮挡）。
- 以太网：双网口时分别配置 eth0、网口2（eth1），各显示当前 IP；静态 IP 需填掩码、网关、DNS。
- WiFi：勾选开启后可扫描无线网络，并配置 IP 与加密方式。
- 4G/5G：勾选开启，提供诊断，结果以表格展示（IMEI、IMSI、CCID、COPS、Lac_ci、信号强度）。
三系统配置
“系统配置”内层为子 Notebook，共 9 个子页签：串口配置、MQTT 配置（内含通道1/2）、缓存配置、时间同步、脚本处理、远程穿透、日志管理、账户密码。 （Web 端系统配置为 8 个页签、无“日志管理”；上位机比 Web 多一个“日志管理”。）
串口配置
启用 COM1/COM2，设置设备、波特率、数据位、停止位、校验位。可“读取串口配置 / 保存串口配置”。
缓存配置（断网续传）
断连时本地缓存，恢复后顺序补传。设置存储方式（文件/SQLite）、单文件大小、Flash 占比上限（默认 85%，满后覆盖最早数据）、 最长存储时间、重连补传间隔。
时间同步
手动/自动 NTP，默认 ntp.aliyun.com，可添加服务器、设置间隔、立即同步。
脚本处理
管理自定义发布/订阅 Json：新建、编辑、删除；编辑器提供示例与变量说明，可测试后保存。
远程穿透 / 日志管理
“远程穿透”配置中继参数（见第四章）；“日志管理”设置日志级别、文件大小、存储，支持查询、停止/继续打印、导出、清理。
账户密码（修改登录密码）
在“账户密码”子页签修改登录密码：先输入旧密码，再输入新密码（不少于 6 位）并确认，保存后下次登录使用新密码； 遗忘后需由工程人员通过串口 / SSH 恢复。
四远程透传（连接隧道）
“远程透传”页签用于在外网经云中继远程访问现场网关。该功能独立运行，不受顶部是否本地连接网关影响。
| 步骤 | 操作 | 说明 |
|---|---|---|
| 1 | 填写中继服务器 IP / 端口 | 如 47.93.54.222 / 9443（WSS 加密，由授权 / 管理员提供） |
| 2 | 填写网关编号、登录密码 | 网关编号即隧道 ID；登录密码为透传密码（授权工具生成） |
| 3 | 确认本地端口 / 网关目标端口 | 本地端口默认 8081，网关目标端口 8080，一般无需修改 |
| 4 | 点击“连接隧道” | 状态变为“已连接”，日志打印 TLS + WS 握手成功、本地监听 127.0.0.1:8081 |
| 5 | 点击“切换到远程连接” | 顶部网关地址自动改为 127.0.0.1、端口 8081，并自动连接网关 |
| 6 | 像在现场一样配置网关 | 各页签操作均经加密隧道转发到现场网关 |
| 7 | 结束点“断开” | 断开隧道；可把顶部地址改回现场网关本地 IP |
http://127.0.0.1:8081，等同于打开现场网关的 Web 页面。五升级重启
点“升级重启”页签，读取当前版本（网关型号、软件版本），进行升级、授权导入与重启。
- 本地上传升级：选择升级压缩包（含应用与协议库，不含配置/缓存），点上传升级，完成后提示并重启应用。
- 远程 OTA：平台下发指令与下载路径，网关下载后自动更新。
- 授权导入：在本地上传升级区域下方，选择授权工具生成的
license.bin导入，导入后回读生效信息。 - 应用重启：仅重启软件（倒计时 5 秒）；系统重启：reboot 操作系统（倒计时 16 秒）。
六授权导入
网关授权由独立的“授权工具”生成。可在“升级重启”页导入 license.bin，或由授权工具一键写入。
- 授权与网关芯片密钥绑定，控制设备数量、采集点数与有效期，并写入网关型号、公司/计算机/项目信息、中继参数与透传密码。
- 运行中新增设备/点位不得超过授权上限，超过提示无法新增；未授权仅可加 1 设备 1 点位测试。
- 授权与本机绑定，把应用拷到其它网关因芯片密钥不匹配而无法使用。
七附录：默认参数、表格编辑与常见问题
表格直接编辑（像 Excel 一样）
本工具的表格（点位、映射、系统配置等）支持双击单元格直接编辑：文本单元格双击后直接输入， 带下拉项的单元格双击后直接选择，无需弹窗。表格内容居中显示，表头与网格线清晰。
常用默认参数
| 项目 | 默认值 |
|---|---|
| 网关端口 | 8080 |
| 登录账号 / 密码 | admin / admin123 |
| Modbus-TCP 从站 / 端口 | 地址 1 / 502 |
| MQTT 端口 / 默认周期 | 1883 / 10000ms |
| 远程透传本地端口 / 中继端口 | 8081 / 9443（WSS） |
| 串口参数 | 9600 / 8 / N / 1 |
| NTP / 缓存上限 | ntp.aliyun.com / Flash 85% |
常见问题
| 现象 | 排查方向 |
|---|---|
| 点连接提示超时/无反应 | 确认网关 IP、端口 8080、账号密码；电脑与网关网络互通 |
| 双击 exe 打不开 | 检查是否被杀毒拦截；改用源码 .pyw（需 Python 环境） |
| 设备/点位、监控、映射下拉为空 | 先连接网关并点刷新；映射页选择设备后才加载点位 |
| 设备离线 / 值为 0 | 核对协议、IP/端口或串口/从站、波特率、接线与设备供电 |
| MQTT 收不到 | Broker、端口、主题（前缀末尾保留“/”）、上传模式、防火墙 |
| 连接隧道后连不上网关 | 网关穿透已启用、编号/密码已中继同步、本地端口 8081 未被占用 |
| 无法新增设备/点位 | 已达授权上限，需重新授权 |