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 |
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 disconnectsmessage - When Munic.Box sends a message on any channeltrack - When Munic.Box sends tracking dataWebhooks are configured from your Munic.Box account.
Here are the basic steps:
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.
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"
}
}]
Multiple data packets can be aggregated, and sent in one request to the client's server.
The 2 main use-cases:
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).
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.
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.
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.
We recommend using RequestBin to troubleshoot webhooks.
Returns tracks that match a specified query, or all tracks if no query is specified.
GET /tracks
q:
~ _Optional_ **string** - Search query. Should be URL encoded. Queries will be limited by complexity.
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`
GET /tracks?q=asset%3A356896033350886
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"
}
]
Return a single track, specified by the id parameter.
GET /tracks/:id
GET /tracks/342644193287471127
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"
}
Returns all applications.
GET /applications
Status: 200 OK
[
{
"id": "abc1234",
"name": "Twitter",
"type": "application",
"os": null,
"version": "2.1",
"min_os": "1.8",
"max_os": "2.0"
}
]
Show application.
The information returned contains the last application version’s information.
GET /applications/:id
GET /applications/abc1234
Status: 200 OK
{
"id": "abc1234",
"name": "Twitter",
"type": "application",
"os": null,
"version": "2.1",
"min_os": "1.8",
"max_os": "2.0"
}
Returns all versions of an application.
GET /applications/:id/versions
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"
}
]
Show a specific version of an application.
You need to replace all periods in the version number with underscores.
GET /applications/:id/versions/:version
GET /applications/abc1234/versions/2_0
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 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
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.
Status: 201 Created
{
"id": "abc1234",
"name": "Twitter",
"type": "application",
"os": null,
"version": "2.1",
"min_os": "1.8",
"max_os": "2.0"
}
Change what assets are allowed for this version.
PUT /applications/:id/versions/:version
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!
{
"allowed_assets":"1234abc,1234def,5678abc,1234ghi,9999abc"
}
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 of an application.
DELETE /applications/:id/versions/:version
Status: 204 No Content
Show all app requests.
GET /app_requests
[
{
"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
}
]
Show a specific app request.
GET /app_requests
{
"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."
}
]
}
POST /api/v3/app_requests/versions
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.
{
"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"
}
POST /api/v3/app_requests/updates
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.
{
"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
}
POST /api/v3/app_requests/:app_request_id/comments
content:
~ Required string – Body of the comment.
{
"id": "511e3e3361c4e301dc000008",
"content": "Hello world!"
}
List all configurations.
GET /api/v3/configurations
[
{
"id": "42",
"data" : {},
"signature": "cc767e391619ef72fa44bd724a6899be",
"targeted_assets": [ "351777040574871" ]
}
]
Get a specific configuration.
GET /api/v3/configurations/:configuration_id
{
"id": "42",
"data" : {},
"signature": "cc767e391619ef72fa44bd724a6899be",
"targeted_assets": [ "351777040574871" ]
}
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.
| Morpheus features | included |
|---|---|
| Rich IDE including a device emulator & complete toolsuite |  |
| Inexpensive solution | |
| Multi-application architecture | |
| Advanced system safety services | |
| Enhanced power management | |
| Integrated mapping primitive | |
| Transparent distributed (multi-board) resources access | |
| Full Modem driver (GPRS, SMS, 3G…) | |
| Complete & configurable tracking system | |
| Highly efficient and lightweight wireless data transfer protocol | |
| Telematics drivers (CAN, USB, accelerometer, IOs, BT, OBD…) | |
| Unique set of dedicated APIs to Telematics (more than 3000) | |
| Complete OTA administration capabilities | |
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 …)
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.
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 :
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:
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;
}
}
}