Editing ASCOM SafetyMonitor

====== Deep Sky Chile Safety Monitor (ASCOM Driver) ======

===== Overview =====
The **Deep Sky Chile Safety Monitor** is an ASCOM-compliant driver that exposes the **safety status** of Deep Sky Chile observatories.

It reads the roof state of a selected observatory via the Deep Sky Chile API and converts it into the standard ASCOM ''SafetyMonitor'' ''IsSafe'' value.

Mapping:

  * **Roof open**  → ''IsSafe = True''
  * **Roof closed** → ''IsSafe = False''

This driver is intended for remote observatory automation systems that rely on an ASCOM SafetyMonitor to decide whether it is safe to operate equipment.

===== Features =====
  * ASCOM ''SafetyMonitor'' implementation
  * Periodic polling of the Deep Sky Chile observatories API
  * Observatory selection via dropdown list
  * Roof state-to-safety mapping
  * Stale data protection
  * Optional trace logging
  * Configurable fail-safe mode

===== How it Works =====
The driver periodically queries the API endpoint:

  * ''http://api.deepskychile.com/observatories''

On each poll it:

  - Retrieves the list of observatories from the API.
  - Identifies the **selected observatory** (configured in the Setup dialog).
  - Reads its ''roofState'' value (typically ''open'' or ''closed'').
  - Converts this into an ASCOM ''IsSafe'' boolean:
    * Roof open  → safe
    * Roof closed → unsafe
  - Applies stale data protection logic.
  - Exposes ''IsSafe'' to any ASCOM client application.

===== Requirements =====
To use this driver you need:

  * A Windows PC
  * The **ASCOM Platform** installed
  * An internet connection to reach the Deep Sky Chile API
  * Client software that supports ASCOM ''SafetyMonitor'' devices (e.g. N.I.N.A., Voyager, etc.)

===== Installation =====
  - Download and run the driver installer.
  - The installer will:
    * Copy the driver files to your system
    * Register the COM driver with ASCOM
    * Create the necessary ASCOM profile entries

After installation, the driver appears in the ASCOM chooser as **Deep Sky Chile Safety Monitor** (or similar).

===== Configuration =====
Open the **Setup** dialog from any ASCOM-compatible application (via the ASCOM chooser → **Properties** / **Setup**).

You can configure:

  * **API URL**
    * Default: ''http://api.deepskychile.com/observatories''
    * Change this only if instructed by Deep Sky Chile.

  * **Observatory selection**
    * A dropdown list shows the available observatories returned by the API.
    * Select the observatory whose roof state should control ''IsSafe''.

  * **Polling interval**
    * Defines how often the driver polls the API.
    * Choose a value that balances responsiveness with network load.

  * **Stale data multiplier**
    * Protects against using outdated information.
    * If the data is older than ''multiplier × polling interval'', it can be treated as stale.

  * **Fail-safe mode**
    * Defines the default ''IsSafe'' value in case:
      - The API is unreachable, or
      - Data is stale or invalid.
    * Typical configuration:
      * Fail-safe to **unsafe** (''IsSafe = False'') for maximum safety.

  * **Trace logging**
    * When enabled, the driver logs detailed operations and any errors.

Trace logs are stored in:

  * ''Documents\ASCOM\Logs''

===== Usage with Automation Software =====
Example workflow with N.I.N.A. or similar software:

  - Open the application.
  - For the **Safety Monitor** (or equivalent) device:
    * Open the ASCOM chooser.
    * Select **Deep Sky Chile Safety Monitor**.
    * Click **Properties** / **Setup** to configure API URL, observatory, polling, etc.
    * Connect to the driver.

From that point:

  * The application can read ''IsSafe'' from the driver.
  * Roof open → ''IsSafe = True'' → automation may start or continue imaging (depending on your rules).
  * Roof closed → ''IsSafe = False'' → automation can park the mount, close sessions, etc.

Always configure your automation software so that **''IsSafe = False'' triggers protective actions.**

===== Logging and Troubleshooting =====
If something does not work as expected:

  - Enable **trace logging** in the Setup dialog.
  - Reproduce the issue (connection error, wrong safety state, etc.).
  - Check the log files in:
    * ''Documents\ASCOM\Logs''

Things to verify:

  * Can your PC reach the API URL in a web browser?
  * Is the correct observatory selected in the Setup dialog?
  * Is the polling interval reasonable?
  * Is the fail-safe mode set to the desired behaviour if the API is down?

===== Uninstallation =====
To uninstall the driver:

  - Open **Windows Settings** → **Apps** (or **Control Panel** → **Programs and Features**).
  - Find **Deep Sky Chile Safety Monitor** in the list.
  - Click **Uninstall**.

The uninstaller removes all related files and registry entries.

===== Support =====
For help, contact:

  * **Cédric Thomas**
  * E-mail: ''cedric@deepskychile.com''

===== Disclaimer =====
This driver depends entirely on the **Deep Sky Chile API** for the roof and safety information.

It must not be your only safety measure. Always implement additional, independent safety systems (hardware interlocks, local weather sensors, etc.) in any remote observatory.