# A Ferramenta de Construção de Script

Aplicativos KDE podem ser controlados externamente a partir de outro programa, da linha de comando do console, ou a partir de um script shell usando o Protocolo de Comuniação do Ambiente de Trabalho (do inglês, DCOP). O KStars aproveita este recurso para permitir que comportamentos complexos sejam roteirizados e executados repetidamente a qualquer hora. Isto pode ser usado, por exemplo, para criar uma aula demonstrativa para ilustrar um conceito astronômico.

O problema com scripts DCOP é que escrevê-los é um pouco parecido com programação, e pode ser uma tarefa desanimadora para quem não possui experiência de programação. A Ferramenta de Construção de Script fornece uma GUI do tipo apontar e clicar para construir scripts DCOP para o KStars, tornando muito fácil criar scripts complexos.

## Introdução ao Construtor de Script

Antes de explanar como usar o Construtor de Script, eu fornecerei uma introdução bem resumida de todos os componentes GUI; para mais informações, use a função "O Que É Isso?".

A Ferramenta de Construção de Script
Ferramenta de Construção de Script

O Construtor de Script é mostrado na captura de tela acima. A caixa à esquerda é a caixa do Script Atual; ela mostra a lista de comandos que compreende o script de trabalho atual. A caixa à direita é o Navegador de Função; ele mostra a lista de todas as funções de script disponíveis. Abaixo do Navegador de Função, existe um pequeno painel que exibirá uma documentação resumida sobre a função de script destacada no Navegador de Função. O painel abaixo da caixa de Script Atual é o painel de Argumentos da Função; quando uma função é destacada na caixa do Script Atual, este painel conterá todos os ítens para valores especificados para qualquer argumento que a função destacada precise.

Ao longo do topo da janela, existe uma linha de botões que operam no script como um todo. Da esquerda para direita, eles são: Novo Script, Abrir Script, Salvar Script, Salvar Script Como... e Testar Script. A função destes botões deve ser óbvia, execto talvez o último botão. Pressionar Testar Script experimentará a execução do script atual na janela principal do KStars. Você deve tirar a janela do Construtor do Script da frente antes de pressionar isto, de modo que possa ver os resultados.

No centro da janela, existe uma coluna de botões que operam em funções individuais do script. De cima para baixo, elas são: Adicionar Função, Remover Função, Copiar Função, Mover Acima e Mover Abaixo. Adicionar Função adiciona a função atualmente destacada no Navegador de Função à caixa do Script Atual (você pode também adicionar uma função dando um duplo-clique nela). O resto dos botões operam na função destacada na caixa do Script Atual, seja removendo-a, duplicando-a, ou mudando sua posição no script atual.

## Usando o Construtor de Script

Para ilustrar o uso do Construtor de Script, nós apresentaremos um pequeno tutorial exemplo onde nós criaremos um script que rastreia a Lua enquanto o relógio roda a uma taxa acelerada.

Se nós iremos rastrear a Lua, nós precisaremos apontar o mostrador primeiro. A função lookToward é usada para fazer isto. Destaque esta função no Navegador de Função e observe a documentação exibida no painel abaixo do Navegador. Pressione o botão Adicionar Função para adicionar esta função na caixa de Script Atual. O painel de Argumentos da Função agora conterá uma caixa combinada rotulada dir, abreviatura para direção. Esta é a direção na qual o mostrador deverá ser apontado. A caixa combinada contém somente os pontos cardinais, não a Lua ou qualquer outro objeto. Você pode inserir Lua na caixa manualmente, ou pressionar o botão Objeto para usar a janela Procurar Objeto para selecionar a Lua na lista de objetos nomeados. Observe que, como sempre, centrar em um objeto engaja automaticamente o modo de rastreamento do objeto, logo não é necessário adicionar a função setTracking após a lookToward.

Agora que nós já apontamos para Lua, nós vamos em seguida criar um passo de tempo numa taxa acelerada. Use a função setClockScale para isto. Adicione-a ao script com um duplo-clique nela no Navegador de Função. O painel de Argumentos da Função contém um caixa de contagem de passo de tempo para configurar o passo de tempo desejado para a simulação do relógio. Mude o passo de tempo para 3 horas.

