MeshCube User Guide v.5.6

BlueUp Processing Engine BPE is a BlueUp proprietary engine used to process different kind of information, such as positioning, sensing and beaconing. MeshCube is an IoT platform for positioning, tracking and distributed monitoring, developed by BlueUp. MeshCube uses Wirepas 2.4GHz mesh network technology as backbone for device communication. MeshCube integrates the following functionalities:

• positioning: this is the core functionality of MeshCube. Position of the Mesh Tags is provided with a typical interval of a few minutes, and can range from a minimum value of 15 seconds to a maximum value of 18 hrs. Minimum value is to be used only in specific conditions (e.g. ALARM state) as it consumes high values of energy and drains the batteries quickly;
• monitoring: sensor data is collected from Mesh Anchors or Mesh Tags that are equipped with sensors;
• beaconing: both Mesh Anchors and Mesh Tags can be enabled to broadcast Bluetooth Low Energy advertising packets for beacon use.

BPE is provided with a user-friendly web interface, that will be described in this document, and with API calls that can be used of further integration.

System Info

This first tab of the BPE Web Interface displays all the necessary information about the software, the license (type of license and validity) and network. The license of MeshCube is Server only.

Note: for owners of previous versions of MeshCube with Dongle license, the license status is checked every 5 minutes. If the Dongle is removed while the software is running, at the following license check the license error “No Dongle Detected” will appear. If the error persists, after 2 hours the software will stop responding to the API calls and will disconnect also from the MQTT Dispatcher. In case the user tries to connect to the BPE software when the Docker is not connected the “No Dongle Detected” error will appear in the login page.

System Settings

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

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/bpe/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/bpe/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.

Request topic

This topic is used by the client to send the requests to the system. The default structure is blueup/bpe/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/bpe/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 is the request name,
• request-id is the request identifier generated by the client in the request topic.

Broker log

This section contains the Logs provided by the MQTT Broker.

Maps

The Map section allows to visualize the position of the tags on the map. To do that the Sink and the Router nodes (positioning anchors) should be placed on the map so that the tags 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 anchor 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.
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, and with the left mouse button press on the points where the vertexes of the zone should be (press Ctrl to stick the vertex to the guide).
   Press Enter to create and save the zone.
   With the right press on the zone appear a menu that allows to edit the zone or to delete it.
4. Select Place Sink/Routers on the map in Actions menu, select the Sink or Router to place o the map and place it on the map.
   To move a Sink or Router right click on it an a menu will appear, from which it is possible to move or delete a node.
   In Layers menu it is possible to select the items visible on the map, such as the Guides, Zones, Mesh Nodes, Tags, and others. Two important items are Tag Accuracy and Positioning anchors. Tag 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.

MeshCube

MeshCube application includes MeshIPS, MeshSense and MeshBeacon.

MQTT Broker Log

This section contains the Logs provided by the MQTT Broker.

MQTT Broker Packets

This section contains the Packets received from the MeshCube devices. In the Logging Menu it is possible to enable or disable the logging, change the display time, that is the time for which the logs will be displayed on the interface, and change the Storage time, that is the time for which the logs are stored on the disk. When downloading the logs, it is possible to download all the logs or to specify the logs to download, based on the date, the network, the node address, the type of log.

Network configuration

The network configuration tab allows to configure the diagnostics interval of the Mesh Network and also allows to configure the Mesh Nodes. If needed, there is a possibility to visualize all the previous configuration versions, in the menu in the right upper corner. It is possible to configure one or more node classes at the same time. A problem that could arise when defining the configuration is due to the length of the configuration. From the interface, the configuration is translated into a stream of bytes. This stream of bytes must have a maximum length of 80 bytes. If the network configuration, after it has been translated into bytes, exceeds the 80 bytes an error will appear. Note: to make the byte stream shorter, eliminate useless configuration parameters (accelerometer, beaconing) or configure one (maximum 2) node class at a time.

Router node configuration

This setting allows to configure all the Router Nodes of the Network at the same time. The settings include the sensing interval, the alerts enable and the configuration of the Beaconing. The supported beaconing packet types for the Router Nodes are iBeacon and Eddystone-UID.

Non Router node configuration

As for the Non Router Nodes, we can distinguish between Asset and Personal Tags. The distinction is made to allow the user to configure the two types of the Tags with different parameters. The Non Router Node Configuration contains the base configuration parameters, that refer to the Mesh Non Router Node functioning, and Advanced configuration parameters, such as Advanced Accelerometer Configuration and Beaconing Configuration.

Besides the Motion configuration (Threshold and Duration), the Advanced Accelerometer Configuration allows to add other Accelerometer detection modes, such as Position, Shock, Freefall and ManDown detection and to define proper parameter values. The beaconing packet types supported by the Non Router Nodes are iBeacon, Safety and Quuppa Emulation Mode.

Gateways

This tab contains the list and information of all the Gateways detected in the network, grouped in Connected Gateways and Available Gateways detected on LAN. For all the gateways there is a direct link to the Web Interface of the Gateway. In case of the available detected gateways, it is possible to directly connect the gateway to the interface, with the “Connect” button.

Alert manager

The alert Manager tab allows to create and save some tag alerts without having to compose them by hand. By pressing the + button on the right on top, a configuration panel opens (Fig. 21) from where the user can specify all the alert parameters and assign an alert ID.

Once the alert is saved it will appear in the Alert Manager tab and the alert can be edited at any time. The alert can be sent from the Node tab, by pressing the Send command button, selecting the Alert enable option.

The user now can choose to compose the alert manually or to choose one of the alerts saved previously.

Nodes

