TinyGateway WiFi Wirepas User Guide

TinyGateway WiFi Wirepas (in the following referred to also as “TinyGateway WiFi” or simply “gateway”) is the new Wirepas Mesh 2.4GHz gateway by BlueUp based on ESP32 module (for WiFi connectivity) and nRF52832 (for Wirepas sink). The TinyGateway WiFi comes in two options: Standard (indoor) and Outdoor.

TinyGateway WiFi Wirepas	TinyGateway WiFi Wirepas Outdoor

TinyGateway has a web user interface that allows to:

• configure the WiFi network, sink parameters, MQTT connection;
• monitor gateway data and active services;
• update firmware.

Unless explicitly specified, all the following information in this document refers to both gateway models.

Hardware description

TinyGateway WiFi Wirepas is a low-power and low-cost Wirepas Mesh gateway, with WiFi connectivity, compatible with Wirepas Mesh 2.4GHz network (sink node). TinyGateway WiFi has one button on the side that has the following features:

• single press to reboot the gateway (WiFi LED Red when pressing)
• 5 sec long press to perform the reset of all the configurations, except for Sink Configuration (WiFi LED Red when pressing and then blinks Red after 5 sec)
• 10 sec long press to perform the factory reset of the gateway (WiFi LED Red when pressing, blinks Red after 5 sec and then blinks Red again after 5 sec).

TinyGateway WiFi has 3 LEDs, placed as depicted in the figure 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
WiFi LED	RGB	WiFi network status: White ON → gateway is in Access Point (AP) mode Green blinking → gateway is connecting to the WiFi network Green ON → gateway is connected to the WiFi network Red blinking → some malfunctioning of the gateway has been detected Red ON → when pressing the button

TinyGateway can be powered on with one of the two following alternative power-supply options:

• 5VDC USB (through lateral USB-C connector);

• 4.5-30VDC (through internal 2-port connector)

How to Install

The gateway installation procedure changes based on the gateway type (Indoor or Outdoor) and on the power supply type. For each power supply type, follow the described steps to correctly install the gateway.

TinyGateway WiFi Wirepas Indoor

TinyGateway WiFi Wirepas Indoor – external USB-C connector

1. Attach the double sided tape on the back panel.
2. Stick the gateway to the wall or to any other surface where you want to install the gateway. To ensure optimal adhesion:
   • apply to a smooth, clean and dry surface;
   • once applied, hold for at least 3 seconds.
3. Attach the USB-C for the power supply.

TinyGateway WiFi Wirepas Indoor – internal 2-port connector

This option is recommended in case of rear power supply, with power cables coming out of an opening in the wall. DC power supply is required with voltage range 4.5Vdc to 30Vdc.

1. Ensure that the power cables protrude by at least 5cm from the hole on the wall, for maximum ease of fixing.
2. Open the gateway enclosure using a tool (e.g. flat-head screwdriver)
3. Create an opening in the back panel by pushing the circle where PUSH is written.
4. Using the screws, screw the back panel to the wall where the power supply wires are.
   We recommend using screws with a diameter of 3 mm and a countersunk head.
5. Connect the wires to the 2-port connector provided with the gateway.
6. Attach the connector to the board as in figure below.
7. Close the gateway that is now ready to use.

TinyGateway WiFi Wirepas Outdoor

TinyGateway WiFi Wirepas Outdoor can be powered on only using the internal 2-port connector. The steps to follow are similar to the one described for TinyGateway WiFi indoor with internal 2-port connector.

1. Ensure that the power cables coming out of an opening on the wall protrude by at least 5 cm from the hole in the wall, for maximum ease of fixing.
2. Open the gateway enclosure.
3. Using the screws, screw the back panel to the wall where the power supply wires are.
4. Let the wires pass through the cable gland on the enclosure.
5. Connect the wires to the 2-port connector provided with the gateway.
6. Attach the connector to the board.
7. Close the gateway that now is ready to use.

First Start

By default, TinyGateway is pre-configured in Access Point mode and must be configured to be able to use it.
In the following section 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 section.
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
WiFi LED	White	White blinking → gateway is booting White ON → gateway is in Access Point (AP) mode

This is a transitory configuration that has to be used to connect to the gateway web interface and to configure the gateway.

Step 2: Connect to the gateway

Since the gateway is in Access Point mode, the user can directly 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 and its runtime working status.

Now proceed with the WiFi network configuration to let the gateway connect to an existing 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.

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.

Once the reboot is completed the gateway will try to connect to the user's WiFi network and the LEDs blinking will be as follows:

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
WiFi LED	White	White blinking → gateway is booting Green blinking → gateway is connecting to the WiFi network Green ON → gateway is connected to the WiFi network

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 chipher 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.
• Advanced settings: it is strongly suggested to leave the adavanced settings at the default values.
  • Data encoding: encoding protocol for the data trasmitted through MQTT;
  • Network timeout: time (seconds) for how long to wait for a network responce before timing-out. Higher values can be used for networks with higher latencies;
  • Message retransmit timeout: time (seconds) after which the message will be retransmitted;
  • Reconnect timeout: time (seconds) after which the MQTT client will try to reconnect to the broker after the connection is lost.

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 should be subscribed to this topic to receive gateway responses)
• api-event/<gateway-id>: topic where the gateway will publish its events (the remote host should 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 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.

NTP configuration

In Configuration → NTP it is possible to setup the NTP Server.

The NTP server is used to synchronize the time of the TinyGateway to the local time. If not set, the internal TinyGateway time starts from the Epoch Time, that is January 1st, 1970.

System menu

In the upper-right corner, by pressing a system menu will appear.

The possible options are:

• Change password - a popup dialog will appear where you can change the current password with a new password;
  
• Export configuration - a .json file will be downloaded containing all the settings of the TinyGateway;
• Import / Restore configuration - it is possible to upload a configuration contained in a .json file;
• Downtime reboot - time (minutes) after which the gateway will reboot when it loses connection to the network;
• Reboot - to reboot the gateway;
• Logout - to logout the web interface.

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.