SitRepMapper Data File Reference

Purpose and the read-only rule

A companion program is a separate tool that adds a feature by reading SitRepMapper's data, with no change to SitRepMapper's code. This page lists the data a companion can use and the rules that keep it safe.

The one rule: companions read SitRepMapper's live data files; they never write to them. SitRepMapper loads these files at startup and rewrites them whenever its data changes. A file edited by another program while SitRepMapper runs will be overwritten, or will confuse its merge logic.

To get data into SitRepMapper, a companion writes an import file in a folder of its own. The user then loads it from SitRepMapper's normal Import menu (see Sending data back).

To show something on SitRepMapper's screen, a companion writes a small display file in the companions folder (see Showing things on screen).

Rules for companion authors

If you build a companion with an AI coding assistant, give it this whole page. These rules come first; the sections below give the details.

  1. Don't change SitRepMapper. A companion works from outside it. If something seems to need a change to SitRepMapper, stop and ask the user instead of making it.
  2. Read the live files; never write to them. Data goes back to SitRepMapper only through import files that the user loads (see Sending data back). In the config folder, the only files a companion writes are its own display files in companions/ (see Showing things on screen).
  3. Use the Safe reading recipe: retry if the JSON won't parse, check format and version, and re-read a file only when its modified time or size changes.
  4. Don't transmit unless the user has explicitly chosen that. Sending from two programs at once can collide with SitRepMapper's Send and Expect features.
  5. Open the JS8Spotter database read-only (mode=ro).
  6. Leave expect.expect.json and send_drafts.json alone. They are not part of the companion contract.
  7. Ignore fields you don't recognize, and give every config.json key a default.
  8. SitRepMapper's Python helpers are a convenience, not a promise. Recheck them after each SitRepMapper update.
  9. Keep the load light. Many users run on a Raspberry Pi shared with SitRepMapper, JS8Call and JS8Spotter.
  10. Test against a real ~/.config/sitrepmapper folder, not just made-up samples.
  11. If the companion acts on what stations send, give it callsign lists (see Stations a companion responds to).
  12. Ship an info sheet with it (see Companion info sheet).

Where the files live

All live data sits in one folder, ~/.config/sitrepmapper/. On Linux and Raspberry Pi OS that is /home/<user>/.config/sitrepmapper/; on Windows it is C:\Users\<user>\.config\sitrepmapper\. In Python, os.path.expanduser('~/.config/sitrepmapper') gives the right path on both.

FileHoldsCompanion use
reports.reports.jsonReport Library: every stored F!/CommStat report, plus deletion recordsRead
flags.flags.jsonFlag pins, plus deletion recordsRead
areas.areas.jsonDrawn areas, plus deletion recordsRead
config.jsonUser settings: data source paths, station call and grid, filtersRead
statusboard.statusboard.jsonStatus Board summary: latest status per station, sub-optimal flags, totalsRead
expect.expect.jsonExpect auto-reply entriesLeave alone
send_drafts.jsonSaved Send-form draftsLeave alone
companions/Display files that companions writeWrite your own only
companions.logProblems with display filesRead

The exports/ folder under the program directory is the default destination for exports. A companion may read files there too, but the user decides what goes in it.

reports.reports.json

This file is the Report Library: reports the user has imported. It does not hold live on-air traffic. SitRepMapper reads live reports straight from the JS8Spotter database or JS8Call's DIRECTED.TXT each time and never copies them here. A companion that needs live traffic should read those sources the same way (see Other data sources). A companion that only needs the overall picture can read statusboard.statusboard.json instead.

Top level:

{
  "format": "sitrepmapper_reports",
  "version": "1.0",
  "exported_at": "2026-08-28T02:47:59Z",
  "reports": [ ... ],
  "deleted": { "<sha256 identity hash>": "2026-08-13T16:06:44Z" }
}

Each entry in reports:

