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

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:

  1. Enters STARTUP and runs the startup list.
  2. On success, enters RUNNING and runs the running list.
  3. 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

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 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

- 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.

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

Cooler

- 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.

Capture

Sequences

Scheduler

Device recovery

Control flow

- 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).

External scripts

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:

- 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.

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:

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:

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:

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:

Resume guards (leaving UNSAFE)

_maybe_resume only promotes UNSAFE -> RESUME when all hold:

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:

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:

Config knobs

On config.blockscript:

On the blockscript object itself:

On config.observatory:

Safety and gotchas

How it ties into the rest of Starship

What a blockscript does not do

See the Roadmap topic for the broader list.

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