TinyGateway LTE Wirepas User Guide

TinyGateway LTE Wirepas (in the following referred to also as “TinyGateway LTE” or simply “gateway”) is the new Wirepas Mesh 2.4GHz gateway by BlueUp based on ESP32 module (for Ethernet and WiFi connectivity), BG96 module (for LTE connectivity) and nRF52832 (for Wirepas sink).

TinyGateway has a web user interface that allows to:

• configure Ethernet connection, Wirepas Sink settings, MQTT connection
• monitor Wirepas mesh messages and active services
• update gateway firmware and user interface

Hardware description

TinyGateway LTE Wirepas is a low-power and low-cost Wirepas Mesh gateway, with WiFi, Ethernet and LTE connectivity, compatible with Wirepas Mesh 2.4GHz network. TinyGateway LTE has one button that has the following features:

• single press to reboot the gateway;
• 5 sec long press to perform the reset of all the configured parameters, except for Sink Configuration;
• 10 sec long press to perform the factory reset of the gateway.

TinyGateway LTE has 3 LEDs, placed as depicted in the fiugure whose functionality is described in table below.

Name	Color	Description
Power-on LED	Green	Gateway status: ON: power-on OFF: power-off
Wirepas LED	Blue	Wirepas Mesh 2.4 GHz stack status: ON: Wirepas stack active OFF: Wirepas stack not active
Status LED	Red	Status: OFF → normal gateway operation condition Red blinking → some malfunctioning of the gateway has been detected Red ON → when pressing the button

How to Install

The gateway installation procedure changes based on the power supply type. For each power supply type, follow the described steps to correctly install the gateway.

TinyGateway LTE Wirepas – USB-C power supply

1. Install TinyGateway in the desired location using the screws for the holes in the lateral flanges (2x M3.5 screws, not included).

2. Prepare the gateway for the network connection:

   • In case of LTE connectivity:
     • Insert the SIM card in the specific slot.
     • Connect the LTE antenna to the gateway.
   • In case of Ethernet connectivity, connect the gateway to the LAN with a standard Ethernet cable.

3. Power on the gateway using:

   • a standard USB 5V power supply with USB to USB-C cable (not included)
   • a PoE network switch (please note that LTE cannot be used when the gateway is powered from PoE)

4. TinyGateway now is ready to be used (Power-on green LED switched on).

TinyGateway LTE Wirepas – PoE power supply

PoE power supply can be used for Ethernet and WiFi connectivity, but not for LTE.

Make sure that your LAN is already provided with a PoE Switch or connect a PoE switch to your LAN network.

1. Install TinyGateway in the desired location using the screws for the holes in the lateral flanges (2x M3.5 screws, not included).
2. Connect the gateway to the PoE-enabled LAN with a standard Ethernet cable.
3. TinyGateway is now ready to be used (Power-on green LED switched on).

First Start

In the following are described the steps to follow at the first start of the gateway to correctly configure it.

Step 1: Power-on

Install and power-on the gateway as described in How to install above. At the first start the LEDs configuration will be:

Name	Color	Description
Power-on LED	Green	Gateway status: ON: power-on
Wirepas LED	Blue	Wirepas Mesh 2.4 GHz stack status: OFF: Wirepas stack not active
Status LED	White	OFF → normal gateway operating condition

Step 2: Connect to the gateway

By default, the gateway WiFi interface is configured in Access-Point mode. To be able to connect to and to configure the TinyGateway the user has to connect to it through WiFi connection, using the following credentials:

Step 3: Web interface access

Once connected to the Access-Point the user can access the web user interface using a browser at the following address:

From this interface the user can configure all the gateway parameters. The Device interface summarizes the gateway information.

Now proceed with the LTE or Ethernet or WiFi network configuration to let the gateway connect to your mobile or LAN or WiFi network.

Gateway Configuration

After you have successfully connected the TinyGateway to your local LAN network, the configuration of the gateway can be performed through the gateway web interface.
To access the gateway web interface, open a browser (Chrome or Firefox) and type the IP address of your gateway.
The configuration section of the web interface lets you configure all the settings of the TinyGateway:

• WiFi / Ethernet / LTE network connections
• Wirepas Sink parameters
• MQTT broker connection
• Remote Management
• NTP parameters
• Password

Network configuration

Multiple network interfaces can be configured, depending on the gateway model.

• For TinyGateway WiFi, only the WiFi network interface is available.
• For TinyGateway PoE, the Ethernet and the WiFi network interfaces are available.
• For TinyGateway LTE, the LTE, Ethernet and WiFi network interfaces are available.

The above network connections are exclusive: when one connection is configured, the other are disabled automatically. The only exception is the WiFi Access Point that could be enabled in parallel to the Ethernet or LTE connection.

LTE configuration

To configure Ethernet connection parameters, go to Configuration → LTE.

To properly configure the LTE configuration a SIM card should be inserted in the gateway SIM card slot and the LTE antenna should be connected to the external SMA connector.

When LTE connection is chosen, make sure that TinyGateway is powered on through the USB power supply and not through the PoE Ethernet.

