================================================================================ JS8Reporter – User Manual Version 1.7.1 Stephen Clay McGehee, KN4AM ================================================================================ TABLE OF CONTENTS ----------------- 1. Overview 2. Requirements and Installation 3. Starting the Program 4. Interface Layout 5. Loading Data 5.1 Open Assessments Database 5.2 Import F505 File 5.3 Import F104 File 5.4 Import All Files from Folder 5.5 Automatic Deduplication 5.6 Ignoring Call Signs (IGNORE.TXT) 6. The Assessment List 7. The Map 7.1 Map Symbols and Markings 7.2 F!104 Situation Report Pins 7.3 Map Legend 7.4 Pop-Out Map 7.5 Flag Pins 7.6 Grid Converter 8. Assessment Detail and Summary Table 9. Date Filter 10. Circle Filter 11. Time Lapse 12. ALERT Detection 13. Reports 14. Exporting Data 15. Settings 16. Keyboard Shortcuts 17. Troubleshooting ================================================================================ 1. OVERVIEW ================================================================================ JS8Reporter is a companion program to JS8Spotter. It reads MCF505 Area Assessment (F!505) and F!104 Situation Report form data received via JS8Call / JS8Spotter and displays that data on an offline map of North America, allowing emergency managers to visualize operational status and situational awareness across a wide area. JS8Reporter operates entirely offline at runtime. No internet connection is required once the program and its map data are installed. Key capabilities: - Displays color-coded F!505 map pins showing infrastructure condition at each reporting station's grid square location - Displays F!104 Situation Report diamond pins showing operational status (Normal / Degraded / Significant Problems) at each station's location - Both pin types respect all filters: Date Filter, Circle Filter, and Time Lapse - Flag Pins: manually-placed SitRep markers annotating the map with information from any source; import/export in a format interoperable with MHGridMapper for net distribution - Tabulated summary and detail views of all received assessments - Date filtering to focus on a specific time window - Circle filter to focus on a geographic area - Time Lapse playback to visualize how conditions change over time - ALERT detection for both F!505 and F!104 records, with prominent notification identifying the form type, callsign, and grid square - Twelve analytical report types for F!505 data; F!104 Summary report - Export of map images and tabular data MCF505 / F!505 Form Reference: https://sitrepnet.com/mcforms/MCF505.txt More Information: SitRepNet.com ================================================================================ 2. REQUIREMENTS AND INSTALLATION ================================================================================ Full installation instructions, system requirements, desktop launcher setup, and setup troubleshooting are in a separate document: Installation_Guide.txt This file is included in the JS8Reporter program folder. Quick summary: 1. Open a terminal (or Command Prompt on Windows) and navigate to the js8reporter folder. 2. Run: python3 setup.py (Linux / Raspberry Pi) python setup.py (Windows) 3. Verify map data with Help > Map Setup (setup.py)… ================================================================================ 3. STARTING THE PROGRAM ================================================================================ Linux / Raspberry Pi --------------------- Double-click the JS8Reporter icon on the Desktop. Or from a terminal: bash /home//js8reporter/run.sh Windows -------- Double-click the JS8Reporter shortcut on the Desktop. Or from a Command Prompt: C:\Users\\js8reporter\run.bat On startup, JS8Reporter will automatically reload the last database that was opened, if one is available. If IGNORE.TXT contains any call signs, an "IGNORE.TXT Active" dialog will appear listing the ignored call signs. See Section 5.6. If setup has not been run yet, see Installation_Guide.txt. ================================================================================ 4. INTERFACE LAYOUT ================================================================================ The JS8Reporter window is divided into four main areas: +------------------------------------------------------------------+ | Menu Bar: File View Circle Reports Settings Tools Help | +------------------+-----------------------------------------------+ | | | | Loaded | MAP | | Assessments | (color-coded map pins on North America) | | (list) | | | | Navigation toolbar (zoom, pan, home) | +------------------+-----------------------------------------------+ | Date Filter | Assessment Detail / Summary Table | +------------------+-----------------------------------------------+ | Status Bar | Mode | +------------------------------------------------------------------+ Menu Bar -------- All program functions are accessed through the menu bar. See the individual sections below for details on each menu. Left Panel — Loaded Assessments --------------------------------- Lists all assessments currently loaded into the program. Each entry shows the callsign, grid square, and report timestamp. Color coding in the list: - Normal text : Valid assessment - Bold red : Assessment contains an ALERT - Gray / italic : Assessment marked as invalid (excluded from map) Click an entry to select it and view its full detail below. Press the Delete key while an entry is selected to mark it as invalid (or to restore it if it is already invalid). Marking an assessment as invalid removes it from the map and from all reports, but keeps it visible in the list for reference. Date Filter ----------- Located below the assessment list. Allows filtering by date range. See Section 9 for full details. Map Area -------- Shows a color-coded map of North America with two types of map symbols: F!505 Area Assessment pins (▼ inverted triangle + circle): Color indicates infrastructure condition: Green (#28a745) = Score 3 – Fully Operational Yellow (#ffc107) = Score 2 – Degraded Orange (#fd7e14) = Score 1 – Severely Impaired Red (#dc3545) = Score 0 – Destroyed The score displayed is determined by the Pin Color Mode setting. F!104 Situation Report pins (◆ solid diamond): Color indicates reported operational status: Green (#28a745) = Status 1 – Normal Yellow (#ffc107) = Status 2 – Degraded Red (#dc3545) = Status 3 – Significant Problems F!104 pins carry no label. Click a diamond to see its detail. Both pin types display a red "!" badge when an active ALERT is present. The navigation toolbar below the map provides: Home – Return to the default full-map view Back – Go to previous zoom/pan view Forward – Go to next zoom/pan view Pan – Click and drag to pan the map Zoom – Draw a rectangle to zoom in; auto-exits after one use Press Escape at any time to exit Pan or Zoom mode and return the cursor to normal. Click any map pin or diamond to view its detail in the panel below. To show or hide F!104 pins, use View > Show F!104 Pins. Report Detail / Assessment Detail ----------------------------------- The panel title and content change depending on what is selected: "Report Detail" — shown when an F!505 assessment is selected, or when no pin is selected (summary table mode). "F!104 Detail" — shown when an F!104 diamond pin is clicked. Displays callsign, grid, status label, and filed date for that record. To return to the summary table, use View > Show Summary or click an empty area of the assessment list. Status Bar ---------- Shows the most recent program message (e.g., "Loaded 12 assessments from spotter.db"). Mode Indicator -------------- The blue label at the right of the status bar shows the current interaction mode (e.g., "Click map to set circle center"). ================================================================================ 5. LOADING DATA ================================================================================ JS8Reporter can load F!505 assessment data and F!104 Situation Report data from multiple sources: 5.1 Open Assessments Database (File > Open Assessments Database…) -------------------------------------------------------------------- Opens a JS8Spotter SQLite database file (.db). This is the primary way to load data that has been received over the air by JS8Spotter. JS8Reporter opens the database read-only and is safe to use while JS8Spotter is actively running and writing to the same file. Both F!505 assessments and F!104 Situation Reports are loaded from the same database file automatically. The database path is remembered and the database is automatically reloaded the next time JS8Reporter starts. 5.2 Import F505 File (File > Import F505 File…) -------------------------------------------------- Imports F!505 assessments from a single plain text file or a JS8Spotter CSV export file. Useful for loading manually prepared assessments or data exported from another system, including files created by File > Export as F505…. Supported formats: - Plain text F505 form (as transmitted over JS8Call) - JS8Spotter CSV export - F505 export file created by File > Export as F505… 5.3 Import F104 File (File > Import F104 File…) -------------------------------------------------- Imports F!104 Situation Report records from a single plain text file or a JS8Spotter CSV export file. Supported formats: - Plain text F!104 form (as transmitted over JS8Call) - JS8Spotter CSV export containing F!104 records F!104 records are added to the existing display without clearing any loaded F!505 assessments. 5.4 Import All Files from Folder (File > Import All Files from Folder…) -------------------------------------------------------------------------- Imports F!505 and F!104 records from every .txt and .csv file found in the configured Import Records folder, and imports flag pins from every .flags.json file found there (see Settings > Export > Import Records folder). Each .txt/.csv file is automatically scanned for both F505 and F104 form types. Before importing, JS8Reporter will display a confirmation message showing the folder path and warn that all currently loaded F!505 and F!104 reports will be cleared. Flag pins are merged (not cleared) using the same timestamp-based merge as a normal flag pin import. Click Yes to proceed or No to cancel. After clearing, all files in the folder are parsed and combined. Any records that appear in more than one file are automatically deduplicated before being added to the display. The Import Records folder is set in Settings > Export > Import Records folder. It defaults to the data/imports/ folder inside the JS8Reporter program folder. 5.5 Automatic Deduplication ----------------------------- When loading data, JS8Reporter automatically handles duplicates: F!505 Station + Date deduplication: If the same callsign submitted more than one assessment on the same calendar day, only the most recent submission for that day is shown. F!505 Grid square deduplication: If more than one F!505 assessment maps to the same grid square, the behavior is controlled by the Settings > Filters > Duplicate grid-square handling option (use most recent, or average scores). F!104 Grid square deduplication: If more than one F!104 record maps to the same grid square, only the most recently received record for that grid square is shown. 5.6 Ignoring Call Signs (IGNORE.TXT) --------------------------------------- Assessments from call signs listed in IGNORE.TXT are silently discarded and never added to JS8Reporter's display. IGNORE.TXT is a plain text file located in the main JS8Reporter program folder (the same folder as js8reporter.py). If the file does not exist, no call signs are ignored. File format: - One call sign per line - Call signs are not case-sensitive - Lines beginning with # are treated as comments and skipped - Blank lines are skipped Example IGNORE.TXT: # Operators whose assessments should not be displayed W1ABC KG5XYZ The filter applies to every data source: - JS8Spotter database (open, auto-reload on startup, and the periodic background refresh while a database is open) - File imports (File > Import F505 File…) - Folder imports (File > Import All Files from Folder…) On startup, if IGNORE.TXT contains any entries, JS8Reporter displays an "IGNORE.TXT Active" dialog listing the ignored call signs. To stop ignoring a call sign, remove it from IGNORE.TXT and restart JS8Reporter. ================================================================================ 6. THE ASSESSMENT LIST ================================================================================ The list on the left side of the window shows all loaded assessments, sorted by report creation date (most recent first). Selecting an Assessment ----------------------- Click any entry to select it. The Assessment Detail panel updates to show that assessment's full field-by-field detail. Click an empty area of the list to deselect and return to the Summary Table view. Marking as Invalid / Restoring -------------------------------- Select an assessment and press the Delete key. - If the assessment is valid, you will be asked to confirm marking it as invalid. Invalid assessments are grayed out in the list and excluded from the map and all reports. - If the assessment is already invalid (grayed out), you will be asked to confirm restoring it as valid. Invalid/valid status is remembered between sessions for the same database. ALERT Records ------------- Assessments whose text contains the word "ALERT" are shown in bold red in the list and trigger the ALERT notification. See Section 12. ================================================================================ 7. THE MAP ================================================================================ The map shows two types of data pins (F!505 and F!104), an optional Circle Filter overlay, and ALERT badges. All are described in 7.1 below. Map Navigation -------------- Use the navigation toolbar below the map to zoom and pan. The Home button returns to the full North America view. When Time Lapse is running, use the Left and Right arrow keys to step backward and forward through dates. Pin Color Modes (Settings > Pin Colors) ----------------------------------------- Applies to F!505 Area Assessment pins only. Lowest score across all fields: Pin color reflects the single worst-scoring field in the assessment. Average of all fields: Pin color reflects the overall average score (default). Average within selected category: Pin color reflects the average score for one specific category. Lowest score within selected category: Pin color reflects the worst field within one specific category. 7.1 MAP SYMBOLS AND MARKINGS ------------------------------ F!505 Area Assessment Pin Each F!505 assessment with a valid grid square appears on the map as a two-part pin symbol: Circle (head): A solid filled circle positioned above the triangle. The circle has no independent meaning — together with the triangle it forms a single "map pin" symbol, similar to a thumbtack. The larger circular head makes the pin easier to see at a glance and easier to click. It is the same color as the triangle below it. Triangle (stem/pointer): A downward-pointing triangle whose tip marks the exact grid square location on the map. The triangle color represents the assessment score, determined by the active Pin Color Mode (see above). Color scale: Green (#28a745) = Score 3 – Fully Operational Yellow (#ffc107) = Score 2 – Degraded Orange (#fd7e14) = Score 1 – Severely Impaired Red (#dc3545) = Score 0 – Destroyed Label: When pin labels are enabled (Settings > Pin Colors > "Always display Map Pin info"), the callsign and score appear to the right of the pin. F!104 Situation Report Diamond Each F!104 record with a valid grid square appears as a solid filled diamond (◆) at that grid square location. Color scale: Green (#28a745) = Status 1 – Normal Yellow (#ffc107) = Status 2 – Degraded Red (#dc3545) = Status 3 – Significant Problems F!104 diamonds carry no label. Click a diamond to see its detail. Use View > Show F!104 Pins to show or hide the diamond layer. ALERT Badge When an F!505 assessment or F!104 record carries an active ALERT: - A red circle with a white "!" appears above the pin or diamond. - F!505 pins change to a red-orange color. - F!104 diamonds keep their status color but gain the "!" badge. Dismissing the ALERT banner with "Cancel Alert" removes all badges. New alert records arriving afterward will trigger the badge again. Circle Filter Overlay When the Circle Filter is enabled, a dashed blue circle with a center crosshair (+) and a diameter label is drawn on the map. Assessments and records outside the circle are excluded from the map and reports. See Section 10 for full details. 7.2 F!104 SITUATION REPORT PINS ---------------------------------- F!104 Situation Report pins appear as solid colored diamonds (◆) on the map. They are separate from, and drawn on top of, the F!505 pin layer. Colors: Green (#28a745) – Status 1: All operations normal Yellow (#ffc107) – Status 2: Under control, degraded Red (#dc3545) – Status 3: Significant current problems F!104 pins carry no callsign label. Click any diamond to open its detail in the "F!104 Detail" panel (callsign, grid, status, filed date). Clicking an F!505 pin or clearing the selection returns the panel to "Report Detail" mode. Show / Hide: Use View > Show F!104 Pins to toggle F!104 diamond pins on or off. The setting is saved and restored on the next startup. Data source: F!104 records are loaded from the same JS8Spotter database as F!505 assessments (automatically), or from a file via File > Import F!104 File…, or from a folder via File > Import All Files from Folder. 7.3 MAP LEGEND --------------- A single combined legend is displayed in the lower-left corner of the map. It is organized into three sections: Map Symbols: Shows all map symbols with representative markers: ▼ F!505 Area Assessment pin ◆ F!104 Situation Report diamond ▼ Flag Pin (SitRep) — teardrop shape, user-chosen color ○ Selection Circle F!505 Status ▼: Color scale for F!505 Area Assessment pins. F!104 Status ◆: Color scale for F!104 Situation Report diamonds. This section is omitted when View > Show F!104 Pins is unchecked. Flag Pins ⚑: Appears when at least one flag pin exists. Shows a teardrop pin marker (▼) in the default red color with a "SitRep Flag Pin" label. 7.4 POP-OUT MAP ---------------- The map can be detached from the main window into its own resizable window via View > Pop Out Map. This is useful when you want to keep the map continuously visible while working in the main window — for example, while reviewing individual assessment details or scrolling the assessment list. For routine monitoring, the pop-out map is often the better arrangement. With the map in its own window (or on a second monitor), the main window is free to display the full assessment list and detail panel without the map competing for vertical space. The pop-out map is fully live: it updates on the same automatic polling cycle as the rest of the application, so new records appear on the map within approximately one minute of arrival — no manual refresh needed. Dock Map button: The "Dock Map" button at the bottom of the pop-out window returns the map to its original position inside the main window. The window size and position are remembered, so the next time you pop the map out it reopens where you left it. Closing the pop-out window has the same effect as clicking "Dock Map" — the map returns to the main window rather than being dismissed entirely. 7.5 FLAG PINS -------------- Flag pins are manually-placed situational awareness markers. They are independent of received F!505/F!104 radio traffic and can represent information gathered from any source — radio nets, voice reports, written messages, etc. Placing a Flag Pin: Right-click any location on the map and select "Add Flag Pin Here…". Fill in the fields in the dialog: Description: Free-text note (appears as a label on the map). Grid Square: Maidenhead locator — auto-fills lat/lon (or vice versa). Date / Time: UTC timestamp for the event (defaults to now). Source: Where the information came from. Pre-filled with the station callsign set in Settings > General; edit as needed (e.g., "W5XYZ via voice net"). Color: Pin color — click the color swatch to choose. Editing or Deleting a Flag Pin: Right-click anywhere near a flag pin on the map. The context menu shows the pin's description and offers "Edit Flag Pin: [description]…" and "Delete Flag Pin". If an F505 or F104 pin is also near the click location, the same menu additionally shows "View Assessment: [callsign]" and/or "View F104 Report: [callsign]", so all overlapping pins are accessible from a single right-click. Exporting Flag Pins (File menu): File > Export Flag Pins… saves all current flag pins directly, without opening the Flag Pins dialog. Managing All Flag Pins (View > Flag Pins…): Opens the Flag Pins management dialog listing all current pins. Buttons: Add, Edit, Delete, Jump to Map, Import, Export. Exporting Flag Pins: Click Export in the Flag Pins dialog. The file is saved in the sitrep_flags JSON format (.flags.json). The station callsign set in Settings > General is written to the file as created_by. Importing Flag Pins: Click Import in the Flag Pins dialog. Select a .flags.json file. New pins are added; existing pins (matched by ID) are replaced only if the incoming pin has a newer updated_at timestamp. The count of pins added or updated is shown on completion. Net Distribution Workflow: One operator (e.g., net control or SitRep officer) creates flag pins from multiple sources and exports the file. The .flags.json file is distributed over the radio net. Recipients import it — corrections and additions in the redistributed file update existing pins automatically via the timestamp-based merge. Flag pins are stored in data/flags.flags.json and persist between sessions. The .flags.json format is fully interoperable with MHGridMapper. Flag Pin Appearance: JS8Reporter displays flag pins as a teardrop map-pin shape (▼) in the user-chosen color — the same shape used for F!505 and F!104 pins. MHGridMapper displays the same pin data as a traditional flag icon (⚑). The visual symbols differ between programs; the underlying data and file format are identical. 7.6 GRID CONVERTER (Tools > Grid Converter…) ---------------------------------------------- Converts between Maidenhead grid squares, MGRS/USNG military grid coordinates, and decimal Lat/Lon. Enter any supported format in the input field and click Convert (or press Enter) — the format is detected automatically. Accepted input formats: Maidenhead e.g. EL99hc MGRS / USNG e.g. 15RYP53780 Lat, Lon e.g. 34.5678, -86.1234 Results displayed: Detected format – Maidenhead, MGRS, or Lat/Lon Maidenhead – Grid square (4, 6, or 8 characters) MGRS / USNG – Military grid reference Latitude – Decimal degrees N/S Longitude – Decimal degrees E/W Options: MGRS precision – 10 m / 100 m / 1 km / 10 km Maidenhead length – 4-char, 6-char (default), or 8-char Buttons: Copy Maidenhead, Copy MGRS, Close. ================================================================================ 8. ASSESSMENT DETAIL AND SUMMARY TABLE ================================================================================ The detail panel title and content change based on what is selected. Summary Table (title: "Report Detail") ---------------------------------------- Shown on startup and whenever no pin is selected. Displays a grid of category averages for all currently visible F!505 assessments, with Min / Max / Avg columns. To return to the summary table at any time: - Use View > Show Summary, or - Click an empty area in the assessment list. F!505 Assessment Detail (title: "Report Detail") --------------------------------------------------- Shown when an F!505 assessment is selected from the list or by clicking a pin on the map. Displays full information for that assessment: - Callsign, grid square, coordinates, state, city/county - Report prepared timestamp and received timestamp - Source, SNR, frequency - Overall average score with color bar - Per-category scores with color bars - Field-by-field scores (fields 1–32) - Notes, if any Score values: 3 – Fully Operational 2 – Degraded 1 – Severely Impaired 0 – Destroyed X – Unknown / Not Applicable (excluded from averages) F!104 Situation Report Detail (title: "F!104 Detail") ------------------------------------------------------- Shown when an F!104 diamond pin is clicked on the map. Displays compact information for that record: - Callsign - Grid square - Status code and full status label - Filed date/time (UTC) - ALERT: Active (if an alert flag is set) The F!104 detail panel does not affect the Assessment List selection. Click an empty area of the assessment list or use View > Show Summary to return to the summary table. ================================================================================ 9. DATE FILTER ================================================================================ The Date Filter is located in the lower-left panel, below the assessment list. It restricts the map and all reports to assessments within a specified date range. Enabling and Disabling ----------------------- Check or uncheck the "Enable" checkbox, then click Apply. Date Format ----------- Dates must be entered as: YYYY/MM/DD (e.g., 2025/03/14) The From and To fields use overtype mode — type digits directly over the existing date. The cursor skips over the "/" separators automatically. Adjusting Dates --------------- With the cursor in a date field, press: + or = to advance the date by one day - to move the date back by one day Default Range ------------- When the filter is first enabled, it defaults to the past 30 days. Buttons ------- Apply – Activates the filter with the current From / To dates. Clear – Removes the date filter (shows all dates). ================================================================================ 10. CIRCLE FILTER ================================================================================ The Circle Filter restricts the map and all reports to assessments whose grid square falls within a specified radius of a center point. Setting the Circle Center -------------------------- Circle > Set Circle Center… The mode indicator changes to "Click map to set circle center." Click anywhere on the map to place the center point. The circle is drawn immediately. Configuring the Circle ----------------------- Circle > Configure Circle… Opens the Settings dialog to the Circle tab, where you can enter the center latitude, longitude, and radius in miles directly. Disabling the Circle --------------------- Circle > Disable Circle Removes the circle overlay and includes all assessments regardless of location. Notes ----- The circle is drawn as a geographic ellipse on the equal-aspect lat/lon map. It appears wider east-west at higher latitudes, which correctly represents equal distances in all directions. ================================================================================ 11. TIME LAPSE ================================================================================ Time Lapse steps the map through assessment dates, allowing you to visualize how conditions have changed over time. Starting and Stopping ---------------------- View > Time Lapse (checkbutton — checkmark shows when running) A checkmark next to the menu item indicates Time Lapse is active. Select it again to cancel. If no dated assessments are available, Time Lapse cannot start and the checkmark is cleared automatically. Navigation ---------- Use the Left and Right arrow keys to step through dates: Left arrow – Step back one date Right arrow – Step forward one date Dates wrap around at both ends. Time Lapse Modes ----------------- Set in Settings > Filters > Time Lapse Mode: Rolling Window (default): Shows assessments within a sliding window of N days ending on the current playback date. The window size is user-configurable (default: 14 days). This is the most useful mode for showing recent conditions as the date advances. Cumulative: Shows all assessments up to and including the current playback date. The map "builds up" as time advances. Assessments from the current playback date are highlighted. Snapshot: Shows only assessments from the exact current playback date. Time Lapse Settings -------------------- View > Time Lapse Settings… opens the full Settings dialog where the mode and rolling window size can be configured. ================================================================================ 12. ALERT DETECTION ================================================================================ JS8Reporter automatically scans incoming records for ALERT conditions: F!505 assessments: the word "ALERT" in the message text F!104 records: an active alert flag (CSA character 3 = 'E') When an ALERT Is Detected -------------------------- - The ALERT notification bar appears at the top of the window in bold red, identifying the form type, callsign, and grid square: F!505 ALERT: W4XYZ (EM73) F!104 ALERT: K5ABC (DM79) - A "Cancel Alert" button appears next to the notification - F!505 assessments with an alert are displayed in bold red in the assessment list - The alerting pin or diamond shows a red "!" badge on the map The bar shows the details of the first alert received. Subsequent alerts in the same session are recorded but do not update the bar text until after Cancel is pressed. Canceling the Alert -------------------- Click the "Cancel Alert" button to dismiss the notification. All active alert records of both types are cleared in the current session. They will not re-trigger the notification unless new alert records arrive after the cancel. Marking an F!505 Alert Record as Invalid ------------------------------------------ If an F!505 ALERT record is marked as invalid using the Delete key, the notification banner is automatically dismissed (since the record is no longer considered active). Enabling / Disabling ALERT Detection -------------------------------------- Settings > Preferences… > Filters tab > Alert enabled checkbox. GPIO Alert Output (Raspberry Pi only) ---------------------------------------- On a Raspberry Pi, JS8Reporter can drive a GPIO pin to signal an active ALERT to external hardware — for example, a warning light or a buzzer wired to the pin. How it works: - The configured GPIO pin goes HIGH when an ALERT is detected. - The pin returns LOW when the alert is cancelled (by clicking "Cancel Alert" or by marking the ALERT record as invalid). To enable: Settings > Preferences… > Filters tab > GPIO Alert Output section Check: "Drive a GPIO pin HIGH while an ALERT is active" Enter the BCM pin number to use (default: 17) Click OK, then restart JS8Reporter for the change to take effect. Pin numbering: The pin number uses Broadcom (BCM) numbering, not physical board pin numbers. BCM 17 is physical pin 11 on the 40-pin header. Refer to a Raspberry Pi GPIO pinout diagram for other options. Hardware wiring note: GPIO pins source 3.3 V at low current. For driving an LED directly, use a current-limiting resistor (typically 330 Ω). For higher-current devices (buzzers, relays), use a transistor or a relay module rated for 3.3 V logic. Permission requirement: The user running JS8Reporter must be a member of the "gpio" group. On a standard Raspberry Pi OS installation with the default user, this is already the case. If you see a "GPIO Unavailable" warning at startup, see Section 17 (Troubleshooting) for instructions. This feature is not available on Windows or non-Raspberry Pi Linux systems. The GPIO section does not appear in Settings on those platforms. If RPi.GPIO is not installed: The GPIO Alert Output section still appears on Raspberry Pi hardware, but the controls are replaced by a message: "RPi.GPIO not found — install it to enable GPIO output: pip install RPi.GPIO" Install the package (or use the apt method in Section 17) and restart JS8Reporter to make the controls appear. ================================================================================ 13. REPORTS ================================================================================ The Reports menu generates analytical text reports from the currently visible assessments (respecting the active Date Filter and Circle Filter). All reports open in a viewer window with: - Full scrollable text display - Save to Export Folder button (saves automatically with a timestamp) - Save As… button (choose any location) - Close button The report header shows which filters were active when the report was generated. Report Descriptions -------------------- Area Assessment Summary The primary summary table showing category averages for each reporting station, with Min / Max / Avg columns. This is the same table shown in the Assessment Detail / Summary Table panel. Full Detail Report Complete field-by-field detail for every visible assessment, formatted for printing or filing. Score Rankings All stations sorted from worst to best overall average score. Useful for quickly identifying the most severely affected areas. Category Focus (submenu) Select any of the eight MCF505 categories to see all stations' field-level scores for that category only. Stations are sorted worst to best for that category. Categories available: Water Sewage/Waste Power Communications Economy Transportation Health/Safety Social/Political Alert Records Lists only the assessments that contain an ALERT, with full detail for each. Shows "No ALERT records found" if none are present. Geographic Summary Assessments grouped and subtotaled by state, sorted alphabetically. Useful for briefing by jurisdiction. Critical Infrastructure Lists every infrastructure field (1–32) that has been scored 0 (Destroyed) or 1 (Severely Impaired) by any station. Sorted by field number, showing which stations reported each critical condition. Trend Analysis Shows only stations that submitted assessments on more than one date, with scores for each date and an arrow (↑ / ↓ / →) indicating the direction of change. Useful for tracking whether conditions are improving or deteriorating. Infrastructure Heat Map For each category, shows how many field scores fall at each level (0 / 1 / 2 / 3 / N/A), with percentages. Gives a quick overview of the overall distribution of conditions. Data Quality / Coverage Lists each station with the number of fields reported, the completion percentage, and the age of the assessment in days. Useful for identifying incomplete or outdated reports. Worst Conditions Ranks stations by their single worst category average score (lowest first). Highlights where the most severe problems are concentrated. Network Coverage Lists all reporting grid squares with their latitude/longitude coordinates and the date of their most recent assessment. Sorted north-to-south, west-to-east. Useful for mapping network coverage. F!104 Summary Lists all currently-filtered F!104 Situation Report records in a compact table: callsign, grid square, status (code and label), and filed date. Records with an active alert are marked with "!". Respects the active Date Filter and Circle Filter. ================================================================================ 14. EXPORTING DATA ================================================================================ 14.1 Save Text Report (File > Save Text Report… Ctrl+S) ----------------------------------------------------------- Saves a combined text file containing the Area Assessment Summary table followed by the full detail for every visible assessment. 14.2 Export F505 Data (File > Export F505 Data (CSV/TSV)… Ctrl+T) ---------------------------------------------------------------------- Exports all visible F!505 assessments as a CSV or TSV file with one row per assessment. Columns include callsign, grid, state, timestamps, all category averages, and all 32 individual field scores. The format (CSV or TSV) is set in Settings > Export. 14.3 Export Map Image (File > Export Map Image… Ctrl+E) ---------------------------------------------------------- Saves the current map view as an image file. Supported formats: PNG (default), JPEG, SVG. The format is set in Settings > Export. 14.4 Export as F505 (File > Export as F505…) --------------------------------------------------------------- Saves all currently loaded and visible assessments to a plain-text file in the same F505 format as originally received — either the over-the-air JS8Spotter message text, or the format used when importing via File > Import F505 File…. Purpose: compile received F505 reports and transfer them to another operator so they can import the file into their copy of JS8Reporter using File > Import F505 File…. The exported file contains one F505 record per line and can be re-imported directly. The currently active Date Filter and Circle Filter are respected — only visible assessments are included. The file is saved to the default export folder unless you choose a different location in the Save dialog. 14.5 Export as F104 (File > Export as F104…) ---------------------------------------------- Saves all currently visible F!104 Situation Report records to a plain-text file (one record per line in the over-the-air F!104 format). Useful for transferring records to another operator. 14.6 Export Flag Pins (File > Export Flag Pins…) --------------------------------------------------- Saves all current flag pins to a .flags.json file in the sitrep_flags format, interoperable with MHGridMapper. The station callsign (Settings > General) is written as the created_by field. This option is also available via the Export button in the View > Flag Pins… dialog. 14.7 Export Folder -------------------- Report viewer windows include a "Save to Export Folder" button that saves the report automatically to the designated export folder with a timestamp-based filename (no dialog required). The default export folder is: /data/exports/ A custom export folder can be set in Settings > Export > Default export folder. ================================================================================ 15. SETTINGS ================================================================================ Open via Settings > Preferences… General Tab ----------- Station callsign: Your amateur radio callsign. Stored in settings and written to the created_by field of every flag pin export file, so recipients know which station produced the SitRep flag set. Pin Colors Tab -------------- Pin color mode: Controls what score drives the color of each map pin. Options: Lowest all fields, Average all fields (default), Average in category, Lowest in category. Category: The category used when a category-specific pin color mode is selected. Rounding for averages: How averaged scores are rounded to a whole-number color level. Options: Standard rounding (default), Always round up, Always round down. Map pin labels: When checked, each pin shows the callsign and score. When unchecked, only the color pin is shown (click to see details). Filters Tab ----------- Duplicate grid-square handling: When two assessments share the same grid square, use only the most recent (default) or average the scores. Category display filter: Limit the map and reports to selected categories only. Leave all checked (default) to include all categories. Time Lapse mode: Rolling Window (default), Cumulative, or Snapshot. See Section 11. Rolling window days: Number of days in the rolling window (default: 14). Alert enabled: Enable or disable ALERT detection. GPIO Alert Output (Raspberry Pi only — section visible only on Pi): Enable or disable GPIO pin output during an active ALERT. BCM pin number: the Broadcom pin number to drive (default: 17). Changes take effect after restarting JS8Reporter. If RPi.GPIO is not installed, the controls are replaced by an install hint; see Section 12 for full details, wiring notes, and permissions. Circle Tab ---------- Circle center latitude and longitude, and radius in miles. These can also be set by clicking on the map (Circle > Set Circle Center…) or via Circle > Configure Circle…. Export Tab ---------- Map image format: PNG (default), JPEG, SVG. Tabular data export format: CSV (default) or TSV. Default export folder: Folder used by "Save to Export Folder" in report windows. Leave blank to use the default data/exports/ folder. Click Browse… to select a folder. Import Records folder: Folder scanned by File > Import All Files from Folder…. Leave blank to use the default data/imports/ folder. Click Browse… to select a folder. Auto-Update Tab --------------- Check for updates on startup: When enabled, JS8Reporter checks SitRepNet.com for a newer release at startup (requires internet). Offline operation is never affected. Version check URL: The URL used for version checks. Defaults to the SitRepNet.com JS8Reporter download page. Leave blank to disable. Tools Menu ---------- The Tools menu provides utility functions not specific to data loading or export: Grid Converter… Opens the Grid Converter dialog. See Section 7.6. ================================================================================ 16. KEYBOARD SHORTCUTS ================================================================================ Escape Exit Pan or Zoom map mode; dismiss right-click context menus Delete Mark selected assessment as invalid / restore if invalid + or = (in date field) Advance date by one day - (in date field) Move date back by one day Left (Time Lapse) Step back one date Right (Time Lapse) Step forward one date ================================================================================ 17. TROUBLESHOOTING ================================================================================ Setup / Installation Problems ------------------------------ For problems related to setup — missing packages, missing map data, desktop icon not appearing, or "virtual environment not found" errors — see the troubleshooting section in: Installation_Guide.txt No assessments loaded from the database ----------------------------------------- Use Help > DB Diagnostic… to inspect the database. JS8Reporter looks for rows in the "forms" table with typeid containing "505". Verify that JS8Spotter has received and stored at least one MCF505 form. Common causes: - The database file selected is not a JS8Spotter database - No MCF505 forms have been received yet - The forms were stored under an unexpected typeid value (the diagnostic will show what typeids are present) No F!104 pins appear after opening the database ------------------------------------------------- F!104 records are loaded automatically alongside F!505 records when a database is opened. If no diamonds appear: - Confirm View > Show F!104 Pins has a checkmark. - Verify the database contains F!104 records: use Help > DB Diagnostic… and check for a typeid value of "F!104". - Confirm the active Date Filter includes the dates of those records. - If the records arrived recently, wait up to one minute for the automatic background poll to pick them up, or use View > Refresh Map to force an immediate update. Map pins appear but in the wrong location ------------------------------------------ The grid square field in the assessment may contain an invalid or unusual grid locator. Select the assessment and check the Grid field in the detail panel. Date filter is not showing expected assessments ------------------------------------------------ Verify the From and To dates are entered correctly in YYYY/MM/DD format. Check that the Enable checkbox is checked and Apply was pressed. Also check whether the assessment's date falls in the filter range. The filter uses the received date if available, otherwise the report prepared date. Time Lapse starts but the map does not change ---------------------------------------------- If only one unique date is present in the visible assessments, Time Lapse has nothing to step through. Try disabling the Date Filter or expanding the date range. Auto-update check fails silently ---------------------------------- The update check runs in the background and fails silently if the network is unavailable. This is by design — offline operation is never affected. To disable the check entirely: Settings > Preferences > Auto-Update > uncheck "Check for updates on startup". GPIO controls not visible in Settings > Preferences… > Filters tab (Raspberry Pi) ----------------------------------------------------------------------------------- The GPIO Alert Output section is shown on Raspberry Pi hardware but the controls are replaced by a red message if RPi.GPIO is not installed. To install RPi.GPIO: Option 1 — pip (inside the JS8Reporter virtual environment): ~/js8reporter/venv/bin/pip install RPi.GPIO --ignore-installed Note: plain "pip install RPi.GPIO" may report "Requirement already satisfied" even though the package is not inside the venv. The --ignore-installed flag forces it to install correctly. Option 2 — apt (system-wide): sudo apt install python3-rpi.gpio After installing, restart JS8Reporter. The controls will appear. "GPIO Unavailable" warning at startup (Raspberry Pi) ------------------------------------------------------ JS8Reporter displays this warning when GPIO alert output is enabled in Settings but the GPIO pin could not be initialized. Most common cause: the user running JS8Reporter is not a member of the "gpio" group. To fix: 1. Open a terminal and run: sudo usermod -aG gpio (replace with your actual username) 2. Log out and log back in, or reboot, for the group change to take effect. 3. Restart JS8Reporter. To verify group membership before restarting: groups The word "gpio" should appear in the output. If the warning persists after adding the user to the gpio group and logging back in, confirm that RPi.GPIO is installed: /home//js8reporter/venv/bin/python3 -c "import RPi.GPIO" If that command reports an error, see the entry above for install steps. ================================================================================ End of JS8Reporter User Manual JS8Reporter is designed and developed by Stephen Clay McGehee, KN4AM Coding done using Claude Code AI See SitRepNet.com for more information ================================================================================