Add TURF file upload so a radio can be re-TURFed without SmartSDR for Windows

Request preparation

• I used an AI assistant to help structure this request
• I checked for existing issues covering the same feature

What would you like?

Add TURF file upload so a radio can be re-TURFed without SmartSDR for Windows

Summary

AetherSDR can already push firmware to a radio (Settings → Radio Setup → Radio → Firmware Update). The remaining reason an operator still has to keep a Windows box around is the TURF file — the region / transmit-range file that FlexRadio or a national distributor issues per radio.

This asks for a TURF upload control alongside the existing Firmware Update section, using the same file upload transport that firmware already rides.

Why this matters

• It closes the last standalone gap. Firmware is done. TURF is the other thing that only SmartSDR for Windows can do today, and it's a much smaller job than firmware was.
• TURF changes are not one-off. A TURF loaded for MARS/SHARES or for travel has historically not survived a power cycle — operators have reported having to reload it every time the radio restarts. If that behaviour still holds on 4.x, a Linux/macOS operator currently needs Windows repeatedly, not once.
• Travelling and non-US operators need it routinely. A US radio taken to the UK, or an EU radio needing the EU-region file for 60 m, gets re-TURFed on arrival and again on return.
• There's precedent in a third-party client. SmartSDR for Mac exposes an "Install TURF file" button, so this is an established thing for a non-FlexRadio client to do, not novel territory.

What this is not

Worth stating up front, because "TURF" and "unlock" get conflated in the community:

• No parsing, rewriting, or generation of TURF files.
• No signature or validation work of any kind.
• TURF files carry the radio's serial number and won't apply to a different radio; the radio validates them, not the client.

AetherSDR would be a courier moving an already-issued file from disk to the radio. A file the radio would reject through SmartSDR gets rejected through Aether identically. Operators still obtain TURF files the normal way — FlexRadio sales/HelpDesk for MARS/SHARES, or their national distributor.

Protocol

turf is one of the tokens on the existing file upload command family. From the FlexLib 4.2.18 command reference:

C<seq>|file filename <filename>
C<seq>|file upload <length> turf

Same family as update (firmware), db_import, memories_csv_file, new_waveform, db_meta_subset.

The firmware trace captured in #5572 on a FLEX-6400 / v4.2.20 shows how the transport actually works — the bytes do not go over the command socket:

TX: C329 file filename FLEX-6x00_v4.2.20.ssdr
TX: C330 file upload 386282416 update
RX: R329|0|                      <- filename ACK
RX: R330|0|42607                 <- data field is a TCP port
RX: S0|file server active        <- radio bound its listener
RX: S0|file client detected      <- radio saw the second socket connect
RX: S121B5D93|file update transfer=0.00
    ... climbing ...
RX: S121B5D93|file update transfer=1.00

So: announce the name, announce length + kind, read the port out of the response, open a second TCP connection to the radio on that port, stream the raw bytes there, and track progress from the transfer= status lines on the command socket.

If turf follows the same pattern, the only difference from the firmware path is the token and the payload size (kilobytes rather than ~400 MB).

Proposed implementation

The cheapest version of this is a refactor rather than new code:

1. Lift the kind token out of the existing firmware transfer as a parameter, so the same class serves update and turf (and is there for memories_csv_file / new_waveform later).
2. Add a TURF File group to Settings → Radio Setup → Radio, under Firmware Update:
   • Current region display, if the radio reports it
   • Browse .turf… file picker, filtered to *.turf
   • Upload button with progress and the radio's status text
3. Sanity checks before upload — non-empty, and small enough to plausibly be a TURF file rather than a misclicked firmware image. Advisory only; the radio is authoritative.
4. Surface the radio's rejection reason verbatim on failure. The most common real-world case will be a TURF cut for a different serial, and the operator needs to see that rather than a generic "upload failed".

Risk is much lower than the firmware path: no reboot, no multi-hundred-MB transfer, and a rejected file leaves the radio exactly as it was.

Needs verification before implementing

I have the firmware trace but not a TURF trace, so these are open:

• Does file upload <len> turf return a port in the response data field the way update does, or does the small payload go some other way?
• Is the preceding file filename command required for turf, or only for update?
• Are progress statuses emitted as file turf transfer=…, or is the transfer too small to generate any?
• Is a follow-up command needed to make the radio apply the region, or does it take effect on receipt?
• Does the radio emit a region-change status afterwards that the UI could read back?

A Wireshark capture of SmartSDR for Windows installing a real TURF file would settle all five. If someone with a MARS/SHARES or distributor-issued TURF file can grab one, that unblocks the work.

Related

• #5572 — firmware upload reaches 100% but the radio never activates. Same transport; whatever that turns out to be probably affects this too.
• Wiki: Firmware Update — documents the existing file upload … update flow.

Note on .lic files

Raising this here so nobody spends time on it: there is no license-file upload in the protocol. The entire License command surface in FlexLib 4.2.18 is one verb, license refresh, which asks the radio to re-read its entitlement state. Licences bind to the radio's unique identifier, install into the radio, and FlexRadio holds a cloud copy — entitlements move radio↔FlexRadio, never client→radio. If Aether ever wants a "my licence didn't show up after purchase" button, license refresh is the whole feature.

Happy to test on request, and to help write up a capture if someone can supply a TURF file for their own radio.

turf-upload-feature-request.md

Start by reading the existing Firmware Update flow in Settings → Radio Setup → Radio and the Wiki's Firmware Update documentation, then review the transport trace in #5572. Verify the TURF protocol with a SmartSDR capture before implementing the shared upload path. Done means a .turf picker and upload control report progress and verbatim radio rejection status without requiring SmartSDR for Windows.