GateDetector User Guide

Gate Detector is a BlueUp proprietary application developed to detect and monitor the transits of a beacon through an entrance or exit point, referred to as Gate.

Gate Detector provides real-time information and data about the transits of people or assets, provided with a beacon, through a gate, distinguishing between entrance or exit.

User Interface structure

User interface is divided into tabs, that will be described in the following. In the right corner there is a drop-down menu, from which it is possible to:

  • Restart service
  • Restart server
  • Shutdown server
  • Software update (by uploading an update packet or by checking in online BlueUp repository)
  • License update
  • Logout

Main page

System Info

This first tab of the Gate Detector web interface displays all the necessary information about the software, the licence and network interfaces.

System Info

System Settings

In this section it is possible to change some important settings such as the Access Password, Clock Synchronization, HTTP Port.

The Web Workers Settings allows to define the number of Web Client Workers, that is the maximum number of clients than can use the control panel at the same time, without having troubles with the performance of the software.

System Settings

MQTT

MQTT is a publish/subscribe network protocol used to transport messages between devices.

Certificates

This section allows to define and setup the MQTT Certificates related to the brokers. When importing certificates, at the moment, the only acceptable format is the PKCS#12 one.

MQTT Certificates

Brokers

To configure the MQTT, the software has to be connected to the MQTT Server, by configuring the MQTT Broker. Connection Timeout and Keep Alive Period are configurable from the actions menu.

MQTT Brokers

Broker Log

This section contains the Logs provided by the MQTT Broker.

MQTT Broker log

Topic Configuration

Status Topic

This topic contains the system status information. This kind of topic has a configurable sending frequency, from disabled to every 24 hours. In the “topic” field has to be specified the Status’ Topic structure.

The default structure is blueup/gatedetector/status, but it is possible to add other parameters, called Placeholders, that will be displayed in the topic:

  • client-id is the MQTT connection Client ID,
  • system-id is the system unique ID,
  • timestamp is the system UNIX timestamp.

Status topic

Event Topic

This topic contains the events sent by the system. The default structure is blueup/gatedetector/event/event-id/event-timestamp. Other Placeholders are:

  • client-id is the MQTT connection Client ID,
  • system-id is the system unique ID,
  • timestamp is the system UNIX timestamp,
  • event-id is the event identifier,
  • event-timestamp is the timestamp of the event, with accuracy of hundredths of nanoseconds.

Event topic

Request Topic

This topic is used by the client to send the requests to the system. The default structure is blueup/gatedetector/request/#. This structure can contain Wildcards, that are:

• + is equal to any word in that given position

• # is equal to anything in that given position, that can be a word, an identifier, a structure.

Request topic

Response Topic

This topic contains the responses to the requests. The default structure is blueup/gatedetector/response/request/request-id.

The possible Placeholders are:

  • client-id is the MQTT connection Client ID,
  • system-id is the system unique ID,
  • timestamp is the system UNIX timestamp,
  • request-id is the request identifier generated by the client in the request topic,
  • request is the request name set in request topic.

Response topic

Gateways

Gateways section contains the supported BLE Antenna types with the information regarding each antenna detected in the network.

In this section are listed all the connected antennas.

To connect new Antenna press the “+” button in the right corner and select “Scan the Network” option. All the Antennas that are detected in the network will be listed and the user can choose one or more Gateway to connect.

Gateways

Tag Filters

Tag Filters section allows to define the rule following which the Tags are detected in Gate application.

Only Safety beacons are supported by Gate Detector application. Beacons can be delivered with Safety beaconing already enabled or the user can enable it using BlueBeacon Manager App..

In case you are configuring your beacons by yourself, the suggested configuration parameters are:

  • Safety slot enabled
  • Advertising Interval 2.5s
  • Radio Tx Power -8dB
  • Triggered Advertising Interval 100ms
  • Triggered Radio Tx Power -8dB
  • Triggers: Movement, Button short, Button long
  • Trigger Duration 1s
  • Movement Threshold 5

In this tab the user can specify the Safety UUIDs to detect for the Gate application. Only tags having the specified UUID will be detected and listed in Tags tab (Sec. 7), all the other tags will be discarded.

Tag filter

Tags

In Tags tab are listed all the tags that are detected by the gateways and that meet tag filtering conditions.

For each tag its basic information is shown, such as ID, Mac address, UUID, etc. For simplicity each tag can be given an Alias, an alternative identifier to easier recognize the tag.

Moreover, the nearest anchor to the tag is shown with RSSI value.

Tags

By pressing the Tag settings button, it is possible to set the Anchor detection timeout (in sec). If the tag is not seen by any of the anchors in the system for more than the set timeout, the tag is eliminated from the list of the detected Tags.

Tag settings

Gates

This section contains all the information about the Gates. Before defining a gate and setting up the gate parameters, the gateways should be physically installed forming a gate. To properly configure the gate, the entrance and exit directions should be defined, by defining which gateway is at the entrance (In) and which one is at the exit (Out).

Create a new gate

To create a new gate press “+” button in the right corner.

Create new gate

