|====================================================| | This is the install file for the Astrotron project | |====================================================| |PD - PD - PD - PD - PD - PD - PD - PD - PD - PD - PD| |====================================================| | Astrotron and all the files I include with it are | | given by me, fyngyrz, to the public domain. Enjoy. | | You can do whatever you want with this. If you | | improve it, of course I'd love to hear about it, | | but there's no requirement to tell me. | | | | Everything in the archive as I distribute it is my | | original work. | | | | Thanks to Deb for putting up with my fascinations. | | | | Thanks to Brandon Craig Rhodes, who worked with me | | to get ephem cooking in the old RH9 / early python | | environment. | | | |====================================================| | File formatted for 80 columns using tabstops of 4. | |====================================================| | PD code by fyngyrz v1.0.H http://fyngyrz.com | | June of 2010, at Glasgow, Montana, USA, Earth, SOL | |====================================================| Astrotron Installation: ======================= Prerequisites: -------------- Zeroth: You'll need to be able to use the 'su' command if you don't already have PIL and/or ephem installed. On the Mac, by default, you can't do this. In order to allow the su command to work, you need to enable the root account. Here's a good resource to get that handled: http://www.spy-hill.com/~myers/help/apple/EnableRoot.html First, you need PIL if you don't already have it. Download it from the above link, set the BUILDME script to be executable, then run it. Then su to root and in the PIL install directory, run "python setup.py install". If you don't know if you have it installed, don't worry, the install process is going to tell you. You can get PIL here: http://www.pythonware.com/products/pil/ Second, you need ephem. Download it from the link above if you don't already have it. Then su to root and in the ephem install directory, run "python setup.py install". If you don't know if you have it installed, don't worry, the install process is going to tell you. You can get ephem here; http://rhodesmill.org/pyephem/index.html Third, your *nix system has to incorporate a working webserver. Make sure you can edit files in the directory the webserver serves, and that you can see the changes in those edited files using a web browser with the URL set to point at those files. Please be aware that I can't help you get your webserver working, but even so, you cannot proceed until you get this resolved. Seek help from experts with your particular OS flavor. And, as I say, your OS needs to be OS X or linux (or maybe even unix); the scripts use various common *nix commands such as wget, mkdir, chmod, ln, rm, mv, cp and so forth; Astrotron is really unlikely to work under Windows unless you have some kind of very *nix-y environment up and running underneath everything else. Even so, you're on your own there. Sorry. I've a low tolerance for Windows. Fourth, your system has to have the "wget" command available. You can obtain wget here: http://www.gnu.org/software/wget/ NOTE: As a security measure, I strongly suggest you make a copy of wget named something really weird (ex: puntajabba [DON'T use that, just use something similarly ridiculous]) and use it that way by entering the wackily renamed wget as the wget command in the astrotron.conf file. Then set the execute permissions on the actual wget command to root only. This prevents wanna-be hackers from using wget, because they can't find an executable copy. Again, strongly suggested. But it's your call. Installing Astrotron -------------------- There are 14 (very basic and easy) steps to this process. You need to perform them in the specific order presented because one thing depends upon another, etc. PLEASE follow the directions; "technical support" is limited to hollow laughter. Ok, you can email me using [fyngyrz at gmail dot com], and I might be able to help, though I will still probably be cackling quietly at your discomfort. 1) You can be logged into your machine as your own user, root should not be required. Although root will also work, so whichever you prefer. There are no third party web security issues with permissions on the Astrotron scripts, because web visitors to the astrotron.html page don't run, control, feed input to, or have any other kind of access to the code if you install as directed. Open a command line shell. 2) BEFORE you start, you need to be CD'd to the directory where you want the astrotron dir to be created. The gunzip / tar extraction will CREATE the dir, and a subdir, and so you'd better be CD'd to exactly where you want the astrotron dir created when you do step #3!!! 3) extract the goodies: a] gunzip mastrotron-1.0.H.tar.gz b] tar -xvf mastrotron-1.0.H.tar 4) Let's say you were CD'd to "~/src" when you did step 3. There is now a directory "~/src/astrotron" which contains the project files. CD into there directly: cd astrotron 5) Run the "envtest.py" script... ./envtest.py ...and see what it tells you about the PIL library, the ephem library, and the wget command. If you need to install any of the three, go get that handled before you go on to the next step. Install whatever you need to, cd back to this directory (~/src/astrotron for example) and run envtest.py again until you get results like this: PIL library is installed. ephem library is installed. wget location: /usr/local/bin/wget Make a note of exactly what envtest.py tells you about the location of the wget command in your filesystem (/usr/local/bin/wget in the above example); you're going to need that information shortly. 6) Determine the elevation (in meters), the latitide, and the longitude for your observing location. Make a note of these three values. Negative numbers are west and south, respectively; also, FYI, the format we're interested in is... degrees:minutes:seconds ...see my location in astrotron.conf for an example. TIP: Have your lat/long in decimal format? Here's how you get DMS: Say you have a latitude of 48.5503; the 48 portion is the degrees value. Now multiply by 60 using only the fraction (.5503 x 60), which gives you 33.018; 33 is the minutes value. Now multiply by 60 again using only the new remaining fraction (.018 x 60), that gives you 1.08, which is the seconds value. So your latitude is then "48:33:1.08", or 48 degrees, 33 minutes, 1.08 seconds. In simple form: a) 48.5503 (D=48) b) .5503 x 60 = 33.018 (M=33) c) .018 x 60 = 1.08 (S=1.08) d) DMS = 48:33:1.08 7) Edit the file "astrotron.conf" and change the elevation, latitude and longitude to the values you just collected. If you're located outside the USA, then also set the weather variable to 0 (US weather services don't supply data outside the borders of the country, sadly.) Don't save the astrotron.conf file yet. 8) Set opath. Your web server is serving pages from somewhere in your filesystem. I can't imagine where. :) But let's say it is... /usr/www/mysite/htdocs ...and in there is where you plan to put the astrotron.html page. So in that case, you would edit the "opath" variable so it matched the above, but with a '/' on the end: opath /usr/www/mysite/htdocs/ You're also going to need a subdirectory here for the images. It can be named anything reasonable. I use astpicsdir, and the OS X webserver serves pages from the Sites directory in my user home, hence, my settings are... opath ~/Sites/ # Web dir subdir astpicsdir/ # location for images (no leading '/') ...now, "~/Sites/" has to already exist, but the subdir will be created if possible (I hope it goes without saying that the user you logged in as needs read/write permissions to do this!) I do recommend that you use a new dir dedicated to astrotron's files, as there are quite a few files and they aren't named in a particulary useful manner -- they'll clog up your normal images or pics dir if you put them there. 9) Edit the variable "wcmd" and put the location of the wget command you learned in step 5 into it. And you'd use the name that replaces wget if you've followed my little security tip. Now you can save the edited astrotron .conf file. 10) While still CD'd to the astrotron directory, execute the "makelinks.py" script... ./makelinks.py ...this creates the subdir you specified, puts softlinks in it to the actual files (in /tmp), generates the doall.py script, and generates the astrotron.html and astrohelp.html files into the location specified by the opath variable, modified appropriately to reflect your choice of image subdir, your location, weather features, and so on. 11) Add a line to your crontab that will fire off the "doall.py" script every five minutes. cron table formats vary, so I have to leave this up to you for the most part. Here's how my OSX cron is set up, which I did using "crontab -e" just FYI... 4,9,14,19,24,29,34,39,44,49,54,59 * * * * /Users/MyUsErNaMe/src/astrotron/doall.py >~/dump.txt ...note that the given path isn't "~/src..." etc., instead it's a full path. that's because tilde expansion is NOT an OS feature, it's a shell feature, and cron doesn't necessarily know about shell features. You can use tilde expansion in this project, in the path variables, because I do the tilde expansion for you. But (probably) not in cron. And of course, this sample needs to be edited with your ACTUAL path, even if you are using the same cron (my cron came with OS X 10.5 Leopard.) 12) Go to your web browser, try to look at astrotron.html, and see what there is to see. If things don't look right, etc., then one of the above steps was skipped or done incorrectly. Start over. If it looks right, but doesn't update, then the cron job is not running correctly (and user root will probably be getting some email fom cron.) 13) Advisory only: Since the cron line I show causes data to be captured and processed at the 4 and 9 minute points along each hour's timeline, the best time to refetch the page would be at the 5 and 10 minute points along each hour's timeline. Put another way, since the astrotron page automatically refreshes itself every five minutes, just initially load the page at any multiple of five minutes (0,5,10...), and you should be displaying the latest data that's been converted into astrotron dials, graphs and images a minute previous to the page fetch(es.) The reason I tell you this is that auroral activity is very dynamic; substorms can come and go very quickly, so you really want to know just as soon as possible that they are, or may be, happening. 14) There are two more settings, chairx and chairy, in the .conf file that are of immediate interest. These place a crosshair on the auroral polar map, the idea being that you put the crosshair where the latitude and longitude settings are, and in this way, it becomes very easy to see if the auroral intensity oval is overhead at your location. To disable the crosshair, you can set these to 0. You'll have to do some fooling around with the values and observing the results to get them just where you want them. Each time you change them, manually run the aur_getpol.py script... ./aur_getpol.py ...then refesh the astrotron.html web page to see the changes. When you've got it right, you're done -- they'll be included on the polar map from then on. Here are some starter settings for selected northern US states that should give you a starting point for your own location: X Y --- --- Washington 68 162 Montana 80 167 North Dakota 90 169 Over the US, an increase in X moves east; an increase in y moves south. About the weather feature ------------------------- Note that if you turn the weather feature off by using the 0/1 flag in the astrotron.conf file, to actually reset the install, you'll need to cd to the astrotron project directory and run makelinks.py again... ./makelinks.py This removes the weather dial images from the HTML page. Otherwise, if they were on previously, they'll just sit there unchanging (unless you turn the weather back on.) So why would you do this? Two reasons. First, if you're not in the US: the US National Weather Service provides weather reports strictly for the US. Sorry about that. Ideally, you turned off the weather during the initial installation in that case, because you'll get some unhappy behaviors otherwise. But you can resolve them by turning off the feature and re-running makelinks.py. Second, because according to the NWS, the weather XML availability is, and I quote, "experimental"; that means it could stop working at any time in the particular way it works now, breaking the weather support in astrotron until / unless I can deal with the new format, presuming, of course, that there *is* a new format and that they have not abandoned the digital weather data project entirely. So if the weather reporting gets really weird or you start getting emails from cron complaining about parsing the weather or the XML file... set weather to 0 in the astrotron.conf file and let me know (I probably already do, because if the NWS parsing doesn't work for you with US lat/long settings, it won't work for me either.) I'll do what I can to fix it.