C# API wrapper demo

The C# wrapper example is designed to help you decode information and fields coming from CloudConnect and to help you implement your own connector.

Fields decoded by the wrapper are:

  • GPRMC_VALID
  • GPS_SPEED
  • GPS_DIR
  • DIO_IGNITION
  • ODO_FULL
  • DIO_ALARM
  • DRIVER_ID
  • DIO_IN_TOR

Description of every field retrieved by Munic.Box is detailed here: http://www.munic.io/documentations/how_it_works

With Nuget Package

Install-Package MD.CloudConnect

Manually

Dlls required for your project (available from library directory on github) :

  • MD.CloudConnect
  • Newtonsoft.Json (dependencie)

On your server create an HttpHandler.ashx to receive http notifications coming from CloudConnect. Read the message's body, and send the Json message (description below) to the function 'Notification Decode'. Make a loop on MDData response to retrieve information that you need.

Json data coming from CloudConnect

[{
    "meta": {
        "account": "AccountExample",
        "event": "message"
    },
    "payload": {
        "asset": "359551XXXXX6317",
        "channel": "example.channel",
        "created_at": "2012-07-25T15:07:12Z",
        "parent_id": null,
        "parent_id_str": null,
        "b64_payload": "SGVsbG8gZXhhbXBsZSBwYXlsb2Fk",
        "received_at": "2012-07-25T15:07:12Z",
        "recipient": "@@server@@",
        "recorded_at": "2012-07-25T15:07:10Z",
        "sender": "359551XXXXX6317",
        "thread_id": 339393147572322327,
        "thread_id_str": "339393147572322327",
        "type": "message",
        "id": 339393147572322327,
        "id_str": "339393147572322327"
    }
},{
    "meta": {
        "account": "AccountExample",
        "event": "track"
    },
    "payload": {
        "id": 342656641079967767,
        "id_str": "342656641079967767",
        "asset": "359551XXXXX6317",
        "recorded_at": "2012-08-03T14:25:25Z",
        "received_at": "2012-08-03T14:26:28Z",
        "loc": [2.36687, 48.78354],
        "fields": {
            "GPS_SPEED": {
                "b64_value": "AAAAKg=="
            }
        }
    }
}]

Please note that you need to answer and HTTP 200 ACK

Decoder function

    List decodedData = MD.CloudConnect.Notification.Instance.Decode(jsonData);
    foreach (MD.CloudConnect.MDData mdData in decodedData)
    {
        if (mdData.Meta.Event == "track")
        {
            ITracking tacking = mdData.Tracking;

            /** Use tracking.Longitude , tracking.Speed to read data **/
            mylongitude = tracking.Longitude;
            ...

            /** In case where you manage by yourself the data cache, you must
            ** check if field exist in MDData before to access it
            **/

             if(tracking.ContainsField(MD.CloudConnect.FieldDefinition.DIO_IGNITION.Key))   
                myIgnition = tracking.Ignition;
            ...
        }
    }

For more information about data on the cloud, please look at documentation

The Cloud Connect notification system only sends updated fields (if a recorded field is identical to the previous one, it is not resend) thus the previous state of each field must be stored. This library helps you by managing a part of this data cache. You only need to initialize the library with "Field" that you need and a special object MD.CloudConnect.IDataCache.

In the global.asax , Application_Start() :

    protected void Application_Start()
    {
        InitializeCloudConnect();
    }

    private void InitializeCloudConnect()
    {
        //List the field that you want in the notification result
        string[] fieldsThatINeed = new string[]
        {
            MD.CloudConnect.FieldDefinition.GPRMC_VALID.Key,
            MD.CloudConnect.FieldDefinition.GPS_SPEED.Key,
            MD.CloudConnect.FieldDefinition.GPS_DIR.Key,
            MD.CloudConnect.FieldDefinition.ODO_FULL.Key,
            MD.CloudConnect.FieldDefinition.DIO_IGNITION.Key,
            MD.CloudConnect.EasyConnect.MDI_DRIVING_JOURNEY.Key,
            MD.CloudConnect.EasyConnect.MDI_IDLE_JOURNEY.Key,
            MD.CloudConnect.EasyConnect.MDI_JOURNEY_TIME.Key
        };

        //initialize field and object (IDataCache)
        MD.CloudConnect.Notification.Instance.Initialize(fieldsThatINeed, MD.CloudConnect.Example.Tools.MyDataCacheRepository.Instance, true);
    }

An example of object that you could implement for IDataCache interface :

    public class MyDataCacheRepository : MD.CloudConnect.IDataCache
    {
        /* Singleton */
        protected static readonly MyDataCacheRepository _instance = new MyDataCacheRepository();
        public static MyDataCacheRepository Instance
        {
            get
            {
                lock (_instance)
                {
                    return _instance;
                }
            }
        }

        static MyDataCacheRepository()
        {

        }

        /* IDataCache */
        public DateTime getHistoryFor(string asset, ITracking data)
        {
            MyModelOfData lastTracking = MyPersistantRepo.GetLastTrackingDataFor(asset);

            if(lastTracking != null)
            {
                data.Speed = lastTracking.Speed;
                data.IsValid = lastTracking.IsValid;
                data.Direction = lastTracking.Direction;

                /*
                * ...
                */

                return lastTracking.Date;
            } else
                return DateTime.MinValue;
        }
    }

As the library does not manage persistance data, you need to fill the "GetHistoryFor" with the last information stored in your database.
The function "GetHistoryFor" will only be called once per Device (Asset) upon the start after start server when the library
will receive new data for an asset not present in the Data cache of the library.

In the case where you need a field which is not present you can use special function to decode directly your field :


    // ID is an optional parameter
    public static FieldDetail MY_FIELD = new FieldDetail() { Key = "MY_FIELD", Id = 212 };

    ITracking tracking = mdData.Tracking;

    if(tracking.ContainsField(MY_FIELD.Key))
        mypersonalData = tracking.GetFieldAsInt(MY_FIELD.Key);
    // you have also a function for string and boolean
    // GetFieldAsString
    // GetFieldAsBool

In the next page, you will see how you can use this library to receive data step by step.
See example