================================================================================
SitRepNet Scheduler v1.0.0 – User Manual

Designed and developed by Stephen Clay McGehee, KN4AM
Coding done using Claude Code AI
See SitRepNet.com for more information
================================================================================


OVERVIEW
--------
SitRepNet Scheduler lets a station monitor one frequency — the primary
frequency — in JS8Call or FLDIGI, and switch automatically to other
frequencies at scheduled times to receive bulletins or join nets. When a
scheduled window ends, it puts the program back exactly as it was just
before the switch: frequency, audio offset, and JS8Call speed or FLDIGI
mode.

Key capabilities:
  - Weekly schedule: each entry is one day of the week and a start time,
    in UTC or local time
  - JS8Call entries set frequency, offset and speed; FLDIGI entries set
    frequency, offset and mode
  - Optional early start: switch a few minutes before the official start
  - Returns to primary automatically, even if the Scheduler or computer
    was restarted in the middle of a window
  - Never switches or returns in the middle of a transmission — it waits
    for the transmission to finish
  - Overlap warnings when entering the schedule
  - Copy an entry to other days of the week
  - Copy the schedule table to the clipboard to paste into a document or
    spreadsheet and print
  - Works with the standard JS8Call and the JS8Call-improved fork

More Information:  SitRepNet.com


CONTENTS
--------
  Launching the Program
  The Main Window
  Primary and Scheduled
  Adding a Schedule Entry
  How Days and Times Work
  Early Start
  Overlapping Entries
  Copy to Other Days
  Copy Table
  Controls: Return to Primary, Pause, Test
  What Happens When Things Go Wrong
  Settings
  Auto-Update
  Menu Reference
  Configuration Files
  Troubleshooting


LAUNCHING THE PROGRAM
----------------------
From the desktop:
  Double-click the SitRepNet Scheduler icon.

From the terminal:
  python3 /home/<username>/sitrepnetscheduler/main.py

See SitRepNetScheduler_Installation_Guide.txt for installing, and for
setting up JS8Call or FLDIGI so the Scheduler can control them.

Only one copy of the Scheduler can run at a time.


THE MAIN WINDOW
----------------
From top to bottom:

Status panel
  - Which program is being controlled and whether it is connected, e.g.
    "JS8Call at 127.0.0.1:2442 — connected". NOT CONNECTED shows in red.
  - The clock, top right: local time with its zone, and UTC, e.g.
        Wed 14:16:33 local (EDT, UTC-4)   Wed 18:16:33 UTC
  - The state line — ON PRIMARY, ON SCHEDULE, etc. See PRIMARY AND
    SCHEDULED below.
  - Now: the program's current frequency, offset and speed or mode, read
    from the program every 15 seconds and right after each switch.
  - Next: the next scheduled switch, in local time and UTC, with a
    countdown.
  - Buttons: Return to Primary, Pause Scheduling, Test Selected Entry Now.

Schedule table
  One row per entry. Columns: ⚠ (overlap marker), Day, Start (local),
  Start (UTC), Early, Duration, Name, Program, Freq (MHz), Speed/Mode,
  Offset, Enabled.

  - Sort by (top right of the table): "Day and time" (Monday to Sunday)
    or "Next date" (soonest first).
  - Entries for the program that isn't selected in Settings, and disabled
    entries, are shown in grey. They are kept but don't run.
  - ⚠ marks an entry that overlaps another. Hover over it to read the
    warning.
  - Start (local) and Start (UTC) are for the entry's next date, so they
    shift by an hour when daylight saving starts or ends.
  - Double-click a row to edit it. Press Delete to delete it.

  Buttons under the table: Add, Edit, Duplicate, Delete, Enable/Disable,
  Copy to Other Days, and Copy Table.

Activity
  What the Scheduler has done, with times in UTC: switches, returns to
  primary, connection lost and regained, warnings and errors. The same
  lines go to scheduler.log (see CONFIGURATION FILES).


PRIMARY AND SCHEDULED
----------------------
The primary settings are whatever the program is set to just before a
scheduled switch — normally the frequency you monitor. The Scheduler
saves them at the moment it switches and puts them back when the window
ends. You don't enter the primary frequency anywhere; if you change your
monitoring frequency by hand, that becomes the primary for the next
switch.