This section contains the list of all the detected mesh Nodes, divided into Sink, Router and Non Router Nodes. For each Node the tables contain information about that node.

For the Sink Nodes it is possible to set a Detection timeout, in the settings menu. The second-last column in router and non-router nodes table contains the Config button, that allows to display the current node configuration. The Config button can have four states, with different colors:

• Grey – the system has not received the node configuration yet.
• Red – the configuration received from the node is different from the Network Configuration set in the interface. It can happen, for example, when the new configuration has been set and the nodes have not been configured yet.
• Yellow – the node class configuration in not present in the last Network Configuration. This can happen since we can add or eliminate node classes when configuring the nodes in the network.
• Green – the configuration has been correctly received.

In case of Router and Non Router Node it is possible to send commands to one or to all nodes. The commands are:

• Reboot the device
• Button Enable / Disable
• Alert Enable / Disable
• GPIO Configuration to configure the IO Pins.

Firmware update

In the right upper corner there is the Firmware Update menu. To do that, a firmware file has to be uploaded and, once it is uploaded, the new firmware will be spread all over the network. If, for some reason, there is a node that is out of network, the firmware update will get stuck trying to connect to the last node. While the firmware update is running, it is possible to Cancel the update, selecting if to stop the update completely or to keep the update in background, so that the firmware update will be performed on the new nodes that will be introduced in the network.

MeshIPS

When the Router Nodes are placed on the Map and are configured to detect the devices in the nearhood, these Nodes become Anchors. While when the Non Router Nodes are configured to be localized, they become Tags. When the Nodes are configured as Anchors and Tags and are configured with the positioning functionalities, they become part of the MeshIPS localization system.

Tags settings

The Detection Settings are used to set the decision rule for the detection of Mesh Tags. The Detection Timeout is the time interval after which the tag is considered inactive when there is no update from the tag. The remove not detected tags time defines the rule of the remove of an inactive Tag from the Tags list.

Positioning settings

The Positioning settings allow to define the Tag positioning rules.

• Tag Positioning Settings allow to define the basic rules for positioning. The two possible Positioning Modes are Trilateration based 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 best chosen zone.

• Advanced Settings defines the rules for choosing the best option, in case of multiple Maps, multiple Zones or Trilateration positioning.

  • The RSSI Threshold is the min RSSI 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 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.

  • For Trilateration, it is possible to define the Max and Min number of Anchors to take into account when calculating the tag’s position.

• Logging allows to enable or disable the logging option. If needed, a TagID pattern can be defined, to log the events of those tags that contain the set pattern

Mesh Anchors

In this tab are listed all the Router Nodes configured as Mesh Anchors. For each Anchor is specified the information about its position, positioning settings (positioning enabled, calibrated RSSI, N), last update and battery level, if the Anchor is battery-powered. The positioning parameters can be changed for one or for all Anchors, in the menu with the setting symbol.

Mesh Tags

In this section are listed all the detected Non Router Nodes configured as Mesh Tags. For each Tag the table contains information about the position of the Tag, the tag state, the Alarm type, if the alarm was enabled, and operation mode. The possible Alarms are button short, button long, double button press, horizontal position detection, shock detection, freefall detection, mandown detection.

A Mesh Tag has four operating states, that are Default, Sleep, Motion and Alarm, as shown in Fig. 30. The main state is Default and if the accelerometer and the alarms are not configured, the tag never exits Default state. Otherwise, if the accelerometer detects a motion, the tag enters Motion state or, if an alarm is detected, the tag enters Alarm state. If the tag hasn’t changed its state for the duration of Default State Timeout, the tag enters Sleep state. From Motionstate, after Motion State Timeout, the tag switches to Default state. In case an alarm is detected, it enters Alarm state. The tag enters Alarm state after an alarm detection, such as button pressure, horizontal position, shock, mandown, freefall detection. From Alarm state the tag can switch to Motion state, if a motion is detected, or to Default state, after the Alarm State Timeout. The Sleep state is the best operating state if the Tag is stationary for most of the time, since it is a low power consuming mode. The tag exits Sleep state only if a movement (Motion state) or an alarm (Alarm state) is detected.

MeshSense

Mesh Sense collects all the nodes that are designed and configured as Sensors. For each sensor, data of Temperature, Humidity, Pressure, CO2 and VOC are collected and displayed, if available. In case of CO2 levels, also the air quality is evaluated:

• EXCELLENT if CO2 is under 700 ppm
• GOOD if CO2 level is between 700 and 1000 ppm
• MEDIUM if CO2 level is between 1000 and 1600 ppm
• BAD if CO2 level is over 1600 ppm

MeshBeacon

Mesh Beacons are Nodes with Beaconing enabled when configuring the Nodes, that is configurable for both Anchors and Tags. For each node class it is specified the type of beaconing, the frame, based on beaconing type, advertising interval values and advertising TX power, set when configuring the devices. The possible Beaconing types for Anchors are iBeacon and Eddystone-UID, while for the Tags are iBeacon, Safety and Quuppa Emulation Mode.

Logs

System logs

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

System 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.

Starting from MeshCube v. 5.6.6 some events contain a new field, called travel_time [ms]. Travel time is the delay with which the packets sent on the mesh network by Wirepas devices (anchors or tags) reach the sink/gateway, due to a low energy algorithm. Using Travel Time, it is possible to calculate the actual timestamp of a certain event by subtracting the value travel_time" [ms] from the event timestamp. Events that contain travel_time field are:

• meshNodeGPIOChanged
• meshNonRouterNodeDetectionUpdate
• meshTagAlarmOff
• meshTagAlarmTriggered
• meshTagOperationModeChanged
• meshTagStateChanged
• tagPositionChanged