Back to Details

meter-protocol-serial

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

meter-protocol-serial

meter-protocol-serial

698/645 电表协议串口发帧与解析 Skill
698/645 Electricity Meter Protocol Serial Port Frame Sending and Parsing Skill

触发时机

Trigger Conditions

当用户需求涉及以下任一关键词时触发本 skill：
  • 698
    、
    645
    、
    DL/T698
    、
    DL/T645
  • OAD
    、
    DI
  • 串口发帧
    、
    组帧
    、
    COM口
  • 协议调试
    、
    回归测试
  • 发帧验证
    、
    读电表数据
    、
    写电表参数
This skill is triggered when the user's requirement involves any of the following keywords:
  • 698
    、
    645
    、
    DL/T698
    、
    DL/T645
  • OAD
    、
    DI
  • serial frame sending
    、
    frame assembly
    、
    COM port
  • protocol debugging
    、
    regression test
  • frame sending verification
    、
    read meter data
    、
    write meter parameters

功能概述

Function Overview

本 skill 提供统一的 698/645 电表协议组帧、发送、接收和解析能力：
  1. 只组帧模式（无 port 参数）：输出组好的请求帧十六进制
  2. 串口闭环模式（有 port 参数）：发送请求、接收响应、解析结果
This skill provides unified frame assembly, sending, receiving and parsing capabilities for 698/645 electricity meter protocols:
  1. Frame-only mode (no port parameter): Output the assembled request frame in hexadecimal
  2. Serial port closed-loop mode (with port parameter): Send request, receive response, parse result

使用方法

Usage

快速调用

Quick Invocation

Linux / macOS / 原生Python

Linux / macOS / Native Python

bash
undefined
bash
undefined

645读数据（只组帧）

645读数据（只组帧）

python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000
python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000

645读数据（串口发送）

645读数据（串口发送）

python3 $SKILL_DIR/scripts/protocol_cli.py port=/dev/ttyUSB0 proto=645 op=read di=00010000
python3 $SKILL_DIR/scripts/protocol_cli.py port=/dev/ttyUSB0 proto=645 op=read di=00010000

698读数据

698读数据

python3 $SKILL_DIR/scripts/protocol_cli.py proto=698 op=read oad=40010200
python3 $SKILL_DIR/scripts/protocol_cli.py proto=698 op=read oad=40010200

698设置参数

698设置参数

python3 $SKILL_DIR/scripts/protocol_cli.py proto=698 op=set oad=43000300 value=bool:true
undefined
python3 $SKILL_DIR/scripts/protocol_cli.py proto=698 op=set oad=43000300 value=bool:true
undefined

Windows / WSL (重要差异)

Windows / WSL (Important Differences)

WSL中使用Windows串口时，推荐走 Python 包装脚本，它会自动转成 
python.exe
+ Windows 路径：
bash
undefined
When using Windows serial port in WSL, it is recommended to use the Python wrapper script, which will automatically convert to 
python.exe
+ Windows path:
bash
undefined

WSL中访问Windows COM口（推荐方式：使用 Python 包装脚本）

WSL中访问Windows COM口（推荐方式：使用 Python 包装脚本）

python3 $SKILL_DIR/meter-cmd.py port=COM10 proto=645 op=read di=04000401
python3 $SKILL_DIR/meter-cmd.py port=COM10 proto=645 op=read di=04000401

或者手动转换路径

或者手动转换路径

SKILL_PATH=$(wslpath -w /home/xx/.agents/skills/meter-protocol-serial/scripts/protocol_cli.py) python.exe "$SKILL_PATH" port=COM10 proto=645 op=read di=04000401

**常见错误：**
```bash
SKILL_PATH=$(wslpath -w /home/xx/.agents/skills/meter-protocol-serial/scripts/protocol_cli.py) python.exe "$SKILL_PATH" port=COM10 proto=645 op=read di=04000401

**Common Errors:**
```bash

错误方式1（WSL Python无法访问Windows串口）

错误方式1（WSL Python无法访问Windows串口）

python3 protocol_cli.py port=COM10 ... # 会报错: No such file or directory
python3 protocol_cli.py port=COM10 ... # 会报错: No such file or directory

错误方式2（Windows Python无法直接访问WSL路径）

错误方式2（Windows Python无法直接访问WSL路径）

