Skip to content

Home

Jump to bottom
Pooja Gulabchand Mishra edited this page Nov 17, 2022 · 43 revisions

Welcome to the Mist vBLE Android SDK wiki!

Table Contents:
Overview
Requirements
App Permission
Integrate MistSDK
Initialize MistSDK
Getting Map Info
Getting Location Info
Lat/Long coordinate
Error Handling
Save SDK Client Name
Sample Apps
Documentation for MistSDK callbacks
Release Notes

Overview

Mist provides indoor blue dot navigation experience with 16 vBLE antenna array in Mist Access Point. This guide will provide detailed information on our Android SDK. It will help you configure application to integrate Mist SDK and initialize location services.

MistSDK DR uses dead reckoning approach to calculate user’s current position by using a previous position and advancing that position based on known and estimated speeds over elapsed time. Meaning DR is designed to take all location information available that a user had when connected and work the same as though the client is connected, even when experiencing a disconnect or blimp in the connection.

Mist android vBLE SDK supports following features:
1. Zones and vBLE events callbacks .
2. Background Mode .
3. App Wake Up .
4. Maps Supported .

Requirements

  • Android Studio: 4.0 or later
  • Minimum Android SDK: API 26
  • Target Android SDK: API 29
  • Latest Mist SDK
  • Mist AP wireless network infrastructure
  • BLE enabled android device
  • Access to Mist Account

App Permissions:

Mist SDK will require bluetooth and location services to function on your device. Declare the following permission(s) in your application manifest file. For example:

<manifest ... >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_GPS" />
    <uses-permission android:name="android.permission.BLUETOOTH" />
    <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
  ...
</manifest>

To compile version 31 or above, add the following additional permissions in the manifest file.

<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

Integrate MistSDK

MistSDK can be integrated by using one of the following ways in your android app project:

JCenter (Recommended)

Add the following to your app module build.gradle, This will take care of both Mist Core SDK and DR SDK

implementation 'com.mist:core-sdk:2.1.29'

or

Manual Adding mistsdk-framework.aar

While manually setting up SDK, include both 'Mist Core SDK' and 'DR SDK' in you application project.

  • Download mist-framework.aar' and 'mist-mobile.aar' from SDK Releases
  • Add following to app/build.gradle in dependencies
implementation(name:'mist-framework', ext:'aar')
implementation(name:'mist-mobile', ext:'aar')
implementation fileTree(include: ['*.jar'], dir: 'libs')

In project/build.gradle, add following in repositories

flatDir { dirs 'libs'}

Other Set up(Required):

For API level 28 (Android 9.0) or above, you must include the following declaration within the element of AndroidManifest.xml.

<uses-library android:name="org.apache.http.legacy" android:required="false" />

Add the following in App/build.gradle, to implement the web socket dependencies:

implementation "org.java-websocket:Java-WebSocket:1.4.0"

For more details please refer to one of the Sample Apps

Initialize MistSDK

To initialize Mist SDK you need organization secret and organization id.

  1. Obtain the invitation for Mobile SDK secret(sdktoken) from the Mist portal at the following path: Organization -> Mobile SDK -> secret.
    [Refer FAQs: where can I find my secret key?]
    Use the sdktoken to obtain the org_id and secret via onReceivedSecret callback method from MSTOrgCredentialsManager:
 MSTOrgCredentialsManager.enrollDeviceWithToken(mApp.get(), sdkToken, this);
 @Override
 public void onReceivedSecret(String orgName, String orgID, String sdkSecret, String error, String envType) {
     if (!TextUtils.isEmpty(sdkSecret) && !TextUtils.isEmpty(orgID) && !TextUtils.isEmpty(sdkSecret)) {
         saveConfig(orgName, orgID, sdkSecret, envType);
         connect(indoorOnlyListener, this.advanceListener, appMode);
     } else {
         if (!Utils.isEmptyString(error)) {
             if (indoorOnlyListener != null) {
                 indoorOnlyListener.onMistErrorReceived(error, new Date());
             }
         }
     }
 }
  1. Use the org_id and secret to initialize the MSTCentralManager. To use the location methods, implement the MSTCentralManagerIndoorOnlyListener and MistLocationAdvanceListener.

  • MSTCentralManagerIndoorOnlyListener is used to fetch x, y coordinates, map details, vBeacons list, zone and vBeacon notifications.

  • MistLocationAdvanceListener provides advance callbacks to fetch the Lat/Lon, Speed and direction along with relative x, y coordinate.

      mstCentralManager = new MSTCentralManager(mApp.get(), orgData.getOrgId(), orgData.getSdkSecret());
  mstCentralManager.setMSTCentralManagerIndoorOnlyListener(indoorOnlyListener);
  mstCentralManager.setMistLocationAdvanceListener(advanceListener);
  1. Set Cloud Environment - The environment is identified based on the first char of the Mobile SDK secret obtained from the Mist UI Portal. If your Org is in environment such as EU or GCP, the Mobile SDK secret should start with 'E' or 'G' respectively. By default, envType is set to 'Production' by the SDK.
  1. Call start API of MSTCentralManager to start the SDK: 
    mstCentralManager.start();
  2. Call stop on MSTCentralManager to stop receiving callbacks from Mist SDK: 
    mstCentralManager.stop();

