Astronomical Device Control with INDIINDI ControlOverviewKStars provides an interface to configure and control astronomical instruments via
the INDI protocol.The INDI protocol supports a variety of astronomical instruments
such as CCD cameras and focusers. Currently, KStars supports the following
devices:
INDI SetupINDISetup
KStars can control local and remote devices seamlessly via the INDI server/client architecture. INDI devices may be run in three different modes:Local: The local mode is the most common and is used to control local device (&ie; a device attached to your machine).Server: The server mode establishes an INDI server for a particular device and waits for connections from remote clients. You cannot operate server devices, you can only start and shut them down.Client: The client mode is used to connect to remote INDI servers running INDI devices. You can control remote devices seamlessly like local devices.You can run local device, establish INDI servers, and connect to remote clients from the Device Manager in the Devices menu.Here is a screenshot of the Device Manager
window:Running device driversStart device driversYou can run devices by browsing the device tree, selecting a specific device, and then clicking on the Run Service button. You can select the operation mode, either local or server as defined above.To control remove devices, refer to the remote device control section.Telescope SetupINDISetupMost telescopes are equipped with RS232 interface
for remote control. Connect the RS232 jack in your telescope to your
computer's Serial/USB port. Traditionally, the RS232
connects to the serial port of your computer, but since many new laptops
abandoned the serial port in favor of USB/FireWire
ports, you might need to obtain a Serial to USB adaptor to use with new
laptops.After connecting your telescope to the Serial/USB port, turn your
telescope on. It is highly recommended that you
download and install the latest firmware for your telescope
controller.The telescope needs to be aligned before it can be used properly.
Align your telescope (one or two stars alignment) as illustrated in your
telescope manual.&kstars; needs to verify time and location settings before connecting to the telescope. This insures proper tracking and synchronization between the telescope and &kstars;. The following steps will enable you to connect to a device that is connected to your computer. To connect and control remote devices, please refer to remote device control section.You can use the Telescope Setup Wizard and it will verify all the required information in the process. It can automatically scan ports for attached telescopes. You can run the wizard by selecting Telescope Setup Wizard from the Devices menu.Alternatively, you can connect to a local telescope by performing the following
steps:Set your geographical location. Open the Geographic... window by selecting
Set Geographic Location... from the
Settings menu, or by pressing the Globe icon in the toolbar, or by pressing &Ctrl;g.Set your local time and date. You can change to any time or
date by selecting Set Time... from the Time menu, or by
pressing the time icon in the toolbar. The Set Time window uses a standard &kde; Date Picker widget, coupled with three spinboxes for setting the hours, minutes and seconds. If you ever need to reset the clock back to the current time, just select Set Time to Now from the Time menu.Click on the Devices menu and select the
Device Manager.Under the Device column, select your telescope model.Right-click on the device and select
Run Service.Click Ok to close the Device Manager
Dialog.Frequent SettingsYou do not need to set the geographic location and time every time you connect to a telescope. Only adjust the settings as needed.You are now ready to use the device features, &kstars; conveniently provides two interchangeable GUI interfaces for controlling telescopes:Controlling your telescopeSky map Control: For each device you run in the Device Manager, a corresponding entry will show up in popup menu that allows you to control the properties of the device. You can
issue commands like Slew, Sync, and
Track directly from the sky map.
Here is a screenshot of the popup menu with an active LX200 Classic
device:Controlling devices from sky mapINDI Control Panel: The panel offers the user with all the
features supported by a device.
The panel is divided into three main sections:Device tabs: Each additional active device occupies a
tab in the INDI panel. Multiple devices can run simultaneously without
affecting the operation of other devices.
Property view: Properties are the key element in INDI
architecture. Each device defines a set of properties to communicate with
the client. The current position of the telescope is an example of a
property. Semantically similar properties are usually contained in logical
blocks or groupings.
Log viewers: Devices report their status and acknowledge commands by sending INDI messages. Each device has its own log view, and all devices share one generic log viewer. A device usually sends messages to its device driver only, but a device is permitted to send a generic message when appropriate.
INDI Control PanelYou are not restricted on using one interface over another as they can be both used simultaneously. Actions from the Sky map are automatically reflected in the INDI Control Panel
and vice versa.To connect to your telescope, you can either select Connect from your device popup menu or
alternatively, you can press Connect under your device tab in the INDI Control Panel.By default, KStars will try to connect to the /dev/ttyS0
port. To change the connection port, select INDI Control Panel from the Devices menu and change the port under your device tab.&kstars; automatically updates the telescope's longitude, latitude, and
time based on current settings in &kstars;. You can enable/disable these
updates from Configure INDI dialog under the
Devices menu.
If &kstars; communicates successfully with the telescope, it will retrieve the current RA and DEC from the telescope and will display a crosshair on the sky map indicating the telescope position.Synchronizing your telescopeIf you aligned your telescope and the last alignment star was, for example, Vega, then the crosshair should be centered around Vega. If the crosshair was off target, then you can right-click Vega from the sky map and select
Sync from your telescope menu. This action will instruct the telescope to synchronize its internal coordinates to match those of Vega, and the telescope's crosshair should now be centered around Vega.
That is it: your telescope is ready to explore the heavens.WARNINGNever use the telescope to look at the sun. Looking at the sun might cause irreversible damage to your eyes and as well as your equipment.CCD and Video-Capture SetupCCD Video ControlSetupKStars supports the following imaging devices:Finger Lakes instruments CCDsApogee CCDs: Parallel, ISA, PCI, and USB modes are supported. You need to install Apogee kernel drivers for your specific mode (for USB mode, you only need libusb).Video4Linux compatible devices. Philips webcam extended features are supported as well.You can run CCD and Video Capture devices from the Device Manager in the Devices menu. Like all INDI devices, some of the device controls will be accessible from the skymap. The device can be controlled fully from the INDI Control Panel.The standard format for image capture is FITS. Once an image is captured and downloaded, it will be automatically displayed in the KStars FITS Viewer. To capture a sequence of images, use the Capture Image Sequence tool from the Devices menu. This tool is inactive until you establish a connection to an image device.The FLICCD driver requires root privileges in order to operate properly. Note that running the driver as root is considered a security riskCapture Image SequenceCaptureImageThe Capture Image Sequence tool can be used to acquire images from cameras and CCDs in interactive and batch modes. Furthermore, you can select which filter, if any, you want to use for your images. The capture tool remains disabled until you establish a connection to an imaging device.Capture Image SequenceThe above screenshot depicts a sample capture session. The tool provides the following options:Camera/CCD The desired imaging device. The image prefix which will be prepended to each captured filename. The number of seconds to expose each frame. The number of images to acquire. The delay in seconds between consecutive images. Append ISO 8601 time stamp to the filename. (e.g. image_01_20050427T09:48:05).Filter The desired filter device. The desired filter slot. You can assign color values to slot numbers using the Configure INDI window (e.g. Slot #1 = Red, Slot #2 = Blue..etc).After you fill in the desired options, you can begin the capture procedure by pressing the Start button. You may cancel at any time using the Stop button. All captured images will be saved to the default FITS directory which can be specified in the Configure INDI window.If you have more complex capturing requirements and conditions to fulfil, it is recommended to create a script to meet your specific needs using the Script Builder tool in the Tools menu.Configure INDIConfigureINDIThe Configure INDI window allows you to modify Client side INDI specific options. The window is divided into four main categories: General, Automatic device updates, Display, and Filter Wheel:General Specify the directory where all captured FITS images will be saved to. If no directory is specified, images will be stored in $HOME. When checked, KStars will display captured FITS in KStars FITS Viewer tool. If you use the Capture Image Sequence tool, all captured images will be saved to disk regardless of this 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. 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.Automatic device updates Update the telescope's date and time, if supported, upon connection. Update the telescope's geographical location information (current longitude and latitude), if supported, upon connection.Display 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 Configure KStars window. Select the Colors tab, and then change the color of the Target Indicator item to the desired color. When checked, KStars displays INDI status messages in the KStars status bar.Filter Wheel: Assign color codes to the filter wheel slots (e.g. 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.INDI ConceptsTelescope ControlConcepts
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 non-canonical devices. In INDI, all devices may contain one or more properties. Any property may contain one or more elements. There are four types of INDI properties:Text property.Number property.Switch property (Represented in GUI by buttons and checkboxes).Light property (Represented in GUI by colored LEDs).For example, all INDI devices share the CONNECTION standard switch property. The CONNECTION property has two elements: CONNECT and DISCONNECT switches. KStars parses the generic XML description of properties and builds a GUI representation suitable for direct human interaction.The INDI control panel offers many device properties not accessible from the sky map. The properties offered differ from one device to another. Nevertheless, all properties share common features that constrains how they are displayed and used:
Permission: All properties can either be read-only, write-only, or read and
write enabled. An example of a read-write property is the telescope's Right
Ascension. You can enter a new Right Ascension and the telescope, based on
current settings, will either slew or sync to the new input. Furthermore,
when the telescope slews, its Right Ascension gets updated and sent back to
the client.State: Prefixed to each property is a state indicator (round LED).
Each property has a state and an associated color code:
INDI State color codeStateColorDescriptionIdleGrayDevice is performing no action with respect to this propertyOkGreenLast operation performed on this property was successful and
activeBusyYellowThe property is performing an actionAlertRedThe property is in critical condition and needs immediate
attention
The device driver updates the property state in real-time when
necessary. For example, if the telescope is in the process of slewing to a
target, then the RA/DEC properties will be signaled as
Busy. When the slew process is completed successfully,
the properties will be signaled as
Ok.
Context: Numerical properties can accept and process numbers in two formats:
decimal and sexagesimal. The sexagesimal format is convenient when expressing
time or equatorial/geographical coordinates. You can use any format at your
convenience. For example, all the following numbers are equal:-156.40-156:24:00-156:24
Time: The standard time for all INDI-related communications is Universal Time UTC specified as YYYY-MM-DDTHH:MM:SS in accord with ISO 8601. &kstars; communicates the correct UTC time with device drivers automatically. You can enable/disable automatic time updates from the Configure INDI dialog under the Devices menu.
Remote Device ControlTelescope ControlRemote DevicesKStars provides a simple yet powerful layer for remote device control.
A detailed description of the layer is described in the INDI white
paper.You need to configure both the server and client machines for remote
control:Server: To prepare a device for remote control, follow the same steps in the local/server setup. When you start a device service in the Device Manager, a port number is displayed under the Listening port column. In addition to the port number, you also need the hostname or IP address of your server.
Client: Select the Device Manager from the Device menu and click on the Client tab. You can add, modify, or delete hosts under the Client tab. Add a host by clicking on the Add button. Enter the hostname/IP address of the server in the Host field, and enter the port number obtained from the server machine in step 1.
INDI ClientAfter you add a host, right click on the host to
Connect or Disconnect.
If a connection is established, you can control the telescope from the
Sky map or INDI Control Panel
exactly as described in the local/server section. It is as easy at that.
Running an INDI server from the command lineWhile &kstars; allows you to easily deploy an INDI server; you can launch an INDI server from the command line.
Since INDI is an independent backend component, you can run an INDI server on a host without KStars. INDI can be compiled separately to run on remote hosts. Furthermore, device drivers log messages to stderr and that can be helpful in a debugging situation. The syntax for INDI server is
as following:$ indiserver [options] [driver
...]Options: -p p : alternate IP port, default 7624 -r n : max restart attempts, default 2 -v : more verbose to stderrFor example, if you want to start an INDI server running an LX200 GPS
driver and listening to connections on port 8000, you would run the
following command:$ indiserver -p 8000 lx200gpsSecure Remote OperationSuppose we want to run an indiserver with INDI drivers on a remote host,
remote_host, and connect them to &kstars; running on the local machine.From the local machine log onto the remote host, remote_host, by typing:$ ssh -L local_port:remote_host:remote_portThis binds the local_port on the local machine to the remote_port on the remote_host. After logging in, run indiserver on the remote host:$ indiserver -p remote_port [driver...]Back on the local machine, start &kstars; then open the Device Manager and add a host under the Client tab. The host should be the local host (usually 127.0.0.1) and the port number should be the local_port used in the steps above. Right-click on the host and select Connect from the popup menu. &kstars; will connect to the remote INDI server securely. The host information will be saved for future sessions.INDI Frequently Asked QuestionsTelescope ControlFAQWhat is INDI? INDI is the Instrument-Neutral-Distributed-Interface control protocol developed by ElwoodC.
Downey of ClearSky Institute. &kstars; employs device drivers that are compatible with the INDI protocol. INDI has many advantages including loose coupling between hardware devices and
software drivers. Clients that use the device drivers (like &kstars;) are completely unaware of the device capabilities. In run time, &kstars; communicates with the device drivers and builds a completely dynamical GUI based on services provided by the device. Therefore, new device drivers can be written or updated and KStars can take full advantage of them without any changes on the client side.
Do you plan to support more devices?
Yes. We plan to support major CCD cameras and focusers and extend support
for more telescopes. If you would like INDI to support a particular device,
please send an email to indi-devel@lists.sourceforge.net
What operations does KStars provide to control the telescope?
It depends on the particular telescope you're running, but the minimum three operations are Slew, Track, and Sync, which you can issue directly from the sky map. Your telescope must be aligned for those operations to perform correctly. Some telescopes offer you more operations like site management, slew modes, focusing, parking, and more. You can access the telescopes extended features from the INDI Control Panel in the Devices Menu.
What's the difference between Slew, Track, and Sync exactly?
The command Slew orders the telescope to move to a particular target, and once the telescope reaches its target, the telescope keeps tracking that target at a sidereal rate (i.e. the rate at which stars move across the sky). This works well for stars, Messier objects, and about everything outside our solar system. But solar system objects travel differently across the sky and so the telescope must Track the objects as they move.
Therefore, you need to issue a track command if you want to track an object with non-sidereal motion. On the other hand, Sync is used to synchronize the telescope's internal coordinates with that of an object you select.
Can I control my telescope remotely?
Yes. You can start an INDI server on the machine connected to your telescope and the server will listen to requests from &kstars; clients. Once you're connected, you can control your telescope directly from the sky map. This procedure is described in detail in the Remote device control section.
When I try to Connect, &kstars; reports that the
telescope is not connected to the serial/USB port. What can I do?
This message is triggered when &kstars; cannot communicate with the telescope. Here are few things you can do:Check that you have both reading and writing permission for the port you are trying to connect to.Check the connection cable, make sure it is in good condition and test it with other applications.Check your telescope power, make sure the power is on and that the telescope is getting enough power.Set the correct port in the INDI Control Panel
under the Devices menu. The default device is
/dev/ttyS0Restart &kstars; and retry again.&kstars; reports that the telescope is online and ready, but I cannot find the telescope's crosshair, where is it?&kstars; retrieves the telescopes RA and DEC coordinates upon connection. If your alignment was performed correctly, then you should see the crosshair around your target in the Sky Map. However, the RA and DEC coordinates provided by the telescope may be incorrect (even below the horizon) and you need to Sync your telescope to your current target. You can use the right-click menu to center and track the telescope crosshair in the sky map.The telescope is moving erratically or not moving at all. What can I do?This behavior is mostly due to incorrect settings, please verify the following check list:Is the telescope aligned?Is the telescope alignment mode correct? Use INDI Control Panel to check and change these settings (Alt/Az,Polar, Land).Are the telescope's time and date settings correct?Are the telescope's longitude and latitude settings correct?Is the telescope's UTC offset correct?Are the telescope's RA and DEC axis locked firmly?Is the telescope's N/S switch (when applicable) setup correctly for your hemisphere?Is the cable between the telescope and computer in good condition?If you think all settings are correct but the telescope still moves erratically or not at all, then please send a report to
kstars-devel@kde.org