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:

gatewaymactyperssitimestampdata_lendata
8 bytes6 bytes1 byte1 byte8 bytes1 byte1-255 bytes

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 Cloud button 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

NOTE
For HTTP transport the SEND REALTIME option is not available because of the high amount of BLE packets that can be gathered by the gateway per second.

HTTP Transport

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.

MQTT Transport

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.

TCP Server Transport

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.

TCP Client Transport

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.

UDP Client Transport