User Guide v4.8

LocateBLE Software has a user-friendly web interface that can be used for configuration and monitoring purposes. In the following will be described all the web interface tabs layout, parameters and important characteristics of the system.

System Info

This is the first tab the user sees after logging in the system. Here are described the characteristics of the software itself, like General Info, License and Network Interfaces.

System Settings

In this section it is possible to change some important settings such as Access Password and HTTP Port. The Web Workers Settings allow to define the number of Web 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.

MQTT

MQTT is a publish/subscribe network protocol used to transport messages between devices. MQTT communication can be configured to receive push messages from the system, without using the BlueUp web interface.

MQTT Certificates

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

MQTT 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 Interface Configuration

The different topics that arrive from LocateBLE to the user though the MQTT Broker can be configured to be easily recognized. In the following are described the different topics and their default schemes defined by BlueUp.

For each topic the Quality of Service (QOS) level has to be configured. QOS is an agreement between the client and the broker on the guarantee of delivery of the message. There are tree possible QOS levels:

• 0 - At most once - this level guarantees a best-effort delivery. The client simply publishes the message and there is no acknowledgement from the broker, so the delivery is not guaranteed.
• 1 - At least once - this level guarantees that a message is delivered at least once to the receiver. It means that the sender stores and resends the message until an acknowledgement is received. That the sending is guaranteed, although the message may be received multiple times.
• 2 - Exactly once - this level guarantees that each message is received only once by the receiver.

Status topic

Status 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/locateble/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

Event Topic contains the events sent by the system. The default structure is blueup/locateble/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, with precision of hundredths of nanoseconds,
• event-id is the event identifier,
• event-number is a unique numeric identifier of the event,
• event-timestamp is the timestamp of the event, with precision of hundredths of nanoseconds.

Request topic

Request Topic is used by the client to send the requests to the system. The default structure is blueup/locateble/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

Response Topic contains the responses to the requests. The default structure is blueup/locateble/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, with precision of hundredths of nanoseconds,
• request-id is the request identifier generated by the client in the request topic,
• request is the request name.

Broker log

This section contains the Logs provided by the MQTT Broker.

Maps

In this tab it is possible to visualize the position of the tags on a map. To do that the positioning locators should be placed on the map so that the Tag position can be computed.

In the following are described the steps to configure the map.

1. In the Maps tab in the upper right corner press on Create new map. To define the map the user has to upload the map image and define the Scale of the map in pixels per meters. This parameter is important to calculate the position of the tag, converting the pixels in the actual distance from the anchor to the tag.

2. For an easier locator placement on the map it is possible to place the guides. To do that, enable the Guides in Layers menu and then in Actions menu select Add Vertical / Horizontal Guide. To move the guide, press with the left mouse button on the edge of the guide and move it. To eliminate the guide from the map, click with the right button on its edge.
   To let anything stick to the guide lines press the Ctrl button and then place it there.

3. Create the Zones on the map. This is useful in case the user wants to compute the position of the tag based on the zones. In Actions menu press on Create new zone, with the left mouse button press on a point in the map where one of the vertexes of the zone will be (press Ctrl to stick the edge to the guide) and then drag the mouse to draw a rectangle. Press on one of the edges to modify the shape of the rectangle.
   To build a different shaped zone it is possible to add or delete vertexes:

   • Shift + left mouse click on a vertex to add another vertex on the left
   • Shift + Ctrl + left mouse click on a vertex to eliminate that vertexes

   Press Enter to create and save the zone.

4. Before placing the Anchors on the map it is possible (but not mandatory) to place the Placeholders. They are the place markers for the locators. This step is useful during the design, to first decide where the locators will be placed, since it is easier and faster to move a placeholder than a locator.
   In the Actions menu select Add Gateway placeholder and place it on the map (Ctrl to place it on a guide). To align other elements with a placeholder, right click on it and select Create guides from the Placeholder.

5. Place the Gateways. The first way to place a gateway on the map is to right click on a Placeholder and select Place gateway here. Choose a gateway from the list of available gateways that will appear.
   Otherwise it is possible to directly place a gateway on the map selecting Add GW01 Gateway (or another Gateway type if requested).
   To move a Gateway on the map press Shift button, select the gateway and click on the map where to place the gateway.

