本文档由当前目录中的 ESP32-S3 固件源码反向整理，目标是支持 App、小程序和业务后台完成设备扫码、BLE 配网、账号绑定、MQTT 控制、状态展示和检测结果入库。

整理日期：2026-08-07。

1. 适用设备

天权 AE 和天权 PRO AF 的 BLE 名称完全相同，不能靠广播名判断具体型号。型号应来自机身二维码或业务后台的产品档案。

2. 文档导航

1. 设备绑定与 BLE 配网：首次入网、GATT UUID、配网 JSON、成功判定、重新配网和解绑。
2. 天玑 AB API：KH/钙/镁设备的控制与数据字段。
3. 天权 AE API：KH/钙/镁设备的控制与数据字段。
4. 天权 PRO AF API：KH/钙/镁设备的控制与数据字段，固件 1.3.7。
5. 天枢 AH API：六参数设备及真实 PH/ORP 数据字段。
6. 天璇 AG API：六参数设备及真实 PH/ORP 数据字段。
7. 摇光 AI API：NO3/PO4 设备的控制与数据字段。

每个型号均按源码独立整理成一份 API 文档，包含通信入口、上行 JSON、下行指令、进度键、错误码和源码依据。

3. 最短接入路径

上层应用至少要实现下面这条链路：

1. App 扫描机身二维码，从后台取得 productCode、短 clientid、下行主题、上行主题和 MQTT 地址。
2. 后台先订阅该设备的上行主题，并把绑定记录置为 provisioning。
3. App 连接设备 BLE，把 Wi-Fi 与 MQTT 七个字段写入 RX 特征。
4. 设备保存参数并重启。BLE 断开只表示设备可能已重启，不代表绑定一定成功。
5. 后台在上行主题收到合法 JSON，校验 ID，保存设备的三组参数快照并把绑定记录原子更新为 bound。
6. App 以后只调用业务后台；由后台向设备专属下行主题发 MQTT，并把上行数据转成 App 可消费的统一模型。

4. 必须先确认的量产阻断项

设备 ID 存储存在地址冲突。 固件把 clientid 保存到 EEPROM 150 后，又复制到 EEPROM 500，但业务数据从 510 开始。AB、AE、AF、AH、AG 还会从 500 再次读取 ID。超过 9 个 ASCII 字节的 clientid 会与业务区重叠，可能造成 ID 乱码、MQTT 重连失败或业务参数被覆盖；源码示例中的 15 位 ID 本身就会触发该问题。

量产固件应取消 EEPROM 500 的副本及二次读取，或重新规划不重叠的地址。固件修复前，临时联调只能使用不超过 9 个 ASCII 字节的唯一 clientid；这只是兼容措施，不应代替固件修复。摇光 AI 未启用从 500 反读 ID，但仍存在写入重叠。

另外，当前固件还有这些协议级限制：

• BLE 没有配对、鉴权、设备证书或不可变硬件 ID。
• MQTT 使用明文 TCP，只有 Client ID，没有用户名、密码、TLS 和遗嘱消息。
• 下行 JSON 不校验 ID，设备隔离完全依赖唯一的下行主题。
• 发布和订阅均按 QoS 0 使用，没有通用请求 ID、ACK 或离线补发。
• 当前固件没有“主动查询全部状态”指令；三组快照主要在启动及部分设置变更后上报。
• 多个数值字段会以 JSON 字符串返回，PH/ORP 异常时还可能返回 ".."。上层必须宽容解析。

5. 协议使用约定

• 本文把设备订阅的 mqtttopic 称为“下行主题”，把设备发布的 pubtopic 称为“上行主题”。
• 示例中的 productCode、绑定令牌、用户权限和 HTTP 接口属于推荐的业务后台设计，不是现有固件字段。
• 所有动作命令默认都是非幂等的。检测、加液、泵动作、清洗、校准、恢复出厂和 OTA 不得使用 retained MQTT 消息，也不能在超时后自动盲重发。
• 除特别说明外，开关枚举使用 10 表示开启，20 表示关闭；检测模式使用 10 表示高精度，20 表示普通。
• 每次 MQTT 下行只发送一个动作或一个完整设置组，不要把检测、设置、OTA 等混在同一 JSON 中。

6. 源码依据

通用配网代码位于各型号的 Config_net.h 和 Config_eeprom.h；MQTT 指令入口位于各主程序的 Analyze_json()；周期、滴定和检测结果分别位于 Set.ino、DOS.ino、Detect.ino。本文档只描述当前源码能确认的行为，未把注释掉的代码当作已支持接口。

