# L'outil de génération de scripts

Les applications KDE peuvent être pilotées de l'extérieur par un autre programme, depuis une invite de console ou depuis un script shell en utilisant le Desktop COmmunication Protocol (DCOP). KStars utilise cette fonction pour permettre à des comportements plutôt complexes d'être scriptés et rejoués à n'importe quel moment. Ceci peut être utilisé par exemple pour créer une démonstration de salle en classe pour illustrer un concept astronomique.

Le problème avec les scripts DCOP est que leur écriture ressemble à de la programmation, et peut sembler difficile à ceux qui n'ont pas l'expérience de la programmation. L'outil de génération de scripts fournit une interface graphique de type pointer-cliquer pour construire des scripts DCOP pour KStars, rendant très facile l'écriture de scripts complexes.

## Introduction au générateur de scripts

Avant d'expliquer comment utiliser le générateur de scripts, je fournis une très brève introduction à tous les composants d'interface graphique ; pour plus d'informations, utilisez la fonction « Qu'est-ce que c'est ? ».

L'outil de génération de scripts
Outil de génération de scripts

Le générateur de scripts est affiché dans la capture d'écran ci-dessus. La zone à gauche est la zone de script courant ; elle affiche la liste des commandes que comprend le script actuellement en fonctionnement. La zone à droite est le navigateur de fonctions ; il affiche la liste de toutes les fonctions de script disponibles. Sous le navigateur de fonctions, se trouve un petit panneau qui affiche une courte documentation sur la fonction de script surlignée dans le navigateur de fonction. Le panneau sous la zone de script courante est le panneau des arguments de fonctions ; quand une fonction est surlignée dans la zone de script courant, ce panneau contient des éléments pour spécifier les valeurs pour n'importe quel argument que la fonction surlignée nécessite.

Le long du haut de la fenêtre, il y a une rangée de boutons qui opèrent sur le script comme un tout. De la gauche vers la droite, il y a : Nouveau script, Ouvrir un script, Enregistrer le script, Enregistrer le script sous... et Tester le script. La fonction de ces boutons devrait être évidente, sauf peut-être le dernier bouton. En actionnant Tester le script, vous tenterez de lancer le script courant dans la fenêtre principale de KStars. Vous devrez déplacer la fenêtre de générateur de script hors du chemin avant d'actionner cela, et ainsi, vous pourrez voir le résultat.

Au centre de la fenêtre, se trouve une colonne de boutons qui opèrent sur une fonction individuelle du script. Du haut vers le bas, ce sont : Ajouter une fonction, Supprimer une fonction, Copier une fonction, Monter et Descendre. Ajouter une fonction ajoute la fonction actuellement sélectionnée dans le navigateur de fonctions à la zone de script courant (vous pouvez aussi ajouter une fonction en double-cliquant dessus). Le reste des boutons opère sur la fonction surlignée dans la zone de script courant, soit en l'enlevant, soit en le dupliquant, soit en changeant sa position dans le script courant.

## Utilisation du générateur de scripts

Pour illustrer l'utilisation du générateur de scripts, nous présentons un petit didacticiel où nous faisons un script qui suit la Lune, alors que l'horloge fonctionne à une vitesse accélérée.

Si nous voulons suivre la Lune, nous aurons besoin de pointer l'affichage dessus d'abord. La fonction lookToward est utilisée pour faire cela. Surlignez cette fonction dans le navigateur de fonctions et notez la documentation affichée dans le panneau au-dessous. Actionnez le bouton Ajouter une fonction pour ajouter cette fonction à la zone de script courante. Le panneau des arguments de fonction comportera maintenant une liste combinée libellée dir, abréviation de direction. C'est la direction dans laquelle l'affichage doit être pointé. La liste combinée ne contient que les points cardinaux, pas la Lune ni d'autres objets. Vous pouvez soit écrire Lune dans la zone à la main, soit actionner le bouton Objet pour utiliser la fenêtre de recherche d'objet pour sélectionner la Lune dans la liste des objets nommés. Notez que, comme d'habitude, un centrage sur un objet engage automatiquement le mode de suivi, de telle manière qu'il n'y a pas besoin d'ajouter la fonction setTracking après lookToward.

Maintenant que nous avons pris soin de pointer la Lune, nous voulons ensuite faire passer le temps en accéléré. Utilisez la fonction setClockScale pour cela. Ajoutez-la au script en double-cliquant dessus dans le navigateur de fonctions. Le panneau des arguments de fonctions contient un compteur de pas du temps pour régler le pas désiré pour l'horloge de simulation. Changez le pas sur 3 heures.

