Interfaces (pyobs.interfaces)

Using interface, a Module signals another one, what functionality it provides for remote procedure calls. The base class for all interfaces in pyobs is:

class Interface

Base class for all interfaces in pyobs.

get_capabilities(interface: type[Interface]) → Any | None

Return the capabilities for the given interface, or None.

get_state(interface: type[Interface], *, max_age: float | None = None) → Any | None

Return the last received state for the given interface, or None.

classmethod has_own_state() → bool

True if this interface defines its own state, as opposed to merely inheriting one from a component interface it combines (e.g. ICamera inheriting IExposure’s state). Modules publish state under the interface that actually defines it, so composite interfaces would otherwise be (wrongly) treated as publishing state too.

async wait_for_state(interface: type[Interface], timeout: float = 10.0, *, max_age: float | None = None) → Any | None

Return state immediately if available, otherwise wait for the first update.

Modules need to implement the required interfaces. For instance, if a module operates a camera, it probably should implement ICamera.

IAbortable

class IAbortable

Bases: Interface

The module has an abortable action.

abstractmethod async abort(**kwargs: Any) → None

Abort current actions.

IAcquisition

class IAcquisition

Bases: IRunning, IAbortable

The module can acquire a target, usually by accessing a telescope and a camera.

abstractmethod async acquire_target(**kwargs: Any) → AcquisitionResult

Acquire target at given coordinates.

If no RA/Dec are given, start from current position. Might not work for some implementations that require coordinates.

Returns:

Result with time, ra, dec, alt, az, and an offset in whichever frame the mount supports.

Raises:

• AbortedError – If the acquisition was aborted.

• GeneralError – If a dependency (e.g. the camera) failed.

• ImageError – If the calculated offset was too large or otherwise unusable.

• AcquisitionError – If target could not be acquired within the given tolerance.

state

alias of AcquisitionState

AcquisitionResult

class AcquisitionResult(time: 'Time', ra: 'Annotated[float, Unit.DEGREES]', dec: 'Annotated[float, Unit.DEGREES]', alt: 'Annotated[float, Unit.DEGREES]', az: 'Annotated[float, Unit.DEGREES]', offset_frame: 'OffsetFrame | None' = None, offset_lon: 'Annotated[float, Unit.DEGREES] | None' = None, offset_lat: 'Annotated[float, Unit.DEGREES] | None' = None)

Bases: object

alt: DEGREES: 'deg'>]

az: DEGREES: 'deg'>]

dec: DEGREES: 'deg'>]

offset_frame: OffsetFrame | None = None

offset_lat: DEGREES: 'deg'>] | None = None

offset_lon: DEGREES: 'deg'>] | None = None

ra: DEGREES: 'deg'>]

time: Time

AcquisitionAttempt

class AcquisitionAttempt(attempt: 'int', distance: 'Annotated[float, Unit.ARCSEC]', offset_applied: 'bool', offset_frame: 'OffsetFrame | None' = None, offset_lon: 'Annotated[float, Unit.DEGREES] | None' = None, offset_lat: 'Annotated[float, Unit.DEGREES] | None' = None)

Bases: object

attempt: int

distance: ARCSEC: 'arcsec'>]

offset_applied: bool

offset_frame: OffsetFrame | None = None

offset_lat: DEGREES: 'deg'>] | None = None

offset_lon: DEGREES: 'deg'>] | None = None

AcquisitionState

class AcquisitionState(attempts: 'list[AcquisitionAttempt]' = <factory>, result: 'AcquisitionResult | None' = None, time: 'Time' = <factory>)

Bases: object

attempts: list[AcquisitionAttempt]

result: AcquisitionResult | None = None

time: Time

IAutoFocus

class IAutoFocus

Bases: IRunning, IAbortable

The module can perform an autofocus.

abstractmethod async auto_focus(count: int, step: float, exposure_time: ~typing.Annotated[float, <Unit.SECONDS: 'seconds'>], **kwargs: ~typing.Any) → AutoFocusResult

Perform an autofocus series.

This method performs an autofocus series with “count” images on each side of the initial guess and the given step size. With count=3, step=1 and guess=10, this takes images at the following focus values: 7, 8, 9, 10, 11, 12, 13

Parameters:

• count – Number of images to take on each side of the initial guess. Should be an odd number.

• step – Step size.

• exposure_time – Exposure time for images.

Returns:

Result of autofocus.

Raises:

• AbortedError – If the autofocus series was aborted.

• FocusError – If focus could not be obtained.

state

alias of AutoFocusState

AutoFocusResult

class AutoFocusResult(focus: 'float', focus_err: 'float')

Bases: object

focus: float

focus_err: float

AutoFocusPoint

class AutoFocusPoint(focus: 'float', value: 'float')

Bases: object

focus: float

value: float

AutoFocusState

