Home

Awesome

<div align = center>

BlueDisplay

This library enables an Android smartphone / tablet to act as a graphical display for your Arduino or ESP32.<br/>

Badge License: GPLv3     Badge Version     Badge Commits since latest     Badge Build Status     Badge Hit Counter <br/> <br/> Stand With Ukraine

Available as Arduino library "BlueDisplay".

Button Install     Button Changelog

</div>

If you find this library useful, please give it a star.

🌎 Google Translate

<br/>

BlueDisplay library for Arduino

With the BlueDisplay library you create the GUI for your application, e.g. Graphics, Text, Buttons and Sliders on the Arduino itself.<br/> No Android programming required!<br/> The Arduino is connected via USB-cable or Bluetooth with your smartphone / tablet, where the BlueDisplay app renders the GUI. GUI callback, touch and sensor events are sent back to the Arduino, where they can be handled.<br/> The Bluetooth connection can be achieved by using an ESP32 or connecting a HC-05 to the RX/TX pins of your Arduino. Connecting the Arduino with an USB cable to your smartphone requires an USB-OTG adapter.<br/>

<br/>

Features

Local graphic support

<br/>

Installation

On Android, you need to install the BlueDisplay app.

<br/>

Usage

//#define BLUETOOTH_BAUD_RATE BAUD_115200   // Activate this, if you have reprogrammed the HC05 module for 115200, otherwise 9600 is used as baud rate
#include "BlueDisplay.hpp"

// Declare callback handler for (re)connect and resize
void initDisplay(void);
void drawGui(void);

void setup() {
    Serial.begin(BLUETOOTH_BAUD_RATE);
    BlueDisplay1.initCommunication(&initDisplay, &drawGui);
}
void loop() {
...
    checkAndHandleEvents();
}
void initDisplay(void) {
    // Initialize display size and flags
    BlueDisplay1.setFlagsAndSize(BD_FLAG_FIRST_RESET_ALL | BD_FLAG_USE_MAX_SIZE | BD_FLAG_TOUCH_BASIC_DISABLE, 320, 240);
    // Initialize all GUI elements here
 ...
}
void drawGui(void) {
    BlueDisplay1.clearDisplay(COLOR16_WHITE);
    // Draw all GUI elements here
...
}
<br/>

Which Serial interface?

For boards which have more than one serial interface, the library tries to use Serial1 for the BT connection to leave Serial, which is mostly connected to the USB, for other purposes as logging etc.. If you require direct USB connection to the smartphone / tablet by cable for this board, you must activate the macro USE_USB_SERIAL.<br/> Another, but more more complicated, way is to modify the central serial interface function of the library. You only have to change the first 2 lines of the function sendUSARTBufferNoSizeCheck() in BlueSerial.hpp according to your requirements.

<br/>

Sensor axis for an Arduino application

Android axis are defined for natural screen orientation, which is portrait for my devices:

The BlueDisplay application converts the axis, so that this definition holds for each screen orientation. For detailed information to sensors see ShowSensorValues example

<br/>

Using the new *.hpp files

In order to support compile options more easily, the line #include <BlueDisplay.h> must be changed to #include <BlueDisplay.hpp> in your main program (aka *.ino file with setup() and loop()).

In all other files you must use #include <BlueDisplay.h>, to prevent multiple definitions linker errors:

<br/>

Compile options / macros for this library

To customize the library to different requirements, there are some compile options / macros available.<br/> These macros must be defined in your program before the line #include <BlueDisplay.hpp> to take effect.<br/> Modify them by enabling / disabling them, or change the values if applicable.

