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 data processing chain from start to end. Each step in the process will be further explained below.
This section covers the steps of the data processing 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 emit a Presence create event to notify the Location Service of this Item. The Presence create event contains the Item's unique identity and initial proximity.
When the proximity of an Item changes (stronger, weaker), a Presence proximity changed event is generated to notify the Location Service of this change.
Finally when the Item goes out of range and the hold time for this Item in the Smartspot exceeds, a Presence delete event is being generated. This notifies the Location services that the Item has disappeared.
All event data from begin to end will be used in the location process. At default only Presence proximity is used by the Location Service to select a location candidate. In case that this basic approach is not sufficient, configuration in the Smartspot can be changed to gather additional data which are periodically send in the form of Presence Reports for statistical analysis.
The following sections will explain a bit more about Presence Proximity, Presence Reports and how Smartspot settings may impact the Item 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 a minimal RSSI threshold filter before being allowed to be used in the processing chain. At default the threshold is set to a minimal which means that all samples pass this filter stage without being dropped. This can be changed by the user if it is required for that specific setup.
Once samples pass the threshold filter, samples will be filtered in at 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 the maximum window value. This results in a no initialization delay at start which means an 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 is 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 average 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, 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 by default disabled but can be enabled if the setup requires more data. Examples for these setups are scenarios where Smartspot devices are positioned in close range to each other or to 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.
|Minimal RSSI sample threshold
|Average filter maximum window
|Presence Proximity threshold
|Yes, <technology>_immediate, near
|Presence Proximity hysteresis
|Presence hold time
|Presence Reports and the interval
|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.