CMUPA release 1 (7/16/1998)

What's in this release:

* Definition of CMUPA data structure
* UNIX source code for packing, unpacking, and printing packets
* UNIX source code for a dummy OCU
* Visual C++ class for packing and unpacking
* Visual C++ class for sending, receiving, and handshaking with the server

CMUPA data structure
	The data structure is defined verbatim as described in the CMUPA documentation.
	Please check the CMU VSAM home page for the latest version of the specification.
	A pointer is used in any place where a large binary data may be stored, i.e. for
	imageries, videos, or target template.  This saves on some data copying within
	the program.

UNIX CMUPA source codes
	All files are in cmupa/.   Provided functions are:

	long pack_cmupa(CMUPA *, char *);
	long unpack_cmupa(char *, CMUPA *);
	void print_cmupa(CMUPA);

	pack_cmupa() takes a CMUPA data structure and packs it into the array of char
	given as the second parameter.  The function returns the size of the character
	string on successful completion and the resultant character string is smaller
	than MAX_BUFFER_LENGTH, or ERROR otherwise.  Currently, exceeding
	MAX_BUFFER_LENGTH is the only way to cause the function to return ERROR.

	unpack_cmupa() takes a character string of less than MAX_BUFFER_LENGTH size
	and unpacks the encoded data out to the given CMUPA structure.  The function
	returns the amount of character used in unpack, or returns ERROR otherwise.
	Currently, the only way to cause the function to return ERROR is to exceed
	MAX_BUFFER_LENGTH during unpacking.

	print_cmupa() prints a formatted output of a CMUPA packet.

	Future additions:
	* better bounds checking for pack/unpack
	* better handling of pointers in data structure
	* helper functions for network communication and handshaking with the OCU

UNIX dummy OCU code
	All files are in dummyOCU98/.  Some modification may be needed if you are
	compiling for different platforms, using the vendor-supplied compiler.  For
	platforms that has cc aliased to gcc, such as Linux (our target OCU platform), it
	will build out of box.

	Current features:
	* listen for connection
	* perform handshaking
	* print out all packets 

	Future additions:
	* properly handle SPU disconnection/reconnection
	* real OCU functions
	* data logging

Visual C++ CCMUPA and CComms classes
	Files:
		VC++/enums.h
		VC++/CMUPA.h
		VC++/CMUPA.cpp
		VC++/Comms.h
		VC++/Comms.cpp

	CCMUPA methods:
		int pack_cmupa(char *);
		int unpack_cmupa(char *);
	CCMUPA member variable:
		CMUPA data;

	These functions pack from or unpack to data structure stored in the class.  See
	above for return value.

	Use the member variable data to access CMUPA data structure.

	CComms methods:
		BOOL Connect(char *, int);
		BOOL Send(void);
		BOOL SendNow(void);
		BOOL Receive(void);
		BOOL Disconnect(void);
	CComms member variable
		CCMUPA InPacket;
		CCMUPA OutPacket;
		int SPUID;

	All functions return TRUE if successful, or FALSE if error occured.

	Connect() takes the IP address of the server as stored as char string and the
	port number.  Connect() also performs necessary handshaking with the OCU to
	establish a connection.  Prior to calling Connect(), the program needs to set the
	SPUID member variable, SPU capabilities, and initial sensor status.  An sample
	code as follows:

		CComms com;
		com.SPUID = my_spu_id; /* use ID_SPU_# enumeration */
		com.OutPacket.data.command_block[0].packet_bitmask.c_bitmask = 0x00;
			/* repeat for s_bitmask, i_bitmask, r_bitmask, and e_bitmask */

			/* set s_bitmask to indicate what initial data will be supplied */
		com.OutPacket.data.sensor_block[0].s_bitmask = 0x01;
		com.OutPacket.data.sensor_block[0].lvcs_pos.x = 0.00;
			/* etc ... */

			/* and finally */
		com.Connect("127.0.0.1", 7000);

	Send() packs the data structure in OutPacket and sends it to the connected host.
	It is the responsibility of the user to set the appropriate bitmasks to indicate
	which data needs to be sent.  The packing function will adjust the packet size.
	Send() follows the network bandwidth guideline.

	SendNow() is identical with Send, but it does not following network bandwidth
	guideline and sends the packet immediately.  This function should be used to
	respond to CM_REQUEST_DATA_PRIORITY command.

	Receive() checks the network buffer for a packet, and if one exists, unpacks it to
	InPacket member variable.

	Disconnect() closes the socket and prevents more information from being transmitted.

Please send all comments to ycl@cmu.edu.
All rights reserved by Carnegie Mellon University.