Observatory Configuration

Observatory Configuration#

banner

Astra requires an observatory configuration file in YAML format that defines all devices, their settings, safety limits, and how they interact with each other.

Important

Each Astra instance runs exactly one observatory at a time, specified by the observatory_name field in your base configuration file (~/.astra/astra_config.yml).

This name determines which configuration files are loaded: {observatory_name}_config.yml and {observatory_name}_fits_header_config.csv.

You’ll need to configure two files for your observatory:

  • {observatory_name}_config.yml (this page) - Device definitions, safety limits, and settings

  • {observatory_name}_fits_header_config.csv (FITS Header Configuration) - FITS header keyword mappings

Example Observatory Configuration Template#
Telescope:
  - device_name: telescope_observatoryname
    ip: localhost:11111
    device_number: 0
    pointing_threshold: 0.1 # arcmins
    meridian_flip: false # enable automated meridian flips
    meridian_flip_min: 5 # minutes past meridian to trigger flip
    equatorial_system: auto # frame the mount expects: auto (read ASCOM EquatorialSystem), J2000, JNow, J2050, B1950
    guider: # populated using calibrate_guiding sequence
      PIX2TIME: # ms/pixel for camera used for guiding
        +x: 71.62908053771561
        -x: 71.62926906533114
        +y: 71.62775367838461
        -y: 71.62771750106279
      RA_AXIS: "x"
      ANGLE: 0.0 # degrees, camera rotation from the mount axes
      DIRECTIONS:
        +x: East
        -x: West
        +y: North
        -y: South
      PID_COEFFS: # defaults
        "x": { "p": 0.70, "i": 0.02, "d": 0.0 }
        "y": { "p": 0.50, "i": 0.02, "d": 0.0 }
        "set_x": 0.0
        "set_y": 0.0
      MIN_GUIDE_INTERVAL: 60 # seconds
Focuser:
  - device_name: focuser_observatoryname
    ip: localhost:11111
    device_number: 0
    focus_position: 10000
    focus_tolerance: 0 # steps; skip move if already within this many steps of target
    settle_time: 3 # seconds
    connectable: true # optional, default: true
Camera:
  - device_name: camera_observatoryname
    ip: localhost:11111
    device_number: 0
    temperature: -20 # degrees Celsius
    temperature_tolerance: 1 # degrees Celsius
    cooling_timeout: 30 # minutes
    settle_factor: 0.0 # exposure multiplier to wait after pointing and autofocus moves (for SPIRIT like cameras)
    # dark_filter: Dark # optional, filter for darks and bias frames (for cameras without a shutter)
    flats:
      target_adu: 31500 # ADU
      target_adu_tolerance: 10500 # ADU
      lower_exptime_limit: 1 # seconds
      upper_exptime_limit: 60 # seconds
    paired_devices:
      Telescope: telescope_observatoryname
      Focuser: focuser_observatoryname
      Dome: dome_observatoryname
      FilterWheel: fw_observatoryname
      ObservingConditions: weather_observatoryname
      SafetyMonitor: safety_observatoryname
      Camera: camera_observatoryname
Dome:
  - device_name: dome_observatoryname
    ip: localhost:11111
    device_number: 0
    close_dome_on_telescope_error: false
    telescopes:
      - telescope_observatoryname
FilterWheel:
  - device_name: fw_observatoryname
    ip: localhost:11111
    device_number: 0
ObservingConditions:
  - device_name: weather_observatoryname
    ip: localhost:11111
    device_number: 0
    polling_interval: 5 # seconds
    closing_limits:
      Humidity:
        - upper: 70
          max_safe_duration: 30
        - upper: 80
          max_safe_duration: 150
        - upper: 90
          max_safe_duration: 300
      Temperature:
        - lower: 0
          max_safe_duration: 30
      WindSpeed:
        - upper: 10
          max_safe_duration: 30
      SkyTemperature:
        - upper: -30
          max_safe_duration: 30
      RelativeSkyTemp:
        - upper: -40
          max_safe_duration: 30
SafetyMonitor:
  - device_name: safety_observatoryname
    ip: localhost:11111
    device_number: 0
    max_safe_duration: 15 # minutes

