Using commands with GoQat
GoQat's graphical user interface (GUI) is made up of many elements, each referred to as a 'widget'. Each widget has an identifier associated with it. This identifier can be used to change the state of the widget, for example to click a button, select an option, or enter text or numbers into a field. GoQat enables the user to discover the identifier of any widget and can receive commands to change the state of the widget from an external source. This means that GoQat can be controlled entirely by another application or external script. If you want to embed GoQat in something else 'behind the scenes', you can even hide the GUI altogether.
GUI widget identifiers
GoQat can show us the identifier of a widget and its current state (these two items together make a command). To do this, start GoQat and click on the File menu, then select 'Show widget commands'. Now middle-click with the mouse on the 'Open camera' checkbox on the Camera tab. If the camera is closed, you will see 'chkCCDOpen 0' in GoQat's log window. Now open the camera and try again. This time you will see 'chkCCDOpen 1'. The identifier for the widget is 'chkCCDOpen'; when the camera is closed it has a state of '0' and when the camera is open it has a state of '1'. You can middle-click on any widget in the GUI to see its identifier and current state, but the widget must be available (i.e. not greyed-out and must be visible on a selected tab or in an open window or dialog). The widget identifier and its state are not written to the log file. If you want to save them to a file, go to the File menu and select 'Write commands to log and file'. They will be written to a file called 'commands.txt' in the GoQat folder of your home directory. Instances of GoQat greater than 1 will write to a file called commands_nn.txt where 'nn' is the instance number.
Commands
In previous tutorials we saw how to use tasks in the task queue. Tasks are primarily for carrying out extended operations that take some time, for example focusing the camera and slewing the telescope. By contrast, commands are instantaneous and are useful for setting the state of the GUI. However, commands can also be used for initiating extended operations such as camera exposures as we shall see.
A command consists of a widget identifier followed by the state to which the widget should be set. GoQat receives such commands from a file that you specify on the Files tab. To do this, select a location for the incoming commands file and enter the file name, then click 'Activate' to have GoQat monitor the file. GoQat will create the file if it does not already exist. Whenever the file content changes, GoQat will read it and process the command. If the file is pre-existing, any content already in the file is ignored. More than one instance of GoQat can monitor the same file, so if you have multiple imaging platforms for example, you could control them all at once.
Some examples
We'll see how this works with some examples. Here we will enter commands in a terminal session but commands could just as well be written by a script or sent from another application. Make sure GoQat is running and you have activated monitoring on an incoming commands file. Open a terminal session and type:
echo 'chkCCDOpen 1' > /my/commands/file
where '/my/commands/file' is the full file path and file name of the incoming commands file that GoQat is monitoring. If your camera is connected to GoQat, GoQat will open the camera. Now we'd like to set the exposure type to 'FLAT'. Make sure you've selected 'Show widget commands' from the File menu and middle-click on the exposure type combobox. GoQat tells you that the identifier is 'cmbCCDExpType'. To set it to type 'FLAT', do this:
echo 'cmbCCDExpType FLAT' > /my/commands/file
Similarly, we can set an object name for the FITS header and set the exposure time like this:
echo 'txtCCDObject Flat field' > /my/commands/file
echo 'txtCCDExposure 8.5' > /my/commands/file
Now we'd like to start the exposure. Middle-click on the 'Start Exposure' button - GoQat replies with 'btnCCDStart' in the log window. Note that it doesn't give a state. You don't need to provide one for buttons that press in and come out again when you click them - just give the identifier and GoQat understands that you want to 'click' it:
echo 'btnCCDStart' > /my/commands/file
Let's save the image file. We need to navigate to the Files tab first. Middle-click where it says 'Files' at the top of the tab - GoQat replies with 'ntbMainNotebook CCD Camera'! Well, that wasn't what we were expecting. Recall that a widget has to be available for middle-clicking to work. Click on the files tab as normal to select it, then middle-click again at the top. This time GoQat says 'ntbMainNotebook Files'. Now go back to the Camera tab and do this:
echo 'ntbMainNotebook Files' > /my/commands/file
See how GoQat switches from the Camera tab to the Files tab?
We'd like to specify a location to save the image file. Middle-click on the folder chooser button for the camera image. GoQat replies with 'flcFolderCCD /current/folder/location' where '/current/folder/location' is the current folder that the button is pointing to. We can specify a different folder like this:
echo 'flcFolderCCD /a/different/folder' > /my/commands/file
Now we specify the filename that we want:
echo 'txtFileCCD my_flat_field' > /my/commands/file
We can save the image file by clicking 'Save CCD image' on the File menu. GoQat tells us that the identifier for that menu item is 'save_ccd_image'. There's a curious feature of the way that the GUI is constructed which is actually very helpful: we don't have to activate higher level menus before we can send commands to lower level menu items. So we don't have to open the File menu before activating the 'Save CCD image' menu item. All we need to do is this for GoQat to save the file:
echo 'save_ccd_image' > /my/commands/file
You don't need to type every command individually. If you have some favourite commands that are normally executed one after the other you can put them in a file and send them to GoQat all at once. The file can contain blank lines and comments preceded by a '#'. We could have put some of the above commands in a file like this:
Then we can 'cat' the entire contents of the file to GoQat like this:
cat file_of_commands > /my/commands/file
Of course an external script or application would need to know when the exposure had ended before it could save the file. In fact you can get this from GoQat's Status directory, by default in the 'GoQat' folder of your home directory. The file called 'Exposing' in the 'CCD_Camera' subdirectory contains a '1' when the camera is exposing and '0' when it isn't.
GoQat command-line interface
It's a bit tedious typing lots of 'echo' statements if you want to control GoQat from a terminal session. Instead you can use GoQat's command-line interface (CLI). Type 'gqcli' at a terminal prompt to start the interface. It is just a very simple script that allows you to define the files to which commands can be written and then sends any commands to that file for you. You can also send tasks to GoQat in a very similar fashion. The CLI knows which are commands and which are tasks and sends them to the appropriate files. The files to which tasks and commands are sent must pre-exist before you start; the CLI checks for their existence and give an error if they are not available. You can also send the contents of entire files of tasks or commands to GoQat with the CLI. The following four examples show how to send a command, a task, a file of commands and a file of tasks to GoQat.
gqcli > chkCCDOpen 1
gqcli > GoToNext
gqcli > cmd file_of_commands
gqcli > tsk file_of_tasks
GoQat without the GUI
You might want to control GoQat by sending commands and tasks from an external source and then hide GoQat completely. To do this, you need to have the Xvfb virtual frame buffer installed. Start the frame buffer like this:
Xvfb :1 &
This tells the frame buffer to run in the background with display number 1. Then start GoQat like this:
GoQat --display=:1
GoQat will then start invisibly with its graphical output directed to display number 1 provided by the frame buffer X server (you can use a different display number for Xvfb and GoQat if you wish). But this isn't ideal because we can't see what GoQat is doing, although we could look at the log file. To interact properly with an invisible GoQat from a terminal window, we need to tell GoQat to monitor chosen files for incoming tasks and commands and to write its log window output to the terminal session. So we can start GoQat like this:
GoQat --taskfile /home/user/tasks --commandfile /home/user/commands --logtoterm --display=:1 &
or:
GoQat -t /home/user/tasks -c /home/user/commands -l --display=:1 &
Either of these commands starts GoQat as a background process sending its graphical output to display number 1. GoQat will monitor the file /home/user/tasks for incoming tasks and /home/user/commands for incoming commands, creating these files if they do not already exist. GoQat will send its log output to the terminal session. Then we can interact with GoQat via the CLI. Here's an example, where the CLI session is in blue and GoQat's response is in green. We start with a command to select INDI's 'Telescope Simulator' as the telescope driver on the Devices menu and then send a command to open the telescope link. After that we send a GoTo task to slew the telescope:
Some closing remarks about commands and identifiers
When you middle-click on a widget having selected 'Show widget commands' from the File menu, GoQat generally gives you the widget identifier and its current state (if applicable). If you sent the identifer and state to the file that GoQat monitors for incoming commands then this would be sufficient to set the selected widget to its existing state. But there are a few things to note:
- Option buttons (radio buttons) consist of a group of buttons of which only one can be selected at once. It isn't possible to de-select an option by clicking on it; this only ever selects that option and de-selects any others in its group. So if you middle-click on an option button, you might see 'optCCDHotPixelReplace 1' if that option is selected, but if it is not selected you will see just 'optCCDHotPixelReplace'. You don't see 'optCCDHotPixelReplace 0' because it isn't possible to de-select it with such a command.
- Some buttons open a dialog for you to choose a file name or location, for example the 'Load tasks from file...' button in the tasks editing window. Since there isn't any particular file or location set by default, you will see e.g. 'btnTLoadTasks /file-path/file-name'. In this case, you could send 'btnTLoadTasks /path/to/my/file' and GoQat will load the tasks from file 'file' in location '/path/to/my'.
- A few options are not so obvious: to select an entry from the list in the configuration settings dialog, enter 'trvSetting my comment', where 'my comment' is the content of the Comment field. Sending 'cviRect x y width height' will set the centre of the selection rectangle and its width and height in the autoguider Image window.
- Be aware that widgets in the INDI client interface have very long names, possibly containing spaces. For example 'txts_Telescope Simulator!EQUATORIAL_EOD_COORD!DEC! -12:08:13' will set the requested declination for the Telescope Simulator driver to -12:08:13.
- There are a few widgets that return nothing when you middle-click them. This is because they open dialogs that GoQat doesn't have any easy way of closing, e.g. the canvas font dialog from the Miscellaneous menu and the About dialog from the Help menu. So the user is not permitted to activate these with commands.