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
    settle_factor: 0.0 # exposure multiplier for calculated settle time after pointing (for SPIRIT like cameras)
    meridian_flip: false # enable automated meridian flips
    meridian_flip_min: 5 # minutes past meridian to trigger flip
    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"
      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
    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
    flats:
      target_adu: 31500 # ADU
      target_adu_tolerance: 10500 # ADU
      bias_offset: 300 # 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

  # 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

  # 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: Exposure multiplier for calculated settle time after pointing - useful for continuous acquisition type cameras (float, default: 0.0)

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

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

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

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

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)

    • bias_offset: Median bias level offset in ADU for exposure time calculations (int)

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

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

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

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

  • 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

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

Contents