Bien. Nous avons pointé la Lune et accéléré l'horloge. Maintenant, nous voulons simplement que le script attende plusieurs secondes pendant que l'affichage suit la Lune. Ajoutez la fonction waitFor au script, et utilisez le panneau des arguments de fonction pour spécifier qu'il devrait attendre 20 secondes avant de continuer.

Pour finir, réinitialisons le pas d'horloge à la valeur normale d'une seconde. Ajoutez une autre instance de setClockScale, et positionnez sa valeur sur 1 sec.

En fait, tout n'est pas fini. Nous devons probablement nous assurer que l'affichage utilise les coordonnées équatoriales avant que le script ne suive la Lune avec le pas accéléré. Sinon, si l'affichage utilise les coordonnées horizontales, il tournera très vite sur de grands angles au lever et au coucher de la Lune. Ceci peut être troublant, et on l'évite en réglant l'option d'affichage UseAltAz sur false. Pour changer une option d'affichage, utilisez la fonction changeViewOption. Ajoutez cette fonction au script, et examinez le panneau des arguments de fonction. Il y a une liste combinée qui contient la liste de toutes les options d'affichage qui peuvent être ajustées par changeViewOption. Comme nous savons que nous voulons l'option UseAltAz, nous pouvons simplement la sélectionner dans la liste combinée. Cependant, la liste est assez longue, et il n'y a pas d'explication sur l'utilisation de chaque élément. Pour cela, il peut être plus facile d'actionner le bouton Parcourir l'arborescence, qui ouvrira une fenêtre contenant une vue arborescente des options disponibles, organisées par sujet. De plus, chaque élément a une courte explication sur ce que fait l'option, et le type de donnée de valeur de l'option. Nous trouvons UseAltAz sous la catégorie Options de carte du ciel. Surlignez simplement cet élément et actionnez OK, et elle sera sélectionnée dans la liste combinée du panneau des arguments de fonctions. Enfin, rendez sa valeur false ou 0.

Une dernière étape : le changement d'UseALtAz à la fin du script n'est pas bon ; nous avons besoin de le changer avant que quelque chose d'autre n'arrive. Ainsi, assurez-vous que cette fonction est surlignée dans la zone de script courant, et actionnez le bouton Monter jusqu'à ce que ce soit la première fonction.

Maintenant que nous avons fini le script, nous devrions l'enregistrer sur le disque. Actionnez le bouton Enregistrer le script. Cela ouvrira d'abord une fenêtre dans laquelle vous pouvez fournir un nom pour le script, et remplir votre nom en tant qu'auteur. Écrivez Suivi le la Lune comme nom, et votre nom comme auteur, et actionnez le bouton OK. Ensuite, vous verrez la boîte de dialogue standard de &kde; d'enregistrement des fichiers. Donnez un nom de fichier pour le script et actionnez OK pour enregistrer le script. Notez que si votre nom de fichier ne se termine pas par .kstars, ce suffixe sera automatiquement ajouté. Si vous êtes curieux, vous pouvez examiner le fichier de script avec un éditeur de texte.

Mantenant que nous avons un script terminé, nous pouvons le lancer de plusieurs manières. De l'invite d'une console, vous pouvez simplement exécuter le script tant qu'une instance de KStars est en fonctionnement. D'une autre manière, vous pouvez exécuter le script depuis KStars en utilisant l'élément Exécuter un script du menu Fichier.

## Automatisation du matériel avec INDI

La planification et l'automatisation du matériel est gérée pour tous les matériels compatibles INDI. Vous pouvez coordonner autant de matériel pour effectuer des opérations complexes avec le générateur de scripts de &kstars;. Ceci se fait en utilisant l'interface INDI DCOP de &kstars;, qui fournit différentes classes de fonctions pour s'adapter à vos tâches. Les fonctions INDI DCOP peuvent se décomposer en cinq classes différentes. Ce qui suit est un survol des fonctions et de leurs arguments, comme ils sont gérés par KStars. Il est très recommandé de lire la section Concepts INDI, car nous emploierons des concepts INDI dans ce didacticiel.

1. Fonctions génériques du matériel : fonctions pour établir/arrêter le matériel, etc.

   - `startINDI (QString deviceName, bool useLocal)` : établir un service INDI, soit en local, soit en serveur.

   - `shutdownINDI (QString deviceName)` : arrêter le service INDI.

   - `switchINDI(QString deviceName, bool turnOn)` : connecter ou déconnecter un service INDI.

   - `setINDIPort(QString deviceName, QString port)` : déterminer le port de connexion du matériel.

   - `setINDIAction(QString deviceName, QString action)` : active une action INDI. L'action peut êtren'importequel élément dans une propriété d'interrpution

   - `waitForINDIAction(QString deviceName, QString action)` : mettre en pause l'exécution du script jusqu'à ce que l'action spécifiée property retourne l'état OK.