1. 绑定原则

当前固件不能通过 BLE 读取出厂序列号，也不会证明自身身份。clientid 是 App 写入的可变字符串，之后同时作为 MQTT Client ID 和所有上行 JSON 的 ID。

因此推荐把“产品身份”和“联网结果”分开处理：

• 产品身份由机身二维码、包装码或后台出厂档案确定。
• BLE 仅负责把 Wi-Fi、MQTT 路由和后台分配的短 clientid 写入设备。
• 是否配网成功，以后台在预期上行主题收到该设备首个合法上报为准。

2. 进入配网模式

设备仅在 EEPROM 网络配置标志为空时启动 BLE：

• 新设备或网络配置已清除：开机后进入 BLE 配网并持续广播。
• 已配网设备：开机后直接连接旧 Wi-Fi/MQTT，不同时广播 BLE。
• Wi-Fi 密码错误：设备约 41 秒后结束首次等待，但不会自动回到 BLE，之后仍会用旧参数重试。

重新配网时，长按设备的网络重置键约 2 秒后松开。固件会清除 EEPROM 0～498 的网络参数并重启进入 BLE。该操作不清除业务参数、校准数据和 EEPROM 500 以后的内容。

MQTT 命令 {"HFCC":1} 只恢复业务参数，不清网络配置，不能用于远程解绑。当前固件没有远程清网或远程重新配网 API。

3. 扫描与识别

注意事项：

• 固件没有把 Service UUID 显式加入广播数据。App 不应只用 Service UUID 扫描过滤；应扫描全部附近设备或先按名称过滤，连接后再做服务发现。
• BLE 名称不含序列号。多台同型号同时上电时，名称无法区分，推荐扫码后只让目标设备进入配网，或结合距离/RSSI 和实体指示确认。
• AE 与 AF 广播名相同，具体型号必须由二维码或后台产品档案确定。

4. GATT 定义

六个型号完全一致：

RX 只支持普通 Write，App 应使用 write-with-response。固件没有配置 BLE 配对或鉴权。

连接后，TX 大约每 3 秒通知一个自增的单字节计数器，数值从 0 到 255 循环。它只能用于判断 BLE 链路仍存活，不是配网进度或成功 ACK。

5. 配网 JSON

把一个 UTF-8、无 BOM 的紧凑 JSON 对象写入 RX。七个字段全部必填、非空：

兼容当前未修复固件的短字段示例：

{"ssid":"WF-IOT","password":"wf-iot-2026","clientid":"AB240001","mqtttopic":"d/AB240001/d","pubtopic":"d/AB240001/u","mqttserver":"192.168.1.20","mqttport":1883}

固件只在启动时从 EEPROM 读取每个网络字符串的前 30 个字节，写入时却不做边界检查。超过 30 字节会在重启后被截断；更长字符串还可能覆盖相邻配置。App 必须按 UTF-8 字节数而不是字符数校验，量产配置优先只使用 ASCII。

6. 写入与分包

固件从收到 { 开始累计字节，遇到第一个 } 就立即解析，没有换行符或长度前缀。配网对象必须是扁平 JSON，不要在字符串值中使用 }。

固件的 BLE 聚合缓存会在主循环中被错误地反复清空，因此慢速分包不可靠：

1. 连接后尽量协商较大的 MTU。
2. 使用紧凑 JSON，不加空格和换行。
3. 优先在一次 write-with-response 中发送完整 JSON。
4. 平台必须分包时，按字节顺序连续写入，第一片以 { 开始、最后一片以 } 结束，并在约 3 秒内完成全部片段。
5. 不要并发写，也不要在同一连接里混入其他数据。

7. 成功与失败判定

七个字段有效时，设备会保存配置，等待约 1 秒，然后直接重启。固件没有发送结构化成功响应。字段缺失、空值或 JSON 解析失败时只输出串口日志，不向 App 返回错误。

推荐状态机：

scanning
  → ble_connected
  → provisioning_write
  → waiting_device_reboot
  → waiting_mqtt_uplink
  → bound

判定规则：

• 写入成功：仅表示 GATT 写操作完成。
• 随后 BLE 断开：可视为设备可能已保存并重启，但仍不是最终成功。
• 最终成功：后台在预先订阅的 pubtopic 收到合法 JSON，主题正确，且 ID 与分配值一致。
• 建议等待窗口：至少 60 秒。Wi-Fi 信号差时可由产品定义延长，但不要自动重复写入。
• 超时后提示用户检查 2.4 GHz Wi-Fi、密码、路由器隔离和 MQTT 可达性；需要换参数时必须物理清网后重试。

