Module ascom_alpaca::api
source · Expand description
ASCOM Alpaca Device API v1
The Alpaca API uses RESTful techniques and TCP/IP to enable ASCOM applications and devices to communicate across modern network environments.
Interface Behaviour
The ASCOM Interface behavioural requirements for Alpaca drivers are the same as for COM based drivers and are documented in the API Interface Definitions e.g. the Telescope.SlewToCoordinates method. This document focuses on how to use the ASCOM Interface standards in their RESTful Alpaca form.
Alpaca URLs, Case Sensitivity, Parameters and Returned values
Alpaca Device API URLs are of the form http(s)://host:port/path where path comprises “/api/v1/” followed by one of the method names below. e.g. for an Alpaca interface running on port 7843 of a device with IP address 192.168.1.89:
- A telescope “Interface Version” method URL would be http://192.168.1.89:7843/api/v1/telescope/0/interfaceversion
- A first focuser “Position” method URL would be http://192.168.1.89:7843/api/v1/focuser/0/position
- A second focuser “StepSize” method URL would be http://192.168.1.89:7843/api/v1/focuser/1/stepsize
- A rotator “Halt” method URL would be http://192.168.1.89:7843/api/v1/rotator/0/halt
URLs are case sensitive and all elements must be in lower case. This means that both the device type and command name must always be in lower case. Parameter names are not case sensitive, so clients and drivers should be prepared for parameter names to be supplied and returned with any casing. Parameter values can be in mixed case as required.
For GET operations, parameters should be placed in the URL query string and for PUT operations they should be placed in the body of the message.
Responses, as described below, are returned in JSON format and always include a common set of values including the client’s transaction number, the server’s transaction number together with any error message and error number. If the transaction completes successfully, the ErrorMessage field will be an empty string and the ErrorNumber field will be zero.
HTTP Status Codes and ASCOM Error codes
The returned HTTP status code gives a high level view of whether the device understood the request and whether it attempted to process it.
Under most circumstances the returned status will be 200
, indicating that the request was correctly formatted and that it was passed to the device’s handler to execute. A 200
status does not necessarily mean that the operation completed as expected, without error, and you must always check the ErrorMessage and ErrorNumber fields to confirm whether the returned result is valid. The 200
status simply means that the transaction was successfully managed by the device’s transaction management layer.
An HTTP status code of 400
indicates that the device could not interpret the request e.g. an invalid device number or misspelt device type was supplied. Check the body of the response for a text error message.
An HTTP status code of 500
indicates an unexpected error within the device from which it could not recover. Check the body of the response for a text error message.
SetupDialog and Alpaca Device Configuration
The SetupDialog method has been omitted from the Alpaca Device API because it presents a user interface rather than returning data. Alpaca device configuration is covered in the “ASCOM Alpaca Management API” specification, which can be selected through the drop-down box at the head of this page.
Macros
Structs
- AxisRate
telescope
Axis rate object - Devices collection.
- ImageArray
camera
Image array. - General information about the server.
Enums
- AlignmentMode
telescope
Returned side of pier - Axis
telescope
The axis of mount rotation. - CalibratorStatus
covercalibrator
Returned side of pier - CameraState
camera
Returned camera state - CoverStatus
covercalibrator
Returned side of pier - Returned dome shutter status
- DriveRate
telescope
DriveRate enum corresponding to one of the standard drive rates. - EquatorialSystem
telescope
Returned side of pier - ImageArrayRank
camera
Rank of an image array. - PutPulseGuideDirection
camera
ortelescope
The direction in which the guide-rate motion is to be made. - SensorType
camera
Returned sensor type - SideOfPier
telescope
Returned side of pier
Traits
- Camera
camera
Camera Specific Methods - CoverCalibrator
covercalibrator
CoverCalibrator Specific Methods - ASCOM Methods Common To All Devices
- Dome
dome
Dome Specific Methods - FilterWheel
filterwheel
FilterWheel Specific Methods - Focuser
focuser
Focuser Specific Methods - ObservingConditions
observingconditions
ObservingConditions Specific Methods - Rotator
rotator
Rotator Specific Methods - SafetyMonitor
safetymonitor
SafetyMonitor Specific Methods - Switch
switch
Switch Specific Methods - Telescope
telescope
Telescope Specific Methods