Misc:
  backup_time: "12:00" # UTC back up time of polled data (e.g. CCDTemperature) and logs


  # Webcam: http://localhost:8888/inside
  ## Multiple webcams:
  # Webcam:
  #   - name: Inside View
  #     url: http://localhost:8888/inside
  #   - name: Outside View
  #     url: http://localhost:8888/outside
  #     snapshot_url: http://camera-ip/snapshot.jpg # JPEG/PNG image, needed for time-lapse
  #     timelapse:      # optional, record a time-lapse of this camera
  #       interval: 10  # minutes between frames
  #       retention: 24 # hours to keep frames

  # AllSky: /path/to/allsky.jpg
  ## Multiple all-sky cameras:
  # AllSky:
  #   - name: East Sky
  #     path: /path/to/allsky_east.jpg
  #   - name: West Sky
  #     path: /path/to/allsky_west.jpg
  #     timelapse: true # optional, record a time-lapse (10 min interval, 24 h retention)

  # filename_templates:
  #   object: "{action_date}/{device}_{filter_name}_{object_name}_{exptime:.3f}_{timestamp}.fits"
  #   calibration: "{action_date}/{device}_{imagetype}_{exptime:.3f}_{timestamp}.fits"
  #   flats: "{action_date}/{device}_{filter_name}_{imagetype}_{exptime:.3f}_{timestamp}.fits"
  #   autofocus: "autofocus/{action_date}/{device}_{filter_name}_{imagetype}_{exptime:.3f}_{timestamp}.fits"
  #   calibrate_guiding: "calibrate_guiding/{action_date}/{device}_{filter_name}_{imagetype}_{exptime:.3f}_{timestamp}.fits"
  #   pointing_model: "pointing_model/{action_date}/{device}_{filter_name}_{imagetype}_{exptime:.3f}_{timestamp}.fits"
  #   default: "{action_date}/{device}_{filter_name}_{imagetype}_{exptime:.3f}_{timestamp}.fits"

This example configuration shows all supported device types and their parameters. You can customize this template for your specific observatory setup.

Device Types and Configuration#

Astra supports the following device types, all conforming to the ASCOM Alpaca standard:

  • Telescope

  • Focuser

  • Camera

  • Dome

  • FilterWheel

  • ObservingConditions

  • SafetyMonitor

  • CoverCalibrator

  • Rotator

  • Switch

Each device type has specific configuration parameters detailed below.

Common Device Parameters#

All devices share these required parameters:

  • device_name: Unique identifier for the device (string, e.g., “camera_main”)

  • ip: Network address of the Alpaca device (string, format: “hostname:port”)

  • device_number: ASCOM Alpaca device number (integer)

  • polling_interval: How often to poll ASCOM properties (set by FITS header configuration), in seconds (integer, optional, default: 5)

  • connectable: Whether to attempt connection at startup (boolean, optional, default: true)

Telescope Configuration#

Additional parameters for telescope mounts:

  • pointing_threshold: Maximum acceptable pointing error in arcminutes before pointing correction is applied (float, default: 0.1)

  • settle_factor: Deprecated. Set settle_factor in the camera config instead. Astra still reads this value if the camera config does not set one, and logs a warning.

  • meridian_flip: Enable automated meridian flips (boolean, default: false)

  • meridian_flip_min: Buffer time in minutes past meridian to trigger flip (float, default: 5)

  • equatorial_system: Coordinate frame the mount expects for slews and syncs (string, default: auto). With auto, Astra reads the ASCOM EquatorialSystem property once at first use. Set J2000, JNow, J2050 or B1950 to override a driver that reports the wrong value. Astra works in ICRS (J2000) internally and converts to the mount’s frame just before each slew. A mount that reports J2000, or whose property cannot be read, receives the ICRS coordinates unchanged. A JNow mount that is sent J2000 coordinates misses by about 20 arcminutes, so check the log line Telescope <name> expects TOPOCENTRIC coordinates on first use if your mount is JNow.

  • guider: Autoguider calibration settings (dict, populated automatically by the calibrate_guiding sequence)

Focuser Configuration#

Focuser-specific parameters:

  • focus_position: Best known absolute focus position (integer)

  • focus_tolerance: Maximum deviation in steps from the target position before a focuser move is issued (integer, default: 0). Moves are skipped when the current position is within this many steps of the target, avoiding unnecessary mechanical motion when thermal drift is small. A focuser that ends a move within this many steps of the target counts as on target, so no warning is logged.

  • settle_time: Time in seconds to wait after focus position move (integer)

Camera Configuration#

Camera-specific parameters for cooling and imaging:

Cooling Parameters:

  • temperature: Target cooling temperature in Celsius (float)

  • temperature_tolerance: Acceptable temperature tolerance from target in Celsius (float)

  • cooling_timeout: Time in minutes to wait to reach target temperature before timing out (int, default: 30)

Settle Parameters:

  • settle_factor: Exposure multiplier for the extra wait after a move, before the next exposure (float, default: 0.0). Astra waits settle_factor × exptime after each pointing correction slew, each pointing model slew, and each focus move during autofocus. Use it for cameras that capture continuously, such as SPIRIT, so that the next frame starts after the move. Set it to 1.0 to discard about one frame.