NameDefault valueDescription
BLUETOOTH_BAUD_RATE9600Change this, if you have reprogrammed the HC05 module for another baud rate e.g.115200.
DO_NOT_NEED_BASIC_TOUCH_EVENTSdisabledDisables basic touch events like down, move and up. Saves up to 620 bytes program memory and 36 bytes RAM.
USE_SIMPLE_SERIALdisabledOnly for AVR! Do not use the Serial object. Saves up to 1250 bytes program memory and 185 bytes RAM, if Serial is not used otherwise.
USE_USB_SERIALdisabledActivate it, if you want to force using Serial instead of Serial1 for direct USB cable connection to your smartphone / tablet. This is only required on platforms, which have Serial1 available.
SUPPORT_LOCAL_DISPLAYdisabledSupports simultaneously drawing on the locally attached display. Not (yet) implemented for all commands!
DISABLE_REMOTE_DISPLAYdisabledSuppress drawing to Bluetooth connected display. Allow only drawing on the locally attached display. Not (yet) implemented for all commands!
LOCAL_GUI_FEEDBACK_TONE_PINdisabledIf defined, local GUI library calls tone(LOCAL_GUI_FEEDBACK_TONE_PIN, 3000, 50) on flags like FLAG_BUTTON_DO_BEEP_ON_TOUCH.
SUPPORT_ONLY_TEXT_SIZE_11_AND_22disabledIf defined, saves program memory especially for local GUI.
LOCAL_DISPLAY_HEIGHT240The height of the local diplay used by the LocalGUI library.
LOCAL_DISPLAY_WIDTH320The width of the local diplay used by the LocalGUI library.
<br/>

Display Unicode characters with setCharacterMapping()

