MeshCube User Guide v.6.0.0

MeshCube is an IoT platform for positioning, tracking and distributed monitoring developed by BlueUp.
MeshCube uses Wirepas Mesh 2.4GHz network technology as backbone for device communication. MeshCube is provided with a user-friendly web interface that can be used for monitoring and configuration of Mesh devices.

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.

Project size CPU RAM HardDisk space
Small
20 Anchors + 20 Tags
4 cores 4GB 128 GB
Medium
100 Anchors + 200 Tags
4/8 cores 8GB 128 GB
Large
500 Anchors + 1000 Tags
8+ cores 16GB 256 GB

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

BPE menu

In the upper right corner of the web interface there is the notification center Notifications 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 Off 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.

Off menu

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 Check for updates button.

System information

License

MeshCube 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 MeshCube:

  • 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 MeshCube 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:
    • Maps is the maximum number of maps that the user can create in MeshCube;
    • Anchors is the maximum number of Anchors that are supported. If the number of anchors exceeds the maximum allowable the license will become Not valid;
    • Tags is the maximum number of Tags that are supported. If the number of tags in the system exceeds the maximum allowable the license will become Not valid;
    • Mesh Networks can be "All allowed" or can be a list of allowed networks. This sets the quantity and the network addresses that can be managed by MeshCube instance;
    • MeshIPS module if enabled, MeshCube can manage the positioning function;
    • MeshSense module if enabled, MeshCube can manage the sensor nodes;
    • MeshBeacon module if enabled, MeshCube can manage the beaconing of the nodes;
    • 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.

License expiry

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 settings

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.

Timezone

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

  • 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 settings - Maintenance

System - System Password

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

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

Change password

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 MeshCube will send an email.

System settings - Email Service

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

System settings - Software settings

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.

System settings - WebServer

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 MeshCube 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 MeshCube server will be available also at <service_hostname>.local address in your browser.

System settings - mDNS

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.

System settings - API Settings

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 New token 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.

System settings - 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 Edit
  • Download the tokenDownload
  • Enable Enable token or Disable Disable the token
  • Delete the token Delete

System settings - JWT Token List

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 Upload. The acceptable certificate format is PKCS#12.

System settings - Certificates

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.

In case the same configuration is intended to be used with multiple broker connections, the Username field should be set to auto when configuring.

System settings - MQTT Brokers

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

System settings - MQTT Brokers

Mesh - Mesh handler

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

  • Enable / disable data storage;
  • Packet storage retention days is for how long packets are stored in MeshCube database.

Mesh Handler

Mesh - Gateways Settings

This flag allows to decide whether to periodically scan the local network, searching for new gateways to connect.

Gateways settings

Mesh - Nodes - Alert Templates

In this section are collected all the alert templates that have been created or it is possible to compose a new alert template to send to the nodes. Alert templates are useful for node alerting, without having to compose the alert manually every time.

In the alert template the user has to specify:

  • the ID of the alert to easily recognize it;
  • the description of the alert;
  • buzzer (if enabled) period, number of repeats and duty cycle in percentage;
  • vibration (if enabled) period, number of repeats and duty cycle in percentage;
  • LED (if enabled) period, number of repeats, duty cycle in percentage and the color mask.

The alert then can be sent to the nodes in the Nodes section.

System settings - Alert Template

Mesh - Tags - Tag positioning settings

Tag Positioning settings allow to define the rules for Tag positioning. The settings are divided into 3 configuration levels:

  • Basic
  • Extended
  • Advanced

each described in the following.

Note: When choosing e.g., Basic settings, the parameters in Extended and Advanced settings will be configured with default values.

Basic positioning settings

  • Positioning Mode:
    • Trilateration based: the exact position of the Tag is calculated geometrically, based on the signal strength indicator RSSI of all the anchors that are near the tag (refer to the algorithm);
    • Zone based: 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 inside that zone (refer to the algorithm);
  • Anchor RSSI Threshold is the minimum RSSI value that can be used when evaluating the position of the tag. If RSSI between the tag and an anchor is lower than the set value, the anchor is not considered when evaluating the tag position;
  • Min. / Max. Anchors is the minimum and maximum number of anchors to consider when evaluating the position of the tag.

System settings - Tag Settings - Basic

Extended positioning settings

Additionally to the Basic configuration:

  • Average RSSI for positioning (Default/Sleep) a switch that allows to decide whether to take into account positioning changes when the tag is in Default or in Sleep mode;
  • Map / Group selection - RSSI threshold is the min RSSI value to decide that one Map or Group is better than the other(s), comparing the Max RSSI value of the Map or Group;
  • Map / Group selection - 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 Group is lower than the RSSI Threshold value.

