将自定义 TC4 文本协议设备接入 HiBean
当烘焙机、控制器或转接板使用逐行文本命令通讯，但 HiBean 里没有对应的专属设备入口时，可以使用 TC4 自定义。你需要自行定义通讯方式、初始化指令、状态帧、字段含义，以及在确保安全时使用的手动控制模板。
这不是自动识别流程。HiBean 不会猜测设备指令和字段顺序，开始前请准备好厂家协议资料。
如果 HiBean 已经列出你的具体设备或固件，请优先使用专属入口。TC4 模块页面介绍的是 HiBean 已适配的专属 TC4 模块；本指南只适用于 TC4 自定义。
这个流程是否适合你的设备？
满足以下条件时再使用 TC4 自定义：
- 设备收发 UTF-8 文本消息；
- 协议明确规定了消息分隔符，通常是
\n、\r\n或\r； - 一条状态指令可以稳定返回带分隔符的完整状态帧；
- 已知哪个字段是豆温（BT）；
- 需要启用控制时，已经掌握控制指令、允许范围、反馈字段和安全值。
你可以从空白配置开始，也可以导入 HiBean JSON 模板。
导入模板只会预填表单，不会带入连接、读取、baseline 或控制证明。导入和编辑后的配置都必须在当前设备上重新完成全部验证。
平台与通讯方式
| 平台 | Socket / WebSocket | BLE | 经典蓝牙 SPP | 串口 |
|---|---|---|---|---|
| Android | 支持 | 支持 | 支持 | 不支持 |
| iOS | 支持 | 支持 | 不支持 | 不支持 |
| macOS | 支持 | 支持 | 支持 | 支持 |
| Windows | 支持 | 支持 | 支持 | 支持 |
模板可能包含当前平台不可用的通讯方式。HiBean 可以读取这些初值，但必须改为当前平台支持的方式并重新验证，才能保存设备。
开始前需要准备什么
| 范围 | 需要准备的资料 |
|---|---|
| 通讯方式 | IP 和端口、蓝牙标识符与 UUID，或串口及串口参数 |
| 组帧 | 状态指令、消息分隔符和轮询间隔 |
| 初始化 | 连接后需要按顺序发送的可选指令，每行一条 |
| 读取字段 | 字段分隔方式、厂家文档使用的索引口径、字段含义和数值格式 |
| 控制 | 指令模板、开关或范围模式、最小值、最大值、步进、测试值、安全值和同语义反馈字段 |
开始控制验证前，确认设备已经上电、处于空闲状态，并且测试动作不会造成点火、进豆、排豆或其他危险。
1. 选择通讯方式
新建配置后，选择设备和当前平台都支持的通讯方式。
Socket 和 WebSocket
填写设备的主机地址和端口。WebSocket 还需要填写协议规定的路径。确认电脑和设备网络互通，且端口没有被防火墙拦截。
BLE
选择 BLE 设备，填写服务 UUID 和写特征 UUID。只有固件通过通知特征返回状态时，才填写可选的通知特征 UUID。
经典蓝牙 SPP
先在操作系统中完成配对，再在 HiBean 中选择对应的 SPP 标识符。iOS 不支持经典蓝牙 SPP。
串口
选择当前系统中的串口，再按厂家资料填写波特率、数据位、停止位、奇偶校验和流控制。
本指南截图使用 macOS PTY 模拟器端口 /dev/ttys007。真实硬件应选择设备或转接器创建的端口。Debug 串口路径只用于开发环境，不属于正式版本的正常接入流程。
点击 连接设备。这一步验证 HiBean 能打开当前通讯方式并发送初始化指令，但还不能证明状态指令、字段映射或控制配置正确。
2. 读取并映射状态帧
填写读取指令、刷新间隔、消息分隔符和可选初始化指令，然后点击 读取状态 获取一个完整帧。
本指南使用的模拟器返回：
25.0,195.0,180.0,0,0,0,0,0在这个开发示例中，数据段 3（从 0 开始的 index 2）映射为豆温，数据段 4（从 0 开始的 index 3）映射为加热器功率反馈。
READ、这组帧格式和字段索引都只是模拟器示例，不是通用 TC4 标准。请按你的设备资料确定指令、分隔符、字段顺序，以及整数或小数解析格式。
必填映射与 baseline
- 豆温（BT）必填。
- 不认识或不用的数据段保持“未标记”。
- 启用某个控制前，先映射与它同语义的反馈数据段。
- 映射完成后建立 baseline，HiBean 会连续完成三轮完整读取。
修改通讯方式、指令、分隔符、解析格式或字段含义后，旧的连接证据、baseline 和控制证明都会失效，必须重新完成受影响步骤。
3. 只在需要时添加控制
如果只需要温度和曲线，保持所有控制关闭后继续。这也是面对不熟悉固件时更安全的起点。
只有掌握以下资料时才启用控制：
- 准确的指令模板；
- 开关或数值范围模式；
- 允许的最小值、最大值和步进；
- 设备空闲时安全的测试值；
- 安全恢复值；
- 与控制项表达同一物理量的状态反馈字段。
模拟器示例使用：
模板：OT1;{value}
范围：0..100
步进：1
测试值：50
安全值：0
HiBean 会发送 50，读取加热器反馈 50，再发送安全值 0 并读取反馈 0。只有两次读回都匹配，才会签发控制证明。
写入结果未知时立即停止
如果请求超时、连接关闭、状态帧无法解析或反馈不匹配，不要连续重发控制指令，也不要猜测安全值是否已经生效。先观察设备并人工恢复到安全状态，再从已知状态重新验证。
自定义控制只授权给已经验证的实时手动操作。自动化、回放、自动冷却和软件 PID 都不能调用用户定义的控制模板。
4. 检查并创建设备
最后一页填写设备名称，并确认通讯、三轮完整读取和每个已启用控制都已经验证。
创建设备时，HiBean 会关闭配置阶段的临时 probe，保存严格配置和本地控制证明，再构建正式运行实例。后续修改配置或出现写入结果未知时，控制授权可能被撤销。
5. 添加后编辑、导入或导出
进入 TC4 自定义设备的 设备设置。
- 编辑配置会预填当前配置，完成全部验证后原位更新同一设备。
- 导入模板并编辑会把 JSON 模板作为编辑初值，并要求重新完成全部验证。
- 导出配置会保存一份可移植的 JSON 模板。
- 连接方式和连接设置显示当前设备使用的通讯配置。
取消编辑或编辑失败时，HiBean 会保留或恢复旧设备。编辑成功后，设备 ID、云端 ID、设备数量和列表位置保持不变。
JSON 模板包含什么
模板是 UTF-8 JSON，envelope 固定为：
{
"kind": "hibean.tc4.custom.profile",
"profileVersion": 1,
"config": {}
}模板包含通讯初值、初始化指令、状态轮询与字段映射，以及控制模板和范围。它不包含：
- 设备名称、设备 ID 或云端 ID；
- 当前设备归属、连接缓存或运行状态；
- 原始样本和 baseline 结果；
- 控制证明或控制授权。
遇到未知字段、不支持的版本、未知枚举、非法范围或非法映射时，HiBean 会拒绝导入，不会宽松套用。
常见问题
通讯已连接，但读取状态失败
检查指令结尾、响应分隔符、UTF-8 编码、初始化指令顺序，以及是否有其它程序正在轮询同一设备。
能看到状态帧，但 baseline 无法完成
确认每个已映射数据段在三次读取中都存在，且含义和数值格式保持一致。不要映射会在不同响应中消失的可选尾部字段。
控制验证无法通过
确认模板包含 {value}，测试值符合范围与步进，反馈字段与控制项表达同一物理量。如果反馈始终保持安全值，应判定验证失败，不能强行进入 Review。
共享模板里的通讯方式在当前平台不可用
改为当前平台和设备共同支持的通讯方式，再重新完成全部验证。模板不携带平台授权或验证证据。
截图与模拟器的证据边界
本指南截图来自 macOS Debug App，并使用 HiBean 的 generic-roaster PTY 模拟器。它直接验证了 TC4 自定义正式入口、真实串口连接器、状态映射、三轮 baseline、加热器 50 → 0 控制证明、设备创建和设置入口。
它不能证明 USB 驱动、电气接线、厂家固件、真实烘焙机安全性，也不能替代 Android、iOS 和 Windows 的用户验收。