Add PAA Live Monitor

[jrhuerta]

PAA (Polar Alignment Assistant) Live Monitor

Summary

This PR adds an optional PAA Live Monitor: when enabled, INDI Web Manager tails the KStars/Ekos log file, parses Ekos "PAA Refresh" lines, and exposes a live view (web page plus REST/WebSocket API) of polar alignment error—total, altitude, and azimuth in DMS and arcseconds, with correction directions. The feature is opt-in: the server must be started with --with-paa; otherwise behavior is unchanged.

---

What it does

• Log discovery: Finds the latest KStars/Ekos log under configurable base directories (default: native and Flatpak paths).
• Parsing: Regex matches Qt-style log lines containing PAA Refresh, Corrected az:, alt:, and total: in DMS (e.g. 01° 06' 24").
• Tail-only when clients are connected: With at least one WebSocket client, only newly appended log content is read so the UI reflects "live" updates without re-reading the whole file.
• REST: GET /api/paa/status returns current status and latest PAA values (or "waiting" / "disabled" when applicable).
• WebSocket: /ws/paa streams updates (new data, heartbeat, or status messages such as "waiting" / "stale").
• Web UI: /paa shows Total, Altitude, and Azimuth error with direction arrows, optional accuracy target (arcsec), and a "Back to INDI Web Manager" link. Layout is responsive and usable on mobile (including bottom padding so content isn’t hidden by Safari’s toolbar).

---

Ekos configuration required

For the monitor to see data, users must:

1. In Ekos, enable "Log to file" so PAA Refresh lines are written to the KStars log.
2. Run the Polar Alignment Assistant in Ekos so those lines appear.

If Log to file is off or PAA hasn’t been run, the UI and API report that no PAA data was found and direct users to enable Log to file and run PAA.

---

Configuration

• --with-paa
  Enables the PAA monitor. Without it, the app behaves as before (no /paa, no PAA API, no log tailing).

• --kstars-logs DIR [DIR ...] (optional)
  One or more log base directories (each expected to contain YYYY-MM-DD subdirs with *.txt logs). If omitted, the app searches:

  • ~/.local/share/kstars/logs (native KStars)
  • ~/.var/app/org.kde.kstars/data/kstars/logs (Flatpak)

Example:
indi-web --with-paa
or
indi-web --with-paa --kstars-logs /path/to/kstars/logs

---

API

• GET /paa
  HTML page for the PAA Live Monitor.

• GET /api/paa/status
  JSON: state (active | waiting | disabled), optional message, and when state === 'active': timestamp, az, alt, total (DMS strings), total_arcsec, az_direction, alt_direction. Does not mutate tail state.

• WebSocket /ws/paa
  JSON messages: type update (live PAA payload), status (waiting/stale + message), or heartbeat. Payload fields match the REST shape (az, alt, total, total_arcsec, directions).

---

UI integration

• Main form: When PAA is enabled, the main INDI Web Manager form shows a PAA button linking to /paa (see indiweb/views/form.tpl).
• PAA page: Standalone page with status bar, Total/Altitude/Azimuth blocks, accuracy target input (persisted in localStorage), and back link. Uses WebSocket for live updates and handles waiting/stale/active states.
• Mobile: Bottom padding includes env(safe-area-inset-bottom) and extra space so the accuracy target and back link remain visible above Safari’s bottom bar on iPhone.

---

Files changed

• indiweb/paa_monitor.py (new): Regex, log discovery, tailing, PaaMonitor, _match_to_dict, REST and WebSocket endpoints.
• indiweb/views/paa.tpl (new): PAA Live Monitor page (HTML/CSS/JS).
• indiweb/main.py: --with-paa, --kstars-logs, lifespan shutdown of PAA monitor, conditional creation of PaaMonitor and inclusion of PAA router.
• indiweb/state.py: paa_monitor on app state (optional).
• indiweb/views/form.tpl: PAA button linking to /paa when PAA is enabled.
• README.md: New "PAA Live Monitor" section (description, how to enable, Ekos "Log to file" requirement, /paa and API, mobile screenshot).
• img/paa-monitor-mobile.jpeg (new): Screenshot of the PAA page on mobile for the README.
• tests/test_paa_monitor.py (new): Tests for regex, log discovery, tail behavior, _parse_latest, get_status, REST, WebSocket (including heartbeat), and page render.

---

Testing

• tests/test_paa_monitor.py
  Covers: PAA regex (real Ekos format, negative azimuth, rejection of non-PAA lines), date-dir pattern, discovery of latest log (single and multiple dirs), _parse_latest (dict shape, DMS strings, negative zero DMS), tail-only when client connected, no log / empty dir, wrong format; REST GET /api/paa/status (active with data, waiting when no logs); GET /paa HTML; WebSocket connection, diagnostic when log dir missing, and receipt of heartbeat/status. All tests use --with-paa and, where needed, --kstars-logs with temporary directories.

Run with:
pytest tests/test_paa_monitor.py -v