+----------------------------------------------------------------------------+
| phpAPRS - A PHP Automatic Packet Reporting System ("APRS") class for PHP 5 |
| Copyright (c) 2008 Matthew Asham, VE7UDP <matthewa@bcwireless.net>         |
+----------------------------------------------------------------------------+

= SYNOPSIS =

phpAPRS is a PHP class for writing APRS utilities.  The class presently supports 
TCP/IP based APRS.

The project website is http://sourceforge.net/projects/phpaprs/

APRS is a registered trademark of Bob Bruninga, WB4APR, who tries to maintain the standards and compatibilty among all applications.

For more information regarding APRS, see the APRS1.1 and APRS1.2 addendums www.aprs.org/aprs11.html and aprs12.html

 
= PROJECT STATUS =

This project is in an alpha state, and is subject to change and improvement.  It may also
give you migrain headaches, eat your dog, or be of immense utility. 

= LICENSE =


phpAPRS is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

phpAPRS is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License
along with phpAPRS.  If not, see <http://www.gnu.org/licenses/>.

= USING THE LIBRARY =

== DIRECTORY LAYOUT ==

 aprsbot/    - an example APRS bot
 build/      - miscellaneous build scripts (for developers)
 docs/       - class documentation
 lib/        - the core phpAPRS library
 lib/packets - individual APRS frame classes
 
== ARCHITECTURE ==

phpAPRS consists of a core class, and individual packet classes derived from a basepacket class.

The core class is BCWNS_APRS() - lib/class.bcwns.aprs.php.  BCWNS_APRS handles I/O between the
APRS-IS network and the application, parsing of APRS packets and execution of message callbacks.

Each APRS frame type is implement as its own packet class.   For example:
 * class.bcwns.aprs.item.php implements an APRS Item type, for posting Items to the APRS network
 * class.bcwns.aprs.message.php implements APRS messaging
 * class.bcwns.aprs.position.php implements APRS position reporting
 
For each APRS frame to be sent to the APRS network, a new packet must be constructed, configured
and sent through BCWNS_APRS().

Presently, BCWNS_APRS->ioloop() must be called periodically to handle transmission (and retransmission,
if applicable) and reception of APRS packets.  ioloop() does the dirty business, and will
dispatch message handling callbacks for each APRS packet received. 

== ROUGH EXAMPLE ==

/* include the core class.  this class will also include the basepacket 
   base class, and individual packet classes */

require "lib/class.bcwns.aprs.php";

// make an APRS object

$aprs = new BCWNS_APRS();

// enable the BCWNS_APRS I/O debugger
$aprs->setDebug(APRSDEBUG_IO);

// connect to the aprs-is host
if($aprs->connect("some.aprs.host","10152","MYCALL","PASSCODE")==FALSE){
	die("Couldn't connect!\n");
}

// instrument the i/o loop 
while(1){
	$aprs->ioloop(5);
	// do stuff
	sleep(1);
}

== DEMO APPLICATIONS ==
The first concept application for phpAPRS was WIFIFRED, the VA7BCW-1 (British Columbia Wireless Network Society)
Information Robot.

