emuehlstein/OpenGD77_SSRFLite_Generator

# OpenGD77 SSRFLite 生成器 一个适用于运行 OpenGD77 固件的对讲机以及兼容 CHIRP 的对讲机的、可复现且数据驱动的 codeplug 构建器。该生成器接收 [SSRF-Lite YAML](#ssrflite) 文件并生成： - **OpenGD77 CSVs**：用于导入 OpenGD77 CPS 的 `Channels.csv`、`Contacts.csv`、`TG_Lists.csv`、`Zones.csv` - **CHIRP CSV**：通过 CHIRP 软件兼容大多数业余无线电的通用格式 - **VGC N76 CSV**：适用于 VGC N76 对讲机的格式 ## 输出格式 ### OpenGD77 格式（默认） 生成适用于通过 OpenGD77 CPS 导入的 OpenGD77 专用 CSV 文件。包含完整的 DMR 支持，涵盖联系人、通话组列表和区域。 📖 **[OpenGD77 文档](README.md)**（此文件） ### CHIRP 格式 生成兼容 [CHIRP](https://chirpmyradio.com/) 的通用 CSV 文件，这是一款免费、开源的用于对数百种业余无线电型号进行编程的工具。仅导出 FM/模拟信道（不包含 DMR 和数字模式）。 📖 **[CHIRP Generator 文档 →](README_CHIRP.md)** 支持的对讲机包括：Baofeng UV-5R、Yaesu FT-60/FT-7800、Icom IC-880/IC-2730、Kenwood TH-D72/TM-V71 以及[更多型号](https://chirpmyradio.com/projects/chirp/wiki/Supported_Radios)。 ### VGC N76 格式 生成兼容 VGC N76 对讲机且按库整理的 CSV 文件。 📖 **[N76 Generator 文档 →](README_N76.md)** ## 概览 ``` ┌────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ SSRF-Lite data │ → │ Profiles (selection│ → │ Policies (opinions │ │ Reference-only │ │ & scoping) │ │ & rendering rules) │ └────────────────┘ └────────────────────┘ └────────────────────┘ ``` - **SSRF-Lite** 记录权威的射频事实：谁拥有某个系统，其物理位置，如何发射，以及存在哪些授权。 - **Profiles** 选择哪些 SSRF 分配适用于请求的配置（例如：“Chicago GMRS”或“仅限紧急情况”）。 - **Policies** 表达特定于使用者的意见，例如发射启用、扫描跳过默认值、区域成员资格、排序和命名约定。 保持这些关注点相互分离，使得 SSRF-Lite 能够跨对讲机、服务和策略堆栈重复使用。 **配置库：** - **RF 系统和信道规划数据库** – [浏览 SSRF 文档 →](docs/ssrf/README.md) - **用于各种地理位置的示例 Profiles** – [浏览 Profile 文档 →](docs/profiles/README.md) - **Policy 叠加和分配覆盖** – [浏览 Policy 文档 →](docs/policies/README.md) **理念：** 本项目坚持的几个理念： - **关注点分离：** 保持 RF 参考数据独立于 codeplug 呈现形式，从而使相同的事实能够支持多种构建。 - **分层配置：** SSRF 参考 → profile 选择 → policy 叠加，允许每一层独立演进而不破坏其他层。 - **可复现的输出：** 生成器基于版本控制的数据和确定性的工具（`uv`）运行，因此 CSV 能够可靠地重新生成和比对。 - **安全优先的默认设置：** 除非明确许可，否则发射保持禁用状态，从而降低非法或意外发射的风险。 - **可扩展性：** 新的服务、profiles 或对讲机应能通过添加额外的 SSRF 文件或 policies 接入，而无需重构核心代码。 ## 快速开始 1. **安装前提条件** – 确保您的系统上安装了 Python 3.10+ 和 `uv` 包管理器。 2. **克隆代码库并进入目录。** git clone https://github.com/emuehlstein/OpenGD77_SSRFLite_Generator.git cd OpenGD77_SSRFLite_Generator 3. **使用 `uv` 同步虚拟环境。** 这将创建 `.venv/` 并安装生成器、Pydantic 模型和测试工具。 uv sync 4. **构建 OpenGD77 CSV 包。** 结果将存放在 `opengd77_cps_import_generated/` 中。 uv run python generate_opengd_import.py 5. **导入到 CPS。** 在 OpenGD77 CPS 中选择 **File → CSV → Import CSV**，指向生成的文件夹，并加载 Channels/Contacts/TG Lists/Zones 文件。 需要其他 profile？添加如 `--profile chicago_amateur` 或 `--profile gmrs_only` 等标志。当您希望在 Amateur 默认设置之外启用发射时，请添加 `--tx-service gmrs`（或 `--tx-all-services`）。 要在编辑后验证所有内容，请运行冒烟测试： ``` uv run python -m pytest tests/test_profiles.py ``` ## SSRF‑Lite 本项目包含一种用于共享 RF 系统信息的拟议格式，即“SSRF-Lite”，它是美国国防部 (US DoD) 使用的 SSRF 格式的简化和 YAML 化版本。 - 项目文档：[SSRF‑Lite Spec](./ssrf/_schema/SSRF-Lite-Spec.md) - 背景（NTIA SSRF）：[https://www.ntia.gov/publications/2023/standard-spectrum-resource-format-ssrf](https://www.ntia.gov/publications/2023/standard-spectrum-resource-format-ssrf) ### 验证 每个 SSRF-Lite 文件都对应一个版本化的 JSON Schema，该 schema 与规范一起发布在 [`ssrf-lite-0.5.3.schema.json`](./ssrf/_schema/ssrf-lite-0.5.3.schema.json)。每个 YAML 文件 都包含一个 `# yaml-language-server:` modeline 以及顶层的 `$schema` 和 `ssrf_lite_version: "0.5.3"` 键，因此编辑器和 CI 无需导入 Python 模型即可进行验证。 ``` make schema # regenerate the JSON Schema from the Pydantic models make stamp-headers # (re)apply schema headers to every SSRF-Lite YAML make validate-schema # verify the schema and headers are up to date (CI) ``` ## Profiles & Policies Profiles 为 SSRF 参考数据提供包含过滤器。每个 profile 位于 `profiles/.yml`，并在 `profile.include` 下声明 glob 模式以及可选的服务过滤器。 Profiles 现在可以使用可选的 `profile.policy` 块指向一个或多个 **policy** 文件： ``` profile: name: "chicago_amateur" include: paths: - "ssrf/plans/US/amateur/*.yml" - "ssrf/systems/US/IL/Cook/Chicago/amateur/*.yml" policy: files: - policies/base.yml paths: - policies/chicago/**/*.yml ``` 为了保持叠加层的可组合性，较大的系统和规划被拆分为专注的文件（例如 `policies/ham_fm_simplex.yml` 或 `policies/marine_vhf.yml`）。Profiles 按需选择所需部分，使得将来将多个 profiles 或叠加层组合在一起变得非常直接。 Policies 是简单的 YAML 文档，用于描述应如何渲染选定的分配。典型的键包括： - `assignments..codeplug.name` – 重命名信道、标记 `rx_only`、选择 `preferred_contacts` 等。 - `assignments..zones` – 提供区域包含/排除列表。 - `assignments..scan` – 配置 `all_skip`、`zone_skip`、`tot`、`power`、`vox` 及相关扫描提示。 - `assignments..tx` – 为仅接收构建明确禁用发射。 如果 profile 省略了 `policy` 块，则生成器将在存在 `policies/.yml` 时回退到该文件，从而保持小型构建的流程便捷。 可用的入门 profiles： - `default` – 包含国家规划系统和芝加哥地区系统的广泛构建。 - `chicago_light` – 专注于 GMRS 和公共安全的精简扫描列表。 - `chicago_amateur` – 芝加哥业余中继台加上 simplex 规划。 - `chicago_gmrs` – 芝加哥 GMRS 中继台和全美 GMRS 规划。 - `gmrs_only` – 带有 policy 调优 GMRS 区域布局的全美 GMRS 规划。 `policies/gmrs_only.yml` 将全美 GMRS 规划分类到 `GMRS Simplex`、`GMRS Listen` 和 `GMRS Repeaters` 区域中，同时默认将仅限 FRS 的互调信道设为仅接收。 检查可用的 profiles： ``` uv run python generate_opengd_import.py --list-profiles ``` 使用特定 profile 生成： ``` uv run python generate_opengd_import.py --profile chicago_light uv run python generate_opengd_import.py --profile gmrs_only --tx-service gmrs # GMRS-only build, TX enabled on GMRS channels ``` 在其他服务上启用发射（默认仅限 Amateur）： ``` uv run python generate_opengd_import.py --profile chicago_light --tx-service gmrs # 允许在 radio 支持的所有地方进行 transmit uv run python generate_opengd_import.py --profile chicago_light --tx-all-services ``` 预览 profile 将加载的 SSRF 文件： ``` uv run python generate_opengd_import.py --profile chicago_light --dry-run ``` ## 工作原理 生成器加载并合并 SSRF‑Lite YAMLs，然后： - 从 `contacts[]` 构建 `Contacts.csv`（仅生成具有数字 ID 的项目）。 - 解析 policy 叠加层（如果有），并将它们与遗留的 `assignments.codeplug` 提示合并： - Policy 键驱动信道命名、TX 启用、跳过标志、TOT、功率级别、VOX、APRS 和区域成员资格。 - `preferred_contacts` 和 `default_contact` 可以引用联系人 ID、号码或名称；第一个有效条目将设置默认的 DMR 联系人/时隙。 - 从 `assignments[]` 构建 `Channels.csv`： - 如果设置了 `rf_chain_id` 且链路在支持的频段内属于 FM 或 DMR，生成器将使用 policy+遗留提示生成模拟或数字行。 - 如果设置了 `channel_plan_id`，匹配的规划信道将作为模拟信道生成（例如 NOAA），受频段过滤器限制。 - 根据每个分配的 policy/遗留 `preferred_contacts` 构建 `TG_Lists.csv`（最多 32 个，列表名称派生自分配或 `codeplug.tg_list_name`）。 - 从派生自 policy 的区域列表构建 `Zones.csv`（回退到遗留的 `assignments[].zones`），每个区域最多 80 个信道。 不支持的模式（例如 D‑STAR、C4FM）和频段外的项目将被跳过。 ## 设置与用法 (uv) 要求： - Python 3.10+ - 已安装 uv（通过 Homebrew 或官方安装程序） 安装依赖并运行（默认 profile = `default`）： ``` uv sync uv run python generate_opengd_import.py --profile default ``` 预期输出： ``` Wrote channels, contacts, TG lists, and zones to opengd77_cps_import_generated CSV validation: PASS (headers and column counts correct) ``` 将 `opengd77_cps_import_generated` 文件夹复制到您的 OpenGD77 CPS 可以读取的位置（例如，Documents 子文件夹或可移动媒体）。在 CPS 中，打开 **File → CSV → Import CSV**，浏览到该文件夹，然后选择生成的文件夹并将其加载到您的 codeplug 项目中。 ## 文档 ### Profile 文档 📚 **[浏览所有 Profile 文档 →](docs/profiles/README.md)** 为 profiles 生成全面的 Markdown 文档： ``` # 为所有 profiles 生成文档 uv run python generate_profile_docs.py # 为特定的 profile 生成文档 uv run python generate_profile_docs.py --profile chicago_amateur # 列出可用的 profiles uv run python generate_profile_docs.py --list-profiles ``` 生成的文档包括信道详细信息、区域组织、联系人列表、授权要求和源文件引用。请参阅 [profile 文档索引](docs/profiles/README.md) 以获取所有可用 profiles 的完整概述和比较。 ### Policy 文档 📋 **[浏览所有 Policy 文档 →](docs/policies/README.md)** 为 policies 生成全面的 Markdown 文档： ``` # 为所有 policies 生成文档 uv run python generate_policy_docs.py # 为特定的 policy 生成文档 uv run python generate_policy_docs.py --file gmrs_only.yml # 列出可用的 policies uv run python generate_policy_docs.py --list-files ``` 生成的文档包括分配覆盖、区域配置、扫描设置、自定义名称以及 TX/RX 行为。请参阅 [policy 文档索引](docs/policies/README.md) 以获取所有 policy 配置和使用模式的完整概述。 ### SSRF 数据文档 📡 **[浏览所有 SSRF 文档 →](docs/ssrf/README.md)** 为 SSRF 文件生成全面的 Markdown 文档： ``` # 为所有 SSRF 文件生成文档 uv run python generate_ssrf_docs.py # 为特定的 SSRF 文件生成文档 uv run python generate_ssrf_docs.py --file ssrf/plans/US/gmrs/gmrs_channels.yml # 列出可用的 SSRF 文件 uv run python generate_ssrf_docs.py --list-files ``` 生成的文档提供了 RF 系统、信道规划、分配和地理覆盖范围的详细视图。每个 SSRF 文件都有其独立的文档页面，包含频率详细信息、服务信息和组织数据。请参阅 [SSRF 文档索引](docs/ssrf/README.md) 以获取完整概述和可浏览的文件目录。 ### 自动文档更新 🔄 **文档会自动与您的更改保持同步！** 本项目包含多种自动化选项，以保持文档最新： #### 本地开发 ``` # 一次性更新所有文档 ./update-docs.sh # 或者为了方便使用 Makefile make docs # Generate all documentation make docs-profiles # Generate profile docs only make docs-policies # Generate policy docs only make docs-ssrf # Generate SSRF docs only make status # Show project status ``` #### Git Hooks（自动） 当您提交更改时，文档会自动重新生成： - **Pre-commit hook**：当 profiles、policies 或 SSRF 文件发生更改时更新文档 - **选择性更新**：仅重新生成受影响的文档类型 - **自动暂存**：更新后的文档会自动添加到您的提交中 #### GitHub Actions (CI/CD) - **自动更新**：文档在推送到 main/develop 分支时重新生成 - **Pull request 验证**：确保 PR 中的文档是最新的 - **一致性检查**：验证所有文件都有相应的文档 #### 开发命令 ``` # 带有文档自动化的项目设置 make dev-setup # 验证文档是否为最新 make validate-docs # 查看项目状态和文档数量 make status # 列出所有可用的 targets make help ``` 该自动化确保文档永远不会与您的数据文件不同步，随着项目的演进，能够轻松维护全面、准确的文档。 ## 数据说明与约定 - 这里使用的 SSRF‑Lite 实体：`organizations`、`locations`、`stations`、`antennas`、`rf_chains`、`contacts`、`channel_plans`、`assignments`。这些仍然是仅供参考的事实。 - Policies（或遗留的 `assignments.codeplug`）提供渲染指令：信道名称、区域成员资格、跳过标志、TOT、功率、VOX 和首选联系人。除非通过 `--tx-service` 或 `--tx-all-services` 将其他服务列入白名单，否则发射启用默认仅限 Amateur。 - 对于 DMR，`mode.color_code` 设置色码；默认时隙派生自 policy/遗留的首选联系人（回退到全局默认值）。 - 如果可用，纬度/经度取自信道的 station → location 链接。 - DCS 码被规范化为数字；如果需要，我们可以保留前导（例如 073）。 ## 限制 - 仅生成 136–174 & 400–480 MHz 范围内的 FM 和 DMR。 - 其他数字模式（D‑STAR、C4FM）不会导出到 OpenGD77 CSVs。 - TG 列表根据每个分配生成；以后可以添加项目级的管理列表。 - 其他 SSRF‑Lite 系统可以放入 `ssrf/systems/` 下相应的文件夹中，并将被默认 profile 自动包含。 ## 路线图 - **Profile 继承与按系统覆盖** *(计划中)* 未来的 profiles 将允许： - 继承/默认值（例如 `rx_only`、`all_skip`、`zone_cap`） - 位于 `profiles//overrides/` 下的按系统覆盖文件 `.overrides.yml` 使用原生 SSRF schema，通过 `name` 合并信道列表。 - `--strict` 用于未知的键或模糊的匹配。 - `--explain` 显示每个最终值的来源。 ## 安全 / 合规 - 仅在获得许可的情况下监听公共安全和商业频率；仅在获得许可/授权的情况下进行发射。 - 验证亚音频、频偏和活动；数据可能会发生变化。 ## 贡献 1. 创建分支 2. 在 `ssrf/` 中编辑或添加 SSRF‑Lite YAML（规划或系统） 3. `uv run python generate_opengd_import.py` 并查看差异 4. 根据需要更新文档/测试，并提交 PR ## 许可证 本项目根据 Apache License, Version 2.0 授权。有关详细信息，请参阅 [LICENSE](./LICENSE) 文件。 ## 致谢 感谢当地俱乐部/目录以及将 NTIA SSRF 作为参考模型。

标签：CHIRP, OpenGD77, SOC Prime, YAML, 业余无线电, 代码插件生成器, 安全库, 开发工具, 数据转换, 逆向工具