orchestr8 Location & Wayfinding SDK

 

Mobile App Development

The orchestr8 Location & Wayfinding SDK provides a map/navigation library for iOS and Android. The library enables any app to add site-specific Google Maps-like functionality with minimal software integration.

On both platforms, the library contains:

  • A view that is added to the view hierarchy
  • API integrations
  • A processor for location and wayfinding data

The view handles:

  • Loading:
    • SVG maps
    • Wayfinding data
    • Places of interest
  • Display:
    • User location and heading
    • Current route
    • Friend locations
    • Places of interest (POIs)
  • User interaction:
    • Zooming
    • Panning
    • Toggle user-centered map
    • Tap on POI for POI detail

API integrations make available data from native device APIs such as BLE and GPS, and from orchestr8 back-end services.

The location processor combines data obtained from the device and from the orchestr8 back-end to calculate position, routes, nearby places of interest, etc.


Quick Start

Quick start for iOS (Android is nearly identical):

    // Include MapView in your storyboard or programmatically ...
	@IBOutlet weak var mapView: MapView!
	...
	// And then in `viewDidLoad()`:
    let geoData = GeoData(declination: 15.36, latitude: 47.6104478, longitude: -122.3372017)
    let config = MapConfig(
       structureIdentifier: "MyCampus",
       wayfindingServiceUrl: "http://10.1.10.29:8086",
       gisServiceUrl: "http://10.1.10.29:8081",
       locationEngineUrl: "http://10.1.10.29:8096",
       reportingInterval: 5.0, // seconds
       geoData: geoData,
       startingLevelNumber: 3
    )
    mapView?.initialize(configuration: config, currentUser: currentUser, bundle: Bundle.main) { [weak self] err in
        if let error = err {
            self?.showAlert(errorMessage: "\(error)")
        }
        else {
            self?.mapView.startUpdatingLocation()
        }
    }

Concepts

  • Structure: A "structure" is the entire area to be mapped; typically a multi-level building, represented by multiple maps.
  • Level: An area (typically a single "floor") within a structure, represented by a single map.

Configuration

  • structureIdentifier: Arbitrary string that identifies your set of maps.
  • wayfindingServiceUrl: Endpoint for wayfinding data.
  • gisServiceUrl: Endpoint for gis (location) data.
  • locationEngineUrl: Endpoint for reporting user location.
  • reportingInterval: Frequency (in seconds) to report user location to back end.
  • geoData: Geophysical data (declination, lat, lon) that helps with system accuracy.
  • startingLevelNumber: Which level number to load upon init.

Location Services

The orchestr8 library provides real-time tracking of the user's location.

Location tracking is started by calling the library's startUpdatingLocation() method once initialization has completed.

Location tracking may use one or more site-specific technologies, including iBeacons, trackables and readers, GPS, inertial navigation, etc., to perform location estimation. At present, only iBeacons are enabled. All location processing, including Kalman filtering, is done on-device.

Location and heading updates are available programmatically.


Admin App

The orchestr8 Location & Wayfinding SDK includes an admin app that can be used to complete an iBeacon installation. The steps are:

  1. Create a set of known hardware locations in map space (using web and/or admin app);
  2. Install beacons at known hardware locations;
  3. Use the admin app to scan each beacon and associate its UUID with its location.

Once the association is made, iBeacon-based location services become available.


Wayfinding

Given a destination, the orchestr8 library provides route-finding and route display from the user's current location. All wayfinding processing is done on-device.

  • A route is requested by tapping on a POI or a friend and then tapping the "directions" button.
  • Routes may cross multiple levels.
  • User may request "accessible" route.*
  • Estimated time-to-destination is provided.*
  • Quick routes (eg., find closest bathroom) are available.*

Wayfinding is available programmatically.


A search field enables the user to search for a specific destination or feature (eg., rest rooms, elevators, etc.) and display the results on the map.


Places of Interest (POIs)

A CMS is available for creating POIs. These POIs are associated with places and/or areas of the structure and are displayed as markers on the map. Tapping on a marker triggers a back-end request, loading and displaying additional POI data and image. The POI popup contains a button that lets the user navigate to that POI.


Friends

Authenticated users may choose to share their current location with friends who are also using the system. Location updates are reported to the back end and each user can receive real-time friend locations on their own map. Each friend is essentially a POI that can be tapped on and navigated to.

Locations may also be shared via text message.*

Friend and POI data are available programmatically.


3D View

A 3D view lets the user view all levels of a multi-level structure, rather than one level (map) at a time.*


REST API Reference

CMS

The CMS task service provides a system for creating and managing versioned documents to represent places of interest (POIs), events, etc.. These documents may, optionally, be associated with a point or region on a map.

The service also provides endpoints for managing categories, keywords, and associated media files for the documents.

View CMS Task Service API Documentation here:

Wayfinding

The wayfinding task service provides a system for creating and managing SVG map assets.

The service also provides endpoints for managing:

  • Map metadata: structure and level information for the asset, along with related geophysical data.
  • Waypoints: a grid-like network of known locations in map space that are the basis for route-finding.
  • Connections: the relationships between a waypoint and its closest neighbors, including accessibility metadata.
  • Route-finding: find the best route between origin and destination.
  • User locations: most recent known location of users who opt into location-sharing.
  • POI locations: location information for places of interest.

View Wayfinding Task Service API Documentation here:

GIS

The GIS task service has some overlap with the wayfinding task service, but generally provides more low-level access. It is used to specify the location of installed equipment (such as iBeacons, sensors, etc.) and also to define subregions within maps. In addition to creating and managing map assets, waypoints, and connections it supports:

  • Static beacons
  • Sensors
  • Readers
  • Cameras
  • Hardware locations

The service also provides the endpoint for real-time user location reporting.

View GIS Task Service API Documentation here: