Blockscript
The safety-automation scripting engine. A blockscript defines a whole unattended observing session as a state machine: it brings the observatory up, runs the night, reacts to weather and device failures, and tears everything down to a safe state — all without a human present. It is the layer that turns "the sky went unsafe" into "park, close the roof, warm the cooler, notify, and stand by."
A blockscript is built from short, named action lists — one per state. The engine moves between states in response to events (safety verdicts, device health, body completion, manual overrides) and runs the matching action list on entry to each state.
What it is
A blockscript runs as a state machine on its own thread (BlockscriptEngine). Each state has an associated action list that runs once on entry to that state. Only one blockscript runs at a time — the observatory is a single resource, and BlockscriptManager enforces this.
States
- IDLE — nothing running (initial / no engine).
- STARTUP — runs the
startuplist. If all actions succeed, flows to RUNNING; if any required action fails, flows to EMERGENCY. The list stops at its first failed action (v23.1.2): the rest of it is not run, so a start-up whose devices did not connect never opens the roof, and the mount is never unparked under a roof that refused to open. One exception to EMERGENCY: when the only thing that failed is opening the roof (or unparking) and safety is not SAFE, the weather turned during start-up - the session goes to UNSAFE (make safe, wait) and RESUME opens and unparks when it clears. - RUNNING — the session body. Reached after startup and after every successful recovery/resume.
- WARNING — tier 1. A soft problem (safety WARNING/UNKNOWN, or a recoverable device loss). The engine waits and tries to recover; it does not tear down.
- UNSAFE — tier 2. Safety verdict is UNSAFE. The engine pre-empts the session now and puts the observatory in a safe state. Can later RESUME.
- RESUME — transient. Entered only when it is safe again (the Supervisor's own sustained-safe dwell already served), it is dark enough to re-open, and resume is not held. Re-entry is unlimited (bounded by the absolute dawn deadline, not a cap). Immediately flows back to RUNNING (incrementing the resume counter).
- SHUTDOWN — runs the
shutdownlist, then flows to DONE. - EMERGENCY — reachable from any state. Runs the
emergency(safe-state) list, then either auto-returns to RUNNING (if allowed and the safe-state actions succeeded) or halts. - DONE — terminal, clean. The session finished normally.
- HALTED — terminal, safed, awaiting a human. The session hit an unrecoverable condition but the observatory was put in a safe state first.
Happy path: STARTUP -> RUNNING -> SHUTDOWN -> DONE. From RUNNING the engine can divert to WARNING, UNSAFE (then back via RESUME), or EMERGENCY at any time. A session ends at dawn even when its body has not finished (the dawn deadline); tick Run again every night to have it start again the next evening (see Run again every night below).
How to use it
You author a blockscript object with a name and one action list per state name (startup, running, warning, unsafe, resume, shutdown, emergency). Each list is a list of action dicts. A minimal action is {"type": "<action>", ...params}.
The engine is event-driven. Once started it:
- Enters STARTUP and runs the
startuplist. - On success, enters RUNNING and runs the
runninglist. - Reacts to events posted from the rest of Starship (safety ticks, device-lost/recovered, body-done) and to manual overrides (force emergency / force shutdown / hold resume).
You normally don't drive the engine by hand — BlockscriptManager.start(blockscript) wires it to the safety bus and runs it. The manager exposes force_emergency(), force_shutdown(), hold_resume(held), status(), and stop().
Example block
name: "deep_sky_night"
startup:
- type: unpark
- type: open_roof
- type: cool_to
target_c: -10.0
policy:
retry_count: 2
wait_s: 30
on_error: emergency
- type: run_sequence
sequence: "M51_LRGB"
running:
- type: notify
severity: info
message: "Session running"
warning:
- type: notify
severity: warning
message: "Conditions degraded - holding"
unsafe:
- type: abort_exposure
- type: park
- type: close_roof
resume:
- type: unpark
- type: open_roof
shutdown:
- type: park
- type: close_roof
- type: warm_cooler
- type: notify
severity: info
message: "Session complete"
emergency:
- type: abort_exposure
- type: park
- type: close_roof
- type: warm_cooler
- type: notify
severity: critical
message: "EMERGENCY safe-state engaged"
Action types
Every action type maps to a _do_<type> handler on the runner, which calls a real Console method. Unknown types fail with unknown action '<type>'. An action that raises is caught and reported as a failure — it never crashes the engine.
Mount
- park —
mount_park, then the mount'sAtParkis read back. A mount that reads back not parked fails the action and sends one critical notification. A mount that cannot report its park state is trusted on its acknowledgement. - unpark —
mount_unpark, then read back. A mount that still reads parked fails the action (with a warning), so a startup or resume does not go on to image with a parked mount. - find_home (new in v23) — the mount's own FindHome seek (the same as the sequence action of that name), then waits for it: until the mount reports AtHome, or is idle again. Optional
timeout_s(default 180). A mount that reports nothing back is trusted on its acknowledgement. (mount_homeis a different action: it sends the mount to its zero position without a seek, works only on mounts whose driver offers it, and is not a park.)
Dome
New in v23. The dome's shutter is open_roof / close_roof (the same shutter). These four add what a dome night needs around it.
- dome_slave — switches slit slaving on and reads it back. Fails if slaving did not start. Put it in startup and resume, after the shutter is open.
- dome_unslave — switches slaving off and reads it back. Fails if the dome still reports slaved. Put it before the make-safe moves.
- dome_park — parks the dome's rotation and waits until the dome reports AtPark. This drops slaving. Optional
timeout_s(default 180). - dome_home — rotates the dome to its home azimuth and waits until it stops moving. This drops slaving. Optional
timeout_s(default 120). A dome already at home succeeds at once.
dome_slave needs the enclosure type set to dome (see the Dome & ASDM slaving topic). Dome motion can only be proven on a real dome: run a new blockscript supervised the first time.
Roof
- open_roof —
roof_open, then the shutter is read back; a shutter that reads back not open fails the action (with a warning), and one that cannot report is trusted on its acknowledgement. The Console refuses to open unless the verdict is SAFE — not during the Safety Supervisor's dwell (WARNING) either — and the hardware refuses too (the roof is hardwired to CloudWatcher). An open while the shutter is already opening is accepted; an open while it is closing is refused (an open never reverses a close). - close_roof —
roof_close. Behaviour depends onobservatory.roof_motion_requires_safe_mount:
- False (default) — mounts clear the roof in any position, so it closes regardless of park state (confirm_unparked=True). - True — it parks first, then closes. If the park fails it still closes (safety beats optics) but sends a critical notification. - After the command the shutter is read back (shutter_status == 1, Closed). A shutter that reads back not closed fails the action and sends one critical notification noting that the hardware interlock still applies. A roof that cannot report its state is trusted on its acknowledgement. The close command itself is always sent; it is never held back waiting on a read-back. - A close is never refused because the shutter is moving. If it is already closing (the enclosure's own controller can close on its own weather vote a moment before Starship does) the close counts as under way and is verified; if it is opening, the close is sent anyway (with AbortSlew first if the driver refuses it mid-open). A close that was not accepted but whose shutter reads closing or closed is verified, not reported as a failure.
Flat cover
A sequence that runs inside a blockscript skips its own observatory actions, the flat-cover open/close included, so on a supervised night the blockscript owns the cover: open it at the end of startup, close it in shutdown. On a shared roof the cover and the mount park are this telescope's own protection.
- open_flat_cover —
flat_cover("open"), then readsCoverStateback from the device (up to 90 s; a WandererCover takes 10–20 s). A cover that does not read back open fails the action and sends a warning (a closed cover means a night of black subs — in startup that failure goes to EMERGENCY like any other startup failure). - close_flat_cover —
flat_cover("close"), then readsCoverStateback. A close that does not read back closed fails the action and sends one critical notification, exactly likeclose_roof. - Both: a driver that cannot report the position (no readback, Unknown) is trusted on its acknowledgement, with a note. A rig with no flat device configured, or a light-only panel with no motorised cover, gets a note — never a failure — so a shutdown or emergency list does not climb the failure ladder over a cover it does not have. A flat device that is configured but not connected fails (its cover state is unknown); for a close that is a critical too, as for
close_roof. - The panel light is a different function:
flat_light_on/flat_light_off.
Power and connection
For a rig whose gear sits behind a switchable power box (a Pegasus, for example). connect_power / disconnect_power connect the power device only; power_on / power_off take the switch id (channel; the editor lists the switches by name once the power device is connected) — power_off is the dangerous direction and is sent with the console's off-confirmation. connect_all / disconnect_all connect / disconnect every configured device except power, so the power device brackets the rest: on a cold start power comes up first and goes down last.
Guiding
- start_guiding — starts PHD2 guiding and waits for it to settle. Optional parameters:
exposure_s(guide exposure),fresh_star(default true: pick a new guide star first),settle_px,settle_time_s,settle_timeout_s(default 60). It fails when PHD2 is not connected or[phd2] allow_controlis off, and when PHD2 finds no star or does not settle in time. While a sequence is running or paused it is skipped with a note, because the sequence starts and manages its own guiding. - stop_guiding — does nothing, on purpose, and reports success with a note. The engine itself stops guiding before the park and close on every make-safe (UNSAFE, EMERGENCY, SHUTDOWN); a stop from an ordinary list would pull guiding out from under a running sequence.
Cooler
- warm_cooler — warms the camera, then switches the cooler off; it waits until that is done, so put it first in shutdown, before power-down. Optional params:
- target_c (°C) and minutes — the gentle warm-up: the setpoint is ramped from the sensor temperature up to target_c over minutes (blank = the [cooling] ramp_minutes default, 0 = set it in one step), the action waits for the sensor to get there — at most minutes + [cooling] warm_up_timeout_min — and then switches the cooler off. On a night colder than the target the sensor cannot get there (a cooler cannot heat above the air temperature): once the ramp is done and the sensor has stopped rising for three minutes with the cooler idle, the cooler is switched off and the action succeeds with a note (v23.1.2; it used to wait out the whole time limit). A cooler that is already off, or a sensor already at the target, is just switched off. The typical shutdown uses 15 °C over 10 minutes. - No target_c — the old behaviour, unchanged: cooler_warm_up with the [cooling] settings, which with no warm_up_target_c simply switches the cooler off.
- cool_to —
cooler_ramp_to(target_c). Paramtarget_c(float, default 0.0) is the setpoint in degrees C. Optionalminutes(float) ramps down over that long (e.g. cool to −10 over 5 minutes to spare the sensor from thermal shock); omit it (or leave it blank) to use the cooler's configured default ramp rate. It also checks that the cooler really cools: one that reads on but draws 0 % while the sensor sits well above the setpoint is switched off and on once (see Camera cooling).
Capture
- abort_exposure —
capture_abort. Stops the in-progress exposure; use it first in unsafe/emergency lists so the mount/roof can move.
Sequences
- run_sequence — runs a named sequence via
Console.run_sequence. Paramsequence(required; empty name fails). As of v20.9 this is really wired: the Console loads + compiles the named plan from the plan library and starts it as an injected (supervised) run — the sequencer skips observatory-domain phase actions (roof/mount/park) because the blockscript owns them. A missing/unknown plan, a disabled sequencer, or a busy sequencer returns a clear failure (not a silent success), so anon_errorpolicy can retry orgoto. On success the injected run signalsbody_donewhen imaging finishes, moving RUNNING -> SHUTDOWN. See the Sequencer topic.
Scheduler
- run_scheduler — launches the dispatch Scheduler as the session body. The session's shutdown stops the dispatcher, so with Run again every night this action starts it again each evening (the target list and its progress persist in
scheduler.db; a second start while it runs is reported as success, never a second dispatcher). Put it in the running list to turn a blockscript into an unattended campaign runner: the dispatcher images the best eligible target every clear, dark, safe night — swapping targets through your per-target recipes — until every active project's goals are filled, then it signalsbody_done(RUNNING -> SHUTDOWN). It is non-blocking and idempotent-ish: if the dispatcher is already running the action reports success rather than erroring. Optional paramschedule(a saved-schedule name) loads that saved schedule into the target pool first, so one auto-starting blockscript can pull up the right campaign after a restart; omit it (or leave it blank) to run whatever projects are already loaded. (If the dispatcher is already running when ascheduleis given, the current pool is kept and the named schedule is ignored — it won't yank targets out from under a live run.) Loading a schedule replaces the pool and starts it at 0 frames, so on the second and later nights of a Run again every night session the schedule is not loaded again — the pool and its progress carry over from night to night. (A session started by hand or by Auto-start on boot is a first night and does load it.) While the blockscript supervises, each scheduled visit runs as an injected sequencer run, so the blockscript keeps the roof/mount/park/safety domain and the scheduler only chooses and images targets. See the Scheduler topic.
Device recovery
- retry_connect — reconnects a device. Param
role(required). Tries theascomthenalpacatransports'connect(role). Used automatically by the engine on device-lost (see below); you can also place it in an action list.
Control flow
- wait — pauses the action list, in one of several modes (param
mode, defaultduration). Every mode is cancellable: it polls a stop/abort event and returns early if the engine is stopping or a manual override is queued.
- duration (default) — sleeps seconds (float, default 0). Back-compat: an action with no mode and just seconds still means a plain sleep. - until_safe — holds until the safety supervisor reports SAFE. With no supervisor configured it returns immediately. - until_time — holds until until. Accepts "HH:MM" (the next local occurrence — so 05:30 waits to tomorrow morning if it's already past) or a full ISO datetime (2026-06-30T22:00). An unparseable value fails the action. - until_dark — holds until astronomical darkness (Sun at/below −18° at the configured site). - until_safe_dark — holds until it is both SAFE and astronomically dark — the natural "open the roof and start imaging" gate. - The gated modes (everything but duration) take an optional timeout_min (float) that caps the wait; on timeout the action fails (so an on_error policy can react). If the site location is unset, the darkness modes can't compute dusk — they skip the darkness half rather than block forever (and still honour the safe half of until_safe_dark).
- notify — sends a notification. Params
severity(defaultinfo) andmessage(default empty). If no notifier is configured it logs instead. Best-effort — always succeeds.
External scripts
- run_script — runs an external command via the shared, sandboxed
[scripts]executor (disabled by default; honoursallowed_dir, a hard timeout, and no-shell). Paramscommand(orscript; required),args,timeout(ortimeout_s),cwd,shell, andfail_ok(treat a non-zero exit as success with a note). The engine's abort event is handed to the executor, so a long script can never delay a manual emergency/shutdown. Escalation on failure is the engine's job — attach apolicyto the action. See the External scripts & plugins topic.
On-fail policy
Every action may carry an optional policy dict. With no policy, behaviour is one attempt; on failure the error is logged and the rest of the list keeps running (the safe-state lists must run to completion — you don't want a failed park to skip the close_roof after it). Policy is opt-in and changes nothing unless present. Fields:
- retry_count (0) — extra attempts after the first before declaring failure.
- wait_s (0.0) — seconds to wait between attempts. The wait is sliced so
stop()and events stay responsive. - notify (false) — on final failure, send a notification describing the failed action.
- on_error (
continue) — what to do after all attempts fail:
- continue (default) — record the failure, keep running the list. - raise / emergency — enter EMERGENCY (both behave identically). - goto — enter the state named in goto (case-insensitive: e.g. SHUTDOWN, unsafe). An unknown target logs a warning and falls through to continue.
- goto — target state name, used only when
on_errorisgoto.
This is a uniform per-action error contract, modelled on ROCK's per-block "On Error" options.
In the editor (v23). Each action row has an on fail strip: retries, wait s, a notify tick box, and then — carry on (the default), EMERGENCY, or go to a state you pick. Leave it alone and nothing is stored. A policy written by hand (for example on_error: raise) is shown and kept, and changing an action's type no longer wipes its policy. An action type the menu does not list is shown and kept as written.
Dry run
New in v23. The Dry run button in the editor walks the blockscript as it is on screen, saved or not, without touching any device. Nothing is sent to the mount, roof, camera, the event bus or a running session.
It shows, for each state (startup, running, warning, unsafe, resume, shutdown, emergency), the actions in the order the engine would run them, with each action's on-fail policy, and marks what would fail:
- an unknown action type,
- a
run_sequencewith no sequence chosen, or naming a sequence that is not saved, - a
wait until_timewith no time, - an on-fail policy that is not valid (a
gototo a state that does not exist, an unknownon_error, numbers that are not numbers).
It warns when startup has no actions, when running has no run_sequence or run_scheduler, when the unsafe, emergency or shutdown list has no park, close_roof or close_flat_cover, when startup opens the roof with no safety wait before it, and when a run-again-every-night script does not begin with wait until_safe_dark.
It also notes where the engine changes your order: in the make-safe lists park and close_roof run in the order set by [observatory] park_before_roof_close, and guiding is stopped first.
A dry run checks the script, not the rig. It cannot tell you whether a device will answer, whether the weather will be SAFE, or how long anything takes. Use Check plan for the wider pre-flight check.
Emergency and force-emergency
EMERGENCY is reachable from any state and is where the observatory is forced to a safe state:
- How it's reached: startup failure; an action policy with
on_error: raise/emergency; a device lost beyond the retry cap; or a manual force_emergency override. - On entry the
emergencyaction list runs (your safe-state sequence: abort, park, close roof, warm cooler, notify). - Then
_do_emergencydecides: ifemergency_auto_returnis enabled, the recovery count is withinmax_recovery_attempts, and the safe-state actions all succeeded, it auto-returns to RUNNING. Otherwise it enters HALTED — safed, awaiting a human. - force_emergency (and force_shutdown) are manual overrides that win in any state.
BlockscriptManager.force_emergency()/force_shutdown()post these.
Run again every night
A session always ends at dawn: the dawn deadline tears it down (SHUTDOWN -> DONE) even while the scheduler still has work, and DONE is terminal. For a campaign that takes several nights, tick Run again every night until the scheduler's goals are complete in the editor (repeat_nightly = true on the blockscript). Then:
- When the night ends — the dawn teardown (a running session reaching dawn, or a weather suspend that lasted until dawn), or a startup weather hold that gave up because the weather never cleared — the session runs its shutdown list as usual, and the manager starts the same blockscript again (the saved copy of that name, so an edit saved during the day takes effect). It is journalled and notified: session ended at dawn - starting again for the next night (night 2); the status shows the night number.
- The next night's startup holds it through the day: it must begin with
wait until_safe_darkwith timeout 0 (no timeout). A timeout shorter than a day would expire in the afternoon and fail the startup into EMERGENCY — Ask Pete warns about this. Nothing is powered or connected during the hold. - It does not start again when the session body is complete (the scheduler reports all goals done — checked again at dawn), when the session ended in EMERGENCY / HALTED, when you pressed Force shutdown or Force emergency (at any point, including during the day hold), on any other kind of shutdown (a stopped sequence body, an on-error goto, the 12 h weather-suspend ceiling), or when the blockscript was deleted, renamed or had the option switched off. You are notified why.
- The scheduler: the shutdown stops the dispatcher and
run_schedulerstarts it again each night; its ledger lives inscheduler.db, so progress carries over. A namedscheduleis only loaded on the first night. - Never two at once: the restart waits for the finished session's thread, re-checks that nothing else was started in between, and never follows the previous night's start by less than an hour.
A typical multi-night blockscript for a rig whose gear sits behind a switchable power box, with the scheduler's Manage roof on (the scheduler opens the roof and unparks when it is dark and safe, and parks and closes at dawn, on unsafe and when the goals are done) — this is what + add typical fills in:
repeat_nightly: true
startup:
- wait: until_safe_dark, timeout_min 0 # holds through the day
- connect_power
- power_on: channel 0 # e.g. "Quad Power"
- wait: 25 s # let the devices enumerate
- connect_all
- cool_to: target_c -10, minutes 5
- open_flat_cover
running:
- run_scheduler
shutdown:
- warm_cooler: target_c 15, minutes 10 # gentle, waits, then cooler off
- close_flat_cover
- park
- close_roof
- disconnect_all
- power_off: channel 0
- disconnect_power
How safety ties in
BlockscriptManager.start() subscribes to the safety.state_changed bus event and bridges each verdict into the engine via on_safety(state). The engine reacts to SafetyState:
- UNSAFE — from RUNNING/WARNING/RESUME, enter UNSAFE and run the safe-state list. Clears the safe-since timer.
- WARNING or UNKNOWN — from RUNNING, enter WARNING (UNKNOWN fails toward caution, treated as at-least WARNING). Does not relax an existing UNSAFE.
- SAFE — from WARNING, return to RUNNING ("safety cleared"). From UNSAFE, attempt resume.
Resume guards (leaving UNSAFE)
_maybe_resume only promotes UNSAFE -> RESUME when all hold:
- It is safe again. The environmental anti-flap dwell is owned by the Safety Supervisor (asymmetric debounce: instant suspend, but it holds WARNING until the raw reading stream has been continuously clean-safe for its own dwell), so a SAFE verdict reaching the engine already means sustained-safe — the engine adds no second hold of its own. The dwell is Settings → Safety supervisor → UNSAFE → SAFE dwell.
- Resume is not held by an operator (
hold_resume(True)). - It is dark enough to re-open (the roof must not re-open onto a daytime sky; skipped when the site is unset).
Weather re-entry is UNLIMITED — an unstable night keeps recovering as long as it stays dark. The never-clears case is owned by the absolute next-dawn deadline (weather_suspend_dawn_alt_deg), not an attempt cap: if the sky stays UNSAFE until dawn, the engine escalates to a verified teardown (SHUTDOWN -> warm/park/close -> DONE) and notifies.
The engine also re-checks resume on its idle tick (every ~0.5 s) — and checks the dawn deadline there too — so neither depends on a fresh safety event arriving.
Device health
on_device_lost(role) / on_device_recovered(role) feed device health in. As of v20.9 the manager wires these for you: it subscribes to the equipment.device bus event and bridges each snapshot into the engine. A loss (connected False with an error from a failed poll) escalates; a deliberate disconnect (connected False, no error) is ignored so you can take a device offline without tripping EMERGENCY; healthy polls are de-duplicated so a steady device never spams recovery. On a loss the engine increments a per-role retry counter:
- Within
device_loss_retry_cap(default 3) — enter WARNING and fire aretry_connectfor that role. If it reconnects, clear the counter and return to RUNNING. - Beyond the cap — enter EMERGENCY (
device unrecoverable).
body_done (posted via signal_body_done()) moves RUNNING -> SHUTDOWN ("session body complete"). A supervised run_sequence posts this automatically when imaging finishes; if it arrives while transiently in WARNING/UNSAFE/RESUME it is latched and applied on the return to RUNNING, so a finished session never hangs past dawn.
The safety model for this site
These hardware facts shape why the engine is "command-and-report" rather than a hard gate:
- The roof is hardwired to CloudWatcher. It physically cannot open against an unsafe verdict. Software here commands and reports; the hardware interlock is the real guarantee.
- Mounts clear the roof in any position, so closing the roof does not require parking first — unless
observatory.roof_motion_requires_safe_mountis True. - Actuation is read back where the driver can report it. Close and park re-read the driver's state; a definite mismatch fails the action with a critical notification, and a driver that cannot report is trusted on its acknowledgement. The close command is never held back: better to close against an unconfirmed read-back than to leave the roof open.
Config knobs
On config.blockscript:
- device_loss_retry_cap (3) — device-lost retries (WARNING + retry_connect) before EMERGENCY.
- auto_start (empty) — name of a blockscript to relaunch automatically when Starship starts (set from the ⟳ Auto-start on boot selector on the Blockscripts page). On startup the service waits on a background thread for a first safety verdict, then starts that blockscript — so an interrupted unattended campaign resumes (the scheduler ledger persists across the restart). Note: this only fires once Starship's process is running; on a fresh power-up something at the OS level (a Windows startup task/service) still has to launch Starship first.
On the blockscript object itself:
- weather_suspend_dawn_alt_deg (-6.0) — Sun altitude (civil dawn) at which a never-clearing weather suspend ends the session with a verified teardown + notify. It is also when a running session ends its night and runs Shutdown. In the editor this is End the night (run Shutdown) at: civil dawn (−6°), nautical dawn (−12°) or just after astronomical darkness ends (−16°). On a scheduler night with "manage the roof" on, imaging stops, the roof closes and the mount parks when astronomical darkness ends (−18°) whatever is chosen; the choice decides when the rest of Shutdown (cover, camera warm-up, power off) runs.
- startup_wait_for_safe (True) / startup_wait_safe_timeout_min (720.0) — events-masked boot: when the startup list opens the roof, wait for safe darkness first (a storm-time reboot holds the roof shut until safe instead of failing into EMERGENCY), capped by the timeout.
- max_recovery_attempts (2) — EMERGENCY auto-return budget.
- emergency_auto_return (False) — whether EMERGENCY may auto-return to RUNNING at all. If off, EMERGENCY always halts.
- repeat_nightly (False) — Run again every night until the scheduler's goals are complete: after a dawn teardown the session starts again and waits for the next safe, dark night (see Run again every night).
On config.observatory:
- roof_motion_requires_safe_mount (False) — if True,
close_roofparks first (and still closes even if the park fails).
Safety and gotchas
- Safe-state lists must run to completion. Without a policy, a failed action is logged and the list continues — by design, so a failed
parknever prevents the followingclose_roof. Order safe-state lists so the critical close/warm steps come after the ones that merely help. on_error: raiseandemergencyare equivalent — both go to EMERGENCY. There is no "abort the list but stay" option; usegotofor a different destination state.stop_guidingdoes nothing. The engine stops guiding itself on every make-safe.start_guidingis real: it needs[phd2] allow_control = trueand fails if PHD2 cannot settle.- run_sequence runs under supervision. A blockscript's
run_sequencestarts the plan as an injected run, so the sequencer leaves the roof/mount/safety to the blockscript and just images. A bad plan name, a disabled sequencer, or a sequencer already running fails the action cleanly — give it anon_errorpolicy if you don't want a failed start to be merely logged. Requires[sequencer].enabledand a plan in the library. - A read-back mismatch fails the action. A
parkorclose_roofthat reads back wrong is a failed action plus a critical notification, and the list carries on to the next action unless the action has a policy. The hardware interlock remains the real guarantee. - Only one blockscript at a time.
start()refuses if one is already active (any state except DONE/HALTED/IDLE). - A pending Windows restart refuses the start (v23). While Windows has a restart pending, starting a blockscript asks you to confirm, because a forced restart would end the night mid-run. An auto-started blockscript is not started and a critical alert says so. See the Windows restarts and crashes topic.
- Terminal states need a human. HALTED means safed-but-stuck; the engine will not restart itself. DONE is the clean finish — except that with Run again every night a DONE reached at dawn starts the next night's session.
- A repeat-nightly session is live all day. Between nights it sits in STARTUP, holding in its
wait until_safe_dark— Starship refuses to quit while a session is active, so press Force shutdown first (that also ends the repeats; start it again, or let Auto-start on boot do it, afterwards).
How it ties into the rest of Starship
- Safety supervisor — the manager bridges
safety.state_changedverdicts into the engine; the engine's WARNING/UNSAFE/RESUME logic is driven entirely bySafetyState. See the Safety topic. - Console — every action calls a Console method (
mount_park,roof_close,cooler_ramp_to,capture_abort, ...). The engine is the policy; the Console is the hardware bridge. - Sequencer —
run_sequenceinvokes a named sequence as an injected (supervised) run, so the sequencer skips its own roof/mount/park phase actions and leaves them to the blockscript. See the Sequencer topic. - Scheduler — when a blockscript is active the dispatch scheduler runs each chunk as an injected run too (the blockscript owns the observatory; the scheduler only chooses + images targets). Only a
run_sequencebody signalsbody_done; the scheduler's many chunks do not, so a many-target night runs to completion instead of shutting down after the first chunk. See the Scheduler topic. - Bus / Monitor — the engine publishes
blockscript.state({name, state, reason}) andblockscript.action({action, ok, error, attempt}) so the Monitor and audit trail can track the session. A 20-entry state history is kept forstatus(). - Notifications —
notifyactions and failure/readback notices go through the configured NotificationHandler.
What a blockscript does not do
- It does not pick a sequence up mid-way after a restart. A blockscript started again (by hand or by Auto-start on boot) begins from its startup list. A
run_sequencebody starts its plan from the beginning; arun_schedulerbody carries on from the scheduler's saved frame counts. The opt-in resume after a restart is for stand-alone sequences only (see the Windows restarts and crashes topic). - Removed in v23: the resume scope, resume dwell and max resumes fields. Nothing read them. An old blockscript that still has them loads without error and they are ignored.
See the Roadmap topic for the broader list.