The state line in the status panel shows:

  ON PRIMARY (green)
      No scheduled window is running.

  ON SCHEDULE: "State SitRep" until Wed 19:30 local / Wed 23:30 UTC —
  will return to 7.078 MHz, offset 2300 Hz, Normal (orange)
      A scheduled window is running. Shows when it ends and exactly what
      it will return to.

  SWITCHING… / RETURNING TO PRIMARY… (orange)
      A change is in progress, or the Scheduler is waiting for a
      transmission to finish first.

  RETURN TO PRIMARY FAILED — retrying (red)
      The window has ended but the primary settings couldn't be put back
      (for example, JS8Call was closed). It keeps trying every 30 seconds.
      See WHAT HAPPENS WHEN THINGS GO WRONG.

  (scheduling PAUSED) is added to any of these while scheduling is paused.

Back-to-back windows: if a second entry starts while the first is still
running (or right as it ends), the Scheduler goes straight from one to
the other and returns to the ORIGINAL primary settings at the end — it
never mistakes the first bulletin frequency for the primary.


ADDING A SCHEDULE ENTRY
------------------------
Schedule > Add Entry…, or the Add button. Fields:

  Name          Up to 60 characters, e.g. "State SitRep Bulletin".

  Program       JS8Call or FLDIGI. Only entries for the program selected
                in Settings > Program run.

  Day (local)   One day of the week — always your LOCAL day, even for a
                UTC start time. See HOW DAYS AND TIMES WORK. For the same
                schedule on several days, save one entry and use Copy to
                Other Days.

  Start time    HH:MM, 24-hour, with UTC or Local.

  Switch        "At start time", or N minutes before the start time
                (up to 120). See EARLY START.

  Duration      Minutes after the start time (up to 1440, i.e. 24
                hours). The window ends at start time + duration, however
                early it started.

  Frequency     Dial frequency in MHz, e.g. 7.078.

  Speed         JS8Call: Normal, Fast, Turbo or Slow.
  Mode          FLDIGI: the mode name. The list comes from FLDIGI itself
                when it is running; otherwise type the name exactly as
                FLDIGI shows it (e.g. OLIVIA-8-250, BPSK31).

  Offset        Audio offset in Hz (0–5000).

  Notes         Anything you like; not used by the program.

  Enabled       Untick to keep an entry without running it.

The Next dates box at the bottom shows the next three times the entry
will run, in local time and UTC, including the early switch time and the
end time. Check it before relying on a new entry, especially one in UTC.

Save checks the entry for overlaps with your other entries (see
OVERLAPPING ENTRIES) and saves the schedule.

Duplicate opens the editor on a copy of the selected entry (named
"… (copy)"), so you can change its day or time before saving.


HOW DAYS AND TIMES WORK
------------------------
Nets usually name the local day even when they give the time in UTC. A
"Monday night" net at 02:00 UTC is actually Tuesday in UTC, but Monday
evening in US local time.

So the rule is: the day is always your local day, and the start time is
read in the time basis you choose (UTC or Local). An entry set to
"Monday, 02:00 UTC" for a US Eastern station runs on Monday evening local
time — 22:00 EDT in summer, 21:00 EST in winter.

  - Local entries stay at the same local time all year.
  - UTC entries stay at the same UTC time all year, so their local time
    moves by an hour when daylight saving changes.
  - On the day daylight saving starts, a local time that doesn't exist
    (e.g. 02:30 when clocks jump from 02:00 to 03:00) is skipped that
    week, and logged. On the day it ends, a local time that happens twice
    runs once, the first time.

The Next dates preview in the entry editor shows exactly when each entry
will run.

If the computer's clock is set to UTC (common on a Raspberry Pi), choose
your own zone in Settings > Time Zone so that "local" means your local
time. Changing the zone can move UTC entries to a different local day —
check the table afterwards.


EARLY START
-----------
"Switch N minutes before start" moves the switch earlier, so the program
is already listening when the bulletin begins (or so you can check in
early to a net). The window still ends at start time + duration.

The early start never cuts into another entry's window — see below.


OVERLAPPING ENTRIES
--------------------
When you save or enable an entry, the Scheduler compares it with your
other enabled entries for the same program over the coming year, and
warns you about two kinds of overlap:

  Full overlap — the later entry's start time falls inside the earlier
  entry's window. At the later entry's start time the Scheduler switches
  to it, ending the earlier one early. Example warning:

      "Region Net" overlaps "State SitRep" on Monday: "State SitRep" runs
      until Mon 22:30 local / Tue 02:30 UTC, and "Region Net" starts at
      Mon 22:15 local / Tue 02:15 UTC. "Region Net" will take over at its
      official start time and end "State SitRep" early.

  Early-start overlap — only the early start falls inside the earlier
  window. The later entry will NOT start early; it switches at its
  official start time instead. If it needs to start early, change its
  time or the other entry's duration.

If an overlap happens on only some dates (a UTC entry and a local entry
can overlap only part of the year, as daylight saving moves one against
the other), the warning says on which dates.

