HomeESP is a simple home automation solution for the ESP8266, which allows you to monitor, control and configure compatible devices through a user friendly dashboard.
HomeESP requires the following libraries to be installed:
- ESPHelper (Make sure to use my fork, as the original is not compatible with newer versions of ArduinoJSON)
- Metro
- Pubsubclient
- ArduinoJson 6.x
HomeESP also makes use of the following libraries for the sensors and RF transmitter:
In addition to those libraries, make sure that you have the ESP core files installed aswell:
Download and install an MQTT broker that supports websocket connections, such as mosquitto or hiveMQ.
Create login credentials for both yourself (Which will be used to login to the dashboard) and your devices.
Enable websockets in your broker configuration, as this is required for the dashboard to connect to the broker.
NOTE: If you deploy the dashboard on an HTTPS server you must also use websockets with SSL, this means your MQTT broker needs an SSL certificate and be configured accordingly.
More info on how to install and setup your MQTT server can be found on their respective websites:
Click the green download button above, next click "Download ZIP".
Installation for use on local machine:
Unzip the downloaded file and place the 'Dashboard' folder on your device, next open the index.html file inside to start.
Installation for web deployment:
Unzip the downloaded file and place the contents of the dashboard folder in the root of your webserver, next simply navigate to your IP address or domain.
Connect all components to the ESP board. You can use this webpage as a pinout reference for your specific ESP board.
| Name | Type | Connected to GPIO |
|---|---|---|
| DHT11/DHT22 | Temperature and humidity sensor (Input) | 14 |
| BH1750 | Light intensity sensor (Input) | 4 & 5 (I2C) |
| Button | Input | 13 |
| RF Transmitter | Output | 2 |
| LED | Output | 12 |
Example with D1 Mini:
Connect the ESP board to your computer.
Open the ESP8266 folder, and open the HomeESP.ino file inside with the Arduino IDE.
Make sure you have all of the required libraries, and the ESP8266 Arduino Core installed.
Select the correct board variant from Arduino IDE -> Tools -> Board.
Click Upload.
Once the upload is complete, press the button that is connected to GPIO 13 of the device. The device will now enter a broadcast mode, which allows you to connect to your device directly via wifi. Look for any open network with the name "HomeESP" followed by 4 random numbers, and connect to it.
Next, open your webbrowser and navigate to the device configuration page: http://192.168.1.1/config.
Lastly, enter the desired hostname, network info and MQTT broker logindetails for your device and click save.
Your device should now automatically restart, and connect to your network and MQTT broker.
Open the dashboard and enter the login details that you created in step 1.
Enter the hostname of your broker and the websocket port that you configured in step 1 and click login.
Once you succesfully login you should be greeted with the discovery tool, this allows you to quickly add any devices that are currently connected to the MQTT broker, if your device does not show up right away you can press the green refresh button.
Next, simply select all of the devices that you would like to add and click 'Add selected devices'.
The HomeESP dashboard and devices use the MQTT protocol (A lightweight publish/subscribe protocol) to communicate with one another. MQTT clients communicate by subscribing and publishing messages to specific topics, which may also contain a payload. All topics used by HomeESP are laid out in the table below.
| Topic | Description | Payload Type | Example Payload |
|---|---|---|---|
| home-esp/discover | Request all Home-ESP devices to respond on callback topic | ||
| home-esp/discover/callback | Contains device name | string | "Livingroom" |
| <device>/status | Connection status of the device with the MQTT broker | ||
| <device>/restart | Restart the node | ||
| <device>/uptime | Device uptime [s] | string <int> | 806 |
| <device>/config | A JSON object containing the configuration parameters of the device: • tempMin • tempMax • hmdtyMin • hmdtyMax • lightsensMin • lightsensMax • sensors • actuators • kakuAddress • kakuUnits |
JSON string | |
| <device>/config/set | Set the configuration parameters of the device (see above) | JSON string | |
| <device>/config/get | Request the device configuration parameters (see above) | ||
| <device>/params/get | Request the following parameters from the device: • <device>/temp • <device>/hmdty • <device>/lightsens • <device>/light • <device>/kaku/<unit> (of all units) |
||
| <device>/temp | Latest temperature measurement [°C] | string <float> | 22.30 |
| <device>/hmdty | Latest humidity measurement [%] | string <float> | 50.90 |
| <device>/lightsens | Latest light intensity measurement [lux] | string <float> | 324.29 |
| <device>/light | Current state of the light ["on"/"off"] | string | "on" |
| <device>/light/toggle | Toggle the state of the light | ||
| <device>/kaku/<unit> | Current state of the specified unit ["on"/"off"] | string | "off" |
| <device>/kaku/<unit>/toggle | Toggle the state of the specified kaku unit |