
Copyright (C) 2006 Jim Chandler <jim@n0vh.org>
Portions Copyright (C) 2004 Bruce Bennett <bruts@adelphia.net>
Portions Copyright (C) 2000-2018 The Xastir Group
(Modified for the Xastir project under GPL license)


LaCrosse WS-23xx Weather Station support for Xastir - open2300db2APRS


OVERVIEW
--------

This is a bridge utility between "open2300", a LaCrosse Weather Station 
data storage & display application by Kenneth Lavrsen (see 
http://www.lavrsen.dk/twiki/bin/view/Open2300/WebHome) and "Xastir", 
the APRS package for Linux (see http://www.xastir.org). It allows your 
LaCrosse WS-23xx weather data to be used by Xastir for local station data.

You will need to obtain and install Xastir, mysql and open2300 as 
outlined in the following sections. After Xastir and open2300 are
in working order, this utility can be run as a daemon to provide 
weather data to Xastir (or any other APRS-format application).

"open2300db2APRS" watches for new weather data in the database, retrieves
the new data, formats it in APRS "position less" ASCII format and
makes it available on a TCP port of your choosing. Xastir is 
capable of reading this data (see note under Xastir installation).


INSTALLATION
------------

Steps in order:

1) Install mysql - initial tested version mysql-3.23.58
   although version 4 is released and has some significant 
   improvements - and version 4 *should* work (to be tested yet). 
   If you use an RPM or DPK binary-image version, be sure to add 
   the mysql-devel headers. For the latest image-version, see 
   http://www.mysql.com and follow the links to the downloads. 
   I used mysql-3.23.58-pc-linux-i686.tar.gz from that site.   

2) Install open2300 - tested version open2300-1.10 
   See the instructions for installing & then setting 
   up open2300 that come with the tar ball. Obtain the latest open2300 
   at http://www.lavrsen.dk/twiki/bin/view/Open2300/WebHome - the setup 
   is rather involved but worth the efort. Some SQL/XML skills can help 
   here, but are not absolutely required...

   The table setup for the mySQL portion of the open2300 database can be 
   found in the weatherdump.sql file.  My database is setup for degree F, 
   inches of Mercury, inches of rain, and windspeed in knots.

3) Install or update your installation for Xastir to the latest
   version ("http://github.com/Xastir/Xastir" project Xastir) 

4) Install open2300db2APRS 
   See instructions below.


SETTINGS & STARTUP
------------------

1) mysql - it is recommended by mysql to set up passwords, but for
   this usage it doesn't matter. In fact, it's a bit of a pain.
   TODO - open2300db2APRS has the annoying fault of clearly displaying 
   the password used for the mysql database for anyone to see via 
   'ps -ef'. Start mysqld before open2300db2APRS, meteo and Xastir in your 
   boot-time initializations.

2) open2300 - my testing used a five minute data accumulation rate. 
   Thirty seconds would more closely match Xastir, but the 
   database growth rate would be twelve as fast (about 600  
   Mbytes/year at 30 sec rate).  I run a cronjob every five minutes that
   calls mysql2300 to populate the data.  See the open2300 documentation.

3) open2300db2APRS - see "open2300db2APRS RUN OPTIONS" below. Start this daemon 
   after mysqld and before Xastir.  I start it with the command 
   "open2300db2APRS -r --password <db2passwd>

4) xastir - start this last, if you are auto-opening the WX port.
   Set the weather port as a network weather station on 
   "localhost", port number as chosen in "db2APRS RUN OPTIONS" 
   (default is 1313). Make sure your station is set to one of the
   "w/weather data" and your Icon is set to a weather Icon.


open2300db2APRS RUN OPTIONS
-------------------

The open2300db2APRS utility takes standard short & long command line 
options, which can be displayed by "open2300db2APRS -?". Here's the list:

  -h	--help	

      Show help info and exit.

  -v    --verbose

      Useful with the -n switch, for trouble-shooting, not for 
      normal operation. Tells you more than you really wanted to  
      know, but I recommend that you use this switch while you 
      try to initially set up db2APRS.

  -c	--cport [port#]

      Choose which TCP/IP port data comes out from. If not used,
      port number 1313 is the default. HINT: "telnet localhost 
      [port#]" is a handy way to verify db2APRS operation.

  -u 	--user [database user]	

      Username for mysql database connection. If unspecfied 
      defaults to "meteo" (which is per the meteo setup intended
      to be a read-only account for meteo).

  -p 	--password [db passwd]	

      Password for mysql connection. If unspecfied, no password  
      is supplied. NOTE: this password is unfortunately visible 
      to anyone on your system running 'ps -ef'. TO BE FIXED.

  -b 	--database [database]	

      Database name for mysql connection. If not supplied the 
      default is "meteo".

  -n	--nodaemon

      Run in the fore-ground as a program. Useful for debugging
      or initial setup, when used with -v.

  -r	--repeat
      
      Keep going till killed - if not specified, one pass is 
      performed and then db2APRS exits. The only case where this  
      switch is *not* used is during initial setup/debug.

Typical example: "./open2300db2APRS -r -u open2300 -p mysql2300" for normal use
or "./open2300db2APRS -r -n -v -u test -p password" for debugging.


OPERATIONAL DETAILS
-------------------

open2300db2APRS connects to the specified mysql database, extracts the 
latest timestamp and compares it to the last timestamp it read. 
If newer, the outdoor weather data (extception: air pressure is
taken as indoor=outdoor) bearing this timestamp is extracted 
and formatted in the APRS "position less" string format with a  
Davis and X-APRS tag on the end. Any connecting client is given 
this string at 25 second intervals, after new database entries 
are checked for.

This daemon could run on any networked Linux machine instead of 
the machine hosting Xastir, if desired (it's a good way around 
lack of processing power, disk space or serial ports!).

Note that the open2300db2APRS daemon keeps providing data to Xastir even 
when no new entries in the database have been made. This could 
lead to errors in the timestamp on the data that Xastir is 
transmitting.


BUILD open2300db2APRS
-------------

It's the usual:

$ cd xastir/LaCrosse
$ ./bootstrap.sh
$ ./configure
$ make
$ su -c 'make install'


ACKNOWLEGEMENTS & AUTHORS
-------------------------

A large portion of this work taken from db2APRS (thanks Bruce!!)

db2APRS is the product of Bruce Bennett, callsign KB8ROP 
<bruts@adelphia.net> It is freely available at no charge 
under the GNU GENERAL PUBLIC LICENSE (see "COPYING" document)
NO WARRANTY, expressed or implied, use at your own risk.

Please feel free to contact me with test results & comments 
at the above EMAIL address

Code portions and style taken from wx200d by Tim Witham 
<twitham@quiknet.com>, et. al.

mysql is the product of MySQL - see http://www.mysql.com for
team details.

and finally, Xastir is the brain child of Frank Giannandrea et. 
al. (see http://www.xastir.org for current EMAIL addresses)


