GateDetector User Guide v.3.0

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 and exit.

Specifications

Here are summarized the recommended system specification for different project sizes.

These are recommended specifications for typical projects. Contact us if you have doubts.

The system should be installed on a Debian - based Linux system.
Ubuntu 20.04 or later is recommended.

GateDetector web interface, described here, is divided into sections for a more user friendly navigation.

In the upper right corner of the web interface there is the notification center where are shown the useful notifications from the system to the user and also where are shown the background processes running in the system.

By pressing the button in the upper-right corner, the system opens a pop-up menu from which it is possible to logout the system, restart the service or restart the server.

System Info

This first tab of the BPE Web Interface displays all the necessary information about the software, the license and network.

From this interface the user can check if there are new software updates available and to update the software by pressing button.

License

GateDetector is a licensed software.
The license is applied to the server on which the service is running.
In the System info is summarized information about the license of your GateDetector:

• Status signals if the license is valid or not;
• Expires on is the expiry date and time of the license. After the license has expired, the service will be still available for 2 hours. After the 2 hours, the service will stop responding to the users requests;
• Maintenance expiry is the date and time when the maintenance to the GateDetector will end. For maintenance is intended the possibility to update the software with the new releases. If the license is still valid, but the maintenance is expired the software can not be updated;
• Capabilities are the proprieties of the software the user has access to. The user can have a limited license version, without support of some capabilities. The possible capabilities are:
  • Gates is the maximum number of gates that GateDetector can process;
  • Automation module if enabled, MeshCube can manage the Automation module. For more information refer to Automation.

Note: When the license is about to expire, starting from 1 month before the expiry date, the system sends a daily notification to the user to remind to renew the license.

System Settings

This section gathers all the possible settings of the system: it is divided in subsections where settings and configurations are collected based on their functionality.

System - Timezone

This setting allows to setup the timezone where the server is located. The timezone is useful for Maintenance and other basic operations that are time-related.

System - Maintenance

This section allows to configure the Maintenance of the system. During maintenance the system performs some operations of checking, optimizing, updating and deleting expired data from the system. During these operations the system can pause some basic functionalities of GateDetector.

• System maintenance enabled flag allows to enable or disable system maintenance. It is suggested to keep system maintenance enabled;
• Days - table that allows to select the days when the maintenance will be performed;
• Maintenance Time is the time (in 24h format) when the maintenance is performed.

Since during maintenance some basic functionalities can be paused, when configuring maintenance period it is suggested to set days and time when the system is not used, to not to interfere with system functioning.

System - System Password

This setting allows to change the access password of the GateDetector interface.
After inserting the current password and the new one, the button will appear to save the new password.

If the New password and the Confirm password do not coincide the button will not appear.
If the inserted Current password is not correct an Error pop-up will appear.

System - Email Service

This section can be used to setup an email service. This service can be used for testing purposes or to configure Plug-ins that support email services.

• SMTP Server to be selected among the SMTP servers setup in IO - SMTP Servers;
• Sender name to be able to recognize the email coming from MeshCube service;
• Sender email address is the email address from which GateDetector will send an email.

System - Software settings

This setting allows to decide which software release the user wants to use, among:

• Stable is the officially released version of the software;
• Beta is a Beta version of the software, before stable release;
• Dev is a Development version of the software;
• Custom available only if a custom version of the software has been required. In this case BlueUp will provide the user also with Repository, App id, App key to insert in the settings to download the updates related to the custom version.

By selecting one of the software releases, when updating the software, it will be updated to the latest available version of the chosen release.

Note: if you choose Beta or Dev versions, consider that they are not stable versions, therefore there can be some bugs in the system. If you find any, please report the bug or problem by opening a ticket or by writing an email at support@blueupbeacons.com

Web - WebServer

The WebServer settings allow to setup the HTTP interface settings.

• Server URL is used to setup the URL at which the server is reachable;
• Certificate allows to select (in case of HTTP S connection) the certificate corresponding to the HTTPS connection. The certificate is setup in Certificates settings;
• Listening port is the port at which the service is listening;
• Workers is the number of processes that the system can open at the same time;
• Check idle connections is a function that scans for active connections to the server and automatically closes the connections that have been idle for at least 1 hour;
• Use reverse proxy is an advanced setting related to the proxy. Leave to default value if not sure about its use;
• CORS enabled allows to setup the cross calls to the system from other domains. For more information refer to Cross-origin Resource Sharing.

Web - mDNS

mDNS is a protocol that allows to discover network services and devices in the local network with their hostnames instead of IP addresses. This procedure can be applied only if the GateDetector server is installed on premises and not in cloud.

Make sure that mDNS is configured in your network interface.

• Service Description is the description of the service that allows to easily discover the service in the network;
• Service hostname is the hostname at which the service is reachable, instead of the IP address.

When defining the service hostname, the GateDetector server will be available also at <service_hostname>.local address in your browser.

API - API Settings

This setting allows to setup the security level for what concerns the HTTP API calls.