后台必须在 App 写 BLE 之前订阅上行主题，否则可能错过设备启动时发送的三组参数快照。

8. 后台绑定事务

推荐的数据状态：

建议步骤：

1. 校验二维码的一次性绑定令牌、产品代码和是否已被其他账号占用。
2. 为设备分配全局唯一、最多 9 个 ASCII 字节的临时 clientid，以及互不相同的专属上下行主题。
3. 后台先订阅上行主题，再向 App 返回 BLE 配网参数。MQTT 凭据不应长期暴露给 App；当前固件没有账号密码时，至少只在受控网络或专用接入层使用。
4. 收到首个上行后，在同一事务中保存设备归属、最后在线时间、固件版本和初始快照。
5. 同一二维码重复提交时返回已有绑定结果，不重复分配 Client ID 和主题。

9. 解绑与换网

业务解绑和设备清网是两个动作：

• 业务解绑：后台解除用户与设备的关系、撤销旧主题权限或令旧主题失效。固件没有对应命令。
• 设备清网：用户长按物理网络重置键，让设备删除旧 Wi-Fi/MQTT 配置后重新进入 BLE。

如果只在后台解绑而不清网，设备仍会继续连接旧 MQTT 并上报。若新用户要重新绑定，必须同时完成后台旧权限撤销和设备物理清网。

10. 源码依据

• UUID、特征和 BLE 回调：各型号 Config_net.h。
• 配网字段与保存：各型号 Config_net.h 的 jiexiBTjson()。
• EEPROM 地址和 30 字节读取限制：各型号 Config_eeprom.h 的 saveConfig()、loadConfigs()、readStringFromEEPROM()。
• 物理清网：各型号 Config_net.h 的 longPressStop() 和 clearConfig()。

整理日期：2026-08-08
源码目录：天玑/tianji-AB
固件版本：1.3.6
BLE 名称：天玑DipperConverge
检测能力：KH、钙、镁
相关文档：README、设备绑定与 BLE 配网

1. 通信入口

设备启动并连接 MQTT 后立即发布三组快照 DF_SJSB1()、DF_SJSB2()、DF_SJSB3()，随后发布 {"ID":"...","state":0}。

2. 上行 JSON

所有上行 JSON 都包含 ID。固件没有通用请求 ID、ACK 或离线补发，上层不能依赖“收到响应”判断指令成功。

2.1 数据上报 1：设备状态与参数

2.2 数据上报 2：周期、模式与最新结果

2.3 数据上报 3：余量、PID 与滴定参数

2.4 心跳与实时状态

设备约每 55 秒发布一次心跳。检测、清洗、校准等过程通过动态键上报进度：

{"ID":"AB240001","KHCSW":20}

其中键名是 YXXM 运行项目，值是 XMJC 进度百分比整数。本型号可能出现的键：

微量泵动作还会发布 {"ID":"...","KHBZZ":0} 开始、{"ID":"...","KHBZZ":1,"state":0} 结束；钙和镁对应 GAIBZZ、MEIBZZ。滴定动作完成后会发布 KHDOS、GAIDOS 或 MEIDOS，表示本次滴定液用量。

2.5 错误码

错误上报通常为 {"ID":"...","error":n,"state":0}。

3. 下行指令

将 JSON 发布到设备的 mqtttopic，或通过串口发送同一 JSON。每次只发送一个动作或一个完整设置组。检测、滴定、泵动作、校准、恢复出厂和 OTA 都不是幂等的，不能使用 retained 消息或超时后盲目重发。

3.1 系统指令

时钟校准通过 year 键触发，需要同时提供 month、day、hour、minute、second。成功后上行 {"ID":"...","SZXZ":1}。

{"year":2026,"month":8,"day":8,"hour":10,"minute":30,"second":0}

3.2 检测周期设置

钙和镁使用相同结构：GAIXQ/GAIJCCS/GAIMS、MEIXQ/MEIJCCS/MEIMS。设置成功后设备会重新发布 DF_SJSB2()。

{"KHXQ":[1,0,1,0,1,0,1],"KHJCCS":2,"KHMS":10}

3.3 滴定设置

KH 滴定设置字段：

钙对应 GAIDDCS、GAIRDD、DDBKG、GAILDKG、GAIYSZ、STRL、GAIZDTJ、GAIBC；镁对应 MEIDDCS、MEIRDD、DDCKG、MEILDKG、MEIYSZ、STRL、MEIZDTJ、MEIBC。每个字段可用字符串 "A" 表示“不修改”。设置完成后设备会重新发布三组快照。

