================================================================================
SitRepNet Scheduler v1.0.0 – Installation Guide

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


UPDATING FROM AN OLDER VERSION
-------------------------------
  Already have SitRepNet Scheduler installed? Updating uses the same steps
  as a fresh install (Section 2 or 3 below) — just extract the new ZIP
  into your existing sitrepnetscheduler folder instead of a new one,
  overwriting files when prompted, then restart the program. There is no
  separate update package or procedure.

  Close the Scheduler before updating. If it is in the middle of a
  scheduled window when you close it, answer Yes to "Return to primary
  before closing?" so the radio is back on its primary frequency.

  Nothing else to do first:
    - Your schedule and settings are stored in your config folder
      (~/.config/sitrepnetscheduler/ on Linux/Raspberry Pi,
      C:\Users\<username>\.config\sitrepnetscheduler\ on Windows), not
      the program folder, so they are never touched by extracting the ZIP.

  See SitRepNetScheduler_CHANGELOG.txt for what's new in this version.


TABLE OF CONTENTS
-----------------
  1.  System Requirements
  2.  Installation: Linux / Raspberry Pi
  3.  Installation: Windows
  4.  The Desktop Launcher (Linux / Raspberry Pi)
  5.  Setting Up JS8Call and FLDIGI
  6.  Starting the Program
  7.  Troubleshooting


================================================================================
1.  SYSTEM REQUIREMENTS
================================================================================

Supported Platforms
-------------------
  - Raspberry Pi 4B / 5 running Raspberry Pi OS Bookworm or Bullseye
    (primary)
  - Linux (Ubuntu, Debian, Fedora and derivatives)
  - Windows 10 / 11

Python Version
--------------
  Python 3.9 or newer is required.

  Check your version:
      python3 --version       (Linux / Raspberry Pi)
      python  --version       (Windows)

Python Packages
---------------
  None. SitRepNet Scheduler uses only Python's standard library — there
  is nothing to install with pip.

  Tkinter is required. It is pre-installed on Windows, Raspberry Pi OS and
  most Linux desktops. See Troubleshooting (Section 7) if it is missing.

Radio Software
--------------
  JS8Call or FLDIGI, with rig control (CAT) set up so that the program
  can change the radio's frequency. The Scheduler tells JS8Call or FLDIGI
  what frequency to use; JS8Call or FLDIGI tells the radio.

  JS8Call: both the standard JS8Call (2.2 or newer) and the
  JS8Call-improved fork (3.0 or newer) are supported. Tested with
  JS8Call-improved 3.0.3.
  FLDIGI: tested with FLDIGI 4.2.13.

  The Scheduler controls one program at a time — whichever is selected
  in Settings > Program.

Internet Connection
-------------------
  Not required. The only thing that uses the internet is the optional
  check for updates (Settings > Auto-Update), and it is silent when
  there is no connection.


================================================================================
2.  INSTALLATION: LINUX / RASPBERRY PI
================================================================================

Step 1 — Copy the program files
---------------------------------
  Extract the ZIP. It contains a single folder, sitrepnetscheduler.
  The recommended location for a single-user installation is the home
  directory:

      /home/<username>/sitrepnetscheduler

  For a system-wide installation accessible to all users, use:

      /opt/sitrepnetscheduler

  Either location works; the launcher script in Step 3 finds the folder
  on its own.

Step 2 — Make sure Tkinter is installed
-----------------------------------------
  Raspberry Pi OS usually has it already. On Ubuntu/Debian, if it isn't:

      sudo apt update
      sudo apt install python3-tk

  On Fedora and other RPM-family distros:

      sudo dnf install python3-tkinter

Step 3 — Install the desktop launcher
---------------------------------------
  See Section 4 for full details on the desktop launcher.

  From the program folder, run:
      cd ~/sitrepnetscheduler        (or cd /opt/sitrepnetscheduler)
      sh make_launcher.sh

  It adds SitRepNet Scheduler to the application menu and puts its clock
  icon on the Desktop.

Step 4 — Set up JS8Call or FLDIGI
-----------------------------------
  See Section 5.

