CricketDaemon 1.0 Protocol

Introduction
============

The CricketDaemon1.0 Protocol allows applications to obtain processed
information from the Cricket listener software, the CricketDaemon.  The
information is packaged in a type-length-value format so that the
content of the packet is self-describing.  This feature allows future
extensions to the packet format while perserving backward compatibility
to existing applications.

Registration
============

Applications REGISTER with the Server by sending to the Server at port
5001 a TCP byte stream containing the following null terminated string:


"register"

The Server uses the source address and port in the TCP packet to return
TCP RESPONSEs to the Application.  Whenever the Server receives an
update from one of the CricketDaemon processing modules, it will send a
packet to each of the registered Applications.  Each packet represents
one update.  It is assumed that an update do not span across multiple
packets.  Hence, there is an implicit limit on the length of the update.

Response Packet Format
======================

The RESPONSE packet is encoded in UTF-8 (ASCII compatible).  A generic
packet consists of a cricket server versioning token, and a payload made
up of a sequence of "|"-separated fields.  We use the symbol "+" to
denote concatenation and "*" as a modifier to denote zero or more
instances of a token.

packet = cricket_ver + "|" + timestamp + "|" + fragment + "|" + payload + "\n"

where 

cricket_ver = "CricketServer1.0"

timestamp = (long) time (ms) when the packet was sent out

fragment = is an ASCII 0 or 1, where 1 means this packet is a fragment
of a complete message (e.g. part of an array) and that the client should
reassemble all packets with a 1 until a packet with 0 fragment value is
received.

payload = field*

where each field within the payload has the format of

field = "|type|length|value|"

For example, a packet may have the following format:

cricket_ver|timestamp||type|length|value||type|length|value|...

where type    is an UTF-8 string denoting the type of the field value,
      length  is a positive integer (UTF-8 encoded) that denotes the 
              length of the value string (in number of bytes),
              excluding the field seperators "|" around the 
	      value field.

Note that the character "|" is reserved as a field separator and
therefore it must not be within the type or length field.  However, this
character can be safely used in the value field as the length field can
be used to distinguish whether "|" is part of the field value.  

Note that nested fields are possible:

value = field* 'or' ascii-string

For example, given a payload:

|type1|length1|VALUE||type2|length2|value2||type3|length3|value3...

we can have a nested VALUE of

|type11|length11|value11|type12|length12|value12|

Note that length1 denotes the entire length of the VALUE field,
including the "|" separators in between but excluding the "|" separators
around VALUE.

The server and the client MUST agree on how to parse and interpret the
ascii-string in the value field for each field type.  The client MAY
ignore and skip over any field(s).

Field Types
===========

The types labelled "(nested)" denotes a type where its value field
contains a nested sequence of fields.

Type		Interpreted Value	Description
----		-----------------	-----------

array:dist_est	array of dist_est	An array of distance estimate
(nested)	(DIST_EST HAS BEEN	records representing the beacons
(DEPRECATED)	CHANGED)		heard by the listener, sorted
(NOW USES DIST_EST instead)		in ascending distance order.

array:stat_est	array of dist_est	Same as above except each
(nested)				record in the array contains
					statistical information about the
					distance estimate for each beacon.
					The array is sorted in 
					asending distance order.

cur_space	a dist_est		A distance estimate record 
(nested)				representing the closest beacon
					heard by the listener.

dist_est	record of		A distance estimate record 
(nested)	{ space, id,            representing a beacon
		  last_update,   	heard by the listener.
		  dist_stat }		NOTE: a dist_est record can
					contain any combination of
					listed sub elements under
					Interpreted Value

space		ascii-string		The string of the space 
					identifier in the beacon.

id		non-negative decimal	The beacon identifier within
		integer			a space.

dist		double			A distance estimate between the
					beacon and listener.

dist_stat	record of		Statistical information about
(nested)	{ dist, median,	mean	the distance estimate wrt a
		  mode, max, min,	beacon.
		  stddev, var,
		  array:sample }

array:sample    array of sample		Timestamp and distances for
(nested)				each sample collected
					within a sliding time window


sample		record of		Timestamp and distance of a
		{ time, dist }          recevied beacon chirp

device_pos	record of		The coordinate of device and
(nested)        { algor, pos,           the _calculated_ distances
                  array:dist_est }      of each beacon used to solve
					the device's coordinate.

pos		record of		The coordinate of device/beacon.
(nested)	{x, y, z}

last_update	64-bit long in ms	In dist_est, the time of last
					distance sample received for a 
					particular beacon.

median		double			median
mean		double			mean
mode		double			mode
max		double			maximum
min		double			minimum
stddev		double			standard deviation
var		double			variance

x		double			x coordinate
y		double			y coordinate
z		double			z coordinate	

algor		string			id of the algorithm that
                                        produced the result

version 1.1

orient		double			orientation from 0 to 2pi
					wrt anchor beacon

anchor		a dist_est		A distance estimate record 
(nested)				representing the anchor beacon
					of the orientation reading.