class AutoFocusState(points: 'list[AutoFocusPoint]' = <factory>, time: 'Time' = <factory>)

Bases: object

points: list[AutoFocusPoint]

time: Time

IAutoGuiding

class IAutoGuiding

Bases: IStartStop, IExposureTime

The module can perform auto-guiding.

state

alias of GuidingState

GuidingState

class GuidingState(loop_closed: 'bool' = False, offset_frame: 'OffsetFrame | None' = None, offset_lon: 'Annotated[float, Unit.DEGREES] | None'=None, offset_lat: 'Annotated[float, Unit.DEGREES] | None'=None, time: 'Time' = <factory>)

Bases: object

loop_closed: bool = False

offset_frame: OffsetFrame | None = None

offset_lat: DEGREES: 'deg'>] | None = None

offset_lon: DEGREES: 'deg'>] | None = None

time: Time

IAutonomous

class IAutonomous

Bases: IStartStop

The module does some autonomous actions, mainly used for warnings to users.

IBinning

class IBinning

Bases: Interface

The camera supports binning, to be used together with ICamera.

capabilities

alias of BinningCapabilities

abstractmethod async set_binning(x: int, y: int, **kwargs: Any) → None

Set the camera binning.

Parameters:

• x – X binning.

• y – Y binning.

Raises:

ValueError – If binning could not be set.

state

alias of BinningState

Binning

class Binning(x: 'int', y: 'int')

Bases: object

x: int

y: int

BinningState

class BinningState(x: 'int', y: 'int', time: 'Time' = <factory>)

Bases: object

time: Time

x: int

y: int

BinningCapabilities

class BinningCapabilities(binnings: 'list[Binning]' = <factory>)

Bases: object

binnings: list[Binning]

ICalibrate

class ICalibrate

Bases: Interface

The module can calibrate a device.

abstractmethod async calibrate(**kwargs: Any) → None

Calibrate the device.

Raises:

GeneralError – If calibration failed.

ICamera

class ICamera

Bases: IData

The module controls a camera.

IConfig

class IConfig

Bases: Interface

The module allows access to some of its configuration options.

capabilities

alias of ConfigCapabilities

abstractmethod async get_config_value(name: str, **kwargs: Any) → bool | int | float | str | list[bool | int | float | str] | dict[str, bool | int | float | str]

Returns current value of config item with given name.

Parameters:

name – Name of config item.

Returns:

Current value.

Raises:

InvalidArgumentError – If config item of given name does not exist.

abstractmethod async set_config_value(name: str, value: bool | int | float | str | list[bool | int | float | str] | dict[str, bool | int | float | str], **kwargs: Any) → None

Sets value of config item with given name.

Parameters:

• name – Name of config item.

• value – New value.

Raises:

• InvalidArgumentError – If config item of given name does not exist.

• ValueError – If value is invalid.

ConfigCapabilities

class ConfigCapabilities(caps: 'dict[str, tuple[bool, bool, bool]]'=<factory>)

Bases: object

caps: dict[str, tuple[bool, bool, bool]]

ICooling

class ICooling

Bases: ITemperatures

The module can control the cooling of a device.

abstractmethod async set_cooling(enabled: bool, setpoint: ~typing.Annotated[float, <Unit.CELSIUS: 'celsius'>], **kwargs: ~typing.Any) → None

Enables/disables cooling and sets setpoint.

Parameters:

• enabled – Enable or disable cooling.

• setpoint – Setpoint in celsius for the cooling.

Raises:

ValueError – If cooling could not be set.

state

alias of CoolingState

CoolingState

class CoolingState(setpoint: 'Annotated[float, Unit.CELSIUS] | None', power: 'Annotated[int, Unit.PERCENT] | None', enabled: 'bool', time: 'Time' = <factory>)

Bases: object

enabled: bool

power: PERCENT: 'percent'>] | None

setpoint: CELSIUS: 'celsius'>] | None

time: Time

IData

class IData

Bases: Interface

The module can grab and return an image from whatever device.

abstractmethod async grab_data(broadcast: bool = True, **kwargs: Any) → str

Grabs an image and returns reference.

Parameters:

broadcast – Broadcast existence of image.

Returns:

Name of image that was taken.

Raises:

• DeviceBusyError – If the device is already busy (exposing or running a sequence).

• GrabImageError – If there was a problem grabbing the image.

IDataSequence

class IDataSequence

Bases: IAbortable

The module can grab a counted sequence of data (images, spectra, …).

abstractmethod async abort_sequence(**kwargs: Any) → None

Stop the sequence after the current grab. The grab currently in progress, if any, finishes normally; no further grabs in the sequence are started.

This is the graceful counterpart to IAbortable.abort(), which remains the hard-stop path: it cancels the running grab immediately and the remaining sequence count.

abstractmethod async grab_sequence(count: int, broadcast: bool = True, delay: Annotated[float, <Unit.SECONDS: 'seconds'>] = 0, **kwargs: Any) → None

