README for WX/sql v0.20B ------------------------ DESCRIPTION ----------- This distribution consists of essentially 3 modules: 1. COLLECTION DAEMON - This is the daemon that runs on the computer that is connected to the weather console. It collects the raw data from the console, and writes it to a MySQL database which can be local, or on a different computer. The collection daemon has been tested and works on both Win32 and Linux. 2. XML DATA PRESENTATION - This is a CGI program intended to run on a web server that has backend access to the MySQL database. When the URI is accessed, an XML document is returned which contains current conditions and some historical data such as daily max wind speed, daily and monthly rainfall, and list of the average barometric pressure for each of the previous 24 hours. 3. DISPLAY CLIENTS - WX/SQL currently has two display clients, one written in PERL which is a CGI program, and another that is a Java Swing application. They look approximately the same. The CGI program runs on a web server, and the Java application runs locally on any computer that will run Java, and is connected to the internet. Both flavors get their data from the XML URI. Both can be configured to display data from any WX/SQL XML server, so you can point them at different URI's anywhere on the internet, and display the data from there. 5. WEATHER UNDERGROUND DAEMON - This is a program that uploads current weather data to Weather Underground (http://www.wunderground.com) as part of their personal weather station data project. It is written in PERL. INSTALLATION ------------ MYSQL ----- MySQL is an open source relational database system available for download at http://www.mysql.com It is a client/server RDBMS that is very stable, and very widely used. I have used it for many projects, both commercial and personal. Here are the steps to install and configure MySQL for WX/SQL: 1. Download the appropriate distribution for your platform. Follow the instructions they provide for installation. It installs and runs nicely on both Windows and Linux/Posix. RPMs and other binary packages are available. 2. Start the database, and confirm that it running. 3. In the directory called "sql" in the WX/sql distribution, you will find a file called wxsql.sql. Change to that directory in a command window, and type: mysql -u root < wxsql.sql This will create a database called Weather, and will create all the necessary tables and indexes for WX/sql. If you have set a password for the MySQL root user during installation, you may have to type: mysql -u root -p < wxsql.sql You can create a MySQL user (schema) with grants for the Weather database if you desire. This is not necessary, but may be desirable for security reasons. At this point, the database server is ready to go. PERL ---- If you are going to run any of the modules on Windows, I highly recommend ActivePERL from http://www.activestate.com. It installs very easily, and makes it very easy to add the extra modules necessary for WX/sql via it's Perl Package Manager (ppm) program. If you are using Linux or other Unix, install PERL via whatever method you prefer. The following PERL modules are required: For the collection daemon: DBI DBD::MySQL Switch Win32::SerialPort (Win32 only) Device::SerialPort (Linux/Posix only) Win32 (Win32 only) Win32::API (Win32 only) Switch is included by default in most distributions including ActivePERL. Win32 and Win32::API are also included in ActivePERL. On Windows, you can use either CPAN or PPM to get the DBI and DBD::MySQL modules. PPM makes it very easy. You will probably need to get Win32::SerialPort from CPAN because I have been unable to find it with PPM. For Linux/Posix, CPAN is the way to go. For the CGI display client, you will need: DBI DBD::MySQL CGI GD For ActivePERL, everything is available via PPM. For the Java display you will need to have Java JRE installed. For the WU Upload module you will need: DBI DBD::MySQL CONFIGURING THE DAEMON ---------------------- Copy wxsqld.pl to some appropriate directory if you like. Open it in your favorite editor and do the following: 1. Make sure the first line which starts with #! contains the path to your perl executable. On Windows, this step can usually be ignored because Windows should recognize the .pl extension. 2. Comment and uncomment the appropriate sections for your platform. The defaults for $SerialPort should work in most cases, but may need to be modified in your case. Make $DeBug = 1 for the time being. 3. If you are running the daemon on the same computer that has your MySQL database, make $DBHOST = 'localhost' otherwise, put in the IP of the computer where you installed MySQL. NOTE! If your MySQL database is NOT on the same computer as the daemon, you may need to install the MySQL client programs on the daemon machine. 4. The $DBNAME should be 'Weather' if you used wxsql.sql to set up your database. 5. $DBUSER is either the special user name that you added to MySQL, or 'root'. By default, use 'root'. $DBPASS will be either the password that you have set for the database user, or '' by default if you did not set one, including for 'root'. TESTING THE DAEMON ------------------ Open a command window. Change directories to wherever you put wxsqld.pl. Type wxsqld.pl (or ./wxsqld.pl on Unix). If your weather console is plugged into a serial port (Oh yeah! Forgot about that!), you should start seeing debug output as the sensors report in. If the daemon is not configured for the correct serial port, you will see nothing. Hit Control-C, and edit $SerialPort. Try again. If you get MySQL errors, check the MySQL documentation to see what's going on. You may have to modify some grants. If you see the data flowing, then you are golden. You can just let it run in the window forever, but I don't recommend that. I recommend that you change $DeBug back to 0 to save log space. It will still log errors regardless of the setting of $DeBug. If you are running under Windows, I highly recommend a product called FireDaemon (http://www.firedaemon.com). The free version works fine for wxsqld. Install it, then under the "Program" tab put "C:\Perl\bin\perl.exe" in the Executable box, or whatever is appropriate for your PERL installation. In the "Parameters" box, put "c:\dev\wxsqld.pl", or wherever you put wxsqld. Under the "Settings" tab, choose "Hidden" under "Show Window", "Automatic" in the "Start-Up Mode" box, and "Restart the Program" in the "Upon Program Exit" box. In the "Advanced" tab, stick a full path to a file you want logging to go to, and click "Capture Strerr in Stdout". Hit "Install", and wxsqld will autostart at boot time, run in the background, and never bother you again. CONFIGURING THE XML CGI MODULE ------------------------------ The XML module should run on any web server that supports standard CGI. 1. Copy wxsql2xml.pl to your web server's cgi-bin directory. 2. Open wxsql2xml.pl in your favorite text editor. Under MySQL setup, change $host to the name or IP address of your MySQL server. The $database should always be "Weather", unless you changed it during the MySQL setup. $username and $password should correspond to however you configured your MySQL access. 3. Change the @sensors line so that it contains a comma separated list of the sensor numbers that you own, based on the supplied legend. The %sensor_name array consists of the same sensor number, followed by your preferred name for that sensor (quoted), followed by the next sensor number, etc. 4. Convert to sea level pressure - this is the value in MB used to adjust the barometric pressure reading at your location so that it reads sea level pressure. 5. Site Name - This string is included in the XML document, and is displayed by the display clients. TESTING XML CGI MODULE ---------------------- Access the XML doc by entering http:////wxsql2xml.pl - the XML document should display (assuming you have data in your database of course). The default units are metric. To convert to English units, http:////wxsql2xml.pl?units=1 If it doesnt work, a resonable error will be displayed, or you may have to check your servers error log. THE PERL CGI DISPLAY MODULE --------------------------- The display module consists primarily of two CGI programs: wind-dir-s.pl and wxsql-display-x.pl, both of which are in the cgi-bin distribution directory. wind-dir-s.pl is used solely for generating the wind display graphic. It does not query the database, it accepts parameters from the script that calls it, and generates a transparent background PNG image of the wind data. This is the script that requires the GD module, as it is used to create the image. This script requires no configuration. wxsql-display-x.pl accesses the WX/SQL XML URI, and displays the data. The display will auto-refresh about every 15 seconds with updates on all values. Configuring wxsql-display-x.pl 1. Copy the contents of the html sub directory to your web server's HTML document root directory, including the images directory. 2. Copy wxsql-display-x.pl and wind-dir-s.pl to your web server's cgi-bin directory. On Unix, make sure they are executable. 3. Open wxsql-display-x.pl in your favorite editor. 4. Make sure the #! line contains the path to your local PERL executable for Unix OS's. 3. Change the default XML doc to the full URI of your WX/SQL XML document (or anyone elses for that matter) - remember to add the ?units=1 param to the URI if you want english units. 4. Change the colors, if you like. 5. Change the refresh rate if you like, but keep in mind that the shortest update period sent out by the WMR-868 sensors is 10 seconds for the wind sensor. That being the case, anything less than 20 seconds should show the newest wind data every time. Too short a period creates an annoying display. 6. Access http:///cgi-bin/wxsql-display-x.pl via a web browser. Note that you can also specify a different XML source from your browser, such as: http:///cgi-bin/wxsql-display-x.pl?xml_doc=http://wxsql.darktech.org/perl/wxsql2xml.pl You really should urlencode the xml_doc param... I have included some examples of how to include the display in a web page in the html distribution directory, if you want to go beyond using it standalone. Putting it in an IFRAME container works nicely with the auto-refresh. THE JAVA CLIENT --------------- The Java client is pretty easy to use, and it works great as a Java Web Start application. I have included a sample .jnlp file. See http://java.sun.com/products/javawebstart/ for more info on Java Web Start. 1. Install the Java JRE - http://java.sun.com/j2se/downloads/index.html 2. If you have a web server and want to use JWS, put wxsql.jar and wxsql.jnlp in your servers document directory. Otherwise, you only need to put wxsql.jar someplace. 3. To run it directly from the command line (any OS): java -cp wxsql.jar DisplayWXSQL http://wxsql.darktech.org/perl/wxsql2xml.pl 1 Change the last param to 0 if you want metric display. Change the URI to whatever WXSQL server you want to access, but if mine is up, it should work. 4. If you want to use JWS, edit the wxsql.jnlp file. The section gets displayed during the JWS startup. In the section, there are 2 s - the first is the URI of the XML document, and the second is the units, 1 for English, 0 for Metric. 5. Access it via JWS by entering http:///wxsql.jnlp and JWS takes care of the rest. THE WU UPLOAD MODULE -------------------- Once you get everything else working to your satisfaction, you may want to upload your data to Weather Underground. They make some really cool graphs out of it for you. Go to http://www.wunderground.com and sign up to be in the data exchange. You will need your Weather Underground station ID to proceed. Configure WU upload ------------------- wxsql2wunderground.pl is located in the daemon directory. It can be run anywhere that has the required PERL stuff installed, and has access to your Weather database. Here are the steps to get it running. 1. Pick which sensor you want to be used for your outdoor temperature data. You will probably want to use sensor 1, if you own the OS solar powered sensor. Set the $outdoor_sens variable to that number. 2. Change the MySQL variable to values appropriate for your installation, as described above. 3. Change the Wunderground variables to reflect your Wunderground ID and password. The URL should work as-is. 4. Execute the program in a command window. You should get back a timestamp, and the word "success", or an appropriate error which should be self explainitory. 5. I have included a Linux init script that works with RedHat - wxsql2wud.