1 /******************************************************************************* 2 Copyright(c) 2017 Jasem Mutlaq. All rights reserved. 3 4 List of INDI Stanadrd Properties 5 6 This library is free software; you can redistribute it and/or 7 modify it under the terms of the GNU Library General Public 8 License version 2 as published by the Free Software Foundation. 9 10 This library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Library General Public License for more details. 14 15 You should have received a copy of the GNU Library General Public License 16 along with this library; see the file COPYING.LIB. If not, write to 17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 18 Boston, MA 02110-1301, USA. 19 *******************************************************************************/ 20 21 #pragma once 22 23 #include "indibase.h" 24 25 namespace INDI 26 { 27 28 /** 29 * @namespace INDI::SP 30 @brief INDI Standard Properties are common properties standarized across drivers and clients alike. 31 32 INDI does not place any special semantics on property names (i.e. properties are just texts, numbers, or switches that represent no physical function). While GUI clients can construct graphical representation of properties in order to permit the user to operate the device, we run into situations where clients and drivers need to agree on the exact meaning of some fundamental properties. 33 What if some client need to be aware of the existence of some property in order to perform some function useful to the user? How can that client tie itself to such a property if the property can be arbitrary defined by drivers? 34 35 The solution is to define Standard Properties in order to establish a level of interoperability among INDI drivers and clients. We propose a set of shared INDI properties that encapsulate the most common characteristics of astronomical instrumentation of interest. 36 If the semantics of such properties are properly defined, not only it will insure base interoperability, but complete device automation becomes possible as well. Put another way, INDI standard properties are in essence properties that represent a clearly defined characteristic related to the operation of the device drivers. 37 38 For example, a very common standard property is EQUATORIAL_EOD_COORD. This property represents the telescope's current RA and DEC. Clients need to be aware of this property in order to, for example, draw the telescope's cross hair on the sky map. If you write a script to control a telescope, you know that any telescope supporting EQUATORIAL_EOD_COORD will behave in an expected manner when the property is invoked. 39 INDI clients are required to honor standard properties if when and they implement any functions associated with a particular standard property. Furthermore, INDI drivers employing standard properties should strictly adhere to the standard properties structure as defined next. 40 41 The properties are defined as string constants. To refer to the property in device drivers, use INDI::StandardProperty::PROPERTY_NAME or the shortcut INDI::SP::PROPERTY_NAME. 42 43 The standard properties are divided into the following categories: 44 <ol> 45 <li>@ref GeneralProperties "General Properties" shared across multiple devices.</li> 46 <li>@ref Connection::Interface "Connection Properties" 47 <ul> 48 <li>@ref SerialProperties "Serial Properties" used to communicate with and manage serial devices (including Bluetooth).</li> 49 <li>@ref TCPProperties "TCP Properties" used to communicate with and manage devices over the network.</li> 50 </ul> 51 </li> 52 </ol> 53 @author Jasem Mutlaq 54 */ 55 namespace SP 56 { 57 /** 58 * \defgroup GeneralProperties Standard Properties - General: Common properties shared across devices of multiple genres. 59 * The following tables describe standard properties pertaining to generic devices. The name of a standard property and its members must be 60 * strictly reserved in all drivers. However, it is permissible to change the label element of properties. You can find numerous uses of the 61 * standard properties in the INDI library driver repository. 62 * 63 * As a <b>general</b> rule of the thumb, the status of properties reflects the command execution result: 64 * IPS_OKAY: Command excuted successfully. 65 * IPS_BUSY: Command execution under progress. 66 * IPS_ALERT: Command execution failed. 67 */ 68 69 /*@{*/ 70 71 /** 72 * @brief Connect to and disconnect from device. 73 * Name | Type | Member | Default | Description 74 * ---- | ---- | ------ | ------- | ----------- 75 * CONNECTION | SWITCH | CONNECT | OFF | Establish connection to device 76 * CONNECTION | SWITCH | DISCONNECT | ON | Disconnect device 77 */ 78 extern const char *CONNECTION; 79 80 /*@}*/ 81 82 /** 83 * \defgroup SerialProperties Standard Properties - Serial: Properties used to communicate with and manage serial devices. 84 * Serial communication over RS232/485 and Bluetooth. Unless otherwise noted, all the properties are saved in the configuration file so that they are remembered across sessions. 85 */ 86 87 /*@{*/ 88 89 /** 90 * @brief Device serial (or bluetooth) connection port. The default value on Linux is <i>/dev/ttyUSB0</i> while on MacOS it is <i>/dev/cu.usbserial</i> 91 * It is part of Connection::SerialInterface to manage connections to serial devices. 92 * Name | Type | Member | Default | Description 93 * ---- | ---- | ------ | ------- | ----------- 94 * DEVICE_PORT | TEXT | PORT | /dev/ttyUSB0 | Device serial connection port 95 */ 96 extern const char *DEVICE_PORT; 97 98 /** 99 * @brief Toggle device auto search. 100 * If enabled and on connection failure with the default port, the SerialInterface class shall scan the system for available 101 * serial ports and attempts connection and handshake with each until successful. Please note if this option is enabled it can take 102 * a while before connection is established depending on how many ports are available on the system and the handshake timeout of the 103 * the underlying device. 104 * Name | Type | Member | Default | Description 105 * ---- | ---- | ------ | ------- | ----------- 106 * DEVICE_AUTO_SEARCH | SWITCH | ENABLED | ON | Auto Search ON 107 * DEVICE_AUTO_SEARCH | SWITCH | DISABLED | OFF | Auto Search OFF 108 */ 109 extern const char *DEVICE_AUTO_SEARCH; 110 111 /** 112 * @brief Set device baud rate 113 * Name | Type | Member | Default | Description 114 * ---- | ---- | ------ | ------- | ----------- 115 * DEVICE_BAUD_RATE | SWITCH | 9600 | ON | 9600 116 * DEVICE_BAUD_RATE | SWITCH | 19200 | OFF | 19200 117 * DEVICE_BAUD_RATE | SWITCH | 38400 | OFF | 38400 118 * DEVICE_BAUD_RATE | SWITCH | 57600 | OFF | 57600 119 * DEVICE_BAUD_RATE | SWITCH | 115200 | OFF | 115200 120 * DEVICE_BAUD_RATE | SWITCH | 230400 | OFF | 230400 121 */ 122 extern const char *DEVICE_BAUD_RATE; 123 124 /*@}*/ 125 126 /** 127 * \defgroup TCPProperties Standard Properties - TCP: Properties used to communicate with and manage devices over the network. 128 * Communication with devices over TCP/IP. Unless otherwise noted, all the properties are saved in the configuration file so that they are remembered across sessions. 129 */ 130 131 /*@{*/ 132 133 /** 134 * @brief Device hostname and port. 135 * It is part of Connection::TCPInterface to manage connections to devices over the network. 136 * Name | Type | Member | Default | Description 137 * ---- | ---- | ------ | ------- | ----------- 138 * DEVICE_ADDRESS | TEXT | ADDRESS | | Device hostname or IP Address 139 * DEVICE_ADDRESS | TEXT | PORT | | Device port 140 */ 141 extern const char *DEVICE_ADDRESS; 142 143 /*@}*/ 144 145 } 146 } // namespace INDI 147