PHD2 guider

PHD2 is a peer process. Starship doesn't replace it, doesn't embed it, doesn't try to autoguide on its own. It connects to PHD2's JSON-RPC server, reads status, and — unless you switch control off — commands PHD2 the way Voyager does: set the guide exposure, start guiding, dither between subs, and stop guiding.

Connection

Settings → PHD2 guider, enable, set host (typically 127.0.0.1 if same PC) and port (PHD2 default is 4400). Save and restart.

In PHD2: Tools → Enable Server. Without this PHD2 doesn't accept connections.

Test connection on the PHD2 settings page opens a socket to PHD2 to confirm it's running with its server enabled, without changing anything.

Starship keeps the connection alive on its own — it reconnects with backoff if PHD2 is closed or restarts, so you don't have to re-establish the link by hand.

What's exposed (read-only)

The Status / Guiding section shows:

These come from PHD2 events: AppState, GuideStep, Settling, Calibrating, LoopingExposures, SettleBegin/SettleDone, etc. Reading these never requires Allow control — the observe path always works.

The RMS shown

Since v23 the guide RMS on the dashboard is a real RMS: the root-mean-square of the settled guide steps of the last 120 seconds, for RA, Dec and the total. Steps taken while PHD2 is settling (after a dither or a start) are left out, and the figure starts again when guiding starts or stops, or PHD2 disconnects.

For scripts, GET /api/phd2 carries rms_px, rms_ra_px, rms_dec_px, the same three as …_arcsec (null without a pixel scale), rms_samples and rms_window_s. The older keys rms_total, rms_ra, rms_dec are still there and are still the latest single step in pixels; last_error_px, last_error_ra_px and last_error_dec_px are the honest names for them. The guiding watchdog's rms_max_px is still compared with that latest step, in pixels.

Letting Starship command PHD2

Settings → PHD2 guider → Allow Starship to command PHD2 ([phd2] allow_control) is on by default. With it on, a sequence that enables guiding can drive PHD2 — nothing commands PHD2 unless a plan (or a blockscript start_guiding, or Connect all with the launch option below) asks for it. Untick it to keep the link strictly read-only.

Commands mirror the set an observed Voyager rig sends: set the guide exposure (snapped to the nearest duration PHD2 actually supports), start guiding and wait for settle, dither and wait to re-settle, and stop guiding.

Launch PHD2 on Connect all (unattended rigs)

Launch PHD2 on Connect all ([phd2] auto_start) lets an unattended rig come up with no human at the guider. When it's on, Connect all launches PHD2 if it isn't already running, selects the Equipment profile you name (by profile name or numeric id) and — if Connect equipment on Connect all is ticked — connects PHD2's guide camera and mount. The PHD2 executable path is the full path to phd2.exe (blank = the standard install folders); Start delay is how long to wait after the launch before connecting to PHD2's server.

Off (the default) means Starship only connects to a PHD2 you started yourself — it never launches it.

PHD2 is launched, and its equipment connected, on Connect all — the Console's, a blockscript's connect_all or a plan's connect_all action — never when Starship starts and never on sequence start. On a rig whose gear is on a switched power box the order is: Connect power, switch the gear on, wait for it to boot, then Connect all, so PHD2 only ever talks to powered gear. At startup Starship just connects to a PHD2 that is already open, to watch it, and leaves its equipment alone. Once Connect all has run the launch is self-healing: if PHD2 crashes, it's relaunched on the next connect retry.

A saturated guide star

When the star PHD2 picks for a new guiding start is saturated, Starship searches the parts of the guide frame away from it (left, right, above and below, largest first, up to three tries) and takes the first star that is fine on the next frame (v23.1.2). If there is nothing else, it tries once more at a longer exposure and then leaves the choice to PHD2, as before.

Disconnect all releases PHD2

Disconnect all — the Console's, a blockscript's disconnect_all or a plan's disconnect_all — starts with PHD2 when control is allowed: it stops looping or guiding and disconnects PHD2's guide camera and mount, before Starship disconnects its own devices. Powering the gear off afterwards then never cuts a camera or mount PHD2 still holds. It also stops the relaunch until the next Connect all. PHD2 is then closed when Launch PHD2 on Connect all is on (v23.1.2): Starship starts it, so Starship closes it, and the next Connect all starts it again. Untick Close PHD2 on Disconnect all in Settings > Guiding to keep it open. A PHD2 you start by hand (Launch off) is always left open. A PHD2 that isn't running is simply skipped — it never holds up or fails Disconnect all.

Guiding in a sequence