System settings - Tag Settings - Extended

Advanced positioning settings

Additionally to the Extended configuration, the Advanced configuration allows to define the positioning update rules for each state separately. For each state it is possible to set:

  • Position update selecting between Disabled, State transition and Always:
    • State Transition means that the position of the tag will be updated only when the tag changes its state;
  • RSSI update mode between Replace RSSI measurements and Average RSSI measurements, with respect to the previous ones.

System settings - Tag Settings - Advanced

Trilateration algorithm

In case Trilateration is chosen as positioning mode the algorithm performs the following positioning steps:

  1. If in the system there are multiple maps, the algorithm first selects the best Map where the tag is.
  2. If on the map are defined the different Zones, the algorithm selects the Zone where the tag is, based on the highest RSSI between the tag and the anchors of the zones.
  3. Finally, the algorithm evaluates the position of the Tag, based on the RSSI level between the tag and the anchors, applying the Trilateration algorithm.

Zone algorithm

In case Zone is chosen as positioning mode the algorithm performs the following positioning steps:

  1. If in the system there are multiple maps, the algorithm first selects the best Map where the tag is.
  2. If on the map are defined the different Zones, the algorithm selects the Zone where the tag is, based on the highest RSSI between the tag and the anchors of the zones.
  3. Finally, the algorithm evaluates the position of the Tag inside the Zone, based on the RSSI level between the tag and the anchors, applying the Trilateration algorithm.

Note: in case the algorithm is not able to define univocally one zone in which the tag is (e.g. RSSI difference between two zones is lower than the Group RSSI threshold) the position of the tag will be in an array of zones and the trilateration algorithm will be applied considering all the anchors of the array of the zones.

Mesh - Sensors - Mesh Sensors

This setting allows to setup the desired Temperature measurement unit, choosing between Celsius and Fahrenheit. Data will be displayed with the set measurement unit in Sensors section.
It is also possible to setup the Data retention days, that is for how long data is stored in the MeshCube database.

Sensors settings

MQTT

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

In this section are present two subsections:

  • Interface Broker that allows to setup and configure the interface of the MQTT Broker that manages the requests and responses sent by the interface;
  • Mesh Broker section is used to monitor events generated by Mesh network.

The user can setup two different MQTT Brokers or use the same one for Interface and Mesh. In case the same broker is used, the broker Username should be set to auto, as described in MQTT settings.

Interface MQTT Broker Configuration

The Configuration section can be accessed by pressing Settings button Settings.

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

Event topic

Request topic

This topic is used by the client to send the requests to the system. The default structure is blueup/meshcube/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/meshcube/response.

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.

Response topic

Broker log

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

Broker Log

Mesh broker

Mesh MQTT Broker Packets

This section contains the Packets received from Mesh devices.
The packets section can be opened by pressing Broker packets button.

Useful right side buttons are:

  • Toggle packet listener Toggle packets to enable / disable the packet reception;
  • Toggle autoscroll Autoscroll to enable page autoscroll to display the new packets;
  • Delete displayed logs Delete packets to delete the displayed packets.

MQTT Broker Packets

MQTT Broker Log

This section contains the Logs provided by the MQTT Broker.
The log section can be reached by pressing Log section button.

MQTT Broker Log

Maps

The Maps 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.

No map

  1. In the Maps tab in the upper right corner press on Create new map Create new map. To create the map the user has to upload the map image and define the Scale of the map in pixels per meter. This parameter is important to calculate the position of the tag, converting the pixels in the actual distance from the anchor to the tag. Create new map video
  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 one of its ends. Add guides video
  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. Using the left mouse button, press in a spot where one vertex of the zone will be and drag from that point to build a polygon. Release the mouse button. If the zone is not squared, but is an irregular polygon, other vertexes can be added. To add a new vertex, press Shift and press with the mouse on one of the vertexes. The new vertex will be added on the right with respect to the vertex on which you have pressed.
    To move a vertex, press and drag it in the desired position (press Ctrl to stick the vertex to the guide).
    When the zone is setup, press Enter to save the created zone. Create new zone video
  4. Select Place Sink/Routers on the map in Actions menu, select the Sink or Router to place on the map and place it on the map.
    To move a Sink or Router:
    • right click on it and a menu will appear, from which it is possible to move or delete a node;
    • or press Shift and drag the router. Release and press YES if the position if right. Place routers video
  5. Also, it is possible to design the placement of the routers, without physically placing them on the map. This is possible using the Placeholders. In actions menu, select Add placeholder, define the number and the color and place it on the map.
    Once that the project is ready, to place the routers in the place of the placeholders, right click on the placeholder, press on Place item here and select the node to place. Add placeholder video

