ASCOM SafetyMonitor: Difference between revisions

From Deep Sky Chile
← Older edit
No edit summary
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
====== Deep Sky Chile Safety Monitor (ASCOM Driver) ======
This page describes the '''Deep Sky Chile Safety Monitor''' ASCOM driver.


===== Overview =====
It reads the roof state of a selected observatory via the Deep Sky Chile API and exposes it as the ASCOM <code>SafetyMonitor</code> property <code>IsSafe</code>.
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.
See also: [[ASCOM_ObservingConditions|Deep Sky Chile Observing Conditions (ASCOM driver)]]


Mapping:
== Overview ==


  * **Roof open** → ''IsSafe = True''
The '''Deep Sky Chile Safety Monitor''' is an ASCOM-compliant driver that exposes the '''safety status''' of Deep Sky Chile observatories.
  * **Roof closed** → ''IsSafe = False''
 
It converts the roof state into the standard ASCOM <code>IsSafe</code> value:
 
* '''Roof open''' → <code>IsSafe = True</code> 
* '''Roof closed''' → <code>IsSafe = False</code> 


This driver is intended for remote observatory automation systems that rely on an ASCOM SafetyMonitor to decide whether it is safe to operate equipment.
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 =====
== Features ==
  * ASCOM ''SafetyMonitor'' implementation
 
  * Periodic polling of the Deep Sky Chile observatories API
* ASCOM <code>SafetyMonitor</code> implementation
  * Observatory selection via dropdown list
* Periodic polling of the Deep Sky Chile observatories API
  * Roof state-to-safety mapping
* Observatory selection via dropdown list
  * Stale data protection
* Roof-state-to-safety mapping
  * Optional trace logging
* Stale-data protection
  * Configurable fail-safe mode
* Optional trace logging
* Configurable fail-safe mode
 
== How it works ==


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


  * ''http://api.deepskychile.com/observatories''
* <code>http://api.deepskychile.com/observatories</code>


On each poll it:
On each poll it:


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


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


  * A Windows PC
* A Windows PC
  * The **ASCOM Platform 7.1 or later** installed
* The '''ASCOM Platform 7.1 or later''' installed
  * An internet connection to reach the Deep Sky Chile API
* 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.)
* Client software that supports ASCOM <code>SafetyMonitor</code> devices (for example N.I.N.A., Voyager, etc.)
 
== Installation ==


===== Installation =====
# Download and run the driver installer from your Deep Sky Chile customer area.
  - Download and run the driver installer.
# The installer will:
  - The installer will:
#* Copy the driver files to your system
    * Copy the driver files to your system
#* Register the COM driver with ASCOM
    * Register the COM driver with ASCOM
#* Create the necessary ASCOM profile entries
    * Create the necessary ASCOM profile entries


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


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


You can configure:
You can configure:


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


  * **Observatory selection**
* Default: <code>http://api.deepskychile.com/observatories</code> 
    * A dropdown list shows the available observatories returned by the API.
* Change this only if instructed by Deep Sky Chile.
    * Select the observatory whose roof state should control ''IsSafe''.


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


  * **Stale data multiplier**
* A dropdown list shows the available observatories returned by the API. 
    * Protects against using outdated information.
* Select your observatory from the list. The roof state of the selected observatory will determine the value of <code>IsSafe</code>.
    * If the data is older than ''multiplier × polling interval'', it can be treated as stale.


  * **Fail-safe mode**
'''Polling interval'''
    * 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**
* Defines how often the driver polls the API. 
    * When enabled, the driver logs detailed operations and any errors.
* Choose a value that balances responsiveness with network load.
 
'''Stale-data multiplier'''
 
* Protects against using outdated information. 
* If the data is older than <code>multiplier × polling interval</code>, it can be treated as stale.
 
'''Fail-safe mode'''
 
* Defines the default <code>IsSafe</code> value if:
* The API is unreachable, or 
* Data is stale or invalid.
* Typical setting:
** Fail-safe to '''unsafe''' (<code>IsSafe = False</code>) for maximum safety.
 
'''Trace logging'''
 
* When enabled, the driver logs detailed operations and any errors.


Trace logs are stored in:
Trace logs are stored in:


  * ''Documents\ASCOM\Logs''
* <code>Documents\ASCOM\Logs</code>
 
== Usage with automation software ==


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


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


From that point:
Once connected:


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


Always configure your automation software so that **''IsSafe = False'' triggers protective actions.**
Always configure your automation software so that '''<code>IsSafe = False</code> triggers protective actions'''.
 
== Logging and troubleshooting ==


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


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


Things to verify:
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 correct observatory selected in the Setup dialog?
* Is the polling interval reasonable?
  * Is the polling interval reasonable?
* Is the fail-safe mode set to the desired behaviour if the API is down?
  * Is the fail-safe mode set to the desired behaviour if the API is down?
 
== Uninstallation ==


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


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


The uninstaller removes all related files and registry entries.
The uninstaller removes all related files and registry entries.


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


  * **Cédric Thomas**
* '''Cédric Thomas''' 
  * E-mail: ''[email protected]''
* E-mail: <code>[email protected]</code>
 
== Disclaimer ==
 
This driver depends entirely on the '''Deep Sky Chile API''' for the roof and safety information.


===== Disclaimer =====
It must not be your only safety measure. Always implement additional, independent safety systems (hardware interlocks, local weather sensors, etc.).
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.


[[Category:User manuals]]
[[Category:User manuals]]

Latest revision as of 13:48, 4 December 2025

This page describes the Deep Sky Chile Safety Monitor ASCOM driver.

It reads the roof state of a selected observatory via the Deep Sky Chile API and exposes it as the ASCOM SafetyMonitor property IsSafe.

See also: Deep Sky Chile Observing Conditions (ASCOM driver)

Overview[edit]

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

It converts the roof state into the standard ASCOM IsSafe value:

  • 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[edit]

  • 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[edit]

The driver periodically queries the API endpoint:

On each poll it:

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

Requirements[edit]

To use this driver you need:

  • A Windows PC
  • The ASCOM Platform 7.1 or later installed
  • An internet connection to reach the Deep Sky Chile API
  • Client software that supports ASCOM SafetyMonitor devices (for example N.I.N.A., Voyager, etc.)

Installation[edit]

  1. Download and run the driver installer from your Deep Sky Chile customer area.
  2. 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[edit]

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

You can configure:

API URL

Observatory selection

  • A dropdown list shows the available observatories returned by the API.
  • Select your observatory from the list. The roof state of the selected observatory will determine the value of 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 if:
  • The API is unreachable, or
  • Data is stale or invalid.
  • Typical setting:
    • 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[edit]

Example workflow with N.I.N.A. or similar software:

  1. Open the application.
  2. 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.

Once connected:

  • 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[edit]

If something does not work as expected:

  1. Enable trace logging in the Setup dialog.
  2. Reproduce the issue (connection error, wrong safety state, etc.).
  3. Check the log files in:
    • Documents\ASCOM\Logs

Things to verify:

  • 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[edit]

To uninstall the driver:

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

The uninstaller removes all related files and registry entries.

Support[edit]

For help, contact:

Disclaimer[edit]

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

Retrieved from "https://wiki.deepskychile.com/index.php?title=ASCOM_SafetyMonitor&oldid=120"