Notes on AVDS Networking Code

INTRODUCTION:
AVDS sends and receives TCP/IP multicast packets to participate
in distributed simulations with other copies of AVDS and user 
simulations. The network directory structure contains the code
necessary for user's to build their own distributed simulations.
Before using this networking code the user's computer must be configured
for TCP/IP networking.

DIRECTORIES:
The network directory contains the following subdirectories:
bin:
This directory contains programs that resulted from building the 
sample files. There are two samples, 707drone.exe, and Promo.exe.
707drone.exe is an example of one aircraft that flies in a circle.
Promo.exe is an example of many of the AVDS aircraft flying in formation.

examples:
This directory contains subdirectories with Microsoft Project/Workspace
files, makefiles, and source code for the examples.

include:
This directory contains the header file necessary to use the UserNetwork.lib
networking library.

lib:
This directory contains the library that holds the AVDS networking functions.

winsock2:
This directory contains the setup file to update older versions of Windows 95
to winsock 2.0. DO NOT USE THIS FILE WITH WINDOWS NT. See the ReadMe.txt file
located in the winsock2 directory for more information.

STEPS FOR USING AVDS NETWORKING FUNCTIONS:
	1. Call the function, OpenAVDSNetwork, to initialize a multicast
	   session.
	2. Call the function, Init_Aircraft, to initialize an AVDS aircraft
	   structure.
	3. Set the aircraft's host ID and craft ID:
		ac.packet.hostid = 1234;
		ac.packet.craftid = 1234;
	4. To prepare to send out an aircraft packet on the network, fill in,
	   at a (suggested) minimum, the following values in the aircraft structure:
		ac.dt - delta time in seconds
		ac.pos_X - east/west position in feet
		ac.pos_Y - north/south position in feet
		ac.pos_Z - altitude in feet
		ac.rot_X - rotation about the X axis, positive starboard wing
		ac.rot_Y - rotation about the Y axis, positive aircraft nose
		ac.rot_Z - rotation about the Z axis, positive up
	5. Send the aircraft packet using the function, Put_Aircraft. Note the recommended
	   transmission rate is 10 Hz (times/second)
	6. Before exiting call the function, CloseAVDSNetwork, to close the multicast
	   session and cleanup the related networking structures. 

AVDS NETWORKING FUNCTIONS:

int OpenAVDSNetwork(int iCount, TCHAR *tcaAddresses[])
	This functions intializes the multicast network interface. It will
        initialize a multicast session for each set of addresses passed in as parameters.

	PARAMETERS:
	- iCount is the number of multicast addresses being passed in
	- tcaAddresses is an array of strings containing multicast addresses

	RETURN Value:
	 This function returns a 1 if the function succeeds or a 0 if it does not.

	NOTE:
         The format for multicast addresses is:
		mmm.mmm.mmm.mmm:pppp,iii.iii.iii.iii:nnnn
		where:
		- mmm.mmm.mmm.mmm is the multicast address in dot notation e.g
		  222.0.34.20, valid multicast range is: between 224.0.1.0 and 
		  239.255.255.255. 
                  note: Default AVDS multicast address is: 224.0.5.20 
		- pppp is the multicast port e.g 1256
		  note: Default AVDS multicast port is 2267
		- iii.iii.iii.iii is the OPTIONAL local interface address in dot 
		  notation e.g 192.198.0.1 This address is only need if there is
		  more than one local TCP/IP interface.
		- nnnn is the OPTIONAL local interface port e.g 1256

	EXAMPLE:
	int iCount = 1;
	char* strAddress[1];
	strAddress[0] = strdup("224.0.5.20:2267");
	OpenAVDSNetwork(iCount,strAddress);


int CloseAVDSNetwork()
	This function closes all of the open multicast sessions it is required to
	clean-up after the use of the multicast networking.

	RETURN Value:
	 This function returns a 1 if the function succeeds or a 0 if it does not.


void Init_Aircraft( Aircraft* aP, char *name,int id,u_char craft,float lng,float lat,float alt)
	This functions intializes the AVDS aircraft structure for one aircraft.

	PARAMETERS:
		- aP, the aircraft structure, see below.
		- name, a string containing the name of the aircraft.
		- id, each aircraft must have a unique identifier.
		- craft, number of the craft image. This number is the order in which
		     	the image occurs in the craftcap file.
		- lng, starting longitude in degrees decimal.
		- lat, starting latitude in degrees decimal.
		- alt, starting altitude in feet.

	EXAMPLE:
		Init_Aircraft(&ac,"707_Drone",27,AIRCRAFT_TYPE_00,-122.366,37.613,15000.0);

void Put_Aircraft(Aircraft* aP)
	This function sends a packet containing the aircraft dynamics out on the network.

	PARAMETERS:
		- aP is the aircraft structure, see below.

	EXAMPLE:
		Put_Aircraft(&aP)

