AAPA 0.9.0-beta.1

⚠ Beta — read this first

This is a pre-release. The plugin and firmware have been verified offline
(compiler, four self-test suites, and OAPA protocol conformance against the
emulator) and the plugin has been exercised inside a live N.I.N.A., but the
on-sky bring-up is not finished.

Three of the plugin's four components command your mount and the AAPA
motors. Work through nina-plugin/TESTING.md
against the telescope/camera simulators and the OAPA emulator first, then the
stages in docs/bringup-runbook.md.
Supervise the first real run — keep a hand on the power.

Please report anything odd as a GitHub issue,
including your N.I.N.A. version and the AAPA log lines around the problem.

Downloads

Bundle	What it is	Install
AAPA-nina-plugin-v0.9.0-beta.1.zip	N.I.N.A. plugin	Unzip into %LOCALAPPDATA%\NINA\Plugins\3.0.0\, restart N.I.N.A., enable AAPA Polar Alignment.
AAPA-firmware-v0.9.0-beta.1.zip	ESP32 firmware	Both sketches (source) + flashing and wiring docs. Flash AAPA_for_software for OAPA/N.I.N.A.
AAPA-desktop-and-tools-v0.9.0-beta.1.zip	Desktop app + tools	Astro Commander, the OAPA emulator and the ATPPA tools. pip3 install -r software/requirements.txt

SHA256SUMS.txt covers all three. Verify with Get-FileHash <file> -Algorithm SHA256 (PowerShell) or sha256sum -c (Linux/macOS).

What's in it

First public beta. Pre-1.0 on purpose: everything below is verified offline and
in a live N.I.N.A., but the on-sky bring-up is not finished. 1.0.0 is reserved
for the first release that has actually aligned a mount.

Added

• N.I.N.A. TPPA "OAPA" compatibility layer in the USB firmware
  (firmware/AAPA_for_software/AAPA_for_software.ino):
  the board now answers a GRBL-style subset (?, $J=G91G21…, $J=G53…,
  XC/YC/XH/YH) so TPPA can drive it automatically with no custom plugin.
  The native protocol and platedual.py are unaffected.

• OAPA device emulator (tools/aapa_oapa_emulator.py)
  — a virtual AAPA board (with a built-in --selftest and fault-injection flags)
  for testing NINA/TPPA and platedual.py without hardware.

• N.I.N.A. plugin (nina-plugin/, .NET 8 / WPF, assembly
  AapaVisualizer) exporting four components:

  • ATPPA: Auto Polar Align — an Advanced-Sequencer instruction running the
    full hands-off loop (plan safe targets → gated slew → plate-solve →
    circle-fit the polar error → correct via OAPA → iterate) under a safety
    supervisor. Works with the pole out of view; refuses to cross the
    meridian or go below an altitude floor. A Layer 0 pre-flight refuses to
    start at all unless the base is homed inside valid soft limits, the site
    latitude is set, and the mount is connected, unparked and reporting a known
    side of the meridian. Target planning honours the custom horizon from the
    NINA profile, so it plans around your real skyline rather than a flat
    altitude floor — the horizon can only ever raise the floor, never lower it.
    Reverse alt / Reverse az settings handle an axis that moves the sky the
    opposite way (a negative Steps/° is rejected — it inverted the travel
    clamp). A Dry run mode drives the real motor from a simulated sky, with
    no camera or scope.
  • Auto Polar Align panel — the same loop outside a sequence, with a live
    error readout, phase tracker, and converging reticle.
  • AAPA Control panel — manual connect, :HOMEY/:RESETY re-homing, and
    alt/az jogging of the base.

  Both motor-driving panels pick the serial port from a dropdown of the ports
  currently present, and still accept a typed port (e.g. one end of a com0com pair).

  • AAPA Visualizer panel — read-only WebView2 visualizer (3D sphere,
    bullseye, error decay); in Live mode it tails TPPA's log.

• ATPPA design + reference implementation: docs/atppa-design.md,
  tools/atppa_safety_core.py (--selftest 30/30) and
  tools/atppa_orchestrator.py (--selftest 37/37,
  driving the real emulator over OAPA with fault injection).

• Test harness nina-plugin/AtppaCore.Tests
  (dependency-free, dotnet run → 56/56) plus the runtime test plan
  nina-plugin/TESTING.md and an offline interactive
  walkthrough at docs/live-test-walkthrough.html.

• Dry run re-centres the base before starting, so repeated rehearsals no longer walk
  it into the travel limit, and the "travel exhausted" abort now says how to recover.

• Polar error shown in degrees/arcminutes/arcseconds, as TPPA does, in the panel
  readout, the status bar, the log and the abort messages. Empty leading units are
  dropped, so a finished alignment reads 42.0″ rather than 0° 00′ 42″.

• Wrong-way axis detection. A correction must move the measured error by the amount
  applied; if it moves the other way instead, the run aborts naming the reverse setting
  to change. Catches an inverted axis on the pass after the first real correction,
  instead of letting the loop diverge into the travel limit.

• Progress in N.I.N.A.'s application status bar for the alignment loop, calibration
  and :HOMEY, so a run that takes minutes stays visible after switching tabs. One
  shared source, cleared on every exit path.

• Panel settings persist in the active N.I.N.A. profile. COM port, Steps/° and
  the reverse flags are shared between both motor panels, so a calibration done in
  AAPA Control is immediately used by Auto Polar Align.

• Per-axis Steps/° — altitude and azimuth are separate mechanisms and gear
  differently, so each is calibrated, stored and travel-clamped independently.

• Offline plugin-wiring check (tools/check_plugin_wiring.py) — validates
  DataTemplate keys, {Binding} paths and XAML event handlers against the view
  models, catching first-load failures the compiler cannot see.

• OAPA conformance tester (tools/aapa_oapa_emulator.py --conform COMx) — points
  TPPA's own client logic at real hardware and reports whether N.I.N.A. would detect
  and drive it: 300 ms scan-timeout detection, status framing, the two-line ? reply,
  stray chatter, jog completion and the stuck watchdog. --move adds motion. Works for
  any board adapting a mount to OAPA, not just AAPA.

• Automatic Steps/° calibration in the AAPA Control panel — probes an axis in
  machine microsteps, correlates the travel against TPPA's reported alignment error,
  and fits the gear ratio and axis direction by least squares. TPPA's own learned
  response is private and not persisted, so it cannot be reused; this measures the
  same thing from the outside.

• Bring-up runbook (docs/bringup-runbook.md) — the
  bench-to-calibrated-base procedure, including measuring axis direction and the
  gear ratio without needing sky.

• Tagged releases — pushing a vX.Y.Z[-beta.N] tag runs every suite, builds
  the plugin, packages three download bundles (plugin / firmware / desktop+tools)
  with checksums, and publishes a GitHub Release, marked pre-release when the
  tag has a suffix (.github/workflows/release.yml,
  procedure in docs/releasing.md). The plugin's assembly
  version is stamped from the tag, so no version-bump commits.

• Documentation set under docs/ and this changelog.

Changed

• Reorganized the repository into firmware/, software/, tools/, and docs/.
  Firmware sketches now live in folders matching their .ino name (Arduino IDE
  requirement). requirements.txt moved to software/.

Documentation

• Bring-up runbook (bench → calibrated base)
• N.I.N.A. plugin — build, install, limitations
• Runtime test plan
• N.I.N.A. TPPA (OAPA) integration — no plugin needed
• Calibration
• [Troubleshooting](https://github.com/RedbeardThePilot/AAPA/blob/v0.9.0-beta.1/docs/troubleshooting...