Warning, /education/kstars/doc/indi.docbook is written in an unsupported language. File is not indexed.

0001 <chapter id="indi">
0002 <title>Astronomical Device Control with <acronym>INDI</acronym></title>
0003 <indexterm><primary>INDI Control</primary>
0004 <secondary>Overview</secondary>
0005 </indexterm>
0006 
0007 <para>&kstars; provides an interface to configure and control astronomical
0008 instruments via the <acronym><link linkend="what-is-indi">INDI</link></acronym>
0009 protocol.
0010 </para>
0011 
0012 <para>The <acronym>INDI</acronym> protocol supports a variety of astronomical
0013 instruments such as CCD cameras and focusers. For an up to date list of supported
0014 devices, please visit <acronym>INDI</acronym>
0015 <ulink url="https://indilib.org/index.php?title=Devices">supported devices page</ulink>.
0016 </para>
0017 
0018 <sect1 id="indi-kstars-setup">
0019 <title>INDI Setup</title>
0020 <indexterm><primary>INDI</primary>
0021 <secondary>Setup</secondary>
0022 </indexterm>
0023 <para>
0024 &kstars; can control local and remote devices seamlessly via the
0025 <link linkend="what-is-indi">INDI</link> server/client architecture. INDI devices
0026 may be run in three different modes:
0027 </para>
0028 
0029 <orderedlist>
0030 <listitem><para><guilabel>Local</guilabel>: The local mode is the most common and is used to control
0031 local device (&ie; a device attached to your machine).
0032 </para></listitem>
0033 
0034 <listitem><para><guilabel>Server</guilabel>: The server mode establishes an INDI server for a particular
0035 device and waits for connections from remote clients. You cannot operate server devices,
0036 you can only start and shut them down.
0037 </para></listitem>
0038 
0039 <listitem><para><guilabel>Client</guilabel>: The client mode is used to connect to remote INDI servers
0040 running INDI devices. You can control remote devices seamlessly like local devices.
0041 </para></listitem>
0042 </orderedlist>
0043 
0044 <para>You can run local device, establish INDI servers, and connect to remote clients
0045 from the <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Devices</guisubmenu> 
0046 <guimenuitem>Device Manager...</guimenuitem></menuchoice> menu item.
0047 </para>
0048 
0049 <para>Here is a screenshot of the <guilabel>Device Manager</guilabel>
0050 window:
0051 </para>
0052 
0053 <screenshot>
0054 <screeninfo>Running device drivers</screeninfo>
0055 <mediaobject>
0056 <imageobject>
0057 <imagedata fileref="devicemanager.png" format="PNG"/>
0058 </imageobject>
0059 <textobject>
0060 <phrase>Start device drivers</phrase>
0061 </textobject>
0062 </mediaobject>
0063 </screenshot>
0064 
0065 <para>You can run devices by browsing the device tree, selecting a specific device,
0066 and then clicking on the <guibutton>Run Service</guibutton> button. You can select
0067 the operation mode, either local or server as defined above. The port number is
0068 randomly generated between the range from 7624 to 10,000. To specify a port, click
0069 on the port column next to the desired driver. &kstars; allows multiple drivers to
0070 run under one INDI server, and hence one port. Select multiple drivers then press
0071 <guibutton>Run Service</guibutton> button.
0072 </para>
0073 
0074 <para>To control remote devices, refer to the
0075 <link linkend="indi-remote-control">remote device control</link> section.
0076 </para>
0077 </sect1>
0078 
0079 <sect1 id="indi-telescope-setup">
0080 <title>Telescope Setup</title>
0081 <indexterm><primary>INDI</primary>
0082 <secondary>Setup</secondary>
0083 </indexterm>
0084 
0085 <para>Most telescopes are equipped with <hardware>RS232</hardware> interface
0086 for remote control. Connect the RS232 jack in your telescope to your
0087 computer's <hardware>Serial/USB</hardware> port. Traditionally, the RS232
0088 connects to the serial port of your computer, but since many new laptops
0089 abandoned the serial port in favor of <hardware>USB/FireWire</hardware>
0090 ports, you might need to obtain a Serial to USB adaptor to use with new
0091 laptops.
0092 </para>
0093 
0094 <para>After connecting your telescope to the Serial/USB port, turn your
0095 telescope on. It is <emphasis>highly</emphasis> recommended that you
0096 download and install the latest firmware for your telescope
0097 controller.
0098 </para>
0099 
0100 <para>The telescope needs to be aligned before it can be used properly.
0101 Align your telescope (one or two stars alignment) as illustrated in your
0102 telescope manual.
0103 </para>
0104 
0105 <para>&kstars; needs to verify time and location settings before connecting
0106 to the telescope. This insures proper tracking and synchronization between
0107 the telescope and &kstars;. The following steps will enable you to connect
0108 to a device that is connected to your computer. To connect and control remote
0109 devices, please refer to
0110 <link linkend="indi-remote-control">remote device control</link> section.
0111 </para>
0112 
0113 <para>You can use the Telescope Setup Wizard and it will verify all the
0114 required information in the process. It can automatically scan ports for
0115 attached telescopes. You can run the wizard by selecting the
0116 <menuchoice><guimenu>Devices</guimenu> <guimenuitem>Telescope Wizard</guimenuitem></menuchoice> menu item.
0117 </para>
0118 
0119 <para>Alternatively, you can connect to a local telescope by performing the
0120 following steps:
0121 </para>
0122 
0123 <orderedlist>
0124 <listitem><para>Set your geographical location. Open the
0125 <guilabel>Set Geographic Location</guilabel> window by selecting the
0126 <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Geographic...</guimenuitem></menuchoice>
0127 menu item, or by pressing the <guiicon>Globe</guiicon>
0128 icon in the toolbar, or by pressing <keycombo
0129 action="simul">&Ctrl;<keycap>G</keycap></keycombo>.
0130 </para>
0131 </listitem>
0132 
0133 <listitem><para>Set your local time and date. You can change to any time or
0134 date by selecting <menuchoice><guimenu>Time</guimenu>
0135 <guimenuitem>Set Time...</guimenuitem></menuchoice> menu item, or by pressing the <guiicon>Time</guiicon>
0136 icon in the toolbar. The <guilabel>Set Time</guilabel> window uses a standard
0137 &kde; Date Picker widget. If you ever need to reset the clock back to the current
0138 time, just select the <menuchoice><guimenu>Time</guimenu> <guimenuitem>Set Time to
0139 Now</guimenuitem></menuchoice> menu item.
0140 </para>
0141 </listitem>
0142 
0143 <listitem>
0144 <para>Click on the <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Devices</guisubmenu>
0145 <guimenuitem>Device Manager...</guimenuitem></menuchoice> menu item.
0146 </para>
0147 </listitem>
0148 
0149 <listitem>
0150 <para>Under the <guilabel>Device</guilabel> column, select your telescope model.
0151 </para>
0152 </listitem>
0153 
0154 <listitem>
0155 <para>Click on the <guibutton>Run Service</guibutton> button.
0156 </para>
0157 </listitem>
0158 
0159 <listitem>
0160 <para>Click <guibutton>Close</guibutton> to leave the Device Manager
0161 Dialog.
0162 </para>
0163 </listitem>
0164 </orderedlist>
0165 
0166 <note id="geo-time-note">
0167 <title>Frequent Settings</title>
0168 <para>You do not need to set the geographic location and time every time you
0169 connect to a telescope. Only adjust the settings as needed.
0170 </para></note>
0171 
0172 <para>You are now ready to use the device features, &kstars; conveniently provides
0173 two interchangeable &GUI; interfaces for controlling telescopes:
0174 </para>
0175 
0176 <orderedlist>
0177 <title>Controlling your telescope</title>
0178 <listitem>
0179 <para>
0180 <guilabel>Sky map Control</guilabel>: For each device you run in the
0181 <guilabel>Device Manager</guilabel>, a corresponding entry will show up in popup menu
0182 that allows you to control the properties of the device. You can
0183 issue commands like <command>Slew</command>, <command>Sync</command>, and
0184 <command>Track</command> directly from the sky map.
0185 </para>
0186 
0187 <para>Here is a screenshot of the popup menu with an active LX200 Classic device:
0188 </para>
0189 
0190 <screenshot>
0191 <screeninfo>Controlling devices from sky map</screeninfo>
0192 <mediaobject>
0193 <imageobject>
0194 <imagedata fileref="skymapdevice.png" format="PNG"/>
0195 </imageobject>
0196 </mediaobject>
0197 </screenshot>
0198 </listitem>
0199 
0200 <listitem>
0201 <para>
0202 <guilabel>INDI Control Panel</guilabel>: The panel offers the user with all the
0203 features supported by a device.
0204 </para>
0205 
0206 <para>The panel is divided into three main sections:
0207 </para>
0208 
0209 <itemizedlist>
0210 <listitem>
0211 <para>
0212 <guilabel>Device tabs</guilabel>: Each additional active device occupies a
0213 tab in the INDI panel. Multiple devices can run simultaneously without
0214 affecting the operation of other devices.
0215 </para>
0216 </listitem>
0217 
0218 <listitem>
0219 <para>
0220 Property views on the <guilabel>Main Control</guilabel> and <guilabel>Options</guilabel>
0221 tabs: Properties are the key element in INDI architecture. Each device defines a
0222 set of properties to communicate with the client. The current position of the
0223 telescope is an example of a property. Semantically similar properties are usually
0224 contained in logical blocks or groupings.
0225 </para>
0226 </listitem>
0227 
0228 <listitem>
0229 <para>
0230 <guilabel>Log viewer</guilabel>: Devices report their status and acknowledge commands
0231 by sending INDI messages. Each device has its own log view. A device usually sends messages
0232 to its device driver only, but a device is permitted to send a generic message when appropriate.
0233 </para>
0234 </listitem>
0235 </itemizedlist>
0236 
0237 <screenshot>
0238 <screeninfo>INDI Control Panel</screeninfo>
0239 <mediaobject>
0240 <imageobject>
0241 <imagedata fileref="indicontrolpanel.png" format="PNG"/>
0242 </imageobject>
0243 </mediaobject>
0244 </screenshot>
0245 </listitem>
0246 </orderedlist>
0247 
0248 <para>You are not restricted on using one interface over another as they can be both
0249 used simultaneously. Actions from the <guilabel>Sky map</guilabel> are automatically
0250 reflected in the <guilabel>INDI Control Panel</guilabel> and vice versa.
0251 </para>
0252 
0253 <para>To connect to your telescope, you can either select <guimenuitem>Connect</guimenuitem>
0254 from your device popup menu or alternatively, you can press <guibutton>Connect</guibutton>
0255 under your device tab in the <guilabel>INDI Control Panel</guilabel>.
0256 </para>
0257 
0258 <important><para>By default, &kstars; will try to connect to the <constant>/dev/ttyS0</constant>
0259 port. To change the connection port, select the <menuchoice><guimenu>Tools</guimenu>
0260 <guisubmenu>Devices</guisubmenu> <guimenuitem>INDI Control Panel...</guimenuitem></menuchoice> menu item and
0261 change the port under your device tab.
0262 </para></important>
0263 
0264 <para>&kstars; automatically updates the telescope's longitude, latitude, and
0265 time based on current settings in &kstars;. You can enable/disable these
0266 using the <guilabel>INDI</guilabel> page from the <menuchoice><guimenu>Settings</guimenu>
0267 <guimenuitem>Configure &kstars;...</guimenuitem></menuchoice> menu item. Using the
0268 <guilabel>INDI</guilabel> page you can configure &kstars; to display or not
0269 INDI status messages in the status bar. By default INDI server port numbers have values between
0270 the range from 7624 to 9000, but you can easily change the range using the <guilabel>From:</guilabel>
0271 and <guilabel>To:</guilabel> text boxes from the <guilabel>Server Port</guilabel> section.
0272 </para>
0273 
0274 <para>If &kstars; communicates successfully with the telescope, it will retrieve the
0275 current <abbrev>RA</abbrev> and <abbrev>DEC</abbrev> from the telescope and will display a
0276 crosshair on the sky map indicating the telescope position. You can hide the crosshair that marks telescope
0277 position using <guilabel>INDI</guilabel> page from the <menuchoice><guimenu>Settings</guimenu>
0278 <guimenuitem>Configure &kstars;...</guimenuitem></menuchoice> menu item.
0279 </para>
0280 
0281 <note id="indi-sync">
0282 <title>Synchronizing your telescope</title>
0283 <para>If you aligned your telescope and the last alignment star was, for example, Vega,
0284 then the crosshair should be centered around Vega. If the crosshair was off target, then
0285 you can <mousebutton>right</mousebutton>-click Vega from the sky map and select
0286 <command>Sync</command> from your telescope menu. This action will instruct the telescope
0287 to synchronize its internal coordinates to match those of Vega, and the telescope's crosshair
0288 should now be centered around Vega.
0289 </para>
0290 </note>
0291 
0292 <para>This is it: your telescope is ready to explore the heavens!
0293 </para>
0294 
0295 <warning>
0296 <title>WARNING</title>
0297 <para>Never use the telescope to look at the sun. Looking at the sun might cause irreversible
0298 damage to your eyes and your equipment.
0299 </para>
0300 </warning>
0301 </sect1>
0302 
0303 <sect1 id="indi-other-setup">
0304 <title>CCD and Video-Capture Setup</title>
0305 <indexterm><primary>CCD Video Control</primary>
0306 <secondary>Setup</secondary>
0307 </indexterm>
0308 
0309 <para>You can run CCD and Video Capture devices from the <menuchoice><guimenu>Tools</guimenu>
0310 <guisubmenu>Devices</guisubmenu> <guimenuitem>Device Manager...</guimenuitem></menuchoice> menu item.
0311 Like all INDI devices, some of the device controls will be accessible from the skymap.
0312 The device can be controlled fully from the <guimenuitem>INDI Control Panel...</guimenuitem> item.
0313 </para>
0314 
0315 <para>The standard format for image capture is FITS. Once an image is captured and downloaded,
0316 it will be automatically displayed in the &kstars; <link linkend="tool-fitsviewer">FITS Viewer</link>.
0317 </para>
0318 </sect1>
0319 
0320 <sect1 id="indi-configure">
0321 <title>Configure INDI</title>
0322 <indexterm><primary>Configure</primary>
0323 <secondary>INDI</secondary>
0324 </indexterm>
0325 
0326 <para>The <guilabel>INDI</guilabel> page allows you to modify <emphasis>Client side</emphasis> INDI
0327 specific options. To access it, select the <guilabel>INDI</guilabel> page from
0328 <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure &kstars;...</guimenuitem></menuchoice>
0329 menu item.
0330 The window is divided into several main categories: General, Device Updates, Display and Server Port:
0331 </para>
0332 
0333 <itemizedlist>
0334   <listitem><para><guilabel>General</guilabel></para>
0335     <itemizedlist>
0336       <listitem><para><guilabel>INDI server:</guilabel> Specify the binary of installed INDI server in your system. By default, &kstars; uses <quote>/usr/bin/indiserver</quote> binary.</para></listitem>
0337       <listitem><para><guilabel>INDI drivers XML directory:</guilabel> Specify the &XML; directory where INDI drivers are located in your system. By default, &kstars; uses <quote>/usr/share/indi</quote> directory.</para></listitem>
0338       <listitem><para><guilabel>Default FITS directory:</guilabel> Specify the directory where all captured FITS images will be saved to. If no directory is specified, images will be stored in <varname>$HOME</varname>.</para></listitem>
0339     <!-- Telescope port & Video port:
0340       <listitem><para><option>Telescope port:</option> The default telescope port. When you connect to a local or remote telescope service, &kstars; will automatically fill the telescope's device port with the specified default port.</para></listitem>
0341       <listitem><para><option>Video port:</option> The default video port. When you connect to a local or remote video service, &kstars; will automatically fill the webcam's device port with the specified default port.</para></listitem>    
0342     -->
0343     </itemizedlist>
0344   </listitem>
0345   <listitem><para><guilabel>Time &amp; Location Updates</guilabel></para>
0346     <itemizedlist>
0347       <listitem><para><guilabel>KStars updates all devices</guilabel>: KStars is the master source for time and location settings. All INDI devices time and locations settings are synchronized to KStars settings.</para></listitem>
0348       <listitem><para><guilabel>Mount updates KStars</guilabel>: Mount handset is the master source of time and location settings. KStars time and location settings are synchronized with controller settings.</para></listitem>
0349       <listitem><para><guilabel>GPS updates KStars</guilabel>: GPS driver is the master source of time and location settings. KStars time and location settings are synchronized with GPS settings.</para></listitem>
0350       <listitem><para><guilabel>Time</guilabel>: Synchronize KStars date and time automatically from the update source.</para></listitem>
0351       <listitem><para><guilabel>Location</guilabel>: Synchronize KStars location settings from the update source.</para></listitem>
0352     </itemizedlist>
0353   </listitem>
0354   <listitem><para><guilabel>Display</guilabel></para>
0355     <itemizedlist>
0356       <listitem><para><guilabel>Telescope crosshair</guilabel>: When checked, &kstars; displays the telescope's target crosshair on the sky map. The crosshair is displayed upon a successful connection to the telescope and its location is updated periodically. The telescope's name is displayed next to the crosshair. &kstars; displays one crosshair per each connected telescope. To change the color of the telescope's crosshair, open the <link linkend="viewops">Configure - &kstars;</link> window. Select the <guilabel>Colors</guilabel> page, and then change the color of the <guimenuitem>Target Indicator</guimenuitem> item to the desired color.</para></listitem>
0357       <listitem><para><guilabel>Independent window</guilabel>: Make <guilabel>FITS Viewer</guilabel> window independent.</para></listitem>
0358       <listitem><para><guilabel>Message notifications</guilabel>: Show INDI messages as desktop notifications instead of dialogs.</para></listitem>
0359     </itemizedlist>
0360   </listitem>
0361 <!--
0362   <listitem><para>Update Source: Synchronize &kstars; according to either the
0363     computer or device time and location settings.</para>
0364   </listitem>
0365   <listitem><para>Filter Wheel: Assign color codes to the filter wheel slots (&eg; Slot #0 Red, Slot #1 Blue, &etc;) You can assign color codes for up to 10 filter slots (0 to 9). To assign a color code, select a slot number from the drop down combo box, and then type the corresponding color code in the edit field. Repeat the process for all desired slots and then press OK.</para>
0366   </listitem>
0367 -->
0368   <listitem><para><guilabel>Server Port</guilabel></para>
0369     <itemizedlist>
0370       <listitem><para>Specify range of ports that INDI Server will bind to when starting new drivers.</para></listitem>
0371     </itemizedlist>
0372   </listitem>
0373 </itemizedlist>
0374 
0375 </sect1>
0376 
0377 <sect1 id="indi-concepts">
0378 <title>INDI Concepts</title>
0379 <indexterm><primary>Telescope Control</primary>
0380 <secondary>Concepts</secondary>
0381 </indexterm>
0382 
0383 <para>
0384 The main key concept in INDI is that devices have the ability to describe themselves.
0385 This is accomplished by using &XML; to describe a generic hierarchy that can represent
0386 both canonical and non-canonical devices. In INDI, all <emphasis>devices</emphasis>
0387 may contain one or more <emphasis>properties</emphasis>. Any <emphasis>property</emphasis>
0388 may contain one or more <emphasis>elements</emphasis>.
0389 There are four types of INDI properties:
0390 </para>
0391 <itemizedlist>
0392 <listitem><para>Text property.</para></listitem>
0393 <listitem><para>Number property.</para></listitem>
0394 <listitem><para>Switch property (Represented in &GUI; by buttons and checkboxes).</para></listitem>
0395 <listitem><para>Light property (Represented in &GUI; by colored LEDs).</para></listitem>
0396 </itemizedlist>
0397 
0398 <para>For example, all INDI devices share the CONNECTION standard switch <emphasis>property</emphasis>.
0399 The CONNECTION property has two elements: CONNECT and DISCONNECT switches. &kstars; parses the generic
0400 &XML; description of properties and builds a &GUI; representation suitable for direct human interaction.
0401 </para>
0402 
0403 <para>The INDI control panel offers many device properties not accessible from the sky map.
0404 The properties offered differ from one device to another. Nevertheless, all properties share
0405 common features that constrains how they are displayed and used:
0406 </para>
0407 
0408 <itemizedlist>
0409 <listitem>
0410 <para>
0411 Permission: All properties can either be read-only, write-only, or read and
0412 write enabled. An example of a read-write property is the telescope's Right
0413 Ascension. You can enter a new Right Ascension and the telescope, based on
0414 current settings, will either slew or sync to the new input. Furthermore,
0415 when the telescope slews, its Right Ascension gets updated and sent back to
0416 the client.
0417 </para>
0418 </listitem>
0419 <listitem>
0420 <para>State: Prefixed to each property is a state indicator (round LED).
0421 Each property has a state and an associated color code:
0422 </para>
0423 <table frame="top"><title>INDI State color code</title>
0424 <tgroup cols="3" colsep="1" rowsep="1">
0425 <thead>
0426 <row>
0427 <entry>State</entry>
0428 <entry>Color</entry>
0429 <entry>Description</entry>
0430 </row>
0431 </thead>
0432 <tbody>
0433 <row>
0434 <entry>Idle</entry>
0435 <entry>Gray</entry>
0436 <entry>Device is performing no action with respect to this property</entry>
0437 </row>
0438 <row>
0439 <entry>Ok</entry>
0440 <entry>Green</entry>
0441 <entry>Last operation performed on this property was successful and
0442 active</entry>
0443 </row>
0444 <row>
0445 <entry>Busy</entry>
0446 <entry>Yellow</entry>
0447 <entry>The property is performing an action</entry>
0448 </row>
0449 <row>
0450 <entry>Alert</entry>
0451 <entry>Red</entry>
0452 <entry>The property is in critical condition and needs immediate
0453 attention</entry>
0454         </row>
0455         </tbody>
0456 </tgroup>
0457 </table>
0458 
0459 <para>The device driver updates the property state in real-time when
0460 necessary. For example, if the telescope is in the process of slewing to a
0461 target, then the RA/DEC properties will be signaled as
0462 <guilabel>Busy</guilabel>. When the slew process is completed successfully,
0463 the properties will be signaled as <guilabel>Ok</guilabel>.
0464 </para>
0465 </listitem>
0466 <listitem>
0467 <para>
0468 Context: Numerical properties can accept and process numbers in two formats:
0469 decimal and sexagesimal. The sexagesimal format is convenient when expressing
0470 time or equatorial/geographical coordinates. You can use any format at your
0471 convenience. For example, all the following numbers are equal:
0472 </para>
0473 <itemizedlist>
0474 <listitem><para>-156.40</para></listitem>
0475 <listitem><para>-156:24:00</para></listitem>
0476 <listitem><para>-156:24</para></listitem>
0477 </itemizedlist>
0478 </listitem>
0479 <listitem>
0480 <para>
0481 Time: The standard time for all INDI-related communications is Universal Time UTC
0482 specified as YYYY-MM-DDTHH:MM:SS in accord with ISO 8601. &kstars; communicates the
0483 correct UTC time with device drivers automatically. You can enable/disable automatic
0484 time updates from the <guilabel>INDI</guilabel> page in the settings dialog.
0485 </para>
0486 </listitem>
0487 </itemizedlist>
0488 </sect1>
0489 
0490 <sect1 id="indi-remote-control">
0491 <title>Remote Device Control</title>
0492 <indexterm><primary>Telescope Control</primary>
0493 <secondary>Remote Devices</secondary>
0494 </indexterm>
0495 
0496 <para>&kstars; provides a simple yet powerful layer for remote device control.
0497 A detailed description of the layer is described in the INDI <ulink
0498 url="https://www.clearskyinstitute.com/INDI/INDI.pdf">white paper</ulink>.
0499 </para>
0500 
0501 <para>You need to configure both the server and client machines for remote control:
0502 </para>
0503 
0504 <orderedlist>
0505 <listitem>
0506 <para><guilabel>Server</guilabel>: To prepare a device for remote control, follow the same steps in the
0507 <link linkend="indi-kstars-setup">local/server</link> setup. When you start a device
0508 service in the <guilabel>Device Manager</guilabel>, a port number is displayed under
0509 the <guilabel>Port</guilabel> column. In addition to the port number, you
0510 also need the hostname or IP address of your server.
0511 </para>
0512 
0513 </listitem>
0514 <listitem>
0515 <para><guilabel>Client</guilabel>: Select the <menuchoice><guimenu>Tools</guimenu>
0516 <guisubmenu>Devices</guisubmenu> <guimenuitem>Device Manager...</guimenuitem></menuchoice>
0517 menu item and you can add, modify, or delete hosts into <guilabel>Client</guilabel> tab.
0518 Add a host by clicking on the <guibutton>Add</guibutton> button.
0519 Enter the hostname/IP address of the server in the <guilabel>Host:</guilabel> field, and enter the port
0520 number obtained from the <emphasis>server</emphasis> machine in step 1.
0521 </para>
0522 </listitem>
0523 </orderedlist>
0524 
0525 <screenshot>
0526 <screeninfo>INDI Client</screeninfo>
0527 <mediaobject>
0528 <imageobject>
0529 <imagedata fileref="indiclient.png" format="PNG"/>
0530 </imageobject>
0531 </mediaobject>
0532 </screenshot>
0533 
0534 <para>After you add a host, right click on the host to
0535 <guimenuitem>Connect</guimenuitem> or <guimenuitem>Disconnect</guimenuitem>.
0536 If a connection is established, you can control the telescope from the
0537 <guilabel>Sky map</guilabel> or <guilabel>INDI Control Panel</guilabel>
0538 exactly as described in the <link linkend="indi-kstars-setup">local/server</link> section. It is as easy at that.
0539 </para>
0540 
0541 <sect2 id="indi-commandline">
0542 <title>Running an INDI server from the command line</title>
0543 <para>While &kstars; allows you to easily deploy an INDI server; you can launch
0544 an INDI server from the command line.
0545 </para>
0546 
0547 <para>
0548 Since INDI is an independent backend component, you can run an INDI server on a host
0549 without &kstars;. INDI can be compiled separately to run on remote hosts.
0550 Furthermore, device drivers log messages to <constant>stderr</constant> and that can
0551 be helpful in a debugging situation.  The syntax for INDI server is as following:
0552 </para>
0553 
0554 <para>$ <command>indiserver</command> [options] driver [<filename>driver</filename> ...]
0555 </para>
0556 
0557 <para><screen>Options:
0558  -l d     : Log driver messages to &lt;d&gt;/YYYY-MM-DD.islog
0559  -m m     : Kill client if gets more than this many MB behind, default 128.
0560  -d m     : Drop streaming blobs if client gets more than this many MB behind, default 5. 0 to disable.
0561  -p p     : Alternate IP port, default 7624.
0562  -r r     : Maximum driver restarts on error, default 10.
0563  -f path  : Path to fifo for dynamic startup and shutdown of drivers.
0564  -v       : Show key events, no traffic.
0565  -vv      : -v + key message content.
0566  -vvv     : -vv + complete xml.
0567  driver   : Executable or [device]@host[:port]
0568 </screen></para>
0569 
0570 <para>For example, if you want to start an INDI server running an LX200 GPS
0571 driver and listening to connections on port 8000, you would run the
0572 following command:
0573 </para>
0574 
0575 <para>$ <command>indiserver</command> -p 8000 <filename>lx200gps</filename></para>
0576 </sect2>
0577 
0578 <sect2 id="indi-secure-remote">
0579 <title>Secure Remote Operation</title>
0580 
0581 <para>Suppose we want to run an indiserver with INDI drivers on a remote host,
0582 <constant>remote_host</constant>, and connect them to &kstars; running on the local machine.
0583 </para>
0584 
0585 <para>From the local machine log onto the remote host, <constant>remote_host</constant>,
0586 by typing:
0587 </para>
0588 
0589 <para>$ <command>ssh</command> -L <varname>local_port</varname>:<constant>remote_host</constant>:<varname>remote_port</varname></para>
0590 
0591 <para>This binds the <varname>local_port</varname> on the local machine to the
0592 <varname>remote_port</varname> on the <constant>remote_host</constant>. After logging in,
0593 run indiserver on the remote host:
0594 </para>
0595 
0596 <para>$ <command>indiserver</command> -p <varname>remote_port</varname> [<filename>driver</filename>...]</para>
0597 
0598 <para>Back on the local machine, start &kstars; then open the <guimenuitem>Device Manager</guimenuitem>
0599 and add a host under the <guilabel>Client</guilabel> tab. The host should be the local host
0600 (usually 127.0.0.1) and the port number should be the <varname>local_port</varname> used in the steps above.
0601 <mousebutton>Right</mousebutton>-click on the host and select <guimenuitem>Connect</guimenuitem> from
0602 the popup menu. &kstars; will connect to the remote INDI server securely. The host information will be saved
0603 for future sessions.</para>
0604 </sect2>
0605 </sect1>
0606 
0607 <sect1 id="indi-faq">
0608 <title>INDI Frequently Asked Questions</title>
0609 <indexterm><primary>Telescope Control</primary>
0610 <secondary>&FAQ;</secondary>
0611 </indexterm>
0612 
0613 <qandaset defaultlabel="qanda">
0614 <qandaentry>
0615 <question id="what-is-indi">
0616 <para>What is INDI?</para>
0617 </question>
0618 <answer>
0619 <para><acronym>INDI</acronym> is the
0620 <ulink url="https://indilib.org"> Instrument-Neutral-Distributed-Interface</ulink> control
0621 protocol developed by <author><firstname>Elwood</firstname><surname>C. Downey</surname></author> of
0622 <ulink url="https://www.clearskyinstitute.com/">ClearSky Institute</ulink>. &kstars; employs device
0623 drivers that are compatible with the INDI protocol. INDI has many advantages including loose coupling
0624 between hardware devices and software drivers. Clients that use the device drivers (like &kstars;)
0625 are completely unaware of the device capabilities. In run time, &kstars; communicates with the device
0626 drivers and builds a completely dynamical &GUI; based on services provided by the device. Therefore, new
0627 device drivers can be written or updated and &kstars; can take full advantage of them without any changes
0628 on the client side.
0629 </para>
0630 </answer>
0631 </qandaentry>
0632 
0633 <qandaentry>
0634 <question>
0635 <para>
0636 Do you plan to support more devices?
0637 </para>
0638 </question>
0639 <answer>
0640 <para>
0641 Yes. We plan to support major CCD cameras and focusers and extend support
0642 for more telescopes. If you would like INDI to support a particular device,
0643 please send an email to <email>indi-devel@lists.sourceforge.net</email>
0644 </para>
0645 </answer>
0646 </qandaentry>
0647 
0648 <qandaentry>
0649 <question>
0650 <para>
0651 What operations does &kstars; provide to control the telescope?
0652 </para>
0653 </question>
0654 <answer>
0655 <para>
0656 It depends on the particular telescope you're running, but the minimum three operations are
0657 <command>Slew</command>, <command>Track</command>, and <command>Sync</command>, which you can
0658 issue directly from the sky map. Your telescope must be aligned for those operations to perform
0659 correctly. Some telescopes offer you more operations like site management, slew modes, focusing,
0660 parking, and more. You can access the telescopes extended features from the 
0661 <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Devices</guisubmenu> 
0662 <guimenuitem>INDI Control Panel...</guimenuitem></menuchoice> menu item.
0663 </para>
0664 </answer>
0665 </qandaentry>
0666 
0667 <qandaentry>
0668 <question>
0669 <para>
0670 What's the difference between <command>Slew</command>, <command>Track</command>, and <command>Sync</command> exactly?
0671 </para>
0672 </question>
0673 <answer>
0674 <para>
0675 The command <command>Slew</command> orders the telescope to move to a particular target, and once
0676 the telescope reaches its target, the telescope keeps tracking that target at a
0677 <emphasis>sidereal</emphasis> rate (&ie;, the rate at which stars move across the sky). This works well
0678 for stars, Messier objects, and about everything outside our solar system. But solar system objects
0679 travel differently across the sky and so the telescope must <command>Track</command> the objects as they move.
0680 </para>
0681 <para>
0682 Therefore, you need to issue a track command if you want to track an object with non-sidereal motion.
0683 On the other hand, <command>Sync</command> is used to synchronize the telescope's internal coordinates
0684 with that of an object you select.
0685 </para>
0686 </answer>
0687 </qandaentry>
0688 
0689 <qandaentry>
0690 <question>
0691 <para>
0692 Can I control my telescope remotely?
0693 </para>
0694 </question>
0695 <answer>
0696 <para>
0697 Yes. You can start an INDI server on the machine connected to your telescope and the server will listen
0698 to requests from &kstars; clients. Once you're connected, you can control your telescope directly from
0699 the sky map. This procedure is described in detail in the
0700 <link linkend="indi-remote-control">Remote device control</link> section.
0701 </para>
0702 </answer>
0703 </qandaentry>
0704 
0705 <qandaentry>
0706 <question>
0707 <para>
0708 When I try to <guibutton>Connect</guibutton>, &kstars; reports that the
0709 telescope is not connected to the serial/USB port. What can I do?
0710 </para>
0711 </question>
0712 <answer>
0713 <para>This message is triggered when &kstars; cannot communicate with the telescope. Here are few things you can do:</para>
0714 
0715    <orderedlist>
0716    <listitem>
0717 <para>Check that you have both reading and writing permission for the port you are trying to connect to.</para>
0718    </listitem>
0719    <listitem>
0720 <para>Check the connection cable, make sure it is in good condition and test it with other applications.</para>
0721    </listitem>
0722    <listitem>
0723 <para>Check your telescope power, make sure the power is on and that the telescope is getting enough power.</para>
0724    </listitem>
0725    <listitem>
0726 <para>Select the <menuchoice><guimenu>Tools</guimenu> <guisubmenu>Devices</guisubmenu> 
0727 <guimenuitem>INDI Control Panel...</guimenuitem></menuchoice> menu item and set the correct
0728 port in the <guilabel>INDI Control Panel</guilabel> dialog. The default device is
0729 <constant>/dev/ttyS0</constant></para>
0730    </listitem>
0731    <listitem>
0732    <para>Restart &kstars; and retry again.</para>
0733    </listitem>
0734    </orderedlist>
0735 </answer>
0736 </qandaentry>
0737 
0738 <qandaentry>
0739 <question>
0740 <para>&kstars; reports that the telescope is online and ready, but I cannot find the telescope's crosshair, where is it?</para>
0741 </question>
0742 <answer>
0743 <para>&kstars; retrieves the telescopes RA and DEC coordinates upon connection. If your
0744 alignment was performed correctly, then you should see the crosshair around your target
0745 in the Sky Map. However, the RA and DEC coordinates provided by the telescope may be
0746 incorrect (even below the horizon) and you need to <link linkend="indi-sync">Sync</link>
0747 your telescope to your current target. You can use the right-click menu to center and track
0748 the telescope crosshair in the sky map.
0749 </para>
0750 </answer>
0751 </qandaentry>
0752 
0753 <qandaentry>
0754 <question>
0755 <para>The telescope is moving erratically or not moving at all. What can I do?</para>
0756 </question>
0757 <answer>
0758 <para>This behavior is mostly due to incorrect settings, please verify the following check list:</para>
0759 <orderedlist>
0760 <listitem>
0761 <para>Is the telescope aligned?</para>
0762 </listitem>
0763 <listitem>
0764 <para>Is the telescope alignment mode correct? Use <guilabel>INDI Control Panel</guilabel> to check
0765 and change these settings (<constant>Alt/Az,Polar, Land</constant>).
0766 </para>
0767 </listitem>
0768 <listitem>
0769 <para>Are the telescope's time and date settings correct?</para>
0770 </listitem>
0771 <listitem>
0772 <para>Are the telescope's longitude and latitude settings correct?</para>
0773 </listitem>
0774 <listitem>
0775 <para>Is the telescope's UTC offset correct?</para>
0776 </listitem>
0777 <listitem>
0778 <para>Are the telescope's RA and DEC axis locked firmly?</para>
0779 </listitem>
0780 <listitem>
0781 <para>Is the telescope's N/S switch (when applicable) setup correctly for your hemisphere?</para>
0782 </listitem>
0783 <listitem>
0784 <para>Is the cable between the telescope and computer in good condition?</para>
0785 </listitem>
0786 </orderedlist>
0787 
0788 <para>If you think all settings are correct but the telescope still moves erratically or not at all,
0789 then please send a report to <email>indi-devel@lists.sourceforge.net</email>.
0790 </para>
0791 </answer>
0792 </qandaentry>
0793 </qandaset>
0794 </sect1>
0795 </chapter>
0796