{
  "id": "6a0a2db3-b9e6-49b6-82c6-f8e68cda0004",
  "form_type": "f505",
  "raw_text": "@SITREP MSG F!505 33333333333333333333333333333333 ST[OK] GR[EM15] CT[CANADIAN] #HFV0",
  "callsign": "KJ5MIW",
  "timestamp_str": "2026-08-06 21:52:00",
  "source": "directed_log",
  "stored_at": "2026-08-13T15:31:28Z"
}
FieldMeaning
idUUID assigned when stored
form_typef104, f309, f500, f505 or commstat
raw_textThe message exactly as sent on air. All decoded values come from this.
callsignSending station, upper case
timestamp_strReceive time, YYYY-MM-DD HH:MM:SS, UTC with no zone suffix. May be empty for some F!104/309/505 reports with no datecode.
sourceWhere it came from: directed_log, js8spotter_db, file, …
stored_atWhen it entered the Library, ISO 8601 UTC

deleted maps a content hash to its deletion time. It only prevents a deleted report from coming back on re-import; a companion can ignore it, since deleted reports are already removed from reports.

Decoding raw_text: don't write a second parser. A Python companion can call the existing ones (see Safe reading recipe): report_store.report_from_envelope(entry) returns the decoded report object. Other languages need their own parser (see Decoding F! forms).

flags.flags.json

This file holds every flag pin on the map. It uses the same format as a .flags.json export, so a companion that can read one can read both.

{
  "format": "sitrep_flags",
  "version": "1.0",
  "exported_at": "2026-08-14T13:56:02Z",
  "flags": [
    {
      "id": "a064bad5-c58a-472e-95f1-555a2f44f75f",
      "description": "GMAG Member LJ",
      "grid": "EL99HC84MC",
      "lat": 29.100495416699804,
      "lon": -81.34573866097013,
      "datetime": "2026-07-17T18:35:20Z",
      "source": "GMAG",
      "color": "#00FF00",
      "blink": false,
      "severity": "",
      "status": "",
      "group": "GMAG Member",
      "updated_at": "2026-07-23T02:04:46Z"
    }
  ],
  "deleted": [
    { "id": "2179c825-84f8-4b62-9762-d88ac6c2ad64", "deleted_at": "2026-07-21T12:49:05Z" }
  ]
}
FieldMeaning
idUUID; the key used to merge on import
descriptionLabel shown on the pin
gridMaidenhead locator, 4 to 10 characters
lat, lonDecimal degrees. The map places the pin by these, not by grid.
datetimeEvent time the user entered, ISO 8601 UTC
sourceWho placed it; defaults to the station callsign
colorHex color, #RRGGBB
blinkWhether the pin flashes
severity, statusOptional free-text tags, often empty
groupGroup name for View > Flag Pin Groups; empty means no group
updated_atLast change, ISO 8601 UTC. On import, the newer copy wins.

deleted lists pins the user removed. SitRepMapper already removes those pins from flags, so a companion only needs to read flags.

areas.areas.json

This file holds every drawn area, in the same layout as the flags file: format sitrep_areas, an areas list and a deleted list of {id, deleted_at}.

{
  "id": "5803884c-67b9-4bbe-9a77-9102d6995f19",
  "type": "circle",
  "points": [[28.65111315468583, -80.65114287567138], [28.6505559645154, -80.64146165628706], ...],
  "description": "Zone 4 - Moderate Blast Damage (5 psi)",
  "color": "#FF0000",
  "line_width": 2,
  "show_title": false,
  "title_size": 14,
  "show_center": true,
  "group": "Nuke Damage Zone",
  "updated_at": "2026-08-12T00:40:34Z"
}
FieldMeaning
typepolygon, rectangle or circle
pointsOutline as [lat, lon] pairs in decimal degrees. Note the order: latitude first.
descriptionThe area's title
color, line_widthOutline color #RRGGBB and width in pixels
show_title, title_sizeWhether the title is drawn on the map, and its font size
show_centerWhether a center marker is drawn (on by default for circles)
groupGroup name for View > Area Groups
id, updated_atSame meaning as for flags: merge key and newest-wins timestamp

