popufare/Documentation/Module_Overview.txt

	There are two sets of modules involved in this system, one set lives
on each bus (we will call them Client Side), and those that live on the
central server (we will calal them Server Side).

--------------------------------------------------
		Client Side Modules
--------------------------------------------------

Module Name:		PPP Dialer

Module Function:	

	Maintains connection with the server as much as possible using pppd
to set up a gprs internet connection, and then using an ssh client to set up
secure tunnels for each of the underlying Client->Server protocols
implemented by the other modules.

Module Files:		(these files live in /etc/ppp/)

	ppp-dialer.sh	(script to manage ppp connection and SSH tunnels)
	pap-secrets	(password file for bogus user that modem needs)
	chap-secrets	(same as above)
	ip-down.local  	(script to run when pppd link does down)
	ip-up.local	(script to run when pppd link comes up)
	options		(global pppd options)
	chat/disconnect	(modem disconnect sequence)
	chat/gprs	(modem init sequence, gprs specific dial string)
	peers/gprs	(modem location, gprs specific pppd settings)

Module Outputs:
	
	/tmp/network-is-up	(this file is present when ppp0 is up)
	/tmp/tunnel-is-up	(this file is present when SSH tunnel is up)
	/tmp/ssh_tunnel.pid	(pidfile for ssh client implementing tunnel)

-------------------

Module Name:		Client Supervisor

Module Function:

	This module serves a function for our application (as a set of
client modules) as init servers for UNIX.  It is responsible for spawning
a supplied set of other modules and gathering any log messages they may
generate and routing them to the correct logging location.  It also performs
"aliveness" monitoring for all of the child modules it spawns, resetting any
module that has hung (and logging it), as defined by not getting PONG
messages back from a module that's been sent a PING message through the IPC
hub.  This provides a sanity check that will log (for debugging/improvement)
any crashed process, but will also respawn it to maintain maximum system
functionality.

Module Files:		(these files live in the bin directory)

	client_supervisor	(the binary executable)

-------------------

Module Name:		IPC Hub

Module Function:

	This module serves as a communication hub for all of the other
modules to send notifications, requests, and data structures to one another
in an efficient manner.	 It provides a UNIX domain socket in /tmp which
client processes can connect to and then subscribe to mailboxes, as well as
send messages to mailboxes.  Every message sent to a mailbox gets delivered
to each process with an active subscription to that mailbox.  This module
also provides a wiretap feature which allows a debug client to attach to a
running system and watch the messages as they flow through the hub allowing
live trouble shooting.

Module Files:

	/tmp/commhub	(UNIX domain socket to which clients connect)
	ipc_server	(this is the executable for this module)
	debug_client	(this is the wiretap client for live debug)

-------------------

Module Name:		Billing Database Client

Module Function:

	This module collects submissions of billing and diagnostic log
messages from other modules through its IPC mailbox and stores them in a
transaction synchronous local database.  When an SSH tunnel is available to
the central server, it will attempt to flush any message that hasn't yet
been confirmed by the server, retransmitting as needed.  

Module Files:

	billing.mem	(mmap()-able file containing database of log entries)
	billdb		(billing database client)

-------------------

Module Name:		Pass Database Client

Module Function:

	This module maintains a transaction synchronous local database of
riders (rider ID, Magstripe, RFID, Rule, Rule Parameter) which is kept up to
date with the server whenever there is an SSH tunnel available.
	This module also listens to the mailboxes for incoming credentials
from the passenger interface unit and looks them up in the database.  If a
rider record is found for that credential, the associated rule is applied
which will generate a billing log entry (and possibly passenger interface
and driver interface messages).

Module Files:

	passes.mem	(mmap()-able file containing database of riders)
	passdb		(buspass database client)
	init.scm	(library initialization for scheme interpreter)
	rules.scm	(scheme definitions for rules attached to riders)

-------------------

Module Name:		Passenger Interface Unit

Module Function:

	This module communicates with the Passenger Interface Unit connected
by serial port and reports any credential presentation events to the
appropriate mailbox on the IPC hub.  This module also listens to a mailbox
on the IPC hub for commands instructing it to update the text on the
passenger facing display.

Module Files:

	piu_minder	(executable file for PIU module)


-------------------

Module Name:		AVLS Client

Module Function:

	This module provides Automatic Vehicle Location Service data to the
server as connectivity allows, sending the current vehicle location,
heading, velocity, and information about who is logged in and what route is
being driven to the server whenever there is an SSH tunnel available.

Module Files:

	avls		(executable for AVLS client)


--------------------------------------------------
                Server Side Modules
--------------------------------------------------

Module Name:		Bus Pass Server

Module Function:

	This module responds to client busses when they ask for rider and
pass updates.  It maintains a unique sequence number for each update and
when requested gathers a list of the latest change to each rider after any
given sequence number.  This constitutes enough information to bring a
client up to date.  If a client is too far out of date, or if the client
requests it explicitly, the server will send a ZFLUSH command, followed by a
compressed list of all valid riders, followed by a ZFLUSHDONE command.  This
allows a stale client to efficiently get to an up-to-date state.  

-------------------

Module Name:		Billing Log Server

Module Function:

	This module responds to a client's submitted log entry (billing or
diagnostic log) by responding with (ACK, DUP, or IGN) messages followed by
the MD5 checksum of the submitted message.  This response allows the client
to be sure that the message has been logged in the central database, and may
therefore be purged from the local database where storage space is at a
premium.