if we want to use special characters to display, we face the problem, that we can only send ASCII codes to be displayed. But fortunately the ASCII code table has at least 128 "unused" entries between 0x80 and 0xFF, normally used for the local codepage.<br/> But with setCharacterMapping(<ASCII_value>, <UTF16_value>) you can modify this codepage, i.e display the character <UTF16_value> if you send <ASCII_value>, which has to be between 0x80 and 0xFF.<br/> Since the 2. parameter for setCharacterMapping is 16 bit, you cannot use characters whose Unicode code is higher than 0xFFFF like the electric light bulb (U+1F4A1 from https://www.fileformat.info/info/unicode/char/1f4a1/index.htm).

Example

    BlueDisplay1.setCharacterMapping(0x87, 0x2227); // mapping for unicode AND used as Forward symbol
    BlueDisplay1.setCharacterMapping(0x88, 0x2228); // mapping for unicode OR used as Backwards symbol
<br/>

Using another Codepage with setCodePage()

By default, the local codepage of the Android system is used for display special characters above 0x7F.<br/> But if you have a codepage which better fits your needs and you want to use as your default code page, you can change it with setCodePage(<ISO_8859_Number>). Internally it is done on Android with Charset.forName("ISO_8859_" + <ISO_8859_Number>).

<br/>

Examples

Before using the examples, take care that the Bluetooth-module (e.g. the the HC-05 module) or ESP32 program is connected to your Android device and is visible in the Bluetooth Settings.

All examples initially use the baud rate of 9600. Especially the SimpleTouchScreenDSO example will run smoother with a baud rate of 115200.<br/> For this, change the example baud rate by deactivating the line #define BLUETOOTH_BAUD_RATE BAUD_9600 and activating #define BLUETOOTH_BAUD_RATE BAUD_115200.<br/> AND change the Bluetooth-module baud rate e.g. by using the BTModuleProgrammer.ino example.<br/> For ESP32 no baud rate must be specified :-).

BlueDisplayBlink

Simple example to check your installation.

BreadboardWith debug output after pressing the "Stop" button
BlueDisplayBlink BreadboardWith debug output

BlueDisplayExample

More elaborated example to show more features of the BlueDisplay library.

ScreenshotGraphics test page with additional thick red lines
ScreenshotGraphics test page
Fritzing schematic for BlueDisplay exampleBlueDisplay example breadboard picture
Fritzing boardBreadboard picture

ShowSensorValues

Shows the accelerometer and gyroscope values received from the smartphone both graphical and numerical.

Plotter output of accelerometer

BTModuleProgrammer

Simple helper program to configure your HC-05 or JDY-31 modules name and default baud rate with a serial monitor. It can also be used to enter AT commands directly to the BT module for extended manual programming.<br/> Breadboard picture

Sample outputs can be found here.

RcCarControl

Example of controlling a RC-car by smartphone accelerometer sensor.

RC car control displayHacked RC car
RC car control displayHacked RC car

ServoExample

The accelerometer sensor of the android display is used to control two servos in a frame which holds a laser. This is an example for using a fullscreen GUI.<br/> If no BD connection available, the servo first marks the border and then moves randomly in this area (Cat Mover).<br/>

ScreenshotBias setting
ServoExampleBias setting

SimpleTouchScreenDSO

300 kSamples DSO without external hardware (except the HC-05 module). For AC input, only a capacitor and 4 resistors are needed. More information at Arduino-Simple-DSO.<br/> Not for STM32.

DSO start screenDSO chart screen with long info
DSO start screenDSO chart screen with long info

US_Distance

Shows the distances measured by a HC-SR04 ultrasonic sensor. Can be used as a parking assistance. Breadboard and smartphone

<br/>

Random delays on some smartphones

Depending on the device you use, you can observe some random "delays" up to 500 ms in the timing of the display refresh. The delays does not occur if you use a USB connection instead of the Bluetooth one.<br/> The reason is, that the Android Bluetooth driver does not return its received bytes for a longer time.<br/> If you send to much data during this delay the driver may hang, as you can observe for the SimpleDSO Application, which runs smooth with a USB connection.<br/> Hanging may be avoided if using flow control, but the HC05 firmware and HC05 breakout boards do not support it. On the ESP32, the BluetoothSerial library supports flow control and there you can observe that the client program also delays, when the smartphone driver takes its break.<br/> This Bluetooth driver is usually delivered by the hardware vendor, so it may depend on the chips used in your smartphone. It seems, that some Bluetooth SPP (Serial Port Profile) drivers are not really specified/tested/optimized for real time behavior.<br/> Known devices with these "delays" are:<br/> Lenovo K3 Note 6.0, Nexus7 with AW-NH665 BT-Chip running 6.0.1, Nexus 6P with ?8.x?, Kindle Fire HD 8 with Broadcom BCM2076 running 6.3.1.5.<br/> Known devices without these "delays" are:<br/> Samsung Note 3 running 5.0, Lifetab P9702 running 7.1.2, Lifetab E10310 running 4.2.2, XORO PAD 721 running 4.2.2, Samsung Galaxy S3 GT-I9300 running Lineage 7.1.2, LUX10 running 5.0, iRULU X11 running 5.1.1, Time2 TC1050G running 5.1, Pixel 4 XL running 10.

Extras

The extras folder (in the Arduino IDE use "Sketch > Show Sketch Folder" (or Ctrl+K) and then in the libraries/BlueDisplay/extras directory) contains more schematics, breadboard layouts and pictures which may help you building the example projects.

Hints

Debugging

If you need debugging, you must use the debug() functions since using Serial.print() etc. gives errors (we have only one serial port on the Arduino).

BlueDisplay1.debug("DoBlink=", doBlink);

The debug content will then show up as toast on your Android device and is stored in the log. Change the log level in the app to see more or less information of the BlueDisplay communication.

Connecting TX

To enable programming of the Arduino while the HC-05 module is connected, use a diode (e.g. a BAT 42) to connect Arduino rx and HC-05 tx. On Arduino MEGA 2560, TX1 is used, so no diode is needed.

                 |\ |
   Arduino-rx ___| \|___ HC-05-tx
                 | /|
                 |/ |

Revision History

Version 4.0.1

Version 4.0.0

Version 3.0.2

Version 3.0.1

Version 3.0.0

Version 2.2.0

Version 2.1.1

Version 2.1.0

Version 2.0.0

Version 1.3.0

Version 1.2.0

Version 1.1.0

Version 1.0.1

Version 1.0.0

Initial Arduino library version

Old Revision History corresponding to the Android BlueDisplay App

V 3.7

V 3.6

V 3.5

V 3.4

V 3.3

V 3.2

V 3.1

V 3.0

CI

The library examples are tested with GitHub Actions for the following boards:

Requests for modifications / extensions

Please write me a PM including your motivation/problem if you need a modification or an extension.