3.4 PID 设置

字段：GFP、GFI、GFD、KHP、KHI、GAIP、GAII、MEIP、MEII。数值为两位小数的浮点数，固件会按 0.001 精度比较。完成后重新发布 DF_SJSB3()。

{"GFP":0.4,"GFI":0.2,"GFD":0.05,"KHP":0.4,"KHI":0.2,"GAIP":0.4,"GAII":0.2,"MEIP":0.4,"MEII":0.2}

3.5 检测与校准

3.6 微量泵

3.7 试剂、补充液与滴定点动

4. 接入注意事项

• 固件没有“主动查询全部状态”指令；三组快照主要在启动和部分设置变更后上报。
• 多数数值字段会以 JSON 字符串返回，PH/ORP 相关的本型号为固定值；上层必须宽容解析。
• HFCC 只恢复业务参数，不清网络配置，不能用于远程解绑。
• 检测、校准和泵动作期间不要并发发送其他动作；固件按 Analyze_json() 顺序处理。
• 当前源码的 EEPROM 地址存在 ID 写入重叠风险，量产联调阶段应使用不超过 9 个 ASCII 字节的 clientid，详见 README 第 4 节。

整理日期：2026-08-08
源码目录：天权/tianquan-AE
固件版本：1.3.6
BLE 名称：天权DipperConverge
检测能力：KH、钙、镁
相关文档：README、设备绑定与 BLE 配网

1. 通信入口

设备启动并连接 MQTT 后立即发布三组快照 DF_SJSB1()、DF_SJSB2()、DF_SJSB3()，随后发布 {"ID":"...","state":0}。

2. 上行 JSON

所有上行 JSON 都包含 ID。固件没有通用请求 ID、ACK 或离线补发，上层不能依赖“收到响应”判断指令成功。

2.1 数据上报 1：设备状态与参数

2.2 数据上报 2：周期、模式与最新结果

2.3 数据上报 3：余量、PID 与滴定参数

2.4 心跳与实时状态

设备约每 55 秒发布一次心跳。检测、清洗、校准等过程通过动态键上报进度：

{"ID":"AE240001","KHCSW":20}

其中键名是 YXXM 运行项目，值是 XMJC 进度百分比整数。本型号可能出现的键：

微量泵动作还会发布 {"ID":"...","KHBZZ":0} 开始、{"ID":"...","KHBZZ":1,"state":0} 结束；钙和镁对应 GAIBZZ、MEIBZZ。滴定动作完成后会发布 KHDOS、GAIDOS 或 MEIDOS，表示本次滴定液用量。

2.5 错误码

错误上报通常为 {"ID":"...","error":n,"state":0}。

3. 下行指令

将 JSON 发布到设备的 mqtttopic，或通过串口发送同一 JSON。每次只发送一个动作或一个完整设置组。检测、滴定、泵动作、校准、恢复出厂和 OTA 都不是幂等的，不能使用 retained 消息或超时后盲目重发。

3.1 系统指令

时钟校准通过 year 键触发，需要同时提供 month、day、hour、minute、second。成功后上行 {"ID":"...","SZXZ":1}。

{"year":2026,"month":8,"day":8,"hour":10,"minute":30,"second":0}

3.2 检测周期设置

钙和镁使用相同结构：GAIXQ/GAIJCCS/GAIMS、MEIXQ/MEIJCCS/MEIMS。设置成功后设备会重新发布 DF_SJSB2()。

{"KHXQ":[1,0,1,0,1,0,1],"KHJCCS":2,"KHMS":10}

3.3 滴定设置

KH 滴定设置字段：

钙对应 GAIDDCS、GAIRDD、DDBKG、GAILDKG、GAIYSZ、STRL、GAIZDTJ、GAIBC；镁对应 MEIDDCS、MEIRDD、DDCKG、MEILDKG、MEIYSZ、STRL、MEIZDTJ、MEIBC。每个字段可用字符串 "A" 表示“不修改”。设置完成后设备会重新发布三组快照。

3.4 PID 设置

字段：GFP、GFI、GFD、KHP、KHI、GAIP、GAII、MEIP、MEII。数值为两位小数的浮点数，固件会按 0.001 精度比较。完成后重新发布 DF_SJSB3()。

{"GFP":0.4,"GFI":0.2,"GFD":0.05,"KHP":0.4,"KHI":0.2,"GAIP":0.4,"GAII":0.2,"MEIP":0.4,"MEII":0.2}