In Layers menu it is possible to select the items visible on the map, such as the Guides, Zones, Mesh Nodes, Tags, and others.

Layers

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.
Positioning anchors for each tag shows which anchors contribute to the position calculation and the RSSI value between tag and anchors.

On the bottom of the page there are some features that can be useful:

  • Tag filter where the user can enter the tag ID or Alias (if set) to show on the map only that tag;
  • Reset zoom Reset Zoom to restore the view of the map to the original zoom;
  • No tool selected No tool selected;
  • Map move Map move to move the view of the map;
  • Map area selection Map area selection to zoom the map in a selected area;
  • Measure distance Measure distance to measure the distance between two points on the map.

Gateways

This tab contains the list and information of all the Gateways Connected to the service.

There are 2 ways to connect the gateways to the MeshCube:

  1. In Gateway section, press on Add. The system will scan all the gateways that are available in the network. After, press on Connect gateway button near the gateway you want to connect.
    When connecting the gateway, will appear a pop-up asking the password of the gateway. If you are connecting a TinyGateway the password field can be left empty.
  2. Periodically the system scans the network and reports the new gateways found in the local network in a notification. To connect a gateway, open the notification manager Notify, search the desired gateway and press Click to register to connect it to your MeshCube.
    Discovered gateways

The Status column shows the status of the Gateway, that can be Online or Offline. In case the gateway is offline the row corresponding to the offline gateway will have a light-red background.

The gateway row can assume also a light-orange background meaning that the Sink functionality of the gateway (Sink stack) is offline.

Gateways

For all the TinyGateway gateways there is a direct link to the Web Interface of the Gateway Manage column. This allows to open, inside the MeshCube interface, the web interface of the chosen TinyGateway, that allows to configure the gateway and all its functionalities.

Refer to the manuals of TinyGateway Wirepas for more information about the TinyGateway web interface and configuration.

Networks configuration

MeshCube interface can handle multiple Networks at the same time. Make sure to choose the right network when configuring the devices.

The network configuration tab allows to set a custom configuration to the Mesh Nodes.

The configuration can be applied to one Network at a time. For this reason, if multiple networks are handled by the system, make sure to choose the right network when sending the configuration.

Network Selection

For all the networks, at the first start, a default configuration is already present in the MeshCube web interface.

In this section the user can:

  • create new configuration from scratch Create configuration in the upper right corner of the page. Here the user can start setting up a new configuration or can import the AppConfig and the configuration will be generated accordingly;
  • modify a configuration template Modify configuration;
  • clone a configuration and then modify it Clone configuration;
  • apply a configuration to the network Apply configuration;
  • download the AppConfig of a configuration AppConfig;
  • delete a configuration template Delete configuration (the default configuration, that is always present at the first start, can not be deleted).

Network Configuration - main

The configuration is composed by the following fields:

  • Diagnostics interval, that is how often the devices should send diagnostics information;
  • F9 - Default Anchor class configuration;
  • FA - Default Asset Tag configuration;
  • FB - Default Personal Tag configuration;
  • Custom node classes, from FC up to FF.

Note: Node class configurations are optional. The user can define or not the configuration for a given node class.

A problem that could arise when defining the configuration for multiple node classes is the length of the configuration.
From the interface, the configuration is translated into an AppConfig, that is a stream of bytes. This stream 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(es) at a time.

Default Configuration

Router node configuration

This setting allows to configure all the Router Nodes of the Network at the same time. The settings include:

  • sensing interval - update interval of sensor measurements;
  • alerts enable - if mounted, enables LED and/or button functioning;
  • Off by position setting allows to disable the anchors when they are in horizontal position. This setting is used mainly during transportation of the devices to avoid battery discharges;
  • configuration of the Beaconing. The supported beaconing packet types for the Router Nodes are:
    • iBeacon
    • Eddystone-UID.

Router configuration

Non Router node configuration

As for the Non Router Nodes, we can distinguish between Default Asset (FA), Default Personal Tags (FB) and other configurable node classes (up to FF).
The distinction is made to allow the user to configure the two types of the Tags with different parameters, if needed.

