Settings
Settings is where you tell Starship what equipment you have and how you want it to behave. Each tab on the left is one job. The help link beside the tab name at the top of the page opens the help for the tab you are on.
The tabs
Equipment
- Connections - the two switches that turn ASCOM (drivers on this PC) and Alpaca (devices on the network) on or off. A device tab shows a banner with a Turn on button when its device is set to one that is off.
- Mount, Camera, Focuser, Filter wheel, Rotator, Flat device, Observatory, Power admin - choose the driver for each device and set how Starship uses it.
- Cooling - camera cooling.
- Autofocus - autofocus, First Light and the refocus triggers. Star sizes there are HFR in pixels.
- Observatory - one question, "Does your enclosure clear the telescope in any position?", sets the order of park and close everywhere. The four switches behind it are under Advanced, each with the actions it applies to.
- Site / Location - where the observatory is. Set this first: darkness times, altitude limits and the scheduler all depend on it.
Safety & Environment
- Weather - the CloudWatcher (Solo), SafetyMonitor and ObservingConditions devices, and the weather limits.
- Safety supervisor - whether the weather gates the observatory, and how long it waits before it trusts a clear sky again.
- Crash protection - parking the mount if Starship stops unexpectedly, and the health monitor.
- All-sky camera, CCTV - pictures only.
Integrations
- Cartes du Ciel, Plate solver, Guiding (PHD2).
- Frame quality - grading each sub and rejecting the bad ones.
System
- Web server - the address of this dashboard and its sign-in.
- Guardian (recovery) - what Starship does when a device drops out during a run.
- Audit log, FITS / images.
- Event log rules - write a log line or a file when the safety state changes. This tab only logs and notifies. What the observatory does in bad weather (park, close) is set in the sequence's On Suspend actions and in the blockscript's Unsafe state.
- Sequencer defaults - where plans are kept, and run timing.
- Scheduler - scheduler tuning and Moon avoidance.
Buttons that move hardware are on the Console and the Polar Alignment page, not in Settings. The two tests that have no other home (a guide pulse, and the Guardian dry run) are in a closed Tests block at the bottom of the Guiding and Guardian tabs.
A dot beside a tab name means that tab has changes you have not saved yet.
Save, and Save & restart
There are two buttons at the bottom of every tab.
- Save writes your changes to the configuration file. Most settings take effect at once, the next time they are used.
- Save & restart saves, then restarts Starship so that every setting is read again. Use it when a changed setting has the restart badge, or when you are not sure.
Either button saves the unsaved changes on every tab, not only the one you are looking at. If a value is not allowed, nothing is saved and the page says what to correct.
If the settings were changed from another dashboard after you opened this page, your save is refused and nothing is written. Press Reload settings: what you typed is kept, and you can save again.
The restart badge
A field with a small restart badge beside its name is read only when Starship starts. After a Save that changed one of them, the page lists them by name ("These changes need a restart: ...") and offers Restart now. Until the restart, Starship keeps using the old values. A save that changed none of them takes effect at once.
A restart takes a few seconds and the dashboard reconnects by itself. A restart cuts off a running sequence, schedule or blockscript, so Starship refuses it while one is running: it names what is running and asks you to stop it first, or to confirm that you want to restart anyway.
When the same thing seems to be set twice
A few behaviours have two fields. Each says in its hint what it applies to. In short:
- Settle after slew (Mount tab, twice): the one under Slew behaviour follows every slew a sequence makes; the one under Precise pointing follows each slew of the precise-pointing loop. Both are waited; neither replaces the other.
- After a filter change: "Settle after a filter change" (Sequencer defaults) is part of every filter move; "Additional safe time after filter change" (Camera) is added on top. Both apply.
- Focuser backlash: "Backlash compensation" on the Focuser tab is for plain moves (the Console buttons, a move-focuser step). Autofocus never uses it; it has "Approach direction" and "AF backlash steps" on the Autofocus tab, and Refocus uses the backlash that First Light measured.
- Autofocus binning: "Autofocus frame binning" is the one that is used. "Fallback binning" is used only when that one is 0.
- Guiding settle time: a settle time set in a plan wins. "Guiding settle time" (Sequencer defaults) is used when the plan gives none.
- Refocus triggers: a plan's own Focus-tab triggers always work. With "Enable auto-refocus" on (Autofocus tab), the triggers set there are added to every plan, and where a plan sets the same trigger the plan's value is used.
How saving works (technical)
This part is for people who script Starship or edit config.toml by hand. Every tab maps to a [section] block in config.toml, and every field is one key in the typed config tree (starship/core/config/__init__.py).
What a save does
When you Save, the dashboard POSTs the whole config to /api/config. The server:
- Rebuilds a
StarshipConfigfrom the JSON (from_dict). - Runs
validate()— if anything fails, nothing is written and the errors come back inline. - Backs up the current
config.tomltoconfig.toml.bak, then writes the newconfig.toml. - Swaps the in-memory
svc.configpointer to the new config and reportsneeds_restart: true only when a setting that is read once at startup actually changed (the reply lists those keys inrestart_required_keys).
Two dashboards open
Each dashboard remembers which version of the settings it read. If the settings changed somewhere else after that (a save from another dashboard, or a Save as defaults on another page), your save is refused and nothing is written. The page says so and offers Reload settings. What you typed is kept and goes on top of the fresh copy; then save again. This stops an old page from putting back everything that changed since it was opened. A script that posts /api/config without the _version field is saved as before.
That last step is the subtle one: Save updates the config object in RAM, but it does NOT re-initialise any already-running module. Long-lived things (driver poll loops, ASCOM/Alpaca threads, the PHD2 socket, the web server) captured their settings at startup and keep using those values until the service is rebuilt. Settings that are read fresh every time they're used pick up the change immediately; settings read once at startup do not.
What "restart" means here
The restart is in-process, not a reboot and not even a process exit. request_restart() sets a flag and signals the run loop; the runner (scripts/run_starship.py) tears the service down, re-reads config.toml from disk, and builds a brand-new StarshipService from it — all in the same Python process (the command window stays open). This is why "the config in RAM" matters: a plain Save changes RAM but leaves the old threads running against their startup snapshot; only the rebuild on restart re-creates those threads from the freshly loaded file.
Restart takes about 1–2 seconds.
A restart does not resume a run. The sequencer, the scheduler and blockscript are part of the service that is torn down, so a restart cuts a running sequence, schedule or blockscript session off where it stands, and nothing starts it again afterwards. For that reason Save+Restart (and loading a profile, a factory reset, or Shutdown) is refused while a run is active: Starship names what is running and asks you to stop it first, or to confirm that you want to restart anyway. After a restart you start the run again yourself; a sequence that left a checkpoint can be picked up where it stopped with Resume (the /api/sequencer/resume_run route), which skips the frames already taken.
Starship can also carry on by itself with a stand-alone sequence that was cut short when Starship or the PC went down unexpectedly: Settings → Sequencer defaults → Resume a sequence cut short by a restart ([sequencer] auto_resume_after_restart, off by default; new in v23). It never resumes a run you stopped, or a run that was going when you restarted or shut down on purpose. The Windows restarts and crashes topic lists exactly when it will and will not resume.
What's live (no restart)
Changes that take effect on the next use, because the code reads them fresh each time:
- FITS options other than the three listed under "What needs Save+Restart" (read when a frame is written).
- Cooling parameters (read on every cooling action).
- Autofocus parameters (read on every AF run; the learned Refocus recipe lives in a separate
focus_recipe.json, not in Settings).
- Plate solver (ASTAP) path / radius / timeout / downsample (the
-zfactor: 0 = auto, force 2–4 to solve noisier OSC/short frames). - Site coordinates, mount slew/flip defaults, pointing/rotator/polar parameters (read at the start of each operation). This includes the rotator travel limits and the plate-solve sync limit (see below).
- Auto Flat planner parameters, Frame acceptance gates, and the Guiding watchdog — read when the relevant step runs.
- Filter library (Settings → Filter wheel) — the named filters, per-filter refocus exposure, and focuser offset are read on each filter change / refocus.
- Scheduler loop knobs, score weights, moon-avoidance and roof-management settings (read as the dispatch loop runs).
- Alerts routing (the AlertsManager re-reads on save; the alerts section has its own Save endpoint).
- Audit retain/exclude settings (applied as the log rolls).
- Memory response knobs (
gc_on_warning,drop_preview_cache_on_warning) — read when the health monitor hits a memory warning.
Because these are re-read per operation, a plain Save is enough — but Save+Restart is always harmless.
What needs Save+Restart
Anything bound to a long-lived connection, thread, or server captured at startup:
- Solo host / poll interval / timeout (driver re-binds its poll loop).
- FITS images folder (
images_dir), folder layout (layout) andservice_dir_wipe_on_start(the FITS driver keeps the folder it was started with). - All-sky URL / refresh (poll loop re-creates).
- CCTV RTSP/snapshot URL (capture pipeline re-spawns).
- PHD2 host / port (JSON-RPC connection re-opens).
- Planetarium (Cartes du Ciel) host / port (TCP socket re-opens).
- Web server host / port, and the dashboard auto-open mode (only a restart re-binds the listener).
- Health monitor poll interval / thresholds / restart policy (the monitor thread reads these at start).
- Diagnostics ring-buffer size (installed once at startup).
- Any ASCOM
prog_idor Alpaca host/port/device change, for any of the nine device roles (mount, camera, guide camera, rotator, focuser, filter wheel, observatory, power switch, flat device). The Chooser/Pick buttons re-save and trigger a reconnect, but a restart is the clean way to fully re-init a transport. The ASCOM/Alpaca poll interval and the ASCOM liveness-watchdog timeout are also captured at start.
- Scripts / Plugins — the external-script sandbox and the plugin loader initialise at startup; enabling either, or changing the allowed/plugins directory, needs a restart.
- Sequencer plans directory.
- Death watch (
[deathwatch], Settings → Crash protection → If Starship stops unexpectedly) - the helper's plan is written when Starship starts. See the Windows restarts and crashes topic. - ASCOM / Alpaca weather sources (
[weather],[safety] primary_source, and thesafetymonitor/observingconditionsdevices) - the sources are built when the service starts. See the AAG CloudWatcher (Solo) topic. - Blockscript engine settings.
- Observatory enclosure type — set in Settings → Observatory,
roll_off(default) ordome. A roll-off roof needs no azimuth tracking; switching to dome unlocks ASDM slit slaving and the Dome page (see the Dome topic). Restart after changing it so the dome subsystem binds cleanly.
If unsure, use Save+Restart.
Where the newer knobs live
Autofocus ([autofocus])
The autofocus tunables all live in Settings → Autofocus and are live on save (re-read on every Refocus and every Focus Wizard run). The learned calibration is not in Settings; First Light writes the refocus formula — the V's slope, the focuser's backlash and the over-travel that clears it, the last focus — to focus_recipe.json next to config.toml. See the dedicated Autofocus topic for what each knob does, the current Wizard/Refocus model, and the recommended tunings — that page is the source of truth for this section.
Rotator travel limits ([rotator])
Settings → Rotator. min_position_deg and max_position_deg are mechanical degrees (what the rotator itself reports, not sky angle). The allowed arc runs from min up to max and may wrap through zero: min 270 and max 90 allows 90° either side of zero. Blank = no limit. Every rotator move stays on the arc, rotate-to-position-angle included. See the Field rotator topic.
Plate-solve sync limit ([pointing])
Settings → Mount → Do not sync a solve further away than (°) (max_sync_distance_deg, default 10; 0 = no limit). A plate solve further than this from where the mount says it points is not synced to the mount. Blind sync is exempt. See the Plate solving topic.
A failed start-up step asks first ([performance])
start_prompt_timeout_s (default 0 = do not ask). When above 0, a failed on_start action of a stand-alone sequence asks Try again? in the run view and waits this many seconds before it cancels. See the Sequencer topic.
Manual actions and the weather
When you ask for one of these yourself from the dashboard while safety reads UNSAFE or UNKNOWN, Starship refuses and asks you to confirm:
- unpark the mount,
- slew the mount,
- open the flat cover,
- rotate the dome to an azimuth.
The message names the safety state and its reason. Cancel leaves the rig as it is. OK sends the command again with the safety check overridden; the override is written to the log. Confirm only when you know the rig is protected (the roof is closed, or you are watching the sky).
Nothing is checked in manual mode ([safety] enabled = false). Park, close and cover-close are never held back. The sequencer, blockscript and scheduler do not pass through this check: they follow safety by their own rules.
Fields removed in v23
These were shown in Settings but no code read them. They are gone from the page. An old config.toml that still has the keys loads without error; the keys are dropped the next time the file is saved.
- The whole Telescope tab.
- The Planetarium page in the left nav (it only said "not yet implemented"). Cartes du Ciel is still set up in Settings → Cartes du Ciel and used from the Console and the sequence editor.
- Mount: park on disconnect, custom park altitude / azimuth, slew rate preset.
- Polar: the three motorised-adjuster fields.
- Cooling: auto-setpoint fallback, and the old
cool_down_ramp_min(useramp_minutes). - Autofocus: the engine choice and the resolution preset.
- Sequencer: the journal size.
- Blockscript: resume scope, resume dwell and max resumes (the Safety supervisor's dwell decides when a session re-opens; weather resumes are not capped).
What is in each equipment section
- Camera (
[camera]) — sensor type and Bayer pattern (FITS headers), focal length and pixel size (image scale, framing, FITS headers, the plate-solve scale check), default gain / offset / binning, the plate-solve gain and binning overrides, the download timeout, the FITS-header options and the wait after a filter change.camera_position_angle_degis updated automatically from the last plate solve. - Focuser (
[focuser]) — the travel limits (in_limit_steps/out_limit_steps),reverse_direction, the position-check tolerance, the wait after a move,dont_halt_on_halt_alland the general (non-AF) backlash.step_size_jogpre-fills the Console's relative-move box. Themeasured_backlash_/characterization_fields are not user knobs — approving First Light's focuser report ("Use the measured backlash for manual moves") writes them here (with the full curve report as JSON) so the measured characterisation is visible in Settings and travels with saved profiles. First Light's refocus uses the measured backlash without that approval. - Mount (
[mount]) — the slew, tracking-on-connect, and meridian-flip defaults (includingflip_pier_side_checkand the recenter-after-flip options);precess_targets(v22.2.0, J2000 targets converted to the mount's frame) is config-file only. - Cooling (
[cooling]) — the setpoint / settle / warm-up fields and the ramp (ramp_minutes/ramp_step_s/no_cooldown_for_delta_c).
Backups
Every save first copies the current config.toml to config.toml.bak. One level deep — saving twice in a row overwrites the bak. If a backup write fails (e.g. permissions) it's logged but the save still proceeds. For real history, keep config.toml in version control.
Validation
validate() runs before any write. If it returns errors, the save is rejected and nothing is written. Common failures:
- Port outside 1..65535 (web / PHD2).
- Required field missing (e.g.
solo.host, an all-sky URL when all-sky is enabled, a CCTV camera with neither RTSP nor snapshot URL). - Web Basic Auth enabled without a username or a valid
pbkdf2_sha256$…password hash (fails closed rather than shipping broken auth). - Inconsistent values, e.g.
solo.timeout_s >= solo.poll_interval_s;cooling.ramp_minutes + settle_dwell ≥ timeout_settling_min;autofocus.max_hfd_allowed < near_focus_hfd;autofocus.vcurve_limit_hfd <= near_focus_hfd; an out-of-rangeautofocus.binning(must be 1–4) orcentral_region_pct. - Auto Flat out of range: an unrecognised
flat.flat_type(must bepanel,manual,sky_dusk, orsky_dawn), a non-positivetarget_adu, amax_err_pctoutside (0, 100],max_exposure_s < min_exposure_s, or acalc_roi_pctoutside 1–100. - Frame acceptance gates below 0 (each gate is 0 = off), or a
central_region_pctoutside 1–100. Guiding watchdogrms_max_px/recover_timeout_sbelow 0 or a non-positivepoll_interval_s.
- A
config_versionnewer than this build supports. The current schema version is 3.
Validation errors are displayed inline with the section that triggered them, and Save is blocked until they're fixed.
Environment overrides
A handful of sections (solo, safety, web, audit, phd2, allsky) can be overridden at launch with STARSHIP_<SECTION>_<KEY> environment variables (e.g. STARSHIP_SOLO_HOST=192.168.1.42). These apply on load, on top of whatever is in config.toml. They are not written back to the file, so the Settings page shows the file value, not the override — keep that in mind if a launched value doesn't match what Settings displays.
How it ties into the rest of Starship
- The same
config.tomlis read at process start by the runner and rebuilt on every in-process restart, so Settings is the single source of truth for the whole service. - Equipment profiles (Settings → equipment) are saved/loaded copies of
config.toml; activating a profile copies it over the active file and triggers the same restart path. - Alerts have their own save endpoint (
/api/alerts/config) so the SMTP password is never echoed back to the browser; a blank password field keeps the stored one.