A start-to-finish walkthrough for someone who has an AAPA base, a mount and N.I.N.A., and wants the plugin aligning it. Roughly an hour at the bench plus one clear evening.
It is deliberately a happy path with the traps marked. The exhaustive validation lives in the bring-up runbook and the runtime test plan; come here first, go there when something misbehaves or before you leave it running unattended.
The only emergency stop is cutting power.
:HOMEYblocks the firmware for up to a minute and will not answer:STOPwhile it runs. Keep the supply switch to hand throughout, and make sure the OTA can travel without meeting the pier or a tripod leg.
Four things in N.I.N.A., under the plugin AAPA Polar Alignment:
| Component | What it is for |
|---|---|
| AAPA Control panel | connect, home, jog by hand, calibrate the gearing |
| Auto Polar Align panel | run the alignment loop interactively |
| ATPPA: Auto Polar Align | the same loop as a sequence instruction |
| AAPA Visualizer panel | read-only view of the error converging |
- N.I.N.A. 3.x, plus the Microsoft Edge WebView2 Runtime (already present on Windows 11 and with modern Edge).
- .NET 8 SDK to build the plugin.
- An AAPA base flashed with
firmware/AAPA_for_software. This matters: the WiFi variant does not speak the OAPA protocol the plugin uses. - A working plate solver in N.I.N.A. (ASTAP is a good default) and your site latitude and longitude set — the plugin refuses to start without them.
- Optional but recommended for step 3: a digital inclinometer.
Connect the base by USB and ask whether N.I.N.A. would accept it:
python tools/aapa_oapa_emulator.py --conform COM7 # your portThis points TPPA's own client logic at your hardware and reports pass or fail per check. It is worth doing first because the most common failure is invisible from inside N.I.N.A.: the board auto-resets when the port opens, is still booting when the scan arrives, and simply never appears in the list.
Expect 8 passed, 0 failed. If detection fails, the tool names the cause — see
troubleshooting.md.
No hardware yet? Everything below works against the emulator on a com0com pair — see emulator.md.
dotnet build nina-plugin/AapaVisualizer/AapaVisualizer.csproj -c ReleaseCopy from nina-plugin/AapaVisualizer/bin/Release/ into
%LOCALAPPDATA%\NINA\Plugins\3.0.0\AapaVisualizer\:
AapaVisualizer.dllMicrosoft.Web.WebView2.*.dllWebView2Loader.dll
Restart N.I.N.A., open Plugins, and enable AAPA Polar Alignment. The three panels appear in the Imaging tab's dockable list; the instruction appears in the Advanced Sequencer.
A panel that opens blank means its template no longer matches its view model.
python tools/check_plugin_wiring.pycatches that offline.
Add the AAPA Control panel. Pick your port and press Connect.
The plugin will not start an alignment on a base that has never been homed.
- Check StallGuard first — send
:SGTESTfrom any serial terminal and look forOK_stall_detected. Tuning is in calibration.md. - Press Home (StallGuard). It can take up to a minute; the status bar counts against that.
- No usable StallGuard? Position the axis by hand where you want zero and press Set zero here instead. That satisfies the pre-flight just as well.
- Set soft limits (
:MINY/:MAXY) and:SAVEthem — see the runbook.
With a small jog from the panel, check that altitude and azimuth each move the axis you expect. If they are swapped, the motors are in the wrong driver sockets — fix the wiring rather than compensating in software, because the firmware, the docs and the plugin all assume X = azimuth, Y = altitude.
Steps/° is base microsteps per degree of sky, and there is one per axis
because altitude and azimuth are separate mechanisms that rarely gear alike. The
default of 900 is a placeholder — it is almost certainly wrong for your build.
Two ways to measure it:
- At the bench, with an inclinometer — jog a known number of microsteps, measure how far the polar axis tilted, divide. Full procedure.
- On sky, automatically — the panel's Calibrate Steps/° buttons. Needs TPPA running and measuring with its automated adjustment switched off, so it is not correcting the error the probe moves create. A few minutes per axis.
Press Apply and the figure is saved to your N.I.N.A. profile and shared with the Auto Polar Align panel. Do each axis separately.
How exact does it need to be? Within roughly −30 % / +116 % of true. Under-estimate if unsure: too low is slow and safe, too high is fast right up until it is unstable. The maths is in calibration.md.
If an axis moves the sky the opposite way to a correction, the loop would diverge. Tick Reverse alt or Reverse az for that axis. If you get it wrong the run aborts on the pass after the first real correction and names the setting to change, so this is not a silent failure — but it costs you a run.
Add the Auto Polar Align panel, set your port, and tick Dry run.
Dry run invents the sky but drives the real motor, so it exercises the whole chain except the camera and the mount. It re-centres the base to mechanical zero first — expect the motors to move as it starts.
Press Run and watch:
- the phase tracker cycle Measuring → Fitting → Correcting
- the error readout fall toward zero in degrees, arcminutes and arcseconds
- the status bar, bottom-left, showing which pass and how far through it
A dry run should converge in a handful of passes. If it does not, your Steps/° is
the first thing to suspect.
Rough-align by hand first, to within about a degree. The plugin is designed to take the residual, not a wild starting error — a large correction is applied wherever the OTA happens to be pointing, since the "safe adjust pose" of the design is not implemented yet.
Then, with the mount connected, unparked and tracking, and a solvable sky:
- Untick Dry run.
- Keep the altitude floor conservative (25° is the default) and the iteration cap low for the first run.
- Press Run, and watch the first correction on each axis specifically: right direction, sensible size.
It plans three targets on one side of the meridian, slews, plate-solves each, fits the polar error from the three points, corrects through the base, and repeats until it is inside tolerance. It never needs Polaris and never crosses the meridian.
Cancel is a real stop: it halts the motors and exits.
Every abort names its reason. The ones you are most likely to meet:
| Message | What to do |
|---|---|
ATPPA pre-flight failed |
It lists everything wrong at once — home the base, set the site, unpark the mount |
AAPA base travel exhausted |
The base hit its ±6° host limit. Re-centre with Set zero here and Center azimuth |
Altitude/Azimuth moved the wrong way |
A reverse flag is inverted; the message says which |
no safe targets |
Nothing is inside the envelope — usually an altitude floor set too high, or a custom horizon blocking the sky |
motor stuck |
MPos stopped progressing: a jam, an endstop, or a speed of zero |
Both motor panels share the rig-level settings, because they describe your hardware rather than the panel: change one and the other follows. They are saved in the active N.I.N.A. profile. The sequence instruction keeps its own copy, saved with the sequence.
| Setting | Default | Notes |
|---|---|---|
| COM port | — | one owner at a time; disconnect one panel before connecting the other |
Steps/° alt / az |
900 | measure this; per axis |
| Reverse alt / az | off | tick if an axis drives the error the wrong way |
| Tolerance | 1′ | when to call it aligned |
| Altitude floor | 25° | never plan a target below this |
| Gain | 0.7 | fraction of the error corrected per pass |
| Max iterations | 8 | give up after this many passes |
| Use horizon | on | honour the custom horizon in your NINA profile |
| Dry run | on (panel) | simulated sky, real motor |
- bringup-runbook.md — the staged validation this tutorial compresses, with a record sheet for your measured values
- ../nina-plugin/TESTING.md — the fault-injection cases to run before trusting it unattended
- atppa-design.md — how the safety layers work, and which are still deferred
- nina-tppa-oapa.md — using TPPA directly with no plugin, and adapting other hardware to OAPA