Circles have no center or radius field. They are stored as 48 outline points. The center is the average of the points, and the radius is the average distance from it. area_manager.centroid_latlon() and area_manager.circle_radius_m() compute both, and circle_points() builds the 48 points for a new circle.

config.json

This file is a flat JSON object of user settings. Only keys the user has changed are guaranteed to be there, so a companion must supply its own default for every key it reads. The keys most useful to a companion:

KeyMeaningDefault
report_sourceLive source in use: js8spotter_db or directed_logjs8spotter_db
last_db_pathPath to the JS8Spotter databaseempty
last_directed_log_pathPath to JS8Call's DIRECTED.TXTempty
station_callsignThe user's callsignempty
station_gridThe user's home gridempty
js8call_host, js8call_portJS8Call API address127.0.0.1, 2442
duplicate_handlingF!505 repeat reports: latest or average (see What the map shows)latest
roundingHow averaged F!505 scores round: round, ceil or floorround
filter_mode, filter_n_days, filter_from, filter_toThe map's Date Filter, so a companion can match what the map showsnone, 14, empty, empty
hidden_flag_groups, hidden_area_groupsGroup names hidden on the map[]
export_dirSave to Export Folder destination; empty means <program folder>/exportsempty

The full list, with comments, is DEFAULTS in config.py. Read report_source and the two path keys to find the same live data SitRepMapper is using.

statusboard.statusboard.json

Available in SitRepMapper v1.18.0 and later.

The Status Board's processed picture: each station's latest status for every report type, which stations are flagged sub-optimal and why, and totals. Use it when a companion needs to know what's going on overall, rather than what each report said.

It holds the same results that Reports > Status Board > Station Status Roster and Sub-Optimal Conditions Digest show for the same number of days, so a companion and the screen can't disagree.

Which reports it covers:

When it's written:

Top level:

{
  "format": "sitrepmapper_statusboard",
  "version": "1.0",
  "generated_at": "2026-11-09T18:42:10Z",
  "window": {
    "days": 7,
    "from": "2026-11-03",
    "to": "2026-11-09",
    "date_source": "received_time"
  },
  "thresholds": {
    "f104_degraded": true,
    "f104_problems": true,
    "f309_min_severity": "2",
    "f500_supply_tier": "moderate",
    "f500_mood_tier": "moderate",
    "f505_avg_below": 2.0,
    "commstat_yellow": true,
    "commstat_red": true
  },
  "totals": {
    "stations": 23,
    "flagged": 4,
    "reports_by_type": {"f104": 40, "f309": 3, "f505": 9, "f500": 6,
                        "commstat": 12},
    "flagged_by_type": {"f104": 2, "f505": 1, "commstat": 1}
  },
  "stations": [ ... ]
}
FieldMeaning
generated_atWhen SitRepMapper wrote the file, ISO 8601 UTC
windowWhich reports were counted: days ending on to (both dates UTC, YYYY-MM-DD), and whether a report's date is its receive time or its prepared time (date_source: received_time or timestamp)
thresholdsThe Sub-Optimal Thresholds in use (config.json keys bigpicture_thresh_*, without that prefix)
totalsstations: how many stations reported in the window. flagged: how many have at least one flagged type. reports_by_type: reports counted, every type listed. flagged_by_type: stations flagged for each type; a type with none is left out.

Each entry in stations:

