necst.core.operator_actions

Shared operator action layer for NECST operator-facing tools.

This module intentionally contains command semantics, not GUI or CLI formatting. Terminal commands and the future Operator Console should call these functions so that STOP, ABORT, mount move, and chopper actions use the same validation and Commander calls.

class OperatorActionResult(action, success, message='', data=<factory>)[source]

Bases: object

Result returned by an operator action.

Parameters:

  • action (str) – Stable action name, e.g. "antenna_stop".

  • success (bool) – True if the requested action completed or was accepted.

  • message (str) – Operator-facing summary.

  • data (Dict[str, Any]) – Machine-readable details for CLI/Web callers.

action: str
success: bool
message: str = ''
data: Dict[str, Any]
exception OperatorActionError[source]

Bases: RuntimeError

Raised when an operator action is rejected before it can be sent.

exception OperatorActionTimeout[source]

Bases: TimeoutError

Raised when an operator action was sent but completion was not observed.

class OperatorAuthoritySession(*, dry_run=False)[source]

Bases: object

Hold NECST privilege for a long-lived operator console session.

This is intentionally small: it owns exactly one Commander instance and releases/destroys it explicitly. It is useful for direct Commander actions such as mount move and chopper commands. File-based observation launchers run in separate processes and therefore must not be started while this process is holding privilege for them.

Parameters:

dry_run (bool) –

property commander: Commander
property held: bool
property identity: Optional[str]
acquire()[source]
Return type:

OperatorActionResult

release()[source]
Return type:

OperatorActionResult

antenna_stop(*, confirm_timeout_sec=1.0, settle_sec=0.0, commander=None)[source]

Send the bounded antenna STOP request.

This is the safety STOP path. It does not perform observation cleanup.

Parameters:

  • confirm_timeout_sec (float) –

  • settle_sec (float) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

abort_observation(*, reason='operator requested abort', requester='necst abort', antenna_stop_after_abort=True, repeat=3, interval_sec=0.1, settle_sec=0.2, commander=None)[source]

Request cooperative observation abort.

This publishes the observation-abort request and, by default, also sends the bounded antenna STOP request so blocking point/scan waits return promptly.

Parameters:

  • reason (str) –

  • requester (str) –

  • antenna_stop_after_abort (bool) –

  • repeat (int) –

  • interval_sec (float) –

  • settle_sec (float) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

mount_move(az_deg, el_deg, *, wait=True, timeout_sec=None, dry_run=False, commander=None)[source]

Move to explicit mount mechanical Az/El.

Input Az/El are mount mechanical coordinates in degrees. The command sent to Commander is always direct_mode=True and az_target_mode="mount". Az=360 is therefore a mount angle, not automatically wrapped to zero.

Parameters:

  • az_deg (Any) –

  • el_deg (Any) –

  • wait (bool) –

  • timeout_sec (Optional[float]) –

  • dry_run (bool) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

chopper_status_matches(msg, target_position, target_insert)[source]

Return True if chopper telemetry confirms the requested endpoint.

Parameters:

  • msg (Any) –

  • target_position (int) –

  • target_insert (bool) –

Return type:

bool

format_chopper_status(msg)[source]

Return operator-facing chopper state and detail string.

Parameters:

msg (Any) –

Return type:

tuple[str, str]

wait_chopper_position(com, target_position, target_insert, timeout_sec)[source]

Wait for chopper status to reach target position/flag with a timeout.

Parameters:

  • com (Commander) –

  • target_position (int) –

  • target_insert (bool) –

  • timeout_sec (float) –

Return type:

Any

chopper_status(*, timeout_sec=10.0, settle_sec=0.2, commander=None)[source]

Read chopper telemetry without sending a command.

Parameters:

  • timeout_sec (float) –

  • settle_sec (float) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

chopper_move(position, *, wait=True, timeout_sec=10.0, settle_sec=0.2, repeat=3, interval_sec=0.1, commander=None)[source]

Move the chopper IN or OUT through the shared Commander path.

Parameters:

  • position (Literal['in', 'out']) –

  • wait (bool) –

  • timeout_sec (float) –

  • settle_sec (float) –

  • repeat (int) –

  • interval_sec (float) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

chopper_maintenance(command, *, settle_sec=0.2, commander=None)[source]

Run a chopper maintenance service request.

Parameters:

  • command (Literal['alarm-reset', 'home', 'recover']) –

  • settle_sec (float) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

start_target_tracking(kind, *, name=None, coord1=None, coord2=None, offset_frame='target_frame', offset_x_arcsec=0, offset_y_arcsec=0, cos_correction=True, wait=False, timeout_sec=None, dry_run=False, commander=None)[source]

Start target tracking through the shared Commander path.

kind selects one of: sun, moon, name, radec, galactic. RA/Dec and Galactic coordinates are validated in degrees; RA also accepts sexagesimal hour notation. Offsets are accepted in arcsec and converted to degrees before calling Commander.

Parameters:

  • kind (Any) –

  • name (Any) –

  • coord1 (Any) –

  • coord2 (Any) –

  • offset_frame (Any) –

  • offset_x_arcsec (Any) –

  • offset_y_arcsec (Any) –

  • cos_correction (Any) –

  • wait (bool) –

  • timeout_sec (Optional[float]) –

  • dry_run (bool) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

stop_tracking(*, confirm_timeout_sec=1.0, settle_sec=0.0, commander=None)[source]

Stop target tracking by using the same bounded antenna STOP path.

Parameters:

  • confirm_timeout_sec (float) –

  • settle_sec (float) –

  • commander (Optional[Commander]) –

Return type:

OperatorActionResult

check_obs_file(mode, file_path, *, channel=None, require_exists=True, use_neclib_parser=True)[source]

Check an observation file without touching telescope hardware.

This performs static validation, v16 default expansion, reference-file checks, and an optional neclib mode-specific parser pass. It never moves the antenna/chopper, starts recorder/gate, applies SG settings, or queues an observation.

Parameters:

  • mode (Any) –

  • file_path (Any) –

  • channel (Any) –

  • require_exists (bool) –

  • use_neclib_parser (bool) –

Return type:

OperatorActionResult

dry_run_observation(mode, file_path, *, channel=None, require_exists=True, use_neclib_parser=True)[source]

Build a read-only observation execution-plan preview.

The dry run is intentionally static: it returns the likely sequence, v16 defaults, reference-file status, and rough timing information, but sends no mount/chopper/recording/gate/SG commands and does not queue observation execution.

Parameters:

  • mode (Any) –

  • file_path (Any) –

  • channel (Any) –

  • require_exists (bool) –

  • use_neclib_parser (bool) –

Return type:

OperatorActionResult

start_observation(mode, file_path, *, channel=None, background=True, dry_run=False, check_exists=True, stdout_path=None, stderr_path=None)[source]

Start a file-based observation through the existing NECST launcher.

mode

One of otf, psw, grid, or radio_pointing.

file_path

Path on the NECST computer. In live mode this must exist and be readable.

channel

Optional positive integer spectral-channel override.

background

True starts a separate process and returns immediately. This is the intended mode for the web Operator Console so the HTTP request is not held until the observation finishes.

dry_run

Validate and report the exact command without starting a process.

check_exists

File existence/readability validation. Keep True for live start; tests and UI dry-runs may set False only when no command is sent.

Parameters:

  • mode (Any) –

  • file_path (Any) –

  • channel (Any) –

  • background (bool) –

  • dry_run (bool) –

  • check_exists (bool) –

  • stdout_path (Any) –

  • stderr_path (Any) –

Return type:

OperatorActionResult

run_rsky(*, n=1, integ=2, channel=None, background=True, dry_run=False, stdout_path=None, stderr_path=None)[source]

Run an RSky calibration action through the existing launcher.

Parameters:

  • n (Any) –

  • integ (Any) –

  • channel (Any) –

  • background (bool) –

  • dry_run (bool) –

  • stdout_path (Any) –

  • stderr_path (Any) –

Return type:

OperatorActionResult

run_skydip(*, integ=2, channel=None, tp_range=None, background=True, dry_run=False, stdout_path=None, stderr_path=None)[source]

Run a SkyDip calibration action through the existing launcher.

Parameters:

  • integ (Any) –

  • channel (Any) –

  • tp_range (Any) –

  • background (bool) –

  • dry_run (bool) –

  • stdout_path (Any) –

  • stderr_path (Any) –

Return type:

OperatorActionResult

previous

necst.core.observation_check

next

necst.core.recorder