The Non Router Node Configuration is divided into 3 subsections, that group configuration parameters:

  • Base configuration allows to configure base tag functionality parameters:
    • Positioning interval for all states;
    • Positioning Timeout for default, motion and alarm states;
    • Autoscan enable to define in which states the tag should remain in autoscan.
      Note: when positioning interval is less than 30 sec, the tag automatically enters Autoscan mode;
    • Button / Alerts enable, if mounted;
    • Accelerometer enabled. If enabled, also Motion threshold, motion duration and advanced accelerometer configuration can be modified;
    • Motion threshold defines the intensity of movement. Acceleration needs to be greater than the threshold to detect movement.
      Motion threshold is defined in mG and 160mG is a sufficient value for both asset and people tracking to not to have false movement detection even if the tag is worn pendent around the neck and there are small oscillations of the tag;
    • Motion duration defines the minimum time period for which the acceleration must be greater than the threshold to detect movement;
  • Advanced Accelerometer Configuration allows to configure advanced accelerometer functionalities, other then motion detection. Each accelerometer functionality has its own configurable parameters. For more information on the accelerometer modes refer to Mobile Tag Configuration Packet format. Other Accelerometer modes are:
    • Position
    • Freefall
    • Shock
    • Mandown
  • Beaconing Configuration allows to configure beaconing on the Mesh tags. The supported beaconing packet types are:
    • Quuppa
    • iBeacon
    • Safety.

Non Router configuration

Nodes

This section contains the list of all the detected mesh Nodes, divided into Sink, Router and Non Router Nodes. For each Node type the table contains information about the nodes.

Nodes

For the Sink nodes, the first column shows whether the Wirepas Stack is running or not. If the stack state if offline the gateway sink functionality is not running, the stack state icon becomes Red and the row of the corresponding Sink will have a light-orange background.
If the gateway (that is configured as Sink) is offline, the background of the row becomes light-red.

For the router and non router nodes, the ID field can assume different colors, based on the state of the device:

  • Green - the device is online and correctly working;
  • Grey - the device has been loaded from the cache of the system. That is, after the reboot of the system, the device has not been detected by the system, even if the device has remained in the memory of the system;
  • Red - the device is not detected or offline.

When the device is red it is possible to remove the not detected devices from the Nodes table by pressing the Bin icon in the row corresponding to the not detected node.
If there are many red nodes, it is possible to remove all the not detected nodes of the same type (routers or non routers) by pressing the Bin icon on the right on the same line of the node type.

The columns of the Router Nodes contain:

  • information about the node: ID, Network ID, Alias, if set;
  • Wirepas data: Radio Installation quality, Operation mode (refer to Operation Modes);
  • Config 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 of the device is the same as the one set in the network;
  • Send command button allows to send one of the possible commands to the device. Some commands are:
    • Reboot the device;
    • Button Enable / Disable;
    • Alert Enable / Disable - the user can manually compose the alert or use an alert template created in Alert template setting;
    • GPIO Configuration to configure the IO Pins;
    • Query current configuration;
    • Query current position.

As for the Non-Router nodes the columns are:

  • information about the node: ID, Network ID, Alias, if set;
  • State data:
    • State/Mode (refer to tag states);
    • State time shows for how long the node has been in that state;
    • Last positioning is the time elapsed from the reception of the latest positioning packet from the node;
    • Last config update is the time elapsed from the reception of the latest configuration packet from the node;
    • Last update is the time elapsed from the last update of the mesh network;
  • Config 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 of the device is the same as the one set in the network;
  • Send command button that allows to send one of the possible commands to the device. Some commands are:
    • Reboot the device;
    • Button Enable / Disable;
    • Alert Enable / Disable - the user can manually compose the alert or use an alert template created in Alert template setting;
    • GPIO Configuration to configure the IO Pins;
    • Query current configuration;
    • Query current position.

Send alert

Note: For Router and Non-router nodes the columns displayed in the table are configurable. The user can select the nodes to display in the Filter Columns menu Node columns on the right.

Node columns

Network tree

When pressing Network tree button in the upper right corner, the tree representation of the current network will appear.
This representation allows to inspect the network structure and to see how it is organized, i.e., how the single nodes connect to the sink, with the related link quality.

Network structure

Firmware upgrade

In the right upper corner there is the Firmware Upgrade menu Firmware Upgrade.

To upgrade the firmware of the devices, first select the network to upgrade the firmware to.

Select network

After that, upload the OTA firmware file sent by BlueUp for devices firmware upgrade.

Upload firmware file

The firmware upgrade will be performed as a background process and the user can follow the process through the notifications from the system.

Firmware upgrade

Positioning

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 they contribute to the positioning functionality of the system.

Mesh Anchors

