Differences

This shows you the differences between two versions of the page.

Link to this comparison view

wisar:protocols [2014/08/11 19:22] (current)
tmburdge created
Line 1: Line 1:
 +==Summary==
 +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.
 +
 +==Questions to be Answered==
 +*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?
 +
 +==Google Proto-Types==
 +===Basic Packet Header===
 +<pre>
 +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; 
 +}
 +</​pre>​
 +
 +===Telemetry Request===
 +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.
 +<pre>
 +message TelemetryRequest {
 +    enum ReferenceType {
 +         ​TIMESTAMP ​  = 0;
 +         ​FRAME_INDEX = 1;
 +         ​MOST_RECENT = 2;
 +    }
 +    required ReferenceType referenceType = 1;
 +    optional string timestamp = 2;
 +    optional uint32 frameIndex = 3;
 +}
 +</​pre>​
 +
 +===Telemetry===
 +<pre>
 +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;
 +}
 +</​pre>​
 +
 +===Stream Request===
 +<pre>
 +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];
 +}
 +</​pre>​
 +
 +===Frame Request===
 +<pre>
 +// 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];
 +}
 +</​pre>​
 +
 +===Image===
 +<pre>
 +// 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;
 +}
 +</​pre>​
 +
 +===Annotation===
 +<pre>
 +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;
 +}
 +</​pre>​
 +
 +===Error===
 +<pre>
 +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;
 +}
 +</​pre>​
 +
 +===Message===
 +<pre>
 +message Message {
 +     // not sure yet...
 +}
 +</​pre>​
wisar/protocols.txt ยท Last modified: 2014/08/11 19:22 by tmburdge
Back to top
CC Attribution-Share Alike 4.0 International
chimeric.de = chi`s home Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0