Cloud SDK

The CloudSDK allows you to connect your application to Munic.Box in a very easy and efficient way.

Open for all is the Data Notification (webhook) mechanism that pushs instantly data to your server through an HTTP POST request. We offer also a webservice interface that brings additional features, this access is restricted.

Feature Description Access
Webhook Real time forwarding of data from Munic.Box to an external configurable URL via POST requests
Rest API REST webservice API provides a simple interface for most CloudConnect features such as data collection and the application store accessible from the store
Premium SDK Software development kit that enables you to develop your own embedded application thanks to its framework that includes more than 3000 APIs Request Premium SDK

Available

Mechanism

Whenever Munic.io Cloud receives some event data from an asset, it will forward the event to a configured webserver via a POST HTTP(S) request, also known as WebHook. These "WebHooks" can be used to update an external database, mirror a backup or trigger mail alert or anything you want.

Every request have to be acknowledge by an HTTP 200 OK response.

WebHooks can be triggered by the following events:

  • presence - When Munic.Box connects or disconnects
  • message - When Munic.Box sends a message on any channel
  • track - When Munic.Box sends tracking data

Configuring Webhooks

Webhooks are configured from your Munic.Box account.

Here are the basic steps:

  • Log in to your Munic.Box account
  • Click Get data on my server on the left menu list
  • Enter your URL linked to your endpoint
  • Submit
  • The Webhook will be configured to your URL within 24 hours
  • You are not receiving anything? Check the status

Receiving a webhook

When an event is created on our servers, we'll POST a notification to your URL. The body of the POST will be a JSON-encoded document.
The JSON document is a list of event objects, each object has the account, event and payload field.

Details about the HTTP protocol

  • protocol version HTTP/1.1
  • support for secure connection via HTTPS
  • persistent connection (HTTP KeepAlive) enabled to reduce HTTP connection overhead
  • data type is given with the http header "content-type=application/json"

HTTP message body

Here is an example body with the 3 type of data quoted above:

[{
     "meta": {
         "account": "municio",
         "event": "track"
     },
     "payload": {
         "id": 462903834012811477,
         "connection_id": 630740379448115201,
         "id_str": "462903834012811477",
         "connection_id_str": 630740379448115201,
         "index": 84,
         "asset": "3573220418T04458",
         "recorded_at": "2016-07-01T06:44:06Z",
         "recorded_at_ms": "2016-07-01T06:44:06.000Z",
         "received_at": "2016-07-01T08:54:35Z",
         "fields": {
             "MDI_VEHICLE_STATE": {
                 "b64_value": "MToy"
             },
             "MDI_IDLE_JOURNEY": {
                 "b64_value": "AAAAAQ=="
             },
             "MDI_JOURNEY_TIME": {
                 "b64_value": "AAAAAQ=="
             },
             "MDI_EXT_BATT_VOLTAGE": {
                 "b64_value": "AAA1pQ=="
             },
             "MDI_RECORD_REASON": {
                 "b64_value": "NTox"
             }
         }
     }
 } ,
 {
     "meta": {
         "account": "municio",
         "event": "message"
     },
     "payload": {
         "id": 339393147572322327,
         "parent_id": null,
         "connection_id": 630740379448115201,
         "id_str": "339393147572322327",
         "parent_id_str": null,
         "connection_id_str": "630740379448115201",
         "type": "message",
         "channel": "example.channel",
         "sender": "3573220418T04458",
         "recipient": "@@server@@",
         "asset": "3573220418T04458",
         "b64_payload": "U2VuZCByZWluZm9yY2VtZW50cw==\n",
         "received_at": "2016-07-01T08:54:38Z",
         "recorded_at": "2016-07-01T06:44:25Z"
     }
 },
 {
     "meta": {
         "account": "municio",
         "event": "presence"
     },
    "payload": {
        "id": 339376253389766678,
        "connection_id": 916016555014226291,
        "id_str": "339376253389766678",
        "connection_id_str": "916016555014226291",
        "asset": "3573220418T04458",
        "time": "2016-07-01T08:54:39Z",
        "type": "disconnect",
        "reason": "socket_closed"
     }
 }]

Packet aggregation

Multiple data packets can be aggregated, and sent in one request to the client's server.

