Ferrite

Developers

The .ferrite codeplug format

The .ferrite files Ferrite Console saves: a radio's channels and settings in one file.

A .ferrite file is a Ferrite radio's codeplug as Ferrite Console saves it: the channels and zones, the range presets with their skip lists, Radio Settings, APRS settings, APRS contacts, the quick messages, the waypoints and the DTMF memories, in one file.

  • Written and read by Ferrite Console (src/lib/codeplug.ts, src/lib/zip.ts).
  • Format version 2 (November 1, 2026: protocol 3's channel record, decision 333). Version 1 files still open.
  • The example at the end is a test fixture (ferrite-console/core/tests/fixtures/codeplug/). Console's tests check that each part is exactly what Console writes, and that the zipped file reads back unchanged.

The file

  • A standard ZIP archive (PKZIP). Any unzip tool opens it.
  • Each entry is stored (method 0) or deflated (method 8). Nothing else: no ZIP64, no encryption, no folders.
  • Names are UTF-8. Every entry's CRC-32 is checked on reading.
  • MIME type application/x-ferrite-codeplug. On macOS the type is dev.ferritefw.console.codeplug.
  • File name when saved: <callsign>-<yyyymmdd>-<hhmm>.ferrite, in local time (e.g. VA7IF-20261030-1412.ferrite). radio when there is no callsign.
Entry What it holds Required
manifest.json What the file is, who saved it, which parts it has Yes
channels.json Channels and zones No
presets.json Range presets (MENU 0 1 4) No
settings.json Radio Settings (MENU 0) No
aprs.json APRS settings (MENU 0 5) No
contacts.json APRS contacts (the address book) No
quick.json The quick messages (TEXT-7) No
waypoints.json The waypoints (GPS-10) No
dtmf.json The DTMF memories and their names (DTMF-12) No
  • A part is there only when Console had it: a file saved before Radio Settings was read has no settings.json.
  • Every part listed in the manifest must be in the zip.
  • Readers ignore any other entry.

manifest.json

Field Type Meaning
format string Always "ferrite-codeplug".
version integer, 1 or more The format version. This document is version 2 (version 1 below, under Older files).
created string, ISO 8601 UTC When the file was saved, e.g. "2026-10-30T21:12:00.000Z".
console string The Console version that saved it, e.g. "0.1.0".
radio object What the radio said about itself. Each field is left out when unknown.
radio.callsign string The radio's callsign.
radio.firmware string Ferrite's version, as INFO gives it.
radio.build string The build's name, as HELLO gives it (e.g. tx).
radio_fingerprint string, 8 hex digits The radio's fingerprint, below. Left out when the radio's ID isn't known.
parts array of strings The parts in the file, in this order: channels, presets, settings, aprs, contacts, quick, waypoints, dtmf.

The radio's fingerprint, not its ID

  • A codeplug never holds the radio's unique ID, in the manifest or in any part.
  • Codeplugs get shared (clubs, forums), and the ID is a permanent hardware serial (SELF-8).
  • radio_fingerprint stands for it: the first 8 hex digits (lowercase) of SHA-256 over the ID's 12 bytes as INFO gives them (LINK-35.1), not over the text About shows.
  • It is enough to tell "the same radio" without carrying the serial. Example: the bytes 10 32 54 76 98 ba dc fe 01 23 45 67 give 7f755785.
  • Stored for later use (telling which radio a file came from). Nothing reads it yet.

The parts

Channels, settings and APRS are the JSON Console has always written as single-part backups; the other parts take the same shape. All of them start with the same fields:

Field Type Meaning
format string The part: ferrite-console-channels, -presets, -settings, -aprs, -contacts, -quick, -waypoints or -dtmf.
version integer The part's own version: 2 for channels.json, 1 for the others. A newer one is refused for that part alone.
saved string, ISO 8601 UTC When the part was saved.
radio object of strings What Console knew: connection (how it was connected), firmware, callsign. Any may be missing. The older single-part files also have uid; a codeplug never does.

The record parts store the radio's own record bytes as hex: lowercase, two digits a byte. They are the same records the link protocol carries (manual Appendix G). The readable fields beside them are for people; Console loads the records.

All numbers in the records are little-endian.

channels.json

Field Type Meaning
zones array One entry per zone, numbered 1 up with no gaps (0 to 512 zones).
zones[].number integer, 1-512 The zone's number. Sets the order.
zones[].name string For reading; the record's name is the one loaded.
zones[].record hex string, 26 bytes The zone record, below.
channels array One entry per channel in use (0 to 4000).
channels[].number integer, 1-4000 For reading; the record holds the number.
channels[].name string For reading.
channels[].record hex string, 41 bytes (40 accepted) The channel record, below.
channels[].pos array of 2 numbers, optional The channel's position (CHAN-2): [latitude, longitude] in degrees, north and east positive, up to seven decimals (the radio keeps 1e-7 degree). Left out when the channel has none.

Zone record (26 bytes):

Bytes Type Field Values
0-15 16 bytes Name 1-16 printable ASCII characters, 0-padded
16 u8 Scan all 0 no, 1 in the "scan all" set
17 u8 Shown 1 shown in ◀▶ on home (CHAN-11)
18 u8 By distance 0 or 1
19 u8 Resume 0 the radio's rule, 1-10 seconds, 11 carrier drop, 12 stop on hit (SCAN-5)
20 u8 Dwell 1-254 seconds, 255 the radio's
21 u8 Reserved 0
22-23 u16 Priority channel 1 Channel number minus 1 (0-3999); 0xFFFF none
24-25 u16 Priority channel 2 As priority 1

Channel record (41 bytes; link protocol 3):

Bytes Type Field Values
0-1 u16 Number Channel number minus 1 (0-3999)
2-3 u16 Zone Zone number minus 1 (0-511); 0xFFFF no zone
4-7 u32 RX frequency 10 Hz units (146.520 MHz is 14652000)
8-23 16 bytes Name Printable ASCII, 0-padded; outside the name set written as - (CHAN-31)
24 u8 Mode 0 FM, 1 NFM, 2 AM
25 u8 Narrow Follows the mode: 1 for NFM, else 0
26-27 u16 RX tone 0 none; CTCSS in 0.1 Hz (1000 is 100.0 Hz); DCS: bit 15 set, bit 14 inverted, the code's octal digits as a number (D023 is 0o23)
28-29 u16 TX tone As the RX tone
30-33 i32 Offset 10 Hz units, signed; 0 simplex. With split: the TX frequency itself
34 u8 Power 0 low, 1 mid, 2 high
35 u8 Step Index: 10 Hz, 50 Hz, 100 Hz, 500 Hz, 1 kHz, 2.5, 5, 6.25, 8.33, 10, 12.5, 25, 50, 100 kHz (0-13)
36 u8 Squelch 0-9 a level, 10 Global (the slot's own, SQL-6)
37 u8 Busy lockout 0 off, 1 on (TX-21)
38 u8 Reverse and split Bit 0 reverse, bit 1 split
39 u8 Flags 1 skip, 2 APRS, 4 RX only, 0x40 hidden, 0x80 priority; other bits kept as read
40 u8 End tone and tail Bits 0-2 end tone (0 Global, 1 Off, 2 Beep, 3 Two-tone up, 4 Two-tone down, 5 Chirp, 6 Quindar); bits 3-4 tail elimination (0 Global, 1 Off, 2 On). Left off (40 bytes): Global

The radio checks every record as its own editor would (band, tones, name). Console runs the same checks before it writes.

A zone holds at most 256 channels (CHAN-35). A file may hold more (one from before November 1, 2026: the radio had no limit then); opening it splits each long zone as the radio's own update does: the first 256 by number stay, the rest go 256 at a time to new zones named " 2", " 3" and so on (a copy of the zone's settings, cut to 16 characters). The notice says so, and Undo puts it back.

A position isn't part of the channel record: the link reads and writes it on its own (LINK-53), so it sits beside the record. Console writes it only to a radio whose HELLO says it can store positions (caps 64); an older radio keeps the channel without it.

pos came in October 30, 2026 without a version bump: it is an optional field, and an older Console ignores it (it loads the channels without their positions and never sends positions). A file without pos loads as before.

presets.json

Field Type Meaning
presets array, at most 16 The range presets in the radio's order (MENU 0 1 4).
presets[].number integer, 1-16 For reading: the order is the array's.
presets[].name, low, high, step, mode, resume strings For reading: the name, the range in MHz, and the step, mode and resume as the radio words them.
presets[].record hex string, 24 bytes The preset record, below.
presets[].skips array of strings, at most 48 The skipped frequencies in MHz ("144.39000"), in the radio's order (SCAN-10, LINK-58). Left out when there are none.

Preset record (24 bytes; LINK-21's what 4, as the link reads and writes it):

Bytes Type Field Values
0-11 12 bytes Name 0-12 printable ASCII characters, 0-padded
12-15 u32 Start 10 Hz units, 18 to 1300 MHz
16-19 u32 End 10 Hz units, above the start, up to 1300 MHz; not across 18 or 64 MHz (SCAN-14)
20 u8 Step Index into the radio's steps: 0 10 Hz ... 10 12.5 kHz, 11 25 kHz, 12 50 kHz, 13 100 kHz
21 u8 Mode 0 FM, 1 NFM, 2 AM
22 u8 Narrow 1 for NFM (VFO-20: the mode carries the bandwidth)
23 u8 Resume 0 Global (MENU 0 1 2's rule), 1-10 s, 11 carrier drop, 12 stop on hit (SCAN-24)

A preset's skipped frequencies (SCAN-10, up to 48) aren't in its record: the radio keeps them beside it and the link reads and writes them as a list of their own (LINK-58, what 11). In the file they are skips. Each lies within its preset's range, once. Opening a file puts each preset in the place of the radio's preset with the same number; Write sends the skip lists after the presets, to a radio whose firmware takes them (HELLO's second capability byte). An older radio keeps its own, and the file's stay in Console.

presets.json came in October 30, 2026 without a version bump: it is a new part, and an older Console skips it. skips came the same day, also without one: an optional field, which an older Console ignores (it loads the presets without their lists).

settings.json

The PIN and the PIN lock never go in a codeplug; the radio keeps its own.

  • Left out entirely: MENU 0 9 3 (PIN lock, channel-only mode, Change PIN) is in neither extras nor settings.
  • In record, the PIN lock's fields (its mode, the PIN, its length, the wrong-PIN counters, channel-only mode) are cleared to their defaults. No other key names them.
  • On Open, and again just before Write, Console puts the radio's own PIN lock back into the record. The radio also keeps its PIN lock on every settings write (LINK-7).
Field Type Meaning
record hex string The settings record: ferrite-app's Settings fields in order (persist.rs), then the power-on message. Its length is the firmware's (INFO's settings length; 414 bytes today, always under 512). A record of another length is shown but never written (LINK-21). The PIN lock's fields cleared (above).
extras object, string to string The settings the settings record doesn't carry, Watch, Battery Save and the message sound (since decision 347, from the radio record, LINK-66): the menu number ("0 7 7 1") to the value as the menu shows it ("Level 1"). May be empty.
settings object, string to string Every setting as the radio's menu shows it, "0 1 2 Resume": "5 s". For reading only; ignored when opened.

aprs.json

Field Type Meaning
record hex string, 72 bytes The APRS record, below.
extras object, string to string Empty since decision 347 (every MENU 0 5 value is in the record); a file from before it may list some; they are ignored (the record holds them).
settings object, string to string MENU 0 5 as the menu shows it. For reading only.

APRS record (72 bytes; LINK-43, Appendix G; 25 or 24 before decision 347):

Bytes Type Field Values
0-1 u16 Frequency 5 kHz units; 0 the region's
2 u8 Beacon 0 off, 1 manual, 2-9 every 1, 2, 5, 10, 15, 20, 30, 60 min, 10-16 every 0.1, 0.2, 0.5, 1, 2, 5, 10 km, 17 smart; bit 7 paused
3 u8 Power 0 low, 1 mid, 2 high
4 u8 Path 0 none, 1 WIDE1-1, 2 WIDE1-1,WIDE2-1, 3 custom
5 u8 Digipeater Bit 0 on, bit 1 my callsign too, bits 4-6 the wait (0-5 s)
6 u8 Beacon after voice 0 or 1
7 u8 SSID 0-15
8-23 16 bytes Custom path ASCII, 0-padded
24 u8 FX.25 on transmit 0 off, 16, 32, 64 check bytes (APRS-45). Left off (24 bytes): the radio's setting is kept
25 u8 Message sound 0 7 5 5, an index into the chimes (0 off; APRS-6.1)
26 u8 Symbol An index into the symbols (APRS-47)
27 u8 TX delay 10-100, in 10 ms (APRS-48)
28 u8 TX level 0 low, 1 mid, 2 high (APRS-49)
29-68 40 bytes Comment Printable ASCII, 0-padded (APRS-50)
69 u8 Ambiguity 0 exact to 4 digits dropped (APRS-51)
70 u8 Mic-E 0 off, 1-7 the status (APRS-52)
71 u8 Telemetry 0 or 1 (APRS-54)

contacts.json

Field Type Meaning
contacts array, at most 1016 The address book, in callsign order (APRS-37).
contacts[].call string 3-9 characters: A-Z, 0-9, - (VE7ABC-9).
contacts[].name string Up to 12 characters: letters, digits, space and - . / _ # + & ( ) ' !. Others become -.

Contacts aren't one record: Console writes them by callsign. Opening a file adds or renames those contacts on Write; it deletes none.

quick.json

Field Type Meaning
messages array of 9 The quick messages compose offers, in order (TEXT-7, LINK-54).
messages[].own boolean The owner's own text; false is the factory text.
messages[].text string The text the radio uses: the owner's, or (for reading) the factory one. Up to 67 printable characters, none of \|, ~, {.

Opening a file sets each message as it says: the owner's text, or back to the factory text.

waypoints.json

Field Type Meaning
waypoints array, at most 2032 The waypoints, newest first, as the radio lists them (GPS-10, LINK-55).
waypoints[].name string 1-16 printable characters.
waypoints[].lat, lon numbers Degrees, north and east positive, to 1e-7 (the radio's unit).
waypoints[].source string marked (on the radio), aprs (from a station), link (from Console) or grid (a grid square).

Opening a file makes the radio's list this one on Write: the waypoints it already has are kept, the others deleted, the new ones added.

dtmf.json

Field Type Meaning
memories array, at most 16 The DTMF memories that are set (DTMF-12, LINK-56).
memories[].number integer, 1-16 The memory's number; each once.
memories[].symbols string 1-16 of 0-9, A-D, *, #.
memories[].name string Up to 10 printable characters; may be empty.

Opening a file makes the radio's memories these on Write: the numbers it leaves out are cleared.

quick.json, waypoints.json and dtmf.json came in October 30, 2026 without a version bump: new parts, which an older Console skips.

Opening a file

  • Each part goes into its page as unwritten changes. Settings keep the radio's own PIN lock. Write to radio, page by page, puts it on the radio, after a backup and a diff.
  • One notice lists what was loaded: "Loaded channels (3) and zones (2), range presets (2), APRS settings, contacts (2), quick messages (1 your own), waypoints (2), DTMF memories (2) from VA7IF-20261030-1412.ferrite".
  • A part that doesn't load (a newer part version, a bad record) is named in the notice. The others still load.
  • Refused with a message, nothing loaded:
  • not a zip, or a damaged one (a CRC mismatch, cut short);
  • a zip without manifest.json, or with another format: "not a Ferrite codeplug";
  • a newer version: "a newer codeplug (format version 3) than this Console reads (version 2): update Ferrite Console";
  • a part listed but missing: "damaged codeplug".

Older files: -backup.json

Before October 30, 2026, Console saved each page's part on its own. Open… still takes them:

  • ferrite-<who>-<date>-backup.json, -table.json: channels and zones.
  • …-settings-backup.json, -settings-edited.json: Radio Settings.
  • …-aprs-backup.json, -aprs-edited.json: APRS settings.
  • …-presets.json: range presets (saved beside the channels' backup before each write, from October 30, 2026).
  • …-quick-backup.json, -waypoints-backup.json, -dtmf-backup.json: the lists, saved before each of their writes.

Each is exactly one part's JSON, as above. Console tells them apart by format, not by name, and loads just that part. The backup Console saves before each write is still one of these files.

Older files: version 1

Format version 1 (October 2026, link protocol 2) is the same zip and the same parts, except channels.json (part version 1): its channel records are 40 bytes (39 accepted), the zone one byte at 2 (zone number minus 1, 0-253; 255 no zone), everything after it one byte earlier. Console reads them by widening the zone to two bytes (255 to 0xFFFF) and writes version 2. The limits were then 1,000 channels, 254 zones, 128 contacts and 256 waypoints.

Changing the format

  • version starts at 1. Console reads any version up to its own, and refuses a newer one.
  • Bump version when an older Console would misread a newer file:
  • a part or manifest field renamed, removed or changed in meaning;
  • a change to the zip itself (a new compression method, folders).
  • Don't bump it for what an older Console can safely ignore:
  • a new part (older readers skip it);
  • a new optional field in the manifest or a part.
  • A part's own layout changes with its own version. An older Console then refuses that part alone.
  • A record layout follows the firmware. A record of the wrong length is refused or shown read-only, never written.
  • Writers always write the newest version they know.
  • Change this document with the code and the example fixture. Console's tests fail until all three agree (the doc's check runs when the docs checkout is beside Console's).

Example

VA7IF-20261030-1412.ferrite, saved before Radio Settings was read (no settings.json). Eight entries. To write the fixtures again from Console's code: FERRITE_WRITE_CODEPLUG_EXAMPLE=1 cargo test -p ferrite-console-core codeplug_example.

manifest.json:

{
  "format": "ferrite-codeplug",
  "version": 2,
  "created": "2026-10-30T21:12:00.000Z",
  "console": "0.1.0",
  "radio": {
    "callsign": "VA7IF",
    "firmware": "0.8.2",
    "build": "tx"
  },
  "radio_fingerprint": "7f755785",
  "parts": [
    "channels",
    "presets",
    "aprs",
    "contacts",
    "quick",
    "waypoints",
    "dtmf"
  ]
}

channels.json: zones Local (scan all) and Repeaters (resume on carrier drop, priority channel 10); channel 1 (146.520 NFM, zone Local), channel 10 (146.940, -0.6 MHz, TX tone 100.0, mid power, zone Repeaters, at 49.35 N 123.07 W), channel 20 (446.000, no zone, skipped):

{
  "format": "ferrite-console-channels",
  "version": 2,
  "saved": "2026-10-30T21:12:00.000Z",
  "radio": {
    "callsign": "VA7IF",
    "connection": "Cable",
    "firmware": "0.8.2"
  },
  "zones": [
    {
      "number": 1,
      "name": "Local",
      "record": "4c6f63616c000000000000000000000001010000ff00ffffffff"
    },
    {
      "number": 2,
      "name": "Repeaters",
      "record": "526570656174657273000000000000000001000bff000900ffff"
    }
  ],
  "channels": [
    {
      "number": 1,
      "name": "Calling 2 m",
      "record": "000000006092df0043616c6c696e672032206d000000000001010000000000000000000a0a00000000"
    },
    {
      "number": 10,
      "name": "North hill",
      "record": "090001007036e0004e6f7274682068696c6c00000000000001010000e803a015ffff010a0a00000000",
      "pos": [
        49.35,
        -123.07
      ]
    },
    {
      "number": 20,
      "name": "Calling 70 cm",
      "record": "1300ffffc08aa80243616c6c696e6720373020636d00000001010000000000000000000a0a00000100"
    }
  ]
}

presets.json: 2 m (144-148 MHz, 12.5 kHz steps, NFM, skipping 144.39 and 145.8 MHz) and the airband (118-137 MHz, 25 kHz steps, AM, resuming after 3 s):

{
  "format": "ferrite-console-presets",
  "version": 1,
  "saved": "2026-10-30T21:12:00.000Z",
  "radio": {
    "callsign": "VA7IF",
    "connection": "Cable",
    "firmware": "0.8.2"
  },
  "presets": [
    {
      "number": 1,
      "name": "2 m",
      "low": "144.00000",
      "high": "148.00000",
      "step": "12.5 kHz",
      "mode": "NFM",
      "resume": "Global",
      "record": "32206d00000000000000000000badb0080d4e1000a010100",
      "skips": [
        "144.39000",
        "145.80000"
      ]
    },
    {
      "number": 2,
      "name": "Airband",
      "low": "118.00000",
      "high": "137.00000",
      "step": "25 kHz",
      "mode": "AM",
      "resume": "After 3 s",
      "record": "41697262616e640000000000c00db400a00bd1000b020003"
    }
  ]
}

aprs.json: the radio's defaults:

{
  "format": "ferrite-console-aprs",
  "version": 1,
  "saved": "2026-10-30T21:12:00.000Z",
  "radio": {
    "callsign": "VA7IF",
    "connection": "Cable",
    "firmware": "0.8.2"
  },
  "record": "0000000002000007000000000000000000000000000000001003001e0100000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "extras": {},
  "settings": {
    "0 5 4 Frequency": "144.390",
    "0 5 5 1 SSID": "7 Handheld",
    "0 5 5 2 Symbol": "Person",
    "0 5 5 3 Comment": "Empty",
    "0 5 5 6 Ambiguity": "Exact",
    "0 5 5 7 Mic-E": "Off",
    "0 5 6 1 Mode": "Off",
    "0 5 6 2 After voice TX": "Off",
    "0 5 6 3 Power": "Low",
    "0 5 6 4 Telemetry": "Off",
    "0 5 7 1 Digipeat": "Off",
    "0 5 7 2 Aliases": "WIDE1-1",
    "0 5 7 3 Wait": "0 s",
    "0 5 9 1 Path": "WIDE1-1,WIDE2-1",
    "0 5 9 2 Custom path": "None",
    "0 5 9 3 TX delay": "300 ms",
    "0 5 9 4 TX level": "Mid",
    "0 5 9 5 FX.25 on TX": "16 bytes"
  }
}

contacts.json:

{
  "format": "ferrite-console-contacts",
  "version": 1,
  "saved": "2026-10-30T21:12:00.000Z",
  "radio": {
    "callsign": "VA7IF",
    "connection": "Cable",
    "firmware": "0.8.2"
  },
  "contacts": [
    {
      "call": "VA7XYZ-9",
      "name": "Sam mobile"
    },
    {
      "call": "VE7ABC",
      "name": "Club station"
    }
  ]
}

quick.json: the factory texts, the third the owner's own:

{
  "format": "ferrite-console-quick",
  "version": 1,
  "saved": "2026-10-30T21:12:00.000Z",
  "radio": {
    "callsign": "VA7IF",
    "connection": "Cable",
    "firmware": "0.8.2"
  },
  "messages": [
    {
      "own": false,
      "text": "73"
    },
    {
      "own": false,
      "text": "QSL, thanks"
    },
    {
      "own": true,
      "text": "At the club tonight, 146.94"
    },
    {
      "own": false,
      "text": "Call me"
    },
    {
      "own": false,
      "text": "Where are you?"
    },
    {
      "own": false,
      "text": "QRT for now"
    },
    {
      "own": false,
      "text": "Yes"
    },
    {
      "own": false,
      "text": "No"
    },
    {
      "own": false,
      "text": "Are you on the repeater?"
    }
  ]
}

waypoints.json: two, the newest first:

{
  "format": "ferrite-console-waypoints",
  "version": 1,
  "saved": "2026-10-30T21:12:00.000Z",
  "radio": {
    "callsign": "VA7IF",
    "connection": "Cable",
    "firmware": "0.8.2"
  },
  "waypoints": [
    {
      "name": "Grouse summit",
      "lat": 49.3802,
      "lon": -123.0811,
      "source": "marked"
    },
    {
      "name": "Club shack",
      "lat": 49.2827,
      "lon": -123.1207,
      "source": "link"
    }
  ]
}

dtmf.json: memories 1 and 2, a repeater link's on and off:

{
  "format": "ferrite-console-dtmf",
  "version": 1,
  "saved": "2026-10-30T21:12:00.000Z",
  "radio": {
    "callsign": "VA7IF",
    "connection": "Cable",
    "firmware": "0.8.2"
  },
  "memories": [
    {
      "number": 1,
      "symbols": "*79#",
      "name": "Link on"
    },
    {
      "number": 2,
      "symbols": "#79#",
      "name": "Link off"
    }
  ]
}

Made from docs/dev/codeplug-format.md by docs/tools/mkdev.py.