• No authorization required - the APIs can be called without any specific authorization;
• Basic - the user has to specify a Username and Password to use when calling the API;
• Bearer JWT - the most secure authorization mode, described here. To use this modality, the user has to generate a JWT Token in JWT Tokens section.

API - JWT Tokens

To authenticate using Bearer JWT method, a JWT Token has to be generated to be used when calling an API. To create a new Token press on and fill in the following fields:

• Description of the JWT token;
• Expires to decide if the token expires or not. In case this field is checked, the user has to set an expiry date and time;
• IP addresses is the list of IP addresses that can call the APIs. If left blank, all IP addresses will be allowed;
• Access Rule options are:
  • Allow all to allow the access to all API calls;
    
  • Allow selected APIs to allow to call only the selected API calls;
    
  • Deny selected APIs to deny to call selected APIs;
• Max invocation per hour is the maximum number of API calls that can be invoked per hour with this JWT token.

Once that a Token is saved, it will appear in the list of JWT Tokens.
In the table, for each generated JWT Token are summarized the configured parameters.
Moreover, for each token it is possible to:

• Edit the token
• Download the token
• Enable or Disable the token
• Delete the token

Security - Certificates

This section allows to upload and store all the certificates that are used for HTTPS and/or MQTTS connections.

To upload a certificate, press on the upload button . The acceptable certificate format is PKCS#12.

IO - MQTT Brokers

In this section is possible to setup the MQTT Broker for data transmission. For each MQTT Broker are defined the parameters of the connection to the Broker.

A broker configuration can be imported or created from scratch. Also an existing configuration can be cloned and changed, instead of creating a new one.

IO - SMTP Servers

This setting is used to setup SMTP server for the emailing function. When configuring a new SMTP server the fields to fill in are:

• Host
• Port
• SMTP connect options are:
  • Auto
    
  • SSL
    
  • TLS
    
• Username
• Password

Tags - Tag Configuration

This setting allows to setup the Mesh packet storage in a database:

• Anchor detection timeout (sec) - if the tag is not seen by any of the anchors in the system for more than the set timeout, the tag is set as Not detected;
• Remove when not detected - if the flag is enabled, once hat the tag becomed Not detected it will be removed from the list of the tags.

Tags - Tag Filter

Tag Filter 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 settings the user can decide whether to filter the tags by UUID or by MAC Address.
In both cases, the user has to specify the list of acceptable UUIDs or MAC addresses to use as filters.
Tags that do not satisfy the filter will not be listed in the Tags tab.

Storage - Gate Storage Configuration

This setting allows to define the rule regarding the data storage in the database: Session retention time (days) is for how long data is stored in the GateDetector database.

MQTT Interface

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

Interface MQTT Broker Configuration

The Configuration section can be accessed by pressing Settings button .

In this section it is possible to configure the different topics that can be received/sent through MQTT.
For each topic, also the QOS can be configured, where QOS is the Quality of Service related to the delivery of the packet to the receiver:

• QOS 0 → the gateway publishes the message and there is no acknowledgment from the broker;
• QOS 1 → the broker sends an acknowledgment to the gateway when the message is received.

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.

Event Topic

This topic contains the events sent by the system. The default structure is blueup/gatedetector/events/<event-id>/<event-timestamp>.

Other Placeholders that can be defined 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.

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.

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-name is the request name.

Broker log

This section contains the Logs provided by the MQTT Broker. To enter the Broker log section press on icon in the upper right corner.

Gateways

gateway handler come plugin. attualmente solo gw01

Tags

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

For each Tag the available information is listed in the table, having the following fields:

• Basic information about the tag, such as ID, MAC Address, Alias (if set), UUID, Major;
• Information about the state of the tag: Still / Moving and State time, that is for how long the tag has been in the current state;
• Alarm states that indicates the condition that triggered an alarm, among Button Short, Button Long, Freefall;
• Anchors that currently detect the tag. When pressing on the number of anchors that detect the tag appears a table of that anchors with the related information:
  • RSSI Attenuation is the attenuation of the RSSI signal with respect to the RSSI calibrated at 1 meter;
  • RSSI is the RSSI value after it has been filterd. GateDetector has embedded an RSSI filter that is used to filter noisy signals;
  • RSSI Raw is the raw RSSI value, before filtering.

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.
For Gate Installation options refer to Gate Installation guide.

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) direction.
The direction of the transits then will be calculated based on the definition of IN and OUT gateways.

When defining a gate, by pressing button in the upper right corner, the parameters to setup are described below.

• ID - Gate unique identifier;
• Description - Brief description of the gate;
• IN / OUT Anchor - to be chosen among the gateways detected in the network. Make sure to properly define the IN and OUT gateways to signal the correct transit directions. For a more user-friendly display, the gateways can be defined with different colors.
• IN / OUT Anchor RSSI offset - is the RSSI adjustment with respect to the Calibrated RSSI at 1 meter. In most cases this parameter should remain 0;
• Anchor Detection timeout - the maximum time delay, after which the tag will be disconnected from the anchor and will be marked as Not detected;
• 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 of a too high signal reception delay;
• 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 gateway 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 under which the tag is considered out of gateway's range;
• RSSI filter process noise - process noise used to filter the RSSI values;
• RSSI filter measurement noise - measurement noise used to filter the RSSI values. The raw RSSI signals are filtered with Kalman filter to smoothen the oscillations of the signal.