Dark Parameters:

  • dark_filter: Filter to use for darks and bias frames, for example a blank filter for a camera without a shutter (string, optional). Astra moves the filter wheel to this filter for the darks and then back to where it was. If you do not set it, the filter does not change. The flats, the pointing model darks and calibration actions without a filter use it.

Sky Flat Parameters:

  • flats: Configuration for automated flat field acquisition (dict)

    • target_adu: Target median ADU value for sky flat frame (int)

    • target_adu_tolerance: Acceptable tolerance around target ADU (int)

    • lower_exptime_limit: Minimum allowed exposure time in seconds (int)

    • upper_exptime_limit: Maximum allowed exposure time in seconds (int)

At the start of a flats sequence, Astra takes 3 bias frames before the dome opens. The median of the master bias is the bias level for the flat exposure time calculation. If the bias frames fail, Astra uses a bias level of 0 ADU. The old bias_offset key is not used.

Device Associations:

  • paired_devices: Links to other devices for FITS headers and sequence coordination (dict)

    • {device_type}: {device_name} which must match the name used in device configuration (string)

Dome Configuration#

Dome-specific parameters:

  • close_dome_on_telescope_error: Flag to close the dome in case of a telescope error. (boolean, default: false)

  • telescopes: List of associated telescope(s) within the dome (list)

ObservingConditions Configuration#

Weather monitoring and safety parameters:

  • closing_limits: Weather safety thresholds that trigger observatory closure (dict)

    • {parameter}: Weather parameter name (e.g., Humidity, WindSpeed, Temperature)

    • {parameter}[i].upper/lower: Threshold value - upper for maximum safe value, lower for minimum (float)

    • {parameter}[i].max_safe_duration: Time in minutes the parameter must stay within safe limits before weather_safe is set to True (int)

Supported Parameters:

  • Standard ASCOM: CloudCover, DewPoint, Humidity, Pressure, RainRate, SkyBrightness, SkyQuality, SkyTemperature, StarFWHM, Temperature, WindDirection, WindGust, WindSpeed

  • Custom: RelativeSkyTemp (sky temperature minus ambient temperature; requires both SkyTemperature and Temperature to be available from your weather station via its ASCOM Alpaca ObservingConditions driver)

Important

A weather parameter is only used for safety evaluation when both conditions are met:

  1. It is exposed by your ASCOM Alpaca ObservingConditions driver.

  2. It is defined in your FITS header configuration such that Astra can retrieve historical values from the local SQLite database for safety monitoring its max_safe_duration.

SafetyMonitor Configuration#

Safety system monitoring parameters:

  • max_safe_duration: Time in minutes the IsSafe property must remain True continuously before the observatory is considered weather_safe (int)

Misc Options#

Optional observatory-wide settings:

  • backup_time: UTC time of day to perform automatic daily backups of polled data and logs on the SQLite database (string, format: “HH:MM”)

  • Webcam: Webcam feed configuration. The URL is embedded in an iframe element in the frontend. Can be:

    • Single URL string for one webcam (e.g., Webcam: http://localhost:8888/inside)

    • Array of objects for multiple webcams, each with name and url properties, and an optional snapshot_url

    • Any iframe-compatible video source (e.g., mediamtx)

    • snapshot_url must return a JPEG or PNG image. It is needed only for time-lapse recording.

  • AllSky: All-sky camera configuration. Images are fetched via /api/allsky/latest endpoint and automatically refreshed every 60 seconds. Can be:

    • Single path string for one camera (e.g., AllSky: /path/to/allsky.jpg)

    • Array of objects for multiple cameras, each with name and path properties

    • Supports JPEG and PNG formats

  • timelapse (per camera): Add this key to a camera in the AllSky or Webcam array to record a time-lapse of that camera. Cameras without this key are not recorded. On the Summary page, click the camera image or its clock button to play back the frames.

    • timelapse: true uses the defaults. A mapping can set these options:

      • interval: Minutes between frames (float, default 10).

      • retention: Hours to keep frames (float, default 24). Older frames are deleted.

    • All-sky cameras: a frame is saved only when the image file changes. The frame time is the file’s modification time. A file older than retention is not saved, and a warning is logged.

    • Webcams: a snapshot_url is necessary. It must return one JPEG or PNG image of at most 20 MB, not a video stream.

    • Frames are stored in the timelapse folder of the Astra assets folder. At a 10 minute interval, each camera uses about 40–150 MB, depending on image size.

    AllSky:
  - name: East Sky
    path: /path/to/allsky_east.jpg
    timelapse:
      interval: 5
      retention: 48
Webcam:
  - name: Outside View
    url: http://localhost:8888/outside
    snapshot_url: http://camera-ip/snapshot.jpg
    timelapse: true

  • filename_templates: Customize how FITS files are named and organized (dict). See astra.filename_templates for more details.