Generate NeonPlug exports from ResolvedCodeplug

[emuehlstein]

Summary

Implement codeplugger's first exporter: consume an exporter-neutral ResolvedCodeplug and produce a .neonplug file accepted by NeonPlug for the Baofeng DM-32UV.

SSRF roots + profile -> ResolvedCodeplug -> .neonplug

Profile 0.1 only carries enough radio-specific information for analog channels and zones. Keep this issue to that path and reject unsupported modes rather than inventing values.

Evidence policy

Treat the existing private DM-32 generator and codec as research material, not as a specification.

The old generator currently:

• Requires a base .neonplug file.
• Copies analog and digital channel records as templates.
• Preserves unrelated top-level state from that base.
• Contains inferred defaults and field meanings learned from exports and hardware behavior.

Its successful outputs demonstrate a working workflow, but do not prove that copied fields are required, that inferred meanings are correct, or that a codeplug can be generated safely from an empty object.

Use this evidence order when making exporter decisions:

1. Current NeonPlug source and model definitions.
2. Successful import into a pinned NeonPlug revision/version.
3. DM-32UV hardware behavior.
4. Existing private generator behavior and observed exports as hypotheses to test.

Record the source for every NeonPlug-only default. NeonPlug's DM-32 implementation itself contains TODOs and conflicting comments for some fields, so unresolved fields must not be assigned semantics by guesswork.

Verified container contract

Current NeonPlug source directly establishes that:

• A .neonplug file is a ZIP archive containing codeplug.json.
• The current format version constant is 1.0.0.
• Import defaults many absent top-level collections to empty arrays or null.

These facts should still be covered by exporter tests against a pinned NeonPlug revision. Do not assume every property represented by NeonPlug's TypeScript CodeplugData interface must be emitted until import behavior is tested.

Discovery gate: base-free generation

Before implementing the full writer, create the smallest synthetic analog channel/zone document and answer:

1. Does current NeonPlug import it without a base export?
2. Can NeonPlug write that imported data to a DM-32UV successfully?
3. Which channel fields are actually required for a safe analog write?
4. Which absent fields receive safe defaults, and where are those defaults defined?
5. Are radioSettings, radioInfo, or other device state required for this workflow?

If base-free generation works, implement explicit source-backed defaults. If it does not, define the minimum base-template contract and explain why each retained field is needed. Do not silently clone arbitrary personal or device-specific state.

Scope

The exporter should emit:

• Analog channels from ResolvedCodeplug.channels, preserving order.
• Zones from ResolvedCodeplug.zones, preserving order.
• Zone membership resolved from stable channel_references to generated channel numbers.
• RX/TX frequencies, TX prohibition, and analog tones where verified mappings exist.
• Explicit defaults or a documented minimum base-template contract for required fields absent from ResolvedCodeplug.

Power and bandwidth are not currently represented by ResolvedChannel; their policy must be explicit rather than inherited accidentally from a copied template.

Scan lists, contacts, DMR identities, digital channels, button settings, and profile 0.2+ features are out of scope.

Non-goals

• Decoding existing .neonplug files into a friendly representation.
• Byte-identical decode/encode round trips.
• Preserving unknown or sparse fields from arbitrary exports.
• A general-purpose NeonPlug editing or migration library.

Reference handling

Display names are not unique. Resolve each zone member by ResolvedChannel.reference, then translate it to the generated channel number. Never resolve membership by display name.

Missing or duplicate stable references must raise an actionable error. Positional reference rules for scan lists, contacts, RX groups, and radio IDs belong in their future feature issues, not this one.

Proposed placement

src/codeplugger/exporters/neonplug/

A minimal public API:

write_neonplug(path: Path, codeplug: ResolvedCodeplug) -> None

Profile and SSRF resolution remain exporter-unaware. Add a CLI output option after the writer contract is covered by tests.

Acceptance criteria

• A minimal synthetic analog channel/zone fixture imports into a pinned NeonPlug revision without relying on private data.
• Tests document whether generation is base-free or requires a minimal base template.
• Channel and zone ordering matches ResolvedCodeplug.
• Zone references resolve to the intended generated channel numbers.
• RX/TX frequencies, TX prohibition, and analog tones survive NeonPlug import and are confirmed in the imported model.
• Power, bandwidth, and every other NeonPlug-only field have a documented source and policy.
• Unsupported modes and invalid references fail with actionable errors.
• The archive contains codeplug.json and declares the tested format version.
• Generated content is deterministic except for any explicitly documented metadata such as an export timestamp.
• Public tests use synthetic fixtures only.
• The generated fixture is smoke-tested on DM-32UV hardware before calling the initial milestone complete.

Source material and provenance

The private muehl-ssrf-private/radios/dm32/ implementation may be consulted for experiments and candidate mappings. Port only code whose behavior is needed and independently verified for this narrower exporter.

This repository is licensed under Apache-2.0. Preserve attribution required by any imported source and do not commit real radio exports or personal/device-specific base codeplugs.

Relationship to #3

This issue produces DM-32 output. #3 defines radio constraints. Implement currently enforceable analog channel/zone constraints alongside or immediately after this exporter; defer scan-list constraints until the profile model supports scan lists.

[emuehlstein]

Base-free import experiment result

Tested against NeonPlug commit 456c4bf3d5155d966e9291570b9633df35731748 using NeonPlug's own smartImportCodeplug(), validateChannelForEncoding(), encodeChannel(), and encodeZone() paths.

