BlueRange Gateway

Overview

Our BlueRange Gateway (previously called MeshGateway) is a mighty device. Compared to most IoT gateways it offers a lot of CPU power and memory. Some would call it an edge computing device. We prefer to call it a gateway. With its integrated Bluetooth Low Energy chipset, it is able to participate in a mesh network as a data sink and collect all data from this network. It can preprocess this data and send it to our BlueRange Server. Also, we have extended it to be able to interoperate with BACnet and KNX networks.

BlueRange Gateway V4

gateway v4

Read the documentation on LED blink codes for easy troubleshooting.

Installation

Requirements

Before installing our BlueRange Gateway, you have to meet a number of requirements. These are mostly settings that need to be configured in your firewall. Without them, the gateway won’t operate correctly:

  • An NTP timeserver needs to be accessible

  • Specific network ports need to be open

Time Server

For proper operation, you need to give the gateway access to a network time server. This can be a publicly available time server or a local time server on your network. If your network has access to the public internet, the gateway is preconfigured to look for a public time server. In this case, no specific configuration is needed. If you are using an internal only network without access to public time servers, you can specify the IP address of your in-network time server during the enrollment process of the gateway.

Ports

For basic connectivity of the gateway with e.g. our BlueRange platform at http://iot.bluerange.io, ports 443 and 8883 need to be open for SSL and MQTT connections. Other ports may need to be open, depending on your requirements and setup. Please refer to the BlueRange Gateway Network Requirements for details.

Hardware Installation

Depending on your BlueRange Gateway model, you need to power the gateway using the supplied power adaptor or a power over ethernet (PoE) connection to supply power and network connectivity. We recommend connecting the BlueRange Gateway with a LAN connection. We also support connections via WLAN, but the experience is usually best when connected by an ethernet cable.

Place the gateway in close proximity to one of your mesh nodes and make sure that it is not obstructed by any metal or other objects that interfere with a Bluetooth connection. It is not recommended to install it in a room with walls made of reinforced concrete or in proximity of any metal sheets or inside a metal container. Also, take all common precautions that apply to sensitive electronic devices, such as keeping it away from water, excessive heat, etc.

The type of connectivity (LAN or WLAN) can be selected during enrollment in the BlueRange Admin App. If you are using the WebUI of the gateway to do the enrollment, you have to connect it via LAN first to be able to access it.

Enrollment

Before you can use our gateway, it has to be enrolled. We provide two methods to do this:

During enrollment, the gateway will reboot. This may take up to three minutes.

Gateway OS

We have developed a custom Linux operating system for our gateway that is based on the Yocto project. The operating system may be updated from time to time through our platform. This is necessary to provide you with the latest features and security updates.

Gateway Software

Running on top of the operating system is our Gateway Software. Some of its responsibilities are:

  • Monitoring the Mesh Network with its Mesh Nodes and Tags

  • Updating Mesh Network and Tags

  • Providing the computational power for our Asset Tracking

  • Connecting to KNX or BACnet

  • Upstreaming sensor data via MQTT

Gateway WebUI

We have equipped our gateway with a frontend that is reachable with every standard web browser. All of our gateways are running an Avahi/Zeroconf daemon that makes the gateway available in your local network under the address:

This address is also printed on the side of the gateway.

Gateway WebUI

For more information about the Gateway WebUI see the detail page.

Gateway Console

Our BlueRange Gateway also offers an admin console with more metrics and debug information that might come handy when trying to troubleshoot issues. This can be accessed by using the Gateway WebUI.

Gateway Console

To reach the page you need to select the device. It is important that you do not click on the text, but in the white area next to it.

For security and certificate issues, cf. Gateway Certificate.

Gateway Logs

If you need to access the log output of your gateway, go to > Logging > Log. It is also possible to configure the log levels under > Logging > Logger where you will have the possibility to increase the log level for the com.mwaysolutions.iot logger to a higher level such as e.g. DEBUG. This setting only has effect until the gateway is rebooted and it switches back to its default value after a restart of the gateway.

The BlueRange Gateway does not save its logs to disk, which is why you can only see the log that the gateway has generated since reboot through its web interface.

You can configure it to automatically send its logs to a log server that is reachable either in the local network or through the internet. In order to automatically collect all logs from a number of gateways, see Collecting BlueRange Gateway Logs.

