Common message protocol between Driver and Client

This document is to describe a common way of communication between driver and client.

Definition

Device, kinds of hardware we supplied.

• OpenIMU
• OpenRTK
• Other devices

Driver, a middleware that connect device and UI client

• python-openimu
• Other python driver

Client, applications supply to user

• Web
• Mobile App

Data Flow

Overview This chart is to show relationship among Device, Driver and Client.

1. Device is the base, all outputs are from it.
2. Driver like a dispatch center, it controls commands and data from client and device.
3. Client responses to handle the data.

The main work flow would be,

1. Client connect Device via Driver, Driver send device info, configuration to Client.
2. Client get ready to receive data. Ask driver to start to send data.
3. Client render the output data to user.
4. Client stop receiving data, and send set parameters command to ask Driver update configuration of Device.
5. Client go on receiving data, and render new output data to user.

We can see more scenarios as below,

1. Command Communication. The command may contains get or set parameters, and do configuration, etc.
2. Passive Receiving Data from device. Client may periodically receive data from device.
3. Client’s behavior after receive output of device. Client will match configuration, and find proper render to display data.

Data Model Definition

JSON File

Following the openimu.json from python-openimu, Device may need public a json file, this file play as a bridge, we still need such file. And below definition should also be included in the file.

Example

// device.json
{
  name: 'OpenIMU300-EZ', // Device Name
  type: 'openimu', // Device Type
  appName: 'IMU 1.0.0'，// Firmware name and version
  description: 'A description for device',  
  inputParameters:[  // Input parameter defined for client
    { ... }
  ],
  userMessages:{
    inputPackets:[ // optional
      { ... }
    ],
    outputPackets:[  // output rules defined for client
      { ... }
    ]
  },
  bootloaderMessages:[ // optional
    { ... }
  ],
  CLICommands:[ // optional
    { ... }
  ]
}

Device Configuration

Driver should support to output device configuration to client, so that client can know which device connected and its status(basic info, connection status, etc). It also contains some rules of data render. Output, Input Parameter are basic configuration information.

• Output

Field	Data Type	Required	Description
name	string	Y	Packet name
graphs	array	Y	A collections of render
graphs/name	string	Y	Render name
graphs/renderType	string	N	Render Type. Possible value is 'lineChart' or 'map'. 'lineChart' as default
graphs/fields	array	Y	A list of field from packet
graphs/options	object	Y	Options of render, this depends on render type.

Example

{
  name:'nav',
  graphs: [
    {
      name:'this is a map render',
      renderType:'map',
      fields: [
        { name:'lat', display:'Latitude', unit:'deg' },
        { name:'lon', display:'Longitude', unit:'deg' },
        { name:'heading', display:'Heading', unit:'deg'} 
      ],
      options: {
        hasTrajectory: false
      }
    },
    ......
  ],
}

• Current supported renders

Line Chart Render

{
  name: 'A line chart',
  renderType: 'lineChart', // optional, default is lineChart
  fields: [
    { name:'time', display:'Time', unit:'msec' },
    { name:'xAccel', display:'X Accel', unit:'m/s' },
  ],
  options: {
    xAxis: { name:'time' },
    yAxis: [
      { name:'xAccel', color:'#ff0000'},
      { name:'yAccel', color:'#ffff00'},
       ......
    ]
  }
}

Map Render

{
  name:'this is a map render',
  renderType:'map',
  fields: [
    { name:'lat', display:'Latitude', unit:'deg' },
    { name:'lon', display:'Longitude', unit:'deg' },
    { name:'heading', display:'Heading', unit:'deg' } 
  ],
  options: {
    hasTrajectory: false
  }
}

Indicator Render

{
  name:'this is a indicator render',
  renderType:'indicator',
  fields: [
    { name:'roll', display:'Roll', unit:'deg' },
    { name:'pitch', display:'Pitch', unit:'deg' },
    { name:'heading', display:'Heading', unit:'deg' } 
  ]
}

• Input Parameter

Field	Data Type	Required	Description
id	number	Y	Parameter Id
category	string	N	Parameter
name	string	Y	Parameter Name
displayName	string	Y	Display Name
type	string	Y	Data Type of parameter. Allow values should be number, string, boolean
inputType	string	Y	select, multi select, input, input number, date, date range
options	array	N	Available for input type as select
range	array	N	Define the minimum and maximum, it looks like [min,max]
disabled	boolean	N	Set true if the parameter can be edited. false as default

Example

{
  id:1,
  category:'General',
  name:'port',
  displayName:'Server Port',
  type:'number',
  inputType:'input number',
  range:[0,65535]
}

Message Body

A general message body. Use this message format while communication between client and driver. Client raise a request with specified message body, driver response result. More message will be described in below message definition part.

• Request

Field	Data Type	Required	Description
method	string	Y	Message Name
params	object	N	Request parameter

Example

{
  method:'getConf'
}

• Response

Normally, the response contains return in result, and return error if there is exception at driver side.

Field	Data Type	Required	Description
method	string	Y	Message Name
result	object	N	Return Data
result/packetType	string	Y	The packet name of return
result/data	object	Y	The actual data in return

Example

Success
{
  method: 'getConf',
  result: {
    packetType:’conf’,
    data: {
      ....
    }
  }
}

Failure
{
  method: 'getConf',
  result: {
    packetType:’error’,
    data: {
      message:’error message’
    }
  }
}

