ASCOM Interface Principle (rev. Dec 2019)

Introduction

This ASCOM "business" principle has been formulated to guide decisions on introduction of new interfaces or modification of existing interfaces. The need for this principle arose from discussions in June 2019 on whether flat panels should be supported through their own unique interface or through a specialised expression of the very flexible Switch interface.

Statement

ASCOM interfaces represent complex equipment capabilities in a device neutral way using meaningful interface and member names with defined behaviours. Their intent is to enable applications to focus exclusively on the operational act of observing.

Creation of a new ASCOM device interface, or adding a new feature to an existing one, requires that:

Rationale

A device neutral interface representation enables:

Meaningful member names and defined behaviours reduce errors and speed up development and testing of applications and drivers. The application developer and hardware vendor communities are key beneficiaries of ASCOM interfaces, their involvement is essential to demonstrate demand and ensure that interfaces are effective and provide value. ASCOM interfaces add most value for devices with complex behaviours or operational configuration requirements, simple requirements will be met through existing interfaces wherever possible to manage ASCOM's overall complexity.

Modern astronomy equipment often has complex configuration capabilities which are important to optimising device performance. However, these are frequently manufacturer specific or not commonly used within a device class. Some are set in down time outside operational observing sessions and just used "as configured" during observation e.g. telescope mount modelling. Furthermore, manufacturers increasingly provide advanced monitoring of detailed manufacturer specific device behaviour such as mount motor currents.

ASCOM interfaces focus on essential activities during the operational act of observing, and consequently only support control of parameters that an observer needs to change during a real observation session. The use of unique device interfaces with meaningful member names is favoured over more generic approaches, such as using the Switch interface, because:

  1. In a named interface, use of correct member names is enforced at compile time. When using the Switch interface, specific capabilities must be assigned to "well-known" switch numbers or switch names. Errors in these Switch numbers and names will only show up at run time and increases the support burden for application developers and driver authors.
  2. Well known switch numbers or switch names must be established and managed separately for each "virtual" device interface implemented through the Switch interface. Casing rules for switch names must be established.
  3. Switches can only be accessed through their device number and not by their name. This requires client applications to iterate over the switch device list to map any "well-known" switch names to their associated switch numbers.

Implications

  1. A new interface, or interface change, will be a response to clear requirements and use cases. Changes whose justifications lack clarity or shared support will be rejected.
  2. New device types will have named interfaces with meaningful methods names except when the interface only has one boolean or numeric property, in which case the Switch interface will be used.
  3. In general, creation of a new interface will require support from at least two commercial application authors and two device manufacturers.
  4. Devices that support multiple states will have their own named interfaces.
  5. Devices that have complex run-time configuration options or monitoring capabilities will expose these through their own driver or management application. The device will be responsible for displaying and responding to any device specific monitoring / control GUI and for providing a standard ASCOM device interface that client applications use during an observing session.
  6. The Switch interface will not be used to construct complex interfaces where capabilities are assigned to "well-known" switch numbers or switch names.
  7. Low level monitoring and simple control functions such as turning off observatory lighting, measuring mains power voltage and monitoring backup UPS status will be implemented using the Switch interface.
  8. Devices with a single boolean / numeric property will be implemented through the Switch interface.
  9. The SupportedActions/Action methods will be used to:
    1. Provide proprietary extensions to driver functionality.
    2. Trial potential interface changes by creating "common naming agreements" where well known action names provide the same functionality in different drivers. This allows early implementation without the need for an immediate interface version change.