3.5 检测与校准

3.6 微量泵

3.7 试剂、补充液与滴定点动

4. 接入注意事项

• 固件没有“主动查询全部状态”指令；三组快照主要在启动和部分设置变更后上报。
• 多数数值字段会以 JSON 字符串返回，PH/ORP 相关的本型号为固定值；上层必须宽容解析。
• HFCC 只恢复业务参数，不清网络配置，不能用于远程解绑。
• 检测、校准和泵动作期间不要并发发送其他动作；固件按 Analyze_json() 顺序处理。
• 当前源码的 EEPROM 地址存在 ID 写入重叠风险，量产联调阶段应使用不超过 9 个 ASCII 字节的 clientid，详见 README 第 4 节。

整理日期：2026-08-08
源码目录：天权/tianquan-PRO-AF
固件版本：1.3.7
BLE 名称：天权DipperConverge
检测能力：KH、钙、镁
相关文档：README、设备绑定与 BLE 配网

1. 通信入口

设备启动并连接 MQTT 后立即发布三组快照 DF_SJSB1()、DF_SJSB2()、DF_SJSB3()，随后发布 {"ID":"...","state":0}。

2. 上行 JSON

所有上行 JSON 都包含 ID。固件没有通用请求 ID、ACK 或离线补发，上层不能依赖“收到响应”判断指令成功。

2.1 数据上报 1：设备状态与参数

2.2 数据上报 2：周期、模式与最新结果

2.3 数据上报 3：余量、PID 与滴定参数

2.4 心跳与实时状态

设备约每 55 秒发布一次心跳。检测、清洗、校准等过程通过动态键上报进度：

{"ID":"AF240001","KHCSW":20}

其中键名是 YXXM 运行项目，值是 XMJC 进度百分比整数。本型号可能出现的键：

微量泵动作还会发布 {"ID":"...","KHBZZ":0} 开始、{"ID":"...","KHBZZ":1,"state":0} 结束；钙和镁对应 GAIBZZ、MEIBZZ。滴定动作完成后会发布 KHDOS、GAIDOS 或 MEIDOS，表示本次滴定液用量。

2.5 错误码

错误上报通常为 {"ID":"...","error":n,"state":0}。

3. 下行指令

将 JSON 发布到设备的 mqtttopic，或通过串口发送同一 JSON。每次只发送一个动作或一个完整设置组。检测、滴定、泵动作、校准、恢复出厂和 OTA 都不是幂等的，不能使用 retained 消息或超时后盲目重发。

3.1 系统指令

时钟校准通过 year 键触发，需要同时提供 month、day、hour、minute、second。成功后上行 {"ID":"...","SZXZ":1}。

{"year":2026,"month":8,"day":8,"hour":10,"minute":30,"second":0}

3.2 检测周期设置

钙和镁使用相同结构：GAIXQ/GAIJCCS/GAIMS、MEIXQ/MEIJCCS/MEIMS。设置成功后设备会重新发布 DF_SJSB2()。

{"KHXQ":[1,0,1,0,1,0,1],"KHJCCS":2,"KHMS":10}

3.3 滴定设置

KH 滴定设置字段：

钙对应 GAIDDCS、GAIRDD、DDBKG、GAILDKG、GAIYSZ、STRL、GAIZDTJ、GAIBC；镁对应 MEIDDCS、MEIRDD、DDCKG、MEILDKG、MEIYSZ、STRL、MEIZDTJ、MEIBC。每个字段可用字符串 "A" 表示“不修改”。设置完成后设备会重新发布三组快照。

3.4 PID 设置

字段：GFP、GFI、GFD、KHP、KHI、GAIP、GAII、MEIP、MEII。数值为两位小数的浮点数，固件会按 0.001 精度比较。完成后重新发布 DF_SJSB3()。

{"GFP":0.4,"GFI":0.2,"GFD":0.05,"KHP":0.4,"KHI":0.2,"GAIP":0.4,"GAII":0.2,"MEIP":0.4,"MEII":0.2}

3.5 检测与校准

3.6 微量泵

3.7 试剂、补充液与滴定点动

4. 接入注意事项

• 固件没有“主动查询全部状态”指令；三组快照主要在启动和部分设置变更后上报。
• 多数数值字段会以 JSON 字符串返回，PH/ORP 相关的本型号为固定值；上层必须宽容解析。
• HFCC 只恢复业务参数，不清网络配置，不能用于远程解绑。
• 检测、校准和泵动作期间不要并发发送其他动作；固件按 Analyze_json() 顺序处理。
• 当前源码的 EEPROM 地址存在 ID 写入重叠风险，量产联调阶段应使用不超过 9 个 ASCII 字节的 clientid，详见 README 第 4 节。