python.exe /home/xx/.../protocol_cli.py # 会报错: can't open file

**WSL串口映射关系：**
| Windows | WSL设备 |
|---------|---------|
| COM1 | /dev/ttyS1 |
| COM10 | /dev/ttyS10 |

**Windows原生PowerShell/CMD：**
```powershell
python.exe /home/xx/.../protocol_cli.py # 会报错: can't open file

**WSL Serial Port Mapping:**
| Windows | WSL Device |
|---------|---------|
| COM1 | /dev/ttyS1 |
| COM10 | /dev/ttyS10 |

**Windows Native PowerShell/CMD:**
```powershell

Windows直接运行（PowerShell）

Windows直接运行（PowerShell）

python.exe C:\path\to\scripts\protocol_cli.py port=COM10 proto=645 op=read di=04000401
python.exe C:\path\to\scripts\protocol_cli.py port=COM10 proto=645 op=read di=04000401

Windows直接运行（CMD）

Windows直接运行（CMD）

python C:\path\to\scripts\protocol_cli.py port=COM10 proto=645 op=read di=04000401
undefined
python C:\path\to\scripts\protocol_cli.py port=COM10 proto=645 op=read di=04000401
undefined

带断言的回归测试

Regression Test with Assertion

bash
undefined
bash
undefined

Linux/WSL通用（只组帧，无串口）

Linux/WSL通用（只组帧，无串口）

python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000 expect=ack
python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000 expect=ack

WSL+Windows串口（推荐直接走包装脚本）

WSL+Windows串口（推荐直接走包装脚本）

python3 $SKILL_DIR/meter-cmd.py port=COM3 proto=645 op=read di=00010000 expect=ack
undefined
python3 $SKILL_DIR/meter-cmd.py port=COM3 proto=645 op=read di=00010000 expect=ack
undefined

支持的协议

Supported Protocols

协议操作说明
DL/T645-2007read读数据
DL/T645-2007write写数据
DL/T698.45readGET.request.normal
DL/T698.45setSET.request.normal
ProtocolOperationDescription
DL/T645-2007readRead data
DL/T645-2007writeWrite data
DL/T698.45readGET.request.normal
DL/T698.45setSET.request.normal

输入参数

Input Parameters

通用参数

General Parameters

参数说明示例
proto协议类型645 或 698
op操作类型read / write / set
port串口（可选）/dev/ttyUSB0 或 COM3
timeout_ms超时时间2000
baud波特率2400（645默认）、9600（698默认）
data_bits数据位8
parity校验位even / odd / none
stop_bits停止位1
expect断言条件ack / hex:0102 / bool:true / int:1
decode_hint解码提示hex / ascii / uint16_le / uint32_le / bcd
note备注任意文本
ParameterDescriptionExample
protoProtocol type645 or 698
opOperation typeread / write / set
portSerial port (optional)/dev/ttyUSB0 or COM3
timeout_msTimeout duration2000
baudBaud rate2400 (default for 645), 9600 (default for 698)
data_bitsData bits8
parityParity biteven / odd / none
stop_bitsStop bit1
expectAssertion conditionack / hex:0102 / bool:true / int:1
decode_hintDecoding hinthex / ascii / uint16_le / uint32_le / bcd
noteNoteAny text

645专用参数

645 Dedicated Parameters

参数说明示例
di数据标识（8位十六进制）00010000
addr表地址（12位BCD）000000000001
value写数据值hex:010203 / ascii:abc
fe_count前导FE个数4
raw_prefix前置数据hex:041234
raw_suffix后置数据hex:0000
ParameterDescriptionExample
diData identifier (8-bit hexadecimal)00010000
addrMeter address (12-bit BCD)000000000001
valueWrite data valuehex:010203 / ascii:abc
fe_countNumber of leading FE bytes4
raw_prefixPrefix datahex:041234
raw_suffixSuffix datahex:0000

698专用参数

698 Dedicated Parameters

参数说明示例
oad对象属性描述符（8位十六进制）40010200
server_addr服务器地址000000000000
client_addr客户机地址00
ca客户机地址（缩写）00
value写数据值bool:true / int32:123 / string:abc
ParameterDescriptionExample
oadObject Attribute Descriptor (8-bit hexadecimal)40010200
server_addrServer address000000000000
client_addrClient address00
caClient address (abbreviated)00
valueWrite data valuebool:true / int32:123 / string:abc