{
  "callsign": "KJ5MIW",
  "grid": "EM15",
  "latest": "2026-11-09T17:58:00Z",
  "flagged_count": 2,
  "types": {
    "f104": {
      "time": "2026-11-09T17:58:00Z",
      "grid": "EM15",
      "status": "Problems",
      "flagged": true,
      "reason": "Problems",
      "code": "3"
    },
    "f505": {
      "time": "2026-11-07T19:30:00Z",
      "grid": "EM15",
      "status": "2.40 Degraded but Functional",
      "flagged": false,
      "reason": "",
      "score": 2.4
    },
    "commstat": {
      "time": "2026-11-09T02:10:00Z",
      "grid": "EM15",
      "status": "Red",
      "flagged": true,
      "reason": "Red",
      "code": "3"
    }
  }
}
FieldMeaning
callsignUpper case. Empty ("") when the reports carried no callsign and none could be matched by grid.
gridThe station's grid square: the first grid found in its reports (F!104 first, then F!309, F!505, F!500, CommStat). It doesn't follow later reports, so for where one report says it is, use that report's own grid below. This matters most for F!309, whose grid is the incident's location, not the station's.
latestTime of its most recent report of any type, ISO 8601 UTC, or null if none of its reports has a time
flagged_countHow many of its report types are flagged (0 to 5)
typesOne entry for each type the station sent in the window, holding only its latest report of that type. Types it didn't send are left out.
types.*.timeThat report's time, ISO 8601 UTC, or null
types.*.gridThat report's own grid, upper case, "" if none
types.*.statusThe Station Status Roster's text for that report
types.*.flaggedtrue if it crosses the Sub-Optimal Thresholds
types.*.reasonThe Digest's explanation when flagged, else ""
(values)The type's own machine-readable value(s), below

status and reason are for showing to people; their wording may be improved in later versions. Make decisions from flagged and the values below, which won't change meaning within version 1.x.

Values for each type, each on that type's own scale:

