北达斯港口
- 作者仓库星标 43
- 许可证 GPL-3.0
- 作者仓库 flightjar
- 领域
- 文档
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 94 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @MrSuttonmann · GPL-3.0
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 读取环境变量
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
pyModeS 位于 GitHub 上的`junzis/pyModeS`(默认分支`main`)。 BDS解码器位于`src/pyModeS/decoder/bds/bdsXX.py`下,助手位于`_helpers.py`下。通过 GitHub API 获取`/tmp/pymodes/`(原始 CDN 有时 404 秒;内容 API 可靠):
pyModeS 在 56 位有效负载上作为具有 `(payload >> (55 - i)) & mask` 索引的 Python int 运行(从有效负载位 0 开始,MSB 优先)。 C# 端口保持相同的位索引,因此移植的算术与 Python 一对一地读取。将您的新方法添加到`CommB.cs`中的`public static class CommB`中。使用`CommB.cs`中已有的帮助器:
`CommB.Infer(payload)` 返回一条 `Candidates` 记录,每个启发式寄存器包含一个布尔值。仅当只有一个候选者验证时,`MessageDecoder.InferCommB(msg)`才返回解码的消息。这种单场比赛的规则是有意为之的:多场比赛的有效载荷是不明确的并被丢弃,而不是冒着解码字段污染飞机状态的风险
对于每个解码字段:向 `Aircraft` 添加可为 null 的属性(例如 `public int? WindshearLevel { get; set; }`)。将同名属性添加到`SnapshotCommB`。在`ApplyCommB`中,添加一个从`DecodedMessage`分配的`case "X,Y":`;不要触及其他寄存器中的字段
增强模式S面板完全由快照中的`a.comm_b`驱动。在 `detail_panel.js` 中:在 `buildPopupContent` 中的 `.panel-met-grid` 内添加占位符图块标记 — 与现有图块 (`<div class="metric pop-met-xxx" hidden><div class="label">…</div><div class="val"></div></div>`) 的形状相同。
`CommBTests.cs` 遵循两种模式;将两者用于新寄存器:验证器接受+拒绝:从 pyModeS 的`test_bds_commb.py`中选择一个黄金向量十六进制,断言`IsBdsXX`接受它,然后构造应被拒绝的合成有效负载(全零,超出范围的值,状态位/值位不一致)
`dotnet/tests/FlightJar.Core.Tests/State/AircraftRegistryTests.cs` + `FakeDecoder.cs` 使用假六角键(`BD44`→预建`DecodedMessage`)来练习`ApplyCommB` + `BuildCommBSnapshot`,无需真正的线字节。添加一个`BDxx`装置和测试,证明新字段落在快照中并正确老化过去的`CommBMaxAge`。
`tests/e2e/layout.spec.js`中的`detail panel renders Enhanced Mode S section when comm_b is present`测试注入了带有完整`comm_b`块的虚假快照。如果新寄存器添加了用户可见的图块,则扩展固定装置并断言新标签出现。
# Porting a pyModeS BDS register to FlightJar
FlightJar's Comm-B decoder matches pyModeS 3.x byte-for-byte. When adding
another register, keep the wire behaviour identical so we can cross-check
golden vectors from pyModeS's own test corpus. Every deviation (even a
"cleanup") is a source of silent drift later.
## Touchpoints
A full port spans six files and one frontend + one docs update:
1. **`dotnet/src/FlightJar.Decoder/ModeS/CommB.cs`** — add
`IsBdsXX(payload)` validator + `DecodeBdsXX(payload)` decoder +
`BdsXXData` record. Extend the `Candidates` record and `Infer()` to
include the new register.
2. **`dotnet/src/FlightJar.Decoder/ModeS/DecodedMessage.cs`** — add
one field per value the register exposes.
3. **`dotnet/src/FlightJar.Decoder/ModeS/MessageDecoder.cs`** — add a
branch in `InferCommB` that builds a `DecodedMessage` for the new
register; extend `Merge()` to copy the new fields.
4. **`dotnet/src/FlightJar.Core/State/Aircraft.cs`** — add per-field
state + one `BdsXXAt` timestamp.
5. **`dotnet/src/FlightJar.Core/State/AircraftRegistry.cs`** — add a
`case "X,Y":` branch in `ApplyCommB` that writes the fields +
stamps the timestamp. Extend `BuildCommBSnapshot` to gate the
fields on freshness and feed the `SnapshotCommB` record.
6. **`dotnet/src/FlightJar.Core/State/RegistrySnapshot.cs`** — add
the fields to `SnapshotCommB` (nullable, snake-case on the wire).
7. **`app/static/detail_panel.js`** — add metric tiles to the
`.panel-met-grid` placeholder markup in `buildPopupContent` and
a `set('.pop-met-xxx', …)` call per field in `renderCommBSection`.
8. **`dotnet/tests/FlightJar.Decoder.Tests/ModeS/CommBTests.cs`** —
validator accept/reject tests + golden-vector decoder tests using
hex captures from pyModeS's `tests/test_bds_commb.py`.
9. **`README.md`** — add the new fields to the "Enhanced Mode S air
data" bullet and flag any register-specific caveats.
10. **`CLAUDE.md`** — update the decoder list + any behavioural
nuances.
## Step 1 — Fetch the pyModeS reference
pyModeS lives at `junzis/pyModeS` on GitHub (default branch `main`).
BDS decoders live under `src/pyModeS/decoder/bds/bdsXX.py`, helpers
under `_helpers.py`. Fetch into `/tmp/pymodes/` via the GitHub API
(the raw CDN sometimes 404s; the contents API is reliable):
```bash
# List available registers.
curl -sL "https://api.github.com/repos/junzis/pyModeS/contents/src/pyModeS/decoder/bds?ref=main" \
| grep '"download_url"'
# Fetch a specific register + the shared helpers.
for f in bds45 _helpers _infer; do
curl -sL "https://raw.githubusercontent.com/junzis/pyModeS/main/src/pyModeS/decoder/bds/$f.py" \
> /tmp/pymodes/$f.py
done
# And the golden-vector test corpus.
curl -sL "https://raw.githubusercontent.com/junzis/pyModeS/main/tests/test_bds_commb.py" \
> /tmp/pymodes/test_bds_commb.py
```
## Step 2 — Port the validator + decoder
pyModeS operates on a 56-bit payload as a Python int with `(payload >> (55 - i)) & mask`
indexing (MSB-first from payload bit 0). The C# port keeps **identical**
bit indexing so the ported arithmetic reads one-to-one next to the Python.
Add your new methods inside `public static class CommB` in `CommB.cs`.
Use the existing helpers that are already in `CommB.cs`:
- `WrongStatus(payload, statusBit, valueStart, valueWidth)` — mirrors
pyModeS `_helpers.wrong_status` (status-bit / value-field consistency).
- `Signed(value, width, sign)` — sign-magnitude to signed int (NOT
two's complement; Mode S splits sign + magnitude bits).
- `NormaliseAngle(deg)` — wrap into `[0, 360)`.
Every range gate in `IsBdsXX` must match pyModeS's validator. If pyModeS
rejects `> 600 kt` but you port it as `>= 600`, you will silently accept
values pyModeS would reject.
## Step 3 — Wire into inference
`CommB.Infer(payload)` returns a `Candidates` record with one bool per
heuristic register. `MessageDecoder.InferCommB(msg)` returns a decoded
message only when **exactly one** candidate validates. This single-match
discipline is intentional: multi-match payloads are ambiguous and
dropped rather than risk polluting aircraft state with fields decoded
against the wrong register. Do not relax it without a replacement
disambiguation strategy (e.g. pyModeS Phase 3 known-state scoring).
BDS 4,5 (meteorological hazard) is opt-in in pyModeS because it
false-positives on non-meteorological payloads. When porting, keep
the validator strict; if ambiguity becomes a problem, add a
`Candidates.Bds45` branch behind a config flag rather than unconditionally
accepting it.
## Step 4 — Extend state + snapshot
For every decoded field:
1. Add a nullable property to `Aircraft` (e.g. `public int? WindshearLevel { get; set; }`).
2. Add an identically-named property to `SnapshotCommB`.
3. In `ApplyCommB`, add a `case "X,Y":` that assigns from the
`DecodedMessage`; **do not** touch fields from other registers
(each register owns its own slice of state).
4. In `BuildCommBSnapshot`, compute a `bdsXXFresh` flag using
`CommBMaxAge` (120 s) and use it to gate every field from the
register. Include the register's `BdsXXAt` timestamp on the
snapshot so the frontend can age values out independently.
Naming convention on the wire: snake_case via the global serializer
config in `FlightJar.Api.Configuration`. `MagneticHeadingDeg` becomes
`magnetic_heading_deg` without any extra attributes.
## Step 5 — Extend the frontend panel
The Enhanced Mode S panel is driven entirely by `a.comm_b` in the
snapshot. In `detail_panel.js`:
1. Add placeholder tile markup inside `.panel-met-grid` in
`buildPopupContent` — same shape as existing tiles
(`<div class="metric pop-met-xxx" hidden><div class="label">…</div><div class="val"></div></div>`).
2. Add a `set('.pop-met-xxx', value)` call in `renderCommBSection`
that computes the formatted string or returns `null` to hide the
tile.
Use the existing `uconv('alt' | 'spd' | 'vrt' | 'dst', value)` helper
for unit-system-aware formatting. Raw-unit values (Mach, temperature,
degrees, percent) format inline.
## Step 6 — Tests
`CommBTests.cs` follows two patterns; use both for the new register:
1. **Validator acceptance + rejection**: pick a golden-vector hex
from pyModeS's `test_bds_commb.py`, assert `IsBdsXX` accepts it,
then construct synthetic payloads that should be rejected (all
zeros, out-of-range values, status-bit / value-bit inconsistency)
and assert they're rejected.
2. **Decode golden vector**: decode the pyModeS golden hex and
assert each field matches the pyModeS oracle value to within the
same `abs=` tolerance the pyModeS test uses.
Also add an end-to-end test in `MessageDecoder_RoutesUnambiguousBdsXXOnDf20`
to prove the `InferCommB` branch wires through.
## Step 7 — Add an integration test
`dotnet/tests/FlightJar.Core.Tests/State/AircraftRegistryTests.cs` +
`FakeDecoder.cs` use fake hex keys (`BD44` → pre-built `DecodedMessage`)
to exercise `ApplyCommB` + `BuildCommBSnapshot` without real wire
bytes. Add a `BDxx` fixture and a test proving the new field lands
in the snapshot and ages out correctly past `CommBMaxAge`.
## Step 8 — Playwright smoke (optional)
The `detail panel renders Enhanced Mode S section when comm_b is present`
test in `tests/e2e/layout.spec.js` injects a fake snapshot with a full
`comm_b` block. If the new register adds a user-visible tile, extend the
fixture and assert the new label appears.
## Step 9 — Verify
```bash
cd dotnet && dotnet format FlightJar.slnx --verify-no-changes
dotnet build FlightJar.slnx
dotnet test FlightJar.slnx
cd ..
node --test tests/js/
npx playwright test
```
All five must pass before the port is done. Formatter drift and
Playwright regressions are the two most common surprises.
## Do not
- Do not rename pyModeS's field names in the decoded record unless
you have a codebase-wide reason. `static_air_temperature` in pyModeS
is `StaticAirTemperatureC` in `CommB.cs` — the `C` suffix is the
only concession, and it's there because our wire convention suffixes
every physical-unit field.
- Do not persist Comm-B state in `state.json.gz`. The 120 s freshness
window is far shorter than the 30 s persist cadence + 10 min
`PersistMaxAge`, so restored Comm-B values would be stale on load.
- Do not bypass `CommB.Infer`'s single-match gate by eagerly decoding
every register. Multi-match payloads mean one of the decodes is
wrong; you cannot tell which without an external reference signal,
so dropping ambiguous payloads is the safe default.
- Do not add register-specific env vars for opt-in registers without
updating `README.md`'s configuration reference table.
按说明文件中的顺序排列。
接触点
第 1 步 — 获取 pyModeS 参考
第 2 步 — 移植验证器 + 解码器
第 3 步 — 连接到推理
步骤 4 — 扩展状态 + 快照
文件/命令 -> dotnet/src/FlightJar.Decoder/ModeS/CommB.cs · IsBdsXX(payload) · DecodeBdsXX(payload) · BdsXXData · Candidates · Infer() · dotnet/src/FlightJar.Decoder/ModeS/DecodedMessage.cs · dotnet/src/FlightJar.Decoder/ModeS/MessageDecoder.cs
内容校验值 -> 810e1dbb1261
当前原文的自动摘译,尚未人工审校。
接触点
一个完整的端口跨越六个文件和一个前端 + 一个文档更新:
dotnet/src/FlightJar.Decoder/ModeS/CommB.cs- 添加IsBdsXX(payload)验证器 +DecodeBdsXX(payload)解码器 +BdsXXData记录。扩展Candidates记录和Infer()以包含新寄存器。第 2 步 — 移植验证器 + 解码器
pyModeS 在 56 位有效负载上作为具有
(payload >> (55 - i)) & mask索引的 Python int 运行(从有效负载位 0 开始,MSB 优先)。 C# 端口保持相同的位索引,因此移植的算术与 Python 一对一地读取。在CommB.cs的public static class CommB中添加新方法。使用CommB.cs中已有的帮助器:步骤 4 — 扩展状态 + 快照
对于每个解码字段:将可为空的属性添加到
Aircraft(例如public int? WindshearLevel { get; set; })。将同名属性添加到SnapshotCommB。在ApplyCommB中,添加一个从DecodedMessage分配的case "X,Y":;不要触及其他寄存器中的字段