*    PEERHOOD   *

Copyright 2003,2004,2008,2009 Lappeenranta University of Technology.

This program is distributed under the terms of the GNU Lesser General Public
License.


General Requirements
==============================================================================

	- Linux
	- GNU C++ compiler
	- GNU C++ standard libraries
	- GNU Make

In order to compile PeerHood following libraries must be installed:

	- Linux Bluetooth protocol stack (Bluez)
	- Bluetooth development headers (libbluetooth-dev) 
	- D-Bus library (dbus-1)
	- D-Bus library development headers (libdbus-glib-1-dev)


Additional Platform Specific Requirements
==============================================================================

Maemo:
	- Maemo SDK or SDK+
	- maemo-explicit (for pre-fremantle)
	- mce-dev
	- icd2-osso-ic-dev
	- maemo-cplusplus-env


Configuring the build
==============================================================================

Before compiling PeerHood select modules that are applied into build in
Makefile in the root folder of PeerHood.
Modules are:
  - libpeerhood                      PeerHood library -required
  - peerhoodd                        PeerHood daemon - required
  - plugin-local                     PeerHood local plugin - required
  - plugin-gprs                      GPRS plugin - optional
  - GPRSgw                           GPRS gateway plugin - optional,
                                     requried by plugin-gprs
  - plugin-bt                        Bluetooth plugin - optional
  - plugin-wlan                      WLAN adapter plugin - optional
  - plugin-listener-bluez-bt         Bluetooth listener plugin - optional

Additional modules for Nokia N810 / N900 (all optional):
  - plugin-listener-maemo-bt         Bluetooth listener plugin for Maemo 
  - plugin-listener-maemo-system     System listener plugin for Maemo
  - plugin-listener-maemo-wlan       WLAN listener plugin for Maemo

To adjust other build parameters modify MakeCommonDefs.mk -file:
  - Change C++ compiler: CXX=g++
  - If building in some other environment, set: BUILD_ENV= to preferred
    - n810 and n900 are currently supported as extra enviroments (note: tested
      on scratchbox1)
    - Can be done e.g. with: make build BUILD_ENV=n900
  - Enable/disable debug: DEBUG=y/n
  - Enable/disable daemon debug: PH_DEBUG=y/n
  - Enable/disable library debug: LIB_DEBUG=y/n

PeerHood outputs logging information to /var/log/syslog or /var/log/messages
depending on system configurations.


Compilation and installation
==============================================================================

To compile PeerHood:
  make build
	
To remove all built files:
  make clean

PeerHood will be built to <PeerHood_root>/result/ and following directory
structure will be created:
  - bin/                PeerHood executables: daemon and prototypes
  - etc/
  - include/
    - peerhood/         PeerHood headers
  - lib/                PeerHood libraries
  - share/
    - doc/
      - peerhood/
    - peerhood/
		
To install (as sudo / root):
	make install
	
  Default installation settings:
   - The libpeerhood.so will be installed to /usr/lib as libpeerhood.so.$version
     and a symbolic link with name libpeerhood.so is created into /usr/lib
     pointing to the actual library.
   - All plugins will be installed into /usr/lib/peerhood (libpeerhood-*.so 
     -files)
   - The daemon executable (peerhoodd) will be installed to /usr/bin
   - All include files are installed to /usr/include/peerhood
   - The configuration file (.phconfig) will be installed into /root/ IF such 
     file does not exist
   - ldconfig is executed to rebuild library cache

To create debian package use:
	dpkg-buildpackage -rfakeroot -b -d 

	NOTE: when building on maemo (in scratchbox) the BUILD_ENV=n900 will be set
	and debugging will be disabled.
	

Running PeerHood
==============================================================================

Current version of PeerHood requires that the daemon is ran as root. The user 
configuration file (.phconfig in the root folder of PeerHood source) has to be
copied to $HOME directory of the user that will be running the daemon (root!)
and programs that use PeerHood.

Additionally two environment variables can be set (for root running the
daemon and user whose applications are using PeerHood) to point PeerHood
library, variables are:
  - PH_PLUGIN_DIR      Path to PeerHood plugins 
  - LD_LIBRARY_PATH    Path to PeerHood library
  
Currently these are no longer required if 'make install' is used since ldconfig
is used and plugins are searched from the plugin installation directory
(/usr/lib/peerhood)

To start the PeerHood daemon (as root): ./peerhoodd

By default no parameters are used, if in some case the daemon is required to 
start as "passive" mode when no networking plugins will be started if there is
no client connected, run the daemon as root: ./peerhood passive

To run PeerHood as background daemon run as root:
Passive : ./peerhood passive daemon
Active  : ./peerhood active daemon


Configuring PeerHood
==============================================================================

The .phconfig file contains following variables (as key-value pairs separated
with colon):

  KEY NAME                 DEFAULT VALUE      MEANING
  ============================================================================
  PreferedPlugin           bt-base            What plugin PeerHood prefers.
                                              bt-base = Bluetooth plugin
                                              wlan-base = WLAN plugin
                                              gprs-base = GPRS plugin
  
  gateway                  10.0.20.215        Gateway address for GRPS plugin.
  
  WLANInterface            wlan0              Interface of the WLAN adapter.
                                              Note that reqular ethernet 
                                              adapters work too (e.g. eth0).
  
  BTMonitoringInterval     10                 Monitoring interval of Bluetooth
                                              in seconds.
  
  BTDaemonPort             24                 Bluetooth listening port for 
                                              Daemon only.
  
  BTServiceCheckInterval   3                  Service check interval of 
                                              Bluetooth in times seen. E.g.
                                              if interval is 3 services are
                                              checked when device has been
                                              seen 3 times in row.
  
  WLANMonitoringInterval   5                  Monitoring interval of WLAN in 
                                              seconds
	
  WLANServiceCheckInterval 10                 Service check interval of WLAN
                                              in times seen. See explanation
                                              of BTServiceCheckInterval.
	
  GPRSMonitoringInterval   10                 Monitoring interval of GPRS in
                                              seconds
	
  GPRSServiceCheckInterval 3                  Service check interval of GPRS
                                              in times seen. See explanation
                                              of BTServiceCheckInterval.
	
  MonitoringInterval       20                 Monitoring interval of a device
                                              when put to active monitoring.
                                              Currently not used.
	
  DeviceName               devicename         The name of the device. This is
                                              the name that is visible to
                                              other devices using PeerHood.
                                              Note that users cannot change
                                              this, the name set by root in
                                              .phconfig is used!
	
  Roaming                  no                 Is roaming option enabled.
                                              yes = enabled
                                              no = disabled
		
  DeviceInfo               1                  Can PeerHood share device info.
                                              1 = yes
                                              0 = no
	
  ServiceInfo              1                  Can PeerHood share service info.
                                              1 = yes
                                              0 = no
	
  ProtoInfo                1                  Can PeerHood share proto info.
                                              1 = yes
                                              0 = no
	
  NeighInfo                0                  Can PeerHood share neighborhood
                                              info.
                                              1 = yes
                                              0 = no


