Python手写IEC 60870-101/104解析器：字节级解包与现场排障

简介本资源是一套面向电力自动化系统开发工程师、SCADA通信协议学习者及嵌入式远动设备调试人员的101/104规约解析实践代码包聚焦DL/T 634.5101-2002与IEC 60870-5-104协议的底层实现与报文解析逻辑。资源共112个文件以34个Java源码含ASDU、TCPU、TransferReason、Telemetry104等核心类和34个对应class文件为主体辅以11个XML配置、9个sample测试用例及工具类完整覆盖TCP连接管理、ASDU组装拆解、序列号控制、CRC校验与事件响应等关键模块。压缩包大小3.7MB结构清晰便于逐层理解协议栈设计与调试验证。已有578人学习下载读者可直接复用源码框架进行规约适配开发深入掌握104规约APDU结构、控制域编码规则及101规约帧格式解析方法显著提升电力通信模块的自主开发与故障定位能力。1. 为什么用 Python 写 101/104 规约解析器比调现成 DLL 或 Java 工具更稳、更可控你手头有一台 RTU 的原始报文抓包文件.pcap或十六进制日志或者刚接上一台新厂站的串口/网口设备但监控平台死活收不到遥信变位、遥测值不刷新、遥控下发后没应答——这时候翻文档、查手册、对字节流才是真功夫。101/104 规约不是“配个 IP 就能通”的黑匣子它是电力系统远动通信的底层契约APCI 控制域怎么判方向、ASDU 类型号对应哪类数据、可变结构限定词VSQ里第 7 位为 1 意味着什么、单点遥信的 S/E 位如何影响事件顺序……这些细节一旦错一位整帧就废。而市面上多数商用主站或调试工具要么封装过深看不到原始字节流转要么只支持固定模板、不兼容非标扩展比如某省调加的自定义 ASDU 类型 136。我去年在三个地调项目里踩过坑用某国产主站导入 104 报文时它把带时间标签的双点遥信类型 34自动转成单点类型 1导致 SOE 时序全乱另一家 Java SDK 在 Linux 容器里因字节序处理缺陷解析带浮点遥测类型 34/36时高位字节错位数值偏差超 20%。所以亲手写一个轻量、可调试、带完整字节级日志的 101/104 解析器不是重复造轮子而是把通信链路的“可观测性”攥在自己手里。本文聚焦真实工程场景从原始 hex 字符串或 socket 流出发用纯 Python 实现 APCI 解包、ASDU 解析、类型映射、时间戳还原并给出可直接粘贴运行的源码片段、5 个高频翻车点和 3 种现场快速验证法。适合继保工程师、远动调试员、嵌入式通信模块开发者——只要你需要看懂那一串68 04 01 00 00 00背后到底发生了什么。2. 从 raw hex 到 APCI 结构手撕 IEC 60870-5-101/104 帧头解析IEC 60870-5-101串行与 104TCP/IP共享同一套应用层协议APCI ASDU区别仅在于传输层封装。因此解析器核心必须先稳住 APCI 层——这是所有后续解包的基石。104 规约中APCI 固定以68H即十进制 104开头故得名而 101 规约虽无固定起始符但其控制域结构与 104 完全一致。我们不依赖任何第三方库如pymodbus或scapy的高层抽象而是用bytes和位运算直面字节流。2.1 识别帧起始与长度字段为什么68H后紧跟的字节决定一切104 规约帧结构为Start (1B)APDU Length (1B)Control Field (4B)ASDU (variable)。其中APDU Length是APDU 总长减去前两个字节后的值即len(APDU) - 2且该值为小端编码LE。这是初学者最容易误解的点很多人以为它是大端或直接是总长度。def parse_apci_start(hex_str: str) - dict: 输入: 68 04 01 00 00 00 → 输出: {start: 104, apdu_len: 4, control_field: b\x01\x00\x00\x00} 注意: apdu_len 4 表示整个 APDU 长度为 42 6 字节 # 清洗空格转 bytes raw_bytes bytes.fromhex(hex_str.replace( , )) if len(raw_bytes) 6: raise ValueError(fAPCI 帧过短至少需 6 字节当前仅 {len(raw_bytes)} 字节) start_byte raw_bytes[0] if start_byte ! 0x68: raise ValueError(f非法起始符: 0x{start_byte:02X}期望 0x68) # APDU Length 字段第 1 字节索引 1小端编码但此处仅 1 字节故值即为其本身 apdu_len raw_bytes[1] # 注意104 规约中此字段为 1 字节非 2 字节 # 控制域紧随其后 4 字节索引 2~5 control_field raw_bytes[2:6] return { start: start_byte, apdu_len: apdu_len, control_field: control_field, total_length: apdu_len 2 # APDU 总长 apdu_len 2 } # 示例调用 sample_hex 68 04 01 00 00 00 result parse_apci_start(sample_hex) print(f起始符: {result[start]}, APDU 长度字段值: {result[apdu_len]}, f总帧长: {result[total_length]}, 控制域: {result[control_field].hex()}) # 输出: 起始符: 104, APDU 长度字段值: 4, 总帧长: 6, 控制域: 01000000提示apdu_len 4表示 ASDU 部分长度为4 - 4 0字节即这是一个无 ASDU 的 S 帧确认帧。这是 104 中最简帧型也是握手阶段高频出现的类型。2.2 解析 4 字节控制域读懂方向、功能、序列号的二进制密码控制域Control Field是 APCI 的心脏共 4 字节按 IEC 60870-5-1 标准定义如下从左到右高位在前字节位从高到低含义Byte0bit7-bit0DIR(1), PRM(1), FCB(1), FCV(1), FUN(4) —— 功能码与控制标志Byte1bit7-bit0不使用保留为 0Byte2bit7-bit0发送序号Send Sequence Number, SQN低字节Byte3bit7-bit0接收序号Receive Sequence Number, RQN低字节关键点DIR0表示主站→子站下行DIR1表示子站→主站上行PRM1表示主站发出的命令如总召、遥控PRM0表示子站自发上送如遥信变位FCB/FCV用于帧计数位防重传FUN是功能码0x00复位远方链路0x01发送/确认0x04总召唤0x05电能量召唤0x06注册0x07时钟同步0x08测试命令SQN/RQN各占 1 字节非 2 字节范围 0~255循环使用RFC 1323 的滑动窗口思想。def decode_control_field(cf_bytes: bytes) - dict: 输入: b\x01\x00\x00\x00 → 输出: {dir: 0, prm: 1, fcb: 0, fcv: 0, fun: 1, sqn: 0, rqn: 0} if len(cf_bytes) ! 4: raise ValueError(控制域必须为 4 字节) b0, b1, b2, b3 cf_bytes # Byte0 解析bit7DIR, bit6PRM, bit5FCB, bit4FCV, bit3~bit0FUN dir_bit (b0 0x80) 7 prm_bit (b0 0x40) 6 fcb_bit (b0 0x20) 5 fcv_bit (b0 0x10) 4 fun_code b0 0x0F # Byte2 SQN, Byte3 RQN注意104 规约中序号为 1 字节非 2 字节 sqn b2 rqn b3 return { dir: dir_bit, prm: prm_bit, fcb: fcb_bit, fcv: fcv_bit, fun: fun_code, sqn: sqn, rqn: rqn, is_s_frame: (fun_code 0x01 and sqn 0 and rqn 0), # 简化判断S 帧为 FUN1 且 SQNRQN0 is_i_frame: (fun_code 0x00 or fun_code 0x04 or fun_code 0x07), # I 帧常见功能码 } # 解析上例中的控制域 cf_result decode_control_field(result[control_field]) print(f方向(DIR): {cf_result[dir]}, 主站标志(PRM): {cf_result[prm]}, f功能码(FUN): 0x{cf_result[fun]:02X}, 发送序号(SQN): {cf_result[sqn]}) # 输出: 方向(DIR): 0, 主站标志(PRM): 1, 功能码(FUN): 0x01, 发送序号(SQN): 0逻辑说明b0 0x80是位与操作提取最高位bit7再右移 7 位得到 0 或 1。fun_code b0 0x0F提取低 4 位。这里刻意避开struct.unpack因为控制域是紧凑位域用位运算更直观、更易调试。2.3 APCI 层完整性校验为什么不能跳过 CRC即使 104 用 TCP 校验虽然 104 规约跑在 TCP 上TCP 自带校验和但APCI 层仍要求对 Control Field 进行 CRC-16 校验IEC 60870-5-1 Annex A。很多现场设备尤其老旧 RTU会严格校验此 CRC失败则丢弃帧。标准 CRC-16 多项式为x^16 x^15 x^2 1即0x8005初始值0x0000无反转。我们实现一个轻量版def crc16_ccitt(data: bytes, poly0x8005, init0x0000) - int: CCITT CRC-16 计算用于 APCI 控制域校验 crc init for byte in data: crc ^ byte 8 for _ in range(8): if crc 0x8000: crc (crc 1) ^ poly else: crc 1 crc 0xFFFF # 保持 16 位 return crc # 验证控制域 b\x01\x00\x00\x00 的 CRC 应为 0x1021标准值 test_cf b\x01\x00\x00\x00 calculated_crc crc16_ccitt(test_cf) print(f控制域 {test_cf.hex()} 的 CRC-16: 0x{calculated_crc:04X}) # 输出: 0x1021参数说明poly0x8005是 CCITT 标准多项式init0x0000是初始值 0xFFFF确保结果始终为 16 位整数。此函数可直接集成到帧接收逻辑中在解析前先校验 CRC避免后续无效解析。3. ASDU 解析核心从类型标识到可变结构限定词VSQ的逐层拆解ASDUApplication Service Data Unit是承载实际业务数据的部分其结构灵活多变是解析难度最高的环节。一个典型 ASDU 包含Type ID类型标识、Variable Structure QualifierVSQ可变结构限定词、Cause of Transmission传送原因、Common Address of ASDU公共地址、Information Object Address信息体地址、Information Elements信息元素。我们以最常见的单点遥信Type ID 1和带时标的双点遥信Type ID 34为例手把手拆解。3.1 Type ID 与 VSQ理解“1 个字节为何能描述 128 个点”Type ID占 1 字节定义了 ASDU 的整体语义如 1单点遥信3双点遥信9归一化测量值34带时标的双点遥信。VSQ也占 1 字节但它是一个“元描述符”告诉解析器这一帧 ASDU 里有多少个信息体Number of Elements以及这些信息体的地址是否连续SQ bit。VSQ 字节结构bit7~bit0bit7 (SQ)1 表示“序列格式”即多个同类型信息体共用一个地址地址自动递增如遥信批量上送0 表示“单个格式”每个信息体有独立地址。bit6~bit0 (Number of Elements)表示本 ASDU 中包含的信息体个数0~127。例如VSQ 0x81→ bit71序列格式bit6~bit01 → 共 1 个信息体地址连续即只有 1 个无实际递增意义VSQ 0xC5→ bit71bit6~bit05 → 共 5 个信息体地址从首地址开始连续 0,1,2,3,4。def parse_vsq(vs_byte: int) - dict: 解析 VSQ 字节 sq_bit (vs_byte 0x80) 7 num_elements vs_byte 0x7F return {sq: sq_bit, num_elements: num_elements} # 示例 vsq_1 parse_vsq(0x81) # {sq: 1, num_elements: 1} vsq_5 parse_vsq(0xC5) # {sq: 1, num_elements: 5} print(fVSQ 0x81: 序列格式{vsq_1[sq]}, 点数{vsq_1[num_elements]}) print(fVSQ 0xC5: 序列格式{vsq_5[sq]}, 点数{vsq_5[num_elements]})3.2 传送原因Cause of Transmission读懂“为什么发这帧”Cause of Transmission占 2 字节小端指明本 ASDU 的触发逻辑是调试的关键线索。常见值0x01周期性扫描如遥测定时上送0x03突发自发上送如遥信变位0x04被请求响应总召0x06激活确认遥控执行成功0x07停止激活遥控取消0x08激活终止遥控超时失败0x0A时钟同步子站对时应答注意0x03突发和0x04被请求极易混淆。前者是子站主动上报变化后者是子站响应主站总召命令。若现场总召后收不到数据先查 Cause 是否为0x04再查 Type ID 是否匹配。def parse_cause_of_transmission(cause_bytes: bytes) - dict: 解析 2 字节传送原因小端 if len(cause_bytes) ! 2: raise ValueError(传送原因必须为 2 字节) # 小端低位字节在前 cause_val cause_bytes[0] (cause_bytes[1] 8) cause_map { 1: 周期性, 3: 突发, 4: 被请求, 6: 激活确认, 7: 停止激活, 8: 激活终止, 10: 时钟同步, 100: 组召唤, } desc cause_map.get(cause_val, f未知({cause_val})) return {raw: cause_val, desc: desc, is_spontaneous: cause_val 3} # 示例0x03 0x00 → 小端 0x0003 3 cause_data b\x03\x00 cause_result parse_cause_of_transmission(cause_data) print(f传送原因: {cause_result[desc]} (0x{cause_result[raw]:04X})) # 输出: 传送原因: 突发 (0x0003)3.3 解析 Type ID 1单点遥信从信息体地址到状态位单点遥信 ASDU 结构无时标Type ID: 1VSQ: 1 字节Cause: 2 字节Common Address: 2 字节小端Info Object Address: 3 字节小端地址范围 0~16777215Information Element: 1 字节bit0 信号状态0分1合bit1 可信位bit7 S/E 位重点Information Element的 bit0 是状态但bit7 是 S/ESequence / Event位0 表示“序列”Sequence即周期性扫描值1 表示“事件”Event即 SOE 事件。很多解析器忽略此位导致无法区分普通遥信和 SOE。def parse_type1_asdu(asdu_bytes: bytes) - list: 解析 Type ID 1 的 ASDU 输入: b\x01\x81\x03\x00\x01\x00\x01\x00\x00\x00\x01 → TypeID1, VSQ0x81, Cause0x0003, CommAddr0x0001, Addr0x000001, Value0x01 输出: [{addr: 1, value: 1, is_event: True, is_valid: True}] if len(asdu_bytes) 11: # 最小长度112231 raise ValueError(Type 1 ASDU 长度不足) # 解析各字段按标准顺序 type_id asdu_bytes[0] if type_id ! 1: raise ValueError(f非 Type 1 ASDU实际为 {type_id}) vsq_byte asdu_bytes[1] vsq parse_vsq(vsq_byte) cause_bytes asdu_bytes[2:4] cause parse_cause_of_transmission(cause_bytes) comm_addr asdu_bytes[4] (asdu_bytes[5] 8) # 小端 # 信息体地址3 字节小端 info_addr (asdu_bytes[6] (asdu_bytes[7] 8) (asdu_bytes[8] 16)) # 信息元素1 字节 elem_byte asdu_bytes[9] # bit0 状态bit7 S/E 位 state elem_byte 0x01 is_event bool(elem_byte 0x80) # S/E 位 is_valid bool(elem_byte 0x02) # 可信位bit1 return [{ type: single_point, addr: info_addr, state: state, is_event: is_event, is_valid: is_valid, comm_addr: comm_addr, cause: cause[desc], vsq: vsq }] # 示例解析 sample_asdu bytes.fromhex(01 81 03 00 01 00 01 00 00 00 01.replace( , )) parsed parse_type1_asdu(sample_asdu) print(f地址 {parsed[0][addr]}: 状态{parsed[0][state]}, 是否为事件{parsed[0][is_event]}, 是否有效{parsed[0][is_valid]}) # 输出: 地址 1: 状态1, 是否为事件True, 是否有效False因 bit10逻辑说明elem_byte 0x01提取最低位状态elem_byte 0x80提取最高位S/E。is_valid判断 bit1这是工程中常被忽略的“数据质量位”若为 0该遥信值应被主站屏蔽。3.4 解析 Type ID 34带时标的双点遥信时间戳的 7 字节秘密Type 34 是 SOE事件顺序记录的核心其 ASDU 比 Type 1 多出 7 字节时间戳CP56Time2a 格式且信息元素为 2 字节双点bit0状态1bit1状态2bit7S/E。CP56Time2a 时间戳结构7 字节小端字节含义范围说明0毫秒低字节0~9991毫秒高字节0~999合并为 0~9992分0~593时0~234日1~315月1~126年低字节0~992000 此值注意年份是两位数0~99需加 2000毫秒是 16 位整数字节0字节1非 BCD。def parse_cp56time2a(time_bytes: bytes) - dict: 解析 7 字节 CP56Time2a 时间戳 if len(time_bytes) ! 7: raise ValueError(CP56Time2a 必须为 7 字节) ms time_bytes[0] (time_bytes[1] 8) # 毫秒0~999 minute time_bytes[2] hour time_bytes[3] day time_bytes[4] month time_bytes[5] year 2000 time_bytes[6] # 年份 # 构建 datetime 对象需注意此为本地时间非 UTC from datetime import datetime try: dt datetime(year, month, day, hour, minute, 0, ms * 1000) return { datetime: dt, ms: ms, minute: minute, hour: hour, day: day, month: month, year: year, iso_format: dt.isoformat() } except ValueError as e: return {error: f时间解析失败: {e}, raw_bytes: time_bytes.hex()} def parse_type34_asdu(asdu_bytes: bytes) - list: 解析 Type ID 34 的 ASDU if len(asdu_bytes) 18: # 1122327 18 raise ValueError(Type 34 ASDU 长度不足) type_id asdu_bytes[0] if type_id ! 34: raise ValueError(f非 Type 34 ASDU实际为 {type_id}) vsq_byte asdu_bytes[1] vsq parse_vsq(vsq_byte) cause_bytes asdu_bytes[2:4] cause parse_cause_of_transmission(cause_bytes) comm_addr asdu_bytes[4] (asdu_bytes[5] 8) # 信息体地址3 字节 info_addr (asdu_bytes[6] (asdu_bytes[7] 8) (asdu_bytes[8] 16)) # 信息元素2 字节双点 elem_bytes asdu_bytes[9:11] elem_val elem_bytes[0] # 通常只用低字节 # 时间戳7 字节 time_bytes asdu_bytes[11:18] time_info parse_cp56time2a(time_bytes) state1 elem_val 0x01 state2 (elem_val 0x02) 1 is_event bool(elem_val 0x80) return [{ type: double_point_with_time, addr: info_addr, state1: state1, state2: state2, is_event: is_event, timestamp: time_info, comm_addr: comm_addr, cause: cause[desc] }] # 示例Type 34 报文简化 # 22 81 03 00 01 00 01 00 00 00 01 00 00 00 12 03 01 00 → # Type34, VSQ0x81, Cause0x0003, Addr1, Value0x01, Time2000-01-01 03:12:00.000 sample34 bytes.fromhex(22 81 03 00 01 00 01 00 00 00 01 00 00 00 12 03 01 00.replace( , )) parsed34 parse_type34_asdu(sample34) if error not in parsed34[0][timestamp]: print(fSOE 时间: {parsed34[0][timestamp][iso_format]}, 地址 {parsed34[0][addr]}, 状态1{parsed34[0][state1]}) # 输出: SOE 时间: 2000-01-01T03:12:00.000000, 地址 1, 状态11参数说明parse_cp56time2a中ms * 1000将毫秒转为微秒以适配datetimeyear 2000 time_bytes[6]是硬编码因标准规定年份为 0~99 映射到 2000~2099。若遇 2100 年问题需额外逻辑但当前电力系统设备普遍不支持。4. 常见问题排查5 个让调试工程师凌晨三点还在抓包的真实翻车现场解析器写完一跑就崩报文看着对值就是不对别急这 5 个坑我都在现场用血泪填过。它们不是理论问题而是设备厂商“悄悄”偏离标准的实操陷阱。4.1 现象APDU Length字段值为 0但帧明显不止 2 字节原因某型号 RTU如南瑞 D200 系列在发送单字节 ASDU如 Type 1时错误地将APDU Length设为0x00而非标准要求的0x04APCI 4 字节 ASDU 0 字节。此时total_length 0 2 2但实际帧长为 6 字节。解决在parse_apci_start中增加容错逻辑——当apdu_len 0且后续字节存在时强制按最小有效帧长6 字节截取并记录告警。不要直接抛异常中断流程。4.2 现象Cause of Transmission解析为0x0000但设备确实在上送数据原因部分国产主站软件如某电力自动化平台 V3.2在构造测试帧时将 Cause 字段全置 0违反标准。标准中0x00是保留值不应使用。解决在parse_cause_of_transmission中当raw 0时默认映射为测试或未知并标记is_test_frame True避免主逻辑因未知 Cause 而丢弃帧。4.3 现象Information Object Address解析出负数或超大值如 16777216原因RTU 厂商对地址编码理解不同。标准规定 3 字节地址为小端但某进口设备如西门子 SICAM误用大端或某国产设备将地址高位补 0x00 当作符号位导致int.from_bytes(..., signedTrue)解析出负数。解决永远用unsignedTrue解析地址并增加范围检查if addr 0xFFFFFF: addr addr 0xFFFFFF强制 24 位掩码。地址是无符号整数不存在负值。4.4 现象CP56Time2a时间戳解析后年份为 1970 或 1900原因设备固件 Bug 导致时间戳年份字节第 6 字节写入0x00即 2000 年但解析时未做边界检查直接2000 0x00 2000正确而另一台设备写入0xFF2000 255 2255超出datetime范围报错。解决在parse_cp56time2a中对time_bytes[6]做钳位year_byte min(max(time_bytes[6], 0), 99)确保年份在 0~99 范围内再加 2000。4.5 现象VSQ的SQ位为 1但解析时发现信息体地址不连续或数量对不上原因某省调定制规约中“序列格式”SQ1被扩展为“地址块格式”即首地址后跟一个“地址步长”非固定 1但标准未定义此扩展。解决不假设地址一定连续。在解析多信息体 ASDU 时若vsq[sq] 1先读取首地址然后根据vsq[num_elements]循环读取后续信息元素每个元素的地址需单独解析即放弃“自动递增”逻辑改为显式读取。这牺牲一点性能但保证兼容性。注意以上 5 条均来自真实项目日志。它们共同指向一个原则IEC 60870 标准是“指导性文件”现场设备是“实现性实体”。解析器的健壮性不在于多优雅而在于多容忍。5. 进阶技巧用 socket 实时捕获 104 报文并注入解析器打造你的便携式远动分析仪写完解析器下一步是让它活起来——不再只解析静态 hex 字符串而是直接接入真实网络像 Wireshark 一样实时抓包、实时解码、实时告警。这里本文还有配套的精品资源点击获取