OK, nós já apontamos para a Lua e aceleramos o relógio. Agora nós queremos simplesmente que o script espere por alguns segundo enquanto exibe a trilha da Lua. Adicione a função waitFor ao script, e use o painel de Argumentos da Função para especificar que ele deve esperar por 20 segundos antes de continuar.

Para finalizar, vamos reiniciar o passo de tempo do relógio para o valor normal de 1 segundo. Adicione outra instância do setClockScale, e configure seu valor para 1 segundo.

Nós ainda não terminados. Nós devemos provavelmente certificarmos-nos que o mostrador está usando coordenadas Equatoriais antes do script rastrear a Lua com o passo acelerado de tempo. Caso contrário, se o mostrador estiver usando coordenadas Horizontais, ele rotacionará muito rapidamente com grandes ângulos conforme a Lua nasce e se põe. Isto pode ser muito confuso, e é evitado configurando a Opção de Visão UseAltAz para false. Para mudar qualquer Opção de Visão, use a função changeViewOption. Adicione esta função ao script, e examine o painel de Argumentos da Função. Existe uma caixa combinada que contém uma lista de todas as opções que pode ser ajustadas pelo changeViewOption. Uma vez que nós desejamos a opção UseAltAz, nós podemos simplesmente selecioná-la na caixa combinada. No entanto, a lista é muito longa, e não existe nehuma explanação sobre o que é cada ítem. Talvez seja mais fácil pressionar o botao Navegar Árvore, que abrirá uma janela contendo uma visão em árvore das opções disponíveis, organizadas por tópico. Além disso, cada ítem possui uma explanação resumida do que a opção faz, e o tipo de dado do valor da opção. Nós encontramos o UseAltAz na categoria Opções do mapa celeste. Simplesmente destaque este ítem e pressione OK, e ele será selecionado na caixa combinada do painel de Argumentos da Função. Finalmente, torne este valor false ou 0.

Mais um passo: mudar o UseAltAz no final do script não é o que queremos; nós precisamos que isto seja mudado antes de qualquer coisa acontecer. Logo, certifique-se de que esta função esteja destacada na caixa do Script Atual, e pressione o botão Mover Acima até que ela seja a primeira função.

Agora que terminamos o script, nós devemos salvá-lo no disco. Pressione o botão Salvar Script. Isto primeiro abrirá uma janela da qual você pode fornecer um nome para o script, e preencher seu nome como autor. Insira Rastreando a Lua para o nome, e seu nome como autor, e pressione OK. A seguir, você verá o diálogo padrão do &kde; de Salvar Arquivo. Especifique um nome de arquivo para o script e pressione OK para salvar o script. Observe que se seu nome de arquivo não terminar com .kstars, este sufixo será automaticamente anexado. Se estiver curioso, você pode examinar o arquivo de script com qualquer editor de texto.

Agora que nós completamos o script, nós podemos executá-lo de diversas maneiras. A partir da linha de comando do console, você pode simplesmente executar o script caso um instância do KStars esteja atualmente em execução. Alternativamente, você pode executar o script de dentro do KStars usando o ítem Executar Script no menu Arquivo.

## Automação de Dispositivos com o INDI

O agendamento e automação de dispositivos é suportado para todos os dispositivos compatíveis com o INDI. Você pode coordenar qualquer número de dispositivos para realizarem operações complexas usando o Construtor de Scripts do &kstars;. Isto pode ser conseguido usando a interface DCOP INDI do &kstars;, que fornece diferentes classes de funções para atender as suas tarefas. As funções DCOP INDI podem ser divididas em quatro classes diferentes. A seguir está uma revisão das funções e seus argumentos como suportados pelo KStars. É altamente recomendável ler a seção Conceitos do INDI uma vez que empregaremos conceitos chaves do INDI neste tutorial.

1. Funções de Dispositivo Genéricas: Funções para estabelecer/desligar dispositivos, etc.

   - `startINDI (QString dispoNome, bool usarLocal)` : Estabelece um serviço INDI seja local ou servidor.

   - `shutdownINDI (QString dispoNome)` : Desliga o serviço INDI.

   - `switchINDI(QString dispoNome, bool tornarOn)` : Conecta ou Disconecta um dispositivo INDI.

   - `setINDIPort(QString dispoNome, QString porta)` : Configura a porta de conexão do dispositivo.

   - `setINDIAction(QString dispoNome, QString acao)` : Ativa uma ação INDI. A ação pode ser qualquer elemento de uma propriedade de opção/ação

   - `waitForINDIAction(QString dispoNome, QString acao)` : Pausa a execução do script atá a propriedade de ação especificada retornar com estado OK.