In Layers menu is possible to select the items visible on the map, such as the Guides, Zones, Gateways, Tags, and others. Two important items are Accuracy and Positioning anchors.

Accuracy, applied to the tags, shows the accuracy range of the position of the Tag, while the Positioning anchors for each tag show which anchors contribute to the position calculation and the RSSI value between Tag and anchor.

On the bottom of the page there is the Tag filter that allows to filter the tag/s to be visualized, specifying the Tag ID, Alias, MAC Address or UUID.

Other keyboard shortcuts:

• Ctrl + mouse wheel to zoom in and out the map view;
• Shift + mouse wheel to move the map view on the right and left;
• Ctrl + F12 to restore the default map view (after zooming or moving).

Gateways

In this section are listed all the Gateways present in the system. The system can handle more than one Gateway type at the time and all the connected gateway types are listed in the drop-down menu. It is possible to request the integration of a particular Locator type to be handled. When the handler is ready and integrated it will be visible in the drop-down menu.

The symbol near the drop-down menu allows to start and stop the Gateway Handler operations. For each Gateway handler in the settings menu there are the Configure and Enable/Disable buttons. The Enable/Disable button allows to enable or disable the automatic startup of the Handler after the Service restart. The Configure button is adapted to the configuration parameters of the Gateway type and it changes based on the current gateway type handled.

One important configuration is the choice of the IP address in case more than one network interface is configured, since the LocateBLE Server has a different IP address for each network interface. This is necessary since the Gateways have to be informed on where to send data. In this case, the Controller port and Listener port for the Gateways have to be specified.

The interface where the Gateways are listed is adapted to the Gateways type, based on the information received from the gateways, and thus there is no standard structure. The columns that are common to all the gateway types are Map, Zone, Position, Last activity, Last advertising, Configuration and Remove. Map, Zone and Position describe where the gateway is located, specifying the Map, the zone (if defined) and the coordinates (x, y).

GW01

GW01 is the default Gateway type supported by LocateBLE.

Other Gateway types will have different characteristics and configuration parameters.

To connect new Gateways it is possible to click on the ‘+’ button and select one of two options: Scan the network, after which all the Gateways detected in the network will be listed, or Enter the Gateway IP if you already know the IP address of the Gateway to connect. When the Gateways to connect have been selected and OK button pressed, it will take a few seconds to connect to them and to list them in the Gateways List.

In the right corner the settings button allows to configure some GW01 gateway parameters. An important setting is the Gateway payload filter. This filter is necessary to filter out some bluetooth packets and to be able to receive only the necessary packets. One or more filters can be set at a time and there are some general filter formats:

• iBeacon

  • generic payload: 0201061aff4c000215
  • payload including BlueUp UUID: 0201061aff4c000215acfd065ec3c011e39bbe1a514932ac01

• Safety payload including BlueUp UUID (xx is a wildcard, meaning that any value at that position is accepted): 0201061aff4c000215a565cc841e0e4b5ab2d317c98ff541xx

• Eddystone

  • generic payload: 0201060303aafexx16aafe
  • UID payload: 0201060303aafexx16aafe00
  • URL payload: 0201060303aafexx16aafe10
  • TLM payload: 0201060303aafexx16aafe20

To have a more user-friendly interface, it is possible to define an alias to each gateway, to be able to better recognize them. Each gateway has its own IP address that is specified in this table. RSSI Threshold is the minimum RSSI value that allows to detect a Tag. If the RSSI between a given tag and gateway is below the threshold, the Tag is considered Far and the gateway will not be considered when computing the tag position. Moreover, this particular type of locators (GW01) allow to configure the BLE Advertising channels to use. It is suggested to enable all the three channels, if there are no particular use cases.

The BT Filter column shows whether a bluetooth filter was set or not. If not, the icon is grey. The filtering can be set also for each gateway separately in actions menu in the Configure BLE setting.

Tags

Tags are mobile devices that are associated to people or assets to be able to track them. LocateBLE supports different types of tags: iBeacon, Safety or it is possible to request the integration of a particular Tag type to be handled. When the handler is ready and integrated it will be visible in the drop-down menu.

