Safety Monitor Interface Proposal

Today's safety monitor interface is basic, it simply provides a boolean IsSafe property indicating whether or not a monitored condition is safe. No information is provided about why the condition is unsafe, or what the monitored condition is.

We have received community feedback about enabling SafetyMonitor devices to provide context about the source of the unsafe condition, and this interface revision is a response to that feedback.

This proposal extends the safety monitor interface in two ways:

• Provides safety event descriptions to clients about why monitored conditions are not safe. (Must be implemented.)
• Enables clients and drivers/devices to add their own safety event descriptions and make the safety monitor report IsSafe = false.(Optional implementation.)

The IsSafe property is unchanged so these additions are backward compatible with existing clients.

The proposed interface is described in the SafetyMonitorExtension section to the left and may change in the light of feedback.

To enable the interface to be trialled immediately, we propose an interim approach implemented through the Action / SupportedActions mechanic that all Platform 6 and later clients, drivers and devices support.

The following safety monitor Action names are reserved to implement the three new members:

• SafetyEvents
  - Returns a list of safety events that describe the current safety state of the device.
• SetExternalEvents
  - Accepts a list of safety events and adds them to the device's list of safety events.
• ClearExternalEvents
  - Accepts a list of safety event IDs and removes the corresponding events from the device's list of safety events.

Please see the SafetyMonitorExtension section opposite for class and enum definitions and behavioural information.

The SupportedActions property should return these Action names:

• SafetyEvents (mandatory)
• SetExternalEvents (only if implemented)
• ClearExternalEvents (only if implemented)

Please note that there is no need to implement the CanManageExternalEvents property in this interim implementation because the presence of the SetExternalEvents and ClearExternalEvents action names in the SupportedActions list is sufficient to indicate that external events can be managed.

The Action behaviours are as follows:

• Action Name: SafetyEvents
• Action Parameters: string.Empty
• Returns: A string containing a JSON encoded array of SafetyEvent objects .

See SafetyEvents Action Implementation Notes for more information.

• Action Name: SetExternalEvents
• Action Parameters: A string containing a JSON encoded array of SafetyEvent objects to add to the device's list of external safety events.
• Returns: ""

See SetExternalEvents Action Implementation Notes for more information.

• Action Name: ClearExternalEvents
• Action Parameters: A string containing a JSON encoded array of SafetyEvent.Id string values that identify the events to be removed from the device's list of external safety events.
• Returns: ""

See ClearExternalEvents Action Implementation Notes for more information.

Three areas of support are available to enable the proposed interface to be trialled immediately:

• Testing Clients - The new ASCOM Sentinel (link to Latest Release) application provides a reference implementation of the revised SafetyMonitor interface that clients can use to trial the interface.
• Testing Alpaca Devices and COM Drivers - The latest version of Conform Universal behaves as a reference client and displays safety events returned by Alpaca and COM driver implementations through SafetyEvents. It also exercises the SetExternalEvents and ClearExternalEvents actions to allow testing of these optional features.
• Code Definitions - A NuGet package containing the class and enum definitions required to implement the proposed interface is available from our MyGet feed. You will need to add this URL: https://www.myget.org/F/ascom-initiative/api/v3/index.json as a package source in your development tooling in order to see the package, which is named ISafetyMonitorV4Components.