Introduction - ASCOM Platform 7 For Developers |
This topic contains the following sections:
IntroductionPlatform 7 builds on the architectural changes introduced in Platform 6 with a strong new focus on asynchronous operation. Many Platform 6 interface operations were already explicitly documented as asynchronous and had associated pollable completion properties. Platform 7 ensures that all potentially long running operations are now defined as asynchronous and have associated completion properties.
Some new asynchronous methods and completion properties have been introduced where these were missing from the Platform 6 interface definitions. See the Key Interface Changes section below for details.
With the introduction of fully asynchronous operation, ASCOM is introducing a 1 second target time for completion of asynchronous operation initiation. Of course, the overall operation can take as long as required, it is just the initiation that has a target time. Our interface conformance checker Conform Universal can provide a full timing analysis so you can check how long interface methods take to complete.
Please see Version 7.0 for a detailed list of other Platform changes and fixes for both developers and Platform users.
Connect, Disconnect and ConnectingConnecting to drivers and Alpaca devices has always been effected through the Connected property (Focuser.Link aside), which operates synchronously. For Platform 7 we have introduced an asynchronous connection mechanic for all interfaces to accommodate devices with longer startup times. This operates similarly to other ASCOM asynchronous methods with an initiator: Connect() or Disconnect(), which must return quickly after stating hardware and software initialisation, and a completion property: Connecting that clients can poll regularly to determine when the process completes or errors.
Drivers and Alpaca devices that implement Platform 7 interfaces must implement the asynchronous connection mechanic as well as supporting the Connected mechanic for backward compatibility with earlier clients.
For the most reliable operation, clients should always check the device's interface version and use the new asynchronous connection mechanic if the device supports it.
Telescope SlewingThe Telescope interface has several methods that are specifically defined as operating synchronously, which can be problematic for COM applications and that are unreliable over network connections for Alpaca clients.
Further detail on new implementation requirements for COM clients and drivers and Alpaca clients and devices is set out here: Synchronous and Asynchronous Telescope Slewing.
DeviceState PropertyEvery interface now includes a DeviceState property that returns all the device's operational state in a single call. This has been introduced to reduce the number of polling calls required to monitor the device's operational state. A property is considered Operational if it can change during normal operation e.g a mount's right ascension and declination while slewing. Properties like telescope site latitude are excluded because their values do not change during operation.
Keeping the number of properties to a manageable size was considered important to improve response time and reduce loading on low power devices and to avoid creating large network responses that could cause issues on slower links. The table below shows the properties that are returned for each device type. The TimeStamp value is the time at which the device state was determined, if known, in ISO 8601 format.
Device type | Operational Properties |
|---|---|
Camera | CameraState, CCDTemperature, CoolerPower, HeatSinkTemperature, ImageReady, IsPulseGuiding, PercentCompleted, TimeStamp |
CoverCalibrator | Brightness, CalibratorState, CoverState, CalibratorReady, CoverMoving, TimeStamp |
Dome | Altitude, AtHome, AtPark, Azimuth, ShutterStatus, Slewing, TimeStamp |
FilterWheel | Position, TimeStamp |
Focuser | IsMoving, Position, Temperature, TimeStamp |
ObservingConditions | CloudCover, DewPoint Humidity, Pressure, RainRate, SkyBrightness, SkyQuality, SkyTemperature, StarFWHM, Temperature, WindDirection, WindGust, WindSpeed, TimeStamp |
Rotator | IsMoving, MechanicalPosition, Position, TimeStamp |
SafetyMonitor | IsSafe, TimeStamp |
Switch | See Device State Implementation and Requirements for further information on use and required behaviour. GetSwitch0, GetSwitch1, GetSwitch2, GetSwitchN-1, GetSwitchValue0, GetSwitchValue1, GetSwitchValue2, GetSwitchValueN-1, StateChangeComplete0, StateChangeComplete1, StateChangeComplete2, StateChangeComplete N-1, TimeStamp |
Telescope | Altitude, AtHome, AtPark, Azimuth, Declination, IsPulseGuiding, RightAscension. SideOfPier, SiderealTime, Slewing, Tracking, UTCDate, TimeStamp |
Video | CameraState, TimeStamp |
Platform 7 Interface change summaryInterface | Change |
|---|---|
All | New asynchronous Connect() and Disconnect() methods to replace the PUT Connected property. A new Connecting property acts as the completion property for connect / disconnect operations. Driver authors must continue to implement PUT Connected to ensure backward compatibility. |
All | A new DeviceState property returns all operational properties of the device in a single call. |
CoverCalibrator | A new CalibratorChanging completion property to monitor the state of the CalibratorOn and CalibratorOff operations. The CalibratorState property must continue to reflect the device's state to ensure backward compatibility. |
CoverCalibrator | A new CoverMoving completion property to monitor the state of the CoverCalibrator OpenCover and CloseCover operations. The CoverState property must continue to reflect the device's state to ensure backward compatibility. |
Dome | AbortSlew() is now explicitly defined as asynchronous with Slewing as the completion property. |
Switch | New asynchronous SetAsync() and SetAsyncValue() methods to support long-running Switch operations. The new StateChangeComplete property acts as the completion property for asynchronous switch operations. |
Telescope | FindHome(), Park() and MoveAxis() are explicitly defined as asynchronous using Slewing as the completion property. |
Telescope | PulseGuide is explicitly defined as asynchronous with IsPulseGuiding as the completion property. |
Telescope | The synchronous slewing methods in the Telescope interface have been deprecated for client authors in favour of their asynchronous counterparts. |
Telescope | Driver authors must implement both the synchronous and asynchronous slew methods when programmatic slewing is supported. The synchronous methods must be implemented to ensure backward compatibility with older clients. A consequence of this is that the CanSlew and CanSlewAsync properties will always have the same value. This also applies to the CanSlewAltAz and CanSlewAltAzAsync properties. |
Telescope | AbortSlew() is now explicitly defined as asynchronous with Slewing as the completion property. |
Telescope | Drivers must now reject attempts to set RightAscensionRate or DeclinationRate when TrackingRate is not driveSidereal by throwing an InvalidOperationException. This is because the offsets are only valid when tracking at sidereal rate. |
Telescope | ParkedException is now specified to be thrown in methods where operations are invalid while parked. |
Telescope | The equatorial slewing methods must now throw an InvalidOperationException if called while Tracking is False or when the requested slew would fail due to exceeding a hardware limit of the mount. |
See Also