Value格式

Value Format

645协议：
  • hex:01020304
    - 原始十六进制数据
  • ascii:abc
    - ASCII字符串
698协议：
  • bool:true|false
    - 布尔值
  • int8:1
    , 
    int16:1
    , 
    int32:1
    - 有符号整数
  • uint8:1
    , 
    uint16:1
    , 
    uint32:1
    - 无符号整数
  • enum:1
    - 枚举值
  • octet:112233
    - 八位串（带长度前缀）
  • string:abc
    - 可见字符串（带长度前缀）
  • hex:010203
    - 原始十六进制（直接作为Data）
645 Protocol:
  • hex:01020304
    - Raw hexadecimal data
  • ascii:abc
    - ASCII string
698 Protocol:
  • bool:true|false
    - Boolean value
  • int8:1
    , 
    int16:1
    , 
    int32:1
    - Signed integer
  • uint8:1
    , 
    uint16:1
    , 
    uint32:1
    - Unsigned integer
  • enum:1
    - Enum value
  • octet:112233
    - Octet string (with length prefix)
  • string:abc
    - Visible string (with length prefix)
  • hex:010203
    - Raw hexadecimal (directly used as Data)

输出格式

Output Format

MODE=frame_only|serial_roundtrip
PROTO=645|698
OP=read|write|set
TARGET=di:xxx|oad:xxx
REQUEST_HEX=68 AA AA ... CS 16
RESPONSE_HEX=68 BB BB ... CS 16  (串口模式)
FRAME_CHECK=ok|fail|partial
DECODE_STATUS=ok|partial|fail
RESULT=success|error|timeout
DATA_HEX=01020304
DATA_TYPED=typed_value  (如果有)
ASSERT_RESULT=pass|fail|skipped
ASSERT_REASON=...  (如果有)
SUMMARY=简短中文总结
MODE=frame_only|serial_roundtrip
PROTO=645|698
OP=read|write|set
TARGET=di:xxx|oad:xxx
REQUEST_HEX=68 AA AA ... CS 16
RESPONSE_HEX=68 BB BB ... CS 16  (串口模式)
FRAME_CHECK=ok|fail|partial
DECODE_STATUS=ok|partial|fail
RESULT=success|error|timeout
DATA_HEX=01020304
DATA_TYPED=typed_value  (如果有)
ASSERT_RESULT=pass|fail|skipped
ASSERT_REASON=...  (如果有)
SUMMARY=简短中文总结

645特有输出

645 Specific Output

645_ADDR=000000000001
645_CTRL=91
645_DI=00010000
645_ADDR=000000000001
645_CTRL=91
645_DI=00010000

698特有输出

698 Specific Output

698_SERVER_ADDR=45AAAAAAAAAAAA  (地址特征字节+6字节地址)
698_CLIENT_ADDR=00
698_CTRL=43  (控制域: DIR=0,PRM=1,分帧=0,扰码=0,功能码=3)
698_PIID=00
698_OAD=40010200
698_DAR=00  (数据访问结果，00=成功)
698_SERVER_ADDR=45AAAAAAAAAAAA  (地址特征字节+6字节地址)
698_CLIENT_ADDR=00
698_CTRL=43  (控制域: DIR=0,PRM=1,分帧=0,扰码=0,功能码=3)
698_PIID=00
698_OAD=40010200
698_DAR=00  (数据访问结果，00=成功)

退出码

Exit Code

码值含义
0成功
2输入参数错误
3串口打开或发送失败
4超时无响应
5收到响应但解析失败
6断言失败
Code ValueMeaning
0Success
2Input parameter error
3Serial port opening or sending failure
4Timeout with no response
5Response received but parsing failed
6Assertion failed

AI 使用建议

AI Usage Suggestions

回复顺序

Response Order

当用户使用本 skill 时，AI 应按以下顺序回复：
  1. 执行命令：给出实际执行的 CLI 命令
  2. 关键输出：摘出 REQUEST_HEX、RESULT、ASSERT_RESULT 等关键字段
  3. 简短解释：说明结果含义和下一步建议