2. Fonctions de télescope : les fonctions pour contrôler le mouvement et l'état du télescope.

   - `setINDIScopeAction(QString deviceName, QString action)` : détermine le mode ou l'action du télescope. Les options disponibles sont SLEW, TRACK, SYNC, PARK, et ABORT.

   - `setINDITargetCoord(QString deviceName, double RA, double DEC)` : détermine les coordonnées de la cible JNow du télescope à AD et DEC.

   - `setINDITargetCoord(QString deviceName, double RA, double DEC)` : Détermine les coordonnées de cible JNow du télescope de objectName. KStars cherchera le nom de l'objet dans sa base de données et cherchera l'AD et la Déc une fois trouvé.

   - `setINDIGeoLocation(QString deviceName, double longitude, double latitude)` : détermine l'emplacement géographique du télescope aux longitude et latitude spécifiées. La longitude est mesurée depuis Greenwich, Angleterre, vers l'Est. Cependant, alors qu'il est habituel d'utiliser des longitudes négatives vers l'Ouest, INDI utilise des longitudes entre 0 et 360 degrés. Ainsi, si vous avez une longitude négative, ajoutez simplement 360 degrés pour obtenir la valeur que INDI attend. Par exemple, les coordonnées de Calgary, Canada dans &kstars; sont -114 04 58; latitude: 51 02 58. Vous devrez fournir une longitude de 360 - 114.069 = 245.931 degrés.

   - `setINDIUTC(QString ddeviceName, QString UTCDateTime)` : détermine la date et l'heure UTC en format ISO 8601. Le format est AAAA-MM-JJTHH:MM:SS (&pex; 2004-07-12T22:05:32).

3. `setINDIUTC(QString ddeviceName, QString UTCDateTime)` : fonctions pour contrôler les propriétés et l'état des caméras et CCD.

   - `setINDICCDTemp(QString deviceName, int temp)` : détermine la température de la puce cible en degrés Celsius.

   - `setINDIFrameType(QString deviceName, QString type)` : détermine le type de cadre CCD. Les options disponibles sont FRAME_LIGHT, FRAME_BIAS, FRAME_DARK, et FRAME_FLAT.

   - `startINDIExposure(QString deviceName, int timeout)` : commencer l'exposition CCD/Caméra pour la durée spécifiée par timeout en secondes.

4. Fonctions de focus : fonctions pour contrôler le mouvement et l'état du viseur.

   - `setINDIFocusSpeed(QString deviceName, QString action)` : déterminer la vitesse du viseur. Les options disponibles sont FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM, et FOCUS_FAST.

   - `setINDIFocusTimeout(QString deviceName, int timeout)` : déterminer la durée en secondes pour n'importe quelle opération consécutive à startINDIFocus.

   - `startINDIFocus(QString deviceName, int focusDir)` : déplacer le viseur soit en rapprochement (focusDir = 0), soit en éloignement (focusDir = 1). La vitesse et la durée de cette opération sont déterminées par les fonctions `setINDIFocusSpeed()` et `setINDIFocusTimeout()`.

5. Fonctions de filtrage : fonctions pour contrôler la position du filtre.

   - `setINDIFilterNum(QString deviceName, int filter_num)` : changer la position du filtre en `filter_num`. L'utilisateur peut assigner des alias aux numéros des filtres dans la boîte de dialogue Configuration d'INDI sous le menu Périphériques (&pex; Filter 1 = Red, Filter 2 = Green..etc).

Notez que le nom du périphérique est le premier argument de toutes les fonctions INDI. Ceci permet à différentes commandes d'être envoyées à différents périphériques INDI en étant mélangées dans le script. L'outil de génération de scripts fournit deux options pour faciliter la création et l'édition des scripts INDI.

- `Append waitForINDIAction after any INDI action` : lorsque coché, l'outil de génération de scripts ajoutera automatiquement `waitForINDIAction()` après toute action qu'il reconnaît. Par exemple, si vous ajoutez une fonction `switchINDI()` au script, et que cette option est cochée, le générateur de scripts ajoutera "waitForINDIAction CONNECTION" dans le script juste après `switchINDI()`. Ceci fera que le script s'arrêtera après `switchINDI()` jusqu'à ce que `switchINDI()` retourne l'état OK (&pex; que la connexion au périphérique a réussi). Il est vital de savoir que le générateur de scripts ne peut pas ajouter automatiquement `waitForINDIAction()` pour les actions génériques ajoutées en utilisant la fonction `setINDIAction()`. Ceci est dû au fait que KStars ne peut pas déterminer la propriété parente pour les actions génériques. Pour cela, vous devez ajouter à la main `waitForINDIAction()` après les actions génériques si désiré.