REST Communication

Our BlueRange Gateway uses REST communication over https to communicate with our BlueRange Server. It uses the publicly available REST API documented here.

This API is used to query information about enrolled devices, configurations, settings, etc. It is also used to upload various other data that needs to be made available to the BlueRange server.

MQTT Communication

To receive and publish sensor data, we are using MQTT. For more information go the the documentation of the MQTT API in the BlueRange Server.

MQTT is used to publish positions of all tracking tags, publish any kind of sensor data and to receive read or write requests on the sensor and actuator interface. For more information, see the chapter on Sensor Data.

Updates

Our BlueRange Gateway is fully updatable. The Gateway OS can be updated and we allow updates of the Gateway Software. The Gateway is also able to update all devices in its network with new versions of our BlueRange firmware. For more information on updates, check the chapter on Updates.

Multiple Gateways Per Network

A gateway can only be enrolled in one network at any single time. Also, each network only supports one enrolled gateway. Should a gateway fail due to a hardware issue, you’ll need to replace the hardware as described in Gateway Replacement.

Troubleshooting

Basic instructions are provided below. For further details please see the dedicated Gateway Troubleshooting section.

Gateway Terminal

Due to network issues, it may not be possible to reach the BlueRange Gateway through the local network. In these cases, depending on the BlueRange Gateway Hardware version, you can do one of the following:

BlueRange Gateway V1 up to V3

Attach a USB Keyboard and an HDMI monitor to the gateway for troubleshooting. For the monitor, use either a regular HDMI cable or a micro-HDMI cable, depending on the hardware version of your gateway. Out of the two HDMI connectors on the gateway, use the connector adjacent to the power supply. Unplug and then re-plug the power supply to perform a reboot. After about 1 Minute, you’ll see the gateway menu on the screen.

BlueRange Gateway V4

Connect a Micro USB cable to the connector on the front of the gateway that is labelled "Console", connect the other end to your computer. Next, use a terminal application of your choice (e.g. Putty on Windows or screen on OSX).

You need to connect to the gateway with the following settings:

  • Baudrate: 115200

  • Data bits: 8

  • Stop bits: 1

  • Parity: none

  • Flow control: none

On OSX use the Terminal and type screen /dev/cu.usbserial- 115200,cs8,-parenb,-cstopb,-hupcl. Next, navigate your cursor to the end of usbserial- and press tab to auto-complete the device name. Now, execute the command.

After you have connected to the device, press the return key and you should see the gateway shell.

You can see important information such as IP Address, MAC Address, Serial Number, OS Version, etc,…​.

You can chose from the available opens to perform a factory reset, reset the network configuration, reboot the gateway and view more diagnostic information.

Gateway Terminal

For Gateway versions V1 to V3, once you are done, power down the gateway, remove keyboard and HDMI cable, then power up the gateway.

Gateway Shown As Unavailable

In some instances, the gateway shows as "yellow", NON-COMPLIANT or disconnected on the BlueRange platform.

We have an automatic watchdog to restart the gateway in case it experiences any unexpected issues. You can also send a reboot action through our BlueRange Portal.

If this does not help, you can check the Gateway Terminal to make sure that the network connection, IP address assignment, etc. are working correctly.

If you have access to the gateway, try a power cycle by unplugging and then re-plug the power supply. No data will be lost and the gateway re-establishes its connections automatically after booting up.

Gateway Replacement

Should a gateway malfunction due to a hardware issue that can’t be resolved and you need to replace it with a new hardware, follow these steps:

  • In the BlueRange portal, open the network view where the gateway is located.

  • Click on "Manage Devices"

  • Select the gateway from the list and click "Delete Gateways"

  • Wait about 2 minutes for the gateway to be properly deleted from the network

  • Take a new gateway and enroll it by either using the BlueRange Admin App or by using the BlueRange Portal

  • Replace the old gateway hardware with the new gateway

  • Open the network view on the BlueRange portal

  • Click on "Manage Devices"

  • You’ll find the new gateway under "Devices in Stock" and can position it on the map

  • Open the gateway information view and select the tab "Configurations"

  • Apply the configuration of the old gateway to the new gateway

The connectivity of the mesh nodes in the network will be automatically restored.