After saving the gate, it will be listed in the Gates tab. For each gate, in the tab are summarized some configuration parameters.

Pressing button of the corresponding gate allows to open the gate tab. The gate tab is divided into 3 sections: Detected tags, Transits, Sessions. Each section in described in the following.

Detected Tags

The Detected tags section can be accessed by pressing button in the upper right corner.

In this tab are listed all the tags detetcted by the gate, after they have been filtered with the tag filters.

For each tag are listed some important data:

• Tag information such as ID, MAC address, Alias, Motion;
• Normalized RSSI between the tag and the two gateways of the gate;
• ΔdB of the signals from the two gateways;
• Anchor async value;
• RSSI Monitor is a real time plot of the signal received by the two gateways from the tag. The signals are plotted real-time, only when the chart is kept open.

Transits

The Transits section can be accessed by pressing button in the upper right corner.

Sessions

The Sessions section can be accessed by pressing button in the upper right corner.

Plugins

Plugins are additional functionalities to the software that are different from the embedded ones. With the plugins the user can extend the native functionalities, without changing the basic structure of GateDetector.

GateDetector has pre-installed one plugin: Sample Email notification to allow the users to evaluate and explore the plugins strength.

Other Plugins are already available to be integrated in your GateDetector. Otherwise it is possible to discuss the possibility of developing a plugin for your own use case and for your own necessity.
In any case, to have more information you can reach us by opening a ticket or by writing an email at support@blueupbeacons.com

Sample Email notification

This plugin enables the email notifications for:

• System start/stop
• License status
• Gateways status changes
• Low battery nodes

When the plugin is configured and when one of the above mentioned events occurs, the system sends an email to the configured email address(es) to notify which event has occurred.

Configuration

The user should have an SMTP Server that can be used for email sending and the system must have the Email Service properly configured.

First, the Email service should be configured:

1. Define an SMTP Server in Settings » IO » SMTP Servers
2. Configure the service in Settings » System » Email Service specifying:
   • The SMTP Server created at point 1
   • The sender description (optional)
   • The sender email address, that is the email address the MeshCube will use to send the emails

To start receiving the email notifications, in the setting of the plugin the user should setup the following parameters:

• Enter a valid list of email addresses the email notifications will be sent to
• Select the events that trigger the email sending
• Save the configuration

Once that one of the selected events occurs, MeshCube will send an email to the configured email addresses.

APIs

The GateDetector platform also has a little documentation section, where are documented:

• Events generated by the system;
• HTTP APIs;
• FTR Queries.

FTR Queries

FTR Queries are scripts that allow to define some functions for the call of some APIs.
FTR stands for Filter, Transform, Reduce and these functions are to be written in JavaScript.

When adding a new query (by pressing ) the user has to define:

• the API path, that is the API call to which the FTR will be applied. The currently supported API calls are:
  • /api/gates
  • /api/gate/<id>/sessions
  • /api/gate/<id>/transits
  • /api/tags
• the name of the query without blank spaces;
• query description;

The script can contain Filter, Transform and Reduce functions, described in the following.

All the three functions are optional

When creating a new query, a query template will open.

Above the code field, there are some useful buttons:

• to edit the Api, name and description of the query;
• to export the query;
• to delete the query;
• to enable / disable the query. When the query is disabled, calling the API with query will return the same response as calling the API without query;
• to automatically format the code;
• to heck the validity of the code;
• to show / hide the list of defined parameters. When showing, it is possible also to define a new parameter.

In the system there is already a query template tha can be modified or used as a basis for a new query.

Filter

When defining the Filter function, it is applied to each element of the data set. When defining the filtering rule, the data set will be reduced to the only elements that satisfy the filtering condition.

Transform

The Transform function is used to retrieve only the desired fields of the data set.

Reduce

The reduce function is used to manipulate the output array.

A possible usage is to return only the number of elements that satisfy the query:

reduce(obj => obj.length); 

After setting up the FTR Query, to call the defined API with the defined query, the API call structure will be (example for /api/gates):

<gatedetector_ip_address>/api/gates?q=<query-name>

Logs

System logs

The Logs keep track of the system messages that can be used to track the software activities. The logs can be accessed by pressing button in the upper right corner.

It is possible to filter the logs that are displayed by enabling or disabling different log levels, in the upper left side of the page, by choosing among:

• Information
• Warnings
• Errors
• Debug
• Verbose

System events

The system Events page can be accessed by pressing button in the upper right corner.

These logs contain all the events of the system, if the event tracking is enabled by pressing the button.
The full description of the events can be checked in API Events tab.