For each Tag type is defined a Tag Handler that, as for the Gateways, handles the characteristics and the configuration parameters of each tag type. To be able to visualize the list of the tags and to configure them, the Tag Handler (for both iBeacon and Safety) have to be started, by pressing the green arrow near the drop-down menu.

iBeacon tags

IBeacon is one of the two default tag types handled by LocateBLE. In this section is displayed a table containing the list of the detected Tags with related information. Each Tag has its own ID, MAC Address and, if defined, an Alias for easier detection of the tag. Two important parameters for Tag detection are Anchors, that counts the number of anchors that detect that tag, and Nearest Anchor, that displays the anchor that detects the tag with the highest RSSI, the RSSI value and the relative position of the tag with respect to that Anchor (Immediate, Near of Far).

For each tag the complete information about the detected anchors can be seen by pressing the Monitor button. Here are listed the anchors that detect the tag, specifying the RSSI strength and the estimated distance between the tag and the anchor. In the table below is summarized the Map selection algorithm:

• 2 maps are compared at a time (if in the system are defined 3 maps, the table will contain 3 lines (Map 1-2, map 2-3, map 1-3).);
• for each map is specified the anchor with the highest RSSI value;
• the difference between the highest RSSI value is computed. If the difference is higher then the Map RSSI Threshold than the map with the highest RSSI value is chosen;
• otherwise, the average RSSI value is computed for each map, averaging the Map Averaged Anchors. If the map has a lower number of anchors, the missing number of anchors is set to -90dBm. If the difference is higher then The Map RSSI Threshold than the map with the highest RSSI value is chosen.

By pressing the Settings button, it is possible to Configure the iBeacon Tags or to disable the Tag Handler that is currently displayed. The Configuration menu is composed by four tabs, each grouping different configuration parameters.

iBeacon UUID List

The UUID List is divided into:

• Registered UUID. Are the UUIDs detected and already registered into the system. The registration of an UUID allows to list the Tags with that UUID in the iBeacon Tag list.
• Unregistered UUID detected by the system. Are the UUIDs detected but not registered. These Tags will not be listed in the iBeacon Tag list and the user is not able to track this type of tags.The UUID List is divided into:

iBeacon Tag Settings

This section allows to setup the rule to remove an iBeacon from the system. If the Remove Not Detected Tags flag is set to true, it means that the tag will be removed from the system if the tag is no more detected by any of the anchors. Anchor Detection Timeout is the time after which, if no data was received form the tag, the Anchor states that it does not detect the tag any more.

iBeacon Anchor Settings

In Anchor Settings has to be chosen the type of Anchors that will detect the iBeacons. Only one Anchor type can be chosen. Globally, for all the Anchor category at once, can be set the environmental parameter N (suggested value is 1) and the RSSI Offset. The offset can be set in particular cases to modify the power of the received signal. Therefore, it is suggested to keep this value on 0dBm and change it only if needed.

In this tab the user can change the Proximity parameters. Proximity is a vicinity detection application. The following parameters can be changed:

• “Immediate” detection threshold allows to set the Attenuation Value under which the distance between a Tag and the Gateway is Immediate.
• “Near” detection threshold is the Attenuation value under which the distance between a Tag and the Gateway is considered Near. Over this Attenuation value the distance is considered Far.
• State Transition Threshold is the minimum value of the RSSI Variation to change the Proximity state. This threshold is set to stabilize state transitions in case of an irregular signal.
• State Time Hysteresis allows to set the time interval for which the Tag has to remain in the same state before changing it. This setting too is used in case the signal is irregular.

Then, these parameters can be tuned for each anchor separately. Moreover, in the individual settings menu, it is possible to define the capabilities of each Anchor. The Anchor can assume the following capabilities (one or more at a time):

• Positioning allows to track and locate the Tags.
• Proximity is used for vicinity detection.

iBeacon Positioning Settings

In positioning settings the user can define the rules to compute the position of a Tag. Tag’s position is computed if and only if the Positioning enabled button is set on True. Positioning Settle Time is the time after which the tags position can be computed after a condition for which the first tag position has to be computed (for example system restart, a new tag appearance or other). The positioning can be Trilateration or Zone Based. In case of Trilateration, the exact position of the Tag is calculated geometrically, based on the signal strength indicator RSSI. In case of Zone Based positioning, when defining the zones on the map, the Anchors that are in a zone are automatically associated to that zone. In this case, the algorithm estimates the best zone where the tag is, based on the RSSI value. After that, the algorithm estimates the position of the tag, based on the RSSI values of the Anchors in the best chosen zone.