The fields to fill in are:

  • Gate ID – alphanumeric field. No space is accepted
  • Description – user description of the gate
  • In and Out Anchors – gateways to be used as in and out anchors
  • Anchor detection timeout – the maximum time delay, after which the tag will be disconnected from the anchor
  • Anchor max async – maximum time synchronization error between the two gateways of the gate. If the async time overcomes this value no calculations on the signal will be done, because it is not real time
  • Trigger ΔdB – RSSI difference between In and Out gateways to trigger a transit
  • Trigger range threshold – RSSI value that has to be overcame by at least one of two signals so that the transit is saved. This threshold is used to avoid transits due to the noisy signals when the tag is far from the gate
  • Out of range threshold – RSSI value over which the tag is considered out of gateway’s range
  • RSSI filter – type of the filter applied to the signal. Kalman filter is the recommended one, since it provides better performance of the Gate Detection algorithm

Detected Tags

In this tab are listed all the tags that are detected by the system. For each tag are specified some important information:

  • State of the tag with respect to the In and Out Gateways. The state shows to which gateway the tag is in the proximity. The state can also be Undefined, which means that the tag has not moved yet and its proximity to the gateways is unknown.
  • RSSI between the tag and the In Gateway
  • RSSI between the tag and the Out Gateway
  • Anchor Synch, that is the time synchronization error between the In and Out gateways,
  • Chart is a real time plot (Fig. 17) of the signal received by the In and Out gateways. The signal is plotted only while the chart is kept open.

Detected tags

Chart

Transits

The transits are detected following this algorithm:

  • when the tag is moving, the switch of the signals of the two anchors triggers the verify of the transits
  • first of all the ΔdB after the switch is calculated. If the value is higher than Trigger ΔdB than the next value is evaluated
  • the second parameter to be evaluated is Trigger range threshold. If the ΔdB is acceptable and there is at least one of two signals higher that the trigger threshold, than the transit is detected and displayed in the transits table.

For each transit of a beacon the following information is displayed:

  • Direction of transit, whether it was an entrance or exit
  • Gateways. For each gateway of the gate the RSSI value is displayed
  • Δsync. Time synchronization error between gateways
  • ΔRSSI. RSSI difference between two gateways
  • Chart – graphical plot of the transition that can be displayed even after the transition.

Transits

Configuration

The configurations set up during gate creation can be changed any time in this tab. Important parameters are:

  • Anchor detection timeout is the maximum time delay, after which the tag will be disconnected from the anchor.
  • Anchor max async is the maximum time synchronization error between the two gateways of the gate. If the async time overcomes this value no calculations on the signal will be done, because it is not real time.
  • Trigger ΔdB is the signal difference in dB to trigger the transit.
  • Trigger range threshold is the value that has to be overcame by at least one of two signals so that the transit is saved, as described in 8.3. This threshold is used to avoid transits due to the noisy signals when the tag is far from the gate.
  • Out of range threshold defines the RSSI value over which the tag is considered out of gateway’s range.

  • RSSI filter defines the type of the filter applied to the signal. Kalman filter is the recommended one, since it provides better performance of the Gate Detection algorithm. The recommended values for the Kalman filter calculation are:

    • Process noise = 0.5
    • Measurement noise = 15

Configuration

Data Logging

This functionality (when activated using the button on the top of the table) allows to log all the data related to the transits and the movement of the tags in a database. This is very useful for testing and error detection purposes.

data logging

The data then can be plotted in a chart by selecting the tag and the time period.

Data logging chart

Below there is an example of the data logging chart. In this example are clearly visible 3 transits through the gate: 1 entrance (in) and 2 exits (out).

Data logging chart example

Logs

System Logs

The Logs keep track of the system messages that can be used to track the software activities.

System logs

Events

These logs contain all the events of the system, if the event tracking is enabled. When clicking on the Event name, a brief description of the event will appear.

The most important event displayed is the tagTransit event that is raised when a tag transits through a gate. Among other information, it is specified if the transit is an entrance or an exit, based on the gate In and Out configuration.

Events

APIs

As all BlueUp software, GateDetector is provided with API calls. In the following are listed and described the available APIs.

URL/api/status

This API describes all necessary information about the software and its working status.

URL/api/gatedetector/event-listener

This API allows to generate an event-listener, that collects and lists then the events generated by the system.

If nothing is specified, the event listener list all the possible events generated, otherwise it is possible to specify in the body of the request the list of events to collect and list.

The event listener API generates a token, that has to be used to start the events collection, using the URL/api/gatedetector/events/token API.

Events generated by the system

  • gateStopWorking: event generated when the gate is not working because at least one of the two gateways forming the gate is offline. This event is generated after the event gatewayState notifies that a gateway is gone offline.
  • gatewayState: event generated when a gateway changes its state going online or offline.
  • tagDetection: event generated when the system starts or stops detecting a tag. A tag is not more detected by the system if the tag is not seen by any of the anchors in the system for more than the set timeout.
  • tagTransit: event raised when a transit through a gate is generated. In this event is specified the gate, the direction of the transit and transit characteristics.

URL/api/gatedetector/events/token

The output of this API is the list of collected events, that were requested in the event listener.

URL/api/gatedetector/tags

The above API lists all the existing tags in the system and their information, such as:

  • id, MAC address, UUID
  • movement of the tag
  • last update, battery level
  • anchors that detect the tag, specifying the anchor and the relative RSSI value.