Choose "Save anyway" to keep the entry as it is, or "Go back and edit".
Overlapping entries are marked ⚠ in the table; hover over the mark to
read the warning again.

Only entries for the same program are compared, since only one program
is controlled at a time.


COPY TO OTHER DAYS
-------------------
Select an entry and choose Copy to Other Days…. Tick the days to copy it
to (or use the Weekdays, Weekend, All or None buttons), then Create.

  - Each day becomes its own independent entry with the same settings, so
    any day can be changed later on its own.
  - The copies are named with the day, e.g. "State Net (Thu)". Copying an
    entry that already has a day in its name replaces it rather than
    adding another.
  - A day that already has an entry for the same program, time and
    frequency is skipped, and you're told which.
  - Any overlaps the new copies cause are shown together in one warning.


COPY TABLE
-----------
Copy Table… puts the schedule on the clipboard, to paste into a document
and print, or into a spreadsheet.

  Format
    Aligned text — columns lined up with spaces. Paste into a document
    and set the pasted text to a monospace font (e.g. Courier New,
    DejaVu Sans Mono, Liberation Mono) so the columns line up.
    Tab-separated — pastes into a spreadsheet as a table, or into a word
    processor, where Table > Convert Text to Table makes a real table.

  Entries
    All programs, or only the selected program. Disabled entries are
    left out unless "Include disabled entries" is ticked.

The copied text starts with a heading giving the date and time, your time
zone, and which entries are included. Overlapping entries are marked
"(!)" with a footnote, since ⚠ may not print well. Your choices are
remembered for next time.


CONTROLS: RETURN TO PRIMARY, PAUSE, TEST
-----------------------------------------
Return to Primary (Control menu, or the button)
    Ends the current scheduled window now and puts the primary settings
    back. The Scheduler stays on primary for the rest of that window;
    later entries run as normal.

Pause Scheduling / Resume Scheduling
    While paused, no new windows start. A window already running carries
    on to its end and then returns to primary. Pausing is not remembered
    when the Scheduler is restarted.

Test Selected Entry Now…
    Switches to the selected entry's settings right away, for the number
    of minutes you choose (1–60), then returns to primary. Use it to check
    that an entry's frequency, offset and speed or mode work before its
    real time comes round. It works even while scheduling is paused.
    If a scheduled window is running when the test ends, the Scheduler
    goes straight on to that window.


WHAT HAPPENS WHEN THINGS GO WRONG
----------------------------------
Transmitting at switch time
    The Scheduler never changes frequency in the middle of a
    transmission. It waits for the transmission to finish (JS8Call: until
    8 seconds after the last frame). At switch time it waits up to the
    limit in Settings > Timing (default 5 minutes), then skips that
    window. When returning to primary it waits up to the same limit, then
    returns anyway.

The program isn't running at switch time
    About a minute before each switch, the Scheduler checks that the
    program is connected, and logs a warning if it isn't — time to start
    it. If it still can't connect at switch time, it keeps trying every
    30 seconds for as long as the window lasts. The first failure is
    logged in full; after that, a "Still could not switch…" line every 10
    minutes rather than every 30 seconds.

A switch only partly works
    For example, the frequency changes but the speed doesn't, because the
    program is still starting up. The Scheduler says what didn't take and
    tries again every 30 seconds while the window lasts, then logs
    "Switch to … now complete" when it works.

The program is closed during a window
    Activity shows "Lost the connection to …". When the window ends, the
    Scheduler can't return to primary until the program is running again,
    so it shows RETURN TO PRIMARY FAILED and keeps trying every 30
    seconds. As soon as the program is back, it returns to primary.

The Scheduler is closed, or the computer restarts, during a window
    If you close the Scheduler during a window, it asks whether to return
    to primary first:
      Yes — returns to primary now, then closes.
      No — leaves the program on the scheduled settings. The primary
           settings are kept in state.json and put back the next time the
           Scheduler starts.
    If the Scheduler or computer stops without being closed (a crash or
    power cut), state.json still holds the primary settings. On the next
    start, the Scheduler logs what happened and either stays on the
    window until it ends (if it is still running) or returns to primary
    straight away.

The computer was asleep, or the Scheduler started late
    Activity shows "No activity for N min (computer asleep?)". If a window
    is in progress, the Scheduler joins it, as long as at least the time
    in Settings > Timing (default 2 minutes) remains; otherwise it skips
    it.

The connection settings or time zone are changed during a window
    The Scheduler asks to return to primary first, since the new settings
    would change what it controls or when windows run.