Start a sequence of count grabs. Returns immediately; progress is available via the pushed DataSequenceState.

Parameters:

• count – Number of grabs to take.

• broadcast – Broadcast existence of each grab.

• delay – Seconds to wait between the end of one grab and the start of the next. Does not apply after the last grab. Skipped early if the sequence is aborted during the wait.

Raises:

• InvalidArgumentError – If count or delay is out of range.

• DeviceBusyError – If the device is already busy (exposing or already running a sequence).

state

alias of DataSequenceState

DataSequenceState

class DataSequenceState(count_total: 'int', count_left: 'int', time: 'Time' = <factory>)

Bases: object

count_left: int

count_total: int

time: Time

IDome

class IDome

Bases: IRoof, IPointingAltAz

The module controls a dome, i.e. a IRoof with a rotating roof.

IExposure

class IExposure

Bases: Interface

The module controls a camera.

state

alias of ExposureState

ExposureState

class ExposureState(status: 'ExposureStatus', progress: 'Annotated[float, Unit.PERCENT]', exposure_time_left: 'Annotated[float, Unit.SECONDS]'=0.0, time: 'Time' = <factory>)

Bases: object

exposure_time_left: SECONDS: 'seconds'>] = 0.0

progress: PERCENT: 'percent'>]

status: ExposureStatus

time: Time

IExposureTime

class IExposureTime

Bases: Interface

The camera supports exposure times, to be used together with ICamera.

abstractmethod async set_exposure_time(exposure_time: ~typing.Annotated[float, <Unit.SECONDS: 'seconds'>], **kwargs: ~typing.Any) → None

Set the exposure time in seconds.

Parameters:

exposure_time – Exposure time in seconds.

Raises:

• ValueError – If exposure time could not be set.

• NotSupportedError – If this module doesn’t support setting exposure time directly (e.g. it’s dictated by something else, like incoming science frames).

state

alias of ExposureTimeState

ExposureTimeState

class ExposureTimeState(exposure_time: 'Annotated[float, Unit.SECONDS]', time: 'Time' = <factory>)

Bases: object

exposure_time: SECONDS: 'seconds'>]

time: Time

IFilters

class IFilters

Bases: IMotion

The module can change filters in a device.

capabilities

alias of FiltersCapabilities

abstractmethod async set_filter(filter_name: str, **kwargs: Any) → None

Set the current filter.

Parameters:

filter_name – Name of filter to set.

Raises:

• InvalidArgumentError – If an invalid filter was given.

• MoveError – If filter wheel cannot be moved.

state

alias of FilterState

FilterState

class FilterState(filter: 'str', time: 'Time' = <factory>)

Bases: object

filter: str

time: Time

FiltersCapabilities

class FiltersCapabilities(filters: 'list[str]' = <factory>)

Bases: object

filters: list[str]

IFitsHeaderAfter

class IFitsHeaderAfter

Bases: Interface

The module provides some additional header entries for FITS headers after some event (usually the end of the exposure).

abstractmethod async get_fits_header_after(namespaces: list[str] | None = None, **kwargs: Any) → dict[str, FitsHeaderEntry]

Returns FITS header for the current status of this module.

Parameters:

namespaces – If given, only return FITS headers for the given namespaces.

Returns:

Dictionary containing FITS headers.

IFitsHeaderBefore

class IFitsHeaderBefore

Bases: Interface

The module provides some additional header entries for FITS headers before some event (usually the start of the exposure).

abstractmethod async get_fits_header_before(namespaces: list[str] | None = None, **kwargs: Any) → dict[str, FitsHeaderEntry]

Returns FITS header for the current status of this module.

Parameters:

namespaces – If given, only return FITS headers for the given namespaces.

Returns:

Dictionary containing FITS headers.

FitsHeaderEntry

class FitsHeaderEntry(value: 'int | float | str | None', comment: 'str')

Bases: object

comment: str

value: int | float | str | None

IFlatField

class IFlatField

Bases: IAbortable

The module performs flat-fielding.

abstractmethod async flat_field(count: int = 20, **kwargs: Any) → tuple[int, ~typing.Annotated[float, <Unit.SECONDS: 'seconds'>]]

Do a series of flat fields.

Parameters:

count – Number of images to take

Returns:

Number of images actually taken and total exposure time in seconds

Raises:

DeviceBusyError – If a flat-fielding run is already in progress.

IFocusModel

class IFocusModel

Bases: Interface

The module provides a model for the telescope focus, e.g. based on temperatures.

abstractmethod async set_optimal_focus(**kwargs: Any) → None

Sets optimal focus.

Raises:

• WeatherDataError – If the weather station returned an invalid temperature reading.

• FocusTimeoutError – If a temperature module didn’t respond in time.

• MissingSensorError – If a configured sensor isn’t in a module’s temperature data.

