TinyGateway WiFi BLE User Guide

TinyGateway WiFi Bluetooth LE (in the following referred to also as “TinyGateway WiFi” or simply “gateway”) is the new Bluetooth Low Energy gateway by BlueUp based on ESP32 module (for WiFi connectivity) and nRF52832 (for Bluetooth LE scan and connection). The TinyGateway WiFi comes in two options: Standard (indoor) and Outdoor.

TinyGateway WiFi BLE	TinyGateway WiFi BLE Outdoor

TinyGateway has a web user interface that allows to:

• configure the WiFi network, BLE and transport service;
• 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 BLE is a low-power and low-cost Bluetooth LE gateway, with WiFi connectivity. TinyGateway WiFi has one button on the side that has the following features:

• single press to reboot the gateway
• long press to perform the factory reset of the gateway.

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

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 BLE Indoor

TinyGateway WiFi BLE 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 BLE Indoor – internal 2-port connector

This option is recommended in the case of rear power supply, with the 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 BLE Outdoor

TinyGateway WiFi BLE 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 WiFi 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 above. At the first start the LEDs configuration will be:

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 informations and its runtime working status.

Step 4: WiFi Configuration

To configure the WiFi connection, go to Configuration → WiFi.

1. By pressing the WiFi icon, the gateway will start scanning all the available WiFi networks.
   
   
   
2. When the scanning is completed, a list of available WiFi networks will appear and the user will have to choose the network to connect the gateway to.
   
   
   
3. After choosing the network, enter the WiFi 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.
   
   
   
4. After pressing the Save button, the gateway has to be rebooted to update the configuration by pressing button on top right.
   
   
   Once the reboot is completed the gateway will be onnected to the user’s WiFi network and the LEDs configuration will be as shown in table:

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

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 vaddress of your gateway.
The configuration section of the web interface lets you configure all the settings of the TinyGateway:

• WiFi/Ethernet settings
• MQTT settings
• BLE settings
• Data transport/encoding settings
• NTP settings
• Remote Management settings

MQTT configuration

