EXAMPLES

The following tutorials show how to use GUI-O application with ESP32, ESP8266 and HM-10 boards in various configuration and communication modes (also supporting push notifications). Tutorial for automatic device pairing also shows how to include SSL/TLS for secure IoT connection.

The same principle of operation can be applied to any other board or device - check out how GUI-O works.

To see more examples, check our tutorial series.


NOTE: In case of any problems, please make sure to update GUI-O application to the latest version.

ESP32 & Arduino basic examples

The following examples show basic interaction between GUI-O application and ESP32 module in various communication modes.

ESP32 Bluetooth

  1. Download BasicBluetooth.ino sketch

  2. Follow Basic Bluetooth video tutorial

  3. Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

ESP32 Bluetooth LE

  1. Download BasicBLE.ino sketch (or BasicBLE_NUS.ino for Nordic UART service)

  2. Follow Basic BLE video tutorial

  3. Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

ESP32 MQTT (supports SSL/TLS)

  1. Download BasicMQTT.ino sketch or BasicMQTT_SSL_TLS.ino sketch for secure (encrypted) communication

  2. Follow Basic MQTT video tutorial

  3. Additional Boards Manager URLs: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

ESP32 USB

  1. Download BasicUSB.ino sketch

  2. Follow Basic USB video tutorial

  3. 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 figure). Also note that not all Android devices support USB OTG functionality.

USB OTG adapter connected to ESP32

ESP32 Ethernet

  1. Download BasicEthernet.ino sketch

  2. Follow Basic Ethernet video tutorial

  3. 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

  1. Download Arduino IDE

  2. Download ESP32_GUI-O_pairing_libs.zip and extract the archive

  3. 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

  1. Open Arduino IDE

  2. Select "File -> Preferences" and under Additional Boards Manager URLs enter: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

  3. Select "Tools -> Board -> Boards manager..."

  4. Search and install "esp32" by Espressif Systems

  5. After installation select "Tools -> Board -> ESP32 Arduino -> ESP32 Dev Module"

Step 2: Include necessary libraries

  1. Select "Sketch -> Include library -> Add .ZIP library..."

  2. Navigate to location, where ESP32_GUI-O_pairing_libs.zip archive was extracted

  3. Select .zip library and confirm (repeat procedure until all .zip libraries are included)

Step 3: Upload the code

  1. Select "File -> Open"

  2. Navigate to location, where ESP32_GUI-O_pairing_source.zip archive was extracted

  3. Select PairingMQTT.ino and confirm

  4. Make sure that ESP32 board is connected to your PC

  5. Make sure that the correct port is selected

  6. Press upload button to start code upload (IMPORTANT NOTE: on some ESP32 boards, the BOOT button must be pressed when the upload starts)

  7. 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.


  1. Open GUI-O application and navigate to settings

  2. Make sure that IoT connection is active (select "Connections -> IoT")

  3. From main settings menu select "Quick pair -> Direct device pairing"

  4. Name your ESP32 device (setting your user name is optional) and confirm

  5. Wait while surrounding WiFi networks are scanned then select your (router) WiFi network and input your password

  6. Put the ESP32 device into pairing mode then search and connect to guio_ device (input password 12345678 when prompted)

  7. IMPORTANT NOTE: Do not switch network if prompted by Android (keep connection to guio_ device)

  8. Press "back button" and wait for pairing procedure to complete successfully

  9. 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 push notifications

Push notifications support can simply be added to any of the examples above. Usually, 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 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:

  1. Open GUI-O application settings and navigate to "Info" menu

  2. Make a note of "Application UUID" (you can share the "Application UUID" by clicking on it)

  3. Download Basic_MQTT_push_notification.ino sketch and open it

  4. Use "Application UUID" (from 2.) for the Push topic (keep the /notifications part!)

  5. IMPORTANT NOTE: Don't forget to also generate and set the Out and In topics - see ESP32 MQTT (IoT) example!

  6. Upload the code to ESP32

  7. In GUI-O application settings, navigate to "Quick pair" and press "Connect"

  8. Wait for successful IoT connection and press the GUI-O initialize button from the home screen

  9. 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.