To configure the LTE connection the following parameters could be set up:

• APN: the APN of the mobile operator (mandatory)

• PIN: the SIM card PIN (optional)

• PPP Credentials: the username and password for the PPP authentication (only if provided by your mobile operator)

• DNS: the DNS to be used in place of those provided from the mobile operator (optional, leave empty to use those provided by the mobile operator)

After pressing Save button, a confirmation pop-up will appear.

After confirmation, in order to apply the new LTE configuration, the gateway must be rebooted by pressing button on top right.

When using LTE connection, WiFi Access-Point mode can also be used in parallel to the LTE connection.

Ethernet configuration

To configure Ethernet connection parameters, go to Configuration → Ethernet.

The user can choose whether to use DHCP or not for IP address assignment.
DHCP is enabled by default.

If DHCP is disabled, it is necessary to enter IP address, Netmask, Gateway and DNS manually.

After pressing Save button, a confirmation pop-up will appear.

After confirmation, in order to apply the new Ethernet configuration, the gateway must be rebooted by pressing button on top right.

Note: if the DHCP is disabled and the IP address is assigned manually, after reboot, the web interface will be available at the new configured address.

Since firmware version v1.4.0.221, on the TinyGateway PoE is also possible to configure the WiFi network interface. The WiFi network interface could be enabled in parallel to the Ethernet interface if set up in Access-Point mode, otherwise, if set up in Station mode, the WiFi interface and the Ethernet interface are exclusive.

WiFi configuration

To configure the gateway WiFi network interface go to Configuration → WiFi.

WiFi Access-Point configuration

To let the gateway act as a WiFi Access Point, select Access point from the Mode select box.

When Mode is set to Access point, the following parameters need to be set up:

• SSID: the SSID of the WiFi network created by the gateway
• AP Hidden: if selected, the WiFi network will be hidden and only those who already know the SSID and the password will be able to connect to it
• AP Timeout: if configured to a non-zero value, the WiFi network will be shutdown after the timer is elapsed
• Password: the password of the WiFi network

After pressing the Save button, a confirmation pop-up will appear.

After confirmation, in order to apply the new WiFi configuration, the gateway must be rebooted by pressing button on top right.

WiFi Station configuration

To connect the gateway to an existing WiFi network, select Station from the Mode select box.

When Mode is set to Station, a WiFi network scan can be started by pressing the icon located on the right of the SSID text box. The gateway will now start scanning the available WiFi networks.

When the scan is completed, a list of the available WiFi networks will appear and the user will have to choose the network to connect the gateway to.

After choosing the network, enter the password of the selected network.
The user can choose whether to use DHCP or not for IP address assignment.
If DHCP is disabled, it is necessary to enter IP address, Netmask, Gateway and DNS manually.
In case of public WiFi networks, that do not require a password to connect to, the Use Password flag has to be disabled.
In this way the password will not be required to connect to WiFi.

After pressing the Save button, a confirmation pop-up will appear.

After confirmation, in order to apply the new WiFi configuration, the gateway must be rebooted by pressing button on top right.

NOTE:
In case the entered WiFi password is wrong, the gateway won't be able to connect to the WiFi network and the web user interface will be unreachable.
In this situation, a factory reset is the only solution to be able to access the gateway interface again.
To perform the factory reset of the gateway, press and hold the button for 5 seconds, the led will emit a red blink to indicate that the gateway will perform a factory reset.
After the factory reset, the gateway will restore its factory default configuration and will be reachable again as an Access Point.

Sink Configuration

This section explains how to configure the Wirepas Sink settings of the TinyGateway.
To configure the Wirepas Sink settings of the TinyGateway, go to Configuration → Sink. The following Wirepas settings must be configured for the Sink to work correctly:

• Stack mode: this parameter defines how the Wirepas Sink interface is managed by the gateway.
  The following Wirepas Sink interface management modes are available:

  • Enabled on WiFi/Eth/LTE network status: the Wirepas Sink interface is enabled when there is an active network connection, i.e., the WiFi interface is connected to a WiFi network or the Ethernet interface is connected to a LAN network.
    In this configuration, the Wirepas Sink interface will be disabled on the gateway only when the network interface in use gets disconnected, i.e., the WiFi signal is lost or the ethernet cable is unplugged.
  • Enabled on MQTT status: the Wirepas Sink interface is enabled when there is an established MQTT connection with the broker.
    In this configuration, the Wirepas Sink interface will be disabled on the gateway as soon as the gateway loses connection with the MQTT broker.
  • Permanently enabled: the Wirepas Sink interface is always enabled
  • Permanently disabled: the Wirepas Sink interface is always disabled

  This parameter could be useful to overcome situations where the gateway loses the connection with the MQTT broker backend for a long time.
  If the Wirepas Sink interface is kept always active, the Wirepas Sink will continue to receive data from the Wirepas nodes even if the MQTT connection with the backend is not established (i.e., a disconnection has occurred). For short disconnection times, the TinyGateway is able to buffer received Wirepas nodes messages (up to 250 messages could be buffered), but when the buffer is filled, packages will be discarded and messages will be lost. In such cases, using one of the first two stack management mode is recommended, as the gateway will turn off the Wirepas Sink interface if the backend connection gets dropped and the Wirepas network will re-organize to send data to another Sink.

