The home page for RTGUI+S is at http://www.rtgui.com.
This document was last updated Aug. 28,
2015, for Release 10. Starting with Windows 7, Microsoft has
changed the way scripts are run, using the new Power Shell. See the
notes at the end.
The latest version of this document is on-line at scripting.RTGUI.com
.
This software may be freely distributed and copied for non-commercial personal use, provided that the program and the documentation are not modified in any way. Donations are accepted via Paypal to support the author's development of this and other software. This program may not be sold, and is provided without any guarantee or warrantee whatsoever. Use this program at your own risk. You should watch your telescope carefully whenever it is in motion, and stop it immediately if any problem is detected. The author is not responsible for any possible equipment malfunctions or injuries caused by this software, or by careless use of mechanized telescopes. Do not utilize "Goto" functions in the daytime to avoid the danger of permanent eye damage from slewing in the vicinity of the sun. Do not attempt to observe the sun unless you are using a proper commercially-manufactured solar filter.
Getting Started: This document does not attempt to describe the features or use of RTGUI. It assumes that the user is already familiar with the operation of the program. If not, information about the program, as well as the program itself, can be found at http://www.rtgui.com .
The following parameters must already be set correctly before any RTGUI+S scripts can be run:
Parameters stored in RTGUI.HOM: The observer's latitude; the observer's longitude; the specific type of Goto telescope; the Com port connected to the telescope .
Other parameters: The Windows time zone must be correctly set. The clock in the PC should be set as accurately as possible, preferably using an accurate internet time source.
Scripting for Automated Operation: Starting with Ver. 5, RTGUI is now RTGUI+S. It accepts command-line parameters for most major functions. This allows scripts to be written for completely automated operation of telescopes, for observing or research projects using cameras or other instruments. Because RTGUI+S offers scripting commands to perform certain tasks at certain times, you can create script files to perform automated tasks at designated times, or perform repetitive functions indefinitely. Windows also has capabilities to run command files at various times. Usually the reason for writing such a script is to automatically position the telescope to some object in a catalog, to a planet, or to a specified RA and DEC.
If you are unfamiliar with Windows Batch or Command scripts, there is a lot of information about them on the Web. Microsoft provides a good introduction at http://www.microsoft.com/resources/documentation/windows/xp/all/proddocs/en-us/batch.mspx . This information also generally applies to other versions of Windows, Windows NT, and Windows 2000.
In addition to Windows command scripts, you can also use Visual Basic scripts, Java Scripts, Perl Scripts, Delphi Scripts, or any other script programming language to control the operation of RTGUI+S.
Command Line Parameters: These commands are passed to RTGUI+S as command-line parameters. This may be done using a DOS command line in a DOS box, by executing a Batch file (extension .bat), or by executing a Command File (extension .cmd). Example: rtgui command1; command2; command3; command4 . They can also be passed to RTGUI+S as a string from a scripting language such as Visual Basic or Delphi.
General Syntax and Operational Rules:
All commands must contain an "equal sign". Any command that does not contain an "equal sign" is invalid.
Commands must be terminated by a "semicolon", except for the very last command. The "semicolon" must immediately follow the last character of the command, with no spaces between them. Commands may have one or more spaces preceeding them, following the previous "semicolon". (Indeed, brief notes or number sequences may precede them.)
RTGUI+S will automatically exit when the last command has been performed. The error level is set to zero. However, if RTGUI+S encounters the command stay=ok, it terminates further command processing, and stays resident. It may then be used in normal GUI fashion.
RTGUI+S terminates upon encountering any error preventing the execution of any command. The error level is set non-zero upon termination.
All commands are written to the observing log RTGUILOG.TXT, whether successful or not. The status of the command is indicated, "successful" or "error". In most instances the type of error is indicated. Commands that involve waiting or suspending for time intervals are written twice, once at the beginning of the interval and once upon its completion. Whenever a command does not behave as you expected it to, consult the log.
The GUI features of RTGUI+S cannot be used while commands are being processed, including when the program is suspended or waiting. The forms of RTGUI+S are mostly hidden during this time, although they may be briefly visible.
Commands are not case-sensitive.
Commands longer than 40 bytes will be truncated, resulting in an error.
The maximum number of commands in this version is 25. However, command loops make it possible to execute any number of repeated operations.
Return Codes (ErrorLevel): RTGUI+S returns the following values when it exits after processing commands. This is the same as the errorlevel in a DOS command file.
0: Normal termination. No error has occurred.
1. There is no error, but command processing cannot continue. Examples: the exit time has occurred; we have reached the end of the list of matching objects. Check the log rtguilog.txt .
2. Some error has prevented a command from being executed. Either a command is invalid, or it cannot be executed at this time. (Example: goto an object that is not visible; find an object that is not in the current catalog.) Check the log rtguilog.txt .
How do I coordinate My Camera with RTGUI?
Basically, there are two ways to coordinate telescope and camera:A: One of the Scripting commands RTGUI understands is a "Shell Execute" command, which allows you to run any other program. If you have a program (or command file or script file) to control your camera, you give RTGUI a command line that tells it to go to an object, then use shell= to issue commands to your camera. You can repeat command sequences in a loop, so you can do many different objects in a single command with this approach.B: Write a Script in a higher-level language such as VBasic, Perl, Java, Delphi, etc. An example is given below of a tested and working Visual Basic script to move the scope northward along a line of R.A., at one degree intervals. In this instance, you give RTGUI just a single task, to move the telescope to a position. After RTGUI has done this, your script issues commands to your camera.
Description of Commands: RTGUI+S can perform the following Command-Line Functions (which must be entered exactly as shown). Each command must be terminated with a semicolon when other commands follow it.
Object Selection Commands
cat=
Changes the catalog. Example: cat=marathon.rtg . This allows objects to be selected from any catalog. The catalog extension .rtg must be specified. If this command is used, it should precede any "find". The catalog directory cannot be changed, however it is possible to select catalogs in other directories, relative to the current directory. For example, if the RTGUI directory is \astro\rtgui and the catalogs are kept in the directory \astro\rtgui\catalogs , it is possible to select a catalog in that directory using cat=catalogs\ppm.rtg . To avoid errors it is best to keep your catalogs either in the RTGUI directory, or in a directory immediately below it.
If the catalog selected is a Transient Catalog (asteroid or comet positions), RTGUI automatically selects the correct position for the current time; hence, no find is necessary. The following script will point the telescope to the asteroid Vesta: rtgui cat=TransientCats\vesta.rtg; goto=ok (A transient catalog containing currently-valid positions for the asteroid Vesta must already have been created using Get Comet/Asteroid. If that is not the case, or if Vesta is not visible at the time this is run, an error will result.) The catalog file name specified must exactly match the transient file name as displayed in the scroll box on the Get Comet/Asteroid form. In the case where the object is a comet, the backslash in the object name is replaced by a dash (DOS/Windows will not accept a backslash in a file name, while the Minor Planet Ephemeris Center requires it in the object name of a comet.) A script to position the telescope to a comet will look like this: rtgui cat=TransientCats\2P-Encke.rtg; goto=ok
find=
Finds an object in the current catalog. Example: find=vega . The search operation is executed immediately when this command is processed. If the object is not found, an error occurs and command processing terminates. If minimum altitude (minal) is specified previous to the find, that parameter will be applied. If minimum magnitude (minmag) is specified previous to the find, that parameter will be applied. If a second name to be matched (name2) is specified previous to the find, that parameter will be applied.Otherwise, name matching for only the specified name will be performed.
minal=
(This command requires the use of RTGUI Ver. 9.3 or later.) Optionally specifies a minimum altitude in degrees for objects in a search. Example: minal=35 . When minal is specified before a find or match, objects below this altitude will be ignored. Decimals are OK. Applies to all subsequent find or match operations. Can be modified during a search. RTGUI+S will not goto objects that are not at least one degree above the horizon.
minmag=
Optionally specifies a minimum magnitude for objects to match in a search. Example: minmag=11.5 . When minmag is specified before a find or match, objects fainter than this will be ignored. Applies to all subsequent find or match operations. Can be modified for subsequent searches. Decimals are OK.
name2=
Optionally specifies a second name that is to be matched in a search, in addition to the name specified in the find command. Example: name2=hercules , this will limit matching objects to those whose catalog entry contains the text hercules. The default value for name2 is the null string. If name2 is used it must precede the find command, because the search takes place as soon as the find command is processed. name2 may be changed for subsequent searches, or eliminated by setting name2=; .
match=
Finds the next object in the catalog (if any) matching the search criteria. Example: match=next . This is the same as pressing the "Next Match" button on the GUI interface. After the last matching object has been found, the match command will fail, command processing will cease, and RTGUI+S will exit.
planet=
Finds one of the major planets, Sun, or Moon. Example: planet=6 . 0=Sun, 1=Mercury, 2=Venus, 3= the moon, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto. (Pluto remains for sentimental reasons, since its code was implemented before its demotion to a dwarf planet). To find a minor planet (asteroid) or comet, just load its Transient Catalog: see the Cat command.
2000ra=
Selects the position of an object in terms of RA and Dec for a given epoch. Example: 2000ra=03h14.55m, dec=+14d03.2m . The epoch of the position must be specified as the first four characters of the command. If there is no sign specified for the dec, it will be assumed to be positive (north). The epoch may be any year from 1800 to 2200. RTGUI+S will automatically precess the coordinates to the current epoch. If the epoch of a position you want to examine is not stated, in most cases you should use the current year. The first name of the object will be set to a string describing its RA, the second name describes the Dec, the third name gives the specified Epoch, and the fourth name the Command Number that specified it.
alt=
Selects the position of an object in terms of its current altitude and azimuth. Example: Alt=15d30m, Az=180d00m . The first name of the object will be set to a string describing its Altitude, the second name describes the Azimuth, and the fourth name the Command Number that specified it. Because RTGUI only positions telescopes in terms of RA and Dec, the specified Alt/Az will be converted to whatever RA and Dec correspond to it at the time the command is processed. Any subsequent Goto will be directed to that RA/Dec.
Execution Time or Sequence Control Commands
wait=
Tells RTGUI+S to wait until the specified time until performing the next command. Example: wait=03:30:00 . This is local time, not GMT. All RTGUI+S activity will be suspended until the Windows clock reads the specified time. May be optionally preceeded by the date command to cause RTGUI+S to wait until a particular time and date. The format for the time is hh:mm:ss or hh:mm (in which case the seconds will default to "00"). h:mm:ss or h:mm is also acceptable. The hour must be a number from 0 to 23.
date=
Optionally used in conjunction with the wait command, specifies a day of the month on which the wait command is to wake up. Example: date=13 . If date precedes wait, then the next command after the wait is performed when time and date both match. When date is not used, only the time needs to match. When date is set, each subsequent wait will refer to that date. Two or more date commands may be used in the same command line to cause some tasks to be performed on one date, and others on a later date. This command can be used to schedule an action to take place at any time during the next month. An unusual case: if date=30 is set on January 31, then a subsequent wait statement will not awaken until March 30.
sleep=
The number of seconds to 'sleep' before performing next command. Example: sleep=10 . Decimals are OK. The number specified must be greater than zero, and less than 86400 (24 hours). In actuality, the time specified is a minimum delay, as processing delays within RTGUI+S and within Windows will result in aslightly longer delay than what is specified.
command=
Controls the sequence in which RTGUI+S commands are executed by allowing you to "go to" a particular command number. Example: command=2 . This makes it possible to establish a control loop of commands, for example, to repeatedly find matching objects. The first command is numbered as 1.
exit=
Specifies a time after which command processing will cease. Example: exit=05:30 . This represents local time, not UT. exit=5:30 is also acceptable. Typically this command is used to terminate command processing before the sky gets light. Before each command is processed, RTGUI+S checks the time, and if the specified time has been reached, it exits. Because other commands may result in periods of wait or sleep, there is no guarantee that any command will be executed at the specified time, and therefore there is no guarantee that the operations will terminate at exactly the given time. For example, if the exit time is specified as 05:30, it is possible that no command will be executed until 5:45, or indeed until after 6:00. Therefore, if RTGUI+S detects a time that is equal to or later than the exit time within that same hour, or within the three hours following it, command processing will cease. If an exit time of 5:55 is specified, then the exit will occur if any command is processed between 5:55 and 9:00. If no command is processed in that interval, command processing will continue.
shell=
Causes the execution of some other program, perhaps to control some device such as a camera. Example: shell=CameraControl p1 p2 p3 . The program invoked might also be a command script. Everything following the space after the program name is passed to the program as a Command Line parameter. Because RTGUI+S executes its commands in a predictable sequence, this command can be used to control other devices in a manner that is coordinated with telescope control (for example, the camera will take an image each time that the telescope reaches a new position). RTGUI+S does not wait for the execution of the other program to complete. Unless Windows indicates it is unable to execute that program, RTGUI+S immediately moves on to the next command.
goto=
causes the telescope to Goto currently-selected object or position. Example: goto=ok . This has the same effect as pressing the "Goto" button on the GUI interface. If there is no currently-valid selected object or position, or if the selected object is not at least one degree above the horizon, this will cause an error. If no goto telescope is selected, this will be an error. If a Goto scope of telescope type 3 is selected, this is also an error, because those scopes are not capable of operating without user intervention to press buttons on the hand controller. Note that this command completes immediately, and does not ensure that the telescope is already in position upon completion (indeed, with Meade telescopes there is no software command to determine whether the slew is completed). Therefore before issuing any camera commands, you should issue a sleep command sufficient to ensure that your telescope is in position (Example: sleep 60).
stay=
Tells RTGUI+S to stay resident when command processing is finished - otherwise it terminates. Example: stay=ok . If "stay" is used it will be the last command executed. RTGUI+S then goes into normal GUI operation.
Miscellaneous Commands
sky=
Invokes the Skycharts program (Cartes du Ciel) to produce a sky chart centered on the selected object. This is the same as pressing the Skycharts button from the GUI interface. An object must be selected before invoking the sky command.
Command Examples:
Some examples of a command file using some simple commands might be:
c:\astro\rtgui
rtgui cat=ppm.rtg; find=SAO12345; goto=ok
The above commands change the directory to the one in which RTGUI+S is located, change the catalog to PPM.RTG, locate the star SAO12345 in that catalog, then have the telescope Goto that star.
rtgui cat=wds.rtg; stay=ok
Place the above commands into a file named rtgui.bat . You create a shortcut to this file instead of to RTGUI itself. This will cause RTGUI to start up normally, except that the default catalog will be the Washtington Double Star catalog.
rtgui planet=5; sky=ok; goto=ok
Selects the planet Jupiter, invokes the Skycharts program to produce a star map centered on Jupiter, then commands the telescope to Go To Jupiter.
rtgui 1. name2=virgo; 2. find=galaxy; 3. goto=ok; 4. sleep=300; 5. match=next; 6. command=3
The above command loop uses optional command numbering to better illustrate the logic. It tells RTGUI+S to select each galaxy in the constellation Virgo listed in the current catalog, one at a time; then make the telescope Goto that galaxy. RTGUI+S then will sleep for five minutes, and move on to the next matching galaxy. Should the match command fail to find another matching result, this causes an error and terminates the loop. It may also be appropriate to specify one or more of the following: a minimum altitude for the object, a minimum magnitude, or an exit time when the sky begins to get light.
Visual Basic Scripting Example:
The following is a Visual Basic Script to be run under Windows that takes as input parameters a position in RA (hours and minutes). It starts on the equator at the specified Right Ascension, then moves the telescope northward one degree at a time, pausing to image at each position. When 90 degrees north has been reached, it exits.
' Windows Visual Basic Script - northward.vbs . Use 'cscript' to execute
' Must have two input arguments: Hours and Mins of RA.
Set WshShell = WScript.CreateObject("WScript.Shell")
set args = WScript.Arguments 'The command line arguments passed to the script
rahour = args.Item(0) 'First argument: hours of RA
ramins =
args.Item(1) 'Second argument:
minutes of RA
For degr = 0 To 90 step 1
runstring = "RTGUI.exe
2005ra = " &
rahour & "h" & ramins & "m,
dec = " runstring= runstring & degr &"d00m;
goto = ok; sleep=60" ErrorLevel=
WshShell.Run (runstring,1,TRUE ) 'shell execution of RTGUI+S '"TRUE"
means wait for RTGUI+S to finish, & pick up error level if
(ErrorLevel > = 2 ) then
MsgBox("RTGUI+S Error, ErrorLevel = " & ErrorLevel)
WScript.Quit(ErrorLevel) 'error, must quit
elseif (ErrorLevel = 1 ) then
exit for 'no error, but we're finished
end if
'Insert camera command here to begin exposure
Wscript.sleep 600000 'wait for camera tasks
'Remember that in VB scripts, "sleep" is in miliseconds
'Insert camera command here to end exposure & save image
Next
WScript.Quit(0) 'Normal completion
Paste the above script into a text editor such as Notepad, and save it as northward.vbs in the directory where RTGUI+S resides. Open up a command shell ("DOS box"), go to that directory, and enter cscript northward.vbs 12 30 . This will cause the telescope to gradually crawl northward at one-degree intervals, along the line RA=12h 30m (or choose some other RA that is presently visible). Southern Hemisphere observers can of course modify the script to make it go the other way. You can modify this script to make it do a lot of different things; you probably will not need more complicated scripting than this for RTGUI+S. Of course, other scripting languages can equally well be used to accomplish the same thing.
Miscellaneous Notes on RTGUI+S Scripting:
Donations Accepted: The use of RTGUI+S is free to all noncommercial users. However, if you feel that you have received significant value from it, you may want to make a donation to the author to support the development of this and other software, especially when you consider how many commercial astronomy programs sell for $50, $100, or more. The "donations" button near the top of this file allows you to make a contribution from your Paypal account or from a major credit card, in any amount.
Please report to me any comments you might have on RTGUI+S, or any problems you may find with it.
Robert Sheaffer
Lakeside, California
Notes on Running Scripts on Windows 7 or later
Starting with Windows 7, Microsoft has changed the way scripts are run, using the new Power Shell. Dave Gary posted the following instructions on using Power Shell scripts to the RTGUI Yahoo Group:
Set PowerShell's Execution Policy
PowerShell is secure by default. The first implication of this philosophy is that PowerShell won't execute scripts until you explicitly give it permission to do so. PowerShell has four execution policies that govern how it should execute scripts:
Restricted: PowerShell won't run any scripts. This is PowerShell's default execution policy.
AllSigned: PowerShell will only run scripts that are signed with a digital signature. If you run a script signed by a publisher PowerShell hasn't seen before, PowerShell will ask whether you trust the script's publisher.
RemoteSigned: PowerShell won't run scripts downloaded from the Internet unless they have a digital signature, but scripts not downloaded from the Internet will run without prompting. If a script has a digital signature, PowerShell will prompt you before it runs a script from a publisher it hasn't seen before.
Unrestricted: PowerShell ignores digital signatures but will still prompt you before running a script downloaded from the Internet.
To display the current execution policy, you need to enter the command
Get-ExecutionPolicy
at a PowerShell prompt (which will look like PS C:\> assuming the current location is C:\). To set the execution policy, enter the command
Set-ExecutionPolicy policy
where policy is one of the policy names (e.g., RemoteSigned). I used Unrestricted.
Setting the execution policy requires administrator permissions for the PowerShell application.
I found the Windows PowerShell application, right-clicked the application, hit "Properties" and selected "Run as Administrator". Then I set the execution policy after starting the application.
Ok, assuming the PowerShell application has the proper settings, you can now run your RTGUI script in Windows 7. The following is an example script. It's easier (for me) to set the path for PowerShell if the scripts folder resides within the folder where one keeps RTGUI (usually on the C: drive).
Here's one of my scripts "Find Caldwell Object" that resides within the "RTGUI Scripts" folder within the "rtgui" folder on my C: drive. The script has been altered to run within PowerShell with an Unrestricted policy attribute set for the PowerShell application.
c:\rtgui\rtgui scripts\find caldwell object minal=30; minmag=10.0; find=Caldwell; goto=ok; sleep=100; match=next; command=4
Finally, I've found that if you want to end a script before it completes, merely closing the script window does not exit the scripting process under Powershell as it did with the old Windows Command-Line protocol. One must go into the Windows Task Manager (alt-control-delete), choose "Start Task Manager", go up to the "Processes" menu item and select it. Then scroll through the processes list and select any process that has "rtgui" in its name. Select item/items and tell Task Manager to "End Process". This should end the script.
Hope this helps. If anyone has an easier way to do this please post your solution. I'm all in for easier.
Dave Gary