X-Plane Connect-C (XPC-C) Readme

DESCRIPTION
        XPC-C is a series of C functions that facilitate communication with X-Plane.

-----------------------------------
SETUP
        Before using XPC Functions you must
               1. Copy the folder "[XPC Directory]/xpcPlugin/XPlaneConnect" to the "[X-Plane Directory]/Resources/plugins" directory.
               2. Put in X-Plane CD 1 or X-Plane USB Key.
               3. Start X-Plane.
        4. #include "xplaneConnect.h"

-----------------------------------
BASIC FUNCTIONS
    1. openUDP opens a UDP Socket for communication. This is used to send data or receive.
        INPUT:
        port (unsigned short): Port Number (ex:49067)
        xpIP (char *): IP Address of the computer running x-plane
        xpPort (unsigned short): Port number that the X-Plane/ xpcPlugin Receives on (send -1 for default (49009), Typically xpcPlugin is 49009)

        OUTPUT:
        socket (xpcSocket): The Opened Socket

        USE:
        unsigned short portNumber = 49067;
        struct xpcSocket theSocket = openUDP(portNumber, “127.0.0.1”, 49009);

    2. closeUDP closes an opened UDP Socket for communication. This is to be done after the program has finished using that socket. Use opedUDP to open socket.
        INPUT:
        socket (xpcSocket): The Opened Socket

        USE:
        closeUDP(theSocket);

    3. setCONN sets the return port for requested datarefs.
        INPUT:
        socket (xpcSocket): Socket to use to send the command
        recPort (unsigned Short): Port number for requested dataref values to be sent to

        OUTPUT:
        status (short): 0 if successful

        USE:
        char IP[16] = "127.0.0.1";
        struct xpcSocket theSocket = openUDP(49067);
        setCONN(theSocket,IP,49009,49022); // Sets receive address to 49022;

    4. pauseSim pauses/resumes the x-plane simulation
        INPUT:
        socket (xpcSocket): Socket to use to send the command
        pause (short): 1=Pause, 0=Resume

        OUTPUT:
        status (short): 0 if successful

        USE:
        char IP[16] = "127.0.0.1";
        struct xpcSocket theSocket = openUDP(49067);
        pauseSim(theSocket, IP, 49009, 1);

    5. sendDATA set the value of a state in the "DATA Input & Output" Table
        INPUT:
        socket (xpcSocket): Socket to use to send the command
        dataArray (float[][9]): Array of data to be sent. The first element of each row is the item # (corresponding to the number on the X-Plane "DATA Input & Output" Screen). Send -999 to leave the value unchanged.
        rows (unsigned short): Number of rows of data being sent

        OUTPUT:
        status (short): 0 if successful

        USE:
        char IP[16] = "127.0.0.1";
        struct xpcSocket theSocket = openUDP(49067);
        float data[] = {{14, 1, -999, -999, -999, -999, -999, -999, -999},{25, 0.8, 0.8, -999, -999, -999, -999, -999, -999}}; // Gear and Throttle
        sendDATA(theSocket,IP,49009,data,2);

    6. sendPOSI set the position of an aircraft
        INPUT:
        socket (xpcSocket): Socket to use to send the command
        ACNum (short): Number of aircraft to be moved, use 0 for main aircraft (ownPlane).
        numArgs (short): Number of Arguments to be sent (size of position array)
        position (float []): Arguments corresponding to aircrafts position
            position[0] = Latitude
            position[1] = Longitude
            position[2] = Altitude (m MSL)
            position[3] = Roll (deg)
            position[4] = Pitch (deg)
            position[5] = True Heading (deg)
            position[6] = Gear (0=up, 1=down)

        OUTPUT:
        status (short): 0 if successful

        USE:
        char IP[16] = "127.0.0.1";
        struct xpcSocket theSocket = openUDP(49067);
        float posit[] = {37.5242422, -122.06899, 2500, 0, 0, 0, 1};
        sendPOSI(theSocket, IP, 49009, 7, posit);

    7. sendCTRL send control commands to the aircraft
        INPUT:
        socket (xpcSocket): Socket to use to send the command
        numArgs (short): Number of Arguments to be sent (size of control array)
        control (float []): Arguments corresponding to aircraft control command
            control[0] = Latitudinal Stick [-1,1]
            control[1] = Longitudinal Stick [-1,1]
            control[2] = Pedal [-1, 1]
            control[3] = Throttle [-1, 1]
            control[4] = Gear (0=up, 1=down)
            control[5] = Flaps [0, 1]

        OUTPUT:
        status (short): 0 if successful

        USE:
        char IP[16] = "127.0.0.1";
        struct xpcSocket theSocket = openUDP(49067);
        float ctrl[] = {0, 0, 0, 0.8, 0, 1};
        sendCTRL(theSocket, IP, 49009, 6, ctrl);

    8. sendDREF set the value of a specific dataref. Dataref list found at http://www.xsquawkbox.net/xpsdk/docs/DataRefs.html
        INPUT:
        socket (xpcSocket): Socket to use to send the command
        dataRef (char *): Dataref to be set (with or without "sim/" preceeding it)
        length (short): length of dataref string
        values (float *): Array of values to be sent
        length2 (short): Number of values in values array

        OUTPUT:
        status (short): 0 if successful

        USE:
        char IP[16] = "127.0.0.1";
        struct xpcSocket theSocket = openUDP(49067);
        char theDREF[] = "cockpit/switches/gear_handle_status";
        float value = 1;
        sendDREF(theSocket, IP, 49009, theDREF, strlen(theDREF), &value, 1);

    9. requestDREF Request the value of specific dref(s). Dataref list found at http://www.xsquawkbox.net/xpsdk/docs/DataRefs.html
        INPUT:
        outSocket (xpcSocket): Socket to use to send the command
        inSocket (xpcSocket): Socket to use to receive the result
        DREFArray (char[][100]): Array of DataRefs to be requested
        DREFSizes (int[]): Array of string lengths for each DataRef in DREFArray
        listLength (short): Number of DataRefs in DREFArray
        result (*float[]): Array of pointers to the values returned
        arrayLen (short[]): Array where each element corresponds to the number of elements in the float array.

        OUTPUT:
          length (short): Number of Values Returned

        USE:
        char IP[16] = "127.0.0.1";
        struct xpcSocket theSocket = openUDP(49067);
        char DREFArray[][100] = {"sim/cockpit/switches/gear_handle_status"};
        requestDREF(theSocket, IP, 49009, DREFArray, strlen(DREFArray[0]),1);

    10. sendTEXT write some text to the screen.
	INPUT:
	outSocket (xpcSocket): Socket to use to send the command
	message (char*): The string to be wrote to the screen
	x (int): The x position where the text will be written. Set to -1 to use default position.
	y (int): The y position where the text will be written. Set to -1 to use default position.

-----------------------------------
ADVANCED FUNCTIONS (These are mostly used by the xpcPlugin to read requests)
    1. sendUDP
    2. readUDP
    3. readDATA
    4. parseDATA
    5. readPOSI
    6. parsePOSI
    7. readCTRL
    8. parseCTRL
    9. readRequest
    10. parseRequest
    11. parseDREF
    12. readDREF

-----------------------------------
PLANNED FUNCTIONS
    1. sendVIEW
    2. parseVIEW
    3. readVIEW
    4. sendWYPT
    5. parseWYPT
    6. readWYPT
    7. selectDATA

-----------------------------------
CONTACT
    Email Christopher Teubert (christopher.a.teubert@nasa.gov) with any questions.