整理日期：2026-08-08
源码目录：天枢/tianshu-AH
固件版本：1.2.9
BLE 名称：天枢DipperConverge
检测能力：KH、钙、镁、钾、NO3、PO4、PH、ORP
相关文档：README、设备绑定与 BLE 配网

1. 通信入口

设备启动并连接 MQTT 后立即发布 DF_SJSB1()、DF_SJSB2()、DF_SJSB3()，随后发布 {"ID":"...","state":0}。

2. 上行 JSON

所有上行 JSON 都包含 ID。固件没有通用请求 ID、ACK 或离线补发。

2.1 数据上报 1：设备状态与参数

字段与 02 文档中天玑 AB 的 DF_SJSB1() 一致，包括：GFKG、DDAKG、DDBKG、DDCKG、GFZS、GFZDZS、KHLDKG、GAILDKG、MEILDKG、GFLDKG、STRL、KHYSZ、GAIYSZ、MEIYSZ、KHBCND、GAIBCND、MEIBCND、KHZDTJ、GAIZDTJ、MEIZDTJ、KHXZYZ、GAIXZYZ、MEIXZYZ、JIAXZYZ、NO3XZYZ、PO4XZYZ、GJBB。

2.2 数据上报 2：周期与模式

当前源码中 KX/KJ/GX/GJ/MX/MJ 结果字段在 DF_SJSB2() 里被注释，KH/钙/镁最新结果不会通过该帧上行。钾、NO3、PO4 结果也没有上行字段。结果仍会写入 EEPROM，但 MQTT 层拿不到，这是当前固件的协议缺口。

2.3 数据上报 3：余量、PID 与滴定参数

字段与 02 文档中天玑 AB 的 DF_SJSB3() 一致，另外包含 QXJSJL（清洗剂余量）。KHDDCS、GAIDDCS、MEIDDCS 为滴定次数；KHSJL、GAISJL、MEISJL、JIASJL、NO3SJL、PO4SJL 为试剂余量；FSTYL、SYXH 为废水桶余量和水样消耗；GFP/GFI/GFD/KHP/KHI/GAIP/GAII/MEIP/MEII 为 PID 参数；KHRDD/GAIRDD/MEIRDD 为每日补充量；KHBCYL/GAIBCYL/MEIBCYL 为补充液余量。

2.4 心跳与实时状态

心跳约每 55 秒发布一次，包含：

过程进度使用动态键：

{"ID":"AH240001","NO3CSW":40}

本型号可能出现的键：

微量泵动作开始/结束会发布 KHBZZ、GAIBZZ、MEIBZZ、JIABZZ、NO3BZZ、PO4BZZ 的 0/1 帧，结束帧带 state:0。滴定动作完成后发布 KHDOS、GAIDOS、MEIDOS。

2.5 错误码

3. 下行指令

将 JSON 发布到设备的 mqtttopic，或通过串口发送同一 JSON。每次只发送一个动作或一个完整设置组。

3.1 系统指令

时钟校准通过 year 键触发，需要同时提供 month、day、hour、minute、second。成功后上行 {"ID":"...","SZXZ":1}。

3.2 检测周期设置

六组参数结构相同：

XQ 是周日到周六的整数数组，1 表示开启，固件内部转为 10；模式字段 10=高精度，20=普通。设置成功后重新发布 DF_SJSB2()。

{"JIAXQ":[1,0,1,0,1,0,1],"JIAJCCS":2,"JIAMS":10}

3.3 滴定设置

KH 滴定设置字段：KHDDCS、KHRDD、DDAKG、KHLDKG、KHYSZ、STRL、KHZDTJ、KHBC。

钙：GAIDDCS、GAIRDD、DDBKG、GAILDKG、GAIYSZ、STRL、GAIZDTJ、GAIBC。

镁：MEIDDCS、MEIRDD、DDCKG、MEILDKG、MEIYSZ、STRL、MEIZDTJ、MEIBC。

每个字段可用字符串 "A" 表示不修改；开关字段 10=开，20=关。完成后重新发布三组快照。

3.4 钙反设置

源码中 GFLDKG 被写入 EEPROM 680，与 GFKG 同一地址，存在覆盖风险；文档按当前代码如实描述，不建议在固件修复前依赖该字段的持久化。

3.5 PID 设置

