Data sent by Munic Box is notified to your back-end server using the webhook mechanism. Packets are sent in JSON and are categorized in 3 types:

• presence: contains connection and disconnection reasons
• message: corresponds to messages exchanged between the device and the Cloud
• track: corresponds to the tracking data

Your back-end server must handled all these types of JSON packets to avoid any internal error.

Presence packet description

The "presence" packets are generated when a device connects or disconnects and provide additional information on why the device connects to or disconnects.

Here is an example of "presence" packet:

 [{
     "meta": {
         "account": "municio",
         "event": "presence"
     },
     "payload": {
         "id": 580761513191538809,
         "id_str": "580761513191538809",
         "asset": "359858024342931",
         "time": "2014-05-22T14:18:54Z",
         "type": "disconnect",
         "reason": "network_activity_timeout"
     }
 }]

Note that the type of packet is provided in the meta field of the JSON file.

Track packet description

A "track" packet contains the data fields recorded by Munic Box. Fields recorded at the same time are aggregated in the same track packet.
A "track" packet contains the following properties:

• asset - The unique identifier of each Munic Box (IMEI of the wireless modem).
• recorded_at - The time at which the tracks have been recorded by the device. Timestamp is given by the GPS in UTC time.
• received_at - The time at which the crumbs has been received by the cloud. Timestamp is given by the GPS in UTC time.
• fields - An object containing string keys and string values, describing the data recorded by Munic Box.

Here is an example of track packet:

 [{
     "meta": {
         "account": "municio",
         "event": "track"
     },
     "payload": {
         "id": 580761614244905081,
         "id_str": "580761614244905081",
         "asset": "359858024375626",
         "recorded_at": "2014-05-22T14:18:57Z",
         "recorded_at_ms": "2014-05-22T14:18:57.000Z",
         "received_at": "2014-05-22T14:19:18Z",
         "loc": [2.34793, 48.83487],
         "fields": {
             "GPS_DIR": {
                 "b64_value": "AAA+Hg=="
             },
             "GPS_SPEED": {
                 "b64_value": "AAASCw=="
             }
         }
     }
 }]

Message packet description

A message is the privileged way to communicate in a bi-directional way between the devices and the CloudConnect platform. The messaging system use channel identifiers to multiplex communication according to specific services on the device.
For now, most of these channels are for internal use such as assisted GPS, versions and configurations management. It can also be used by any future module.

Here is an example of "message" packet:

 [{
     "meta": {
         "account": "municio",
         "event": "message"
     },
     "payload": {
         "id": 580747912137408642,
         "thread_id": null,
         "parent_id": null,
         "id_str": "580747912137408642",
         "thread_id_str": "",
         "parent_id_str": "",
         "type": "message",
         "channel": "com.mdi.dynamic_channel_configuration",
         "sender": "359858024351692",
         "recipient": "@@server@@",
         "asset": "359858024351692",
         "b64_payload": "g6hzZXJ2aWNlc5O9Y29tLm1kaS5zZXJ2aWNlcy5pbnN0YW50Rml4SUnaACVjb20ubWRpLnNlcnZpY2VzLmNvbmZpZ3VyYXRpb25NYW5hZ2Vyv2NvbS5tZGkuc2VydmljZXMuZHJpdmVyQmVoYXZpb3KndmVyc2lvbgGib3CsZ2V0c2VydmljZWlk",
         "recorded_at": "2014-05-22T13:24:51Z",
         "received_at": "2014-05-22T13:24:52Z"
     }
 }]

Field description

Fields contain the following properties:

• name - Name of the field
• field - Integer - ID of the field
• field_type - Type of the field. unknown | boolean | integer | decimal | string | base64
• size- Maximum size of the field in bytes
• ack - Does this field need to be acknowledged? If left blank (null), no ack is required, if 0 an ack is sent at once, if a positive integer, the ack is sent within the time specified (in seconds).

Below is an example of Field:

{
  "field": 8,
  "name": "GPS_SPEED",
  "size": 3,
  "ack": 1,
  "description": "Stores the last valid speed of the GPS in 1/1000th knots.",
}

-->Click here to get an overview of the standard available fields<--

The possibility for the user to create its own fields is restricted, please ask our support for more details.

Decoding the fields

As soon as you are connected to Munic Box you will have to decode the payload of the fields, that contains the data sent by Munic Box.
Here are the basic steps:

• Check the type of the fields that you are looking for in the How it works section
• Convert from base64 to adequate type (integer, boolean, ....)

Below is an example source code in C# to decode the base64 payload:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;

namespace MD.CloudConnect.Tools
{
    public class Base64Decoder
    {
        public static bool GetValueAsBool(string b64_value)
        {
            bool result = false;
            if (!String.IsNullOrEmpty(b64_value))
            {
                byte[] values = Convert.FromBase64String(b64_value);
                result = BitConverter.ToBoolean(values, 0);
            }
            return result;
        }

