ESPecial

This project aim to provide an easy way to control your esp32. You no longer need programming skills to set complex tasks. This can be a very nice approach for small projects, home automation and/or educational purposes.

Here is a quick video exemple of what you can do with ESPecial: https://youtu.be/_E-ywkafs94

The event driven web interface: https://youtu.be/yFqBmNJR02w

An exemple of how you can set the interface to control servo motors with a potentiometer: https://youtu.be/_ucSs9OT7Eg

Features:

• [x] Automation: program actions that can be triggered via many different channels (api, mqtt, telegram bot or simply by pins events), without having to code. Control pins value (digital/ledControl/analog/I2C/touchControl support/ADC/DAC), send telegram message, send http requests etc. No need to update the firmware, everything is dynamic.

• [x] ESP-CAM support: stream video directly in the interface. Program an automation to send picture via telegram.

• [x] REST API: Exposes gpio and automations logic. Set pin digital/analog value, mode (input/output), frequence, resolution, if you want to store its state in flash. Trigger automations. Scan I2C addresses, send I2C commands.

• [x] Event driven Web interface: full vanilla js. No internet connexion required. Pins mode, actions, conditions, telegram, everything can be set via the interface. You don't need to refresh the page to get pins state update.

<div> <img src="images/sample-home.png" width="200"> <img src="images/edit-gpio-panel.png" width="200"> <img src="images/add-automation-panel.png" width="200"> <img src="images/settings.png" width="200"> </div>

• [x] Telegram bot: Access and control your esp32 from outside your home. No domotic server required! No port exposed to the outside world (way more secure than exposing your router ports). Restrict the access with a user authorised list.

<div> <img src="images/telegram.png" width="200"> </div>

• [x] Mqtt client: publish/subscribe pin state, actions.

• [x] Wifi: Setting up ESPecial to your local network is easy: at first ESPecial will set a WIFI network in AP mode allowing you to access all features and set your esp32 to your local.

• [x] Easy installation via ESPInstaller: No dependencies or extra tools to install.

• [x] OTA: Update firmware from the web interface. Get notifiy when a new version is available from github and install it directly from it.

• [ ] Plateform.io/Makefile/bash script: simplify the installation process.

• [ ] Compatibility with single cored boards.

Work in progress:

Have a look to this page to track current work.

Getting Started

First, do yourself a nice gift, buy an ESP32 :) Any esp32 will work with this project.

If your board uses a usb-c type port, you should be able to detect your board by installing this driver: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers

Prerequisites

Before installing anything you'll need your esp32 to be ready. This involve having installed an additional Arduino board manager. The process is quite easy and can be found in the following link: https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md

If you want to use vscode while coding (I strongly recommand it) follow this nice tutorial: https://medium.com/home-wireless/use-visual-studio-code-for-arduino-2d0cf4c1760b

Installing

Easy way

You'll need this project installed on your esp32. This is a very lightweight project that will enable you to install any project from their github repo if the owner has enabled it. The good thing is that you don't need to install any dependencies or anything to get that project on your esp32. Just make sure to select the right partition scheme when installing ESPInstaller: Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS Once ESPInstaller installed, select the ESPecial from the list of available repo and click install. This will install everything automatically 👌

Manual way

First copy this repo to your local directory. Use the download as zip or git clone method. Then 5 dependencies need to be added to your Arduino libraries (when you download these dependencies, make sure to remove the '-master' part of the folder name):

• ArduinoJSON v6 (install via library manager) Handle json in a very effective way.
• PubSubClient: (install via library manager) MQTT handling. It's a very robust pubsub client, perfect for iot projects.
• UniversalTelegramBot: Last version to be tested is 1.3. So if you encounter issues, make sure to have that one installed in your library. You can find the zip file here on the official repo.
• ESPAsyncWebServer
• AsyncTCP

Once all libraries installed, upload the scetch to your board. Make sure to select `Minimal SPIFFS (1.9MB APP with OTA/190KB SPIFFS) in Tools>Partition scheme

We now need to upload webserver files to the SPIFF partition, simply follow this guide and then click on tools>ESP Scketch data upload

Usage

Wifi connection

You should first connect your esp32 to your local network. Simply power on your device, and connect to the access point (AP) call ESP32 with the password p@ssword2000 on your computer wifi setup. Once connected, you can access the esp32 web interface in your favorite browser by entering the address http://especial.local. All esp32 features can be access in AP mode (except for the Telegram part of course). But it's better if you connect your esp32 to your local network. Go in the setting page of ESPecial web page, and switch on the Station Mode (STA) in the wifi section. Here simply set your wifi network SSID and password. You can also rename the DNS name of the esp32.

Web interface

The interface is responsive and should be usable on your smartphone. It should look like this:

<p align="center"> <img src="images/initial-home-page.png" width="400"> </p> You now need to add your first pin handler. This is done by simply clicking on the 'plus' button in the top right corner. <p align="center"> <img src="images/add-gpio-panel.png" width="400"> </p> Choose the pin you want to control/listen from the list. This list will only display available pins, so you won't have doublons 👌. You can switch from INPUT modes, to OUTPUT, LedControl, Analog, I2C, ADC and DAC. Depending on which mode you choose, parameters may appears. Like frequencies, resolutions, address etc. When selecting the I2C mode, you be able to scan and detect any slave device. The 'save state' checkbox will allow you to save a state in the flash memory of the controller, allowing you to get back your state even after a reboot. This is available for digital output and LedControl mode. Once you are done with the settings, press 'save' to add the new GPIO. A new line should appear: <p align="center"> <img src="images/gpios-new-line.png" width="400"> </p> You can now control the state of your pin by pressing the 'on/off' button if its mode is set to OUTPUT. If its mode is set to INPUT, it will only display its value. On LedControl mode, you'll be able to set/get the pulse value. <br>

Automation!

And now the best part: set actions that will triggered based on gpios state or telegram/mqtt/api events! This will give you infinite possibilities for controlling your esp32, without having to code or download new firmware.

Click on the plus sign on the top right corner of the automation container. This panel should appear:

<p align="center"> <img src="images/initial-automation-panel.png" width="400"> </p> Here, you'll be able to set conditions based on gpios value. I'm sure there are tons of other possible types, but for now this is enough to cover a lot of use cases. Automations are based on conditions. Keep in mind that in order to run, all conditions have to be true. You can add up to 5 conditions per automations. This is to limit heap memory consumption. Each condition can be linked to the previous one by AND/OR/XOR logic operators. If a condition has "none" operator defined, the next condition will be ignored. For now, you have two types of conditions:

• Gpio value: the main loop will check for gpios change value every 50ms. If a gpio state has changed, the process will check all conditions of all event driven automations. When all conditions are fullfilled for a given automation, it will run it.
• Time: The main loop will also check all conditions of all event driven automations every minute. You can set time conditions based on hours or weekday. It's important you set the right time condition. For instance, if you want to run only once an automation at a certain time, set the time condition to be "equal", otherwise the time checking loop will run your automation every minute.

Now we can set our first action. Simply click the add button in the action editor section. You can choose between three types of actions:

• Set gpio value/pulse
• Send telegram message (and image if you have an ESP-CAM board)
• Send http/https request.
• Automation: run another automation you have already set. This means you can nest an infinite number of automations! Each automation will check its conditions before running.
• Delay: note that this delay is an actual 'delay' function. Meaning that you'll block the process. Yes, automations run