自定义 TC4：让 Agent 生成配置，再导入 HiBean
把设备协议资料交给 Agent，生成一份 HiBean 配置 JSON，然后在 自定义 TC4 中导入。你不必自己逐项编写 JSON，但仍需要在实际设备上验证连接、读数和需要启用的控制。
本指南按 2026-10-19 的 App 1.5.4+189 代码核对。JSON 格式版本仍是 profileVersion: 1、schemaVersion: 2；它们不是 App 版本号。
如果 HiBean 已有对应机型或固件的专属入口，优先使用专属入口。TC4 模块与这里的自定义接入是两个入口。
先确认设备适合接入
自定义 TC4 支持 UTF-8 文本命令和数值状态帧。状态帧的字段固定用英文逗号分隔，必须能找到摄氏豆温字段；JSON 不提供温度单位换算。串口、Socket、BLE 和经典蓝牙的回复需要有换行结束符；WebSocket 可以用一条完整消息作为一帧。
只有二进制协议、Modbus 寄存器、JSON 对象回复，或必须用正则表达式、缩放公式才能得到豆温的设备，不能仅靠这份模板接入。Modbus 设备请看自定义 Modbus RTU。
| 平台 | Socket / WebSocket | BLE | 经典蓝牙 SPP | 串口 |
|---|---|---|---|---|
| Android | 支持 | 支持 | 支持 | 不支持 |
| iOS | 支持 | 支持 | 不支持 | 不支持 |
| macOS / Windows | 支持 | 支持 | 支持 | 支持 |
这是 App 允许配置的范围，实际连接还取决于系统、驱动和设备。当前自定义 TC4 流程不支持 Linux。
把这些资料交给 Agent
| 资料 | 需要说明什么 |
|---|---|
| 设备与软件 | 型号、固件版本、使用 HiBean 的平台和版本 |
| 通讯参数 | IP/端口、WebSocket 路径，或串口参数；BLE 还要设备标识、服务 UUID、写特征和通知特征 |
| 状态协议 | 读取指令、指令结尾、回复结尾、是否需要初始化指令 |
| 原始回复 | 至少一条未经改写的完整回复，保留逗号、空字段和结束符；最好提供连续三条 |
| 字段含义 | 哪一段是豆温、单位是什么，以及其它需要记录的字段 |
| 使用目标 | 只采温画曲线，还是还需要手动控制火力、风量、滚筒或冷却风扇 |
| 控制资料（按需） | 控制指令、范围、步进、同语义反馈字段、允许的测试值和安全恢复值 |
厂家协议、固件源码和真实收发记录最有用。设备名称相似、别人的模板或 BLE 连接成功，都不能证明状态指令和字段顺序相同。
把下面这段话连同资料交给 Agent；同时提供链接指向的 Agent JSON 配置参考，或复制该页全文：
请依据 HiBean 的《TC4 自定义：Agent JSON 配置参考》和我提供的设备资料，
生成一个 UTF-8 .json 文件，供我在 HiBean 的自定义 TC4 中直接导入。
我的平台和 App 版本：
设备型号和固件版本：
我的目标（只采温 / 采温加哪些手动控制）：
通讯参数、协议资料、原始回复：
请先核实设备协议是否符合当前 JSON 能力。
必填资料缺失时先列出具体缺口，不要猜测 READ、字段索引、UUID 或安全值。
只采温时使用空 actuators；需要控制时必须核实控制指令和同语义反馈。
请将配置 JSON、字段来源与假设、导入后的验证步骤分开交付，
不要把说明、测试值、设备名称或验证结果写进 JSON。
说明哪些只通过了格式检查，哪些有真实设备证据。Agent 可以完成字段整理、格式转换和一致性检查；真实设备返回什么、哪个值是豆温，仍须由协议资料和读数确认。
1. 导入并连接设备
在添加设备中打开 自定义 TC4，选择导入 JSON 模板，再检查当前机器上的连接目标。换手机或电脑后，BLE 标识和串口名可能需要重新选择。
点击 连接设备。这一步检查通讯链路；BLE 还会查找指定服务和特征。初始化指令在下一阶段读取状态时执行，连接成功还不能证明读取协议正确。
BLE 的服务 UUID 和特征 UUID 是不同字段。例如某些模块使用服务 FFE0、写入 FFE2、通知 FFE1，但这不是通用 TC4 标准，必须以实际服务发现结果为准。不要把 FFE1 填入服务字段。
当前 BLE 读取依赖通知特征。虽然 JSON 允许省略通知 UUID，使用 BLE 接收状态时仍需要正确的通知通道；App 不会自动改用特征的 Read 操作。
2. 读取并确认字段
进入 状态读取，确认读取指令、响应结束符和初始化指令，点击 读取状态。App 会连接设备、依次发送初始化指令，再发送状态读取指令。
例如设备真实返回 180.5,20，且协议说明第一段是豆温、第二段是火力反馈，则分别对应 index 0 和 1。界面“第 1 个数据段”在 JSON 中是 index 0。
豆温必填。其余不需要的字段不映射；需要控制时映射相应反馈字段。然后完成连续三轮完整状态读取，确认每一轮都能解析全部已映射字段。
JSON 中 messageSeparator 是设备回复的结束符；actuatorCommandSeparator 尽管名称含 actuator，实际也决定读取指令和初始化指令的结尾。两者可以不同。若设备要求回车换行，应让 Agent 写入 JSON 的 "\r\n"，而不是把结束符直接拼进 READ。
3. 验证需要启用的控制
只采温时保持所有控制关闭，继续下一步。
启用控制时，设置与安全值不同的测试值并点击验证。App 会发送测试值、读取同语义反馈，再发送安全值并读回；两次都匹配后，该控制才能使用。测试会真实操作设备，应按设备资料选择可测试状态和值。
如果完整反馈与测试值不匹配，App 会尝试恢复并确认安全值，然后判定验证失败。如果写入或读回结果未知，App 不会靠连续重发来猜测状态；请先检查设备，再重新验证。
模板只提供经过验证后可用的手动控制。自动化、回放、自动冷却和软件 PID 不会调用这些自定义控制模板。
4. 选择手动记录参数
没有设备反馈或协议控制的火力、风量、滚筒参数，可以在 手动记录参数 中按需启用，选择单位和上限。它用于记录你在机器上手动调整的值，不会发送控制命令。
同一项已有设备反馈或协议控制时，不能再作为手动记录来源。此设置保存在 App 的设备配置中，不随协议 JSON 模板导入导出；Agent 不能在模板中添加 recordProfile。
5. 检查并保存
填写设备名称，确认通讯、三轮读取、所有已启用控制的验证，以及手动记录设置，然后创建设备。导入文件不会跳过任何验证。
添加后，在设备设置中可以 编辑配置、导入模板并编辑或导出配置。编辑需要暂时断开设备并重新验证；成功后更新原设备。取消或失败时会尝试恢复旧连接，恢复失败需要手动重新连接。
更改通讯或协议字段会清除先前验证。设备名称和手动记录设置不属于可移植协议模板，控制测试值也只在当前验证操作中输入。
示例文件与常见问题
完整字段和示例下载见 Agent JSON 配置参考。示例的 IP、蓝牙标识、串口名及协议假设需要替换；格式正确不代表设备可用。不要把某一台设备的候选模板作为所有 TC4 的默认值。
| 卡住的位置 | 优先检查 |
|---|---|
| 导入失败 | 是否使用完整模板而非 config: {}；版本、字段名、字段类型和换行转义是否正确 |
| 找不到 BLE 服务 | 服务发现列表中是否真的有该 UUID；是否把通知或写特征当作服务 |
| 通讯成功但读不到状态 | 指令结尾、回复结尾、初始化要求、通知通道及是否存在其它程序占用 |
| 看见原始数据但三轮读取失败 | 豆温位置、空字段、非数值字段，以及所有映射在每一帧是否都存在 |
| 控制验证失败 | 测试值/安全值、范围步进和同语义反馈；只采温时无需开启控制 |
反馈问题时提供 App 版本、平台、卡住步骤、页面错误、配置 JSON 和该次操作的日志。较新代码会记录读取命令、回包摘要、超时残留及字段解析错误；旧版本日志缺少这些内容时，不能只根据“蓝牙连接成功”判断后续读取结果。
页面图片用于说明对应操作，来自 macOS Debug 模拟设备；本次文字和 JSON 按上述代码版本核对，不代表这些截图或示例已经完成各平台真实硬件验收。