Fence Mechanism
The fence mechanism of the DeepHub is tailored to handle use cases of any complexity, and is easy to setup and use. It works for low-level location provider objects and for trackables (representing the high-level abstraction). Fence entries and fence exits are handled similarly through the fence mechanism.
When a location provider or a trackable passes through the border of a fence, this entry into a fence triggers a corresponding region_entry event. Similarly, when a location provider or
a trackable passes beyond the border of a fence, this exit outside the fence triggers a corresponding region_exit event.
Physical limitations of locating systems may lead to location information that exhibits "jittering" effects. This can be problematic for location providers moving close to the border of a fence, triggering false region_entry or region_exit events. To help mitigate this, the fence mechanism includes "tolerance area" properties.
The same way the fence exit mechanism prevents objects from exiting too early or erroneously, the fence entry mechanism helps prevent scenarios where an object is treated as inside a fence if it momentarily came near a fence or had an incorrectly reported location.
See the following section for more details, or the Fence REST API documentation.
The Tolerance Area
The tolerance area is a geometrical area along the outside of a fence, or along the inner side of a fence. Within a tolerance area, location_updates do not immediately lead to a region_entry or region_exit event being triggered. Instead, these events are postponed by a given time, during which subsequent location_updates can "clarify" the object's status as being inside or outside the fence.
In the illustration on the left, the outer tolerance area is marked in grey. The tolerance area is defined as the distance in meters to the fence border. It is specified with the exit_tolerance property.
For the fence entry mechanism, the tolerance area is within a fence (the grey/blue outer rectangle in the illustration on the right). It is also defined as the distance in meters to the border of the fence, and is specified with the entry_tolerance property.
Let's consider the fence exit example illustrated on the left. As long as the location provider (orange circle) is outside the fence but still within the defined tolerance area, the region_exit is not immediately triggered. Instead, for the set number of
milliseconds (defined with the tolerance_timeout property), further location_updates are evaluated based on whether the location provider is either:
- back in the fence
- still in the tolerance area
- outside the fence and the tolerance area
In case 1, a region_exit has not occurred, and a region_exit event is not sent.
In case 2, depending on the defined timeout, the region_exit event is further delayed to wait for more location_updates. As soon as the number of milliseconds set as tolerance_timeout have passed, the region_exit event is triggered.
In case 3, the region_exit event is triggered.
Conversely, an inner tolerance area is used to handle fence entries. Here, the entry_tolerance_timeout property has to be set to define the number of milliseconds for which a region_entry event is delayed if an object is within the defined inner
tolerance area.
If this sophisticated fence entry and exit mechanism should not apply to all location providers and trackables, these properties can be unset for the fence but applied directly to those other entities. The names of the properties are the same.
More details can be found e.g. at the Trackable REST API documentation.
Example Setup
A challenging use case, illustrated in the screenshot below, involves an asset moving along a hallway and entering/exiting rooms represented with fences (triggering corresponding fence events).
region_entry events must not be triggered when the asset travels along the hallway and passes adjacent rooms and their fences. Secondly, after the asset enters a room and its corresponding fence, it must not be falsely treated as having left the room if it is still inside but located next to the outer wall of the room (representing the border of the fence).
In this scenario, both the region_entry and region_exit have to be properly configured via tolerance areas with entry_tolerance_timeout and tolerance_timeout (aka "exit_tolerance_timeout"), respectively, for each fence/room.
The red line represents the movement of the asset from "Raum 001" to "Rein Raum A" and then to "Lager". A region_exit event should happen for "Raum 001", followed by a region_entry event for "Rein Raum A". Next, a region_exit should occur when the asset leaves "Rein Raum A", and a final region_entry should occur when the asset enters "Lager". No other fence events must happen, especially no region_entries for "Raum 002", "Raum 003" and "Raum 004" while the asset is travelling along the hallway.
The fences on the left, "Raum 001" to "Raum 005", are each 8m wide. The hallway is roughly 1.8m wide. Due to these distances, an exit_tolerance of 0.5m would be suitable for the outside tolerance area for these rooms. This would ensure assets are not incorrectly reported as being in the hallway (even though they are still within the boundaries of a room). These rooms would also have entry_tolerance set to 0.5m. This would create an inner tolerance area, ensuring assets are not incorrectly reported as being in a room (even though they are moving through the hallway).
Depending on the locating system in use and its configured update frequency, tolerance_timeout and entry_tolerance_timeout have to be set to a value that would allow at least one location update to occur within the defined time interval. Let's say the locating system reports positions every 30 seconds. The tolerance_timeout and the entry_tolerance_timeout should be set to at least 30,000 milliseconds to allow for one further position update to happen before the time runs out. However, setting these timeouts to 60,000 milliseconds would allow for 2 further position updates, thereby ensuring even greater resistance against jittering. The implication is that region_entries and region_exits would have a 30 or 60 second delay, respectively.
The same applies for "Rein Raum A": it is 5m wide and is next to the hallway. Assets move along the right wall of the room, potentially reaching out to the right border of the fence. An outer and inner tolerance area of 0.5m would be appropriate here too.
If tolerance areas are not necessary but fence entry or exit events should be delayed, the entry_delay and exit_delay properties should be used.