TypeFieldMeaning
f104code"1" Normal, "2" Degraded, "3" Problems, "" if missing
commstatcode"1" Green, "2" Yellow, "3" Red, "4" Unknown, "" if the status couldn't be read
f309severity"1" Minor, "2" Moderate, "3" Severe, "4" Major, "5" Unknown
categoryThe form's category code ("1"–"9", "A"–"R"); status gives its name
time_frame"1" General/unknown, "2" Anticipated (week/month), "3" Imminent (hours to days), "4" Currently happening, "5" Chronic, ""
situationThe form's Current Status: "1" New, "2" Ongoing, Deteriorating, "3" Ongoing, Improving, "4" Resolved, "5" Unknown, ""
expiresWhen the report's own Expiration runs out (from its datecode, else when received), ISO 8601 UTC, or null if it doesn't expire
ended"Resolved" (situation "4") or "Expired" (past expires), else "". An ended F!309 is never flagged, whatever its severity, and its status ends " (Resolved)" or " (Expired)". ended can turn to "Expired" with no new report, when the time passes.
f505scoreAverage of the known scores, 0.00 (worst) to 3.00 (fully operational), or null if every score was unknown
f500worst_questionKey of the most severe answered question: mood, eggs, milk, bread, water, gasoline, diesel, propane, batteries, containers, ammo, materials. null if none was answered (an "Unknown" answer doesn't count). A tie goes to the first in that list.
worst_severityThat answer from 0.0 (normal) to 1.0 (the question's worst answer), or null

There is deliberately no single severity number shared across types: the five forms don't measure the same things on the same scale. Use flagged and flagged_count to compare stations across types.

stations is sorted worst first: by flagged_count, highest first, then by callsign (or grid, when there's no callsign). To list the stations that need attention, take entries until flagged_count is 0.

This file has only each station's latest report of each type. For history or individual reports, read the reports themselves (see reports.reports.json and Other data sources).

Other data sources

Live reports don't come from SitRepMapper's files. They come from the same upstream sources SitRepMapper reads, and a companion can read those sources directly.

JS8Spotter database (path in last_db_path). This is SQLite. Always open it read-only, the way SitRepMapper does, so it is safe while JS8Spotter is running:

conn = sqlite3.connect(f'file:{db_path}?mode=ro', uri=True)
TableHoldsColumns SitRepMapper uses
formsF!104, F!309, F!500, F!505 messagesid, typeid, fromcall, msgtxt, responses, timesig, lm
csstatrepCommStat StatRepsid, cssr_from, cssr_group, cssr_grid, cssr_prio, cssr_msgid, cssr_status, cssr_notes, cssr_timestamp

To poll for new rows only, remember the highest id seen and query WHERE id > ?. js8spotter_db.JS8SpotterDB already does this and returns decoded reports.

JS8Call DIRECTED.TXT (path in last_directed_log_path). This is a tab-separated text log that JS8Call appends to: time (UTC), dial frequency, offset, SNR, then CALLSIGN: message. Read new lines from the last file position; never write to it. directed_log.parse_line() and route_entry() turn a line into a report.

JS8Call TCP API (js8call_host:js8call_port). This is JSON over TCP, for live events and for sending. A companion should only listen unless the user has explicitly chosen to let it transmit. Sending from two programs at once can collide with SitRepMapper's Send and Expect features, which check whether JS8Call is busy before they transmit.

What the map shows

No file holds the reports exactly as the map shows them. SitRepMapper builds that view each time, in this order (statusboard.statusboard.json follows steps 1 to 5 but uses its own window instead of step 6):

  1. Live reports from the source named in report_source.
  2. Plus every report in the Report Library (reports.reports.json).
  3. Minus callsigns listed in IGNORE.TXT, in SitRepMapper's program folder (not the config folder). One callsign per line, any case; lines starting with # are comments. No file means nobody is ignored. It applies to all five report types from every source.
  4. Minus repeat reports: several reports from the same callsign in the same grid square become one (see the table below). "Most recent" means received time, or prepared time if there is none. Different callsigns in the same grid are never merged.
  5. Minus reports with no grid square (they can't be placed).
  6. Trimmed by the Date Filter (filter_mode and the other filter_ keys). A report with no date passes the filter.
Report typeRepeat reports from one callsign in one grid
F!505Follows duplicate_handling: latest keeps the most recent; average makes one report with averaged scores, rounded as set by rounding
F!104, F!500, CommStatAlways keep the most recent
F!309Never merged (each is a separate incident)

A companion doesn't have to match the map. A trend companion may want every report, repeats included. But one that claims to show "what the map shows" should follow these steps.

Decoding F! forms

Python companions should use SitRepMapper's own parsers (see reports.reports.json). Companions in other languages need two things:

Each form is one line. Tags in [brackets] other than the form number and answer string may be missing. A checksum in {HEX} or [CRC:...] form may follow; strip it before parsing.

LayoutAnswer string
F!104 <3 chars> ST[XX] GR[grid] FM[text] <comment> #XXXXChar 1: 1 = Green, 2 = Yellow, 3 = Red. Char 2: situation report code. Char 3: 0 = no alert, E = Awareness/Alert Report active.
F!309 <6 chars> DS[description] GR[grid] #XXXXOne character per field: Affected Area, Category, Severity, Time Frame, Status, Expiration, using the @ codes in MCF309.txt.
F!500 <13 digits> ST[XX] GR[grid] CT[city/county] #XXXXOne digit (1–9) per question, in the order of MCF500.txt.
F!505 <32 chars> ST[XX] GR[grid] CT[city/county] #XXXXOne score per field, 1 to 32: 0, 1, 2 or 3, or X for unknown.

ST is a 2-letter state, GR a Maidenhead grid of 4 to 10 characters.

#XXXX is a datecode: the time the form was prepared, in UTC. It is not a checksum. Each of the 4 characters is one part:

PartCharacters
MonthA–L = January to December
DayA–Z = 1 to 26; 0–4 = 27 to 31
HourA–X = 0 to 23
MinuteA–Z = 0, 2, 4 … 50; 0–3 = 52, 54, 56, 58

The year isn't sent; use the current UTC year. Example: #KCMA is November 3, 12:00 UTC.

CommStat StatReps come in more than one valid format. The easiest route is the JS8Spotter database's csstatrep table, where the fields are already split into columns (see Other data sources).

Sending data back

A companion adds data by writing an import file in its own folder, which the user then loads from the File menu. SitRepMapper's existing merge rules handle duplicates, so importing the same file twice does no harm.

To addWrite this fileUser loads it with
Flag pins<name>.flags.json, same layout as flags.flags.jsonFile > Import Flag Pins…
Areas<name>.areas.json, same layout as areas.areas.jsonFile > Import Areas…
ReportsA sitrepmapper_reports file, same layout as reports.reports.json (id and stored_at may be omitted; deleted is not needed)File > Import/Export Reports > Import Report Library…

Rules for files a companion writes:

Showing things on screen

Available in SitRepMapper v1.18.0 and later.

A companion can put a message on a banner under the toolbar, or a color block at the right end of the toolbar, by keeping a small text file in ~/.config/sitrepmapper/companions/. SitRepMapper checks that folder every 5 seconds. It only reads these files; it never moves, changes or deletes them. Writing them is optional: a companion can have its own window, or no window at all.

SitRepMapper creates the folder when it starts. A companion can start first, so it should create the folder too if it's missing.

File names

FileShows
<CODE>.bannerText for the banner
<CODE>.indicatorA color block

CODE is exactly 3 characters, A-Z or 0-9, upper case. Each companion picks its own, and two companions using the same code will overwrite each other's files. There's no central list. SRM (SitRepMapper) and TST (testing) are reserved. Anything else in the folder is ignored, including *.tmp files.

Keep one file per display and replace it to update the display. Delete the file to clear the display.

File layout

#DET
ACTION: BANNER
MODE: SCROLL
MAXAGE: 120

Bridge out on Route 9 near mile 14
Shelter open at Lincoln School
#DET
ACTION: INDICATOR
COLOR: YELLOW
TEXT: Caution

Line 1 is # plus the code, with nothing else on the line. It must match the file name exactly. Then come LABEL: value lines, in any order. On a banner, a blank line and then the text follow. Each non-blank line of text is one banner item.

LabelUsed onRequired?ValuesDefault
ACTIONBothYesBANNER or INDICATOR, must match the file nameNone
MAXAGEBothNoWhole minutes, 1 or more60
MODEBannerNoSTATIC, SCROLL, ALERTSTATIC
COLORIndicatorYesGREEN, YELLOW, RED, GRAYNone
TEXTIndicatorNoUp to 10 charactersA letter

Format rules

How a banner behaves

How an indicator behaves

Writing the files safely

Write to a temporary name, then rename, so SitRepMapper never catches a half-written file. Rewrite an indicator on a timer even if nothing has changed, with MAXAGE at least twice that interval. Then the block turns gray if the companion stops, which is how the user can tell.

import os

COMPANIONS_DIR = os.path.expanduser('~/.config/sitrepmapper/companions')


def write_display_file(name, text):
    """Replace one display file in a single step."""
    os.makedirs(COMPANIONS_DIR, exist_ok=True)
    path = os.path.join(COMPANIONS_DIR, name)
    tmp = path + '.tmp'
    with open(tmp, 'w', encoding='utf-8') as f:
        f.write(text)
    os.replace(tmp, path)


write_display_file('DET.indicator',
                   '#DET\nACTION: INDICATOR\nCOLOR: GREEN\n'
                   'TEXT: All Clear\nMAXAGE: 5\n')

write_display_file('DET.banner',
                   '#DET\nACTION: BANNER\nMAXAGE: 30\n\n'
                   'Shelter open at Lincoln School\n')

Finding problems

~/.config/sitrepmapper/companions.log records unreadable files with the reason, banner text changes, cut-off text and extra indicators. It's only written when something changes, it keeps only recent entries, and its wording may change. Read it while testing; don't build on it.

Starting and stopping

SitRepMapper doesn't start or stop companions. A companion can start from desktop autostart on Linux and the Pi, or the Startup folder on Windows, and can run while SitRepMapper is closed. One with a window can simply be closed. One without a window needs a way to stop, such as a Stop button in its settings using a PID file.

Stations a companion responds to

A companion that acts on what stations send keeps two callsign lists in its own settings. SitRepMapper has no setting for this.

ListMeaning
Always IgnoreNever act on these stations.
Ignore all exceptAct only on these stations. * means everyone.
def may_trigger(callsign, always_ignore, ignore_all_except):
    """Both lists hold upper-case callsigns. An empty
    ignore_all_except means nobody."""
    callsign = callsign.upper()
    if callsign in always_ignore:
        return False
    return '*' in ignore_all_except or callsign in ignore_all_except

Companion info sheet

Each companion ships a short text file named <ProgramName>_<DocType>.txt, for example FlagWatch_Info.txt, so the user knows what it does before running it. SitRepMapper has no list of installed companions. Copy this template:

<Program name> v<version>
By <author>

Purpose:        What it does, in a sentence or two.
Code:           Its 3-character code, and any Expect codes the user
                must know.
Display:        What each color, word and banner means.
Transmits:      Whether it transmits, when, and how the user turns
                that on.
Callsign lists: Where they're set. An empty "Ignore all except" list
                means nobody can trigger it.
Reads:          The files it reads.
Writes:         The files it writes.
Start:          How to start it, and whether it starts by itself.
Stop:           How to stop it.
Remove:         How to remove it, including any files it leaves.

Safe reading recipe

SitRepMapper saves each data file by writing a temporary <file>.tmp and then swapping it into place, so a reader normally sees either the complete old file or the complete new one. On Windows, if another program has the file open at that moment, the save falls back to writing over the file directly, so a companion can still very rarely catch a file half-written. The fix: if the JSON fails to parse, wait a moment and try again.

import json
import os
import time

CONFIG_DIR = os.path.expanduser('~/.config/sitrepmapper')


def read_sitrep_file(name, expected_format, retries=3):
    """Read one SitRepMapper data file. Returns None if it can't be
    read right now: missing, still mid-write after a few tries, or a
    format this companion doesn't know."""
    path = os.path.join(CONFIG_DIR, name)
    for _ in range(retries):
        try:
            with open(path, encoding='utf-8') as f:
                data = json.load(f)
        except FileNotFoundError:
            return None
        except (json.JSONDecodeError, OSError):
            time.sleep(0.5)      # caught it mid-save; try again
            continue
        if data.get('format') != expected_format:
            return None
        if not str(data.get('version', '')).startswith('1.'):
            return None          # a format this companion doesn't know
        return data
    return None


def file_signature(name):
    """Modified time plus size. Re-read the file only when this
    changes. The size catches two quick saves that land in the same
    2-second slot on FAT/exFAT USB drives."""
    try:
        st = os.stat(os.path.join(CONFIG_DIR, name))
    except FileNotFoundError:
        return None
    return (st.st_mtime_ns, st.st_size)


data = read_sitrep_file('flags.flags.json', 'sitrep_flags')
if data is not None:
    flags = data.get('flags', [])

The same call reads ('areas.areas.json', 'sitrep_areas') with the key areas, ('reports.reports.json', 'sitrepmapper_reports') with the key reports, and ('statusboard.statusboard.json', 'sitrepmapper_statusboard') with the key stations. None isn't the same as an empty list: keep the last good data, or a failed read will look as if everything was deleted.

To decode library reports with SitRepMapper's own parsers, add its program folder to the import path:

import sys
sys.path.insert(0, '/path/to/sitrepmapper')
import report_store

report = report_store.report_from_envelope(reports[0])

Other habits that keep a companion well-behaved:

Stability and compatibility

The file formats are the stable part. They double as SitRepMapper's export formats and are shared with other tools, so they won't change lightly. If they do change, the version field changes and the SitRepMapper changelog says so.

What a companion relies onStability
format names, field names, version 1.0Stable. Check format before reading.
New fields appearing in recordsPossible. Ignore fields you don't recognize. Existing fields won't be removed or renamed within version 1.x.
config.json keysMostly stable, but keys can be added or retired between versions. Always supply a default.
statusboard.statusboard.jsonStable, like the other data files. status and reason are display text whose wording may change; the coded values don't.
Display files in companions/Stable. Labels and values are only added to; existing ones won't change or be removed. companions.log isn't part of this.
Python helpers (report_from_envelope, JS8SpotterDB, parse_line, centroid_latlon)Internal code, not a promise. Usually unchanged, but recheck after a SitRepMapper update.
expect.expect.json, send_drafts.jsonNot documented for companions; may change at any time.