字段：GFP、GFI、GFD、KHP、KHI、GAIP、GAII、MEIP、MEII。数值为两位小数的浮点数，固件按 0.001 精度比较。完成后重新发布 DF_SJSB3()。

3.6 检测与校准

3.7 微量泵

钾、NO3、PO4 只有正反转指令，当前固件没有对应的 WBXZ 微量泵校准指令。

3.8 试剂、补充液与滴定点动

4. 接入注意事项

• 当前固件不通过 MQTT 上报检测结果值，结果只写入 EEPROM；需要结果入库的方案应在固件侧补发结果字段或改为由串口/其他通道读取。
• PH/ORP 异常时可能返回字符串 ".."，所有数值字段都要宽容解析。
• 没有“主动查询全部状态”指令；三组快照主要在启动和部分设置变更后上报。
• HFCC 只恢复业务参数，不清网络配置。
• 检测、校准和泵动作期间不要并发发送其他动作。
• 同 02 文档：当前 EEPROM 的 ID 存储存在重叠风险，量产联调阶段应使用不超过 9 个 ASCII 字节的 clientid。

整理日期：2026-08-08
源码目录：天璇/tianxuan-AG
固件版本：1.2.9
BLE 名称：天璇DipperConverge
检测能力：KH、钙、镁、钾、NO3、PO4、PH、ORP
相关文档：README、设备绑定与 BLE 配网

1. 通信入口

设备启动并连接 MQTT 后立即发布 DF_SJSB1()、DF_SJSB2()、DF_SJSB3()，随后发布 {"ID":"...","state":0}。

2. 上行 JSON

所有上行 JSON 都包含 ID。固件没有通用请求 ID、ACK 或离线补发。

2.1 数据上报 1：设备状态与参数

字段与 02 文档中天玑 AB 的 DF_SJSB1() 一致，包括：GFKG、DDAKG、DDBKG、DDCKG、GFZS、GFZDZS、KHLDKG、GAILDKG、MEILDKG、GFLDKG、STRL、KHYSZ、GAIYSZ、MEIYSZ、KHBCND、GAIBCND、MEIBCND、KHZDTJ、GAIZDTJ、MEIZDTJ、KHXZYZ、GAIXZYZ、MEIXZYZ、JIAXZYZ、NO3XZYZ、PO4XZYZ、GJBB。

2.2 数据上报 2：周期与模式

当前源码中 KX/KJ/GX/GJ/MX/MJ 结果字段在 DF_SJSB2() 里被注释，KH/钙/镁最新结果不会通过该帧上行。钾、NO3、PO4 结果也没有上行字段。结果仍会写入 EEPROM，但 MQTT 层拿不到，这是当前固件的协议缺口。

2.3 数据上报 3：余量、PID 与滴定参数

字段与 02 文档中天玑 AB 的 DF_SJSB3() 一致，另外包含 QXJSJL（清洗剂余量）。KHDDCS、GAIDDCS、MEIDDCS 为滴定次数；KHSJL、GAISJL、MEISJL、JIASJL、NO3SJL、PO4SJL 为试剂余量；FSTYL、SYXH 为废水桶余量和水样消耗；GFP/GFI/GFD/KHP/KHI/GAIP/GAII/MEIP/MEII 为 PID 参数；KHRDD/GAIRDD/MEIRDD 为每日补充量；KHBCYL/GAIBCYL/MEIBCYL 为补充液余量。

2.4 心跳与实时状态

心跳约每 55 秒发布一次，包含：

过程进度使用动态键：

{"ID":"AG240001","NO3CSW":40}

本型号可能出现的键：

微量泵动作开始/结束会发布 KHBZZ、GAIBZZ、MEIBZZ、JIABZZ、NO3BZZ、PO4BZZ 的 0/1 帧，结束帧带 state:0。滴定动作完成后发布 KHDOS、GAIDOS、MEIDOS。

2.5 错误码

3. 下行指令

将 JSON 发布到设备的 mqtttopic，或通过串口发送同一 JSON。每次只发送一个动作或一个完整设置组。

3.1 系统指令

时钟校准通过 year 键触发，需要同时提供 month、day、hour、minute、second。成功后上行 {"ID":"...","SZXZ":1}。

3.2 检测周期设置

六组参数结构相同：

XQ 是周日到周六的整数数组，1 表示开启，固件内部转为 10；模式字段 10=高精度，20=普通。设置成功后重新发布 DF_SJSB2()。

{"JIAXQ":[1,0,1,0,1,0,1],"JIAJCCS":2,"JIAMS":10}

