All data sent with the WiSAR networking library should be preceeded by a PacketHeader. The packet header does several things:

• Identifies itself as a packet header with a predefined sentinel, such as “WISAR”
• Specifies the type of data being sent so that it can be handled/parsed appropriately
• Identifies the total size of data in a given message so the server/client knows when it has received ALL data

Following the PacketHeader, a data header which corresponds to the PacketType (specified in the PacketHeader) should be added. The data header will have at least the minimum data-type-specific fields required (all required fields in the protocol below) for use. Some data headers will specify the length of any raw data associated with it's type. This raw data will follow immediately after the data header.

The WiSAR networking library will wrap each header type such that applications will not need to deal with any Google Protocol Buffers. Additionally, signals can be connected to slots in the networking library for each data type so that applications will be notified when complete data types are ready, thus completely abstracting the network/data interface layer from applications which need to communicate via the network.

• There are three options for handling telemetry data and images: always packaged together, always sent separately, or the ability to request / send both (packaged as well as each individual). Traditionaly telemetry has always been sent packaged with image data. This is a restrictive/inflated model in that devices or clients only interested in one of the data types will always receive both types regardless of request.

• Any thoughts / ideas for a common message protocol (for instance, client A wants to send a message to client B, or broadcast a message to all clients, or send a message to the server)?

• Any other information we need to be able to represent?

message PacketHeader {
     // possible packet types
     enum PacketType {
          RAW               = 0;
          TELEMETRY_REQUEST = 1;
          TELEMETRY         = 2;
          STREAM_REQUEST    = 3;
          FRAME_REQUEST     = 4;
          IMAGE             = 5;
          ANNOTATION        = 6;
          ERROR             = 7;
          MESSAGE           = 8;
     }
     
     // string used to help find the packet header (necessary for worst-case scenarios)
     required string sentinel = 1;

     // type of data to follow
     required PacketType packetType = 2;

     // size of data (in bytes) following this header
     required uint32 packetLength   = 3; 
}

Mike, you said you had already written this element. Feel free to change it / replace it, I wrote this quickly more as a placeholder / idea.

message TelemetryRequest {
    enum ReferenceType {
         TIMESTAMP   = 0;
         FRAME_INDEX = 1;
         MOST_RECENT = 2;
    }
    required ReferenceType referenceType = 1;
    optional string timestamp = 2;
    optional uint32 frameIndex = 3;
}

message Telemetry {
    enum SourceType {
        UAV = 0;
        MANNED_AIRCRAFT = 1;
        GROUND_SEARCHER = 2;
    }

    optional SourceType sourceType = 1;
    optional uint32 sourceId = 2;

    message Tag {
        required string name = 1;
        required string value = 2;
    }

    repeated Tag tags = 3;

    message Time {
        required uint32 year = 1;
        required uint32 month = 2;
        required uint32 day = 3;
        required uint32 hour = 4;
        required uint32 min = 5;
        required uint32 sec = 6;
        required uint32 milli = 7;
    }

    optional Time time = 4;

    message Location {
        required float lat = 1;
        required float lon = 2;
        required float alt = 3;
    }

    optional Location location = 5;

    message Pose {
        required float roll = 1;
        required float pitch = 2;
        required float yaw = 3;
    }

    optional Pose pose = 6;

    message Camera {
        enum CameraType {
            VIDEO = 0;
            STILL = 1;
        }

        optional CameraType type = 1;
        optional string name = 2;
        required Location location = 3;
        required float elevation = 4;
        required float azimuth = 5;
    }

    repeated Camera cameras = 7;
}

message StreamRequest {
     enum RequestType {
	  // start stream at a given frame
          START_STREAM_AT = 0;

	  // pause stream at current frame
          PAUSE_STREAM    = 1;

	  // request live stream
          LIVE_STREAM     = 2;
     }

     required RequestType requestType = 1;

     // which frame to start at
     optional uint32 frameIndex = 2;

     // if true, play stream forward otherwise play backwards, 
     // only valid for START_STREAM_AT requests
     optional bool forward    = 3 [default = true];

     // include telemetry with the stream
     optional bool includeTelemetry = 4 [default = false];
}

// request for a single frame
message FrameRequest {
     // which frame
     required uint32 frameIndex = 1;

     // package telemetry with requested image
     // how do we determine appropriate telemetry to
     // send...??
     optional bool includeTelemetry = 2 [default = false];
}

// header which preceeds raw image data
message Image {

     // image dimensions
     required uint32 width  = 1;
     required uint32 height = 2;

     // number of channels
     optional uint32 nChannels = 3 [default = 3];
     
     // image depth (8 bit... etc)
     optional uint32 depth = 4 [default = 8];

     // used by server for indicating to client index of frame
     optional uint32 frameIndex = 5;

     // size of image data to follow
     required uint32 dataLength = 6;
}

message Annotation {

     // frame this annotation belongs with
     required uint32 frameIndex = 1;

     // pixel coordinate of this annotation
     required int32 xPos = 2;
     required int32 yPos = 3;

     // name of annotation
     optional string label    = 4;

     // any descriptions
     optional string comments = 5;    
     
     // time annotation was created
     optional string timestamp = 6;

     enum StatusType
     {
	PENDING_REVIEW = 0;
        RESOLVED       = 1;
        .... what else??         
     }

     // status of annotation
     optional StatusType status    = 7;
}

message Error {
     enum ErrorType {
         BAD_FRAME_INDEX = 0;  // requested index was out of range or invalid
         NO_PLANE_COMM   = 1;  // no communication with the plane
         IMAGE_DATA_UNAVAILABLE = 2;  // no image data available
         TELEMETRY_UNAVAILABLE  = 3;  // no telemetry data available
         UNKNOWN = 4;  // anything else?         
     }
     required ErrorType errorType = 1;
}

message Message {
     // not sure yet...
}