Open-source firmware and software for AstrophilosLab's motorized polar-alignment device. AAPA drives two stepper motors — Azimuth (X) and Altitude (Y) — to align an equatorial mount's rotation axis with the celestial pole, turning the usual fiddly manual knob-twiddling into an automated procedure.
It works three ways:
- Fully automatic with N.I.N.A., no plugin — the USB firmware speaks the OAPA protocol of N.I.N.A.'s Three Point Polar Alignment (TPPA) plugin, so TPPA plate-solves the sky and drives AAPA to zero out the error.
- Fully automatic with the AAPA N.I.N.A. plugin — nina-plugin/ adds ATPPA, a hands-off loop (plan safe targets → slew → plate-solve → circle-fit → correct → iterate) that works with the pole out of view, plus a manual control panel and a live visualizer.
- Standalone desktop app — Astro Commander (software/platedual.py) reads TPPA's error logs and closes the loop itself, and also gives you manual jog, homing, and calibration controls.
flowchart LR
NINA["N.I.N.A. + TPPA<br/>(plate-solve error)"] -->|"USB serial · OAPA"| ESP
PLUG["AAPA plugin<br/>(ATPPA auto-align)"] -->|"USB serial · OAPA"| ESP
APP["Astro Commander<br/>(platedual.py)"] -->|"USB / WiFi TCP"| ESP
ESP["ESP32<br/>FYSETC E4 v1.3"] --> TMCX["TMC2209 (X)"] --> MX["NEMA-17<br/>Azimuth"]
ESP --> TMCY["TMC2209 (Y)"] --> MY["NEMA-17<br/>Altitude"]
EMU["OAPA emulator<br/>tools/"] -.->|"test without hardware"| NINA
EMU -.->|"test without hardware"| PLUG
| Path | What it is |
|---|---|
| firmware/AAPA_for_software/ | ESP32 firmware — USB build; the only variant that speaks OAPA |
| firmware/AAPA_for_softwareWIFI/ | ESP32 firmware — adds a WiFi TCP command channel (no OAPA layer) |
| software/platedual.py | Astro Commander desktop app (USB) |
| software/platedualWIfi.py | Astro Commander with a USB/WiFi transport switch |
| software/requirements.txt | Python dependencies |
| nina-plugin/ | N.I.N.A. plugin — ATPPA auto-align, manual control, live visualizer |
| tools/aapa_oapa_emulator.py | Virtual OAPA device for testing NINA/TPPA without hardware |
| tools/atppa_safety_core.py | ATPPA planner / safety gate / circle-fit estimator (reference implementation) |
| tools/atppa_orchestrator.py | Full offline ATPPA loop driving the emulator over OAPA |
| docs/ | Full documentation (see index below) |
Prebuilt bundles are on the Releases page:
| Bundle | What you get |
|---|---|
AAPA-nina-plugin-vX.Y.Z.zip |
The N.I.N.A. plugin, built. Unzip into %LOCALAPPDATA%\NINA\Plugins\3.0.0\, restart N.I.N.A., enable AAPA Polar Alignment |
AAPA-firmware-vX.Y.Z.zip |
Both ESP32 sketches (source) + the flashing, hardware and protocol docs |
AAPA-desktop-and-tools-vX.Y.Z.zip |
Astro Commander, the OAPA emulator and the ATPPA tools |
Releases tagged
-beta.Nare pre-releases: verified offline and in 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 motors — work through nina-plugin/TESTING.md against the simulators first.
Building from source instead? Carry on below. Publishing a release? See docs/releasing.md.
Flash the firmware (Arduino IDE + ESP32 core): open
firmware/AAPA_for_software/AAPA_for_software.ino,
install the TMCStepper and AccelStepper libraries, and upload. See
docs/flashing-firmware.md.
Run the desktop app:
pip3 install -r software/requirements.txt
python software/platedual.pyUse it with N.I.N.A.: in TPPA, set Polar Alignment System = OAPA and connect over USB. See docs/nina-tppa-oapa.md. For the hands-off ATPPA loop instead, build and install the plugin — see nina-plugin/README.md.
Test without hardware:
python tools/aapa_oapa_emulator.py --selftest # 14/14
python tools/atppa_safety_core.py --selftest # 30/30
python tools/atppa_orchestrator.py --selftest # 37/37
dotnet run --project nina-plugin/AtppaCore.Tests # 56/56
python tools/check_plugin_wiring.py # plugin XAML wiringFirmware, desktop app and emulator are the mature parts. The firmware's OAPA layer is verified against a port of TPPA's own client logic, so TPPA can drive AAPA today with no plugin at all — that path is the lowest-risk way to use this hardware.
The N.I.N.A. plugin (ATPPA) is new and has not yet aligned a real mount. Where it stands, as of 2026-07-28:
| Status | |
|---|---|
| Builds, and passes 244 offline checks across five suites | ✅ |
| Runs in a live N.I.N.A. — panels, settings, status, dry-run convergence | ✅ |
| Protocol conformance against the emulator | ✅ |
| Driven a real AAPA base | ❌ not yet |
| Aligned a real mount | ❌ not yet |
Next steps, in order — the bring-up runbook walks through them:
--conformagainst the real board, then bench tests: wiring, axis identity, direction, and a measuredSteps/°per axis.- On sky with TPPA in OAPA mode. This is the gate that matters: it exercises firmware, wiring, direction and gearing with none of the plugin's control code in the loop, so any failure is unambiguously hardware.
- Then the plugin — dry run against the real base, then a supervised alignment.
Known gaps are listed in the plugin's README, and the safety layers that remain deferred in atppa-design.md. Nothing here has been run unattended, and it should not be until step 3 above is done.
- Hardware & pinout
- Flashing the firmware
- Command protocol reference — native,
:commands, and OAPA - N.I.N.A. TPPA (OAPA) integration
- Astro Commander desktop app
- OAPA device emulator
- Tutorial — your first automatic polar alignment — start here for the plugin
- Bring-up runbook — bench → calibrated base, step by step
- Calibration · Troubleshooting
- ATPPA — automatic three-point polar alignment — design rationale + what is implemented vs deferred
- N.I.N.A. plugin — build & install · runtime test plan
- Run a live test — interactive walkthrough (open in a browser)
- Releasing — tag → built, tested and published GitHub Release
The mechanical design (CAD) is not in this repository. It is available from the maker: https://astrophiloslab.com/aapa.
Note: earlier docs referenced a precompiled
Platedual.exe. It is not in this repository — run the Python source above instead.
Created by Astrophilos — https://www.youtube.com/@Astro-philos. The full build is documented in this YouTube playlist.
Licensed under the MIT License. If you use this project, please credit Astrophilos.