state

alias of OptimalFocusState

OptimalFocusState

class OptimalFocusState(focus: float, time: pyobs.utils.time.Time = <factory>)

Bases: object

focus: float

time: Time

IFocuser

class IFocuser

Bases: IMotion

The module is a focusing device.

abstractmethod async set_focus(focus: ~typing.Annotated[float, <Unit.MM: 'mm'>], **kwargs: ~typing.Any) → None

Sets new focus.

Parameters:

focus – New focus value in mm.

Raises:

• InvalidArgumentError – If given value is invalid.

• AbortedError – If movement was aborted.

• MoveError – If telescope cannot be moved.

abstractmethod async set_focus_offset(offset: ~typing.Annotated[float, <Unit.MM: 'mm'>], **kwargs: ~typing.Any) → None

Sets focus offset.

Parameters:

offset – New focus offset in mm.

Raises:

• ValueError – If given value is invalid.

• NotSupportedError – If this module doesn’t support a separate focus offset.

• MoveError – If telescope cannot be moved.

state

alias of FocuserState

FocuserState

class FocuserState(focus: 'Annotated[float, Unit.MM]', focus_offset: 'Annotated[float, Unit.MM]', time: 'Time' = <factory>)

Bases: object

focus: MM: 'mm'>]

focus_offset: MM: 'mm'>]

time: Time

IGain

class IGain

Bases: Interface

The camera supports setting of gain, to be used together with ICamera.

abstractmethod async set_gain(gain: float, **kwargs: Any) → None

Set the camera gain.

Parameters:

gain – New camera gain.

Raises:

ValueError – If gain could not be set.

abstractmethod async set_offset(offset: float, **kwargs: Any) → None

Set the camera offset.

Parameters:

offset – New camera offset.

Raises:

ValueError – If offset could not be set.

state

alias of GainState

GainState

class GainState(gain: 'float', offset: 'float', time: 'Time' = <factory>)

Bases: object

gain: float

offset: float

time: Time

IImageFormat

class IImageFormat

Bases: Interface

The module supports different image formats (e.g. INT16, FLOAT32), mainly used by cameras.

capabilities

alias of ImageFormatCapabilities

abstractmethod async set_image_format(fmt: ImageFormat, **kwargs: Any) → None

Set the camera image format.

Parameters:

fmt – New image format.

Raises:

ValueError – If format could not be set.

state

alias of ImageFormatState

ImageFormatState

class ImageFormatState(image_format: 'ImageFormat', time: 'Time' = <factory>)

Bases: object

image_format: ImageFormat

time: Time

ImageFormatCapabilities

class ImageFormatCapabilities(image_formats: 'list[str]' = <factory>)

Bases: object

image_formats: list[str]

IImageType

class IImageType

Bases: Interface

The module supports different image types (e.g. object, bias, dark, etc), mainly used by cameras.

abstractmethod async set_image_type(image_type: ImageType, **kwargs: Any) → None

Set the image type.

Parameters:

image_type – New image type.

state

alias of ImageTypeState

ImageTypeState

class ImageTypeState(image_type: 'ImageType', time: 'Time' = <factory>)

Bases: object

image_type: ImageType

time: Time

IMode

class IMode

Bases: Interface

The module can change modes in a device.

capabilities

alias of ModeCapabilities

abstractmethod async set_mode(mode: str, group: str = '', **kwargs: Any) → None

Set the current mode.

Parameters:

• mode – Name of mode to set.

• group – Name of the group to set the mode for.

Raises:

• InvalidArgumentError – If an invalid mode or group was given.

• MoveError – If mode selector cannot be moved.

state

alias of ModeState

ModeState

class ModeState(modes: 'dict[str, str]'=<factory>, time: 'Time' = <factory>)

Bases: object

modes: dict[str, str]

time: Time

ModeCapabilities

class ModeCapabilities(modes: 'dict[str, list[str]]'=<factory>)

Bases: object

modes: dict[str, list[str]]

IModule

class IModule

Bases: Interface

The module is actually a module. Implemented by all modules.

capabilities

alias of ModuleCapabilities

abstractmethod async get_permitted_methods(**kwargs: Any) → list[str]

Returns names of all methods the calling module is allowed to invoke on this module.

abstractmethod async reset_error(**kwargs: Any) → bool

Reset error of module, if any.

ModuleLocation

class ModuleLocation(longitude: 'float' = 0.0, latitude: 'float' = 0.0, elevation: 'float' = 0.0, timezone: 'str' = 'utc')

Bases: object

elevation: float = 0.0

latitude: float = 0.0

longitude: float = 0.0

timezone: str = 'utc'

ModuleCapabilities

class ModuleCapabilities(label: 'str' = '', version: 'str' = '', location: 'ModuleLocation | None' = None)

Bases: object

label: str = ''