App settings

Application settings

App settings -> Other permissions

Application settings -> Other permissions

App settings -> Battery saver

Application settings -> Battery saver

ESP32 & Arduino 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 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.

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:

  1. Download BasicMQTT_live_image_stream_jpeg.zip (for jpeg stream) or BasicMQTT_live_image_stream.zip (for grayscale stream) archive and extract it

  2. Open Arduino IDE and load .ino file from the extracted archive

  3. 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)

  4. Set your router name / password and unique client id

  5. IMPORTANT NOTE: Don't forget to also generate and set the Out and In topics - see ESP32 MQTT (IoT) example!

  6. Upload the code to ESP32 (FTDI programmer can be used for this; note that the GPIO0 pin must be connected to GND during upload)

  7. In GUI-O application settings, navigate to "Quick pair" and press "Connect"

  8. Wait for successful IoT connection and press the GUI-O initialize button from the home screen

Quick test of GUI-O live image stream

Proof of concept of live image stream using a simple Python script. Download the script and try it yourself. Follow the steps below:

  1. In GUI-O application settings, navigate to "Quick pair -> IoT devices" and create a new device

  2. Note the "In" topic of the created device!

  3. Navigate to "Quick pair", press "Connect" and return to GUI-O home screen

  4. Open the Python script and make sure that all imported modules are installed (paho-mqtt and opencv-python)

  5. Set the "pubTopic" variable in the Python script to the "In" topic of the created device

  6. IMPORTANT NOTE: Make sure that the device running the Python script has a camera (e.g., laptop webcam)

  7. Run the Python script (to stream color image instead of grayscale, enable the "useColor" variable within the script)

ESP8266 & Arduino & GUI-O automatic pairing

The following example shows how to automatically pair GUI-O application with ESP8266 in MQTT (IoT) mode. Although the example uses ESP8266 Wemos D1 R1, it should be compatible with any other ESP8266 board.

The procedure is in principle identical to the ESP32 pairing (check the video tutorials under the ESP32 pairing section for additional information). There are some slight differences between ESP32 and ESP8266 pairing procedure - notably when setting up the board and required libraries. Step-by-step procedure is described in the sections below.

VERY IMPORTANT NOTE: The ESP8266 board acts as a bridge. All commands received from the MQTT broker are transmitted over the ESP8266 serial port (Tx). Analogously, all commands that need to be sent to the MQTT broker must be transmitted over the ESP8266 serial port (Rx). This requires an external microcontroller to handle the incoming commands (sent by the GUI-O application) and outgoing commands (received by the GUI-O application).

After programming the ESP8266 with the pairing code, it can be used, for example, to replace an existing USB Serial Bluetooth module to achieve WiFi connectivity. Furthermore, since the ESP8266 works as a standalone board that communicates with the GUI-O application, it can also be used in any other non-Arduino projects.

Prerequisites

  1. Download Arduino IDE

  2. Download ESP8266_GUI-O_pairing_libs.zip and extract the archive

  3. Download ESP8266_GUI-O_pairing_source.zip and extract the archive

Step 1: Add ESP8266 board support

  1. Open Arduino IDE

  2. Select "File -> Preferences" and under Additional Boards Manager URLs enter: https://arduino.esp8266.com/stable/package_esp8266com_index.json

  3. Select "Tools -> Board -> Boards manager..."

  4. Search and install "esp8266" by ESP8266 Community

  5. After installation select "Tools -> Board -> ESP8266 Boards -> Wemos D1 R1" (if you choose a different board, you might need to adjust the program settings in "config.h" header within the extracted ESP8266_GUI-O_pairing_source folder)

