Introduction to Location quality monitoring
The Location quality monitoring feature allows the measurement, logging and monitoring of the quality of tag location data from location systems.
Various location quality monitors can be set up across a deployment, and each can generate health metrics. Monitors can also raise sensor errors when the number of detected issues within some time interval exceeds a threshold.
The general flow of the feature is:
- Users define the monitors they require.
- The monitors log measured quality metrics to health monitoring.
- If issues are detected in the quality metrics, they are logged to a trace stream and counts are sent to the Health monitoring feature.
- If issues persist, monitors can raise a SmartSpace error.
Installing Location quality monitoring
Requirements
Location quality monitoring requires the following features to be licensed and installed:
- Location rules version 3.6 or higher
- Health monitoring
- Business rules (required for modules to be loaded)
The Error reporting module (ubisense_error_reporting.ssc) must also be loaded and published. You can download a copy of this file from the Ubisense Downloads Portal.
Installation
Load the Error reporting module
Download ubisense_error_reporting.ssc from the Ubisense Downloads Portal.
In SmartSpace Config:
- Open BUSINESS RULES and click Load.
- At Load file, browse to ubisense_error_reporting.ssc and load the required items.
- Publish the loaded rules so that they are now active in your dataset.
For further information on loading and publishing modules, see
For a complete description of the error handling module, see Managing Errors in SmartSpace Applications.
Install the Location quality monitoring feature
To install Location quality monitoring:
- Make sure that the SmartSpace platform includes a license for the correct version of Location rules.
- Install the Location quality monitoring feature using Service Manager.
Download the sample health monitoring dashboard
A sample location quality dashboard, Location Quality Dashboard.json, is supplied. To make use of this dashboard in Health monitoring:
- Download Location Quality Dashboard.json from the Ubisense Downloads Portal.
- In the Grafana website, select Dashboards/Import, select Upload .json file and choose Location Quality Dashboard.json to upload it.
For further information on installing and configuring Health monitoring, see Overview of Health monitoring.
Configuring Location Quality Monitors
Setting up location quality monitoring in a SmartSpace system involves creating and configuring instances of the available Location Quality Monitor sub-types. (The subtypes are derived from the Distance Monitor and Path Monitor base types, which contain shared parameters for their sub-types, and which cannot themselves be used to create object instances.) Each sub-type represents a method of measuring how a location system is performing under specific constraints on the motion of tracked objects.
Objects move in different ways depending on their type and where they are in the process. Monitor instances can therefore also be restricted to a subset of the tags in the SmartSpace system, based on the objects they are associated with. They can apply to objects of a given type, to objects located within a given spatial extent, or to one or more instances of a relevant constraining object, such as a Path Group or Parking Area. This allows different monitors to be set up across a site where this is appropriate. For example, a monitor can be set up for tags on tools tracked along a production line, and a different monitor for the tags on the vehicles on the line.
Each monitor has additional parameters depending upon its sub-type. These determine:
- how the monitored quality is measured
- the conditions for detecting an issue based on the measurement
- the conditions for raising a sensing error based on detections
Monitor types have been chosen that can be computed efficiently so that they can scale to large sites with many located objects.
The following sections describe the types of location quality monitors, starting with parameters shared by all the types and then giving details of each type in turn.
You edit parameters in SmartSpace Config in the SERVICE PARAMETERS task. Choose Location quality monitoring from <select a configuration> to display the hierarchy of location quality monitor types whose parameters can be set:
Common Parameters
All location quality monitors share the following common parameters:
monitored type
The type of object with which the monitored tags must be associated. If none specified, then monitor all associated tags that match any more specific parameter constraints.
error detection count
How many detections are required, within an interval, to raise a sensing error
error detection interval
The time interval for error detection
maximum daily error reports
Suppress further sensing errors if the number reported in a day reaches this threshold
monitor disabled
If set to true, turns off all logging, detections and sensing errors for the monitor
monitor within extent space
Whether to use the extent space to determine which objects to monitor. See below.
Spatial extents for location quality monitors
Location quality monitors also have a space property called “extent”. When the “monitor within extent” flag is true, the object associated with a monitored tag must be located within the extent for any monitored spatial role of the object. Since the motivation is to monitor location system quality, it is expected that any spatial extents should be significantly larger than the expected errors. A spatial monitoring request should be set up for the containment within “extent”, in SmartSpace Config either directly in SPATIAL PROPERTIES/MONITORED SPATIAL RELATIONS, or by setting up a property and/or business rule that causes the relation to be monitored.
Parameters for Base Distance Monitors
Often tracked objects will spend a significant portion of their time stationary. If the location system is sufficiently accurate and robust, the sensed tag locations will normally lie close to a static position. This measures the maximum distance between the current tag position and the longer-term average position, over a time interval.
average over interval
The duration in time over which to compute the distance
trigger distance
How large a spread of sightings triggers a detection
Parameters for Path Distance Monitors
The location rules can be used to define when an object is expected to lie on a defined path. If the location system is sufficiently accurate and robust, the tag sighting should be close to the location corresponding to the object being on the path. This measures the distance of the tag from its expected position if the object is on the path, considering where the tag is attached to the object.
path group
The path group of paths that this monitor applies to. If none specified, then it applies to all paths.
trigger distance
How far the tag can be from its expected path location to trigger a detection
Parameters for Path Jump Monitors
When an object is on a path it should normally have decent location updates throughout. A jump is when the distance along the path between consecutive sightings exceeds a threshold. This measures the distance between consecutive tag positions assuming the tagged object is on the path.
path group
The path group of paths that this monitor applies to. If none specified, then it applies to all paths.
trigger distance
How far the object moves along the line between successive sightings
Parameters for Parking Distance Monitors
As with the path monitor, when an object has been parked at a bay, the sensed tag position should lie close to the position corresponding to the object being parked in the bay. This monitor measures the tag sighting distance from the tag position assuming the object is parked, accounting for the tag offset on the object.
parking area
The area that the object must be parked in
trigger distance
How far the tag can be from its expected parking bay location to trigger a detection
Parameters for Outage Monitors
Sometimes a location system or tag might suffer an outage, during which no locations are seen for tags that should be visible. This generally will only apply in areas where the monitored type is constrained such that its tag should always be visible. This monitor measures the length of time between successive sightings of a tag.
trigger duration
A detection is triggered when an object's tag is not located for this length of time since it was last located
Parameters for Jump Monitors
When consecutive sightings for a tag are a long way apart, this may indicate a sensor error, or that there has been a long period of time during which no sightings were generated. This monitor detects large distances between two consecutive tag location events.
direction
{unconstrained, horizontal, vertical, x axis, y axis }. The direction in which to measure the jump. Where “unconstrained” means to use the 3D Euclidean distance; “horizontal” means to use distance in the XY plane, ignoring height; “vertical” measures only change in height; and others measure distance in the direction of the corresponding axis.
trigger distance
How large a jump between sightings will trigger a detection
Monitoring and health metrics
Normally the count of detections for each location quality monitor is reported using health monitoring. In addition, measured values over the health monitoring interval are also reported. A spreadsheet giving details of the metrics provided is available on the Ubisense Downloads Portal. The metrics can be browsed using the standard Grafana interface. All Location quality monitoring metric names can be identified by their "ubisense_location_quality_" prefix.
A sample Grafana dashboard is available from the Ubisense Downloads Portal.
Logging
When the "location_quality" trace stream is enabled, all triggered detections are also logged, with parameters indicating the tag ID for which the detection was triggered.
To enable the trace stream, use the command:
and then restart the Ubisense/Location rules/Location inference service.
For example:
location_quality: Location Cell 00001: BaseDistanceMonitor triggered for 017-206-255-000-000-000-001 distance 5.89603
Errors
A sensing error is raised when a given number of detections are made for a monitor within a time interval. This is controlled by the common parameters “Error detection count”, “Error detection interval”, and “Maximum errors per day”, as described above.
In order to enable errors, the Error reporting module must be loaded, and the following Sensing Error must be created:
“TRANSLATE(location quality error)”
See Managing Errors in SmartSpace Applications for information on error handling in SmartSpace.