2. Funções de Telescópio: Funções para controlar o movimento e estado do telescópio.

   - `setINDIScopeAction(QString dispoNome, QString acao)` : Configura o modo do telescópio ou ação. As opções disponíveis são SLEW, TRACK, SYNC, PARK, e ABORT.

   - `setINDITargetCoord(QString dispoNome, double RA, double DEC)` : Configura as coordenadas alvo JNow do telescópio para RA e DEC.

   - `setINDITargetName(QString dispoNome, QString objetoNome)` : Configura as coordenadas alvo JNow do telescópio para as coordenadas do objectName. O KStars procurará o nome do objeto no banco de dados e retornará a RA and Dec uma vez encontradas.

   - `setINDIGeoLocation(QString dispoNome, double longitude, double latitude)` : Configura a localização geográfica para a longitude e latitude especificadas. A longitude é calculada E de N. Por exemplo, as coordenadas de Calgary - Canada no KStars são longitude: -114 04 58 - latitude: 51 02 58. Somente longitudes negativas precisam ser convertidas. Para converter a longitude para a notação E de N, consideremos a longitude possitiva e adicionamos 180 graus a ela. Assim, em nosso exemplo, a longitude do INDI = 114 04 08 + 180 00 00 = 294 04 08 E de N.

   - `setINDIUTC(QString dispoNome, QString DataHoraUTC)` : Configura a Data e Hora UTC do telescópio no formato ISO 8601. O formato é AAAA-MM-DDTHH:MM:SS (e.g. 2004-07-12T22:05:32).

3. Funções de Focador: Funções para controlar o movimento e estado do focador.

   - `setINDIFocusSpeed(QString dispoNome, QString acao)` : Configura a velocidade do focador. As opções disponíveis são FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM, e FOCUS_FAST.

   - `setINDIFocusTimeout(QString dispoNome, int espera)` : Configura a duração em segundos para qualquer operação subsequente de startINDIFocus.

   - `startINDIFocus(QString dispoNome, int focoDir)` : Move o focador seja para próximo (focoDir = 0) ou para longe (focoDir = 1). A velocidade e duração desta operação é configurada pelas funções `setINDIFocusSpeed()` e `setINDIFocusTimeout()`.

4. Funções de Câmera/CCD: Funções para controlar as propriedades e estado da câmera/CCD.

   - `setINDICCDTemp(QString dispoNome, int temp)` : Configura a temperatura alvo do chip CCD em graus celsius.

   - `setINDIFrameType(QString dispoNome, QString tipo)` : Configura o tipo de quadro CCD. As opções disponíveis são FRAME_LIGHT, FRAME_BIAS, FRAME_DARK, e FRAME_FLAT.

   - `startINDIExposure(QString dispoNome, int espera)` : Inicia a exposição do CCD/Câmera pela duração especificada por espera em segundos.

Observe que o nome do dispositivo é o primeiro argumento de todas as funções INDI. Isto permite que comandos diferentes que sejam enviados para dispositivos INDI diferentes sejam misturados juntos em um script. A ferramenta Construtor de Scripts fornece duas opções para facilitar a criação e edição de scripts INDI:

- `Adicionar waitForINDIAction após qualquer ação INDI`: Quando habilitado, a ferramenta Construtor de Script automaticamente adicionará `waitForINDIAction()` após qualquer ação que ele reconheça. Por exemplo, se você adicionar a função `switchINDI()` ao script e esta opção estiver habilitada, o Construtor de Scripts adicionará "waitForINDIAction CONNECTION" no arquivo de script logo após o `switchINDI()`. Isto fará que o script pause após ele enviar o `switchINDI()` até que o `switchINDI()` retorne o estado OK (&ie; conexão com dispositivo bem sucedida). É importante saber que o Construtor de Scripts não adicionará automaticamente o `waitForINDIAction()` para ações genéricas adicionadas usando a função `setINDIAction()`. Isto é porque o KStars não pode determinar a propriedade pai de ações genéricas. Deste modo, você deve adicionar manualmente o `waitForINDIAction()` após ações genéricas quando desejar.

