Gateway Troubleshooting
The BlueRange Gateway device is located in-between the mesh network and the service platform. It acts as a servant commanding IoT devices on behalf of the BlueRange server. Gateways run autonomously and require proper configuration for correct operation. This section is provided as an aid in diagnosing issues when the gateway is not operating as expected.
LED Indicator
If you have trouble accessing your BlueRange gateway, first check the LED State Indicator for easy troubleshooting.
Network connection between gateway and server
Check the device status in the server UI. An inactive gateway device indicates that it did not contact the server in time. Please make sure that all gateway network requirements have been fulfilled.
In case you do not know the IP of your gateway….
In case of network issues that are most of the time related to restrictive firewall settings, you have a number of options to find out the IP that was assigned to your gateway:
-
In case Zeroconf is not blocked in your network, enter the url https://meshgw-abcde.local in your browser or use
ping
to access the gateway or retrieve its ip address -
Ask your network administrator for the IP that was assigned by the DHCP server
-
Use the BlueRange Admin app to retrieve diagnostic information from the gateway over Bluetooth
-
Use the gateway terminal to display the IP and other diagnostic information.
If the gateway does not have the correct IP address, e.g. 169.254.x.x
If your gateway does not have an IP address within the valid range for your network, check the following:
-
Make sure that the green and orange LEDs next to the ethernet port are lit / blinking which indicates that the ethernet cable is connected and your ethernet port is properly patched
-
Connect another device to the used ethernet cable and make sure the other device has connectivity and a valid IP
-
If the Gateway has multiple Ethernet ports, check if the second port works. Sometimes network equipment does not behave correctly when negotiating the ethernet speed and a gigabit connection might not work as intended. On some gateways, the secondary port only supports 100 Mbit which can solve the issues and provide a stable connection.
-
Ask your network administrator if the MAC address of your gateway must be registered with the DHCP server to receive an IP address
-
Check the diagnostic log of your gateway and see the output of
ifconfig
for MAC addresses and other information
When the gateway device is shown as inactive….
-
Device availability checking must be enabled in Settings/Device Management of the platform. Also, the inactivity duration is configured here. A setting of less than 5 minutes is not supported and most likely will not work reliably!
-
Check the last connected date displayed in the gateway device details. This timestamp indicates when the gateway was last recently able to contact the server. Was any network infrastructure changed since then? Were any firewall settings altered? Have any SSL certificates expired and/or been renewed in the meantime?
-
Also in device details, the last recent IP address of the gateway is shown. Try accessing the gateway administrative UI web page. For this to work, make sure to prefix the IP by
https://
explicitly as browsers default to insecure HTTP. Also, this will work only if such connection is allowed by your firewall settings and the web UI is enabled (the default) in the gateway configuration.
In case the gateway UI can not be accessed…
When the gateway is connected via ethernet cable, check the LEDs flashing next to the socket. These LEDs indicate network traffic. When no sign of activity is visible, check the physical connection of the gateway regarding network and power.
When network connectivity and power cabling is fine and the gateway can not be accessed…
-
Try temporarily replacing the gateway by a notebook for network diagnosis. Ensure DHCP assigns a proper IP address, DNS name server and NTP time server. The BlueRange server web UI must be accessible using a web browser. Also see if the notebook allows connecting the MQTT broker by following the instructions given at Token Authentication/Using the MQTT Token.
-
Check the administrative interface of your router and/or DHCP server to see if the gateway is a connected client. To find out what client the gateway is, check the UI once with the gateway disconnected physically and compare that list of clients with the one after it is connected.
-
For security reasons, the network settings of the gateway can not be displayed directly. However, the settings can be rewritten to the device by reconfiguring the network settings using the BlueRange Admin App over the Bluetooth connection.
When effective network settings are unknown or the gateway can not be found in DHCP server…
As a last resort the network settings can be reset to DHCP defaults for obtaining all of the IP address, default gateway, name and time servers from the wired connection. Fully relying on DHCP client configuration is the recommended mode of operation. The option for resetting the network settings is offered in the maintenance menu presented when monitor and keyboard as physically connected when the gateway is booted, see Gateway Terminal.
Resetting the network settings erases all network related configuration incl. e.g. WiFi credentials, etc. Please make sure you know the infrastructure the device is connected to. Also make sure to have the BlueRange Admin App available for properly reconfiguring your gateway afterwards. |
When enrollment is refused as the gateway was not withdrawn prior to tearing down an evaluation server…
An already enrolled gateway can be unenrolled by resetting to enrollment information either from the maintenance boot menu or using the BlueRange Admin App.
For security reasons users are required to prove physical access to the gateway for resetting the enrollment. This is done by attaching monitor and keyboards, or by scanning the gateway QR code providing the wireless encryption key. |
Usually the gateway is smart enough to realize when it was withdrawn while it was not powered or went offline for some reason. However, especially when migrating from demo kits to a production environment the BlueRange server used for enrollment might no longer be available.
Once the enrollment is reset, the gateway can be re-enrolled following the instructions given at Enrollment.
Bluetooth connection of the gateway and mesh network
When mesh nodes are shown as inactive…
-
Please check the power supply. Notice, the battery display in the BlueRange server UI provides a qualitative indication only. The information might not be accurate as power and life-times differ depending on manufacturer and the types of batteries being used.
-
Try near-by scanning using the BlueRange Admin App to identify malfunctioning or otherwise broken devices.
-
Check the wireless signal strength among the nodes making up your mesh network. For acceptable connections the RSSI should not be worse than -85 dB.
Nodes transitioning between activity states back and forth may be caused by instable battery power as well as poor connection quality. |
Further assistance
The gateway offers a maintenance boot menu when monitor and keyboard are connected to the device, see Gateway Terminal.
If suspecting a hardware defect…
For an in-detail analysis of the gateway hardware and software environment the device offers collection of a system diagnostic report. The feature is offered from the maintenance boot menu for direct inspection of the log. Also it is uploaded to the enrollment server if the gateway is properly connected.
All in all, you have three possibilities depending on the severity of the issues:
-
Get the log from our BlueRange Server
-
Connect a Monitor and use the Terminal to read the log
Current versions of the BlueRange Gateway will create a diagnostic log for each reboot. To download a diagnostic log once it was created by your BlueRange Gateway and uploaded to our server, navigate to > Devices > Diagnostic Logs
, search for your device, select one or more entries and use the download button.
The diagnostic log can contain sensitive information so make sure to only share it with people you trust. You must have the organization administrator role to be able to download diagnostic logs. |
If the Gateway can not connect to its BlueRange server because it is not enrolled, if the network connectivity is not given or a hardware defect blocks it from connecting properly, you can use the BlueRange Admin App to download the diagnostic log.
Within the app, select the Gateway and use the Debug Information
button.
In the most severe cases, you might not be able to do the above steps, so you have to connect a monitor to the Gateway or connect to its serial terminal using a USB cable (depending on the model) to see the terminal and select the option for viewing the diagnostic log. See Gateway Terminal for more info.
Remote assistance
BlueRange staff can be given the ability to access gateway devices remotely. For this to work, we requires access to the SSH service offered by the gateway on TCP port 22. Such access needs to be granted temporarily. Please consider offering some form of VPN or forwarding mechanism.
Remote access is implemented using public key cryptography. We rely on agent forwarding and can under no circumstances provide private access keys! Regular updates of the gateway OS ensure access keys are rotated. We recommend updating at least twice a year! |
Alternatively reversed SSH access may be possible, provided the gateway is controllable from the enrollment server, that function was not disabled for security reasons and the gateway has access to the Internet and/or a suitable jump server.