TinyGateway PoE BLE User Guide

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

TinyGateway PoE BLE	TinyGateway PoE BLE Outdoor

TinyGateway has a web user interface that allows to:

• configure Ethernet connection, 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 PoE BLE is a low-power and low-cost Bluetooth LE gateway, with Ethernet connectivity. TinyGateway PoE has one button that has the following features:

• single press to reboot the gateway
• long press (5s) to perform the factory reset of the gateway.

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

How to Install

The gateway installation procedure depends 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 PoE BLE Indoor

TinyGateway PoE BLE Indoor – 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. Connect the gateway to the LAN using a standard Ethernet cable.
3. Power on the gateway using a standard USB 5V power supply with USB to USB-C cable (not included).
4. TinyGateway now is ready to be used (Power-on green LED switched on).

TinyGateway PoE BLE Indoor – PoE power supply

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

TinyGateway PoE BLE Outdoor

TinyGateway PoE BLE Outdoor can be powered only using the PoE RJ45 connector. TinyGateway is provided with a pole mounting kit already included for installation ease. Make sure that your LAN is already provided with a PoE Switch or connect a PoE Switch to your LAN network.

1. Install your TinyGateway on a pole using the pole mounting kit provided with the gateway.
   Other mounting options are possible using the 4x threaded holes for M6 screws on the back panel.

   Pole mounted gateway	Pole mounted gateway, back view

2. Connect the gateway to the PoE-enabled LAN with a standard Ethernet cable.

3. TinyGateway now is ready to be used.

First Start

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:

Note: LEDs are not visible in Outdoor version

Step 2. Web interface access

By default TinyGateway PoE Ethernet interface is configured with DHCP. To be able to access the web user interface it is necessary to retrieve the IP address assigned to the gateway by the local DHCP server. Once the IP address is known, the user can browse it and the web user page will appear.

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

Step 3: 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, the gateway has to be rebooted to update the configuration.

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

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.