location: ModuleLocation | None = None

version: str = ''

IMotion

class IMotion

Bases: IReady

The module controls a device that can move.

abstractmethod async init(**kwargs: Any) → None

Initialize device.

Raises:

InitError – If device could not be initialized.

abstractmethod async park(**kwargs: Any) → None

Park device.

Raises:

ParkError – If device could not be parked.

state

alias of MotionState

abstractmethod async stop_motion(device: str | None = None, **kwargs: Any) → None

Stop the motion.

Parameters:

device – Name of device to stop, or None for all.

DeviceMotionStatus

class DeviceMotionStatus(name: 'str', status: 'MotionStatus')

Bases: object

name: str

status: MotionStatus

MotionState

class MotionState(status: 'MotionStatus', devices: 'list[DeviceMotionStatus]' = <factory>, time: 'Time' = <factory>)

Bases: object

devices: list[DeviceMotionStatus]

status: MotionStatus

time: Time

IMultiFiber

class IMultiFiber

Bases: Interface

An interface for multi-fiber setups that helps to set/get a fiber and retrieve position and size of the current fiber on the acquisition/guiding image.

abstractmethod async abort(**kwargs: Any) → None

Abort current actions.

capabilities

alias of MultiFiberCapabilities

abstractmethod async set_fiber(fiber: str, **kwargs: Any) → None

Sets the currently active fiber. Must be in fiber_names capability.

Parameters:

fiber – Name of fiber to set.

Raises:

InvalidArgumentError – If fiber name is invalid.

state

alias of MultiFiberState

MultiFiberState

class MultiFiberState(fiber: 'str' = '', pixel_x: 'float' = 0.0, pixel_y: 'float' = 0.0, radius: 'float' = 0.0, time: 'Time' = <factory>)

Bases: object

fiber: str = ''

pixel_x: float = 0.0

pixel_y: float = 0.0

radius: float = 0.0

time: Time

MultiFiberCapabilities

class MultiFiberCapabilities(fiber_count: 'int' = 0)

Bases: object

fiber_count: int = 0

IOffsetsAltAz

class IOffsetsAltAz

Bases: Interface

The module supports Alt/Az offsets, usually combined with ITelescope and IPointingAltAz.

abstractmethod async set_offsets_altaz(dalt: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], daz: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Move an Alt/Az offset.

Parameters:

• dalt – Altitude offset in degrees.

• daz – Azimuth offset in degrees.

Raises:

MoveError – If device could not be moved.

state

alias of AltAzOffsetState

AltAzOffsetState

class AltAzOffsetState(alt: 'Annotated[float, Unit.DEGREES]', az: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

alt: DEGREES: 'deg'>]

az: DEGREES: 'deg'>]

time: Time

IOffsetsRaDec

class IOffsetsRaDec

Bases: Interface

The module supports RA/Dec offsets, usually combined with ITelescope and IPointingRaDec.

abstractmethod async set_offsets_radec(dra: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], ddec: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Move an RA/Dec offset.

Parameters:

• dra – RA offset in degrees.

• ddec – Dec offset in degrees.

Raises:

MoveError – If telescope cannot be moved.

state

alias of RaDecOffsetState

RaDecOffsetState

class RaDecOffsetState(ra: 'Annotated[float, Unit.DEGREES]', dec: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

dec: DEGREES: 'deg'>]

ra: DEGREES: 'deg'>]

time: Time

IPointingAltAz

class IPointingAltAz

Bases: Interface

The module can move to Alt/Az coordinates, usually combined with ITelescope.

abstractmethod async move_altaz(alt: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], az: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Moves to given coordinates.

Parameters:

• alt – Alt in deg to move to.

• az – Az in deg to move to.

Raises:

• NotSupportedError – If this device doesn’t support Alt/Az pointing.

• AltitudeLimitError – If the destination is below the configured altitude limit.

• MoveError – If device could not be moved.

state

alias of AltAzState

AltAzState

class AltAzState(alt: 'Annotated[float, Unit.DEGREES]', az: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

alt: DEGREES: 'deg'>]

az: DEGREES: 'deg'>]

time: Time

IPointingBody

class IPointingBody

Bases: Interface

Points at and tracks a named solar-system body.

abstractmethod async track_body(body: str, **kwargs: Any) → None

Starts tracking a named solar-system body.

Parameters:

body – Name resolvable to an ephemeris (e.g. ‘moon’, ‘mars’, ‘jupiter’, or an asteroid/comet designation known to JPL Horizons).

Raises:

• NotSupportedError – If this device doesn’t support body tracking.

• BodyResolutionError – If body name is not resolvable.

• MoveError – If telescope could not be moved. Also propagates whatever the underlying RA/Dec move raises (e.g. MissingObserverError, AltitudeLimitError), since tracking a body is implemented as resolving it and then moving there.

IPointingHeliocentricPolar

