Communication Bridge

User guide

(Android version)

Introduction

Communication Bridge app enables communication between different types of communication technologies. Smartphone with this app installed acts as a converter device. It connects to remote devices which cannot communicate directly between each other, and it creates communication bridge between them, enabling them to exchange data. Following types of connections are currently supported:

App can also display all received data in log in hexadecimal or text form and send data directly to connected devices (hexadecimal or text). 

Information in this user guide apply to the latest app version (and higher). If some features are available only in PRO version, it is mentioned in the text.

Current app version: 6.6

Join BETA program to access the latest update with the newest features.

Complex bridge mode in development

Complex mode will be an upgradable feature, which will extend the device limit from 2 to up to 8 devices.  You can check preliminary user guide and also test this feature.

Communication bridge for Windows

Windows version of this application is available to download from Microsoft store.  You can check user guide for Windows version here.

Smartphone requirements

Permissions

For application to function properly, it needs following permissions:

Wi-Fi connection information

Location

Reason for this permissions from Google developer guide: LE Beacons are often associated with location. In order to use BluetoothLeScanner, you must request the user's permission by declaring either the ACCESS_COARSE_LOCATION or ACCESS_FINE_LOCATION permission in your app's manifest file. Without these permissions, scans won't return any results. 

Other

How it works

Communication Bridge app can connect to 2 remote devices and create a communication link between them. These remote devices are represented as Device A and Device B in the app. Each device has a dedicated panel which displays type of active connection (if any), device name and connection status.

Supported connections:

Main screen of the app

App can create a communication link between above mentioned device types. On each side one device type can be selected and these two devices can than communicate with each other via BT/USB/TCP Bridge app.

Impossible connections are:

Examples of use cases

Ex.1: We need to control Arduino board with Bluetooth module from a computer with application which offers only TCP connections. We use bridge app to connect to the TCP server on the PC and on the other side we connect to Bluetooth module HC-05 of our Arduino board. Thus we are able to send commands from PC application to Arduino board.

Ex.2: In this case we want to use Bluetooth terminal application on our PC for communication with BLE device. But our PC does not have the ability to connect to BLE devices. We use smartphone with communication bridge in between which can connect to both devices and mediate the communication.

Ex.3: We have a processor board with serial link (UART) and we need to connect it to Arduino board equipped with Bluetooth module. We use smartphone with USB OTG functionality and USB to UART cable to connect to the processor board. Then we connect to the HC-05 Bluetooth module of the Arduino board.

Ex.4: We want to control our Bluetooth device from our smartphone using terminal app which only offers TCP connections. We connect to Bluetooth device from BT/USB/TCP bridge app and create a TCP server. Than we minimise the app (bridge app can run as a background service) and open our terminal from which we connect to TCP server created with communication bridge app - on the same device.

Connecting process

To create a communication link between 2 remote devices, we first need to create a connection between them and bridge app. After both connections are established, app immediately bridges the communication. Connection process for each type of device / connection is described in the following sections.

Connecting to Classic Bluetooth device