- `Reuse INDI device name` : lorsque coché, le champ de nom du périphérique de toutes les fonctions subséquentes est automatiquement rempli par le dernier nom de périphérique. Le dernier nom de périphérique est déterminé à chaque fois que la fonction `startINDI()` est ajoutée au script courant. Lorsqu'on travaille avec de multiples périphériques, il est recommandé que cette option soit désactivée.

Maintenant, nous sommes prêts à créer un script de démonstration qui contrôle un télescope LX200 GPS, en plusd'une caméra CCD Finger Lakes. Notre tâche est simple. Nous demanderons au télescope de se déplacer et de suivre Mars, puis nous demanderons à la caméra de prendre trois images de 10 secondes, séparées chacune de 20 secondes.

Comme il n'y a pas de retour direct depuis l'interface DCOP INDI concernant la progression, la valeur ou l'état des opérations ou des paramètres du périphérique (sauf pour `waitForINDIAction()`), l'automatisation du périphérique dans KStars est semblable à un système de contrôle à boucle ouverte. Dans un tel système, il n'y a habituellement pas de renseignement en retour pour mesurer la progression du système et corriger les erreurs. En conséquence, vous devez concevoir vos scripts d'automatisation du périphérique avec soin. Tous les scripts d'automatisation doivent être sujets à des tests rigoureux avant déploiement.

L'outil de génération de scripts
Outil de génération de scripts

Le script de démonstration est montré dans la capture d'écran ci-dessus. Notez que nous avons coché `"Append waitForINDIAction after any INDI action"` et décoché `"Reuse INDI device name"`. La première fonction à ajouter est `startINDI()`, comme montré ci-dessus. Nous voulons lancer nos périphériques locaux, ainsi, nous ne changerons pas le mode de service fourni dans la fenêtre des arguments de fonction. Nous écrivons notre nom de périphérique, commençant par le télescope "LX200 GPS". Nous répétons la même opération pour "FLI CCD". Il y a une fonction `waitFor()` après cela. Il est généralement recommandé d'utiliser la fonction `waitFor()` juste après `startINDI()` pour mettre en pause le script pendant 1 à 5 secondes. Ceci assurera que toutes les propriétés sont construites et sont prêtes à recevoir des commandes. C'est aussi utile pour contrôler des périphériques distants, car les trouver et construire leurs propriétés peut prendre du temps. Dans la fonction suivante, `switchINDI()`, nous connectons chaque périphérique.

Comme `"Append waitForINDIAction after any INDI action"` est coché, nous n'avons pas besoin d'ajouter de fonction `waitForINDIAction()` après `switchINDI()` pour s'assurer que nous continuons seulement à exécuter le script après une connexion correcte. Ceci est dû au fait que l'outil de génération de scripts fera ceci automatiquement pour nous lorsque nous enregistrerons le script. Maintenant, réglons le télescope en mode suivi, cliquons sur la fonction `setINDIScopeAction()`, et sélectionnons TRACK. Notez que nous avons besoin de régler le mode du télescope sur suivi, avant de fournir les coordonnées dont il a besoin pour le suivi. La fonction `setINDIScopeAction()` est fournie pour des raisons pratiques, car, dans cet exemple, elle fournit simplement une fonction générique `setINDIAction()`, suivie par le mot-clé TRACK. Cependant, le bénéfice d'utiliser `setINDIScopeAction()` est que KStars peut ajouter automatiquement `waitForINDIAction()` après, lorsque nécessaire. Cette facilité n'est pas disponible automatiquement aux actions génériques, comme nous en avons discuté plus tôt.

Ensuite, nous utiliserons la fonction `setINDITargetName()` et la déterminerons sur Mars. Enfin, les quelques dernières étapes impliquent la capture d'une image pendant 10 secondes, ce qui peut se faire en utilisant la fonction `startINDIExposure()`, et l'attente pendant 20 secondes entre elles, ce qui peut se faire en utilisant la fonction `waitFor()` avec une valeur de 20.

Nous pouvons, maintenant, enregistrer notre script et l'exécuter n'importe quand. Le script enregistré sera semblable à ceci :

>     #!/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

La bibliothèque INDI fournit des outils de scriptage robustes pour permettre aux développeurs d'orchestrer des scripts très complexes. Pour plus de détails, référez-vous au Manuel du développeur INDI.