ESP Home Documentation

Getting Started

At a Glance

enter image description here

  • Web Server in IoT device simply replies to commands that you send from JavaScript files to return status or take controlling actions.
  • JavaScript files are the core of the whole system.
  • Page Configs are definition of sections and rows to be displayed in mobile app. You have direct control over what to show from JavaScript Files.
  • Data Files are small data objects that you might need to save for each device. I usually use them to save and load scheduled programmings. It’s an alternative to use EEPROM memory of the device which is not very efficient.
  • Selected Device in Mobile App is the current selected device that is running the JavaScript Files and interact with almost all of the parts in ESPHome Server.


To start using ESP Home, you need to setup the device and make sure it can be controlled using HTTP connections. Usually I make an HTTP server that can response to commands and return results in JSON format. Something like a REST based API. Make sure you can get status of the current state of the device and ability to make changes to the current state.
Next step is to signup for a free ESP Home account and start codding.

Your first device

After signup, browse to user area and you will find the Sample Device that created for you. Check all the areas and feel free to experiment.


Now install and open ESPHome on your mobile device. Login with your account and you will see the Sample Device.
Note: If you make any changes to the devices or files on site, you need to pull down the list of devices to refresh changes.
Tap on the Sample Device to see the results.

JavaScript Basics

As you can see, a default JavaScript file is created for device. That’s the main JavaScript file that will be run when you open the device on App. This file contains a function named ESP_MAIN(), that’s the entry point for your application. Setup everything from this function. Sample Device can give you some idea of what you can do and how to communicate with App on device.

Communicate with real device

Device should be connected to internet. On Arduino platforms you can use an ESP8266, setup a web server and response to API commands. In JavaScript you can connect to the device using its address and ESP.httpGET or ESP.httpPOST functions. Here is an example:

	'success': function(result){
		var status = JSON.parse(result);

This example connects to a device located at and ask for status. Assumes that device send out the status in JSON format and current state of the device is in ‘on_or_off’ field. Then updates value of the ‘status_row’ row on app.