1 /* 2 SPDX-FileCopyrightText: 2012 Jasem Mutlaq <mutlaqja@ikarustech.com> 3 4 SPDX-License-Identifier: GPL-2.0-or-later 5 */ 6 7 #ifndef INDICOMMON_H 8 #define INDICOMMON_H 9 10 #include <QString> 11 #include <QMap> 12 13 /*! 14 \page INDI "INDI Overview" 15 \tableofcontents 16 17 \section Intro Introduction 18 19 INDI is a simple XML-like communications protocol described for interactive and automated remote control of diverse instrumentation. INDI is small, easy to parse, and stateless. 20 The main key concept in INDI is that devices have the ability to describe themselves. This is accomplished by using XML to describe a generic hierarchy that can represent both canonical and 21 non-canonical devices. All devices may contain one or more properties. A property in the INDI paradigm describes a specific function of the driver. 22 Any property may contain one or more elements. There are four types of INDI properties: 23 24 <ul> 25 <li><b>Text property</b>: Property to transfer simple text information in ISO-8859-1. The text is not encoded or encrypted on transfer. If the text includes elements that can break XML syntax, a BLOB property should be used to make the transfer.</li> 26 <li><b>Number property</b>: Property to transfer numeric information with configurable minimum, maximum, and step values. The supported number formats are decimal and sexigesmal. The property includes a GUI hint element in printf style format to enable clients to properly display numeric properties.</li> 27 <li><b>Switch property</b>: Property to hold a group of options or selections (Represented in GUI by buttons and check boxes).</li> 28 <li><b>Light property</b>: Property to hold a group of status indicators (Represented in GUI by colored LEDs).</li> 29 <li><b>BLOB property</b>: BLOB is a Binary Large OBject used to transfer binary data to and from drivers.</li> 30 </ul> 31 32 For example, all INDI devices share the CONNECTION standard switch property. The CONNECTION property has two elements: CONNECT and DISCONNECT switches. 33 GUI clients parse the generic XML description of properties and builds a GUI representation suitable for direct human interaction. 34 35 KStars is a fully featured INDI client. INDI Data (i.e. devices and properties) and GUI (how they appear on the screen) are separated. INDI adopts is a server/client architecture where one or more servers 36 communicate with one or more drivers, each driver can communicate with one or more actual hardware devices. Clients connect to the server, obtain a list of devices, and generate GUI to represent the 37 devices for user interaction and control. The creation of GUI happens in run time via introspection. 38 39 \section Structure Hierarchy 40 41 The following is a description of some of the various classes that support INDI: 42 43 <ul> 44 <li>DriverManager: Manages local drivers as installed by INDI library. Enables users to start/stop local INDI servers (ServerManager) running one or more drivers (DriverInfo). Also enables connecting to local or remote 45 INDI servers. For both local and remote connection, it creates a ClientManager to handle incoming data from each INDI server started, and creates a GUIManager to render the devices in INDI Control Panel. 46 The user may also choose to only start an INDI server without a client manager and GUI.</li> 47 <li>ClientManager: Manages sending and receiving data from and to an INDI server. The ClientManager sends notifications (signals) when a new device or property is defined, updated, or deleted.</li> 48 <li>GUIManager: Handles creation of GUI interface for devices (INDI_D) and their properties and updates the interface in accord with any data emitted by the associated ClientManager. The GUI manager supports 49 multiple ClientManagers and consolidate all devices from all the ClientManagers into a single INDI Control Panel where each device is created as a tab.</li> 50 <li>INDIListener: Once a ClientManager is created in DriverManager after successfully connecting to an INDI server, it is added to INDIListener where it monitors any new devices and if a new 51 device is detected, it creates an ISD::GenericDevice to hold the data of the device. It also monitors new properties and registers them. If it detects an INDI standard property associated with a particular device family 52 (e.g. Property EQUATORIAL_EOD_COORD is a standard property of a Telescope device), then it extends the ISD::GenericDevice to the particular specialized device type using the <a href="http://en.wikipedia.org/wiki/Decorator_pattern"> 53 Decorator Pattern</a>. All updated properties from INDI server are delegated to their respective devices.</li> 54 <li>ServerManager</li> Manages establishment and shutdown of local INDI servers.</li> 55 <li>DriverInfo</li>: Simple class that holds information on INDI drivers such as name, version, device type..etc.</li> 56 <li>ISD::GDInterface: Abstract class where the ISD::DeviceDecorator and ISD::GenericDevice are derived.</li> 57 <li>ISD::DeviceDecorator: Base class of all specialized decorators such as ISD::Telescope, ISD::Filter, and ISD::CCD devices.</li> 58 <li>ISD::GenericDevice: Base class for all INDI devices. It implements processes shared across all INDI devices such as handling connection/disconnection, setting of configuration..etc.. When a 59 specialized decorator is created (e.g. ISD::Telescope), the decorator is passed an ISD::GenericDevice pointer. Since ISD::Telescope is a child of ISD::DeviceDecorator, it can override some or all 60 the device specific functions as defined in ISD::GDInterface (e.g. ProcessNumber(INumberVectorProperty *nvp)). For any function that is not overridden, the parent ISD::DeviceDecorator will invoke 61 the function in ISD::GenericDevice instead. Moreover, The specialized decorator device can explicitly call DeviceDecorator::ProcessNumber(INumberVectorProperty *nvp) for example to cause the ISD::DeviceDecorator to invoke 62 the same function but as defined in ISD::GenericDevice.</li> 63 </ul> 64 65 \section Example Example 66 67 Suppose the user wishes to control an EQMod mount with \e indi_eqmod_telescope driver. From the DriverManager GUI, the user selects the driver and \e starts INDI services. The DriverManager 68 will create a ServerManager instance to run an INDI server with the EQMod driver executable. After establishing the server, the DriverManager will create an instance of ClientManager and set 69 its INDI server address as the host and port of the server created in ServerManager. For local servers, the host name is \e localhost and the default INDI port is 7624. If connection to the INDI server 70 is successful, DriverManager then adds the ClientManager to both INDIListener (to handle data), and GUIManager (to handle GUI). Since the ClientManager emits signals whenever a new, updated, or deleted 71 device/property is received from INDI server, it affects both the data handling part as well as GUI rendering. 72 73 INDIListener holds a list of all INDI devices in KStars regardless of their origin. Once INDIListener receives a new device from the ClientManager, it creates a new ISD::GenericDevice. At the GUIManager side, it creates INDI Control Panel and adds a new tab with the device name. 74 It also creates a separate tab for each property group received. The user is presented with a basic GUI to set the connection port of EQMod and to connect/disconnect to/from the telescope. If the 75 user clicks connect, the status of the connection property is updated, and INDI_P sends the new switch status (CONNECT=ON) to INDI server via the ClientManager. If the connection is successful 76 at the driver side, it will start defining new properties to cover the complete functionality of the EQMod driver, one of the standard properties is EQUATORIAL_EOD_COORD which will be detected 77 in INDIListener. Upon detection of this key signature property, INDIListener creates a new ISD::Telescope device while passing to it the ISD::GenericDevice instance created earlier. 78 79 Now suppose an updated Number property arrives from INDI server, the ClientManager emits a signal indicating a number property has a new updated value and INDIListener delegates the INDI Number 80 property to the device, which is now of type ISD::Telescope. The ISD::Telescope overridden the processNumber(INumberVectorProperty *nvp) function in ISD::DeviceDecorator because it wants to handle some telescope 81 specific numbers such as EQUATORIAL_EOD_COORD in order to move the telescope marker on the sky map as it changes. If the received property was indeed EQUATORIAL_EOD_COORD or any property handled 82 by the ISD::Telescope ProcessNumber() function, then there is no further action needed. But what if the property is not processed in ISD::Telescope ProcessNumber() function? In this case, the 83 ProcessNumber() function simply calls DeviceDecorator::ProcessNumber() and it will delgate the call to ISD::GenericDevice ProcessNumber() to process. This is how the Decorator pattern work, 84 the decorator classes implements extended functionality, but the basic class is still responsible for handling all of the basic functions. 85 86 */ 87 88 #define INDIVERSION 1.7 /* we support this or less */ 89 90 typedef enum { PRIMARY_XML, THIRD_PARTY_XML, EM_XML, HOST_SOURCE, CUSTOM_SOURCE, GENERATED_SOURCE } DriverSource; 91 92 typedef enum { SERVER_CLIENT, SERVER_ONLY } ServerMode; 93 94 typedef enum { DATA_FITS, DATA_VIDEO, DATA_CCDPREVIEW, DATA_ASCII, DATA_OTHER } INDIDataTypes; 95 96 typedef enum { LOAD_LAST_CONFIG, SAVE_CONFIG, LOAD_DEFAULT_CONFIG, PURGE_CONFIG } INDIConfig; 97 98 typedef enum { NO_DIR = 0, RA_INC_DIR, RA_DEC_DIR, DEC_INC_DIR, DEC_DEC_DIR } GuideDirection; 99 100 /* GUI layout */ 101 #define PROPERTY_LABEL_WIDTH 100 102 #define PROPERTY_LABEL_HEIGHT 30 103 #define ELEMENT_LABEL_WIDTH 175 104 #define ELEMENT_LABEL_HEIGHT 30 105 #define ELEMENT_READ_WIDTH 175 106 #define ELEMENT_WRITE_WIDTH 175 107 #define ELEMENT_FULL_WIDTH 340 108 #define MIN_SET_WIDTH 50 109 #define MAX_SET_WIDTH 110 110 #define MED_INDI_FONT 2 111 #define MAX_LABEL_LENGTH 20 112 113 typedef enum { PG_NONE = 0, PG_TEXT, PG_NUMERIC, PG_BUTTONS, PG_RADIO, PG_MENU, PG_LIGHTS, PG_BLOB } PGui; 114 115 /* new versions of glibc define TIME_UTC as a macro */ 116 #undef TIME_UTC 117 118 /* INDI std properties */ 119 enum stdProperties 120 { 121 CONNECTION, 122 DEVICE_PORT, 123 TIME_UTC, 124 TIME_LST, 125 TIME_UTC_OFFSET, 126 GEOGRAPHIC_COORD, /* General */ 127 EQUATORIAL_COORD, 128 EQUATORIAL_EOD_COORD, 129 EQUATORIAL_EOD_COORD_REQUEST, 130 HORIZONTAL_COORD, /* Telescope */ 131 TELESCOPE_ABORT_MOTION, 132 ON_COORD_SET, 133 SOLAR_SYSTEM, 134 TELESCOPE_MOTION_NS, /* Telescope */ 135 TELESCOPE_MOTION_WE, 136 TELESCOPE_PARK, /* Telescope */ 137 CCD_EXPOSURE, 138 CCD_TEMPERATURE_REQUEST, 139 CCD_FRAME, /* CCD */ 140 CCD_FRAME_TYPE, 141 CCD_BINNING, 142 CCD_INFO, 143 CCD_VIDEO_STREAM, /* Video */ 144 FOCUS_SPEED, 145 FOCUS_MOTION, 146 FOCUS_TIMER, /* Focuser */ 147 FILTER_SLOT, /* Filter */ 148 WATCHDOG_HEARTBEAT 149 }; /* Watchdog */ 150 151 /* Devices families that we explicitly support (i.e. with std properties) */ 152 typedef enum 153 { 154 KSTARS_ADAPTIVE_OPTICS, 155 KSTARS_AGENT, 156 KSTARS_AUXILIARY, 157 KSTARS_CCD, 158 KSTARS_DETECTORS, 159 KSTARS_DOME, 160 KSTARS_FILTER, 161 KSTARS_FOCUSER, 162 KSTARS_ROTATOR, 163 KSTARS_SPECTROGRAPHS, 164 KSTARS_TELESCOPE, 165 KSTARS_WEATHER, 166 KSTARS_UNKNOWN 167 } DeviceFamily; 168 169 const QMap<DeviceFamily, QString> DeviceFamilyLabels = 170 { 171 {KSTARS_ADAPTIVE_OPTICS, "Adaptive Optics"}, 172 {KSTARS_AGENT, "Agent"}, 173 {KSTARS_AUXILIARY, "Auxiliary"}, 174 {KSTARS_CCD, "CCDs"}, 175 {KSTARS_DETECTORS, "Detectors"}, 176 {KSTARS_DOME, "Domes"}, 177 {KSTARS_FILTER, "Filter Wheels"}, 178 {KSTARS_FOCUSER, "Focusers"}, 179 {KSTARS_ROTATOR, "Rotators"}, 180 {KSTARS_SPECTROGRAPHS, "Spectrographs"}, 181 {KSTARS_TELESCOPE, "Telescopes"}, 182 {KSTARS_WEATHER, "Weather"}, 183 {KSTARS_UNKNOWN, "Unknown"}, 184 }; 185 186 typedef enum { FRAME_LIGHT, FRAME_BIAS, FRAME_DARK, FRAME_FLAT, FRAME_NONE } CCDFrameType; 187 188 const QMap<CCDFrameType, QString> CCDFrameTypeNames = 189 { 190 {FRAME_LIGHT, "Light"}, 191 {FRAME_DARK, "Dark"}, 192 {FRAME_BIAS, "Bias"}, 193 {FRAME_FLAT, "Flat"}, 194 {FRAME_NONE, ""}, 195 }; 196 197 198 typedef enum { SINGLE_BIN, DOUBLE_BIN, TRIPLE_BIN, QUADRAPLE_BIN } CCDBinType; 199 200 typedef enum 201 { 202 INDI_SEND_COORDS, 203 INDI_FIND_TELESCOPE, 204 INDI_CENTER_LOCK, 205 INDI_CENTER_UNLOCK, 206 INDI_CUSTOM_PARKING, 207 INDI_SET_PORT, 208 INDI_CONNECT, 209 INDI_DISCONNECT, 210 INDI_SET_FILTER, 211 INDI_SET_FILTER_NAMES, 212 INDI_CONFIRM_FILTER, 213 INDI_SET_ROTATOR_TICKS, 214 INDI_SET_ROTATOR_ANGLE 215 } DeviceCommand; 216 217 typedef enum { SOURCE_MANUAL, SOURCE_FLATCAP, SOURCE_WALL, SOURCE_DAWN_DUSK, SOURCE_DARKCAP } FlatFieldSource; 218 219 typedef enum { DURATION_MANUAL, DURATION_ADU } FlatFieldDuration; 220 221 #endif // INDICOMMON_H 222