ASCOM General Requirements

Revised 28-Jan-2016

In order to be called "ASCOM compliant", a driver, component, or application scripting interface must meet all of the applicable guidelines in this document. Only then may a driver, interface, or a component's packaging and user interface, carry the ASCOM logo.

Please Note:

Drivers

  1. The driver must install and run on on Microsoft Windows 10, 8.1, 7, Vista, and XP with the latest service packs at the time of driver release, and with User Account Control enabled at its default/normal setting. It should work on both 32- and 64-bit systems. Support for Windows 2000 is no longer provided.
  2. The driver author must implement the published standard for the device type as a late-bound COM interface. The published standards are specific about the data types that are used for properties and method parameters. These data types (and COM itself) are what make drivers cross language compatible. Note that by using a .NET language and the .NET driver templates we provide with the Platform Developer Components, this is all taken care-of for you. Also see item 6 below.
  3. The driver must never "extend" the standard interface (add private members - properties and/or methods). If private members are desired, they must be exposed through a separate non-standard interface. Starting with Platform 6, driver authors can also extend their drivers through the new Action and SupportedActions members that are now common to all device interface standards.
  4. The driver must never display a modal window which requires user interaction to dismiss. All errors must be raised/thrown back to the client.
  5. The driver must use the Profile's Register() method for ASCOM registration. It is recommended that drivers also use the Profile object for storage of their persistent configuration, state data, etc., as well as the Serial object serial port I/O. for The components are part of the ASCOM Platform and serve to isolate drivers from changes in Platform architecture. They also make develpment easier by providing high level functionality commonly needed by drivers.
  6. Prior to release, the driver must pass the Conform tests using the current/latest version of the Conformance Checker test tool.
  7. The driver must be delivered as a self-contained installer. It is unacceptable to ask users to copy files, edit the registry, run BAT files, etc. See Creating a Driver Installer.

Scriptable Components and Programs (not drivers)

  1. The product must run (at a minimum) on Microsoft Windows 7, Vista, and XP with the latest service packs at the time of driver release, and with User Account Control enabled at its default/normal setting. It should work on both 32- and 64-bit systems. Support for Windows 2000 is no longer provided.
  2. The name ASCOM and/or the ASCOM logo must never be displayed for products which are in experimental, beta, preview, or any other such state. Only production products which are available and supported by the vendor or author are eligible.
  3. Property and method names should be user friendly (e.g., SlewToCurrentObject instead of slw_curob). Use of so-called "Hungarian" notation is specifically discouraged. These interfaces may be used by scripters and should be user-friendly.
  4. Wherever practical, property and method names should be consistent with existing ASCOM standard interfaces. For example, a property that implements equatorial right ascension should be called RightAscension, as used in the Telescope standard interface.
  5. The product must implement scriptable dispatch ("Automation") interface(s) via the Microsoft Component Object Model (COM), and use only automation-compatible data types (see the data type requirements below).
  6. Errors within your product must raise Automation exceptions (via IErrorInfo). The error info must contain both an error number that is based on FACILITY_ITF and an informative error message in English and optionally other languages. Optionally, methods which do not return values should return VARIANT_BOOL indicating success or failure. This allows clients to determine status while ignoring exceptions (e.g. On Error Resume Next and try/catch). IErrorInfo support is essential to providing client writers with the behavior they rely on. Very few of these people manually test return values for errors with 'if' logic. They depend on their client environment to pop a meaningful alert box (or catch an exception with try/catch) when things go wrong.
  7. Components must be 100% usable from an automation client without user interaction. For example, it is not permitted to require a user to dismiss an error alert window when the program is being controlled through a component automation interface. On the other hand, it is permitted to require the user to use a program's configuration features to set preferences. Another example of non-compliant behavior is a component server whose behavior changes or stops depending on whether it is a foreground or background window. The point of this requirement is to assure that, when used from a script, the program will never hang awaiting some user action such as a window shuffle, or clearing an error message box or selector dialog. Raise an exception and return to the client for handling the error or establishing the selection.
  8. The product must be delivered as a self-contained installer. It is unacceptable to ask users to copy files, edit the registry, etc. See Creating a Driver Installer.
  9. Executable components must self-register when first started, and must support the command line options /REGSERVER and /UNREGSERVER to manually register and unregister them. Invocation with either of these options must immediately exit and must not start the program.
  10. Any executable component must start automatically if one of the objects it serves is created by a client. Furthermore, it must exit automatically when the last reference to any object it is serving is deleted. Unless there is a good reason to do otherwise, an executable component should start in a minimized window. This is not a hard requirement as a component may benefit from displaying information as it operates. Unless this is the case, though, the component should remain out of sight (minimized) unless manually made visible by the user.

