diff options
Diffstat (limited to 'doc/kstars/scriptbuilder.docbook')
| -rw-r--r-- | doc/kstars/scriptbuilder.docbook | 300 |
1 files changed, 300 insertions, 0 deletions
diff --git a/doc/kstars/scriptbuilder.docbook b/doc/kstars/scriptbuilder.docbook new file mode 100644 index 00000000..3a2f57ce --- /dev/null +++ b/doc/kstars/scriptbuilder.docbook @@ -0,0 +1,300 @@ +<sect1 id="tool-scriptbuilder"> +<title>The Script Builder Tool</title> +<indexterm><primary>Tools</primary> +<secondary>Script Builder</secondary> +</indexterm> + +<para> +KDE applications can be controlled externally from another program, +from a console prompt, or from a shell script using the Desktop +COmmunication Protocol (<abbrev>DCOP</abbrev>). KStars takes +advantage of this feature to allow rather complex behaviors to be +scripted and played back at any time. This can be used, for example, +to create a classroom demo to illustrate an astronomical concept. +</para> +<para> +The problem with DCOP scripts is, writing them is a bit like +programming, and can seem a daunting task to those who do not have +programming experience. The Script Builder Tool provides a +<abbrev>GUI</abbrev> point-and-click interface for constructing +KStars DCOP scripts, making it very easy to create complex scripts. +</para> + +<sect2 id="sb-intro"> +<title>Introduction to the Script Builder</title> + +<para> +Before explaining how to use the Script Builder, I provide a very +brief introduction to all of the <abbrev>GUI</abbrev> components; +for more infomation, use the "What's This?" function. +</para> + +<screenshot> +<screeninfo> +The Script Builder Tool +</screeninfo> +<mediaobject> + <imageobject> + <imagedata fileref="scriptbuilder.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Script Builder Tool</phrase> + </textobject> +</mediaobject> +</screenshot> + +<para> +The Script Builder is shown in the above screenshot. The box on the +left is the <firstterm>Current Script box</firstterm>; it shows the +list of commands that comprise the current working script. The box +on the right is the <firstterm>Function Browser</firstterm>; it +displays the list of all available script functions. Below the +Function Browser, there is a small panel which will display short +documentation about the script function highlighted in the Function +Browser. The panel below the Current Script box is the +<firstterm>Function Arguments panel</firstterm>; when a function is +highlighted in the Current Script box, this panel will contain items +for specifying values for any arguments that the highlighted function +requires. +</para><para> +Along the top of the window, there is a row of buttons which operate +on the script as a whole. From left to right, they are: +<guibutton>New Script</guibutton>, <guibutton>Open Script</guibutton>, +<guibutton>Save Script</guibutton>, <guibutton>Save Script +As...</guibutton>, and <guibutton>Test Script</guibutton>. The +function of these buttons should be obvious, except perhaps the last +button. Pressing <guibutton>Test Script</guibutton> will attempt to +run the current script in the main KStars window. You should move +the Script Builder window out of the way before pressing this, so you +can see the results. +</para><para> +In the center of the window, there is a column of buttons which operate +on individual script functions. From top to bottom, they are: +<guibutton>Add Function</guibutton>, <guibutton>Remove +Function</guibutton>, <guibutton>Copy Function</guibutton>, +<guibutton>Move Up</guibutton>, and <guibutton>Move Down</guibutton>. +<guibutton>Add Function</guibutton> adds the currently-highlighted +function in the Function Browser to the Current Script box (you can +also add a function by double-clicking on it). The rest of the +buttons operate on the function highlighted in the Current Script box, +either removing it, duplicating it, or changing its position in the +current script. +</para> +</sect2> + +<sect2 id="sb-using"> +<title>Using the Script Builder</title> +<para> +In order to illustrate using the Script Builder, we present a small +tutorial example where we make a script that tracks the Moon while +the clock runs at an accelerated rate. +</para><para> +If we are going to track the Moon, we will need to point the display +at it first. The <firstterm>lookToward</firstterm> function +is used to do this. Highlight this function in the Function Browser, +and note the documentation displayed in the panel below the Browser. +Press the <guibutton>Add Function</guibutton> button to add this +function to the Current Script box. The Function Arguments panel +will now contain a combobox labeled <quote>dir</quote>, short for +direction. This is the direction in which the display should +be pointed. The combobox contains only the cardinal compass points, +not the Moon or any other objects. You can either enter +<quote>Moon</quote> in the box manually, or press the +<guibutton>Object</guibutton> button to use the <guilabel>Find +Object</guilabel> window to select the Moon from the list of named +objects. Note that, as usual, centering on an object automatically +engages object-tracking mode, so there is no need to add the +<firstterm>setTracking</firstterm> function after lookToward. +</para><para> +Now that we have taken care of pointing at the Moon, we next want to +make time pass at an accelerated rate. Use the +<firstterm>setClockScale</firstterm> function for this. Add it to +the script by double-clicking on it in the Function Browser. The +Function Arguments panel contains a timestep spinbox for setting the +desired time step for the simulation clock. Change the timestep to +3 hours. +</para><para> +OK, we have pointed at the Moon and accelerated the clock. Now we just +want the script to wait for several seconds while the display tracks +on the Moon. Add the <firstterm>waitFor</firstterm> function to the +script, and use the Function Arguments panel to specify that it should +wait for 20 seconds before continuing. +</para><para> +To finish up, let us reset the clock's timestep to the normal value +of 1 second. Add another instance of setClockScale, and set its value +to 1 sec. +</para><para> +Actually, we are not quite done yet. We should probably make sure that +the display is using Equatorial coordinates before the script tracks +the Moon with an accelerated time step. Otherwise, if the display is +using Horizontal coordinates, it will rotate very quickly through +large angles as the Moon rises and sets. This can be very confusing, +and is avoided by setting the View Option +<firstterm>UseAltAz</firstterm> to <quote>false</quote>. To change +any View Option, use the <firstterm>changeViewOption</firstterm> +function. Add this function to the script, and examine the Function +Arguments panel. There is a combobox which contains the list of all +options which can be adjusted by changeViewOption. Since we know +we want the UseAltAz option, we could simply select it from the +combobox. However, the list is quite long, and there is no +explanation of what each item is for. It therefore may be easier to +press the <guibutton>Browse Tree</guibutton> button, which will open +a window containing a tree view of the available options, organized by +topic. In addition, each item has a short explanation of what the +option does, and the data type of the option's value. We find +UseAltAz under the <guilabel>Skymap options</guilabel> category. +Just highlight this item and press <guibutton>OK</guibutton>, and it +will be selected in the combobox of the Function Arguments panel. +Finally, make its value <quote>false</quote> or <quote>0</quote>. +</para><para> +One more step: changing UseAltAz at the end of the script does us no +good; we need this to be changed before anything else happens. So, +make sure this function is highlighted in the Current Script box, +and press the <guibutton>Move Up</guibutton> button until it is the +first function. +</para><para> +Now that we have finished the script, we should save it to disk. +Press the <guibutton>Save Script</guibutton> button. This will first +open a window in which you can provide a name for the script, and fill +in your name as the author. Enter <quote>Tracking the Moon</quote> +for a name, and your name as the author, and press +<guibutton>OK</guibutton>. Next, you will see the standard &kde; Save +File dialog. Specify a filename for the script and press +<guibutton>OK</guibutton> to save the script. Note that if your +filename does not end with <quote>.kstars</quote>, this suffix +will be automatically attached. If you are curious, you can examine the +script file with any text editor. +</para><para> +Now that we have a completed script, we can run it in a couple of ways. +From a console prompt, you can simply execute the script as long as an +instance of KStars is currently running. Alternatively, you can execute +the script from within KStars using the <guimenuitem>Run +Script</guimenuitem> item in the <guimenu>File</guimenu> menu. +</para> +</sect2> + +<sect2 id="sb-indi"> + <title>Device Automation with INDI</title> + <para> + Device scheduling and automation is supported for all <link linkend="what-is-indi">INDI</link>-compliant devices. You can coordinate any number of devices to perform complex operations using &kstars; <link linkend="sb-intro">Script Builder</link>. This can be accomplished by using &kstars; INDI DCOP interface, which provides different classes of functions to suit your tasks. The INDI DCOP functions can be decomposed into five different classes. The following is a review of the functions and their arguments as supported in KStars. It it highly recommended to read the <link linkend="indi-concepts">INDI Concepts</link> section as we will employ key INDI concepts throughout this tutorial.</para> + <orderedlist> + <listitem><para>Generic Device Functions: Functions to establish/shutdown devices..etc.</para> + <itemizedlist> + <listitem><para><function>startINDI (QString deviceName, bool useLocal)</function> : Establish an INDI service either as local or server.</para></listitem> + <listitem><para><function>shutdownINDI (QString deviceName)</function> : Shutdown the INDI service.</para></listitem> + <listitem><para><function>switchINDI(QString deviceName, bool turnOn)</function> : Connect or Disconnect an INDI device.</para></listitem> + <listitem><para><function>setINDIPort(QString deviceName, QString port)</function> : Set the device's connection port.</para></listitem> + <listitem><para><function>setINDIAction(QString deviceName, QString action)</function> : Activate an INDI action. The action can be any <emphasis>element</emphasis> of a <emphasis>switch property</emphasis></para></listitem> + <listitem><para><function>waitForINDIAction(QString deviceName, QString action)</function> : Pause script execution until the specified action <emphasis>property</emphasis> returns with OK status.</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>Telescope Functions: Functions to control the telescope motion and status.</para> + <itemizedlist> + <listitem><para><function>setINDIScopeAction(QString deviceName, QString action)</function> : Set the telescope mode or action. Available options are SLEW, TRACK, SYNC, PARK, and ABORT.</para></listitem> + <listitem><para><function>setINDITargetCoord(QString deviceName, double RA, double DEC)</function> : Set the telescope JNow target coordinates to <emphasis>RA</emphasis> and <emphasis>DEC</emphasis>.</para></listitem> + <listitem><para><function>setINDITargetName(QString deviceName, QString objectName)</function> : Set the telescope JNow target coordinates to the coordinates of <emphasis>objectName</emphasis>. KStars will lookup the object name in its database and will fetch RA and Dec once found.</para></listitem> + <listitem><para><function>setINDIGeoLocation(QString deviceName, double +longitude, double latitude)</function> : Set the telescope geographical +location to the longitude and latitude as specified. The longitude is measured +from Greenwich, UK, to the East. However, while it is common to use negative +longitudes for the Western hemisphere, INDI requires longitude values between +0 and 360 degrees. So if you have a negative longitude, simply add 360 +degrees to get the value that INDI expects. For example, Calgary, Canada +coordinates in &kstars; are longitude: -114 04 58; latitude: 51 02 58. So +INDI's would need longitude = 360 - 114.083 = 245.917 +degrees.</para></listitem> + <listitem><para><function>setINDIUTC(QString ddeviceName, QString UTCDateTime)</function> : Set the telescope UTC Date and Time in ISO 8601 format. The format is YYYY-MM-DDTHH:MM:SS (e.g. 2004-07-12T22:05:32).</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>Camera/CCD Functions: Functions to control the camera/CCD properties and status.</para> + <itemizedlist> + <listitem><para><function>setINDICCDTemp(QString deviceName, int temp)</function> : Set the CCD chip target temperature in degrees celsius.</para></listitem> + <listitem><para><function>setINDIFrameType(QString deviceName, QString type)</function> : Set the CCD frame type. Available options are FRAME_LIGHT, FRAME_BIAS, FRAME_DARK, and FRAME_FLAT.</para></listitem> + <listitem><para><function>startINDIExposure(QString deviceName, int timeout)</function> : Start the CCD/Camera exposure for the duration specified by <emphasis>timeout</emphasis> in seconds.</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>Focuser Functions: Functions to control the focuser motion and status.</para> + <itemizedlist> + <listitem><para><function>setINDIFocusSpeed(QString deviceName, QString action)</function> : Set the focuser speed. Available options are FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM, and FOCUS_FAST.</para></listitem> + <listitem><para><function>setINDIFocusTimeout(QString deviceName, int timeout)</function> : Set the duration in seconds for any subsequent startINDIFocus operations.</para></listitem> + <listitem><para><function>startINDIFocus(QString deviceName, int focusDir)</function> : Move the focuser either inward (focusDir = 0) or outward (focusDir = 1). The speed and duration of this operation is set by the <function>setINDIFocusSpeed()</function> and <function>setINDIFocusTimeout()</function> functions.</para></listitem> + </itemizedlist> + </listitem> + <listitem><para>Filter Functions: Functions to control the filter position.</para> + <itemizedlist> + <listitem><para><function>setINDIFilterNum(QString deviceName, int filter_num)</function> : Change the filter position to <varname>filter_num</varname>. The user can assign aliases to filter numbers in the <guimenuitem>Configure INDI</guimenuitem> dialog box under the <guimenu>Devices</guimenu> menu (e.g. Filter 1 = Red, Filter 2 = Green..etc).</para></listitem> + </itemizedlist> + </listitem> + + </orderedlist> + +<para> +Note that the device name is the first argument of all INDI functions. This permits different commands that are sent to different INDI devices to be intermixed together in one script. The Script Builder tool provides two options to facilitate the creation and editing of INDI scripts:</para> +<itemizedlist> + <listitem><para><option>Append waitForINDIAction after any INDI action</option> : When checked, the Script Builder tool will automatically add <function>waitForINDIAction()</function> after any action it recognizes. For example, If you add <function>switchINDI()</function> function to the script and this option was checked, the Script Builder will add "waitForINDIAction CONNECTION" in the script file just after <function>switchINDI()</function>. This will cause the script to pause after it issues <function>switchINDI()</function> until <function>switchINDI()</function> returns with OK status (&ie; device connection was successful). It is critically important to know that the Script Builder cannot automatically add <function>waitForINDIAction()</function> for generic actions added using the <function>setINDIAction()</function> function. This is because KStars cannot determine the parent property of generic actions. Therefore, you must manually add <function>waitForINDIAction()</function> after generic actions when desired.</para> + </listitem> + <listitem><para><option>Reuse INDI device name</option> : When checked, the device name field of all subsequent functions is automatically filled with the last device name. The last device name is set every time <function>startINDI()</function> function is added to the current script. When working with multiple devices, it is recommended to have this option off.</para> + </listitem> +</itemizedlist> + +<para>Now we are ready to create a demo script that controls LX200 GPS telescope, in addition to Finger Lakes CCD camera. Our task is simple. We will ask the telescope to slew and track Mars, then we will ask the camera to take three shots 10 seconds each separated by 20 seconds.</para> +<important><para>Since there is no direct feedback from the INDI DCOP interface about the progress, value, or status of the device operations and parameters (except for <function>waitForINDIAction()</function>), device automation in KStars is similar to an open-loop control system. In such a system, there is usually no direct feedback to measure the progress of the system and to correct for errors. Consequently, you must design your device automation scripts with careful consideration. All automation scripts must be subjected to rigorous testing before deployment.</para></important> + +<screenshot> + <screeninfo> + The Script Builder Tool + </screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="indiscript.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Script Builder Tool</phrase> + </textobject> + </mediaobject> +</screenshot> + +<para>The demo script is shown in the above screenshot. Note that we checked <option>"Append waitForINDIAction after any INDI action"</option> and unchecked <option>"Reuse INDI device name"</option>. The first function to add is <function>startINDI()</function> as shown above. We want to run our devices as local, so we will not change the service mode provided in the function arguments window. We type in our device name, starting with the telescope "LX200 GPS". We repeat the same operation again for "FLI CCD". There is a <function>waitFor()</function> function after that. It is generally recommended to use <function>waitFor()</function> function immediately after <function>startINDI()</function> to pause the script for 1-5 seconds. This will ensure that all properties are built and are ready to receive command. It is also useful for controlling remote devices because retrieving and building properties might take some time. In the next function, <function>switchINDI()</function>, we connect to each device.</para> + +<para>Since <option>"Append waitForINDIAction after any INDI action"</option> is checked, we do not need to add <function>waitForINDIAction()</function> after <function>switchINDI()</function> to insure that we only continue executing the script after we successfully connect. This is because the Script Builder tool will do this automatically for us when we save the script. Now let us set the telescope mode to tracking, click on the <function>setINDIScopeAction()</function> function and select TRACK. Note that we need to set the telescope to tracking <emphasis>before</emphasis> issuing the coordinates it needs to track. The <function>setINDIScopeAction()</function> function is provided for convenience; since in this example, it simply issues a generic <function>setINDIAction()</function> function followed by the keyword TRACK. However, the benefit of using <function>setINDIScopeAction()</function> is that KStars can automatically append <function>waitForINDIAction()</function> after it when required. This facility is not automatically available to generic actions as we discussed before.</para> + +<para>Next we use the <function>setINDITargetName()</function> function and set it to Mars. Finally, the last few steps involve capturing an image for 10 seconds which can be done by using <function>startINDIExposure()</function> function, and waiting for 20 seconds in between which can be done by using <function>waitFor()</function> function with a value of 20.</para> + +<para>We can now save our script and execute it at any time. The saved script will be similar to this:</para> +<blockquote><programlisting> + #!/bin/bash + #KStars DCOP script: Demo Script + #by Jasem Mutlaq + #last modified: Thu Jan 6 2005 09:58:26 + # + KSTARS=`dcopfind -a 'kstars*'` + MAIN=KStarsInterface + CLOCK=clock#1 + dcop $KSTARS $MAIN startINDI "LX200 GPS" true + dcop $KSTARS $MAIN startINDI "FLI CCD" true + dcop $KSTARS $MAIN waitFor 3 + dcop $KSTARS $MAIN switchINDI "LX200 GPS" true + dcop $KSTARS $MAIN waitForINDIAction "LX200 GPS" CONNECTION + dcop $KSTARS $MAIN switchINDI "FLI CCD" true + dcop $KSTARS $MAIN waitForINDIAction "FLI CCD" CONNECTION + dcop $KSTARS $MAIN setINDIScopeAction "LX200 GPS" TRACK + dcop $KSTARS $MAIN waitForINDIAction "LX200 GPS" ON_COORD_SET + dcop $KSTARS $MAIN setINDITargetName "LX200 GPS" Mars + dcop $KSTARS $MAIN waitForINDIAction "LX200 GPS" EQUATORIAL_EOD_COORD + dcop $KSTARS $MAIN startINDIExposure "FLI CCD" 10 + dcop $KSTARS $MAIN waitForINDIAction "FLI CCD" EXPOSE_DURATION + dcop $KSTARS $MAIN waitFor 20 + dcop $KSTARS $MAIN startINDIExposure "FLI CCD" 10 + dcop $KSTARS $MAIN waitForINDIAction "FLI CCD" EXPOSE_DURATION + dcop $KSTARS $MAIN waitFor 20 + dcop $KSTARS $MAIN startINDIExposure "FLI CCD" 10 + dcop $KSTARS $MAIN waitForINDIAction "FLI CCD" EXPOSE_DURATION +</programlisting> +</blockquote> + +<note> +<para>The INDI Library provides robust scripting tools that enable developers to orchestrate very complex scripts. For more details, refer to the <ulink url="http://indi.sourceforge.net/manual/book1.html">INDI Developer Manual</ulink>.</para> +</note> +</sect2> +</sect1> + |