Message Definition

There are some messages would be used in most of application.

Device Info

1. getDeviceInfo

Get information of a device, it tells user which device is connected, and summary of the device.

Request Parameters

Field	Value	Description
method	getDeviceInfo

Returns

Field	Data Type	Description
packetType	string	deviceInfo
data	array	A name-value pair array

Example

{
  method: 'getDeviceInfo',
  result: {
    packetType:'deviceInfo',
    data: [
      {name:'SN', value:'1808400316'},
      {name:'PN', value:'5020-3885-01'},
      {name:'App Version', value:'IMU 1.0.0'},
      ...
    ]
  }
}

Configuration

1. getConf

This message is used to get configurations from device, these configurations will contains editable parameters, output configurations, etc.

Request Parameters

Field	Value	Description
method	getConf

Returns

Field	Data Type	Description
packetType	string	conf
data	object
data/outputs	array	Refer to data model definition - Output
data/inputParams	array	Refer to data model definition - Input Parameter

Example

{
  method: 'getConf',
  result: {
    packetType:'conf',
    data: {
      outputs:{},
      inputParams:{},
    }
  }
}

2. getParams

Get all editable parameters with current value.

Request Parameters

Field	Value	Description
method	getParams

Returns

Field	Data Type	Description
packetType	string	inputParams
data	array

Example

{
  method: 'getParams',
  result: {
    packetType:'inputParams',
    data: [
      ...
    ]
  }
}

3. setParams

Request to update parameter(s)

Request Parameters

Field	Value	Description
method	setParams
params	array
params/paramId	number	Parameter Id
params/value	string	Parameter value

Example

{
  method:'setParams',
  params:[
   { paramId: 0, value: 123 },
   { paramId: 1, value: ’ABC’ },
     ...
  ]
}

Returns

Field	Value	Description
pack	setParams

Example

{
  method: 'setParams',
  result: {
    packetType:'success'
  }
}

4. saveConfig

Save parameters configuration permanently in device.

Request Parameters

Field	Data Type	Description
method	string	'saveConfig'

Returns (TODO: the return define is not good enough, should update)

Field	Data Type	Description
packetType	string	'success'
data	string or number	if the value is string, the value would be 'Command timeout'. If number, and number greater than 0, it means driver has a save error

Passive Receiving Data

1. startStream

Driver starts to send packet data to client after received this command. Client will match the packet type, then find the proper render from configuration to display data.

Request Parameters

Fields	Data Type	Description
method	string	'startStream'

Returns

Field	Data Type	Description
packetType	string	'success'

Example

{
  method: 'startStream',
  result: {
    packetType:'success'
  }
}

Passive Receing Data from Device The data may contains navigation packet, skyview packet, e2 packet or others

Field	Data Type	Description
packetType	string	'nav', 'skyview', 'e2', etc
data	object	Packet Data

Example 1

{
  method: 'stream',
  result: {
    packetType:'nav',
    data: {
      lon:38.6518,
      lat:104.07642
    }
  }
}

Example 2

{
  method: 'stream',
  result: {
    packetType:'e1',
    data: {
      timeCntr: 1201,
      time:1,
      roll:23,
      pitch:56,
      heading:0,
      ...
    }
  }
}

2. stopStream

Stop sending data to client if driver received the command

Request Parameters

Field	Data Type	Description
method	string	'stopStream'

Returns

Field	Data Type	Description
packetType	string	'success'

Example

{
  method: 'stopStream',
  result: {
    packetType:'success'
  }
}

Log Data

1. startLog

Upload the data from device to Azure Storage.

Request Parameters

Field	Data Type	Description
method	string	'startLog'
params	object
params/id	number	UserID
params/access_token	string	Current logged user's access token
params/fileName	string	File name input by user

Example

{
  method: 'startLog',
  params: {
    id: 239,
    access_token:’xx_yy_zz’,
    fileName:’xxx’
  }
}

Returns

Field	Data Type	Description
packetType	string	'success'
data	string	File name uploaded to Azure Storage

Example

{
  method: 'startLog',
  result: {
    packetType:'success',
    data:'xxx.csv'
  }
}

2. stopLog

Stop uploading data if driver received the command.

Request Parameters

Field	Data Type	Description
method	string	'stopLog'

Returns

Field	Data Type	Description
packetType	string	'success'
data	string	Empty string

Example

{
  method: 'stopLog',
  result: {
    packetType:'success',
    data:''
  }
}

Upgrade Framework

1. upgradeFramework

Start an upgrade request, then driver will send stream packet data to output the progress of upgrade.

Request Parameters

Field	Data Type	Description
method	string	'upgradeFramework'
params	string	'xxx.bin'

Example

{
  method:'upgradeFramework',
  params:'xxx.bin'
}

Returns

Field	Data Type	Description
packetType	string	'success'

Stream packet data for upgrade progress upgrade_progress

{
  method: 'stream',
  result: {
    packetType: 'upgrade_progress',
    data: { add: 240, fs_len: 101864}
  }
}

upgrade_complete

{
  method: 'stream',
  result: {
    packetType: 'upgrade_complete',
    data: { success: true }
  }
}

Mag Align

1. magAlignStart TODO

2. magAlignAbort TODO

3. magAlignSave TODO

4. magAlignStored TODO