ESP32
IMPORTANT NOTE: All examples are based on ESP32 library version 2.x. If you are using ESP32 library version 3.x, see the migration guide or downgrade your ESP library to latest 2.x version.
The following examples show how to connect GUI-O application with ESP32 in various communication modes. Tutorial for automatic device pairing also shows how to include SSL/TLS for secure MQTT (IoT) connection.
Page contents
ESP32 & Arduino & GUI-O basic examples
The following examples show basic interaction between GUI-O application and ESP32 module in various communication modes.
ESP32 Bluetooth
Download BasicBluetooth.ino sketch
Follow Basic Bluetooth video tutorial
Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
ESP32 Bluetooth LE
Download BasicBLE.ino sketch (or BasicBLE_NUS.ino for Nordic UART service)
Follow Basic BLE video tutorial
Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
ESP32 MQTT (supports SSL/TLS)
Download BasicMQTT.ino sketch or BasicMQTT_SSL_TLS.ino sketch for secure (encrypted) communication
Follow Basic MQTT video tutorial
Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
ESP32 USB
Download BasicUSB.ino sketch
Follow Basic USB video tutorial
Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
NOTE: In order to connect ESP32 to your Android device, a simple adapter cable is needed (as shown in the image). Also note that not all Android devices support USB OTG functionality.
ESP32 Local WiFi
Download BasicEthernet.ino sketch
Follow Basic Ethernet video tutorial
Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
ESP32 & Arduino & GUI-O automatic pairing (supports SSL/TLS)
The following example shows how to automatically pair GUI-O application with ESP32 in MQTT (IoT) mode. Although the example uses ESP32-WROOM-32 board, it should be compatible with any other ESP32 board.
GUI-O application always uses SSL/TLS for secure (encrypted) communication. In order to also establish a secure connection from the ESP32 side, use ESP32_GUI-O_pairing_source_SSL_TLS.zip. To establish an unencrypted connection, use ESP32_GUI-O_pairing_source.zip instead (see "Prerequisites" section below).
The following step-by-step instructions are also shown in the video tutorials below.
Prerequisites
Download Arduino IDE
Download ESP32_GUI-O_pairing_libs.zip and extract the archive
Download ESP32_GUI-O_pairing_source.zip or ESP32_GUI-O_pairing_source_SSL_TLS.zip (for secure connection) and extract the archive
Step 1: Add ESP32 board support
Open Arduino IDE
Select "File -> Preferences" and under Additional Boards Manager URLs enter: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
Select "Tools -> Board -> Boards manager..."
Search and install "esp32" by Espressif Systems
After installation select "Tools -> Board -> ESP32 Arduino -> ESP32 Dev Module"
Step 2: Include necessary libraries
Select "Sketch -> Include library -> Add .ZIP library..."
Navigate to location, where ESP32_GUI-O_pairing_libs.zip archive was extracted
Select .zip library and confirm (repeat procedure until all .zip libraries are included)
Step 3: Upload the code
Select "File -> Open"
Navigate to location, where ESP32_GUI-O_pairing_source.zip archive was extracted
Select PairingMQTT.ino and confirm
Make sure that ESP32 board is connected to your PC
Make sure that the correct port is selected
Press upload button to start code upload (IMPORTANT NOTE: on some ESP32 boards, the BOOT button must be pressed when the upload starts)
Reset ESP32 board after code upload
Check out the video tutorial below!
Video tutorial of Step 1 - 3
Step 4: Pair GUI-O application with ESP32 board
The pairing procedure is fully guided within GUI-O application. The important parts are described below.
Open GUI-O application and navigate to settings
Make sure that IoT connection is active (select "Connections -> IoT")
From main settings menu select "Quick pair -> Direct device pairing"
Name your ESP32 device (setting your user name is optional) and confirm
Wait while surrounding WiFi networks are scanned then select your (router) WiFi network and input your password
Put the ESP32 device into pairing mode then search and connect to guio_ device (input password 12345678 when prompted)
IMPORTANT NOTE: Do not switch network if prompted by Android (keep connection to guio_ device)
Press "back button" and wait for pairing procedure to complete successfully
Select your (router) WiFi network and press "back button" to start the connection test
Check out the video tutorial below!
Video tutorial of Step 4
Important notes
ESP32 operates in two WiFi modes: AP (access point - used for pairing) and STA (stationary - used for normal operation)
After first pairing, ESP32 stores the pairing data into its EEPROM and always boots to STA mode when powered on
To clear the pairing data and boot to AP mode, send the following command to ESP32 over the serial port: "!CLEAR_PARAMS\r\n" (see "serialInputHandler()" method in "program_base.cpp" source)
Implement custom handling of GUI-O messages within "mqttReceiveCallback(...)" method in "program_sta.cpp" source
ESP32 & Arduino & GUI-O IoT push notifications
NOTE: This is not a standard way of implementing push notifications! It only works in IoT mode and does not deliver messages if the mobile device is offline, unless MQTT broker supports this and messages are published with quality of service level 1 or 2. If you require a reliable delivery in any communication mode, see push notifications.
IoT push notifications support can simply be added to any of the examples above. IoT push notifications are used to notify the user about some urgent event. For more information regarding push notifications in GUI-O application, see IoT push notifications section in the manual. Also note that the IoT push notifications can be used even if the GUI-O application is not running.
Note that push notifications feature works in the same way as regular IoT messages - if you migrate to your own MQTT broker, no additional setup is required.
Before continuing, it is recommended to try the ESP32 MQTT (IoT) example, since it is used as a reference for this example. Then follow the steps below:
Open GUI-O application settings and navigate to "Info" menu
Make a note of "Application UUID" (you can share the "Application UUID" by clicking on it)
Download Basic_MQTT_push_notification.ino sketch and open it
Use "Application UUID" (from 2.) for the Push topic (keep the /notifications part!)
IMPORTANT NOTE: Don't forget to also generate and set the Out and In topics - see ESP32 MQTT (IoT) example!
Upload the code to ESP32
In GUI-O application settings, navigate to "Quick pair" and press "Connect"
Wait for successful IoT connection and press the GUI-O initialize button from the home screen
Press the Push notification button
Important notes
The "Application UUID" changes if the application is re-installed, or if the application data is deleted. Updating the application does not change the "Application UUID".
In idle mode, the foreground service consumes minor amounts of data. The user is notified about the approximate data usage, when this feature is enabled.
In certain conditions (e.g., low memory), the service can be killed by the host operating system. It is therefore necessary to disable any battery (and similar) optimizations and also enable the "Autostart" feature (if applicable). For reference, see https://dontkillmyapp.com. When the notification feature is enabled, the user is presented with an option to directly open the GUI-O application settings and disable any such optimizations. See the example images of GUI-O application settings menu below.
Application settings
Application settings -> Other permissions
Application settings -> Battery saver
ESP32 & Arduino & GUI-O live image stream (using OV2640 camera)
GUI-O application supports streaming arbitrary grayscale (1 byte per pixel), color (3 bytes per pixel) and jpeg (compressed) images in IoT and Local WiFi mode. The images are packed in a binary format in order to optimize the data transmission.
The images can originate from various sources (e.g., live camera image, SD card image, etc.), but before sending the image, it must be formatted in such a way that it can be correctly parsed by the GUI-O application. For more information, see the "Image stream" widget description in the manual and check out the example below using ESP32-S with OV2640 camera.
ESP32 MQTT live image stream
Before continuing, it is recommended to try the ESP32 MQTT (IoT) example, since it is used as a reference for this example (note that the same Out and In topics can also be used here). Then follow the steps below:
Download BasicMQTT_live_image_stream_jpeg.zip (for jpeg stream) or BasicMQTT_live_image_stream.zip (for grayscale stream) archive and extract it
Open Arduino IDE and load .ino file from the extracted archive
Navigate to "Tools -> Board -> ESP32 Arduino" and select your board (this example uses AI Thinker ESP32-CAM board; also select your camera model within the sketch, if using another board)
Set your router name / password and unique client id
IMPORTANT NOTE: Don't forget to also generate and set the Out and In topics - see ESP32 MQTT (IoT) example!
Upload the code to ESP32 (FTDI programmer can be used for this; note that the GPIO0 pin must be connected to GND during upload)
Open GUI-O and tap "Connect" from top-left corner of the home screen
Select your device and wait for successful IoT connection
Connect . Create . Control