To connect to a classic Bluetooth device, click on the "Select task" button and select Classic Bluetooth. Classic Bluetooth device can be connected as a Device A or Device B, so it does not matter which of two "Select task" button you click. Let`s connect it as a Device A in this example.

NOTE: App can also open port and listen for incoming Bluetooth connections. To enable listening for remote connections, click on "Select task "button and select "Open Bluetooth listening socket". Then you can initialise connection from remote device.

Make sure remote Bluetooth device is paired with your phone, is turned on and is listening for incoming connections. Then select it from the list of all paired devices and the connection should be established. After successful connection, name of the device will be displayed under Device A/B label with status "connected".

If your Bluetooth device is not showing in the list because it is not paired with your phone, minimalize app, pair device and return to app. If the device you just paired still does not show up in the list, return to main app screen and then select again task of connecting classic Bluetooth device - the list of paired devices will be refreshed.

If you want app to automatically try to re-connect to selected device when connection is lost (e.g. device got temporary out of range) check the checkbox Automatically try to reconnect...

Note that even if BLE devices might be listed as paired devices, they will not be connected using Serial port profile (SPP) protocol. To connect to BLE device select "Connect to BLE device" on the main screen (see following section).

In our case, we want to connect to HC-05 Bluetooth module. It is already paired so it appears in the list. Just click on the name HC-05.

Connecting to BLE device

Click on Select task button and select BLE Device. 

In our example we want to use service 0000ffe0-0000-1000-8000-00805f9b34fb and characteristic 0000ffe1-0000-1000-8000-00805f9b34fb, so we click on the respective characteristic.

Connecting to USB-serial device

In order to connect to USB-serial device, your smartphone must support USB OTG functionality. You also need USB OTG cable. Supported USB devices are: CP210x, CDC, FTDI, PL2303 and CH34x chips.

Plug in USB-serial converter using USB OTG cable. Click on Select task button and select USB-serial. USB device should be automatically detected. In some cases (some smartphones) more than one USB device can be detected (might be internal USB device). In that case you need to try which one is the correct one by changing index in the drop-down menu USB#.

Following parameters can be set for the connection:

After setting up the parameters click on the "USB connect" button. After successful connection, device name will be displayed in the respective Device A or B panel of the main screen and status will be set as "Connected".

TCP client

Using TCP client, app can connect to a TCP server on a network (local network or internet). Make sure you are connected to the right network. TCP server can be created on a PC, other smartphone device or any other device supporting TCP protocol. If you create TCP server on a PC, make sure firewall is not blocking connections. Alternatively you can connect to a server running on the same device using localhost address. 

To connect to a TCP server, you need to start TCP client in the app. Click on "Select task" button and select TCP client. To connect to a TCP server you need to enter its IP address (or host name) and port number. Click "Connect to Server" and TCP client from your smartphone will connect to specified TCP server.

You can also configure TCP client to try to automatically reconnect if connection is lost. This might be useful in scenarios where a device is moving in and out of a network range or when WiFi signal is weak. This autoreconnection simply tries to re-establish previous connection with configured parameters and is performed each second.

TCP server

App can start TCP server and allow connection of multiple TCP clients. To start TCP server click on "Select task" button. On next screen following parameters can be configured for the server.

Local Port specifies the port number on which your server will be listening. Your IP address is displayed also, use it on your TCP client together with the port number you specified to make a connection.

Following features are available in PRO version.

Client count limit determines how many client connections will server accept. When the client count is already full and new client tries to connect you can configure server to refuse incoming connection or to disconnect oldest client and allow new incoming connection. This option might be useful if your client loses connection with server (it moves out of WiFi range) and socket is not closed on server side. With this option checked you will be able to re-establish connection without the need of restarting TCP server. No connection will be overwritten in such case, because it was already lost.

In the case that multiple clients are connected to the server, it acts as a multiplexer / splitter. All outgoing data are splited to all clients and all incoming data are multiplexed to one stream for other connected device.

There is also an option to automatically disconnect connected client if no data is coming from it for set period of time. You can specify timeout in seconds. In the example below, connection with the client will be interrupted by TCP server if it receives no incoming data for 10 seconds. Uncheck the checkbox to not use this feature. If multiple clients are connected, this timeout refreshes each time when server receives data from any client. If timeout expires, all clients are disconnected.

When configuring TCP server, you also have the option to broadcast an UDP packet, if no client is connected. The purpose of this feature is to enable TCP server to be detected on the network by clients. You can include necessary information into UDP packet data.  UDP broadcast automatically stops once client is connected. If client disconnects, UDP broadcast is resumed.

Here is an example of a practical usage of such feature.

Options for UDP (broadcast) address:

Get network broadcast address automatically - Network broadcast address will be detected and used.

Use loopback broadcast address - loopback broadcast address is fixed value of 127.255.255.255

Enter address manually - With this option you can manually specify any IPv4 address.

You can use all these options in combination with autostart / autoconnect configuration.


UDP socket

App can open listening UDP socket. You can specify local port number. For remote device (remote UDP socket) you need to know and enter its IP address and its port number. 

UDP is connectionless communication - no active connection is created when you create a UDP socket. Data transmitted over network are individually addressed and routed based on information carried in each data packet. Therefore status of this connection (on the main screen) does not differentiate between connected /  disconnected state.

MQTT client

Next connection option is MQTT client. Enter typical parameters, as broker (IP address or its host name), port, connection protocol, QoS, Client ID and publish and/or subscribe topic. Either publish or subscribe topic must be entered. If only publish topic is defined, MQTT client will only send data. If only subscribe topic is defined, MQTT client will only receive data.

You can also specify credentials (username and password) if broker requires authentication. Leave these fields empty to connect without authentication.

Note about QoS parameter: QoS (Quality of Service) is a parameter used in MQTT (Message Queuing Telemetry Transport) protocol to specify the level of guarantee for delivering a message. There are three levels of QoS:

QoS 0 is the fastest and least reliable option, while QoS 2 is the slowest but most reliable option. The level of QoS is determined by the publisher and is specified when publishing a message. The subscriber can also request a specific QoS level when subscribing to a topic.

When ready, click Connect to Broker to establish connection.

Serial transmission vs packets

If you are retransmitting data from a serial communication, which does not define packets (Bluetooth SPP - serial port profile, UART, etc.), to a type of connection, which does (e.g. TCP or MQTT) it is important to understand that the original data from the serial communication might arrive segmented  differently as originally sent from the sender. Data might arrive in multiple packets, or, on the other hand, data from multiple transmit events might be joined to one packet on a receiver side.

Let`s have 2 connection in the app. Device A is Bluetooth connection (for example some Bluetooth module) and Device B is MQTT client. We have both devices (both communication ends) under our control, meaning we can send and receive data to and from both ends. Imagine situation that we sent 8 byte long message from Bluetooth module to the Bridge app, which will receive and retransmit the data using MQTT client. We can`t expect that receiver receives 8 byte long message at once (at one event). New data event might be raised 2x with 4 bytes, or with 2 bytes, then 6 bytes.

Another example: if you send 2 messages consecutively from the sender (Bluetooth module), each with length of 8 bytes, receiver might receive it in one New data event with buffer size of 16 bytes. That is how serial communication works. There are no messages, no packets. It is just a stream of data.

If, on a receiver side, we want to receive data in coherent way (abstraction of a complete message), we need to implement buffer / parser logic. We can for example define that the message (packet) will always be 8 bytes long. Then on a receiver side we will implement small buffer which will be treated as a complete message only when full. To make this more robust we might need to implement other mechanisms like CRC byte(s), fixed value header byte(s) and timeouts to invalidate incomplete messages.

This is also the reason why app has the option to display each received data in one event as a separate line. You can observe how the data are received and then retransmitted by the app itself.

Running in background

App can run in background, when minimized or when screen is turned off. To prevent Android OS from stopping app in the background mode, it is highly recommended to have app excluded from battery optimization in phone settings.

View current device configuration

Once the device is active or connection established, you can view its current configuration by clicking on its symbol.

Retransmission

When both connections are established (Device A and Device B) app immediately acts as a communication mediator. This is indicated by a status "Bridge active".  All received data from one device are automatically send to the second device and vice versa. However, if needed, this behaviour can be changed. App can act as a one-way filter, re-sending only data from one device to the second, but ignoring incoming data from the second device. To activate this feature select the desired retransmission direction in the Retransmission drop-down menu. If needed, retransmission can also be (temporarily) disabled.

Data logging

Incoming data from remote devices can be viewed in the log. To show log click on "Traffic" button on the main screen.

To start logging incoming data click on a "Start" button. Data logging is not enabled by default since it can slow down data retransmission (if you use high transfer speeds and large amount of data you might notice a delay when logging is enabled).

In a drop-down menu you can select which data you want to show in log.

Incoming message consist of data identifier (name of a device from which message is received and time stamp of reception) and data itself. Data identifiers can be customised in settings. Size of the font used for logging can be changed in settings also.

In the following screenshot 2 devices are connected (BLE device MLT-BT05 and TCP server) and each is sending data. You can identify sender by its name.

If the color differentiation is enabled in the setting, following colors will be used:

You can also copy a particular message from the log by long clicking on it. It will be copied to a clipboard.

Data sending

Data can be send to remote devices directly from the app (traffic page). You can select between hexadecimal or text form. To switch between these two options, click on "0x/txt" button. Enter value (either valid hexadecimal number or text) and click "Send". In the checkboxes "A" and "B" you can specify to which connected devices(s) you want to send the data. Data will also appear in the log.

Autostart / Autoconnect

Autostart / autoconnect feature (available only in PRO version) allows you to automatically connect to selected device(s) upon app start without need to selecting it (them) manually each time. Each type of device (connection) can be configured for autostart functionality.

To enable this feature either device A, B or both need to be configured, meaning each required parameter must be known for app to be able to establish connection or start task on next app run.

First thing you need to do is to connect manually (without autostart) to the device(s) which you want to be remembered by autostart function. Then from the app settings open Autostart menu. Here, set currently connected device A, B or both by clicking on "Configure device A/B" and select "Set currently connected device". You can review autostart configuration for both devices by clicking on "View autostart script configurations".

Second step is to enable autostart functionality. Click on "Autostart" and select Enable. Autostart can be enabled only if at least one device(A/B) is configured for autostart.

"Help with autostart" will get you here.


Autostart script

Autostart / Autoconnect feature is carried out by a script which runs automatically (if enabled in settings) when the app starts. This script goes through different steps based on configured device types. For example if Bluetooth device is configured for autoconnect, Bluetooth adapter is checked and enabled (if it is not). Then required permissions are checked, then connection attempt is initiated, etc...

Autostart script runs for device A then device B. If Only one device is configured, other device is skipped.

Autostart script can be interrupted by user. In such case all already established connections will be disconnected.

If needed, autostart script can be run again later, when app is already started by clicking on "Re-run" button. Any active connections will be closed a priory.

Settings

To access the app settings click on the 3 lines symbol in the top right corner in the main screen.

To exit settings, click on the back button. All changes are saved automatically.


Log settings

Log settings is accessible via settings menu.