Scripting Interface Requirements

Besides the compatibility requirements described above, ASCOM interfaces must comply with the following. Remember that a major goal of ASCOM is to make programming with scripts straightforward, consistent, and non-intimidating for "ordinary people":
  1. Property and method names must be user friendly (e.g., SlewToCurrentObject instead of slw_curob). Use of so-called "Hungarian" notation is specifically discouraged. These interfaces are for the use of ordinary people.
  2. Wherever practical, property and method names should be consistent with existing ASCOM standard interfaces. For example, a property that implements equatorial right ascension should be called RightAscension, as used in the Telescope standard interface.
  3. Methods must not be used to implement what are really properties. For example, a pair of methods called SetSpeed(newSpeed) and GetSpeed() are really a property Speed.
  4. Interfaces for drivers must contain at least a Connected property and a SetupDialog() method. The Connected property establishes or breaks the physical link between the object and the device under control. The SetupDialog() method causes a modal dialog to appear which is used to configure the object for use with the device. Any settings that must persist must be the responsibility of the object itself, clients must not be required to persist object state.
  5. The interface must be a scriptable dispatch ("Automation") interface per the Microsoft Component Object Model (COM), and use only automation-compatible data types (see the data type requirements below). It is not permitted to require the use of VTBL binding (via standard abstract interfaces). While a "dual" interface is permitted, ASCOM core functionality demands the use of IDispatch and "loose binding". It must be possible to use the interface from scripting languages which support only dispatch binding, and it must be possible to implement the interface with a Windows Script Component ("scriptlet"), which cannot expose a VTBL.
  6. All properties, method parameters, and method return values must be Automation-compatible types such as INT, LONG, DOUBLE, SINGLE, BSTR, DATE, VARIANT_BOOL, and VARIANT/VT_DISPATCH. Any arrays produced and consumed by your product must be passsed as a VARIANT. In short, all data items must be 100% compatible with Automation, and specifically with ActiveX Scripting engines including both VBScript V5 and JScript V5 (or later) and with Visual Basic for Applications V5 (or later).
  7. Method parameters must be passed only by value, as required by some ActiveX Scripting engines (notably JScript). Consider passing object references (VT_DISPATCH) by value as a way to have methods work on arbitrary (non-Automation) data owned by the client.

Client Programs

  1. The product must run (at a minimum) on Microsoft Windows 7, Vista, and XP with the latest service packs at the time of driver release, and with User Account Control enabled at its default/normal setting. It should work on both 32- and 64-bit systems. Support for Windows 2000 is no longer provided.
  2. The product must be capable of using scriptable dispatch ("automation") interface(s) via the Microsoft Component Object Model (COM). The the client must be able to call via IDispatch. Clients written in .NET should take advantage of the client toolkit, a library that provides access to the late-bound driver interfaces while presenting a fully strict IntelliSense environment to the client developer, even in C#.
  3. Error exceptions (raised in a component via IErrorInfo) must be caught and handled by the program in a way that gives the user the error message that came from the component. It is not permitted to display a "friendly", "generic", or otherwise mangled version of an error message in the exception.

Logo Usage

If you have a driver or an astronomy product that conforms to these requirements, feel free to use the logo on your web site and product packaging, as long as you do the following:

  1. If you use the logo on a web site, please link it back to this site http://ascom-standards.org/
  2. Post a note to ASCOM-Talk indicating your product, company, and URL. The moderator or other responsible person will add you to the partners page and link to your web site.
Please This is on the honor system, there are no contracts or other covenants required. Please don't undermine this effort by ASCOM-labeling software that doesn't meet the above requirements. Make the effort and your software will be better for it!