Step 5 — Check the time zone
------------------------------
  The Scheduler needs to know your local time zone, because entries are
  scheduled on your local day of the week. Many Raspberry Pis have their
  clock set to UTC. If yours is, either:
    - set the Pi's own time zone (Raspberry Pi menu > Preferences >
      Raspberry Pi Configuration > Localisation > Set Timezone), or
    - leave the Pi on UTC and choose your zone in the Scheduler's
      Settings > Time Zone.
  The clock at the top right of the main window shows local time and UTC
  side by side, so you can confirm it's right.


================================================================================
3.  INSTALLATION: WINDOWS
================================================================================

Step 1 — Install Python
-------------------------
  If Python is not already installed, download it from python.org.
  During installation, check the box labeled "Add Python to PATH."

  Verify the installation:
      python --version

Step 2 — Copy the program files
---------------------------------
  Extract the ZIP to a convenient location, for example:

      C:\Users\<username>\sitrepnetscheduler

Step 3 — Create a desktop shortcut
-------------------------------------
  1. Right-click the Desktop and select New > Shortcut.
  2. In the Location field, enter (adjust the path to match your install):
         pythonw "C:\Users\<username>\sitrepnetscheduler\main.py"
     (pythonw runs the program without leaving a black console window
     open. Use python instead if you want to see the console.)
  3. Click Next, name it "SitRepNet Scheduler", and click Finish.
  4. To add the icon: right-click the shortcut > Properties > Change Icon…,
     browse to:
         C:\Users\<username>\sitrepnetscheduler\assets\icon.ico

Step 4 — Set up JS8Call or FLDIGI
-----------------------------------
  See Section 5.

  Windows normally keeps its clock on local time, so the Settings > Time
  Zone option isn't needed on Windows (and is usually greyed out there,
  since Python on Windows has no time zone list of its own).


================================================================================
4.  THE DESKTOP LAUNCHER (LINUX / RASPBERRY PI)
================================================================================

The Launcher Script
---------------------
  make_launcher.sh, in the program folder, creates the launcher for
  wherever the program is installed:

      sh make_launcher.sh

  It writes ~/.local/share/applications/sitrepnetscheduler.desktop, which
  makes SitRepNet Scheduler appear in the application menu (under
  Accessories or Other, or Hamradio on desktops that have that
  category), and copies it to ~/Desktop/ as a clickable icon (only if
  ~/Desktop/ exists), marked executable and trusted. Run it again if you
  move the program folder.

Installing the Launcher by Hand
---------------------------------
  The file sitrepnetscheduler/sitrepnetscheduler.desktop is
  pre-configured for an installation at /opt/sitrepnetscheduler. If you
  installed somewhere else, edit the Exec= and Icon= lines first:

      Exec=/usr/bin/python3 /home/<username>/sitrepnetscheduler/main.py
      Icon=/home/<username>/sitrepnetscheduler/assets/icon.png

  Then copy it to ~/.local/share/applications/ and ~/Desktop/, and run:
      chmod +x ~/Desktop/sitrepnetscheduler.desktop
      update-desktop-database ~/.local/share/applications

Starting Automatically at Login (optional)
--------------------------------------------
  To have the Scheduler start every time you log in, also copy the
  .desktop file to ~/.config/autostart/:
      mkdir -p ~/.config/autostart
      cp ~/.local/share/applications/sitrepnetscheduler.desktop \
          ~/.config/autostart/
  JS8Call or FLDIGI can start before or after it; the Scheduler keeps
  trying to connect and logs "Connected to …" when it does.

If the Desktop Icon Did Not Appear
-------------------------------------
  1. Verify the Exec= path in the .desktop file points to your actual
     installation location and that main.py exists there. Running
     sh make_launcher.sh again from the program folder fixes the paths.

  2. Mark the Desktop copy as executable:
         chmod +x ~/Desktop/sitrepnetscheduler.desktop

  3. Some desktops refuse to run a .desktop file until it is marked
     trusted. Right-click the Desktop icon and look for "Allow Launching",
     or run:
         gio set ~/Desktop/sitrepnetscheduler.desktop metadata::trusted true

  4. Try logging out and back in to force a full desktop refresh.

Running Without a Desktop Icon
--------------------------------
  The Scheduler can always be launched from a terminal:

      python3 /home/<username>/sitrepnetscheduler/main.py


================================================================================
5.  SETTING UP JS8CALL AND FLDIGI
================================================================================

Both programs must already be able to change the radio's frequency —
that is, rig control (CAT) is set up and working. Check by changing the
frequency in JS8Call or FLDIGI by hand and watching the radio follow.

