================= Table of Contents ================= A. Setup A.1 Building and Running gpsd A.2 Building CricketDaemon (Optional) A.3 Building CricketDaemon Applications (Optional) B. Run (Basic) B.1 Running CricketDaemon with javax.commapi B.2 Running CricketDaemon with gpsd B.3 Running BeaconFinder C Run (Advanced) C.1 Logging Beacons C.2 Playback C.3 Interactive Simulation C.4 Beacon Value Translation D. Application Interface with CricketDaemon E. Extending CricketDaemon (incomplete) ======== A. Setup ======== Before you can run the CricketDaemon software, you need to make sure that: 1) you're running the new java jdk1.3, or higher. 2) (Windows only) have cygwin installed Next, you need to either have the javax.commapi library installed or have the gpsd package compiled on your platform. The CricketDaemon needs one of these modules to access the listeners via the serial port. A.1 Building and Running gpsd ------------------------------ If you just want to run CricketDaemon and do not want to modify CricketDaemon, this is the preferred method because it saves you some setup time from finding and installing the javax.commapi package. One can "telnet" into gpsd and observe the raw data coming to the serial port. This is useful for troubleshooting your setup/hardware failures. gpsd will compile under Win32 if cygwin is installed. See http://sources.redhat.com/cygwin/ ---> gpsd works well on cygwin-1.3.2 ---> on later versions such as cygwin-1.3.9 or cygwin-1.3.10, the following fixes are required: 1) Change CFLAGS in Makefile.in from -g -O2 to -g 2) In serial.c a) Comment out lines 82-86 (tcgetattr and ioctl calls) b) Change (line 88) #if defined (USE_TERMIO) to #if 0 3) In gpsd.c change line 301 from nfds = getdtablesize(); to nfds = 67; To build, 1) go to the Cricket\src\gpsd-1.06 directory 2) run ./configure 3) run make To run gpsd ./gpsd -s 9600 -T c -p /dev/ttyS0 (use /dev/ttySA0 for iPAQ and COM1 in Win32) To test gpsd 1) telnet localhost 2947 (or replace localhost with the host that gpsd is running on) 2) type 'r' and enter in telnet. You should now see some Cricket Listener reading. (Remember to turn the beacon and listeners on!) A.2 Building CricketDaemon (Optional) -------------------------- Building CricketDaemon is optional as the binaries (.jar files) are included in the Cricket\bin directory. To build CricketDaemon, you need to have the javax.commapi installed. See www.javasoft.com. (Linux only) you also need the serial port extensions installed from www.rxtx.org Next, we build. 1) "cd" into the Cricket/src/cricketdaemon and modify the Makefile The ROOT variable should point to the directory above Cricket. The COMM variable should point to the the comm.jar file in the javax.commapi package. Set the SEP variable to the appropriate classpath separator for your platform. (e.g. in Win32 it's a semicolon and in Unix, it's a colon) 2) type "make". A.3 Building CricketDaemon Applications (Optional) --------------------------------------- Building the Applications that comes prepackaged with CricketDaemon is also optional as the binaries (.jar files) are included in the Cricket\bin directory. 1) Just "cd" into the packages in Cricket/app and modify the Makefiles in the application package you want to build. The ROOT variable should be set to point to the directory above Cricket. Set the SEP variable to the appropriate classpath separator for your platform. (e.g. in Win32 it's a semicolon and in Unix, it's a colon) 2) type "make" (For running on Windows, I have only tested this with cygwin installed). =============== B. Run (Basic) =============== B.1 Running CricketDaemon with javax.commapi --------------------------------------------- 1) First, you need to have the javax.commapi package installed. See www.javasoft.com and www.rxtx.org (Linux) 2) cd into Cricket/bin 3) modify cricket.conf. The "port" can be left blank for default values. (COM1 for Win32 systems and /dev/ttyS0 for Linux). For iPAQ, set it to /dev/ttySA0. The "baudrate" should be kept at 9600. e.g.: port /dev/ttySA0 baurate 9600 4) modify either classpath.bat (in Windows) or classpath.sh (in UNIX). a) Set JAVACOMM to point to the comm.jar file (installed from step 1) b) Set CRICKETROOT to point to the directory above Cricket 5) run the classpath.bat (or "source classpath.sh") 5) java cricketdaemon.CricketDaemon Add the "-h" option to see a list of available options. B.2 Running CricketDaemon with gpsd ------------------------------------ 1) First, you need to build gpsd. 2) To run CricketDaemon, a) perform steps 2) through 5) in B.1; ignore step 4.a b) java cricketdaemon.CricketDaemon -g127.0.0.1 One can omit 127.0.0.1 if gpsd is running on the localhost, or replace 127.0.0.1 with the ip address of the host that is running gpsd. B.3 Running BeaconFinder ------------------------- 1. run CricketDaemon by following all the steps in B.1 or B.2, include the "-S" flag to turn on the BeaconStatModule. 2. java beaconfinder.BeaconFinderApp ================= C. Run (Advanced) ================= The cricket.conf file and the CLASSPATH variable must be setup properly. Please see "B. Run (Basic)" for instructions on how to set these up. C.1 Logging Beacons -------------------- The CricketDaemon allows one to save the observed beacon readings into a log file that can be used for playback later. Use the argument "-L" to enable this feature. The log file name can be passed as an option value: java cricketdaemon.CricketDaemon -Lfoobar.log Note that there should not be a space between the flag and the option value. Each beacon reading has the folloing Logging Format: TIMESTAMP TYPE: SEQNUM RESERVED SPACE BEACON_ID DISTANCE COORDINATE C.2 Playback Beacons -------------------- The CricketDaemon can playback beacon log file (see C.1) in real time. This is a useful feature for testing applications and various beacon processing algorithms. To run CricketDaemon in playback mode, use the "-f" flag. The option value specifies the beacon log file for playback. java cricketdaemon.CricketDaemon -ffoobar.log Note that there should not be a space between the flag and the option value. C.3 Interactive Simulation --------------------------- The CricketDaemon can process beacon readings generated from an interactive simulation instead of readings obtained from the CricketListener. 1. Setup the Beacon Configuration file. The default is beacons.conf located in Cricket\bin. It has the following format: SPACE%ID X Y Z a) The SPACE and ID is delimited by a "%" symbol. Do not include "%" as part of the space string. Thus "512A%3" denotes a beacon with space=512A and id=3. b) The X, Y, Z are coordinates expressed in double. Currently, the z coordinate is ignored and assumed to be zero. The origin of the x,y plane is at the top left-hand corner of the GUI, with increasing x and y values toward the right and down direction respectively. c) The "#" or "!" characters can be used to comment out an entire line. For details, see the Java documentation for java.Util.Properties.load(). 2. Run CricketDaemon with the "-s" option. The option value specifies a custom beacon configuration file. e.g.: java cricketdaemon.CricketDaemon -sfoobar.conf 3. The controls for the interactive GUI is as follows: (remember to disable CAPSLOCK) The arrow keys navigates the device in the virtual world. "d" and "f" rotates the device in different directions. Note: Orientation measurement is not yet supported. C.4 Beacon Value Translation ----------------------------- The CricketDaemon allows the user to enable a "beacon reading filter" to translate or map a particular field(s) to a different value. For example, a typical beacon reading may be: 994444476962 Beacon: 8 null 508A 32 127 null null One may wish to change the space name to 507B and add the coordinate information before passing the beacon reading to the processing modules: 994444476962 Beacon: 8 null 507A 32 127 ( 110.0 60.0 0.0 ) null This feature is useful for a user to test different beacon placments and setups without having to reprogram the beacons. To enable Beacon Value Translation, run the CricketDaemon with the "-m" flag. The default translation configuration file is "translate.conf" in Cricket\bin. Each line specifies a translation rule for a beacon. Each rule has the following format: TARGETBEACON MAPPING where TARGETBEACON = SPACE%ID and MAPPING = SPACE%ID X Y Z a) TARGETBEACON specifies the beacon from which the readings are to be translated. b) MAPPING specifies the mapping values for the TARGETBEACON. For example, the rule that generates the translation of the sample given above would be: 508A%32 507A%32 110 60 0 c) The distance and orientation fields are currently NOT translated. d) The "#" or "!" characters can be used to comment out an entire line. For details, see the Java documentation for java.Util.Properties.load(). ========================================== D. Application Interface for CricketDaemon ========================================== See the SPEC under Cricket/src/cricketdaemon/server for instructions how to connect to the CricketDaemon via UDP, and for the packet format specification. If the application is being written in Java, there is a client library available. The relevant information are contained in the client library directory under Cricket/src/cricketdaemon/clientlib. See the BeaconFinderApp for an example. ========================== E. Extending CricketDaemon ========================== TBA.