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_GPS_SPEED or MDI_OBD_SPEED (configuration available from the DeviceManager)

Standard configuration

The periodical algorithm is configured as such :

Name Description Standard configuration
minHeadingAngle Minimum value of angle (in degrees) requested to send a position. 40
minHeadingDistanceAngle Minimum distance (in meters) between two records in case of angle test. 50
minHeadingDistance Minimum distance (in meters) required since last record. 250
minHeadingFreq Minimum time (milliseconds) between 2 records (no angle test) 120000
maxHeadingDistance Maximum distance (in meters) between 2 records. 5000
maxHeadingFreq Maximum time (in milliseconds) between 2 records. Can be used to record points when the device is not moving. 300000

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.

IF ( !isValid(lastPos) && isValid(curPos)) THEN

Maximum Distance

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

Maximum time

Time (Allows record when the vehicle is not moving)

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

Heading Change

Heading (Allows recorded based on the GPS Direction)

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

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
  IF ((isMvt (lastPos) != isMvt (curPos)) THEN
    IF (PreviousStoppedPosition IS EMPTY “or” Distance (lastPos, curPos) >= minHeadingDistance) THEN
    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

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:

Device Table
Munic Box 2 MunicOS - Box2 v3.7
Munic Box MunicOS v3.6
Munic Box MunicOS v2.4
Munic Box MunicOS v2.1

On MunicOS v2.x

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

Field Name Format Description Size
Record_Reason string ‘type : state’ 3

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

Event Name Record_Reason Type States
Ignition On/Off 0 0: Ignition OFF / 1: Ignition ON
Idle in 1 "1:0;1:201" : No movement "1:0;1:204": No Ignition
Over speed 2 0: no Overspeed detected / 1: Overspeed detected
Over RPM 3 0: no Over RPM detected / 1: OverRPM detected
Idle out 4 4: external power supply / 8: Accelerometer movement detected / 128: Periodical Wake Up
Journey On/Off 5 0: OFF / 1: ON
Idling 6 0: OFF / 1: ON
Tow away 7 0: OFF / 1: ON
External battery low 12 0: Normal battery level / 1: Low external battery
DTC Malfunction Indicator Light (MIL) 13 0: MIL OFF / 1: MIL ON
DTC number 14 integer: number of listed DTC

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*

BEHAVE_ID Description
11 Harsh acceleration
10 Harsh braking
12 Left turn
13 Right turn

(*) 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)

Field Name

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.