JS8Call (standard or JS8Call-improved)
----------------------------------------
  In JS8Call, open File > Settings > Reporting and set:
    - "Enable TCP Server API" — on
    - "Accept TCP Requests" — on. Without this, JS8Call silently ignores
      every request, and the Scheduler can read nothing and change
      nothing.
    - TCP server port — 2442 (the default). If you use a different port,
      enter the same one in the Scheduler's Settings > Program.
    - "TCP Max Connections" — raise it if other programs also use the
      JS8Call API (JS8Spotter, SitRepMapper's Send feature, etc.). The
      Scheduler keeps one connection open all the time, so allow at least
      one more than the number of other programs you run.

  JS8Call-improved only: if its WSJT-X protocol option is set to the same
  server and port as its UDP server, it stops answering frequency
  requests. Give them different ports.

FLDIGI
-------
  FLDIGI's XML-RPC control is always on, on port 7362 unless FLDIGI was
  started with a different --xmlrpc-server-port. Nothing to change in
  FLDIGI itself, apart from rig control (Configure > Rig Control) so that
  it can set the radio's frequency.

Checking the Connection
------------------------
  Start the Scheduler, open Settings > Program, and press Test next to
  JS8Call or FLDIGI. A good result looks like:

      Connected — version 3.0.3. 7.078 MHz, offset 1500 Hz, speed normal.

  (Standard JS8Call doesn't report its version, so that part is left out.)

  Then choose which program the Scheduler controls ("Program to
  control"), and press OK.

  For a full check that switching works, add a schedule entry, select it,
  and use Control > Test Selected Entry Now… with 1 or 2 minutes. The
  program should move to the entry's frequency, then come back.


================================================================================
6.  STARTING THE PROGRAM
================================================================================

Linux / Raspberry Pi
---------------------
  Double-click the SitRepNet Scheduler icon on the Desktop or in the
  application menu.

  Or from a terminal:
      python3 /home/<username>/sitrepnetscheduler/main.py

Windows
--------
  Double-click the SitRepNet Scheduler shortcut on the Desktop.

  Or from a Command Prompt:
      python C:\Users\<username>\sitrepnetscheduler\main.py

Only One Copy at a Time
------------------------
  If the Scheduler is already running, a second copy shows "SitRepNet
  Scheduler is already running" and closes. Two copies would both try to
  switch the radio.

First-Time Use
----------------
  The schedule starts empty. See the User Manual
  (SitRepNetScheduler_User_Manual.txt) for adding entries.


================================================================================
7.  TROUBLESHOOTING
================================================================================

"No module named tkinter" or "No module named _tkinter"
--------------------------------------------------------
  Install Tkinter (Section 2, Step 2).

Settings > Program > Test says it could not connect (JS8Call)
--------------------------------------------------------------
  - Is JS8Call running?
  - Is "Enable TCP Server API" on, and is the port the same in both
    programs?
  - Has JS8Call reached its "TCP Max Connections" limit because other
    programs are connected? Raise the limit.

Test says "JS8Call did not answer …" (JS8Call)
-----------------------------------------------
  Turn on "Accept TCP Requests" in JS8Call's Settings > Reporting. For
  JS8Call-improved, also see the WSJT-X protocol note in Section 5.

Test says it could not connect (FLDIGI)
----------------------------------------
  - Is FLDIGI running?
  - Was FLDIGI started with a different --xmlrpc-server-port? Use that
    port in Settings > Program.

The program changes frequency, but the radio doesn't
------------------------------------------------------
  Rig control (CAT) in JS8Call or FLDIGI isn't working. Fix that in
  JS8Call or FLDIGI first — the Scheduler can only ask them to change.

Times are off by several hours
--------------------------------
  The computer's time zone is wrong, or its clock is on UTC. See
  Section 2, Step 5.

Where are my files?
--------------------
  Linux / Raspberry Pi:  ~/.config/sitrepnetscheduler/
  Windows:               C:\Users\<username>\.config\sitrepnetscheduler\

    config.json      Settings
    schedule.json    The schedule
    state.json       Present only during a scheduled window: the
                     settings to return to. Don't delete it while a
                     window is running.
    scheduler.log    Activity log (times in UTC), kept to about 4 MB
                     across scheduler.log and its .1/.2/.3 backups.


================================================================================
  End of Installation Guide
================================================================================