void Get_Aircraft(Aircraft* aP )	*** NOT YET IMPLEMENTED ***
	PARAMETERS:
		- aP is the aircraft structure, see below.

	EXAMPLE:
		Get_Aircraft(&aP)




AVDS NETWORKING STRUCTURES:


Aircraft Structure:
	This structure contains the information that is passed to the AVDS packet 
		structure, see below, to describe the dynamics of the aircraft.

typedef struct aircraft_struct {
	int state;	/* aircraft state */
	float elev,ail,rud,throttle;	/* commands */
	float u,v,w,p,q,r;
	/* Real values in world coordinates */
	double ref_X, ref_Y;			/* initial latitude and longitude converted to feet in Init_Aircraft */
	double pos_X, pos_Y;			/* east/west and north/south position in feet from reference */
	float pos_Z;				/* altitude in feet */
	float pos_dX, pos_dY, pos_dZ;		/* linear velocities in feet/second */
	float rot_X, rot_Y, rot_Z;		/* angular rotations in degrees */
	float rot_dX, rot_dY, rot_dZ;
	unsigned char engine;				/* throttle position */
	int hostid;
	Packet packet;
	float dt;	/*aircraft delta time*/
} Aircraft;



Network Packet Structure:
	This is the information that is sent out on the network. The function,
	    PutAircraft with the aircraft structure is used to fill in the information
	    in this structure. 

struct packet_struct  {	/* Description		Units                       */
  /***** header (no changes) *****/				/* 48 bytes */
  char   ether[14];	/* ethernet header	14 bytes                    */
  short  padding00;
  int    revision;	/* aviator revision	major,minor,patch           */
  char   handle[PACKET_HANDLE_SIZE];	 /*	string                      */
  char	 home_port[4];	/* Airport name		string			    */

  /***** data (not copied) *****/				/* 28 bytes */
  int    hostid;	/* hostid		unitless                    */
  int    craftid;	/* unique craft id	unitless                    */
  int    craft_checksum;/* crafttcap checksum	unitless                    */
  int    lockon_hostid;	/* hostid of target	unitless (0=nolock)         */
  int    collide_hostid;/* hostid		unitless                    */
  int    collide_craftid;/* unique craft id	unitless                    */
  int    collide_damage;/* unique craft id	MASK_WING_PORT,etc.         */

  /***** data (copied) *****/					/* 24 bytes */
  u_char craft_type;	/* craftcap type	0->255 craftcap order       */
  u_char engine;	/* engine level		ENGINE_MIN,ENGINE_MAX,etc.  */
  u_char ground_type;	/* object is over	GROUND_TYPE_WATER,etc.      */
  char   padding01;
  short  status;	/* status		STATUS_LOCAL,etc.           */
  char   ground_slope_X;/* slope of the ground	unitless (Z/X*128)          */
  char   ground_slope_Y;/* slope of the ground	unitless (Z/Y*128)          */
  int    ground_Ipos_Z;	/* height of ground	pseudo-half-inches          */
  int    render_mask;	/* craft rendering mask	MASK_CANOPY,etc.            */
  float  current_fuel;	/* total fuel		pounds                      */
  float  current_warhead;/*total warhead	pounds of TNT               */

  /***** dynamics (copied) *****/				/* 60 bytes */
  int    Ipos_X;	/* longitude linear	pseudo-half-inches          */
  int    Ipos_Y;	/* latitude  linear	pseudo-half-inches          */
  int    Ipos_Z;	/* altitude  linear	pseudo-half-inches          */
  float  Fpos_dX;	/* longitude velocity	pseudo-half-inches/sec      */
  float  Fpos_dY;	/* latitude  velocity	pseudo-half-inches/sec      */
  float  Fpos_dZ;	/* altitude  velocity	pseudo-half-inches/sec      */
  float  Fpos_ddX;	/* longitude accelerate	pseudo-half-inches/sec/sec  */
  float  Fpos_ddY;	/* latitude  accelerate	pseudo-half-inches/sec/sec  */
  float  Fpos_ddZ;	/* altitude  accelerate	pseudo-half-inches/sec/sec  */
  int    Brot_X;	/* east      rotation 	pseudo-third-minutes        */
  int    Brot_Y;	/* north     rotation	pseudo-third-minutes        */
  int    Brot_Z;	/* vertical  rotation	pseudo-third-minutes        */
  float  Frot_dX;	/* east      velocity	pseudo-third-minutes/sec    */
  float  Frot_dY;	/* north     velocity	pseudo-third-minutes/sec    */
  float  Frot_dZ;	/* vertical  velocity	pseudo-third-minutes/sec    */

  int	 view_Brot_x;	/* View up/down */
  int	 view_Brot_y;	/* View left/right */

  short  current_cm_x;	/* center mass starbord	pseudo-half-inches          */
  short  current_cm_y;	/* center mass fore	pseudo-half-inches          */
  short  current_cm_z;	/* center mass vertical	pseudo-half-inches          */
  short extra;
};