The 2 main use-cases:

  • The client's url is up and running with devices deployed. In this case, data packets arrive on the Cloud and they are notified a few seconds later. If a packet arrives alone, it is sent alone. If there is a large number of connected devices and/or a high data throughput however (which is directly related to the client's configuration), multiple packets are likely to arrive concurrently and will be bundled and sent together.
  • The client's url is down for maintenance. In this case, packets will be queued until the url is back up and running, and the queue will then be emptied by aggregating the maximum number of data packets that will fit in the configured packet size for the url and sending them in one request.

In either case, a variable number of data packets will be sent in one request. If enough data is aggregated to reach the upper size limit, it is not abnormal to have requests with several thousand tracking data (but that depends on how many field values each tracking datum contains, as per the device's configuration).

Retry policy

If the customer's HTTP web server is not reachable or doesn't acknowledge the requests in time (responding with a 200 OK HTTP code), connections are retried with an exponential backoff. The maximum amount of time between 2 retries is around 5 minutes.

We'll keep the data internally to retry for 1 week.

Ordering

Please notice that as we added some mechanisms to optimize real-timeness of the notification, we cannot guarantee strict ordering or that no duplicates will be sent.

Whenever possible, be assured that we'll try our best to deliver ordered (for a device) & not duplicated messages.

Message de-duplication and ordering, for a specific asset, can be done with the 'id' attribute.

Responding to a webhook

To acknowledge that you received the webhook without any problem, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. When a webhook is not received for whatever reason, Munic.Box will continue trying to send the webhook once an hour for up to 6 days.

Troubleshooting

We recommend using RequestBin to troubleshoot webhooks.

Available

Data Collection

Tracks methods

List tracks

Returns tracks that match a specified query, or all tracks if no query is specified.

GET /tracks

Parameters

q:
~ _Optional_ **string** - Search query. Should be URL encoded. Queries will be limited by complexity.

Query String parameters

The default scope (if you don't provide a key) will search for the provided text in id, asset.

ret:
~ Parameters to return
~ _allowed:_ `id,asset,recorded_at,received_at,location,fields,url`
~ _default:_ `id,asset,recorded_at,received_at,location,fields,url`

Example

GET /tracks?q=asset%3A356896033350886

Response

Status: 200 OK
Link: ; rel="next",
      ; rel="last"
[
  {
    "id": 342644193287471127,
    "id_str": "342644193287471127",
    "asset": "355131040629069",
    "recorded_at": "2012-08-03T12:22:45Z",
    "received_at": "2012-08-03T12:25:41Z",
    "location": [
      2.36657,
      48.78388
    ],
    "fields": {
      "GPS_SPEED": {
        "b64_value": "AGl2"
      }
    },
    "url": "http://demo.integration.cloudconnect.io/api/v3/tracks/342644193287471127"
  },
  {
    "id": 342637265832378391,
    "id_str": "342637265832378391",
    "asset": "355131040629069",
    "recorded_at": "2012-08-03T11:55:22Z",
    "received_at": "2012-08-03T11:58:10Z",
    "location": [
      2.36656,
      48.78387
    ],
    "fields": {
      "GPRMC_VALID": {
        "b64_value": "QQ=="
      },
      "GPS_SPEED": {
        "b64_value": "AEnT"
      },
      "GPS_DIR": {
        "b64_value": "AAzk"
      }
    },
    "url": "http://demo.integration.cloudconnect.io/api/v3/tracks/342637265832378391"
  }
]

Get a single track

Return a single track, specified by the id parameter.

GET /tracks/:id

Example

GET /tracks/342644193287471127

Response

Status: 200 OK
{
  "id": 342644193287471127,
  "id_str": "342644193287471127",
  "asset": "355131040629069",
  "recorded_at": "2012-08-03T12:22:45Z",
  "received_at": "2012-08-03T12:25:41Z",
  "location": [
    2.36657,
    48.78388
  ],
  "fields": {
    "GPS_SPEED": {
      "b64_value": "AGl2"
    }
  },
    "url": "http://demo.integration.cloudconnect.io/api/v3/tracks/342644193287471127"
}

Application Store API

Application methods

List applications

Returns all applications.

GET /applications

Response

Status: 200 OK
[
  {
    "id": "abc1234",
    "name": "Twitter",
    "type": "application",
    "os": null,
    "version": "2.1",
    "min_os": "1.8",
    "max_os": "2.0"
  }
]

Get a specific application

Show application.

The information returned contains the last application version’s information.

GET /applications/:id

Example

GET /applications/abc1234

Response

Status: 200 OK
{
  "id": "abc1234",
  "name": "Twitter",
  "type": "application",
  "os": null,
  "version": "2.1",
  "min_os": "1.8",
  "max_os": "2.0"
}

Application version methods

List application versions

Returns all versions of an application.

GET /applications/:id/versions

Response

Status: 200 OK
[
  {
    "version": "1.0",
    "allowed_assets": [],
    "allowed_previous_versions": [],
    "ota_allowed_previous_versions": [],
    "os": null,
    "min_os": "1.7",
    "max_os": "2.0"
  }, {
    "version": "2.0",
    "allowed_assets": ["all"],
    "allowed_previous_versions": ["1.0"],
    "ota_allowed_previous_versions": ["1.0"],
    "os": null,
    "min_os": "1.8",
    "max_os": "2.0"
  }, {
    "version": "2.1",
    "allowed_assets": ["1234abc"],
    "allowed_previous_versions": ["1.0", "2.0"],
    "ota_allowed_previous_versions": ["1.0", "2.0"],
    "os": null,
    "min_os": "1.8",
    "max_os": "2.0"
  }
]

Get a specific version

Show a specific version of an application.

You need to replace all periods in the version number with underscores.

GET /applications/:id/versions/:version

Example

GET /applications/abc1234/versions/2_0

Response

Status: 200 OK
{
  "app": "abc1234",
  "name": "Twitter",
  "version": "2.0",
  "allowed_assets": ["1234abc"],
  "allowed_previous_versions": ["1.0"],
  "ota_allowed_previous_versions": ["1.0"],
  "os": null,
  "min_os": "1.8",
  "max_os": "2.0"
}

Create a new version

Create a version of an application .

The version number has to be superior to the last version with the same primary number.
For instance, if versions 2.6 and 3.2 exist, then versions 2.7 and 3.3 will be accepted and versions 2.5 and 3.1 will be refused.

POST /applications:id/versions

Input

version:
~ _Required_ **string** – The version of the application.
file:
~ _Required_ – The application file, base64-encoded. Must be a valid .tar.gz file. The file must be provided as raw multipart data, not a URL.
min_os:
~ _Required_ **string** – The minimum required Core version number.
max_os:
~ _Required_ **string** – The maximum required Core version number. 

Response

Status: 201 Created
{
  "id": "abc1234",
  "name": "Twitter",
  "type": "application",
  "os": null,
  "version": "2.1",
  "min_os": "1.8",
  "max_os": "2.0"
}

Update a version

Change what assets are allowed for this version.

PUT /applications/:id/versions/:version

Input


allowed_assets
~ _required_ **array** – The list of assets that can be updated with this version, given as a string with imeis seperated by commas.  
~ :warning: This overwrites the list of allowed assets!

Example

{
  "allowed_assets":"1234abc,1234def,5678abc,1234ghi,9999abc"
}

Response

Status: 200 OK
{
  "version":"2.1",
  "min_os":1.8,
  "max_os":2.0,
  "allowed_assets":["1234abc","1234abc","1234def","5678abc","1234ghi","9999abc"],
  "allowed_previous_versions":[],
  "ota_allowed_previous_versions":[],
  "os":null
}

Delete a version

Delete a version of an application.

DELETE /applications/:id/versions/:version

Response

Status: 204 No Content

App request methods

List app requests

Show all app requests.

GET /app_requests

Response

[
  {
    "id":       "511e3e3361c4e301dc000004",
    "type":     "version_request",
    "status":   "waiting",
    "app_name": "MyApplication",
    "file_url": "http://",
    "file_md5": "",
    "version":  "1.0",
    "accounts": [ "test_account" ],
    "min_os":   "",
    "max_os":   ""
  },
  {
    "id":           "511e3e2461c4e301dc000003",
    "type":         "update_request",
    "status":       "waiting",
    "app_name":     "MyApplication",
    "file_url":     "http://",
    "file_md5":     "",
    "from_version": "1.0",
    "to_version":   "2.0",
    "ota_allowed":  false
  }
]

Get a specific app request

Show a specific app request.

GET /app_requests

Response

{
  "id":       "511e3e3361c4e301dc000004",
  "status":   "waiting",
  "app_name": "MyApplication",
  "version":  "1.0",
  "accounts": [ "test_account" ],
  "file_url": "http://",
  "file_md5": "",
  "min_os":   "",
  "max_os":   "",
  "comments": [
    {
      "user":    "test_user",
      "account": "test_account",
      "content": "Some content."
    },
    {
      "user":    "Admin",
      "account": "Mobile Device",
      "content": "Some content."
    }
  ]
}

Create a new version request

POST /api/v3/app_requests/versions

Input

app_name:
~ Required string – Name of the app.

version:
~ Required string – The version number.

file_url:
~ Required string –  URL of binary file.

file_md5:
~ Optional string – Checksum of the binary file.

min_os:
~ Optional string – The minimum required Core version number.

max_os:
~ Optional string – The maximum required Core version number.

accounts:
~ Optional array – Names of targeted accounts as an array.

comment:
~ Optional string – Free text used as comment.

Response

{
  "id":       "511e3e3361c4e301dc000009",
  "status":   "waiting",
  "app_name": "MyApplication",
  "version":  "2.0",
  "accounts": [ "test_account", "other_test_account" ],
  "file_url": "http://example.org/my_binary_file",
  "file_md5": "5a9dbf1850fd9054a454d70f3fb24816",
  "min_os":   "3.0",
  "max_os":   "3.2"
}

Create a new update request

POST /api/v3/app_requests/updates

Input

app_name:
~ Required string – Name of the app.

from_version:
~ Required string – Version number before.

to_version:
~ Required string – Version number after.

file_url:
~ Required string –  URL of binary file.

file_md5:
~ Optional string – Checksum of the binary file.

ota_allowed:
~ Optional boolean – Is OTA update allowed? Default is `true`.

comment:
~ Optional string – Free text used as comment.

Response

{
  "id":           "511e3e3361c4e301dc000009",
  "status":       "waiting",
  "app_name":     "MyApplication",
  "from_version": "2.0",
  "to_version":   "2.1",
  "file_url":     "http://example.org/my_binary_file",
  "file_md5":     "5a9dbf1850fd9054a454d70f3fb24816",
  "ota_allowed":  true
}

Add a comment to an app request

POST /api/v3/app_requests/:app_request_id/comments

Input

content:
~ Required string – Body of the comment.

Response

{
  "id":      "511e3e3361c4e301dc000008",
  "content": "Hello world!"
}

Configuration methods

List configurations

List all configurations.

GET /api/v3/configurations

Response

[
  {
    "id":              "42",
    "data" :           {},
    "signature":       "cc767e391619ef72fa44bd724a6899be",
    "targeted_assets": [ "351777040574871" ]
  }
]

Get a specific configuration

Get a specific configuration.

GET /api/v3/configurations/:configuration_id

Response

{
  "id":              "42",
  "data" :           {},
  "signature":       "cc767e391619ef72fa44bd724a6899be",
  "targeted_assets": [ "351777040574871" ]
}

available

Overview

Morpheus3 OS is a complete software platform: an Operating System based on Linux + a Middleware and a framework providing a very rich set of APIs for the development of telematics applications.
More than 3,000 APIs are available today, including complete access to the navigation and the graphical engine.
Morpheus3 Open Telematics OS handles every part of a telematics application, allowing developers to focus on their specific requirement.

Features

Morpheus features included
Rich IDE including a device emulator & complete toolsuite Available
Inexpensive solution Available
Multi-application architecture Available
Advanced system safety services Available
Enhanced power management Available
Integrated mapping primitive Available
Transparent distributed (multi-board) resources access Available
Full Modem driver (GPRS, SMS, 3G…) Available
Complete & configurable tracking system Available
Highly efficient and lightweight wireless data transfer protocol Available
Telematics drivers (CAN, USB, accelerometer, IOs, BT, OBD…) Available
Unique set of dedicated APIs to Telematics (more than 3000) Available
Complete OTA administration capabilities Available

Advantages

Morpheus3 OS key advantages are:

• Runs all applications simultaneously
• Service oriented: allows the execution of applications independently developed by third parties covering a variety of vertical markets (transportation, insurance & tolling, consumer applications, SVR etc…)
• Designed for the in-car specific requirements: power modes, vehicle interfaces, lowest cost communications, adapted HMI…
• Support of the widest range of telematics devices: from very low end black boxes to high end connected navigation
• Lowest cost: no “third party” costs besides the navigation engine
• Support the latest processors (ARM9, ARM11, Cortex, PowerPC, Atom …)

Integrated Development Environment (IDE)

available

Device Manager

In the device manager, you can check if data notification is active for your account and works fine. You can also change the configuration of your devices.

Connector


We created some library in ruby and C# to easily integrate your platform with CloudConnect. You can have more details :

you can see code example here :

Decoding the fields

As soon as you will be connected to Munic.Box you will have to decode the payload of the fieds, that is containing 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 an example source code 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 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;
        }
    }
}