Projects

A project is a unique instance of Sora with its own set of resources. Resources within a project include devices, layers, annotations, events, and alerts. Projects are useful for separating or grouping relevant data and devices. Projects require a name and an optional description. 


Creating a Project

Registered users can create a new project at the Sora Project Selection Page. Select the New Project button, then configure a name and an optional description to create a project. Device icons that display on the map are selected at the project level. 


An option to include demo buses can be toggled when creating a project. The bus demo streams in example data to enable users to try Sora’s functionality without connecting a physical device. 


Modifying a Project

Once a project is created, the project settings can be modified by selecting the Edit button on the project tab. 


Deleting a Project

Projects can be deleted from by selecting the Delete button on the project selection tab for a single project. Deleting a project will permanently remove all associated resources and data.


Connecting Devices 

Sora works with Swift Navigation's GNSS/INS receivers and Starling Positioning Engine software. The Sora Device Client provides a set of simple tools to connect your device to Sora.


The Sora Device Client consists of:

  • A command-line client - the simplest way to connect to Sora
  • A Python client library - for deeper integration and customization


Instructions for installing the Sora device client are published on Github at github.com/swift-nav/sora-device-client.


The following device capabilities are required to run the Sora client:

  • Linux
  • Internet connectivity
  • Access to https://sora.swiftnav.com 
  • Python 3.8
  • Source of location data (ex: GNSS receiver)

Once the Sora device client is installed, entering the command sora login into the terminal initiates the device registration process. Device registration is completed in the web browser, where the device name and project can be configured. 


Data Types Supported by the Sora Client

The Sora API uses the following data types:  time, latitude, longitude, altitude, pitch, yaw, roll. Additionally the Sora client includes the following data types: fix_mode, n_sats, flags, h_accuracy, and v_accuracy. The Sora client is open source and can be modified to include additional data types generated in your application. 


Dashboard

The following subsections provide an overview of the Sora dashboard.

Dashboard Components

The dashboard visualizes your data and devices. Dashboard components are designed to quickly locate data of interest in space and time. 

  • Map
  • Devices
  • Layers
  • Annotations
  • Events
  • Alerts
  • Time Navigation
  • Base Map Settings


Time Selection

The timeline displays the time range of data displayed on the map. Configurable time ranges are a minimum of 1 minute to a maximum of 3 days. The timeline selection can be adjusted by clicking and dragging the endpoints. Selecting the Live option will snap to the present moment in time and maintain the existing time range. 


The calendar icon on the timeline opens a datepicker that allows for data selection by day. Days on the calendar are color coded by the data volume received during that day. This visual indicator enables rapid location of data by time. 


Histogram

Hovering your mouse over the timeline shows a histogram that corresponds to the volume of data present for that period of time. If the events tab is selected, the histogram shows the volume of events generated in that time period. 


Map Settings

The map settings on the far right side of the dashboard allow toggling of 3D mode, drawing polygons and rectangles on the map, and changing the display language.


Devices

The devices tab shows a list of all of your devices and enables modification of device visualization settings.


Device Visualization

Devices can be shown or hidden on the map by selecting the visibility icon. Device color can be changed in the dropdown menu for each device. Selecting the crosshair icon enables you to jump directly to a device’s position on the map.


Layers

A layer is geographic data set and is composed of individual features. Features are points, line segments, or polygons. Each feature in a layer can have properties associated with it, such as a name, coordinates, or application specific data. 


Supported Layer File Types

Sora supports JSON and GeoJSON layer file types.


Generating a Layer

Layers can be drawn on the map and exported using the inbuilt map tool, downloaded from open data repositories on the web, or created using tools like geojson.io.


Uploading a Layer

Layers can be uploaded to Sora using the Layers tab in the dashboard. Select the Add Layer button, then select or drag and drop a file into Sora.


Editing a Layer

Layers can be renamed or recolored on the Layers tab. Currently Sora does not support editing features within the user interface. 


Deleting a Layer

Layers can be deleted by selecting the delete icon next to the layer in the layers tab of the dashboard.


Limitations

  • Layer size 
  • Layers with multiple types of features
  • Zipped files
  • Shape files


Annotations

An annotator appends additional computed values, or annotations, to a device state. Sora supports multiple types of annotators, including geofencing and map matching. Annotators act on each device and incoming state within a project and append the resulting computed output to the same state. Annotators create higher value data types that can be used for downstream analytics or triggering events.


An annotator has three configurable settings: required data for the computation , a display name, and an annotation key. The data is dependent on the annotator type, for example, a geofence annotator requires a layer to be defined. The display name appears in the sidebar, and the annotation key is the key of the corresponding annotation value in the device state.


Creating multiple annotators with the same display or annotation key name is prohibited to prevent inadvertent errors and overwriting of data.


Creating an Annotator

To create an annotator, navigate to the Annotations tab in the dashboard and select Add Annotator. 


Editing an Annotator

Annotators can be modified by selecting the Edit icon associated with a specific annotator. 


Deleting an Annotator

Annotators can be deleted by selecting the Delete icon associated with a specific annotator.


Events

Event generators are a rule set that triggers an event when its conditions are met. Events are a separate log of a device’s state in a specific place and time. Event generators apply to all devices within a project.


Creating multiple event generators with the same name is prohibited to prevent inadvertent data errors. 


Creating an Event Generator

Event generators can be created on the events tab by selecting Add Event Generator. Event generators require a name and a ruleset in their configuration. 


Editing and Event Generator

Event generators can be renamed and rulesets can be modified by selecting the edit icon on an event generator. Changes made to an event generator only affect new data.


Deleting an Event Generator

Event generators can be removed by selecting the delete icon on an event generator. Deleting an event generator will only affect new data.


Event Logs Explanation

The event log is a record of events and their associated data for a project. Selecting the map icon for an event will jump to the event in space and time on the map. 


Alerts

Alerts forward data from event generators to external systems. 


Supported Alert Methods

Slack webhooks are the only currently supported alert method. See Slack's documentation for help on creating a webhook.


Creating an Alert

Alerts can be created by navigating to the alerts tab and selecting the + Add Alert button. Alerts can be connected to an event generator by clicking the event generator dropdown and selecting the alert. 


Editing an Alert

Alerts can be edited by selecting the dropdown menu for an alert.


Deleting an Alert

Alerts can be deleted by selecting the delete icon on an existing alert.


Browser Requirements

Your browser must have WebGL enabled to view the Sora dashboard. You can check if your browser supports WebGL here.


Related Articles