class IPointingHeliocentricPolar

Bases: Interface

The module can move to Heliocentric Polar (Mu/Psi) coordinates, usually combined with ITelescope.

abstractmethod async move_heliocentric_polar(mu: float, psi: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Moves on given coordinates.

Parameters:

• mu – Cosine of the angular distance from Sun centre, dimensionless (0..1).

• psi – Position angle around the solar disk, in degrees.

Raises:

MoveError – If device could not be moved. Also propagates whatever the underlying RA/Dec move raises (e.g. MissingObserverError, AltitudeLimitError), since this is typically implemented as converting to RA/Dec and then moving there.

state

alias of HeliocentricPolarState

HeliocentricPolarState

class HeliocentricPolarState(mu: 'float', psi: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

mu: float

psi: DEGREES: 'deg'>]

time: Time

IPointingHeliographicStonyhurst

class IPointingHeliographicStonyhurst

Bases: Interface

The module can move to Heliographic Stonyhurst (lon/lat) coordinates, a frame fixed to the Sun’s rotating surface, usually combined with ITelescope.

abstractmethod async move_heliographic_stonyhurst(lon: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], lat: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Moves on given coordinates.

Parameters:

• lon – Longitude in deg to track.

• lat – Latitude in deg to track.

Raises:

MoveError – If device could not be moved. Also propagates whatever the underlying RA/Dec move raises (e.g. MissingObserverError, AltitudeLimitError), since this is typically implemented as converting to RA/Dec and then moving there.

state

alias of HeliographicStonyhurstState

HeliographicStonyhurstState

class HeliographicStonyhurstState(lon: 'Annotated[float, Unit.DEGREES]', lat: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

lat: DEGREES: 'deg'>]

lon: DEGREES: 'deg'>]

time: Time

IPointingHelioprojective

class IPointingHelioprojective

Bases: Interface

The module can move to Mu/Psi coordinates, usually combined with ITelescope.

abstractmethod async move_helioprojective(theta_x: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], theta_y: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Moves on given coordinates.

Parameters:

• theta_x – The theta_x coordinate.

• theta_y – The theta_y coordinate.

Raises:

MoveError – If device could not be moved. Also propagates whatever the underlying RA/Dec move raises (e.g. MissingObserverError, AltitudeLimitError), since this is typically implemented as converting to RA/Dec and then moving there.

state

alias of HelioprojectiveState

HelioprojectiveState

class HelioprojectiveState(theta_x: 'Annotated[float, Unit.DEGREES]', theta_y: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

theta_x: DEGREES: 'deg'>]

theta_y: DEGREES: 'deg'>]

time: Time

IPointingOrbitalElements

class IPointingOrbitalElements

Bases: Interface

Points at and tracks a body defined by orbital elements (asteroid, comet, NEO).

abstractmethod async track_orbital_elements(elements: OrbitalElements, **kwargs: Any) → None

Starts tracking a body defined by orbital elements.

Parameters:

elements – Orbital elements of the body to track.

Raises:

• NotSupportedError – If this device doesn’t support orbital-element tracking.

• InvalidOrbitalElementsError – If elements are incomplete or inconsistent (neither mean_anomaly nor perihelion_time given).

• MoveError – If telescope could not be moved. Also propagates whatever the underlying RA/Dec move raises (e.g. MissingObserverError, AltitudeLimitError), since tracking orbital elements is implemented as propagating them and then moving there.

OrbitalElements

class OrbitalElements(epoch: 'Time', semi_major_axis: 'Annotated[float, Unit.AU]', eccentricity: 'float', inclination: 'Annotated[float, Unit.DEGREES]', longitude_ascending_node: 'Annotated[float, Unit.DEGREES]', argument_of_periapsis: 'Annotated[float, Unit.DEGREES]', mean_anomaly: 'Annotated[float, Unit.DEGREES] | None' = None, perihelion_time: 'Time | None' = None)

Bases: object

argument_of_periapsis: DEGREES: 'deg'>]

eccentricity: float

epoch: Time

inclination: DEGREES: 'deg'>]

longitude_ascending_node: DEGREES: 'deg'>]

mean_anomaly: DEGREES: 'deg'>] | None = None

Mean anomaly at epoch, in degrees. Required for elliptical orbits (eccentricity < 1).

perihelion_time: Time | None = None

Time of perihelion passage. Required for near-parabolic/cometary orbits (eccentricity close to or at 1), where mean anomaly is not well-defined.

semi_major_axis: AU: 'au'>]

IPointingRaDec

class IPointingRaDec

Bases: Interface

The module can move to RA/Dec coordinates, usually combined with ITelescope.

abstractmethod async move_radec(ra: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], dec: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Starts tracking on given coordinates.

Parameters:

• ra – RA in deg to track.

• dec – Dec in deg to track.

Raises:

• NotSupportedError – If this device doesn’t support RA/Dec pointing.