Step 2: Include necessary libraries

  1. Select "Sketch -> Include library -> Add .ZIP library..."

  2. Navigate to location, where ESP8266_GUI-O_pairing_libs.zip archive was extracted

  3. Select .zip library and confirm (repeat procedure until all .zip libraries are included)

Step 3: Upload the code

  1. Select "File -> Open"

  2. Navigate to location, where ESP8266_GUI-O_pairing_source.zip archive was extracted

  3. Select PairingMQTT.ino and confirm

  4. IMPORTANT NOTE: ESP8266 can output debug messages during operation - to enable this feature, open the "config.h" header and uncomment "#define _GUIO_DEBUG"

  5. Make sure that ESP8266 board is connected to your PC

  6. Make sure that the correct port is selected

  7. Press upload button to start code upload (IMPORTANT NOTE: on some ESP8266 boards, the GPIO0 pin must be held to GND during the board reset, which enables code upload)

  8. Reset ESP8266 board after code upload

Step 4: Pair GUI-O application with ESP8266 board

The pairing procedure is fully guided within GUI-O application. The important parts are described below.


  1. Open GUI-O application and navigate to settings

  2. Make sure that IoT connection is active (select "Connections -> IoT")

  3. From main settings menu select "Quick pair -> Direct device pairing"

  4. Name your ESP8266 device (setting your user name is optional) and confirm

  5. Wait while surrounding WiFi networks are scanned then select your (router) WiFi network and input your password

  6. Put the ESP8266 device into pairing mode then search and connect to guio_ device (input password 12345678 when prompted)

  7. IMPORTANT NOTE: Do not switch network if prompted by Android (keep connection to guio_ device)

  8. Press "back button" and wait for pairing procedure to complete successfully

  9. Select your (router) WiFi network and press "back button" to start the connection test

Important notes

  • ESP8266 operates in two WiFi modes: AP (access point - used for pairing) and STA (stationary - used for normal operation)

  • After first pairing, ESP8266 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 ESP8266 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

HM-10 BLE & Arduino

The following example shows how to connect GUI-O application with HM-10 Bluetooth Low Energy (BLE) module. Arduino Uno is used as an intermediary between the HM-10 and PC serial terminal.

Prerequisites

  1. Download Arduino IDE

  2. Download BLE_HM-10.ino sketch

Step 1: Connect the components

Connect the components as shown in the schematic below. Note that the Arduino Uno transmit pin (pin "D3") uses a voltage divider to reduce 5V to roughly 3.3V.

Step 2: Upload the code

  1. Open Arduino IDE

  2. Select "File -> Open"

  3. Navigate to location, where BLE_HM-10.ino sketch was downloaded

  4. Select BLE_HM-10.ino and confirm

  5. Make sure that Arduino Uno board is selected and connected to your PC

  6. Make sure the correct port is selected

  7. Press upload button to start code upload

Step 3: Connect GUI-O application with HM-10

  1. Open GUI-O application, navigate to settings and select "Connections -> Bluetooth LE"

  2. Search for BLE devices (enable Bluetooth and Location services, if prompted)

  3. Select HM-10 module (named HMSoft or similar)

  4. Wait for successful connection

  5. Open any serial terminal on PC (e.g., Arduino Serial Monitor)

  6. Press the GUI-O initialize button and observe the result on serial terminal on PC

  7. Send any valid command (see example below) via serial terminal on PC and observe the result in GUI-O application

EXAMPLE COMMAND: "|TG UID:toggle X:50 Y:50" (omitting the quotes). Make sure all commands are terminated by carriage return (\r) and line feed (\n). See the GUI-O manual for all supported commands.

Important notes

  • HM-10 module has its own internal status handling and sends OK+CONN (when connection is established) or OK+LOST (when connection is lost. These messages are not terminated by carriage return (\r) or line feed (\n), so this can possibly interfere with GUI-O protocol. It is therefore recommended to parse all messages by the GUI-O specific character ('@'). Character '@' is always prepended to any GUI-O protocol message.

Connect . Create . Control

Connect . Create . Control

YouTube channel
Facebook