Results:

• A ZIP containing only codeplug.json, version, one analog channel, and one zone imports without a base codeplug.
• Missing top-level collections become empty arrays or null through NeonPlug's importer.
• A sparse channel also imports and is reported as valid, but validateChannelForEncoding() rejects it because required fields such as bandwidth are absent. Import success is therefore not meaningful validation by itself.
• The same synthetic channel completed with NeonPlug's createDefaultChannel() passed encoding validation, encoded to a 48-byte DM-32UV channel record, and its zone encoded to a 145-byte record.

Conclusion: base-free generation is viable at the NeonPlug import and channel/zone binary-encoding boundary. Codeplugger must emit a complete channel and explicitly justify each adopted default; it must not rely on the importer to add channel defaults or copy an existing radio export.

Not yet proven: successful write to DM-32UV hardware. That remains the acceptance gate before calling base-free output safe.

[emuehlstein]

Status update:

• Analog-radio export path (CHIRP CSV) is now merged via PR Add UV-5R Mini support and CHIRP CSV export #10.
• This issue remains focused on NeonPlug export from ResolvedCodeplug for DM-32 and is still open.

Recommendation: keep this issue open and continue with the NeonPlug-specific implementation slices.

[emuehlstein]

Status update:

• Analog-radio export path (CHIRP CSV) is now merged via PR Add UV-5R Mini support and CHIRP CSV export #10.
• This issue remains focused on NeonPlug export from ResolvedCodeplug for DM-32 and is still open.

Recommendation: keep this issue open and continue with the NeonPlug-specific implementation slices.

[emuehlstein]

Discovery gate: base-free generation — Q1 is green

Ran the gate this issue defines, against our fork (emuehlstein/NeonPlug, main @ 2b862c1, merged through upstream 8ae18477). Source-level answer, no hardware needed.

The "requires a base .neonplug" constraint is an artifact of the old private generator, not of the format.

Q1 — does NeonPlug import a synthetic doc with no base export?

Yes. src/services/codeplugExport.ts → importCodeplug() is readZip → lookup → jsonSafeToCodeplug, and it performs exactly one validation:

const bytes = files.get(CODEPLUG_JSON_FILENAME);
if (!bytes) {
  throw new Error(`Invalid codeplug file: missing ${CODEPLUG_JSON_FILENAME}`);
}

No schema check, no version gate, no required-collection check. jsonSafeToCodeplug then defaults every collection: channels, zones, scanLists, contacts, digitalEmergencies, analogEmergencies, messages, radioIds, quickContacts, rxGroups, encryptionKeys all ?? []; radioSettings, radioInfo, digitalEmergencyConfig all ?? null. version falls back to CODEPLUG_VERSION ('1.0.0') when absent, and exportDate to new Date().toISOString().

So the minimum viable import is a zip containing codeplug.json with {"channels": [...], "zones": [...]}. This confirms the verified container contract in the issue body and clears the discovery gate for the analog channel/zone path.

Q2/Q3 — can it then write to a DM-32UV, and which fields are actually required?

Not answerable from source. This is where the gate should stop.

The DM-32 write path guards on radioInfo at ~8 sites (src/radios/dm32uv/protocol.ts:517,1032,2396,2521,2761,2949, src/radios/dm32uv/memory.ts:158,168), but those are populated from the live connection at connect time, not from the imported file — so they say nothing about which imported fields a safe write requires. Import-safe is not write-safe. Settling Q2/Q3 needs a radio on the bench, and per this repo's own rules a write path to hardware needs a human.

Two things that make the exporter harder than the issue implies

1. Channel has ~40 fields, and several are explicitly unknown. unknown1A_6_4, unknown1A_3, unknown1C_1_0, unknown1D_3_0, unknown25_7_6 — named unknown in the model, with comments like "values ≥4 reset to 0". An exporter must emit something for each. The evidence policy in this issue (record the source for every NeonPlug-only default; do not assign semantics by guesswork) is the right rule, and it means each of these needs either a cited source or an explicit "copied from observed export, meaning unknown" annotation. That is a real chunk of the work.

2. 🔴 Channel.scanListId carries the stale mask. src/models/Channel.ts:

scanListId: number;         // Bits 5-2: 0-15

That is the decode bug corrected in upstream NeonPlug PR #156 — the real field is 0x19 & 0x3F (low 6 bits). The old mask cannot address past list 15, and a real radio with 7 lists stores 0x42/0x43. An exporter written against that comment inherits the bug.

Same correction landed for the DM-32 capability data in #16 and for the public reference in Chicago-Offline/dm32-info#2. Note that our fork's upstream-scanlist2 branch has the fix but it is not on main, so anything built against main today sees the stale comment.

Related and worth pinning down before scan lists land in profile 0.2: max_channels_per_scan_list is 15, and the reason CPS shows 16 is the phantom +0x0F slot (hardware-verified 2026-08-07 on a DP570UV), not a bonus member. A channel written into +0x0F is neither scanned nor displayed.

Suggested shape

• Write the exporter against a pinned NeonPlug revision, with tests asserting round-trip through jsonSafeToCodeplug, since that is the actual import contract rather than the full CodeplugData TypeScript surface.
• Emit only the analog channel/zone path that profile 0.1 supports; reject unsupported modes rather than inventing values, as the issue already specifies.
• Keep the radio write behind an explicit human-verified step until Q2/Q3 are answered on hardware.
• Fix or avoid scanListId rather than reading its comment.