This article addressed the Location Service’s operation from start to end and covers how all settings along this process that may change the outcome of the Item's location. The article may be a bit difficult to read as its main purpose is mainly for people with a technical background.
Item Location Process
The figure below shows the location process chain from start to end. Each step in the process will be further explained below.
This section covers the steps of the location process handled by the Smartspot device and addresses the following topics: Item Presence, Proximity, Reports and how Smartspot settings may be important in the location process.
What is an Item Presence?
When an Item comes in range of a Smartspot, the Smartspot will generate a Presence event. This Presence contains the Item's unique identity and initial proximity. When the proximity changes, a Presence Proximity changed event is generated to notify the Location Service of this change. And finally when the Item goes out of range and the hold time exceeds, a Presence delete event is being generated.
All the time that an Item is being present, which basically means the period between the start of a Presence until its end (Presence delete), impacts the outcome of the location process.
At default only Presence proximity is being used by the Location Service to select a location candidate. In case that this basic approach is not sufficient, additional data can be gathered by Smartspots and periodically send in the form of Presence Reports to the Location Service for statistical analysis.
The following sections will explain a bit more about Presence Proximity, Reports and how Smartspot settings may impact the Item's location.
The Presence Proximity process has a few stages as illustrated in the figure below. This section will explain each stage in the process and the settings to optimize the output of this process.
All Item RSSI samples must pass the minimal RSSI threshold filter before being allowed to be used further in the process chain. At default this threshold is set to a minimal which means that basically all samples pass this filter stage without being dropped, but may be changed by user if required for that specific setup.
Once samples pass this threshold filter, samples will be filtered in a second stage before the proximity is determined. The second filter stage uses an average filter with a variable window which means, at initialization, the window starts at one and increases automatically until it has reached its maximum window value. This results in no initialization delay at start which means immediate filter output. Over time the output will become more stable while more samples rush in and are being processed.
The disadvantage of this type of filter, and average filters in as a whole is the delay that's being introduced when the windows increases and/or the maximum filter window has been reached. Especially when the number of input samples is initially high but drops when the Item disappears completely or due to poor signal quality introduced by external factors. That’s why there is a system added to this filter that automatically decreases the window when the number of input samples drops. This keeps the filter output responsive.
Proximity ranges and hysteresis
The Presence Proximity is based on the output of the filter and is expressed in one of three following value ranges: far, near or immediate. Each range has a threshold setting to indicate the end of that range and can be modified by user depending on the setup. The hysteresis setting can help to reduce and suppress frequent changes between proximity ranges.
The Presence Reports process, as illustrated in the figure below, uses the same stages as Presence Proximity which means that some settings are shared and all changes will impact both processes equally. This section will explain the differences for Reports and the settings to use and optimize Reports output.
Reports are default disabled but can be enabled if the setup doesn’t allow the simple approach of working with Presence Proximity only. Examples could be difficult setups where Smartspot devices may be positioned in close range to each other or improve Item transitions at one Smartspot for example from check-in to check-out.
Enabling Reports means that data from the filter output and input, as described in Presence Proximity section, is gathered and periodically send to the Location Service for statistical analysis. Obviously this will increase the number of events between Smartspot and Server.
If Reports are enabled on one Smartspot device which is in read range of other devices, all those devices should enable Reports to prevent issues with the location process. Otherwise if an Item is being present at both or all locations, the Location Service falls back to comparing Proximity instead of Report data due to incomplete information which can be a disadvantage.
This section lists all Smartspot settings that impact the Item location process which have been covered in one of the previous sections.
|Setting Description||Device Configuration||API|
|Minimal RSSI sample threshold||No||Yes, <technology>_threshold|
|Average filter maximum window||Yes||Yes, <technology>_max_window_size|
|Presence Proximity threshold||Yes||Yes, <technology>_immediate, near|
|Presence Proximity hysteresis||Yes||Yes, <technology>_hysteresis|
|Presence hold time||Yes||Yes, fixed_hold_delay_s|
|Presence Reports and the interval||Yes, Yes||Yes, Yes, ant_presence, ant_report_ds|
This section covers the steps of the location process handled at the Brain server and addresses the function of the Reporting Location, the location selection process and settings for this service.
A Reporting Location is basically a collector of all data received from one or multiple Smartspots and/or individual Smartspot antennas. The figure below illustrates the Reporting Location.
For each Item, the Reporting Location has a selection process which determines the strongest origin (Smartspot or Smartspot antenna) based on Presence and or Report input. This strongest origin will then be used to represent the Item state at this Reporting Location. The Location Service then compares each Reporting Location and select the strongest Item representation from all Reporting Locations in the system, and this will be finally the location of the Item as represented on the API, API events and Apps. The selection process will be covered in the section below.
The list below gives a basic understanding how the Location Services determines the location of an Item.
- On new Presence, Proximity update or Report data input. Does this sample qualify for further processing?
- Data is valid, Report data is above selected noise level.
- The source, Smartspot or antenna is linked to a valid Reporting Location.
- Find out if Reporting Location Item state needs to be updated:
- New proximity has changed, increased or decreased compared to its previous state.
- Report data shows a change and the difference between Reports is more than the location hysteresis.
- Item is not in range anymore and the last Presence has been deleted.
- Update the item status for the Reporting Location. If the Item status for the Reporting Location has changed, check if this change effects the current system strongest. This selection process repeats the steps as described above.
- If the system status for this Item is changed, check if there are any Location Rules that allow or disallow a move from the current to the new location.
- Initiate the location change. This change process will be delayed by a debounce period as specified in service settings or may be overridden by the value specified in Location Rules, in case they apply. While debounce has not exceeded, the change remains scheduled and can be reevaluated at any time. This may occur when a different, better location than the one currently scheduled, is being selected.
- Debounce timeout has occurred. This means that location change is complete and results are visible in API, API events and Apps.
Location Rule is a new concept introduced in version 1.6.0 of the Location Service allows system administrators to create rules to allow or disallow Item moves between locations or override service settings. This could be helpful to train the system eliminating location changes that could never be possible in real world scenarios or customer processes.
Rules can be managed via API and using the Location Rules App that can be found in the Management Console. The version of the Management Console needs to be 2.14.0 or higher and the user needs to be an Administrator to access the App.
This section lists all Location Service settings that impact the Item location process. Some of them may have been covered in one of the previous sections.
When Presences Reports are enabled, this settings specifies the minimal difference between two Presence Reports before the new Report is qualified for further processing.
When Presences Reports are disabled, this setting specifies the minimal proximity level at which the Location Service may select one of two equal proximity values as the dominant one based on their event time. A minimal time difference of 999 ms between events is mandatory.
When Presences Reports are enabled, these settings specifies the minimal levels at which the RSSI value will be accepted for comparison by the Location Service. Values below this setting won't be compared.
If this setting is enabled, the label property of a new Item is automatically filled using the Item code. This setting has no effect on Barcode Item types as their labels are always automatically filled with an ASCII representation of the hexadecimal code.
This setting sets the last location which can be used to move Items to when they disappear from the system. Disappearing means Items which are no longer in range of a Smartspot and therefore not present at one the Reported Locations. Setting disappeared_location_time_s enables this setting and also specifies the time when this action should be performed.
This setting enables (>0) or disables (0) the disappeared location function and specifies the time when this action should be performed.
This setting delays a Item Location change with a maximum time period specified in seconds. While the delay is active, changes can be made at any time which means that time period is restart with each change. If the time period exceeds the value currently held will be set as new location.
This setting specifies the maximum number of periods that a debounce delay can be re initiated before enforcing the current value as the new location. If value is set to 0 this setting will not be used and the debounce delay can be reinitialized without any limits. Max period is defined as follows: value * debounce_s
This setting sets a delay which freezes Presences state in the Location Service after that Presence at the Smartspot has been deleted. The Presence will remain active on the server for this time and changes during this period won't have effect on the Item's location.
This setting sets a delay which freezes Presences state in the Location Service after the Smartspot disconnects from the server. The Presence for this Smartspot will remain active on the server for this time and changes during this period won't have effect on the Item's location.
This setting sets the internal operation frequency at which some of the internal tasks are being scheduled. This setting has no effect on processing incoming events from Smartspots but may impact the number of times at which Presences are being evaluated for removal.