3.3 滴定设置

KH 滴定设置字段：KHDDCS、KHRDD、DDAKG、KHLDKG、KHYSZ、STRL、KHZDTJ、KHBC。

钙：GAIDDCS、GAIRDD、DDBKG、GAILDKG、GAIYSZ、STRL、GAIZDTJ、GAIBC。

镁：MEIDDCS、MEIRDD、DDCKG、MEILDKG、MEIYSZ、STRL、MEIZDTJ、MEIBC。

每个字段可用字符串 "A" 表示不修改；开关字段 10=开，20=关。完成后重新发布三组快照。

3.4 钙反设置

源码中 GFLDKG 被写入 EEPROM 680，与 GFKG 同一地址，存在覆盖风险；文档按当前代码如实描述，不建议在固件修复前依赖该字段的持久化。

3.5 PID 设置

字段：GFP、GFI、GFD、KHP、KHI、GAIP、GAII、MEIP、MEII。数值为两位小数的浮点数，固件按 0.001 精度比较。完成后重新发布 DF_SJSB3()。

3.6 检测与校准

3.7 微量泵

钾、NO3、PO4 只有正反转指令，当前固件没有对应的 WBXZ 微量泵校准指令。

3.8 试剂、补充液与滴定点动

4. 接入注意事项

• 当前固件不通过 MQTT 上报检测结果值，结果只写入 EEPROM；需要结果入库的方案应在固件侧补发结果字段或改为由串口/其他通道读取。
• PH/ORP 异常时可能返回字符串 ".."，所有数值字段都要宽容解析。
• 没有“主动查询全部状态”指令；三组快照主要在启动和部分设置变更后上报。
• HFCC 只恢复业务参数，不清网络配置。
• 检测、校准和泵动作期间不要并发发送其他动作。
• 同 02 文档：当前 EEPROM 的 ID 存储存在重叠风险，量产联调阶段应使用不超过 9 个 ASCII 字节的 clientid。

整理日期：2026-08-08
源码目录：摇光/AI-new
固件版本：1.3.9
BLE 名称：摇光DipperConverge
检测能力：NO3、PO4
相关文档：README、设备绑定与 BLE 配网

1. 通信入口

设备启动并连接 MQTT 后立即发布 DF_SJSB1()、DF_SJSB2()、DF_SJSB3()，随后发布 {"ID":"...","state":0}。

2. 上行 JSON

所有上行 JSON 都包含 ID。固件没有通用请求 ID、ACK 或离线补发。

2.1 数据上报 1：设备状态

2.2 数据上报 2：周期与模式

当前固件没有通过 MQTT 上行 NO3/PO4 最新结果，结果只写入 EEPROM。

2.3 数据上报 3：余量

2.4 心跳与实时状态

心跳约每 50 秒发布一次，包含 ID、ORP、PH1、WIFI。当前固件固定返回 ORP: 430、PH1: 8.0。

过程进度使用动态键：

{"ID":"AI240001","NO3CSW":40}

本型号可能出现的键：

微量泵动作开始/结束会发布 NO3ABZZ、NO3BBZZ、PO4ABZZ、PO4BBZZ 的 0/1 帧，结束帧带 state:0。

2.5 错误码

3. 下行指令

将 JSON 发布到设备的 mqtttopic，或通过串口发送同一 JSON。每次只发送一个动作或一个完整设置组。

3.1 系统指令

时钟校准通过 year 键触发，需要同时提供 month、day、hour、minute、second。成功后上行 {"ID":"...","SZXZ":1}。

3.2 检测周期设置

设置成功后重新发布 DF_SJSB2()。当前 Analyze_json() 中单独的 NO3MS、PO4MS 指令被注释，模式只能通过周期设置组下发。

{"NO3XQ":[1,0,1,0,1,0,1],"NO3JCCS":2,"NO3MS":10}

3.3 检测与校准

3.4 微量泵

3.5 试剂余量

4. 接入注意事项

• 当前固件不通过 MQTT 上报 NO3/PO4 检测结果值，结果只写入 EEPROM。
• 没有“主动查询全部状态”指令；三组快照主要在启动和部分设置变更后上报。
• HFCC 只恢复业务参数，不清网络配置。
• 本型号没有滴定、PID、补充液浓度/余量等实际指令，相关上行字段为固定值或占位字段。
• 检测、校准和泵动作期间不要并发发送其他动作。
• 同 02 文档：当前 EEPROM 的 ID 存储存在重叠风险，量产联调阶段应使用不超过 9 个 ASCII 字节的 clientid。