- `Reutilizar o nome do dispositivo INDI`: Quando habilitado, o campo do nome do dispositivo de todas as funções subsequentes será automaticamente preenchido com o útlimo nome de dispositivo. O último nome de dispositivo é configurado toda vez que a função `startINDI()` é adicionada ao script atual. Ao trabalhar com dispositivos múltiplos, é recomendável desligar esta opção.

Agora estamos prontos para criar um script de demonstração que controla o telescópio LX200 GPS, em adição a uma câmera Finger Lakes CCD. Nossa tarefa é simples. Nós pediremos ao telescópio para apontar e rastrear Marte, então nós pediremos para câmera tirar três fotografias de 10 segundos cada separadas por 20 segundos.

Uma vez que não existe retorno direto da interface DCOP INDI sobre o progresso, valor ou estado das operações e parâmetros do dispositivo (exceto para o `waitForINDIAction()`), a automação do dispositivo no KStars é semelhante a um sistema de controle de loop aberto. Neste tipo de sistema, não existe normalmente nenhum retorno direto de medida de progresso do sistema e para correção de erros. Consequentemente, você deve desenhar seu script de automação de dispositivo com muito cuidado. Todos os scripts de automação devem ser sujeitos a testes rigorosos antes do seu emprego.

A Ferramenta de Construção de Script
Ferramenta de Construção de Script

O script de demonstração é mostrado na captura de tela acima. Observe que nós habilitamos o `"Adicionar waitForINDIAction após qualquer ação INDI"` e desabilitamos `"Reutilizar o nome do dispositivo INDI"`. A primeira função a adicionar é `startINDI()` como mostrado acima. Nós queremos rodar nossos dispositivos localmente, assim nós não mudamos o modo de serviço fornecido na janela de argumentos da função. Nós digitamos nosso nome de dispositivo, iniciando com o telescópio "LX200 GPS". Nós repetimos a mesma operação novamente para o "FLI CCD". Existe uma função `waitFor()` após isto. É normalmente recomendável usar a função `waitFor()` imediatamente após o `startINDI()` para pausar o script por 1-5 segundos. Isto irá garantir que todas as propriedades estão configuradas e prontas para receberem comandos. Isto também é útil para controlar dispositivos remotos pois a configuração das propriedades pode levar algum tempo. Na próxima função, `switchINDI()`, nós conectamos cada dispositivo.

Uma vez que o `"Adicionar waitForINDIAction após qualquer ação INDI"` está habilitada, nós não precisamos adicionar `waitForINDIAction()` após o `switchINDI()` para garantir que somente continuaremos a executar o script após uma conexão bem sucedida. Isto é porque a ferramenta do Construtor de Script fará isso automaticamente para nós quando salvarmos o script. Agora vamos configurar o modo do telescópio para rastreio; clique na função `setINDIScopeAction()` e selecione TRACK. Observe que nós precisamos configurar o telescópio para rastreio antes de enviar as coordenadas necessárias para rastrear. A função `setINDIScopeAction()` é fornecida por conveniência; uma vez que neste exemplo, ela simplesmente envia uma função `setINDIAction()` seguida pela chave TRACK. No entanto, a vantagem de usar o `setINDIScopeAction()` é que o KStars automaticamente adicionará o `waitForINDIAction()` quando necessário. Este recurso não está automaticamente disponível para ações genéricas como nós já mencionamos antes.

A seguir nós usaremos a função `setINDITargetName()` e a configuraremos para Marte. Finalmente, os últimos poucos passos envolvem a captura de imagens por 10 segundos que pode ser feita usando a função `startINDIExposure()`, e esperando por 20 segundos entre elas o que pode ser feito usando a função `waitFor()` com o valor de 20.

Nós podemos agora salvar nosso script e executá-lo a qualquer hora. O script salvo será semelhante a este:

>     #!/bin/bash
>         #KStars DCOP script: Script de Demonstração
>         #por Jasem Mutlaq
>         #última modificação: Qui 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