Native API Component

# Example configuration entry
  password: 'MyPassword'

Configuration variables:

  • port (Optional, integer): The port to run the API Server on. Defaults to 6053.
  • password (Optional, string): The password to protect the API Server with. Defaults to no password.
  • reboot_timeout (Optional, time): The amount of time to wait before rebooting when no client connects to the API. This is needed because sometimes the low level ESP functions report that the ESP is connected to the network, when in fact it is not - only a full reboot fixes it. Can be disabled by setting this to 0s. Defaults to 5min.
  • id (Optional, ID): Manually specify the ID used for code generation.

Migrating from MQTT to Native API Setup in Home Assistant

The native API is the best way to use esphomelib together with Home Assistant - it’s fast, highly efficient and requires almost zero setup (whereas MQTT requires you to set up an MQTT broker first).

If you’ve previously used esphomelib with Home Assistant via MQTT and have enabled MQTT discovery, the upgrade process is unfortunately not just swapping out the mqtt for api in your configuration: Home Assistant’s entity registry complicates things a bit. If you don’t follow these steps, all your new native API entities will have a trailing _2 at the end of the entity ID.

You can repeat these steps for all your nodes, or convert them over to the new native API one by one.

  1. Disable MQTT discovery on ESP side. In your ESPHome configuration, set a special “clean” discovery flag:
# In your ESPHome configuration! Not HA config!
  # Other settings ...
  discovery: clean
  1. Compile and upload this new firmware. All entities should now be gone from Home Assistant.

  2. Go to your Home Assistant configuration folder and go to the .storage folder (might be hidden depending on your operating system). In there you will find a file called core.entity_registry - open the file with a text editor and paste the contents below

  3. Stop Home Assistant - this is necessary for the entity registry changes not to become overriden.

  4. Convert the Entity Registry file above using the “Convert Entity Registry Button”, and override the .storage/core.entity_registry file with the new contents.

  5. Start Home Assistant.

  6. Now you can enable the ESPHome native API (and upload the new firmware)

# Example configuration entry
  1. In Home Assistant, go to “Configuration” -> “Integrations” - if you’ve set up the discovery: component, you’ll already see the ESP as a suggestion to be configured. But if you’re having issues with that, you can always manually set up an ESPHome device using “Set up a new integration” -> “ESPHome”.
  2. Now you can remove mqtt: from your ESPHome configuration. You don’t have to, but doing so will free up resources (of which these ESPs don’t have too much).


Using MQTT together with the native API seems to be broken on some devices at the moment. Of course in the future you will be able to use both at the same time, but the fix will just take a while to get done as it’s a larger scale issue.

homeassistant.service Action

When using the native API with Home Assistant, you can create Home Assistant service calls straight from ESPHome Automations.

# In some trigger
  # Simple
  - homeassistant.service:
      service: notify.html5
        title: Button was pressed
  # With templates and variables
  - homeassistant.service:
      service: notify.html5
        title: New Humidity
        message: The humidity is {{ my_variable }}%.
        my_variable: |-
          return id(my_sensor).state;

Configuration options:

  • service (Required, string): The Home Assistant Service to call.
  • data (Optional, mapping): Optional static data to pass along with the service call.
  • data_template (Optional, mapping): Optional template data to pass along with the service call. This is evaluated on the Home Assistant side with Home Assistant’s templating engine.
  • variables (Optional, mapping): Optional variables that can be used in the data_template. Values are lambdas and will be evaluated before sending the request.