★ FEATURED ARTICLE 简介这份资源是面向 Python 开发者的 ADS-B 消息处理工具包适合对航空监视数据、航班追踪或无线电信号解析感兴趣的初中级开发者用于在 Python 项目中接收并解析 ADS-B 报文。压缩包共 49 个文件约 55KB以 23 个 py 源码文件为核心辅以 8 个 rst 文档、5 个 txt 说明及 yml、makefile 等构建配置另含 kml 示例与测试脚本目录中 src、tests、examples、docs 分层清晰便于按模块阅读与二次开发。目前已有 1017 人学习下载。项目虽处于开发初期但已提供 API 级文档与基础测试用例读者可据此了解消息解析流程、参考示例代码快速接入并借助测试文件排查问题为后续扩展功能打下基础。1. 从一条 1090MHz 报文说起这个 Python 工具到底能干什么手里有一台 RTL-SDR 或者一块能输出原始 IQ 数据的采集卡想看看头顶飞过的飞机到底在广播什么很多人第一步就卡在解码上。dump1090 这类工具能出结果但它是黑匣子你想把报文拿去做二次分析、批量统计、接进自己的 Python 流水线就得自己啃 112 位报文格式。这个adsb工具包解决的正是这一段把 ADS-B 的原始报文解析、字段提取、CRC 校验这些脏活封装成 Python 接口让你在脚本里直接拿到呼号、高度、经纬度、速度、Squawk 这些结构化字段而不是对着一串十六进制发呆。它适合两类人一类是做无线电信号处理、想把解码结果接进数据分析链路的工程师另一类是拿它做教学演示、协议分析练习的从业者。前提是你得先有原始报文来源这个包不负责射频接收它只负责“报文进来、字段出去”。下面按“先立协议模型、再跑通解析、最后处理边界”的顺序拆中间会给出可直接抄的调用代码和参数说明也会把我在实际数据上翻车的地方写清楚。2. 报文结构先立住112 位里到底装了什么2.1 DF 字段决定了解析分支ADS-B 的每条报文是 112 位扩展 squitter 是 112 位、短报文是 56 位工具包内部按位宽先分流。真正决定后续怎么解析的是前 5 位的 DFDownlink Format字段。DF17 是 ADS-B 最核心的一种携带 88 位的 ME 字段里面再按 Type Code 细分身份、位置、速度、状态。DF11 是 all-call replyDF4/5 是 surveillance 相关DF20/21 是 Comm-B。你如果只关心飞机位置绝大多数有效数据来自 DF17。理解这一点很关键因为工具包的解析入口通常按 DF 分派你传进去的报文如果 DF 不在支持列表里返回的就是空对象或者抛异常而不是“解析出一堆 None”。我在第一次接真实数据时就吃过这个亏采集卡里混进了大量 DF11 的应答脚本按 DF17 的假设去取 ME 字段结果经纬度全是垃圾值。正确做法是先看 DF再决定要不要往下走。DF 值含义是否含 ADS-B ME 字段常见用途17扩展 squitter是88 位位置、身份、速度18扩展 squitter非转发是TIS-B 相关11all-call reply否应答机存在性4 / 5surveillance altitude / identity否高度、Squawk20 / 21Comm-B否气象、状态2.2 ME 字段里的 Type Code 才是真正的路由键DF17 确认之后88 位 ME 字段的前 5 位是 Type CodeTC。TC1~4 是飞机识别呼号TC5~8 是地面位置TC9~18 是空中位置含高度和经纬度TC19 是速度TC20~22 是空中位置GNSS 高度TC28 是飞机状态TC31 是运行状态。工具包一般会按 TC 把 ME 字段再分派到不同的解码函数。这里有个容易忽略的点位置报文TC9~18里的经纬度不是直接编码的而是 CPRCompact Position Reporting格式单条报文只能解出一个“局部”坐标必须结合偶帧和奇帧两条报文才能算出全局位置。所以你在脚本里如果只喂一条位置报文拿到的经纬度要么是 None要么是相对参考点的偏移不是真实坐标。这一点后面第 4 章会专门讲怎么配对。2.3 CRC 校验为什么不能省ADS-B 报文末尾 24 位是校验字段但它的算法和普通 CRC 不完全一样对 DF17 来说校验字段是报文前 88 位做多项式除法后的余数接收端用同样的多项式再算一遍余数为 0 才算通过。工具包一般会提供crc_ok之类的布尔字段或者独立的校验函数。我建议在流水线入口就做过滤别等到解析出字段再回头查。原因很实际真实采集环境里误码率不低一条 CRC 不过的报文解出来的高度可能是 30000 英尺也可能是 -200 英尺你没法从数值本身判断对错。先校验再解析能挡掉大部分脏数据。常见做法是把校验和解析拆成两步校验失败的报文记日志丢弃而不是让它污染后续统计。3. 把解析跑起来从原始报文到结构化字段3.1 安装与最小可运行示例工具包是纯 Python 实现没有编译依赖常规做法是建虚拟环境后 pip 安装。下面这段是最小闭环给一条已知正确的 DF17 报文解析出呼号和高度。# 建议在独立虚拟环境中运行避免和系统里的其他解码库冲突 # python -m venv adsb-env source adsb-env/bin/activate # pip install adsb from adsb import Message # 一条 DF17 的十六进制报文去掉空格后传入 raw 8D4840D6202CC371C32CE0576098 msg Message(raw) # 先看基础分派结果确认 DF 和 Type Code print(DF:, msg.df) print(TC:, msg.tc) # 身份类报文才有 callsign位置类报文这里会是 None print(callsign:, msg.callsign) print(altitude:, msg.altitude) print(crc_ok:, msg.crc_ok)逻辑说明Message构造函数接收十六进制字符串内部先转成整数再按位宽切分。df和tc是最先要看的两个字段它们决定了后面哪些属性有值。callsign只在 TC1~4 时有意义altitude只在位置类报文里有值其余情况返回 None 是正常行为不是 bug。crc_ok用来做入口过滤。参数说明传入的字符串必须是偶数长度的十六进制大小写不敏感但不要带0x前缀和空格。如果你的数据源是字节流先bytes.hex()再传。工具包对 56 位短报文也支持但短报文没有 ME 字段tc会是 None。3.2 批量解析与字段落表单条解析只是验证真实场景是几千条报文批量过。下面这段把报文列表转成字典列表方便直接喂给 pandas 或者写 CSV。from adsb import Message raw_list [ 8D4840D6202CC371C32CE0576098, 8D40621D58C382D690C8AC2863A7, 8D40621D58C386435CC412692AD6, ] rows [] for raw in raw_list: try: msg Message(raw) except ValueError: # 长度不对或含非法字符直接跳过并记录 rows.append({raw: raw, error: invalid_format}) continue rows.append({ raw: raw, df: msg.df, tc: msg.tc, callsign: msg.callsign, altitude: msg.altitude, latitude: msg.latitude, longitude: msg.longitude, crc_ok: msg.crc_ok, }) for r in rows: print(r)逻辑说明try/except包住构造过程是因为真实数据里混入截断报文很常见一条坏数据不该让整批任务挂掉。字段统一落成字典缺失值保留 None后续用 pandas 的dropna或者按列过滤都方便。注意latitude/longitude对单条位置报文大概率是 None原因见 2.2 的 CPR 说明别在这里误判成解析失败。参数说明如果你要控制解析深度可以在构造时传validate_crcTrue让校验不过的报文直接抛异常或者传validate_crcFalse先放行、后面自己按crc_ok过滤。两种策略各有场景离线分析建议先放行再统计校验通过率实时流水线建议入口就拦。3.3 接进 pandas 做统计解析结果落成字典列表后接 pandas 就是几行的事。下面统计各 Type Code 的分布和校验通过率用来判断数据源质量。import pandas as pd from adsb import Message def parse_batch(raw_list): out [] for raw in raw_list: try: m Message(raw) out.append({ df: m.df, tc: m.tc, crc_ok: m.crc_ok, altitude: m.altitude, callsign: m.callsign, }) except ValueError: out.append({df: None, tc: None, crc_ok: False}) return pd.DataFrame(out) df parse_batch(raw_list) # 各 Type Code 占比判断数据里位置报文和身份报文的比例 print(df[tc].value_counts(dropnaFalse)) # 校验通过率低于 0.9 说明采集链路噪声偏大 print(crc pass rate:, df[crc_ok].mean()) # 只看校验通过且带高度的记录 valid df[(df[crc_ok]) (df[altitude].notna())] print(valid[altitude].describe())逻辑说明value_counts(dropnaFalse)把 None 也计入能看出有多少报文没解出 TC。校验通过率是个很实用的链路健康指标我一般拿它当采集质量的第一道体检。describe()看高度分布如果出现负值或者超过 60000 英尺的极端值基本可以判定是误码混进来了。参数说明raw_list建议按时间窗口分批比如每 10 秒一批避免一次性把几百万条读进内存。如果数据源是持续流用生成器逐条 yield 给parse_batch的变体别攒大列表。4. 位置解码与配对CPR 是绕不过去的坎4.1 偶帧奇帧为什么要成对CPR 把经纬度编码成 17 位的局部值单条报文只能确定飞机在一个网格里的相对位置必须用偶帧F0和奇帧F1两条报文联合解算才能得到全局坐标。两条报文的时间间隔不能太大常见做法是限制在 10 秒以内超过就丢弃重新等配对。工具包一般提供even/odd标志或者cpr_format字段你按这个字段把报文分到两个桶里。我见过有人图省事拿单条报文调latitude属性结果拿到的是 None 就以为工具坏了。其实这是协议本身的设计不是实现缺陷。正确流程是维护一个按 ICAO 地址索引的字典偶帧和奇帧各存最近一条两条都到齐且时间差在阈值内再调联合解算函数。4.2 配对解算的代码骨架下面这段演示配对逻辑用字典缓存最近一条偶帧和奇帧满足条件后解算全局坐标。import time from adsb import Message # 按 ICAO 地址缓存最近一条偶帧和奇帧 cache {} def handle(raw): m Message(raw) if m.df ! 17 or m.tc is None or not (9 m.tc 18): return None # 非位置报文不参与配对 icao m.icao slot cache.setdefault(icao, {even: None, odd: None}) # cpr_format: 0 为偶帧1 为奇帧 key even if m.cpr_format 0 else odd slot[key] (m, time.time()) even, odd slot[even], slot[odd] if even and odd and abs(even[1] - odd[1]) 10: # 用较新的一条作为参考帧解算 ref, other (even[0], odd[0]) if even[1] odd[1] else (odd[0], even[0]) lat, lon ref.global_position(other) return {icao: icao, lat: lat, lon: lon} return None逻辑说明cache以 ICAO 地址为键因为同一架飞机的偶奇帧必须来自同一发射源混了别的飞机就解错。cpr_format区分偶奇global_position接收另一帧作为参数完成联合解算。时间差阈值 10 秒是经验值实际可以按你的数据密度调密度高就收紧到 5 秒密度低放宽到 15 秒。参数说明global_position的参考帧选择会影响精度一般用时间较新的那条。如果你的场景对精度要求高解算后可以再用本地接收站坐标做一次合理性检查超出合理半径的直接丢弃。4.3 本地参考位置的作用CPR 解算分全局和本地两种模式。全局模式不需要参考点但要求偶奇帧配对本地模式只需要一条报文加一个已知参考位置比如你的接收站坐标适合数据稀疏、配不上对的情况。工具包通常提供local_position(ref_lat, ref_lon)这类接口。常见做法是两条路都留着配对成功走全局配对失败但有参考坐标就走本地本地解算的结果标记来源统计时分开看。本地模式的误差随距离参考点变远而增大超过一定半径比如 300 公里就不建议用了。这个半径不是硬标准取决于你的应用对误差的容忍度。5. 避坑与排查真实数据上翻过的车5.1 现象经纬度全是 None以为解析失败原因喂进去的是单条位置报文CPR 没配对全局解算条件不满足。这不是工具的问题是协议要求。解决按 4.2 的骨架维护偶奇帧缓存确认cpr_format字段有值、两条报文时间差在阈值内。排查时先打印tc和cpr_format确认报文确实进了位置分支。5.2 现象呼号解出来是乱码或者带一堆问号原因身份报文的 6 位字符编码表里有些值对应的是保留字符工具包按标准映射后可能输出占位符。另外报文本身 CRC 不过时字符位可能被误码污染。解决先看crc_ok不过的直接丢。通过校验但仍有占位符的属于发射端编码问题做统计时把非字母数字字符过滤掉即可不要试图“修正”成某个呼号。5.3 现象高度出现负值或超过 60000 英尺原因高度字段有 Q 位标志Q1 时是 25 英尺分辨率Q0 时是 100 英尺分辨率且编码方式不同。如果工具包按 Q1 的假设去解 Q0 的报文或者报文本身误码就会出极端值。解决解析后加一层合理性过滤民航高度一般在 -1000 到 60000 英尺之间超出范围的标记为可疑。同时检查crc_ok大部分极端值来自校验失败的报文。5.4 现象批量解析跑到一半内存爆掉原因把整个采集文件读成一个大列表再逐条解析几百万条报文加上每条一个 Message 对象内存扛不住。解决改成流式读取逐行解析、逐行落盘或者聚合别攒全量。pandas 那一步也按窗口分批每批处理完释放。我一般用生成器把文件读取和解析解耦内存占用能压到常数级。5.5 现象同一架飞机短时间内出现多个 ICAO 地址原因ICAO 地址是 24 位理论上唯一但真实数据里可能出现地址位误码或者你把不同接收源的数据混在一起没做去重。解决按 ICAO 聚合时加时间窗口和位置连续性检查短时间内位置跳变过大比如几秒内跨了几百公里的记录判为异常丢弃。多源数据合并前先按接收源打标签别直接混池。6. 进阶把解析结果接进实时流水线与质量看板跑通单条和批量之后真正有价值的是把这条链路做成可持续跑的流水线并且带质量监控。我的做法是三层采集层只负责把原始报文按行写入队列解析层用固定大小的线程池消费、逐条校验和解析聚合层按时间窗口统计校验通过率、各 TC 占比、位置解算成功率。三层之间用队列解耦任何一层慢了不会拖垮上游。下面这段是聚合层的骨架按 10 秒窗口输出一份质量快照可以直接打到日志或者推给监控。import time from collections import defaultdict class QualityWindow: def __init__(self, window_sec10): self.window_sec window_sec self.reset() def reset(self): self.start time.time() self.total 0 self.crc_pass 0 self.tc_count defaultdict(int) self.pos_ok 0 def add(self, msg): self.total 1 if msg.crc_ok: self.crc_pass 1 if msg.tc is not None: self.tc_count[msg.tc] 1 if msg.latitude is not None: self.pos_ok 1 def snapshot(self): # 窗口到期输出一份快照并重置 if time.time() - self.start self.window_sec: return None snap { total: self.total, crc_rate: self.crc_pass / self.total if self.total else 0, pos_rate: self.pos_ok / self.total if self.total else 0, top_tc: sorted(self.tc_count.items(), keylambda x: -x[1])[:3], } self.reset() return snap逻辑说明add每来一条报文更新计数snapshot在窗口到期时算比率并重置。crc_rate低于 0.9 说明链路噪声大pos_rate突然掉到接近 0 说明位置报文配对出了问题top_tc能看出数据里主要是身份报文还是位置报文。这三个指标组合起来基本能定位大部分采集侧异常。参数说明window_sec按你的数据密度调密度高用 10 秒密度低用 30 秒窗口太短样本不够比率会抖。top_tc只取前三避免日志膨胀。验证方法上我习惯拿一段已知正确的报文做回归固定一批报文跑解析比对字段快照任何一次改动后重跑字段对不上就回滚。这个习惯是从一次升级后呼号解析全错、排查了半天才发现是字符表映射改动的教训里来的。从那以后我每次动解析逻辑都强制走一遍固定样本回归再上真实数据。希望这套拆法帮到你少在 CPR 配对和 CRC 过滤上走弯路。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
