简介：这份资源是面向 Python 开发者的 ADS-B 消息处理工具包，适合对航空监视数据解析、飞行器追踪感兴趣的初学者与中级开发者，用于接收并处理与 dump1090 等软件输出格式类似的 ADS-B 报文。压缩包共 49 个文件，约 55KB，以 23 个 py 源码文件为核心，辅以 8 个 rst 文档、5 个 txt 说明及 yml、makefile、coveragerc 等配置脚本，另含示例 kml 与测试用日志文件，目录涵盖 src、tests、docs、examples 等模块，结构清晰便于按需查阅。目前已有 1017 人学习下载。项目虽处于开发初期，但已提供 API 级文档与基础测试用例，读者可据此了解报文解析思路、搭建本地测试环境，并参考示例代码快速接入自己的数据流处理流程。
1. 拿到一个 Python 版 ADS-B 工具包，先别急着跑
如果你手上有一块 RTL-SDR 或者一台能输出原始 IQ 数据的接收机，想用 Python 把 1090MHz 上的 ADS-B 报文解出来，那这个叫 adsb 的 Python 工具包大概率会被你搜到。它解决的不是「怎么接收信号」的问题，而是「拿到原始报文之后怎么解析、怎么还原成飞机位置」这一段。换句话说，射频前端你自己搞定，它负责把一串十六进制报文变成你能看懂、能画图的结构化数据。
适合谁？适合已经有一点 Python 基础、手里有接收设备或者现成 IQ 录制文件、想快速验证解码链路是否通的人。不适合完全没接触过 Mode S 报文结构、指望装完就能看到地图的新手。这篇笔记按「它是什么 → 怎么装怎么跑 → 报文怎么解 → 坑在哪 → 怎么验证」的顺序拆，中间会给可直接抄的代码和参数说明，最后落到一个我常用的自检习惯上。
2. 环境与依赖：把解码链路先搭通
2.1 为什么选 Python 而不是现成的解码器
市面上有成熟的 C 系解码器，性能好、吞吐高，但二次开发成本不低。你要改一个字段提取逻辑、加一个自定义输出格式，往往得动编译链。Python 版的价值在于：报文解析这一层用纯 Python 写，字段结构清晰，改起来快，适合做数据清洗、批量离线分析、和 pandas / matplotlib 直接对接。
代价也要说清楚。纯 Python 解报文，单条开销比 C 大一个量级，实时高密度场景（比如机场附近每秒几百条）会吃力。常见做法是：实时链路用 C 解码器出原始报文，Python 只做后处理和可视化；离线分析或者低密度场景，直接用 Python 全链路。我一般会先确认自己的场景是「实时」还是「离线」，再决定要不要上这个包。
2.2 安装与最小可运行环境
依赖主要是 Python 3 环境本身，加上常见的数值和串口/网络库。下面这套是我在干净虚拟环境里验证过的流程，版本号不写死，按你本地实际解析即可。
# 建独立环境，避免和系统 Python 打架 python3 -m venv adsb-env source adsb-env/bin/activate # Windows 用 adsb-env\Scripts\activate # 升级打包工具，老版本 pip 装本地包容易出玄学问题 python -m pip install --upgrade pip setuptools wheel # 装工具包本体（按你拿到的源码包/发布包实际名称替换） pip install ./adsb # 常用配套：数值处理、绘图、串口 pip install numpy pandas matplotlib pyserial逻辑说明：虚拟环境是为了隔离，ADS-B 这类工具经常依赖特定版本的解析库，装到系统环境里以后升级别的项目会互相污染。--upgrade pip setuptools wheel这一步别省，我踩过老 pip 装带pyproject.toml的包直接报元数据错误的坑。最后一行pip install ./adsb是本地源码安装，如果你拿到的是 wheel 包就换成对应文件名。
参数说明：pyserial只有在你从串口读接收机数据时才需要，纯离线解析 IQ 文件可以不装。matplotlib用于后面画轨迹，不画图也可以跳过。
装完先做一次导入自检，确认包能加载、版本能打印：
import adsb print(getattr(adsb, "__version__", "no version attr")) print([n for n in dir(adsb) if not n.startswith("_")][:20])这段的作用是确认包结构。如果dir()出来一堆空列表或者只有__init__，说明你装的是个空壳或者装错了目录，后面所有步骤都白搭。这一步三十秒，能省掉半小时的「为什么解不出来」排查。
2.3 数据从哪来：三种输入形态
工具包本身不产生数据，你得先想清楚输入是什么。常见三种：
| 输入形态 | 典型来源 | 处理方式 |
|---|---|---|
| 原始十六进制报文 | 接收机串口输出、日志文件 | 直接喂给报文解析函数 |
| IQ 采样文件 | SDR 录制、离线回放 | 先做解调，再进解析 |
| 已解调比特流 | 上游解码器输出 | 按帧同步后解析 |
第一种最省事，也是这个包最直接的用法。第二种需要额外的解调环节，Python 做 2MHz 采样率的解调会比较慢，建议先用现成工具转成报文再进来。第三种适合你已经有一层解码、只想复用字段解析逻辑的场景。选型上，我一般优先走第一种，链路短、出错点少。
3. 报文解析：从十六进制到经纬度
3.1 Mode S 报文的基本结构先立住
ADS-B 报文本质是 Mode S 下行链路帧，常见 112 位（长帧）和 56 位（短帧）。长帧里前 5 位是 DF（下行格式），DF=17 才是 ADS-B 的扩展应答，DF=17 里再按 Type Code（TC）区分身份、位置、速度、呼号等。位置报文（TC 在 9–18 和 20–22 区间）用的是 CPR 压缩坐标，单条报文只能解出一个模糊位置，必须成对（偶帧 + 奇帧）才能还原精确经纬度。
这就是很多人第一次用会翻车的地方：拿到一条位置报文直接调解码，出来一个明显不对的坐标，以为是包坏了。其实不是，CPR 全局解码需要偶奇配对，局部解码需要参考位置。这个包把两种模式都留了口子，你得按场景选。
3.2 单条报文解析的可抄代码
下面这段演示从一条十六进制报文出发，识别 DF、TC，并判断它属于哪类信息。报文用占位示例，实际替换成你抓到的即可。
from adsb import decoder # 按实际模块路径调整 raw_hex = "8D40621D58C382D690C8AC2863A7" # 示例长帧，替换为真实报文 msg = decoder.decode_hex(raw_hex) # DF 决定帧类型，17 才是 ADS-B 扩展应答 print("DF:", msg.df) print("ICAO:", msg.icao) # 24 位飞机地址 print("Type Code:", msg.tc) # 按 TC 分流：位置、呼号、速度走不同字段 if msg.tc is not None and 9 <= msg.tc <= 18: print("这是空中位置报文，需要 CPR 配对") elif msg.tc == 4: print("这是呼号/识别报文") elif msg.tc == 19: print("这是速度报文")逻辑说明：decode_hex负责把十六进制串转成比特、切字段。先看df，不是 17 的直接丢弃，省得后面字段错位。icao是飞机的 24 位地址，是你做轨迹关联的主键，务必保留。tc是分流依据，不同 TC 的字段布局完全不同，不能一套字段读到底。
参数说明：raw_hex长度必须是 28 个十六进制字符（112 位）或 14 个（56 位），长度不对会直接抛异常，这是好事，别用 try 吞掉。msg.tc在某些实现里对短帧返回 None，判断前先判空。
3.3 CPR 位置还原：偶奇配对与参考点
位置还原是整条链路最容易出错的一环。全局解码要求偶帧和奇帧的时间差在 10 秒以内（空中目标），地面目标更短。超过这个窗口，配对无效，解出来的坐标会飘。下面是一个配对还原的骨架：
from adsb import cpr # even/odd 分别是从偶帧、奇帧解析出的 17 位 CPR 经纬度编码 # 这两个值来自 msg 的 cpr_lat / cpr_lon 字段（按实际字段名调整） even = {"lat": 93000, "lon": 51372} # 占位示例值 odd = {"lat": 74158, "lon": 50194} # 占位示例值 lat, lon = cpr.global_decode( even_lat=even["lat"], even_lon=even["lon"], odd_lat=odd["lat"], odd_lon=odd["lon"], latest="even", # 以哪一帧为最新，影响结果取哪组 surface=False # 地面目标传 True，解码范围不同 ) print(f"{lat:.5f}, {lon:.5f}")逻辑说明：global_decode内部做的是把两组 17 位编码拼成完整坐标，latest参数决定用偶帧还是奇帧作为基准，选错会有几米的偏差，一般以时间更近的那帧为准。surface必须和目标状态一致，地面目标的 CPR 网格更细，传错了解出来的位置会偏出好几公里。
参数说明：even_lat/even_lon是偶帧的原始编码值，不是度数，别自己先转。latest取值通常是"even"或"odd"。如果你只有单帧、又有可靠的参考位置（比如接收站坐标），可以改用局部解码local_decode，传参考经纬度和单帧编码，精度依赖参考点距离，一般 180 公里内可用。
提示：CPR 配对失败最常见的表现是坐标落在海里或者另一个半球，先检查偶奇帧时间戳差，再检查
surface标志，最后才怀疑编码值本身。
4. 避坑与排查：五条血泪记录
4.1 现象：解出来的 ICAO 全是同一个值
原因：报文切位偏移错了。DF 字段没先判，直接按固定偏移读 ICAO，短帧和长帧混在一起就会错位。解决：解析前先按长度和 DF 分流，DF=17 才走 ADS-B 字段布局，其他 DF 单独处理或丢弃。我一般会在解析函数入口加一条断言，长度不是 14 或 28 直接拒绝。
4.2 现象：位置偶尔正确、偶尔飞到几千公里外
原因：偶奇帧配对窗口超了，或者把地面目标和空中目标混着配。解决：给每条位置报文打时间戳，配对前先算时间差，超过 10 秒（空中）或更短（地面）直接丢弃这对。同时把surface标志纳入配对键，地面帧只和地面帧配。
4.3 现象：呼号解出来带乱码或尾部填充字符
原因：呼号报文用的是 6 位字符集（不是 ASCII），且尾部用空格填充。直接按 ASCII 解会出乱码。解决：用工具包提供的字符集映射表逐字符查表，解完strip()掉尾部空格。别自己写chr()硬转，6 位字符集和 ASCII 不是一回事。
4.4 现象：实时流跑几分钟后内存持续上涨
原因：把每条报文的对象都塞进一个列表做历史缓存，没有淘汰策略。解决：按 ICAO 做字典缓存，每个目标只保留最近 N 条（比如 20 条）用于配对和轨迹，超出就丢最旧的。离线批量分析才需要全量保留，实时链路一定要设上限。
4.5 现象：同一架飞机出现两条轨迹
原因：ICAO 地址读取时大小写或前导零处理不一致，导致同一目标被当成两个键。解决：ICAO 统一转成大写、补齐 6 位十六进制再作为字典键。这个坑很隐蔽，日志里肉眼看两个键长得差不多，实际差一个前导零。
5. 验证与进阶：用已知目标反推链路是否正确
链路搭完，怎么确认解的是对的？我的习惯是找一个已知位置的参照物做闭环验证。具体做法：记录接收站自身坐标，抓一段连续报文，用局部解码模式解出目标位置，再和公开的航班轨迹做粗对比。偏差在合理范围内（受报文密度和配对质量影响，几百米到几公里都算正常），说明链路通；偏差离谱，回到第 4 章逐条排查。
再进一步，可以做解码质量统计，这比单看几条报文靠谱得多：
from collections import Counter stats = Counter() for raw in raw_messages: # raw_messages 是你的报文列表 try: msg = decoder.decode_hex(raw) except Exception: stats["parse_error"] += 1 continue stats[f"df_{msg.df}"] += 1 if msg.tc is not None: stats[f"tc_{msg.tc}"] += 1 total = sum(stats.values()) for k, v in stats.most_common(10): print(f"{k}: {v} ({v/total:.1%})")这段的价值在于把「感觉能解」变成「比例可量化」。正常情况下df_17应该占大头，parse_error应该很低；如果parse_error超过一成，多半是输入里混了非报文数据或者长度不对；如果df_17很少，检查你的接收前端是不是把别的帧也灌进来了。参数上raw_messages建议至少几千条才有统计意义，太少波动大。
还有一个容易被忽略的点：时间同步。ADS-B 报文本身带的时间信息有限，你的配对窗口依赖本地接收时间戳。如果从文件回放，时间戳要按原始记录还原，不能全打成当前时间，否则配对窗口判断全错。我一般会在回放时按报文间隔累加一个虚拟时钟，而不是用time.time()。
从那以后我每次接一个新的解码链路，都强制先跑一遍上面的统计脚本，再拿一个已知目标做闭环，两步都过了才敢往上层业务喂数据。这套习惯帮我挡掉过好几次「看起来能跑、其实字段全错位」的假成功。希望帮到你。
本文还有配套的精品资源，点击获取
