#使用指南(C++)

本指南假设你有一个真实的 DL/T 698.45 采集终端或电能表，想用本库把它读起来。阅读顺序是连接设备 → 读取所需数据 → 理解结果和报文。

使用 Python 接入时，看使用指南(Python)。点位、单位倍率和协议约定仍可参考本指南。

指南统一使用托管接口 dlt698::app::Client / dlt698::app::Server。这两个类管理运行线程、协议关联和链路分帧，你不需要自己创建 Session 或驱动事件循环。想了解底层接口时，右侧的核心类型、协议层、会话与传输模块是完整的接口参考。

#我要读取什么

按业务需求直接跳转：

还没开始？先走第一次读取，十五分钟内读到第一个数值。

#先连上

#当前支持的数据范围

分类以本库已收录的标准对象为依据。库里有定义不等于你的电表能读——设备是否提供某个对象或属性，由设备配置、厂家资料和逐项响应决定，返回 DAR 就是不支持。每一篇都会写明该类数据设备可能缺失哪些对象。

本库没有实现：基波与谐波电能、阶梯电量、时段表业务数据、需量复位与校时方法、其他事件类型、REPORT/PROXY/SECURITY 服务族。完整状态见协议覆盖范围。

#阅读时的三个约定

这三件事贯穿整个指南，弄错任何一个都会得到错误的结果。

一、业务成功不能只看 Result。 client.get() 返回的 Result 成功只表示收到了合法响应，设备可能对其中某些属性回了 DAR。必须逐项检查：

auto value = client.get({0x200F, 2, 0});
if (!value) {
    // 本地错误：超时、断开、地址不匹配
} else if (const auto dar = std::get_if<std::uint8_t>(&value.value())) {
    // 业务失败：设备拒绝了这个属性，*dar 是原因码
} else {
    // 真正读到了数据
}

二、协议整数不等于工程值。 线上传的是整数，2413 是 241.3 V，123456 是 1234.56 kWh。倍率由对象定义决定，必须经过换算：

auto numbers = standard::engineering_values(oad, data);
std::cout << standard::decimal_text(numbers.value()[0]);  // "241.3"

直接把 data.as<model::UInt16>().value 当成读数是最常见的错误来源。

三、单个连接同时只能有一个在途请求。 第二个请求返回 busy，不会被排队。多线程采集时需要自己排队。

#每篇文档的结构

数据类别的页面统一按七节组织，方便横向对比：

1. 能读取什么 — 用业务名称描述，不谈协议字段
2. 数据地址表 — OI、属性、索引、类型、单位、倍率、读写权限
3. 最小完整示例 — 连接、读取、检查错误、解析、输出
4. 常用变体 — 整体与元素、单相与三相、总量与费率
5. 请求与响应报文 — 完整十六进制帧及逐字段说明
6. 相关配置 — 影响这类读取的库参数
7. 常见失败 — 不支持、参数不匹配、空记录、DAR、超时

#关于示例报文

本指南所有报文都用仓库现有编解码接口生成，并经过长度域、HCS、FCS 自检，与 dlt698_decode 交叉验证过，可以直接复制到调试助手里复现。

示例统一使用：SA 六个 00 字节、逻辑地址 0、CA=0、PIID=0。修改地址或 PIID 后必须重新计算校验和，不能沿用原帧 CRC。报文中的数据值是示例值，不代表任何真实设备的测量结果。

#从哪里继续

• 只想快速跑通：第一次读取
• 要对接现场设备：TCP 连接、串口连接
• 出问题了：常见问题排查
• 要理解设计取舍：转到协议覆盖范围和Result 与错误