Starting to sketch our Octane2 protocol

octane2_protocol.md

Octane2

Connection

TCP socket connection with TLS.

Example Message

Uses JSON to represent the message (http://en.wikipedia.org/wiki/JSON).

{
   "msg_type":"header"
   "session":"QWERQW234523WEGERWTRHW"
   "version":2.0
}

{
   "msg_type":"beacon"
   "device_id":"QE254JE58S37JFG"
   "worker_name":"Steve Harding"
   "lat":127.23523
   "long":-37.24236
   "speed":99
   "heading":270
   "effective_at":20101225T00:00.00Z
   "gps_sats":24
   "hdop":1.3
   "ignition":true

   #These ones are optional, and won't be used for the iPhone
   "digital_io_1":false
   "digital_io_2":false
   "digital_io_3":false
   "digital_io_4":false
}

Header Arguments

• msg_type. Must be 'header'
• session. An token representing your user credentials.
• version. The version of the protocol used.

Beacon Arguments

• msg_type. Must be 'beacon'
• device_id. A unique string that identifies the GPS unit sending the update. This is typically the unit's serial number if available

worker_name ? why not id?

I was thinking of it from the perspective of an integrator, who won't know our internal ids. Although name might be too loose.

alternative forms perhaps, worker_id OR worker_name?

{
  header: {
   "session":"QWERQW234523WEGERWTRHW"
   "version":2.0
  }

  beacons: {
    {
      "device_id":"QE254JE58S37JFG"
      "worker_name":"Steve Harding"
      "lat":127.23523
      "long":-37.24236
      "speed":99
      "heading":270
      "effective_at":20101225T00:00.00Z
      "gps_sats":24
      "hdop":1.3
      "ignition":true

      #These ones are optional, and won't be used for the iPhone
      "digital_io_1":false
      "digital_io_2":false
      "digital_io_3":false
      "digital_io_4":false
    },
    {
      ... etc ... 
    }   
  }

}

{
  header: {

   # Required
   "session":”QWERQW234523WEGERWTRHW” 
   "version”:2.0

    # Optional
   "device_id":”QE254JE58S37JFG”
   "worker_name":"Steve Harding”
   "worker_id”:”2”
  }

  beacons: [
    {
       # Require
      "lat”:127.23523
      “lng":-37.24236
      "effective_at":20101225T00:00.00Z

      # Optional  
      "speed”:99 
      "heading”:270
      "gps_sats”:24
      "hdop”:1.3
      “vdop”:0.4
      "ignition”:true
      “altitude”: 123    
      “device_battery”:0.34

      #These ones are optional, and won't be used for the iPhone
      “input_1":false
      "input_2":false
      "input_3":false
      "input_4":false
    },
    {
      ... etc ... 
    }   
  ]
}