        public static int GetValueAsInt(string b64_value)
        {
            int result = 0;
            if (!String.IsNullOrEmpty(b64_value))
            {
                byte[] values = Convert.FromBase64String(b64_value);

                if (values.Length > 0)
                {
                    result = 0;
                    for (int i = 0; i < values.Length; i++)
                    {
                        result = result << 8;
                        result += values[i];
                    }
                }
            }
            return result;
        }

        public static double GetValueAsDouble(string b64_value)
        {
            double result = 0;
            if (!String.IsNullOrEmpty(b64_value))
            {
                byte[] values = Convert.FromBase64String(b64_value);
                result = BitConverter.ToDouble(values, 0);
            }
            return result;
        }

        public static string GetValueAsString(string b64_value)
        {
            string result = String.Empty;
            if (!String.IsNullOrEmpty(b64_value))
            {
                byte[] values = Convert.FromBase64String(b64_value);
                result = String.Empty;
                for (int i = 0; i < values.Length; i++)
                {
                    result += (char)values[i];
                }
            }
            return result;
        }
    }
}

While the OBD dongle is running, it records periodically the following fields based on a combination of time, distance and heading changes:

• MDI_GPRMC_VALID
• MDI_GPS_SPEED or MDI_OBD_SPEED (configuration available from the DeviceManager)
• MDI_GPS_DIR

Standard configuration

The periodical algorithm is configured as such :

Periodical algorithm

In order, to minimize the wireless footprint and to optimize the rendering of the trips on the map, Munic Box uses 4 independent conditions to define when a point must be recorded.

Last recorded position is not valid.

In the case of last GPS position not being valid, the next point will be recorded as soon as a valid position is captured.

Validity
IF ( !isValid(lastPos) && isValid(curPos)) THEN
Record
END IF

Maximum Distance

Distance (Allows periodic record based on the distance)
IF (Distance(lastPos, curPos) >= maxHeadingDistance) THEN
  Record
END IF

Maximum time

Time (Allows record when the vehicle is not moving)

IF (Time (lastPos, curPos) >= maxHeadingFreq) THEN
  Record
END IF

Heading Change

Heading (Allows recorded based on the GPS Direction)

IF (MinHeadingAngle != 0 &&
  Angle (lastPos, curPos) >= minHeadingAngle &&
  Distance(lastPos, curPos) >= minHeadingDistanceAngle) THEN
  Record
END IF

Minimum Distance and Time

Time and Distance (allows record when the vehicle moved enough)

IF (Time (lastPos, curPos) >= minHeadingFreq) THEN
  IF (Distance(lastPos, curPos) >= minHeadingDistance) THEN
    Record
  END IF
  IF ((isMvt (lastPos) != isMvt (curPos)) THEN
    IF (PreviousStoppedPosition IS EMPTY “or” Distance (lastPos, curPos) >= minHeadingDistance) THEN
      Record
    END IF
  END IF
END IF

Munic Box monitors the following events:

• Ignition on/off
• Idle in
• Overspeed
• Over RPM
• Idle out
• Journey state
• Idling state
• Tow away
• External battery low
• OBD MIL
• OBD DTC

The event based recording policy runs independently from the smart recording policy and it records additional fields upon the events listed above.
The following tables describe the fields recorded on each event:

On MunicOS v2.x

On MunicOS v2.x, the events monitored by Munic Box are reported in the Record_reason: MDI_RECORD_REASON.

Record_Reason and associated types and states are defined in the table below:

Example:
The Record_Reason 7:1 means that the OBD dongle has detected a Tow Away event.

On MunicOS v3.x

This record reason is DEPRECATED for versions MunicOS v3.x. Today, events recorded by Munic should be monitored using dedicated fields for each events (for example MDI_VEHICLE_STATE to monitor ignition, tow away & idling, or MDI_OVERSPEED to monitor overspeed events).
The tables provided above describe the recording policy of the fields to use (no MDI_RECORD_REASON field).

Standard Driver Behaviour detected patterns*

(*) Does not take into account specific pattern accessible through the 'Advanced Driver Behaviour' application accessible from the store.

Driving event

Below the information that is recorded when Munic Box detects a driving pattern (for more information on Driver Behaviour, check here)

When Munic Box is connected through the wireless network, Munic Box transmits the buffer of recorded data every 2 minutes.If Munic Box goes into idle mode with data remaining in the buffer, the buffer will be synchronized in non volatile Flash memory and protected until the next boot time. Thus, Munic Box should not lose any data, except in the case where the unit is unplugged during runtime. The size of the buffer is 1 Mbytes and data is compressed inside.

Moreover, Munic Box has an emission strategy: it only sends the field value if the value changes. For a given field, if the values at 2 consecutive records are the same, then the 2nd record value is not sent. Indeed, it is not necessary to send it again since it is already available on the server. The cache of the back-end server can be used to get the latest value received. Either the new received field value or the latest received value has to be used. Finally, this strategy is applicable to all the fields.