The following parameters are used for the Tag position estimation:

• Positioning Interval is the time period of the update of the Tags position.
• Anchor RSSI Threshold is the minimum RSSI value received from the Tag to consider. If the received RSSI is lower than the threshold, then the tag is too far from the anchor and the anchors contribution is not useful for the positioning of the tag.
• Movement Threshold is the minimum space difference between the previous and the current tag position to trigger the position update. This setting is useful to avoid tag position updates if the position has not changed significantly.
• The Map and Zone RSSI Threshold is the min RSSI difference value to decide that one Map or Zone is better than the other(s), comparing the Max RSSI value of the Map or Zone.
• The Map and Zone Averaged Anchors is the number of anchors to consider when calculating the average RSSI. The average RSSI is taken into account when the RSSI difference between Anchors of the Map or Zone is lower than the RSSI Threshold value.
• The Max and Min number of Anchors is the number of anchors to take into account when calculating the tag’s position.

Safety Beacon Tags

Safety packet is a BlueUp proprietary packet format, built on the basis of the iBeacon format. The table containing the list of tags contains also some information related to each tag. Each Tag has its own ID, MAC Address and, if defined, an Alias for easier detection of the tag. The Safety tags send the system also the state of the tags: motion or still, if the button was pressed (short or long pressure) and if a free-fall event has occurred. Two important parameters for Tag detection are Anchors, that counts the number of anchors that detect that tag, and Nearest Anchor, that displays the anchor that detects the tag with the highest RSSI and the RSSI value and the relative position of the tag with respect to that Anchor (Immediate, Near of Far).

For each tag the complete information about the detected anchors can be seen by pressing the Monitor button. Here are listed the anchors that detect the tag, specifying the RSSI strength and the estimated distance between the tag and the anchor. In the table below is summarized the Map selection algorithm:

• 2 maps are compared at a time (if in the system 3 maps are defined, the table will contain 3 lines (Map 1-2, map 2-3, map 1-3));
• for each map is specified the anchor with the highest RSSI value;
• the difference between the highest RSSI value is computed. If the difference is higher then The Map RSSI Threshold than the map with the highest RSSI value is chosen;
• otherwise, the average RSSI value is computed for each map, averaging the Map Averaged Anchors. If the map has a lower number of anchors, the missing number of anchors is set to -90dBm. If the difference is higher then The Map RSSI Threshold than the map with the highest RSSI value is chosen.

By pressing the Settings button, it is possible to Configure the Safety Tags or to disable the Tag Handler that is currently displayed. The Configuration menu is composed by four tabs, each grouping different configuration parameters.

Safety UUID List

The UUID List is divided into:

• Registered UUID. Are the UUIDs detected and already registered into the system. The registration of an UUID allows to list the Tags with that UUID in the Safety Tag list.
• Unregistered UUID detected by the system. Are the UUIDs detected but not registered. These Tags will not be listed in the Safety Tag list and the user is not able to track this type of tags.

Safety Tag Settings

This section allows to setup the rule to remove a safety from the tag list. If the Remove Not Detected Tags flag is set to true, it means that the tag will be removed from the system if the tag is no more detected by any of the anchors. Anchor Detection Timeout is the time after which, if no data was received form the tag, the Anchor states that it does not detect the tag any more.

Safety Anchor Settings

In Anchor Settings has to be chosen the type of Anchors that will detect the Safety tags. Only one Anchor type can be chosen. Globally, for all the Anchor category at once, can be set the environmental parameter N (suggested value is 1) and the RSSI Offset. The offset can be set in particular cases to modify the power of the received signal. Therefore, it is suggested to keep this value on 0dBm and change it only if needed.

In this tab the user can change the Proximity parameters. Proximity is a vicinity detection application. The following parameters can be changed:

• “Immediate” detection threshold allows to set the Attenuation Value under which the distance between a Tag and the Gateway is Immediate.
• “Near” detection threshold is the Attenuation value under which the distance between a Tag and the Gateway is considered Near. Over this Attenuation value the distance is considered Far.
• State Transition Threshold is the minimum value of the RSSI Variation to change the Proximity state. This threshold is set to stabilize state transitions in case of an irregular signal.
• State Time Hysteresis allows to set the time interval for which the Tag has to remain in the same state before changing it. This setting too is used in case the signal is irregular.

Then, these parameters can be tuned for each anchor separately. Moreover, in the individual settings menu, it is possible to define the capabilities of each Anchor. The Anchor can assume the following capabilities (one or more at a time):

• Positioning allows to track and locate the Tags.
• Proximity is used for vicinity detection.

Safety Positioning Settings

In positioning settings the user can define the rules to compute the position of a Tag. Tag’s position is computed if an only if the Positioning enabled button is set on True. Positioning Settle Time is the time after which the tags position can be computed after a condition for which the first tag position has to be computed (for example system restart, a new tag appearance or other).

Positioning can be Trilateration or Zone Based. In case of Trilateration, the exact position of the Tag is calculated geometrically, based on the signal strength indicator RSSI. In case of Zone Based positioning, when defining the zones on the map, the Anchors that are in a zone are automatically associated to that zone. In this case, the algorithm estimates the best zone where the tag is, based on the RSSI value. After that, the algorithm estimates the position of the tag, based on the RSSI values of the Anchors in the best chosen zone.

The following parameters are used for the Tag position estimation:

• Positioning Interval is the time period of the update of the Tags position.
• Anchor RSSI Threshold is the minimum RSSI value received from the Tag to consider. If the received RSSI is lower than the threshold, then the tag is too far from the anchor and the anchors contribution is not useful for the positioning of the tag.
• Movement Threshold is the minimum space difference between the previous and the current tag position to trigger the position update. This setting is useful to avoid tag position updates if the position has not changed significantly.
• The Map and Zone RSSI Threshold is the min RSSI difference value to decide that one Map or Zone is better than the other(s), comparing the Max RSSI value of the Map or Zone.
• The Map and Zone Averaged Anchors is the number of anchors to consider when calculating the average RSSI. The average RSSI is taken into account when the RSSI difference between Anchors of the Map or Zone is lower than the RSSI Threshold value.
• The Max and Min number of Anchors is the number of anchors to take into account when calculating the tag’s position.

Plug-ins

Plug-ins are additive functionalities to the software different from the default ones. The users can request to add some functionalities that are not embedded in the system or decide to use the base functionalities only.

To have more information about the plug-ins and additive functionalities, please contact us at support@blueupbeacons.com

To add the plug-ins, first of all a file will be sent by the BlueUp team. Press on “+” button in the right corner and upload the received file. The system then will ask to restart the service and after that the plug-in will be added and ready to use.

APIs and Docs

APIs

This section contains the summary and brief description of the APIs available to the system. The APIs list contains all the default API calls and if the plug-ins are added, the API related to the Plug-ins will be automatically listed here too. Each API call contains a “Try it out” button that allows to send the request and receive the response from the system. This button is equivalent to call an API using the browser call http://IPaddress/api/locateble/api_call or using any other MQTT or HTTP communication software.

.

One important API command is the Proximity Get and Post command. By requesting /proximity in Get the response contains the full information about the Tags, Gateways and the proximity level (Far, Near, Immediate). The same command can be requested using the Post method. In this case if the request body is empty then the response will be identical to the Get request. Otherwise some parameters can be specified in the request body.

• Subject. Specifying the “tag” or “anchor” in the subject, the response will be giver from the subject’s point if view. As an example, in case the subject is a Tag, for each tag will be specified the connected gateways and the tag proximity level. While if the subject is anchor, then for each anchor will be listed the tags with the related proximity level.

• Tag. The user can specify a Tag ID to receive proximity information related to that tag.

• Gateway. In the response will be listed all the tags detected by that gateway with the proximity level.

• Proximity. The user can filter by the proximity level:

  • 0 – none
  • 1 – far
  • 2 – near
  • 4 – immediate.

Events

This section contains the list and the description of the events that can be sent by the system to the client through MQTT or HTTP APIs.

Logs

The Logs section contains all the Logs generated by the system. The Events are generated only if the Generate events button is enabled.