When users use this skill, AI should reply in the following order:
  1. Execute command: Provide the actual executed CLI command
  2. Key output: Extract key fields such as REQUEST_HEX, RESULT, ASSERT_RESULT, etc.
  3. Brief explanation: Explain the meaning of the result and suggestions for next steps

示例场景

Example Scenarios

场景1：用户说"帮我组一个645读数据的帧"
执行命令：
python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000

输出：
MODE=frame_only
PROTO=645
OP=read
TARGET=di:00010000
REQUEST_HEX=FEFEFEFE6800000000000068110433333333AD16
...
SUMMARY=组帧成功: FEFEFEFE6800000000000068110433...
场景2：用户说"验证COM3口能否读到数据"
执行命令：
python3 $SKILL_DIR/scripts/protocol_cli.py port=COM3 proto=645 op=read di=00010000 expect=ack

输出：
MODE=serial_roundtrip
PROTO=645
OP=read
...
ASSERT_RESULT=pass
SUMMARY=断言通过: 收到响应
Scenario 1: User says "Help me assemble a 645 data reading frame"
执行命令：
python3 $SKILL_DIR/scripts/protocol_cli.py proto=645 op=read di=00010000

输出：
MODE=frame_only
PROTO=645
OP=read
TARGET=di:00010000
REQUEST_HEX=FEFEFEFE6800000000000068110433333333AD16
...
SUMMARY=组帧成功: FEFEFEFE6800000000000068110433...
Scenario 2: User says "Verify if data can be read from COM3 port"
执行命令：
python3 $SKILL_DIR/scripts/protocol_cli.py port=COM3 proto=645 op=read di=00010000 expect=ack

输出：
MODE=serial_roundtrip
PROTO=645
OP=read
...
ASSERT_RESULT=pass
SUMMARY=断言通过: 收到响应

注意事项

Notes

  1. port 参数可选：无 port 时进入只组帧模式，不会打开串口
  2. 地址默认值：
    • 645默认地址 
      AAAAAAAAAAAA
      （12位BCD通配地址）
    • 698默认服务器地址 
      AAAAAAAAAAAA
      （6字节通配地址，地址特征字节=0x45），客户机地址 
      00
  3. 波特率默认：645默认9600bps，698默认9600bps
  4. 超时处理：默认超时2000ms，可通过timeout_ms调整
  5. 断言失败：assert_result=fail时进程返回非零退出码，可用于脚本自动化
  1. port parameter is optional: When there is no port, it enters frame-only mode and will not open the serial port
  2. Default address:
    • 645 default address 
      AAAAAAAAAAAA
      (12-bit BCD wildcard address)
    • 698 default server address 
      AAAAAAAAAAAA
      (6-byte wildcard address, address feature byte = 0x45), client address 
      00
  3. Default baud rate: 645 default 9600bps, 698 default 9600bps
  4. Timeout handling: Default timeout is 2000ms, can be adjusted via timeout_ms
  5. Assertion failure: When assert_result=fail, the process returns a non-zero exit code, which can be used for script automation

模块结构

Module Structure

scripts/
├── protocol_cli.py      # CLI主入口
├── request_parser.py    # 请求解析
├── profiles.py          # 默认配置
├── serial_transport.py  # 串口收发
├── proto_645.py         # 645协议处理
├── proto_698.py         # 698协议处理
├── value_codec.py       # 值编解码
└── result_formatter.py  # 结果格式化
scripts/
├── protocol_cli.py      # CLI主入口
├── request_parser.py    # 请求解析
├── profiles.py          # 默认配置
├── serial_transport.py  # 串口收发
├── proto_645.py         # 645协议处理
├── proto_698.py         # 698协议处理
├── value_codec.py       # 值编解码
└── result_formatter.py  # 结果格式化

第一版限制

V1 Limitations

  • 698：不支持登录、链路建立、安全认证、安全传输
  • 698：不支持 ACTION 和 ROAD
  • 645：不做各类业务DI的专用语义解析
  • 两个协议：仅支持标准明文读写，不支持厂商私有扩展
  • 698: Does not support login, link establishment, security authentication, secure transmission
  • 698: Does not support ACTION and ROAD
  • 645: No dedicated semantic parsing for various service DIs
  • Both protocols: Only support standard plaintext read and write, do not support manufacturer private extensions