Observing

Linear telescope scripts

Open Linear Script between Sequences and Surveys. Create an ordered list of commands, name it, and Save. Load reopens a saved script; Save as copy creates a separate script. Use Run to save and queue the current version. It starts after the active FIFO/calendar operation returns, before another automatic job starts. The ordinary direct-control permissions apply to Run and Resume. Manual execution also uses OBS's existing _command_allowed_for_current_scope and _command_allowed_during_outreach_mode admission checks. A changed command scope or outreach mode pauses the line rather than bypassing those controls. An authorized Real Time reservation continues to permit direct scripts inside that window; it is not treated as an automatic calendar run to wait behind.

Manual mode

Run script in manual mode is visible only to global admins, site owners and telops, and defaults on for them. An explicit off is saved with the script. Other users have this option hidden and off, including when loading an owner's script. Run sends the checkbox value explicitly to Hub. Hub checks the current actor's roles and includes the authorized boolean in the OBS run payload. A missing option does not enable manual mode in Hub or OBS. When enabled, OBS enters manual mode after the current operation finishes and the script passes the existing admission checks. It retains that mode between lines, then restores the preceding mode on completion, pause, STOP or loss of Hub control. An existing device fault/global stop that forces manual mode is preserved. With the option off, the script leaves the current telescope mode alone. Manual-mode exposures do not require a successful IRF90 autofocus sky PA calibration/check. Automatic science and focus exposures retain that requirement.

Command permissions

Dark exposures (single and video), Set rotator field angle, Start rotator and Stop rotator are offered only to site owners, telops, site known users and global admins. Other commands remain available under the existing direct-control permissions. Hub enforces these roles on save, Run and Resume; hiding a control is not the authorization boundary. Calendar runs use the booking creator's roles, and pause with an explicit error before a command that creator cannot execute.

Admin blocks

Global admins can use Add admin block to insert one of the existing calendar Admin Block actions. Hub builds the executable payload from that action; scripts cannot supply an arbitrary raw device command. The block runs in line order on OBS's normal command thread, and action failures pause the script. Restacking retains its existing behavior of submitting work to the calibration worker. Owners, telops and known users do not receive the script Admin Block option.

Pointing and focus

Move to RA and Dec includes Centering exposure, default on. It waits for the slew, runs the existing centering routine, and pauses if centering fails. Turn it off for a plain coordinate slew. Move focuser accepts a direct position or signed relative offset in device steps and waits for verified completion; relative offsets are added to the current position in steps. Small requested moves are sent instead of being skipped by the direct-control deadband.

Exposure commands

Light, dark and Take flat exposures lines include filter, exposure count and duration. Flats use individual illuminated frames and retain flat-frame FITS metadata. Exposure menus use the usual single-frame or video snap-to-grid values; Custom accepts any positive finite floating-point duration without snapping or imposing the menu's upper bound. Saved custom values reopen as Custom. For SmartStack, a custom total uses a final partial frame when needed.

Raw files and local calibration copies

Each light/dark line also offers Add to local calibrations, default off. Its tooltip discourages this because the system manages its own calibrations, and explains that FITS files are produced as normal. Enabling it writes an additional copy of the raw pixels into the selected camera's localcalibrations store: darks use the existing dark folder and lights use a separate lights folder. Native video copies retain the SER/frame spool and capture sidecars. The extra copy is independent of normal raw FITS saving and does not relabel lights as darks.

Save raws is a script-wide option available to all roles, default on. It overrides OBS's normal raw-saving setting for captures made by the script, including nested captures; an explicit off disables the script's raw FITS saving. The observatory configuration is unchanged. On also retains original native video frame spools after processing. Saved scripts and calendar/run snapshots retain these options; older scripts default to on with local copies off.

Camera cooling

Light and dark lines retain their cooling tooltip. Before any light/dark acquisition mode, a cooled camera is explicitly set to its configured nighttime target and capture waits until its measured temperature is within the camera's existing temperature tolerance. STOP cancels this wait. Missing temperature telemetry errors before capture. The script commands the nighttime target and cooling directly; ordinary OBS temperature scheduling does not send competing commands for that camera while the line owns it. The script reports the measured temperature while it cools. A rejected temperature or cooling-enable command pauses the line with its actual driver error, including PICam communication errors, rather than waiting forever for an unapplied request. An already cold sensor does not skip cooling commands. OBS logs line starts, failures, completions and cooling progress, so a resumed line's activity is visible in its foreground console and live logs. The selected camera stays on its night target throughout that exposure line; normal temperature policy resumes afterwards. Existing overheat recovery is retained, other cameras keep their normal policy, and uncooled camera profiles continue without a temperature wait because they have no regulated target. Dark video retains a selected filter when a shutter, darkslide or dark selector can close the optical path; if only a physical dark filter can do that, a conflicting explicit filter is an error.

Cooling emits a heartbeat every 30 seconds with the camera name, measured temperature and nighttime target, including when the temperature has not changed.

Rotator control

Start rotator explicitly enables IRF90 derotation and ongoing field correction to the selected field angle, including in manual mode and before sky PA calibration. It retains the mount's current tracking state; use Set tracking to change that separately. Stop rotator halts movement, disables IRF90 derotation and suspends field correction until another Start. Existing mount slew/Home handoffs, device faults, exposure holds and global Stop still apply. The Start command reports an error on rotators without explicit derotation support; it does not silently substitute a field-angle move.