Open a sequence's Guiding tab and tick Enable guiding for this sequence. When guiding is enabled (and control is allowed), Starship:

  1. Sets the guide exposure and starts guiding once each target is centred, and waits for PHD2 to settle before the first frame.
  2. Dithers between subs at your cadence, waiting for guiding to re-settle each time.
  3. Stops guiding before the next slew, then re-starts guiding on the next target.

Binning comes from the PHD2 profile (the Guide binning dropdown can override it). If guiding can't start on a target — no star, settle timeout — that target is skipped rather than imaged unguided.

The Guiding tab options:

- Dither every (exposures) — how many subs between dithers. - Dither amount (px) — dither size in guide-camera pixels. - RA-only dither — for setups where Dec backlash makes 2-axis dither slow to settle.

Picking the guide star

Before it starts guiding on a new field Starship has PHD2 pick a fresh star in the central part of the guide frame (fresh_star, star_central_frac in the plan's guiding policy). It stops the capture and waits until PHD2 reports it stopped, loops, waits for a new frame, then asks PHD2 to find a star, and checks the pick on the next frame: a star PHD2 flags as saturated, or one it can't measure again, is dropped. When nothing usable turns up, it tries once more with a longer guide exposure (twice the plan's, at most 5 s) and then puts the exposure back. If that fails too, PHD2's own auto-select picks the star when guiding starts, as before.

Refocus and guiding

A sequence refocus moves the focuser through a sweep. A guider that looks through the imaging optics (an off-axis guider) sees its star defocus and drift, so guiding has to pause; a separate guide scope doesn't see the sweep at all, and stopping it there only risks not finding a star again afterwards. Settings → PHD2 → Pause guiding for a refocus ([phd2] pause_guiding_for_focus) decides:

The run journal says once per run what was decided and why, e.g. refocus: guiding kept running - separate guide scope (130 mm vs 360 mm). After a pause, guiding restarts on the same star first — PHD2 keeps it selected and the field hasn't moved — and only picks a fresh star if that doesn't settle.

Guiding as sequence actions

Beyond the Guiding tab, three action steps let you place guiding explicitly in a plan (e.g. in on-start / on-resume / on-end blocks):

When PHD2 control is off, or the plan doesn't enable guiding/dithering, these steps record a no-op instead of failing.

Guiding precondition

If a plan enables guiding but PHD2 isn't connected (or control is off), the sequence first asks PHD2 to come up the way Connect all does (launching it when Launch PHD2 on Connect all is on) and, if it still isn't ready, fails fast with a clear message — pointing you to open PHD2 and connect the guide camera + mount (or hit Connect all) — instead of silently imaging unguided or spamming connection retries.

Guiding watchdog

Optional, off by default (Settings → PHD2 → Guiding watchdog). When on, it holds the next sub until guiding recovers, so the rig never starts an exposure under a lost or degraded guide star. Set a max guide RMS (0 = hold only on a lost star), a recover timeout after which the exposure step fails so the on-error policy decides, and a poll interval. It pairs with frame acceptance, which rejects a sub ruined mid-exposure.

Guiding during the sub (v22.2.17)

Starship keeps a time-stamped history of what PHD2 reports — every guide step (with PHD2's RALimited / DecLimited flags for a pulse clipped at its maximum length), every lost star, guiding starting and stopping, and PHD2's own Alert messages. After each guided light sub it judges the guiding over the exposure: an RMS above the watchdog's max guide RMS (watchdog on), a runaway (3+ clipped pulses in a row on one axis), or the star lost for half the exposure in one stretch rejects the sub — it is not counted, is moved to rejected/ and is re-shot (see the Sequencer topic). A runaway is stopped and re-acquired at once.

When guiding settles and then runs away again within minutes, twice on the same target, Starship treats it as a systematic fault — after a meridian flip that is usually PHD2's Reverse Dec output after meridian flip option (Advanced Setup → Guiding) or a calibration from the other side of the pier — skips the target, and says so in the journal and the alert, quoting PHD2's alert when there is one. PHD2 does not send an alert you ticked Don't show this again for; re-enable it in PHD2 if you want its words in Starship's alerts.

Why peer-process

Two reasons: PHD2 is the de-facto standard and is mature, and keeping autoguiding in a separate process means a Starship crash doesn't take guiding with it.

Because the commands drive the mount, watch the first guided run on your rig — the command path is verified in code and unit-tested, but the live round-trip is only exercised on hardware.

Astroworx Starship v23.1.2 · this page is the in-app help of that buildDownload · HTTP API