Getting Map Info:

  • Map Information: Map details such as mapId, mapName, mapImageURL, mapOrigin, width and height are received in onMapUpdated Callback. This method is called to load the new map or update the map while switching floors and sites.
void onMapUpdated(MSTMap map, Date dateUpdated)

MSTMap object contains following Mist map information:
mapName
mapId
mapImageURL
mapType
mapOrigin
mapScale
mapWidth and mapHeight
ppm (pixel per meter)

Getting Location info:

Location response is used to know the position of the user in that particular floorplan. It is mostly represented as a blue-dot on the map.

To get location information from Mist SDK implement MSTCentralManagerIndoorOnlyListener interface. Following method returns updated location of the device as an MSTPoint object (X, Y) measured in meters from the map origin:

Relative coordinates based on top-left origin in meters (x, y)

void onRelativeLocationUpdated(MSTPoint var1, MSTMap[] var2, Date var3);

To get a snapped location estimate from Mist SDK implement MistLocationAdvanceListener interface. The following method returns the updated snapped location estimate of the device as an MSTPoint object (X, Y) measured in meters from the map origin:

DR Snapped coordinates based on top-left origin in meters (x, y) - (Recommended)

void onDRSnappedLocationUpdated(final MSTPoint var1, final MSTMap var2, Date var3);

We recommend using onDRSnappedLocationUpdated to get better location accuracy.

MSTPoint object contains the following user information:

  • x, y: user location
  • hasMotion: is the user in motion,
  • mstPointType: type Cloud,
  • latency: latency in the network,
  • heading: compass heading,
  • headingFlag: availability of compass heading

Lat/Long coordinate

To get Lat/Lon information along with x/y from the SDK, you need to implement MistLocationAdvanceListener callbacks in your application. Following method returns the Lat/Lon.

void onDRRelativeLocationUpdated(JSONObject var1, MSTMap var2, Date var3);

The latitude and longitude coordinate can be found inside the JSONObject.

{
  "Raw": {
    "Heading": -180,
    "Lat": 36.562600,
    "Lon": -118.957490,
    "Speed": 1.152899
  },
  "Snapped": {
    "Heading": -180,
    "Lat": 36.562600,
    "Lon": -118.957490,
    "Speed": 1.152899
    
  }
}

Error handling

Now if there is Auth failure in SDK, it will stop the SDK and inform the App via the following callback.

  public void didErrorOccurWithType(ErrorType errorType, String details)

ErrorType

· ErrorTypeAuthFailure: will return when MSTCentralManager uses an incorrect or expired secret for initialization. This secrets will be refreshed after every 30 days. The App Developer must implement the ErrorHandling callback to re-enroll the device once the existing token has expired.

· ErrorTypeServerOverloaded: will return when backoff is triggered due to server overload. SDK will pause for a given amount of time before retrying to connect.
· ErrorTypeNoBeaconsDetected : will return when device is not in BLE Proximity.

No action is required from the Mobile App in case of “ErrorTypeServerOverloaded”

 public void didErrorOccurWithType(ErrorType errorType, String details) {
        Log.e(TAG, details);
        if (errorType == ErrorType.ErrorTypeAuthFailure) {
            //Re-enroll device on expiration or invalid token
        }
 }

Save SDK client name

You can update the app client name from the app using mstcentralManagerObj.saveClientInformation(). You should add the saveclientInfo once the Mist Listeners' callback response starts coming in. By default client name is Anonymous.
Key: ‘name’
Value: ‘App-client-name’

//java
self.manager?.saveClientInformation("name":"Mist-Appclient-Android")

Sample Apps

For more detail, you can see the implementation in the sample app here.

Documentation for MistSDK callbacks

For more callback related information refer Mist SDK callbacks page .

Released Notes

Check what's new in the release notes

For further questions please reach out to support@mist.com

Release Notes

Release Notes

Getting Started

Integration Guide

Clone this wiki locally