• MissingObserverError – If no observer is configured.

• AltitudeLimitError – If the destination is below the configured altitude limit.

• MoveError – If device could not be moved.

state

alias of RaDecState

RaDecState

class RaDecState(ra: 'Annotated[float, Unit.DEGREES]', dec: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

dec: DEGREES: 'deg'>]

ra: DEGREES: 'deg'>]

time: Time

IPointingSeries

class IPointingSeries

Bases: Interface

The module provides the interface for a device that initializes and finalizes a pointing series and adds points to it.

abstractmethod async add_pointing_measurement(**kwargs: Any) → None

Add a new measurement to the pointing series.

Raises:

GeneralError – If the measurement could not be added.

IReady

class IReady

Bases: Interface

The module can be in a “not ready” state for science and need to be initialized in some way.

state

alias of ReadyState

ReadyState

class ReadyState(ready: 'bool', time: 'Time' = <factory>)

Bases: object

ready: bool

time: Time

IRoof

class IRoof

Bases: IMotion

The module controls a roof.

IRotation

class IRotation

Bases: IMotion

The module controls a device that can rotate.

abstractmethod async set_rotation(angle: ~typing.Annotated[float, <Unit.DEGREES: 'deg'>], **kwargs: ~typing.Any) → None

Sets the rotation angle to the given value in degrees.

Raises:

MoveError – If the device could not be rotated.

state

alias of RotationState

RotationState

class RotationState(rotation: 'Annotated[float, Unit.DEGREES]', time: 'Time' = <factory>)

Bases: object

rotation: DEGREES: 'deg'>]

time: Time

IRunnable

class IRunnable

Bases: IAbortable

The module has some action that can be started remotely.

abstractmethod async run(**kwargs: Any) → None

Perform module task

Raises:

• DeviceBusyError – If this task is already running.

• ScriptError – ScriptRunner-based implementations wrap whatever the underlying script raises that isn’t already a domain exception.

IRunning

class IRunning

Bases: Interface

The module can be running.

state

alias of RunningState

RunningState

class RunningState(running: 'bool', time: 'Time' = <factory>)

Bases: object

running: bool

time: Time

IScriptRunner

class IScriptRunner

Bases: Interface

The module can execute a script.

abstractmethod async run_script(script: str, **kwargs: Any) → None

Run the given script.

Parameters:

script – Script to run.

Raises:

ScriptError – If the script failed.

ISpectrograph

class ISpectrograph

Bases: IData

The module controls a camera.

IStartStop

class IStartStop

Bases: IRunning

The module can be started and stopped.

abstractmethod async start(**kwargs: Any) → None

Starts a service.

abstractmethod async stop(**kwargs: Any) → None

Stops a service.

IStructuredConfig

class IStructuredConfig

Bases: Interface

The module accepts a whole structured (possibly nested) config object in one call, rather than per-field get/set (see IConfig for the per-field variant).

capabilities

alias of ConfigSchema

abstractmethod async set_config(config: dict[str, bool | int | float | str | list[bool | int | float | str | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | list[ConfigValue] | dict[str, ConfigValue]]], **kwargs: Any) → None

Apply a full structured config to this module.

Parameters:

config – Nested dict matching this module’s ConfigSchema (fetch via get_capabilities). Values are validated and deserialized into the module’s internal config dataclass.

Raises:

ValueError – If config doesn’t match the module’s schema, or values fail validation.

state

alias of ConfigAppliedState

ConfigAppliedState

class ConfigAppliedState(config: 'dict[str, ConfigValue]', time: 'Time' = <factory>)

Bases: object

config: dict[str, bool | int | float | str | list[bool | int | float | str | list[ConfigValue] | dict[str, ConfigValue]] | dict[str, bool | int | float | str | list[ConfigValue] | dict[str, ConfigValue]]]

time: Time

ISyncTarget

class ISyncTarget

Bases: Interface

The module can synchronize a target, e.g. via a telescope control software behinde an ITelescope.

abstractmethod async sync_target(**kwargs: Any) → None

Synchronize device on current target.

Raises:

GeneralError – If synchronization failed.

ITelescope

class ITelescope

Bases: IMotion

The module controls a telescope.

ITemperatures

class ITemperatures

Bases: Interface

The module can return temperatures measured on some device.

state

alias of TemperaturesState

SensorReading

class SensorReading(name: 'str', value: 'Annotated[float, Unit.CELSIUS]')

Bases: object

name: str

value: CELSIUS: 'celsius'>]

TemperaturesState

class TemperaturesState(readings: 'list[SensorReading]' = <factory>, time: 'Time' = <factory>)

Bases: object

readings: list[SensorReading]

time: Time

ITrackingMode

class ITrackingMode

Bases: Interface

The module supports switching between discrete, hardware-native tracking rates.

capabilities