SETTINGS
--------
Settings > Settings… opens a dialog with four tabs. OK saves; Cancel
discards.

Program tab
    Program to control: JS8Call or FLDIGI. Only entries for this program
    run.
    Host and port for each program, with a Test button that connects and
    shows the program's current frequency, offset and speed or mode.
    Defaults: JS8Call 127.0.0.1 port 2442; FLDIGI 127.0.0.1 port 7362.
    Changing these reconnects straight away.

Timing tab
    Wait for transmitting to finish, up to … seconds (default 300).
        At switch time a window is skipped after this long; when
        returning to primary it goes ahead anyway.
    Join a window already in progress if at least … minutes remain
        (default 2).
    Check the program is connected … seconds before a switch
        (default 60).

Time Zone tab
    Local time zone. Normally "Use the computer's setting". For a
    computer whose clock is set to UTC, pick your own zone from the list,
    or type the city (e.g. New York). The tab shows the computer's own
    setting and the local time with the chosen zone, so you can check it.
    Local-time entries, every entry's day of the week, and the times
    shown on screen all follow this zone, including daylight saving.
    Usually greyed out on Windows, which keeps its clock on local time
    anyway.

Auto-Update tab
    Check for updates on startup (default on). See AUTO-UPDATE.


AUTO-UPDATE
-------------
On startup (if enabled in Settings > Auto-Update), the Scheduler checks
SitRepNet.com in the background for a newer version. If there is one, a
dialog offers to open the download page; if not, or if the check fails
(no internet), nothing is shown — offline operation is never affected.

Settings > Check for Updates Now runs the same check on demand and always
reports a result. Nothing is ever downloaded or installed automatically —
you download and install the new version yourself (see "Updating from an
older version" in the Installation Guide).


MENU REFERENCE
---------------
File
    Exit                          Close the Scheduler (asks about
                                  returning to primary if a window is
                                  running).

Schedule
    Add Entry…                    New entry.
    Edit Entry…                   Edit the selected entry.
    Duplicate Entry…              Edit a copy of the selected entry.
    Delete Entry                  Delete the selected entry (asks first).
    Enable/Disable Entry          Turn the selected entry on or off.
                                  Enabling checks for overlaps.
    Copy to Other Days…           See COPY TO OTHER DAYS.
    Copy Table…                   See COPY TABLE.

Control
    Return to Primary             End the current window now.
    Pause / Resume Scheduling     Stop or restart new windows.
    Test Selected Entry Now…      Try an entry for a few minutes.

Settings
    Settings…                     See SETTINGS.
    Check for Updates Now         See AUTO-UPDATE.

Help
    About                         Version and credits.


CONFIGURATION FILES
--------------------
Everything is kept in:
  Linux / Raspberry Pi:  ~/.config/sitrepnetscheduler/
  Windows:               C:\Users\<username>\.config\sitrepnetscheduler\

  config.json      Settings and window position. Deleting it resets the
                   settings to their defaults; the schedule is not
                   affected.
  schedule.json    The schedule. Back it up by copying this file. If it
                   can't be read when the Scheduler starts, the
                   Scheduler says so and won't overwrite it — fix or
                   remove the file, then restart. Individual damaged
                   entries are skipped, and entries with impossible
                   values are loaded disabled; either way you're told.
                   If any were skipped, a copy of the original file is
                   saved as schedule.json.bak.
  state.json       Exists only during a scheduled window: the primary
                   settings to return to. Don't delete it while a window
                   is running.
  scheduler.log    The activity log, with times in UTC. Rotated at 1 MB,
                   keeping three older copies (scheduler.log.1 to .3).
  scheduler.lock   Used to stop a second copy from running. Harmless;
                   it may stay after the Scheduler closes.


TROUBLESHOOTING
----------------
The status panel says NOT CONNECTED
    Start JS8Call or FLDIGI, and check Settings > Program > Test. See the
    Installation Guide, section 5, for the settings JS8Call needs.

"Next:" says no entries are scheduled
    Check that your entries are for the program selected in Settings >
    Program, and that they are enabled (not grey).

An entry runs on the wrong day or at the wrong time
    Open it and look at Next dates. Check that the clock in the top right
    shows the right local time — if not, see Settings > Time Zone.
    Remember the day is always the local day, even for UTC times.

The radio didn't change frequency, but the Activity log says it switched
    Rig control (CAT) in JS8Call or FLDIGI isn't working; the Scheduler
    can only ask them to change.

Something unexpected happened
    Look at the Activity pane and scheduler.log (see CONFIGURATION
    FILES). Unexpected errors are written there in full, which helps when
    reporting a problem.


================================================================================
  End of User Manual
================================================================================