Camera warming and power off

Warm ramp to warm ready temperature ramps the selected cooled camera over one hour to its configured day-warm temperature (night target plus day-warm degrees). Warm ramp to camera off warms all cameras on the existing shared camera power supply to ambient over one hour, confirms that they have warmed, then switches that supply off. Cameras already warm enough need no warming wait. Actual camera power control is required for the off command; unavailable or failed power control pauses the line rather than substituting connected standby. Both commands report warming progress every 30 seconds. STOP cancels the wait and retains the last commanded temperature without switching power off.

Warm/off state persists after the line and script finish. A subsequent exposure or operator temperature command releases it; after power off, the next exposure restores the shared camera supply and reconnects before acquisition. Setting an operator temperature override or releasing that override also releases the script's temperature hold. Normal policy continues for cameras outside the shared off operation. These temporary holds do not change saved configuration and end on OBS restart.

Target names

Set target name sets the name inherited by later exposures. Entering a name on an exposure also sets that name; later blank exposures inherit it. Named moving-target slews also establish their target name. If no name exists, the editor warns and the run records a warning without blocking acquisition. Names are labels and do not change moving-target ephemerides.

Calendar scheduling

Select Linear Script as the calendar event type and choose a saved script to reserve a run. Existing calendar access, conflict, time-window and billing rules apply. Each reservation contains a snapshot, so later library edits do not change already booked or running instructions. Changing the selected script in a future booking takes a new snapshot.

Progress, errors and Resume

The run list shows queued/running/paused/stopping/stopped/completed status and the line number. Returning to the page automatically loads the active run's saved instructions into the editor, including a calendar run or a run started in another window. The current running row has an accent background and border, and its legend shows Running; a paused row uses a warning highlight and shows the actual error. The highlight follows the durable line index as it advances. Navigating away or closing the browser stops only status reads: OBS continues the script independently. Reopening restores its current state without starting a duplicate run or automatically resuming a genuine error. Choosing New/Load or editing makes a separate draft; View active script returns to the run snapshot. Select any run to inspect every line and its command history. A device refusal, unavailable device, failed ephemeris lookup or exposure error pauses at that line. Resume explicitly retries the line; a multi-exposure line may repeat exposures that completed before its failure. No later line runs automatically after an error. Ordinary direct commands can be used to correct a problem while paused; automatic observing remains held until Resume or STOP.

STOP

STOP removes a queued run immediately. During an ordinary command it waits for that command to finish. During light/dark/flat acquisition or a rotator field-angle move, it sends the relevant device stop and prevents the next line. It does not issue a mount stop while a Home, Park or slew is finishing. The existing global observatory stop still applies. A scheduled script pauses when its reservation ends or is removed, using the existing exposure calendar checks as well.

Coordinates and capture modes

RA is in hours; Dec, altitude, azimuth and field angle are in degrees. Minor planets and comets resolve orbital elements by name at execution, or use elements explicitly loaded in the editor. Positions are resolved at execution time. Major planets use the existing Hub ephemeris service. Exposure modes use the existing single, video, planet and paired speckle capture paths, including their hardware capabilities and requirements. Speckle settings are entered with the existing speckle editor. An explicit Single exposure retains its requested duration, including on the Moon. If the existing daytime exposure limit would shorten it, the command errors instead of silently taking a shorter exposure.

Dark video must be able to close its optical path: an existing darkslide, external shutter, dark selector path or physical dk filter. This is a technical requirement for recording dark video on the supported native live-video cameras, whose live-capture APIs otherwise record illuminated frames. If the camera cannot do this, the line errors before capturing. Dark videos retain dark frame metadata and omit light-frame calibration/plate-solve bookends. A subsequent light video opens the shutter/darkslide again. Missing named filters are errors; the legacy wheel's automatic substitute selection is not used by scripts.

Source and runtime

Hub owns linear_scripts.py, the editor and the durable run journal. Its new PostgreSQL auxiliary tables are installed by runtime schema version 22 through the existing startup migration. SQLite is used only by the established test harness. Programs and acknowledgements are small JSON records; no science files are scanned or hashed by the script feature.

Calendar requests use the existing Arbiter Sequence Session transport with a kind: linear_script snapshot and linear-script:<id> sequence reference. Hub and OBS recognize that marker before normal sequence conversion. Arbiter retains the reservation/snapshot through its existing API; no Arbiter code or schema change is needed.

The neighbouring OBS checkout owns linear_script_runner.py and linear_script_capture.py. The existing foreground OBS control loop runs one script line at a time and prevents a new automatic job or queued direct command from interleaving with a running script. Only the control/status poll runs in another thread, so STOP can reach a blocking exposure. Its API uses the existing Hub control WebSocket; both checkouts add the script service paths to hub_control_protocol.py.

Each run has an OBS session ID. After an OBS restart, an in-flight line is paused for inspection rather than replayed. Completion acknowledgements are idempotent: a lost response can be retried without repeating hardware activity. A transport failure during a run prevents the next line and records a pause when Hub is reachable again.

Deploy/update both existing checkouts and run the normal Hub frontend build and foreground console launchers. No Python package installation, service registration, relocated web assets or new background application is required. Local contract tests do not establish live telescope execution or hardware stop latency; those still require an operator-controlled commissioning run.