• Node address: the Wirepas Sink node address

• Node role: TinyGateway could act as both a Wirepas Sink or a Wirepas Anchor.
  

  • if the gateway should act as a Wirepas Sink choose CSMA-CA Sink.
    
  • if the gateway should act as a Wirepas Sink choose CSMA-CA Router.

• Network address: the Wirepas Sink network address

• Network channel: the Wirepas Sink network channel

• Sink cost: leave to the default value

• Cipher Key: the Wirepas Sink network chiper key

• Authentication Key: the Wirepas Sink network authentication key

MQTT configuration

In Configuration → MQTT the MQTT connection can be enabled and configured.

When setting up a new broker connection, you need to configure the following parameters:

• Uri: the URI where the broker is located.
  By clicking on the protocol button in the URI textbox you can switch between the supported MQTT protocols:

  • mqtt://
  • mqtts://
  • ws://
  • wss://

• Port: the port at which the broker is listening.
  

• Use credentials: whether the broker requires a username and a password for the client.

If a secure protocol is selected (mqtts:// or wss://), the broker host Root CA certificate is mandatory.

If the gateway can reach the internet, the Root CA certificate of the broker could be automatically recovered from the gateway using the CA certificate button, otherwise you need to manually upload the Root CA certificate in PEM format.
To retrieve your broker Root CA Certificate you can also use the web utility that BlueUp has made available to its clients (see Root CA Certificates section).

If the gateway is able to resolve the Root CA certificate, it will be shown in the textbox.

Client certificate is optional (depending on your broker settings).

After pressing the Save button, a confirmation pop-up will appear.

After confirmation, in order to apply the new MQTT configuration, the gateway must be rebooted by pressing button on top right.

After the gateway has been rebooted, in Device panel Status section, all the services should appear configured and running.

Once Sink and MQTT configurations are completed, the gateway starts working as Wirepas Mesh Gateway on the configured Wirepas network.

Remote Management configuration

In Configuration → Remote the Remote Management connection can be enabled and configured.
The TinyGateway can be set up for remote management using the same MQTT broker as the one configured in the MQTT section, or using a secondary alternative broker.
When setting up an alternative broker connection, you need to configure the MQTT connection parameters for the alternative broker MQTT connection (see MQTT section).
Remote Management allows to monitor and re-configure the gateway remotely using an MQTT connection (primary or alternative) as a bridge.
When Remote Management is enabled, the gateway MQTT APIs will be enabled (see API documentation), so the gateway will respond to remote API invokation requests and will also send events to the remote host. Remote Management will use the following MQTT topics to work:

• api-request/<gateway-id>: topic where the remote API requests must be published by the remote host (the gateway is subscribed to this topic)
• api-response/<gateway-id>: topic where the remote API responses will be published by the gateway (the remote host hould be subscribed to this topic to receive gateway responses)
• api-event/<gateway-id>: topic where the gateway will publish its events (the remote host hould be subscribed to this topic to receive gateway events)

Once the Remote Management configuration is enabled and configured, the gateway starts sending events to the remote management broker.

NOTE: The gateway will use the same ClientId when connecting the the MQTT broker and to the Remote Management broker, so, do not enable the Remote Management alternative broker with the same Uri and Port as the main MQTT broker otherwise the gateway will not be able to connect.

Change Password

The gateway web interface password can be easily changed by clicking to the top-right toolbar menu button and selecting Change password. A popup dialog will appear where you can change the current password with a new password.

Nodes messages

The nodes that are on the same network as the Sink will start sending data and the received raw data will appear in the Nodes section.

Firmware Updates

The Firmware update section allows to search for new updates of the gateway firmware and/or of the web user interface. To check and download firmware updates, the gateway needs to be connected to the internet. If updates are available, a changelog will be shown before proceeding with the update. Whatever the outcome of the firmware update, at the end of the procedure, the gateway restarts. If the procedure is completed correctly, upon restart the gateway will use the new updates installed, otherwise it will continue to use the previous version.

API

TinyGateway is provided with a wide number of API calls that can be used through HTTP or MQTT protocols. The full list and description of the latest TinyGateway Wirepas API calls is available at the following page.

Root CA Certificates

Protocols that use secure connection (MQTTS, WSS, HTTPS) require a CA Certificate to establish the connection with TinyGateway. CA Certificates are usually provided by your provider, but can also be resolved using public available tools. In case you are not able to find them, BlueUp has made available a web page that allows to retrieve easily your CA Certificate.
Follow the steps below to retrieve your CA Certificate:

1. Open the web page BlueUp Find RootCA.
2. Enter the hostname and the port of the service you want to discover the CA Certificate (ex. my.hostname.com:8883).
3. Press on Find RootCA.
4. In a field below a text with CA Certificate will appear.
5. Copy the text and paste it into a text file and save it with the name “ca_cert.pem”.
6. Upload the certificate where required.