In Configuration → MQTT you can configure at most two MQTT broker connections to use for data and remote management. Having two different brokers is meant for those situations where you need the data to be sent to a broker, while the remote monitoring and management system should reside on a different broker.
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://

  If a secure protocol is selected (as 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 button, otherwise you need to manually update the Root CA certificate in PEM format.
  Client certificate is optional (depending on your broker settings).

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

• Keep alive: the MQTT protocol keep alive period (in seconds).
  If unsure, leave the default value.

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

BLE configuration

This section is used to configure the BLE scanning / advertising parameters of the TinyGateway. The TinyGateway can perform both BLE scanning and advertising at the same time. The BLE configuration section is therefore separated into Scanner Settings and Advertiser Settings.

BLE Scanner

The BLE Scanner section allows the user to configure the BLE scan parameters and the scanning filters for the BLE devices.

• If Passive switch is enabled Scan Response packet is not requested to BLE devices.
  The default OFF value is recommended as beacons do not require scan request/response packets exchange.

• Scan filter allows the specification of one or more filtering rules to discard unnecessary packets and receive only the useful ones.
  The user can define more than one filtering rule, but the filters will follow an OR rule (the packet will be received if it satisfies one rule).
  A filter consists of a string of hexadecimal characters that could include the x character for the don't care bytes (or nibs).
  Most used filter formats are:

  • iBeacon
    • All iBeacons: 0201061aff4c000215
    • Only BlueUp iBeacons: 0201061aff4c000215acfd065ec3c011e39bbe1a514932ac01
  • Safety
    • BlueUp Safety beacons: 0201061aff4c000215a565cc841e0e4b5ab2d317c98ff541xx
  • Eddystone
    • All Eddystone: 0201060303aafexx16aafe
    • Only Eddystone UID: 0201060303aafexx16aafe00
    • Only Eddystone URL: 0201060303aafexx16aafe10
    • Only Eddystone TLM: 0201060303aafexx16aafe20

• RSSI filter allows to define a filter based on the RSSI value of the received advertisement packets.

  • No filter → receive packets from BLE devices having any RSSI value
  • RSSI ≤ value → receive packets from BLE devices having an RSSI value lower then a defined value
  • RSSI ≥ value → receive packets from BLE devices having an RSSI value higher that a defined value

• Use cron allows to schedule scanning using a cron-like expression, useful for applications that don’t need a 24h continuous scanning.

  • Cron expression is the expression of the scanning start time
  • Cron scan duration is the duration of the scan, starting from the scanning start time

• Advanced settings allow to set some BLE settings:

  • Filter duplicates is used to detect and filter out data packets coming from the same device.
    Note: only the first received data packet is sent, next packets are ignored.
    Leave this switch to off if in doubt.
  • Limited is used to scan only BLE devices that have Limited Discoverable mode enabled.
    Leave this switch to off if in doubt.
  • Scan period / interval / window for information about these parameters please refer to the official Bluetooth Core Specification document.

BLE Advertiser

The BLE advertiser configuration allows the user to configure the advertising settings of the TinyGateway.

• Type defines the TinyGateway MAC address type.
  The possible options are:

  • Internal → suggested choice that uses the internal BLE chip MAC address.
  • Random static → a Bluetooth random static MAC address has to be specified (see Bluetooth Core Specification document for more information about random static addresses).
  • Public → a Bluetooth public MAC address has to be specified (see Bluetooth Core Specification document for more information about public addresses).

• Bluetooth 4 compatible specify if the advertisement should be a Legacy BLE4 advertising or a BLE5 advertising.

• Advertised data is the data payload (in hex) that the Gateway will advertise.
  The advertisment data payload should follow the Bluetooth AD-LEN/AD-TYPE format as specified in Bluetooth Core Specification document.

• Use cron allows to schedule advertising, using a cron-like expression, useful for applications that don’t need a 24h continuous advertising:

  • Cron expression is the expression of the advertising start time
  • Cron scan duration is the duration of the advertising, starting from the advertising start time

Transport

Transport configuration allows to configure the settings regarding the data transmission protocols and encoding from the TinyGateway to an endpoint.
The user can configure both:

• the data transport protocol:

  • HTTP
  • MQTT
  • Raw TCP
  • Raw UDP

• the data encoding:

  • JSON Parsed
  • JSON Raw
  • ASCII
  • Raw bytes (COBS encoded)

Transport encodings

Data encoding defines how the data is encoded when is sent to an endpoint.
Not all encodings are available for all transport protocols (i.e. Raw bytes encoding cannot be used for HTTP transport protocol).

Regardless of which encoding is chosen, the data sent from the gateway consists of the following fields:

• gateway : the gateway identifier
• mac : the MAC address of the BLE device
• data : the parsed data advertised by the BLE device
• rssi : the RSSI of the received advertising packet
• type : the advertising type:
  • 1 = ADV_IND (connectable advertising)
  • 2 = ADV_SCAN_IND (directed advertising)
  • 3 = ADV_SCAN_IND (scannable advertising)
  • 4 = ADV_NONCONN_IND (non-connectable advertising)
  • 5 = ADV_SCAN_RSP (scan response)
• timestamp : the packet reception timestamp (this field is optional)

JSON Parsed

This encoding is the most user friendly, the TinyGateway decodes the received BLE advertisement data and provides an understandable JSON object containing the data received from the BLE device in a human readable form.
Example of JSON data object:

{
  "gateway" : "0000f412fad7a3c4",
  "mac" : "fd:c5:a8:6f:45:58",
  "data" : 
  {
    "blueup" :
    {
      "model" : 20,
      "serial" : 1,
    }
  },
  "rssi" : -70,
  "type" : 1,
  "timestamp" : 1683633555529
}

JSON Raw

This encoding scheme uses JSON encoding but does not parse the received BLE advertising data (this means that the BLE advertisement data payload is reported as a raw hex string).
Example of JSON data object:

{
  "gateway" : "0000f412fad7a3c4",
  "mac" : "e4:7d:ba:63:d1:96",
  "data" : "0201061aff4c000215acfd065ec3c011e39bbe1a514932ac0100060003ca",
  "rssi" : -64,
  "type" : 4,
  "timestamp" : 1683634105590
}

ASCII

In ASCII encoding scheme, data is sent to the endpoint as a plain ASCII string built as a sequence of fields separeted by a comma.
The structure of the ASCII data string is the following:

gateway,mac,type,data,rssi,timestamp\n

Example of ASCII data:

0000f412fad7a3c4,e1:9e:dd:60:e7:df,1,020106...,-72,1683636189216

Raw bytes (COBS)

This encoding scheme uses the COBS encoding format that marks the end of the packet with a special byte so that at the receiver side the end of a packet can be recognized.
To decode data sent from the gateway a COBS decoder must be used on the receiver side.
The structure of the decoded payload is organized as follows:

Transport Protocols

The transport protocol defines the network protocol used from the gateway to send the data to an endpoint.
Not all encodings are available for all transport protocols (i.e. Raw bytes encoding cannot be used for HTTP transport protocol).

HTTP

If HTTP is selected, the gateway will act as a HTTP Client and will send the data using standard HTTP POST method to a HTTP Server listening at the specified URI. For HTTP transport, the following fields should be configured:

• Uri: the HTTP Server Uri, format is host:port, if port is not specified, port 80 will be used.
  By clicking on the protocol button in the Uri field it is possible to switch between HTTP and HTTPS protocols.
  If HTTPS secure protocol is used, the Server Root CA must be provided to the gateway. If the gateway is able to reach the internet, the Root CA could be automatically recovered from the gateway using the button, otherwise the Root CA should be supplied in PEM format.
  If the HTTPS Server requires a Client certificate too, use the Use Client Certificate switch to provide a Client certificate to the gateway.

• Encoding: the data encoding to use. For HTTP, the Raw bytes (COBS) data encoding is not available.

• Authentication: the HTTP Authentication to use when sending data to the HTTP Server. Currently the TinyGateway supports only Basic Authentication as HTTP Authentication methods.

• Custom additional header: an additional header that can be set up to mark the data coming form the TinyGateway.

• Send interval: the data sending interval in seconds.

• Update duplicates: if selected, the same packet received several times from the same device will be updated rather than queued several times to the list of received packets.
  If not selected, each received packet will be queued into the data packet list, this means that if a beacon is advertising at 100ms, you could have 10 equal packets per second from the same device.

• Buffer management: specifies how the data queue is managed when full:

  • Send on full: when the queue is full, the data will be sent (even if the send interval is not elapsed)
  • Discard oldest packets: when the queue is full, the oldest packets will be discarded in favor of the new arrivals (the send interval is respected)
  • Discard newest packets: when the queue is full, the gateway will discard any new incoming packet (the send interval is respected)

• Add timestamp: wherether or not to send also the packet reception timestamp

MQTT

If MQTT is selected, the gateway will connect to an MQTT broker and will send data as standard MQTT publishes on the specified topic using the specified QoS. For MQTT transport, the following fields should be configured:

• Encoding: the data encoding to use. For MQTT, all data encodings are available.

• MQTT Broker: allows to choose a broker between those configured on the gateway.

• MQTT Topic: the topic where the data will be published.

• MQTT QoS: the MQTT QoS used for to publish the data.

• Send realtime: if enabled, the data is sent to the broker immediately, without storing them in a buffer. In case of real time transmission, only QOS 0 is available.
  If disabled, the gateway will send the data using a periodic time scheduling.

• Send interval^(*): the data sending interval in seconds.

• Update duplicates^(*): if selected, the same packet received several times from the same device will be updated rather than queued several times to the list of received packets.
  If not selected, each received packet will be queued into the data packet list, this means that if a beacon is advertising at 100ms, you could have 10 equal packets per second from the same device.

• Buffer management^(*): specifies how the data queue is managed when full:

  • Send on full: when the queue is full, the data will be sent (even if the send interval is not elapsed)
  • Discard oldest packets: when the queue is full, the oldest packets will be discarded in favor of the new arrivals (the send interval is respected)
  • Discard newest packets: when the queue is full, the gateway will discard any new incoming packet (the send interval is respected)

• Add timestamp: wherether or not to send also the packet reception timestamp

^(*) These fields are shown only when Send realtime is disabled.

Raw TCP Server

In this mode the gateway will behave as a TCP Server listening for new clients connection before sending data. For TCP Server transport, the following fields should be configured:

• Encoding: the data encoding to use. For TCP Server, all data encodings are available.

• Port: the TCP port to be used from the TCP Server.

• Send realtime: if enabled, the data is sent to the broker immediately, without storing them in a buffer. If disabled, the gateway will send the data using a periodic time scheduling.

• Send interval^(*): the data sending interval in seconds.

• Update duplicates^(*): if selected, the same packet received several times from the same device will be updated rather than queued several times to the list of received packets.
  If not selected, each received packet will be queued into the data packet list, this means that if a beacon is advertising at 100ms, you could have 10 equal packets per second from the same device.

• Buffer management^(*): specifies how the data queue is managed when full:

  • Send on full: when the queue is full, the data will be sent (even if the send interval is not elapsed)
  • Discard oldest packets: when the queue is full, the oldest packets will be discarded in favor of the new arrivals (the send interval is respected)
  • Discard newest packets: when the queue is full, the gateway will discard any new incoming packet (the send interval is respected)

• Add timestamp: wherether or not to send also the packet reception timestamp

^(*) These fields are shown only when Send realtime is disabled.

Raw TCP Client

In this mode the gateway will behave as a TCP Client and will try to connect to the specified TCP Server before sending data. For TCP Client transport, the following fields should be configured:

• Encoding: the data encoding to use. For TCP Client, all data encodings are available.

• Host: the host (IP address or hostname) where the TCP Server is running.

• Port: the TCP port used from the TCP Server.

• Send realtime: if enabled, the data is sent to the broker immediately, without storing them in a buffer. If disabled, the gateway will send the data using a periodic time scheduling.

• Send interval^(*): the data sending interval in seconds.

• Update duplicates^(*): if selected, the same packet received several times from the same device will be updated rather than queued several times to the list of received packets.
  If not selected, each received packet will be queued into the data packet list, this means that if a beacon is advertising at 100ms, you could have 10 equal packets per second from the same device.

• Buffer management^(*): specifies how the data queue is managed when full:

  • Send on full: when the queue is full, the data will be sent (even if the send interval is not elapsed)
  • Discard oldest packets: when the queue is full, the oldest packets will be discarded in favor of the new arrivals (the send interval is respected)
  • Discard newest packets: when the queue is full, the gateway will discard any new incoming packet (the send interval is respected)

• Add timestamp: wherether or not to send also the packet reception timestamp

^(*) These fields are shown only when Send realtime is disabled.

Raw UDP Client

In this mode the gateway will behave as a UDP Client and will send data to the specified UDP Server. For UDP Client transport, the following fields should be configured:

• Encoding: the data encoding to use. For UDP Client, all data encodings are available.

• Host: the host (IP address or hostname) where the UDP Server is running.

• Port: the UDP port used from the UDP Server.

• Send realtime: if enabled, the data is sent to the broker immediately, without storing them in a buffer. If disabled, the gateway will send the data using a periodic time scheduling.

• Send interval^(*): the data sending interval in seconds.

• Update duplicates^(*): if selected, the same packet received several times from the same device will be updated rather than queued several times to the list of received packets.
  If not selected, each received packet will be queued into the data packet list, this means that if a beacon is advertising at 100ms, you could have 10 equal packets per second from the same device.

• Buffer management^(*): specifies how the data queue is managed when full:

  • Send on full: when the queue is full, the data will be sent (even if the send interval is not elapsed)
  • Discard oldest packets: when the queue is full, the oldest packets will be discarded in favor of the new arrivals (the send interval is respected)
  • Discard newest packets: when the queue is full, the gateway will discard any new incoming packet (the send interval is respected)

• Add timestamp: wherether or not to send also the packet reception timestamp

^(*) These fields are shown only when Send realtime is disabled.

Remote Management

This section allows to enable and configure the TinyGateway MQTT Remote Management service.
The TinyGateway MQTT Remote Management service allows the usage of the TinyGateway API remotely using a MQTT broker as a bridge. Using the TinyGateway MQTT Remote Management allows to remotely monitor and control the gateway. When enabled the gateway will use 3 MQTT topics to

• MQTT Broker: the MQTT broker to use for the Remote Management service

• Log level: if enabled, the gateway will report its logs to the broker.
  This field is intended to be used to investigate gateway behaviour in case of problems.
  Don't overload the gateway with verbose remote logging if not needed.
  Possible values to be selected are:

  • No logging
  • Errors only
  • Errors and warnings
  • Verbose

• Request Topic: this is the topic where the remote system will publish its requests that will be taken in charge from the gateway

• Response Topic: this is the topic where the gateway replies to the requests received from the remote system

• Event Topic: this is the topic where the gateway publishes its events

• MQTT QoS: specifies the QoS to be used for the publishes

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.

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

BLE Devices

This section will show the list of all the BLE devices received from the TinyGateway. Each device is uniquely identified by its MAC address. If a BlueUp beacon is detected, the beacon name is also shown. For each device all the received advertising packets are also listed.

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 TinyGateway BLE API calls is available at the following page.