<sect1 id="tool-scriptbuilder"> <title >Budowanie skryptów</title> <indexterm ><primary >Narzędzia</primary> <secondary >Budowanie skryptów</secondary> </indexterm> <para >Programy KDE mogą być kontrolowane przez inny program przy użyciu protokołu Desktop COmmunication Protocol (<abbrev >DCOP</abbrev >). Taka kontrola jest ma miejsce z wiersza poleceń, bądź przez skrypt. KStars korzysta z tych możliwości, co pozwala na budowanie skomplikowanych skryptów i uruchamianie ich w dowolnym czasie. W ten sposób można na przykład przygotować materiał szkoleniowy na lekcję ilustrujący pewne zagadnienie z dziedziny astronomii. </para> <para >Pisanie skryptów DCOP jest podobne do programowania, więc może wydawać się zadaniem trudnym dla tych, którzy nigdy tego nie próbowali. Narzędzie budowy skryptów dostarcza interfejsu <abbrev >GUI</abbrev > do budowy skryptów DCOP, co znacznie ułatwia tworzenie rozbudowanych skryptów. </para> <sect2 id="sb-intro"> <title >Wprowadzenie do budowania skryptów</title> <para >Przed wyjaśnieniem jak działa narzędzie budowy skryptów, krótko opiszemy podstawowe komponenty interfejsu <abbrev >GUI</abbrev >; więcej informacji można uzyskać wykorzystując funkcję "Co to jest?". </para> <screenshot> <screeninfo >Narzędzie Budowanie skryptów </screeninfo> <mediaobject> <imageobject> <imagedata fileref="scriptbuilder.png" format="PNG"/> </imageobject> <textobject> <phrase >Narzędzie Budowanie skryptów</phrase> </textobject> </mediaobject> </screenshot> <para >Powyżej pokazany jest wygląd narzędzia budowy skryptów. Po lewej stronie znajduje się okno <firstterm >Bieżący skrypt</firstterm >; zawiera ono listę poleceń składających się na obecnie tworzony skrypt. Po prawej stronie znajduje <firstterm >Przeglądarka funkcji</firstterm >; wyświetlająca listę wszystkich dostępnych w skryptach funkcji. Poniżej Przeglądarki funkcji znajduje się niewielki panel, wyświetlający krótką dokumentację wybranej funkcji. Panel pod oknem obecnie tworzonego skryptu to panel <firstterm >Argumenty funkcji</firstterm >; zawierający wymagane przez wybraną powyżej funkcję argumenty. </para ><para >U góry okna znajduje się rząd przycisków, które mają zastosowanie przy skryptach. Od lewej są to: <guibutton >Nowy skrypt</guibutton >, <guibutton >Otwórz skrypt</guibutton >, <guibutton >Zapisz skrypt</guibutton >, <guibutton >Zapisz skrypt jako...</guibutton >, i <guibutton >Wypróbuj skrypt</guibutton >. Działanie tych przycisków powinno być oczywiste, może poza ostatnim. Wciśnięcie <guibutton >Wypróbuj skrypt</guibutton > spowoduje próbę uruchomienia bieżącego skryptu w głównym oknie KStars. Przed jego wciśnięciem powinno przesunąć się okno z treścią skryptu tak, aby było widać wyniki. </para ><para >Na środku okna znajduje się kolumna przycisków, które mają zastosowanie do poszczególnych funkcji skryptu. Od góry do dołu są to: <guibutton >Dodaj funkcję</guibutton >, <guibutton >Usuń funkcję</guibutton >, <guibutton >Kopiuj funkcję</guibutton >, <guibutton >W górę</guibutton > i <guibutton >W dół</guibutton >. <guibutton >Dodaj funkcję</guibutton > dodaje obecnie zaznaczoną funkcję z przeglądarki funkcji do skryptu (to samo można osiągnąć przez podwójne kliknięcie nazwy funkcji). Pozostałe przyciski działają na funkcji zaznaczonej w polu skryptu. Powodują jej usunięcie, powielenie lub zmianę pozycji w skrypcie. </para> </sect2> <sect2 id="sb-using"> <title >Korzystanie z narzędzia budowania skryptów</title> <para >Aby przedstawić korzystanie z narzędzia budowania skryptów pokażemy przykład, w którym tworzymy skrypt śledzący Księżyc, podczas gdy zegar działa w trybie przyspieszonym. </para ><para >Jeżeli chcemy śledzić Księżyc musimy najpierw wyśrodkować go na ekranie. Wykorzystamy do tego funkcję <firstterm >lookToward</firstterm >. Zaznacz tą funkcję w przeglądarce funkcji i sprawdź jej dokumentację wyświetloną w panelu poniżej przeglądarki. Wciśnij przycisk <guibutton >Dodaj funkcję</guibutton >, aby dodać funkcję do pola bieżącego skryptu. Panel argumentów funkcji będzie zawierał listę rozwijaną o nazwie <quote >Kierunek</quote >. Wybiera się tam Jest to kierunek, w którym ma być skierowany ekran. List rozwijana zawiera tylko główne kierunki geograficzne, bez Księżyca czy innych obiektów. Możesz wprowadzić "Księżyc" ręcznie albo wcisnąć przycisk <guibutton >Obiekt</guibutton > aby skorzystać z okna <guilabel >Znajdź obiekt</guilabel > do znalezienia Księżyca z listy nazwanych obiektów. Pamiętaj, że jak zwykle wyśrodkowanie na obiekcie spowoduje włączenie trybu śledzenia. Nie ma więc potrzeby aby dodawać funkcję <firstterm >setTracking</firstterm > po funkcji lookToward. </para ><para >Teraz, gdy wskazaliśmy Księżyc, chcemy spowodować aby czas płynął z przyśpieszoną prędkością. Wykorzystaj do tego funkcję <firstterm >setClockScale</firstterm >. Dodaj ją do skryptu poprzez podwójne kliknięcie w przeglądarce funkcji. Panel argumentów tej funkcji zawiera pole umożliwiające ustawienie kroku czasu dla zegara symulacji. Zmień wartość na 3 godziny. </para ><para >Teraz chcemy tylko, aby skrypt zaczekał przez kilka sekund, żeby program wyśrodkował ekran na Księżycu. Dodaj do skryptu funkcję <firstterm >waitFor</firstterm > i skorzystaj z panelu argumentów funkcji aby ustawić wartość oczekiwania na 20 sekund. </para ><para >Teraz zresetuj krok czasowy zegara na wartość domyślną 1 sekundy. Dodaj kolejne wywołanie funkcji setClockScale i ustaw jej wartość na 1. </para ><para >Powinniśmy się jeszcze upewnić, że wykorzystywane są współrzędne równikowe, zanim skrypt będzie śledził Księżyc z przyśpieszonym krokiem czasu. Jeżeli będą wykorzystywane współrzędne horyzontalne nastąpi bardzo szybki obrót o duże kątywraz ze wschodem i zachodem Księżyca. Może być to bardzo irytujące, ale można temu zapobiec ustawiając opcję widoku<firstterm >UseAltAz</firstterm > na <quote >false</quote >. Aby zmienić dowolną opcję widoku wykorzystaj funkcję <firstterm >changeViewOption</firstterm >. Dodaj tą funkcję do skryptu. W panelu argumentów funkcji znajduje się lista rozwijana, która zawiera wszystkie opcje, które mogą być dostosowane za jej pomocą. Z listy tej należy wybrać opcję UseAltAz, możemy także wcisnąć przycisk <guibutton >Przeglądaj drzewo</guibutton >, który zawiera drzewo wszystkich dostępnych opcji, zorganizowane tematycznie. Dodatkowo każda pozycja zawiera krótki opis mówiący o tym, co dana funkcja robi i jakiego typu danych potrzebuje. UseAltAz można znaleźć w kategorii <guilabel >Opcje mapy nieba</guilabel >. Po wybraniu funkcja znajdzie się w odpowiednim polu okna narzędzia budowania skryptów. Zmień jeszcze jej wartość na <quote >false</quote > lub <quote >0</quote >. </para ><para >Jeszcze jeden krok: zmiana UseAltAz na samym końcu skryptu nic nie pomoże, potrzebna jest na samym początku. Zaznacz ją więc w polu skryptu i wciskaj przycisk <guibutton >W górę</guibutton > tak długo, aż UseAltAz będzie pierwszą funkcją skryptu. </para ><para >Teraz, po skończeniu skryptu, należy zapisać go na dysku. Wciśnij przycisk<guibutton >Zapisz skrypt</guibutton >. Spowoduje to otwarcie okna w którym należy wprowadzić nazwę skryptu, a także dane jego autora. Jako nazwę wprowadź <quote >Śledzenie Księżyca</quote >, natomiast w polu autora wpisz swoje imię i naciśnij <guibutton >OK</guibutton >. Teraz zobaczysz standardowe okno zapisu pliku w &kde;. Określ nazwę pliku dla skryptu i wciśnij <guibutton >OK</guibutton >, aby zapisać skrypt. Pamiętaj, że jeżeli nazwa pliku nie będzie kończyć się na <quote >.kstars</quote >, to ten przyrostek zostanie dodany automatycznie. Jeżeli ciekawi Cię wygląd takiego pliku, możesz go obejrzeć w dowolnym edytorze tekstu. </para ><para >Skrypt możemy uruchomić na kilka sposobów. Jeżeli działa KStars możemy to zrobić z wiersza poleceń. Inna metoda to uruchomienie skryptu przez KStars po wybraniu opcji <guimenuitem >Uruchom skrypt</guimenuitem > z menu <guimenu >Plik</guimenu >. </para> </sect2> <sect2 id="sb-indi"> <title >Automatyczne obsługiwanie urządzeń przy pomocy INDI</title> <para >Automatyczna obsługa urządzeń jest zapewniona dla wszystkich urządzeń kompatybilnych z <link linkend="what-is-indi" >INDI</link >. Możesz używać dowolnej ich liczby dzięki narzędziu <link linkend="sb-intro" >Budowanie skryptów</link > w &kstars;. Służy do tego interfejs INDI DCOP &kstars;, który udostępnia różne klasy funkcji do wykorzystania do Twoich potrzeb. Funkcje INDI DCOP można podzielić na pięć klas. Dalej znajduje się opis funkcji dostępnych w &kstars; i ich argumentów. Polecamy przeczytanie sekcji dotyczącej <link linkend="indi-concepts" >zasady działania INDI</link >, jako że w dalszej części podręcznika wykorzystamy kilka szczególnych cech INDI.</para> <orderedlist> <listitem ><para >Ogólne funkcje urządzeń: funkcje do włączania/wyłączania urządzeń itp.</para> <itemizedlist> <listitem ><para ><function >startINDI (QString deviceName, bool useLocal)</function > : Włącza usługę INDI lokalnie lub na serwerze.</para ></listitem> <listitem ><para ><function >shutdownINDI (QString deviceName)</function > : Zamyka usługę INDI.</para ></listitem> <listitem ><para ><function >switchINDI(QString deviceName, bool turnOn)</function > : Podłącza bądź rozłącza urządzenie INDI.</para ></listitem> <listitem ><para ><function >setINDIPort(QString deviceName, QString port)</function > : Ustawia port komunikacyjny urządzenia.</para ></listitem> <listitem ><para ><function >setINDIAction(QString deviceName, QString action)</function > : Aktywuje akcję INDI. Akcja może być dowolnym <emphasis >elementem</emphasis > z <emphasis >własności przełączania</emphasis ></para ></listitem> <listitem ><para ><function >waitForINDIAction(QString deviceName, QString action)</function > : Wstrzymuje wykonanie skryptu aż określona <emphasis >własność</emphasis > zwróci status OK.</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Funkcje teleskopu: Funkcje kontrolujące ruch i stan teleskopu</para> <itemizedlist> <listitem ><para ><function >setINDIScopeAction(QString deviceName, QString action)</function > : Ustawia tryb teleskopu lub działanie. Dostępne opcje to SLEW, TRACK, SYNC, PARK i ABORT.</para ></listitem> <listitem ><para ><function >setINDITargetCoord(QString deviceName, double RA, double DEC)</function > : Ustawia cel JNow teleskopu na współrzędne <emphasis >RA</emphasis > i <emphasis >DEC</emphasis >.</para ></listitem> <listitem ><para ><function >setINDITargetName(QString deviceName, QString objectName)</function > : Ustawia cel teleskopu JNow na współrzędne wybranego obiektu (<emphasis >objectName</emphasis >. KStars wyszuka nazwę obiektu w bazie danych i pobierze ich RA i Dec.</para ></listitem> <listitem ><para ><function >setINDIGeoLocation(QString deviceName, double longitude, double latitude)</function > : Ustawia lokalizację teleskopu na określoną długość i szerokość geograficzną. Długość geograficzna jest liczona od Greenwich na wschód. Jednakże mimo tego, że zwykle korzysta się z odwróconych długości geograficznych dla zachodniej półkuli INDI wymaga wartości długości z przedziału od 0 do 360 stopni. Jeżeli więc Twoja długość geograficzna jest ujemna, po prostu dodaj do niej 360 stopni. Na przykład Calgary w Kanadzie ma długość geograficzną: -114 04 58 i szerokość geograficzną: 51 02 58. Tak więc w INDI' te długość geograficzna będzie wynosić 360 - 114.083 = 245.917 stopni.</para ></listitem> <listitem ><para ><function >setINDIUTC(QString ddeviceName, QString UTCDateTime)</function > : Ustawia datę i czas UTC teleskopu w formacie ISO 8601. Format ten wygląda następująco: YYYY-MM-DDTHH:MM:SS (np. 2004-07-12T22:05:32).</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Funkcje kamer/CCD: Funkcje kontrolujące właściwości i stan kamer/CCD.</para> <itemizedlist> <listitem ><para ><function >setINDICCDTemp(QString deviceName, int temp)</function > : Ustawia docelową temperaturę barw matrycy CCD w stopniach Celsjusza.</para ></listitem> <listitem ><para ><function >setINDIFrameType(QString nazwaUrządenia, QString rodzaj)</function > : Ustawia rodzaj ramki CCD. Dostępne opcje to FRAME_LIGHT, FRAME_BIAS, FRAME_DARK i FRAME_FLAT.</para ></listitem> <listitem ><para ><function >startINDIExposure(QString deviceName, int timeout)</function > : Rozpoczyna ekspozycję, na czas określony przez <emphasis >timeout</emphasis >, w sekundach.</para ></listitem> </itemizedlist> </listitem > <listitem ><para >Funkcje focusera: funkcje do kontroli ruchu i stanu focusera.</para> <itemizedlist> <listitem ><para ><function >setINDIFocusSpeed(QString deviceName, QString action)</function > : Ustawia prędkość focusera. Dostępne opcje to: FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM i FOCUS_FAST.</para ></listitem> <listitem ><para ><function >setINDIFocusTimeout(QString deviceName, int timeout)</function > : Ustawia czas trwania składowych operacji startINDIFocus w sekundach.</para ></listitem> <listitem ><para ><function >startINDIFocus(QString deviceName, int focusDir)</function > : Przesuwa focuser do wewnątrz (focusDir = 0) albo na zewnątrz (focusDir = 1). Prędkość i czas tej operacji są ustawiane przez funkcje <function >setINDIFocusSpeed()</function >i <function >setINDIFocusTimeout()</function >.</para ></listitem> </itemizedlist> </listitem> <listitem ><para >Funkcje filtra: Funkcje kontrolujące pozycję filtra.</para> <itemizedlist> <listitem ><para ><function >setINDIFilterNum(QString deviceName, int filter_num)</function > : Zmiana pozycji filtra na <varname >filter_num</varname >. Użytkownik może przypisać aliasy do numeru filtra w oknie <guimenuitem >Konfiguracja INDI</guimenuitem > z menu <guimenu >Urządzenia</guimenu > (np. Filtr 1 = czerwony, Filtr 2 = zielony itd).</para ></listitem> </itemizedlist> </listitem> </orderedlist> <para >Pamiętaj, że nazwa urządzenia jest pierwszym argumentem dla wszystkich funkcji INDI. Pozwala na umieszczenie w jednym skrypcie różnych poleceń, które są wysyłane do wielu urządzeń INDI. Narzędzie budowania skryptów zawiera dwie opcje ułatwiające tworzenie i modyfikację skryptów INDI.</para> <itemizedlist> <listitem ><para ><option >Po każdej akcji INDI dołącz WaitForINDIAction</option > : Gdy zaznaczona, narzędzie budowania skryptów automatycznie doda <function >waitForINDIAction()</function > po każdym rozpoznanym działaniu. Dla przykładu, jeśli dodasz do skryptu funkcję <function >switchINDI()</function > ,a opcja ta jest zaznaczona, to narzędzie budowania skryptów doda "waitForINDIAction CONNECTION" do pliku skryptu, zaraz po <function >switchINDI()</function >. Spowoduje to wstrzymanie skryptu po wydaniu polecenia <function >switchINDI()</function > aż do momentu gdy <function >switchINDI()</function > zwróci status OK (np. podłączanie urządzenia zakończy się powodzeniem). Jest niezwykle istotne by pamiętać, że narzędzie budowania skryptów nie może automatycznie dodać <function >waitForINDIAction()</function > dla ogólnych działań dodanych za pomocą funkcji <function >setINDIAction()</function >. Dzieje się tak, ponieważ KStars nie może określić właściwości nadrzędnych funkcji ogólnych. Dlatego musisz dodać ręcznie <function >waitForINDIAction()</function > po wybranych działaniach ogólnych.</para> </listitem> <listitem ><para ><option >Ponownie użyj nazwy urządzenia INDI</option > : Gdy zaznaczono, to pole nazwy urządzenia wszystkich podrzędnych funkcji jest automatycznie wypełniane nazwą ostatniegourządzenia. Nazwa ta jest ustawiana po każdym dodaniu<function >startINDI()</function > do bieżącego skryptu. Przy pracy z wieloma urządzeniami zaleca się wyłączenie tej funkcji.</para> </listitem> </itemizedlist> <para >Nadszedł czas na stworzenie skryptu demo sterującego teleskopem LX200 GPS oraz kamerą Finger Lakes CCD. Zadanie jest proste. Każemy teleskopowi obrócić się i śledzić Marsa, następnie każemy aparatowi zrobić 3 ujęcia 10 sekundowe co 20 sekund.</para> <important ><para >Ponieważ nie ma bezpośredniej odpowiedzi z interfejsu INDI DCOP dotyczącej postępu wartości czy stanu działań urządzenia i jego parametrów, za wyjątkiem <function >waitForINDIAction()</function >, automatyczna obsługa urządzeń jest podobna do systemu sterowania z otwartą pętlą. W takim systemie zwykle nie ma bezpośredniej odpowiedzi pozwalającej zmierzyć postęp i poprawić błędy. W związku z tym skrypty trzeba pisać po dokładnym rozważeniu ich działania. Wszysztkie tego typu skrypty wymagają dokładnego testowania przed wdrożeniem.</para ></important> <screenshot> <screeninfo >Narzędzie Budowanie skryptów </screeninfo> <mediaobject> <imageobject> <imagedata fileref="indiscript.png" format="PNG"/> </imageobject> <textobject> <phrase >Narzędzie Budowanie skryptów</phrase> </textobject> </mediaobject> </screenshot> <para >Powyżej zaprezentowany jest skrypt demo. Pamiętaj, że zaznaczyliśmy opcję <option >"Po każdej akcji INDI dołącz WaitForINDIAction"</option > i odznaczyliśmy opcję <option >"Ponownie użyj nazwy urządzenia INDI"</option >. Ponieważ chcemy uruchomić nasze urządzenie lokalnie, nie zmieniamy trybu usługi podanego w oknie argumentów funkcji. Wpisujemy nazwę naszego urządzenia rozpoczynając od teleskopu "LX200 GPS". Tą samą operację powtarzamy dla "FLI CCD". Potem następuje <function >waitFor()</function >. Zaleca się korzystanie z funkcji <function >waitFor()</function > zaraz po <function >startINDI()</function >, aby wstrzymać skrypt do 1-5 sekund. To pozwoli zapewnić, że wszystkie właściwości są jużpoprawnie ustawione i gotowe na przyjmowanie poleceń. Jest to także użyteczne przy kontroli zdalnych urządzeń, ponieważ pobieranie i budowanie właściwości może zabrać sporo czasu. W kolejnej funkcji, <function >switchINDI()</function >, podłączamy się do każdego urządzenia.</para> <para >Opcja <option >"Po każdej akcji INDI dołącz WaitForINDIAction"</option > jest zaznaczona, więc nie trzeba dodawać <function >waitForINDIAction()</function > po <function >switchINDI()</function >, żeby mieć pewność, że będziemy kontynuować tylko w przypadku poprawnego połączenia. Dzieje się tak, gdyż narzędzie Budowanie skryptów zrobi to za nas, automatycznie, przy zapisywaniu skryptu. Teraz przestawmy teleskop w tryb śledzenia. Kliknij funkcję <function >setINDIScopeAction()</function > i wybierz TRACK. Warto zauważyć, że trzeba przestawić teleskop w tryb śledzenia <emphasis >przed</emphasis > podaniem współrzędnych. Dla ułatwienia istnieje funkcja <function >setINDIScopeAction()</function >. W tym przykładzie wykonuje ona po prostu <function >setINDIAction()</function > z dalej następującym słowem kluczowym TRACK. Jednakże zyskiem z wykorzystania <function >setINDIScopeAction()</function > jest to, że KStars może automatycznie dodać po niej<function >waitForINDIAction()</function >, kiedy tylko jest taka potrzeba. Ta właściwość nie jest automatycznie dostępna dla ogólnych akcji omawianych wcześniej. </para> <para >Następnie korzysamy z funkcji <function >setINDITargetName()</function > i ustawiamy ją na Marsa. Ostatnie kilka kroków polega na przechwytywaniu obrazu przez 10 sekund, co można zrobić za pomocą funkcji <function >startINDIExposure()</function >, i odczekaniu 20 sekund, co można zrobić za pomocą funkcji <function >waitFor()</function > z wartością 20.</para> <para >Możemy teraz zapisać skrypt i wykonać go w dowolnym momencie. Powinien on wyglądać podobnie do tego:</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 >Biblioteka INDI zawiera funkcjonalne narzędzia, które umożliwiają programistom tworzenie bardziej skomplikowanych skryptów. Więcej informacji znajdziesz w podręczniku dla programistów <ulink url="http://indi.sourceforge.net/manual/book1.html" >INDI Developer Manual</ulink >.</para> </note> </sect2> </sect1>