TinyGateway PoE BLE User Guide

TinyGateway LTE Bluetooth LE (in the following referred to also as “TinyGateway LTE" or simply “gateway”) is the new Bluetooth Low Energy gateway by BlueUp based on ESP32 module (for Ethernet and WiFi connectivity), BG96 module (for LTE connectivity) and nRF52832 (for Bluetooth LE scan and connection).

TinyGateway has a web user interface that allows to:

• configure LTE, Ethernet, WiFi connection, BLE and transport service;
• monitor gateway data and active services;
• update firmware.

Hardware description

TinyGateway LTE BLE is a low-power and low-cost Bluetooth LE gateway, with Wifi, Ethernet and LTE connectivity. TinyGateway LTE 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 figure whose functionality is described in table below.

How to Install

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

TinyGateway LTE BLE – 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).

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

TinyGateway LTE BLE – 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).

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:

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 settings (depending on the gateway version)
• MQTT settings
• BLE settings
• Data transport/encoding settings
• NTP settings
• Remote Management settings

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 LTE connection parameters, go to Configuration → LTE.

To properly configure the LTE connection 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 and it is suggested to configure the WiFi AP connection to be able to reach the gateway after the configuration is saved.

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.

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.

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: whether 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

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 advertisement 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 by 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 separated 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 by 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 by 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: whether 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: whether 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: whether 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: whether 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: whether or not to send also the packet reception timestamp

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

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.

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 behavior 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 by 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

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;
• Reboot - to reboot the gateway;
• Logout - to logout the web interface.

BLE Devices

This section will show the list of all the BLE devices received by 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.

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.