alias of TrackingModeCapabilities

abstractmethod async set_tracking_mode(mode: TrackingMode, **kwargs: Any) → None

Switches to the given tracking mode.

Parameters:

mode – Tracking mode to switch to.

Raises:

• MoveError – If mode could not be set.

• InvalidArgumentError – If mode is not in this module’s capabilities.

state

alias of TrackingModeState

TrackingMode

class TrackingMode(value)

Bases: StrEnum

Discrete, hardware-native tracking rate.

LUNAR = 'lunar'

OFF = 'off'

SIDEREAL = 'sidereal'

SOLAR = 'solar'

TrackingModeState

class TrackingModeState(mode: 'TrackingMode', time: 'Time' = <factory>)

Bases: object

mode: TrackingMode

time: Time

TrackingModeCapabilities

class TrackingModeCapabilities(modes: 'list[TrackingMode]')

Bases: object

modes: list[TrackingMode]

ITrackingRate

class ITrackingRate

Bases: Interface

The module accepts an arbitrary non-sidereal tracking rate as an absolute RA/Dec offset.

capabilities

alias of TrackingRateCapabilities

abstractmethod async set_tracking_rate(ra_rate: ~typing.Annotated[float, <Unit.ARCSEC_PER_SEC: 'arcsec/s'>], dec_rate: ~typing.Annotated[float, <Unit.ARCSEC_PER_SEC: 'arcsec/s'>], **kwargs: ~typing.Any) → None

Sets an absolute tracking rate on the sky, in arcsec/sec.

Parameters:

• ra_rate – Rate in RA, arcsec/sec on the sky.

• dec_rate – Rate in Dec, arcsec/sec on the sky.

Raises:

MoveError – If rate could not be set.

state

alias of TrackingRateState

TrackingRateState

class TrackingRateState(ra_rate: 'Annotated[float, Unit.ARCSEC_PER_SEC]', dec_rate: 'Annotated[float, Unit.ARCSEC_PER_SEC]', time: 'Time' = <factory>)

Bases: object

dec_rate: ARCSEC_PER_SEC: 'arcsec/s'>]

ra_rate: ARCSEC_PER_SEC: 'arcsec/s'>]

time: Time

TrackingRateCapabilities

class TrackingRateCapabilities(min_update_interval: 'Annotated[float, Unit.SECONDS]')

Bases: object

min_update_interval: SECONDS: 'seconds'>]

Minimum time between successive set_tracking_rate calls this hardware/protocol accepts, independent of whether the value actually changed. Populated per-driver from whatever its protocol allows; 0 if the hardware has no such floor.

IVideo

class IVideo

Bases: IData

The module controls a video streaming device.

capabilities

alias of VideoCapabilities

VideoCapabilities

class VideoCapabilities(mjpeg: 'str | None' = None, raw: 'str | None' = None)

Bases: object

mjpeg: str | None = None

raw: str | None = None

IWeather

class IWeather

Bases: IStartStop

The module acts as a weather station.

abstractmethod async get_sensor_value(station: str, sensor: WeatherSensors, **kwargs: Any) → WeatherSensorReading

Return value for given sensor.

Parameters:

• station – Name of weather station to get value from.

• sensor – Name of sensor to get value from.

Returns:

Current reading for the given sensor.

Raises:

• InvalidArgumentError – If station or sensor is unknown.

• WeatherResponseError – If the underlying weather station’s response is malformed.

state

alias of WeatherState

WeatherSensorReading

class WeatherSensorReading(sensor: 'WeatherSensors', value: 'float', unit: 'str', time: 'Time' = <factory>)

Bases: object

sensor: WeatherSensors

time: Time

unit: str

value: float

WeatherState

class WeatherState(good: 'bool', readings: 'list[WeatherSensorReading]' = <factory>, time: 'Time' = <factory>)

Bases: object

good: bool

readings: list[WeatherSensorReading]

time: Time

IWindow

class IWindow

Bases: Interface

The camera supports windows, to be used together with ICamera.

capabilities

alias of WindowCapabilities

abstractmethod async set_window(left: int, top: int, width: int, height: int, **kwargs: Any) → None

Set the camera window.

Parameters:

• left – X offset of window.

• top – Y offset of window.

• width – Width of window.

• height – Height of window.

Raises:

ValueError – If window could not be set.

state

alias of WindowState

WindowState

class WindowState(x: 'int', y: 'int', width: 'int', height: 'int', time: 'Time' = <factory>)

Bases: object

height: int

time: Time

width: int

x: int

y: int

WindowCapabilities

class WindowCapabilities(full_frame_x: 'int' = 0, full_frame_y: 'int' = 0, full_frame_width: 'int' = 0, full_frame_height: 'int' = 0)

Bases: object

full_frame_height: int = 0

full_frame_width: int = 0

full_frame_x: int = 0

full_frame_y: int = 0