SPOT Tools XLSX File Specification

This document defines the Excel workbook format used by SPOT Tools for import/export of radio configuration data.

Scope

• Format name: SPOT Workbook v1
• File type: .xlsx
• Primary goal: interchange channel + list + radio settings with spreadsheet tools while preserving telemetry constraints

Workbook Structure

Required sheet

• Channels

Optional sheets

• ScanLists
• Radio
• Meta

Unknown sheets are ignored during import.

Sheet: Channels (required)

One row per memory channel.

Required columns

• active
  • Boolean-like (TRUE/FALSE, true/false, 1/0, yes/no, on/off)
• name
  • String, trimmed, max 10 characters
• rx_mhz
  • Numeric MHz value, example: 150.125
• step_khz
  • Numeric step value in kHz; must map to an allowed telemetry step
• scanlist_ids
  • Delimited stable list IDs (ID001..ID016), example: ID001|ID003|ID005

Optional columns

• notes
  • Ignored by importer
• tag
  • Ignored by importer

Sample rows

A small example of how the Channels sheet might look in practice:

Import behavior

• Channel number is derived from sheet row position (row 2 => channel 0, row 3 => channel 1, ...).
• Blank rows preserve existing/default channel values at that row index.
• Empty scanlist_ids means no list membership.
• Unknown/invalid/duplicate list IDs cause an import error.
• Parsed channels are passed through standard sanitization/normalization.

Export behavior

• Export all 200 channels.
• Channel number is represented by row order.
• Emit canonical scanlist_ids column only.

Sheet: ScanLists (optional)

Defines list names and default active-list selection.

One row per list definition.

Columns

• list_id
  • Stable ID, ID001..ID016 (identifier, not row order)
• name
  • String, trimmed, max 10 characters
• active_default
  • Boolean-like flag

Sample rows

Example rows for a ScanLists sheet:

Import behavior

• Missing sheet: keep current list names and active mask.
• Missing rows: only provided rows override; remaining lists keep current values.
• list_id must be present, valid, and unique.
• Blank/invalid name: fallback to default L#.
• If all active_default values are false/empty, importer should preserve current active mask (or apply the app default).
• Row order defines list slot order in the app.

Export behavior

• Always emit 16 rows for IDs ID001..ID016.

Sheet: Radio (optional)

Radio-wide settings encoded as key/value rows for forward compatibility.

Columns

• key
• value
• notes (optional, ignored by importer)

Sample rows

Because Radio is key/value based, a single workbook may include rows like these:

Supported keys (initial set)

• beep_control
• bpm_control
• scan_resume_mode
• scan_dwell_seconds
• peak_time
• rf_gain
• tag_mode
• backlight_time
• flashlight_enabled
• arrow_orientation
• power_on_display_mode
• welcome_line1
• welcome_line2
• squelch_level
• pulse_threshold_dbm
• full_scale_dbm
• battery_calibration
• default_step_setting (optional convenience key)

Legacy-compatible (accepted on import, not canonical in export):

• scan_target_mode

Value expectations

• Booleans: same boolean-like parsing rules as other sheets
• Enums: must match accepted app values
• Numeric fields: parse as integer where applicable
• scan_dwell_seconds: sanitized to nearest of 1, 2, 3, 5, 10, 15, 20, 25, 30
• peak_time: sanitized to nearest of 5, 10, 20, 22, 24, 29, 39 (encoded values)
• rf_gain: clamped to integer range 0..24
• tag_mode: channel | tag
• Strings: trimmed and validated against setting limits
• arrow_orientation: up_down | left_right

Import behavior

• Unknown keys are ignored.
• Invalid values are ignored (current value is preserved).
• Missing sheet keeps existing radio settings unchanged.

Sheet: Meta (optional)

Metadata/provenance only. Optional on read.

Columns

• key
• value

Suggested keys

• format = spot-workbook
• format_version = 1
• exported_by = SPOT Tools <version>
• exported_at = ISO timestamp
• radio_model = uv-k5-telemetry
• schema_version = current JSON schema version

Sample rows

Typical metadata rows might look like this:

Behavior

• Meta data is non-authoritative and does not override parsed configuration values.

Common Parsing Rules

• Boolean-like values accepted: TRUE/FALSE, true/false, 1/0, yes/no, on/off.
• Trim surrounding whitespace from text values.
• Prefer true numeric cell types for numeric columns.
• Import should collect warnings per row/cell and continue where possible.

Validation and Sanitization

After parsing workbook data, SPOT Tools should apply the same sanitization pipeline used for JSON/radio reads:

• channel activity/frequency validity checks
• allowed step enforcement
• scan-list mask/list coercion
• telemetry-safe defaults for unsupported values

This keeps workbook import behavior aligned with all other input paths.

Versioning

• Initial workbook format: SPOT Workbook v1
• Backward compatibility strategy:
  • Channels sheet remains required.
  • Unknown keys/sheets ignored.
  • New optional keys/sheets may be added in future versions without breaking old files.