In this tab are listed all the Router Nodes configured as Mesh Anchors. For each Anchor the available information is listed in the table, having the following fields:

  • Basic information about the anchor, such as ID, Network ID, Alias (if set);
  • Information about the position of the anchor, including the Map, Zone (if defined on the map), Position coordinates;
  • Information about positioning settings of the anchor:

    • Positioning enabled;
    • Calibrated RSSI is the RSSI value at the distance of 1 meter from the anchor;
    • RSSI Offset is the RSSI adjustment with respect to the calibrated value;
    • N is the environmental factor used to evaluate the distance between the anchor and the tag;
    • Battery state of the anchor.

Mesh Anchors

The positioning settings can be modified at any moment, for each anchor separately or for all anchors at the same time, by pressing the Settings icon.

Positioning settings

Mesh Tags

In this section are listed all the detected Non Router Nodes configured as Mesh Tags.

Mesh tags

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

  • Basic information about the tag, such as ID, Network ID, Alias (if set);
  • Information about the position of the tag, including the Map, Zone (if defined on the map), Position coordinates;
  • Information about the current operational state of the tag:
    • Operation mode can be NRLS Tag or Autoscan Tag (for more information refer to Operation Modes);
    • State of the tag, that can be Default, Motion, Alarm or Sleep (for more information refer to Wirepas-enabled positioning application);
    • State Time indicates for how long the tag has been in the current state;
    • Alarm indicates what condition had triggered the alarm state. The possible alarm triggers are: button pressed, Mandown (if configured), Shock (if configured);
  • Battery state of the tag;
  • Position log. When pressed, a new window will open where will be displayed the logs related to the tag. In these logs are shown the steps that are performed to evaluate the position of the tag. This functionality is useful when the user wants to go into detail on how the position is calculated.
    Tag positioning logs

Sensors

Sensors section collects all the nodes that are designed and configured as Sensors. For each sensor are displayed data of the available sensors, that can be:

  • Temperature in Celsius or Fahrenheit, as set in Mesh Sensors settings;
  • CO2 in parts-per-million;
  • Humidity in percent;
  • Pressure in Pascal.

MeshSense

For each sensor it is possible to:

  • Refresh the measurement Refresh;
  • Set or change the alias of the sensor Modify alias;
  • View the charts View charts. This allows to display and monitor the behavior of one measured quantity at a time of the last 24 hours.

Mesh Sense chart

Beacons

Beacons are Nodes with Beaconing enabled when configuring the Nodes, that is configurable for both Anchors and Tags, as described in networks configuration section.

The possible Beaconing types are

  • for Anchors:

    • iBeacon
    • Eddystone-UID
    • for Tags:

    • iBeacon

    • Safety
    • Quuppa Emulation Mode.

The fields that are displayed for each beacon are:

  • Beaconing type;
  • Beaconing frame information;
  • Advertising interval;
  • Advertising TX power.

Mesh Beacon

Automation

Note: Automation function is not included in the standard MeshCube license. If you want to have more information about it, please contact us by opening a ticket or by writing an email at support@blueupbeacons.com

Automation scripts are JavaScript codes that allow the user to define some additional functions to the system. This scripts can not modify the basic functionalities of the software, but only add other functions or tasks that will be executed in an automate way.

Automation

Plugins

Plugins are additional functionalities to the software that are different from the embedded ones. The user can ask about the existing plugins or discuss additional functionalities with the BlueUp team.

Note: the plugins are not included in the MeshCube license.

plugins

API

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

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

APIs

FTR Queries

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

When adding a new query (by pressing New query) 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/gateways
    • /api/maps
    • /api/nodes
    • /api/tags
  • the name of the query without blank spaces;
  • query description;

FTR Queries

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:

  • Edit to edit the Api, name and description of the query;
  • Export to export the query;
  • Delete to delete the query;
  • Start script 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;
  • Reformat code to automatically format the code;
  • Check code to heck the validity of the code;
  • Parameter list to show / hide the list of defined parameters. When showing, it is possible also to define a new parameter.

FTR Query template

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.

Consider, for example, the /api/nodes call that returns the array of all the nodes in the system. The user may want to retrieve only the information regarding the Router nodes. This is possible by defining the filter function.

Example in which are returned only the non router nodes:

filter(obj => {
    return obj.role === 'non_router_node';
});

Transform

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

Taking as example the /api/tags call, it is possible to take only the fields the user is interested in.

Example in which are retrieved only id, alias and battery of the tags:

transform(obj => {
    return {
        id: obj.id,
        alias: obj.alias,
        battery: obj.battery
    }
});

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/nodes):

<meshcube_ip_address>/api/nodes?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 System logs 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 logs

System events

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

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

Event logs