Getting Started

Monday, February 1, 2016

By Alex Lein

The purpose of the Event Message Format is to provide integrators and hardware vendors a common, extensible, easily serialized event format to quickly and easily deploy new hardware, and to satisfy edge-case customers.

Event Message Gateway Address

The exposed gateway uses UDP sockets for two-way communication at the following addresses.

emf.fleetfreedom.com:40012

and/or

67.223.104.99:40012

Introduction and Assumptions

Reading this document assumes you are familiar with:

JSON serialization.
Use of the Provisioning API to add providers to the system.
Using the WebSocket to update and deploy those providers.

Message Format

Of the four attributes in the JSON object, only two are required: id and data .

 {
   "id": string,
   "password": string,
   "data": {
     "<group name>": {
       "<data name>": {
         "value": object,
         "dts": string, /* datetime format */
         "unit": string
       }
     }
   },
   "ack": string
 }

Event Message
Property	Type	Required	Description
id	string	true	A unique identifier for this modem like ESN, IMEI, or some other hardware specific serial number. This identifier must be unique system wide and has a minimum length of 14 characters.
password	string	false	Just like the ProviderGeneral password, the Base64 encoded Event Message password field is used to verify the authenticity of the data. Since this service is exposed to the Internet at large, validation of event data is strongly encouraged.
data	{group,{name,ProviderData}}	true	Where all the event data is stored. Each item in data is grouped by the ProviderDataGroup of data, and each group contains one or more pairs of ProviderDataName / ProviderDatas.
ack	string\|number	false	Used to send an acknowledgement message back through the UDP socket to the modem. So long as this value is not null or white-space, the value will be sent back to the modem unmodified. The reply message is not JSON serialized, just the raw value.

Simple GPS Message Format

 {
   "id": "12345674980123456",
   "password": "WW91IGRlY29kZWQgdGhlIHBhc3N3b3JkLCBnb29kIGZvciB5b3UgY2hhbXAh",
   "data": {
     "GPS": {
       "GPS_LATITUDE": {
         "value": 43.65695997,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "DEGREE"
       },
       "GPS_LONGITUDE": {
         "value": -79.56699282,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "DEGREE"
       },
       "GPS_SPEED": {
         "value": 32.6,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "KILOMETER_PER_HOUR"
       },
       "GPS_HEADING": {
         "value": -27.9,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "DEGREE"
       },
       "GPS_FIX_STATUS": {
         "value": true,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "NONE"
       }
     }
   }
 }

Complex GPS and IO Message Format

 {
   "id": "12345674980123456",
   "password": "WW91IGRlY29kZWQgdGhlIHBhc3N3b3JkLCBnb29kIGZvciB5b3UgY2hhbXAh",
   "data": {
     "GPS": {
       "GPS_LATITUDE": {
         "value": 43.65695997,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "DEGREE"
       },
       "GPS_LONGITUDE": {
         "value": -79.56699282,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "DEGREE"
       },
       "GPS_SPEED": {
         "value": 32.6,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "KILOMETER_PER_HOUR"
       },
       "GPS_HEADING": {
         "value": -27.9,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "DEGREE"
       },
       "GPS_FIX_STATUS": {
         "value": true,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "NONE"
       }
       },
         "IO": {
         "DIGITAL_INPUT_0": {
         "value": true,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "NONE"
       },
       "DIGITAL_INPUT_1": {
         "value": false,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "NONE"
       },
       "ANALOG_INPUT_0": {
         "value": 13.87,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "VOLT"
       },
       "ANALOG_INPUT_1": {
         "value": 0,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "VOLT"
       },
     },
     "CELL": {
       "CELLULAR_RSSI": {
         "value": -119,
         "dts": "2016-04-28T20:56:41Z",
         "unit": "db"
       },
       "CELLULAR_COMM_STATE": {
         "value": "on",
         "dts": "2016-04-28T20:56:41Z",
         "unit": "custom"
       }
     }
   }
 }