Integrating an Indoor Position SDK with a Micello map requires only a few steps to provie a way for the position to be passed into the Micello Map SDK. The reference documentation for the Position class can be found here.

Terms

In this document, three parties are included for reference, the Micello Map SDK ("SDK"), the Position Supplier ("supplier") and the Developer ("developer").

Overview

The SDK provides the connector for the supplier, developer and the Micello map itself to display the position. The supplier provides the positions (either on regular intervals or on demand as needed), the map displays a visual represenation of the position (i.e. the blue dot) and the developer consumes the position for use in an application.

The SDK does not cache the position provided by the supplier. The supplier is the source of truth for the current position.

Instantiation

At map load, the supplier must provide the following functions for the SDK to use:

Callback

Added as the community option "geoposition.callback", this is a function that the supplier provides which is used when the developer requests the current position. This function takes one argument, a developer function which should be called when the position is ascertained. This is expected to be an asynchronous call.

Support Callback

Added as the community option "geoposition.supportCallback", this is a function that the supplier provided which is used when the developer requests the supportability for the current device. This function must return a Boolena (true/false). If this function is not provided, this will always return true.

Example of map instantiation with position integration

var map = L.map('map');

var community;
supplierGetPosition = function (developerCallback) {
      /* Supplier ascertains position via the supplier framework and then calls the developerCallback */
      var func = developerCallback;
      func(positionObject);
}

supplierDeviceIsSupported = function () { 
    /* Supplier ascertains support for given device and returns a Boolean */   
    if ( supported ) { return true; }
    else { return false; } 
}

L.micello.loader.on("indoorReady", function (e) {
    community = L.micello.community ( <!-- Map CID here ->, {
        key: <!--INSERT YOUR KEY HERE-->,
        geoposition: {
            enabled: true,
            callback: supplierGetPosition,
            callbackSupport: supplierDeviceIsSupported            
        }
    }).addTo(map);
});

Position Set

Once the map is instantiated, the supplier can provide the position at any time interval using the setPosition function. This will, in turn, set the "blue dot" marker on the map and fire an event with the supplied position object.

Building on the instantiation example, the following is a simplisitc example of setting the position. 

var map = L.map('map');
 
var community;
supplierGetPosition = function (developerCallback) {
      /* Supplier ascertains position via the supplier framework and then calls the developerCallback */
      var func = developerCallback;
      func(positionObject);
}
 
supplierDeviceIsSupported = function () { 
    /* Supplier ascertains support for given device and returns a Boolean */   
    if ( supported ) { return true; }
    else { return false; } 
}
 
L.micello.loader.on("indoorReady", function (e) {

    community = L.micello.community ( <!-- Map CID here ->, {
        key: <!--INSERT YOUR KEY HERE-->,
        geoposition: {
            enabled: true,
            callback: supplierGetPosition,
            callbackSupport: supplierDeviceIsSupported            
        }
    }).addTo(map);

   community.on ( 'indoorCommunityLoadComplete', function (e) {

       var positionObject = {
           coords: {
               latitude: <latitude in decimal degrees, required>,
               longitude: <longitude in decimal degrees, required>,
               accuracy: <in meters, required>,
               speed: <meters / second or null if unknown>,
               heading: <degrees of heading or null if unknown>,
               altitude: <in meters or null if unknown>,
               altitudeAccuracy: <in meters or null if unknown>
           },
           timestamp: <unix epoch in microseconds>
           lid: <Micello Level ID>
      }
      var position = community.getGeoPosition();
      position.setPosition(positionObject);

   });

});

Position Acquisition

Once the map is instantiated, a position can be acquired in multiple ways including listening for an event or requesting the position explicitly with a callback.

Event Listener

If the position supplier regularly updates the position, the developer can listen to the "indoorPositionUpdate" event which will be fired each time the supplier updates the position. The position object will be provided.

Expanding on the examples, above, the event listener method is as follows.

var map = L.map('map');
 
var community;
supplierGetPosition = function (developerCallback) {
      /* Supplier ascertains position via the supplier framework and then calls the developerCallback */
      var func = developerCallback;
      func(positionObject);
}
 
supplierDeviceIsSupported = function () { 
    /* Supplier ascertains support for given device and returns a Boolean */   
    if ( supported ) { return true; }
    else { return false; } 
}
 
L.micello.loader.on("indoorReady", function (e) {
    community = L.micello.community ( <!-- Map CID here ->, {
        key: <!--INSERT YOUR KEY HERE-->,
        geoposition: {
            enabled: true,
            callback: supplierGetPosition,
            callbackSupport: supplierDeviceIsSupported            
        }
    }).addTo(map);


   community.on ( 'indoorCommunityLoadComplete', function (e) {

       /* Supplier information */
       var positionObject = {
           coords: {
               latitude: <latitude in decimal degrees, required>,
               longitude: <longitude in decimal degrees, required>,
               accuracy: <in meters, required>,
               speed: <meters / second or null if unknown>,
               heading: <degrees of heading or null if unknown>,
               altitude: <in meters or null if unknown>,
               altitudeAccuracy: <in meters or null if unknown>
           },
           timestamp: <unix epoch in microseconds>
           lid: <Micello Level ID>
      }
      var position = community.getGeoPosition();
      position.setPosition(positionObject);


   });


  /* Event Listener method for acquiring the position */
  community.on("indoorPositionUpdate", function (e) {
    
    /* do something with the position */
    
  });

});

Position Request

The developer has the option to request the position in real time and not wait for an event to fire by utilizing the "getPosition" function. With this function, the developer provides a callback that will be fired when the position is ascertained. This is an asynchronous function call.

var map = L.map('map');
 
var community;
supplierGetPosition = function (developerCallback) {
      /* Supplier ascertains position via the supplier framework and then calls the developerCallback */
      var func = developerCallback;
      func(positionObject);
}
 
supplierDeviceIsSupported = function () { 
    /* Supplier ascertains support for given device and returns a Boolean */   
    if ( supported ) { return true; }
    else { return false; } 
}
 
L.micello.loader.on("indoorReady", function (e) {
    community = L.micello.community ( <!-- Map CID here ->, {
        key: <!--INSERT YOUR KEY HERE-->,
        geoposition: {
            enabled: true,
            callback: supplierGetPosition,
            callbackSupport: supplierDeviceIsSupported            
        }
    }).addTo(map);
 
   /* Position request */
   developerCallback = function (position) {
       /* Do something with the position when supplier calls this function */
   }
   var position = community.getGeoPosition();
   position.getPosition(developerCallback);

 
});

Default Position Supplier

If the position class is enabled but a callback is not provided, the default supplier will be used. The default is the HTML5 Geolocation API.

Example of instantiation with the default in use:

var map = L.map('map');
 
var community;
 
L.micello.loader.on("indoorReady", function (e) {
    community = L.micello.community ( <!-- Map CID here ->, {
        key: <!--INSERT YOUR KEY HERE-->,
        geoposition: {
            enabled: true    
        }
    }).addTo(map);

});