ESPHome

https://esphome.io/
Admin
ESPHome is an open-source firmware framework that simplifies creating custom smart home devices for...
Tokens:933,043
Snippets:11,481
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Full Configuration Example

Source: https://esphome.io/components/time/rx8130

Example demonstrating a typical setup with an external time source and the RX8130.

```APIDOC
## Full Configuration Example

### Description

In a typical setup, you will have at least one additional time source to synchronize the RTC with. This example shows how to read the RTC on boot and synchronize with an external source, updating the RTC upon successful synchronization.

### Configuration

```yaml
esphome:
  on_boot:
    then:
      # read the RTC time once when the system boots
      rx8130.read_time:

time:
  - platform: rx8130
    # repeated synchronization is not necessary unless the external RTC
    # is much more accurate than the internal clock
    update_interval: never
    timezone: Europe/Paris
  - platform: homeassistant
    # instead try to synchronize via network repeatedly ...
    on_time_sync:
      then:
        # ... and update the RTC when the synchronization was successful
        rx8130.write_time:
```
```

--------------------------------

### Full Configuration Example

Source: https://esphome.io/components/time/ds1307

Example of a typical setup involving DS1307 and an external time source.

```APIDOC
## Full Configuration Example

### Description
In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an external time source might not always be available e.g. due to a limited network connection. In order to have a valid, reliable system time, the system should read the RTC once at start and then try to synchronize with an external reliable time source. When a synchronization to another time source was successful, the RTC can be resynchronized.

### Method
Configuration

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```yaml
esphome:
  on_boot:
    then:
      # read the RTC time once when the system boots
      ds1307.read_time:


time:
  - platform: ds1307
    # repeated synchronization is not necessary unless the external RTC
    # is much more accurate than the internal clock
    update_interval: never
  - platform: homeassistant
    # instead try to synchronize via network repeatedly ...
    on_time_sync:
      then:
        # ... and update the RTC when the synchronization was successful
        ds1307.write_time:
```

### Response
N/A

#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### Full Micronova configuration example

Source: https://esphome.io/components/micronova

Comprehensive example demonstrating UART setup, Micronova integration, and various sensors, switches, and number controls.

```yaml
uart:
  - id: micronova_port
    rx_pin: GPIOXX
    tx_pin: GPIOXX
    baud_rate: 1200
    data_bits: 8
    parity: NONE
    stop_bits: 2


micronova:
  enable_rx_pin: GPIOxx
  uart_id: micronova_port


text_sensor:
  - platform: micronova
    stove_state:
      name: Stove status


number:
  - platform: micronova
    thermostat_temperature:
      name: Thermostat temperature
    power_level:
      name: Power level


switch:
  - platform: micronova
    stove:
      name: Stove on-off switch


sensor:
  - platform: micronova
    room_temperature:
      name: Room temperature
    fumes_temperature:
      name: Fumes temperature
    stove_power:
      name: Stove power level
    fan_speed:
      fan_rpm_offset: 240
      name: Fan RPM
```

--------------------------------

### Full Configuration Example with Time Synchronization

Source: https://esphome.io/components/time/pcf8563

Example demonstrating a typical setup with a PCF8563 RTC and an external time source (Home Assistant). It reads the RTC on boot and resynchronizes the RTC when network synchronization is successful.

```yaml
esphome:
  on_boot:
    then:
      # read the RTC time once when the system boots
      pcf8563.read_time:


time:
  - platform: pcf8563
    # repeated synchronization is not necessary unless the external RTC
    # is much more accurate than the internal clock
    update_interval: never
  - platform: homeassistant
    # instead try to synchronize via network repeatedly ...
    on_time_sync:
      then:
        # ... and update the RTC when the synchronization was successful
        pcf8563.write_time:
```

--------------------------------

### Example flex layout configuration

Source: https://esphome.io/components/lvgl/layouts

Demonstrates a basic flex layout setup with padding, alignment settings, and a child widget using flex_grow.

```yaml

# Example flex layout


- obj:
    layout:
      type: flex
      pad_row: 4
      pad_column: 4px
      flex_align_main: center
      flex_align_cross: start
      flex_align_track: end
    widgets:
      - animimg:
          flex_grow: 1
```

--------------------------------

### Test Setup with Home Assistant

Source: https://esphome.io/components/hlk_fm22x

Example of how to set up and test the HLK-FM22x module using Home Assistant's developer tools.

```APIDOC
## Test setup

### Description
This section provides an example of how to quickly set up a node and use Home Assistant's action calling feature for testing the HLK-FM22x module.

### Example Usage
To call the `hlk_fm22x.enroll` action:
1. In Home Assistant's developer tools, select the action `esphome.test_node_enroll`.
2. In the action data field, enter the following JSON:
   ```json
   { "name": "My name", "direction": 1 }
   ```
```

--------------------------------

### Configuration Examples

Source: https://esphome.io/components/display/hub75

Various configuration examples for HUB75 displays, including single panel, chained panels, manual pin configuration, and advanced shift driver setup.

```APIDOC
## Configuration Examples

### Basic Single Panel (with Board Preset)

```yaml
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    lambda: |-
      it.print(0, 0, id(font), "Hello!");
```

### Horizontally Chained Panels

```yaml
# Three 64x32 panels chained horizontally = 192x32 total
display:
  - platform: hub75
    id: matrix_display
    board: apollo-automation-m1-rev4
    panel_width: 64
    panel_height: 32
    layout_cols: 3
    layout: HORIZONTAL
    lambda: |-
      it.printf(0, 0, id(font), "Width: %d", it.get_width());
```

### Manual Pin Configuration

```yaml
# Using custom pins without a board preset
display:
  - platform: hub75
    id: matrix_display
    panel_width: 64
    panel_height: 32
    r1_pin: GPIO25
    g1_pin: GPIO26
    b1_pin: GPIO27
    r2_pin: GPIO21
    g2_pin: GPIO22
    b2_pin: GPIO32
    a_pin: GPIO23
    b_pin: GPIO19
    c_pin: GPIO5
    d_pin: GPIO17
    e_pin: GPIO18  # Required for 1/32 scan panels
    lat_pin: GPIO4
    oe_pin: GPIO15
    clk_pin: GPIO16
```

### Advanced Configuration with Shift Driver

```yaml
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    shift_driver: FM6126A
    clock_speed: 20MHZ
    brightness: 200
    bit_depth: 10
    latch_blanking: 2
    lambda: |-
      it.fill(Color(255, 0, 0));  # Red background
```

### 2×2 Grid Layout

```yaml
# Four 64x32 panels in a 2x2 grid = 128x64 total
display:
  - platform: hub75
    id: matrix_display
    board: adafruit-matrix-portal-s3
    panel_width: 64
    panel_height: 32
    layout_rows: 2
    layout_cols: 2
    layout: TOP_LEFT_DOWN_ZIGZAG
    lambda: |-
      it.printf(32, 28, id(font), "128x64");
```
```

--------------------------------

### Full Configuration Example

Source: https://esphome.io/components/time/bm8563

An example demonstrating how to set up the BM8563 time source in conjunction with other time sources.

```APIDOC
## Full Configuration Example

In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an external time source might not always be available e.g. due to a limited network connection. In order to have a valid, reliable system time, the system should read the RTC once at start and then try to synchronize with an external reliable time source. When a synchronization to another time source was successful, the RTC can be resynchronized.

```yaml
esphome:
  on_boot:
    then:
      # read the RTC time once when the system boots
      bm8563.read_time:


time:
  - platform: bm8563
    # repeated synchronization is not necessary unless the external RTC
    # is much more accurate than the internal clock
    update_interval: never
  - platform: homeassistant
    # instead try to synchronize via network repeatedly ...
    on_time_sync:
      then:
        # ... and update the RTC when the synchronization was successful
        bm8563.write_time:
```
```

--------------------------------

### Complete TLC59208F Setup with Multiple Drivers and Outputs

Source: https://esphome.io/components/output/tlc59208f

This example demonstrates configuring multiple TLC59208F drivers and their respective output channels. It also shows how to integrate these outputs into an RGB light component. Ensure unique IDs for each driver and output.

```yaml
# Complete example configuration entry for 3 drivers and 4 outputs
# Maximum 64 drivers with 8 outputs each
tlc59208f:
  - address: 0x20
    id: tlc59208f_1
  - address: 0x22
    id: tlc59208f_2
  - address: 0x24
    id: tlc59208f_3


# Individual outputs
output:
  - platform: tlc59208f
    id: 'tlc59208f_1_ch0'
    channel: 0
    tlc59208f_id: 'tlc59208f_1'
  - platform: tlc59208f
    id: 'tlc59208f_1_ch4'
    channel: 4
    tlc59208f_id: 'tlc59208f_1'
  - platform: tlc59208f
    id: 'tlc59208f_2_ch2'
    channel: 2
    tlc59208f_id: 'tlc59208f_2'
  - platform: tlc59208f
    id: 'tlc59208f_3_ch7'
    channel: 7
    tlc59208f_id: 'tlc59208f_3'


# Sample use as a RGB light
light:
  - platform: rgb
    name: "Sample RGB light"
    red: tlc59208f_1_ch0
    green: tlc59208f_1_ch4
    blue: tlc59208f_2_ch7
```

--------------------------------

### Setup Virtual Environment on macOS

Source: https://esphome.io/guides/installing_esphome

Create and activate a Python virtual environment before installing ESPHome via pip.

```bash
$ python3 -m venv venv      # The last argument is the folder in which to install the virtual environment
$ source venv/bin/activate  # For bash or compatible shells. If using a different shell, use activate.csh or activate.fish
(venv) $ pip install esphome       # Installs ESPHome in the virtual environment
(venv) $ esphome version
```

--------------------------------

### Test Setup for HLK-FM22x Actions

Source: https://esphome.io/components/hlk_fm22x

Example configuration for testing module actions using Home Assistant's developer tools. This snippet shows how to call the `hlk_fm22x.enroll` action with specific parameters.

```json
{ "name": "My name", "direction": 1 }

```

--------------------------------

### MQTT Component Base Configuration Example

Source: https://esphome.io/components/mqtt

Example configuration showing common MQTT overrides for a component.

```yaml
name: "Component Name"
# Optional variables:
qos: 1
retain: true
availability:
  topic: livingroom/status
  payload_available: online
  payload_not_available: offline
state_topic: livingroom/custom_state_topic
command_topic: livingroom/custom_command_topic
command_retain: false
```

--------------------------------

### Template Datetime Examples

Source: https://esphome.io/components/datetime/template

Examples of configuring template datetimes for date, time, and full datetime types. These examples demonstrate setting initial values and enabling optimistic mode and value restoration.

```yaml
datetime:
  # Example Date
  - platform: template
    id: my_datetime_date
    type: date
    name: Pick a Date
    optimistic: yes
    initial_value: "2024-01-30"
    restore_value: true


  # Example Time
  - platform: template
    id: my_datetime_time
    type: time
    name: Pick a Time
    optimistic: yes
    initial_value: "12:34:56"
    restore_value: true


  # Example DateTime
  - platform: template
    id: my_datetime
    type: datetime
    name: Pick a DateTime
    optimistic: yes
    initial_value: "2024-12-31 12:34:56"
    restore_value: true
```

--------------------------------

### Start LVGL Animations

Source: https://esphome.io/components/lvgl/animation

Demonstrates starting single or multiple animations with optional overrides for duration and loop settings.

```yaml
on_...:
  then:
    # Start a single animation by ID
    - lvgl.animation.start: slide


    # Start several, overriding some options
    - lvgl.animation.start:
        id:
          - slide
          - fade
        duration: 2s
        loop: false
```

--------------------------------

### Complete SY6970 Configuration Example

Source: https://esphome.io/components/sensor/sy6970

This is a full configuration for the SY6970 component, including I2C setup, SY6970 parameters, and sensor, text sensor, and binary sensor definitions. Ensure I2C is configured before the SY6970 component.

```yaml
i2c:
  - id: bus_a
    scan: true
    sda: GPIO5
    scl: GPIO6


sy6970:
  id: pmu
  address: 0x6A
  update_interval: 1s
  enable_status_led: true
  input_current_limit: 1000
  charge_voltage: 4200
  charge_current: 500
  precharge_current: 128
  charge_enabled: true
  enable_adc: true


sensor:
  - platform: sy6970
    sy6970_id: pmu
    vbus_voltage:
      name: "VBUS Voltage"
    battery_voltage:
      name: "Battery Voltage"
    system_voltage:
      name: "System Voltage"
    charge_current:
      name: "Charge Current"
    precharge_current:
      name: "Precharge Current"


text_sensor:
  - platform: sy6970
    sy6970_id: pmu
    bus_status:
      name: "Power Source Type"
    charge_status:
      name: "Charging Status"
    ntc_status:
      name: "Battery Temperature"


binary_sensor:
  - platform: sy6970
    sy6970_id: pmu
    charging:
      name: "Battery Charging"
    vbus_connected:
      name: "VBUS Connected"
    charge_done:
      name: "Charge Done"

```

--------------------------------

### Example Configuration Entry

Source: https://esphome.io/components/media_source/audio_http

Configure the audio_http media source with a unique ID.

```yaml
media_source:
  - platform: audio_http
    id: http_source
```

--------------------------------

### Get Fan State JSON Response

Source: https://esphome.io/web-api

Example JSON response returned when performing a GET request to /fan/<entity_name>.

```json
{
  "id": "fan/Living Room Fan",
  "state": "ON",
  "value": true,
  "speed_level": 2,
  "oscillation": false
}
```

--------------------------------

### Get Light State JSON Response

Source: https://esphome.io/web-api

Example JSON response returned when performing a GET request to /light/<entity_name>.

```json
{
  "id": "light/Living Room Lights",
  "state": "ON",
  "brightness": 255,
  "color": {
    "r": 255,
    "g": 255,
    "b": 255
  },
  "effect": "None",
  "white_value": 255
}
```

--------------------------------

### Install ESPHome via pip

Source: https://esphome.io/guides/installing_esphome

Install the necessary wheel package and ESPHome using pip.

```bash
pip3 install wheel
pip3 install esphome
```

```bash
pip3 install esphome
```

--------------------------------

### Customizing Default ESP-IDF Targets

Source: https://esphome.io/guides/esp_idf

Modify ESPHOME_IDF_DEFAULT_TARGETS to specify which ESP-IDF targets should be installed. This example limits installations to esp32s2 and esp32c3.

```bash
# Only install tools for specific targets
export ESPHOME_IDF_DEFAULT_TARGETS="esp32s2;esp32c3"
```

--------------------------------

### Example IR/RF Proxy Configuration

Source: https://esphome.io/components/ir_rf_proxy

This is an example configuration entry for the IR/RF proxy component, including setup for both remote receivers and transmitters, and infrared and radio frequency platforms.

```yaml
remote_receiver:
  id: ir_rx
  pin: GPIOXX


remote_transmitter:
  - id: ir_tx
    pin: GPIOXX
    carrier_duty_percent: 50%
  - id: rf_tx
    pin: GPIOXX
    carrier_duty_percent: 100%


# Infrared platform — creates infrared entities
infrared:
  - platform: ir_rf_proxy
    name: IR Transmitter
    remote_transmitter_id: ir_tx
  - platform: ir_rf_proxy
    name: IR Receiver
    receiver_frequency: 38kHz
    remote_receiver_id: ir_rx


# Radio Frequency platform — creates radio_frequency entities
radio_frequency:
  - platform: ir_rf_proxy
    name: 433MHz RF Transmitter
    frequency: 433.92MHz
    remote_transmitter_id: rf_tx

```

--------------------------------

### Setup Virtual Environment on Linux

Source: https://esphome.io/guides/installing_esphome

Create and activate a virtual environment to contain ESPHome and its dependencies.

```bash
python3 -m venv venv
source venv/bin/activate
```

--------------------------------

### Retrieve Number State

Source: https://esphome.io/web-api

Example JSON response from a GET request to a number entity.

```json
{
  "id": "number/Desired Delay",
  "state": "20.0000",
  "value": 20
}
```

--------------------------------

### Retrieve Select State

Source: https://esphome.io/web-api

Example JSON response from a GET request to a select entity.

```json
{
  "id": "select/House Mode",
  "state": "party",
  "value": "party"
}
```

--------------------------------

### Full Configuration Example

Source: https://esphome.io/components/time/pcf85063

A comprehensive example demonstrating how to set up the PCF85063 RTC in conjunction with another time source (like Home Assistant) for reliable time synchronization.

```APIDOC
## Full Configuration Example

### Description
This example shows a typical setup where an additional time source is used to synchronize the RTC. It includes reading the RTC on boot and updating it when an external time source synchronization is successful.

### Configuration

```yaml
esphome:
  on_boot:
    then:
      # read the RTC time once when the system boots
      pcf85063.read_time:


time:
  - platform: pcf85063
    # repeated synchronization is not necessary unless the external RTC
    # is much more accurate than the internal clock
    update_interval: never
  - platform: homeassistant
    # instead try to synchronize via network repeatedly ...
    on_time_sync:
      then:
        # ... and update the RTC when the synchronization was successful
        pcf85063.write_time:
```
```

--------------------------------

### Retrieve Cover State

Source: https://esphome.io/web-api

Example JSON response from a GET request to a cover entity.

```json
{
  "id": "cover/Front Window Blinds",
  "state": "OPEN",
  "value": 0.8,
  "current_operation": "IDLE",
  "tilt": 0.5
}
```

--------------------------------

### ESPHome Example Configuration

Source: https://esphome.io/guides/creators

This configuration includes substitutions for end-user customization, project identification, logger, API, OTA updates, and Wi-Fi provisioning options like AP, captive portal, and ESP32 IMPROV.

```yaml
# These substitutions allow the end user to override certain values
substitutions:
  name: "project-template"
  friendly_name: "Project Template"


esphome:
  name: "${name}"
  # Friendly names are used where appropriate in Home Assistant
  friendly_name: "${friendly_name}"
  # Automatically add the mac address to the name
  # so you can use a single firmware for all devices
  name_add_mac_suffix: true


  # This will allow for (future) project identification,
  # configuration and updates.
  project:
    name: esphome.project-template
    version: "1.0"


# To be able to get logs from the device via serial and api.
logger: 


# API is a requirement of the dashboard import.
api: 


# OTA is required for Over-the-Air updating
ota:
  platform: esphome


# This should point to the public location of this yaml file.
dashboard_import:
  package_import_url: github://esphome/esphome-project-template/project-template-esp32.yaml@v6
  import_full_config: false # or true


wifi:
  # Set up a wifi access point
  ap:
    password: "12345678"


# In combination with the `ap` this allows the user
# to provision wifi credentials to the device.
captive_portal: 


# Sets up Bluetooth LE (Only on ESP32) to allow the user
# to provision wifi credentials to the device.
esp32_improv:
  authorizer: none


# Sets up the improv via serial client for Wi-Fi provisioning
improv_serial:
  next_url: https://example.com/project-template/manual?ip={{ip_address}}&name={{device_name}}&version={{esphome_version}}

```

--------------------------------

### Configure Ai-Thinker Camera

Source: https://esphome.io/components/esp32_camera

Example configuration for the Ai-Thinker camera board, including I2C setup and camera-specific GPIO pins. Ensure correct I2C pins are defined if using a custom setup.

```yaml
i2c:
  - id: camera_i2c
    sda: GPIO26
    scl: GPIO27

esp32_camera:
  external_clock:
    pin: GPIO0
    frequency: 20MHz
  i2c_id: camera_i2c
  data_pins: [GPIO5, GPIO18, GPIO19, GPIO21, GPIO36, GPIO39, GPIO34, GPIO35]
  vsync_pin: GPIO25
  href_pin: GPIO23
  pixel_clock_pin: GPIO22
  power_down_pin: GPIO32

  # Image settings
  name: My Camera
  # ...
```

--------------------------------

### Dropdown Widget Configuration, Action, and Trigger Examples

Source: https://esphome.io/components/lvgl/widgets

Examples demonstrating how to define a dropdown widget, update it programmatically, and handle selection or cancellation events.

```yaml
# Example widget:
- dropdown:
    id: dropdown_id
    width: 100
    align: CENTER
    y: -40
    options:
      - Violin
      - Piano
      - Bassoon
      - Chello
      - Drums
    selected_index: 2
    dropdown_list:
      selected:
        checked:
          text_color: 0xFF0000


# Example action:
on_...:
  - lvgl.dropdown.update:
      id: dropdown_id
      selected_index: 4


# Example trigger:
- dropdown:
    ...
    on_value:
      - logger.log:
          format: "Selected index is: %d"
          args: [ x ]
    on_cancel:
      - logger.log:
          format: "Dropdown closed. Selected index is: %d"
          args: [ x ]
```

--------------------------------

### Configure garage doors using package templates

Source: https://esphome.io/components/packages

Demonstrates using a single package file with different variables to define multiple garage doors.

```yaml
# In config.yaml
packages:
  left_garage_door: !include
    file: garage-door.yaml
    vars:
      door_name: Left
  middle_garage_door: !include
    file: garage-door.yaml
    vars:
      door_name: Middle
  right_garage_door: !include
    file: garage-door.yaml
    vars:
      door_name: Right
```

```yaml
# In garage-door.yaml
switch:
  - name: ${door_name} Garage Door Switch
    platform: gpio
    # ...
```

--------------------------------

### Retrieve Alarm Control Panel State

Source: https://esphome.io/web-api

Example JSON response from a GET request to an alarm control panel entity.

```json
{
  "id": "alarm_control_panel/My Alarm",
  "state": "ARMED_AWAY",
  "value": 2
}
```

--------------------------------

### Initialize ESPHome Configuration

Source: https://esphome.io/guides/getting_started_command_line

Use the wizard to generate a new YAML configuration file for your device.

```bash
esphome wizard livingroom.yaml
```

```bash
docker run --rm -v "${PWD}":/config -it ghcr.io/esphome/esphome wizard livingroom.yaml
```

--------------------------------

### Retrieve Select State with Options

Source: https://esphome.io/web-api

Example JSON response from a GET request to a select entity with the detail parameter set to all.

```json
{
  "id": "select/House Mode",
  "name": "House Mode",
  "state": "party",
  "value": "party",
  "option": ["party","sleep","relax","home","away"]
}
```

--------------------------------

### Configure SPI Interface and LED Strip

Source: https://esphome.io/components/light/spi_led_strip

This example shows how to configure the SPI interface and the spi_led_strip component. Ensure your SPI pins are correctly defined.

```yaml
spi:
  mosi_pin: GPIO06
  clk_pin: GPIO07


light:
  - platform: spi_led_strip
    num_leds: 30
    id: rgb_led
    name: "RGB LED Strip"
    data_rate: 1MHz

```

--------------------------------

### Configure MCP3204 Component

Source: https://esphome.io/components/sensor/mcp3204

Example configuration for the MCP3204 component. Ensure the 'cs_pin' is correctly set and 'reference_voltage' matches your hardware setup.

```yaml
mcp3204:
  cs_pin: GPIOXX
  reference_voltage: 3.3V
```

--------------------------------

### Full PCM5122 Integration Example

Source: https://esphome.io/components/audio_dac/pcm5122

A comprehensive example showing I2C, I2S, audio DAC, speaker, switch, and binary sensor configuration.

```yaml
i2c:
  sda: GPIOXX
  scl: GPIOXX


i2s_audio:
  - id: i2s_output
    i2s_lrclk_pin: GPIOXX
    i2s_bclk_pin: GPIOXX


audio_dac:
  - platform: pcm5122
    id: pcm5122_dac
    address: 0x4D
    bits_per_sample: 16bit
    analog_gain: -6db
    channel_mix: stereo
    volume_min_db: -60dB
    volume_max_db: -3dB
    enable_pin: GPIOXX


speaker:
  - platform: i2s_audio
    i2s_audio_id: i2s_output
    id: speaker_id
    i2s_dout_pin: GPIOXX
    dac_type: external
    audio_dac: pcm5122_dac


# Use PCM5122 GPIO4 to control an external amplifier enable pin
switch:
  - platform: gpio
    name: "Amplifier Enable"
    pin:
      pcm5122: pcm5122_dac
      number: 4
      mode:
        output: true
    restore_mode: RESTORE_DEFAULT_ON
  - platform: pcm5122
    pcm5122: pcm5122_dac
    name: "PCM5122 Power Down"


# Use PCM5122 GPIO5 as a binary sensor input
binary_sensor:
  - platform: gpio
    id: pcm5122_gpio_input
    pin:
      pcm5122: pcm5122_dac
      number: 5
      mode:
        input: true
```

--------------------------------

### Basic Climate Component Setup

Source: https://esphome.io/components/climate/climate_ir

Set up a basic climate component. Replace 'REPLACEME' with the specific platform name.

```yaml
climate:
  - platform: REPLACEME
    name: "Living Room AC"
```

--------------------------------

### Customizing Default ESP-IDF Tools

Source: https://esphome.io/guides/esp_idf

Use ESPHOME_IDF_DEFAULT_TOOLS to define the default tools to be installed. This example adds 'openocd' to the default 'cmake' and 'ninja'.

```bash
# Force installation of extra tools
export ESPHOME_IDF_DEFAULT_TOOLS="cmake;ninja;openocd"
```

--------------------------------

### Example AM2315C Sensor Configuration

Source: https://esphome.io/components/sensor/am2315c

Use this configuration to add an AM2315C sensor to your ESPHome setup. Specify names for both temperature and humidity readings.

```yaml
sensor:
  - platform: am2315c
    temperature:
      name: "Living Room Temperature"
    humidity:
      name: "Living Room Humidity"
```

--------------------------------

### Example X9C Potentiometer Configuration

Source: https://esphome.io/components/output/x9c

This is an example configuration for the X9C output platform. Ensure you replace GPIOXX with your actual pin numbers. The initial_value ranges from 0.01 to 1.0, and step_delay is in microseconds.

```yaml
output:
  - platform: x9c
    id: x9c_pot
    cs_pin: GPIOXX
    inc_pin: GPIOXX
    ud_pin: GPIOXX
    initial_value: 1.0
    step_delay: 1us
```

--------------------------------

### Configure a Binary Light

Source: https://esphome.io/components/light/binary

Example configuration for a binary light. Requires a name and an output component ID.

```yaml
light:
  - platform: binary
    name: "Desk Lamp"
    output: light_output
```

--------------------------------

### Configure AIC3204 Audio DAC

Source: https://esphome.io/components/audio_dac/aic3204

Example configuration for the AIC3204 audio DAC platform. Ensure the I²C bus is configured in your ESPHome setup.

```yaml
audio_dac:
  - platform: aic3204
```

--------------------------------

### Example Configuration for Current Based Cover

Source: https://esphome.io/components/cover/current_based

This is an example configuration entry for the current_based cover platform. It demonstrates how to set up sensors, current thresholds, durations, and actions for opening, closing, and stopping the cover, along with obstacle detection and rollback.

```yaml
cover:
  - platform: current_based
    name: "Current Based Cover"


    open_sensor: open_current_sensor
    open_moving_current_threshold: 0.5
    open_obstacle_current_threshold: 0.8
    open_duration: 12s
    open_action:
      - switch.turn_on: open_cover_switch


    close_sensor: close_current_sensor
    close_moving_current_threshold: 0.5
    close_obstacle_current_threshold: 0.8
    close_duration: 10s
    close_action:
      - switch.turn_on: close_cover_switch


    stop_action:
      - switch.turn_off: close_cover_switch
      - switch.turn_off: open_cover_switch


    obstacle_rollback: 30%
    start_sensing_delay: 0.8s

```

--------------------------------

### Customizing Default Python Requirements

Source: https://esphome.io/guides/esp_idf

Configure ESPHOME_IDF_DEFAULT_FEATURES to control which Python requirement sets are installed for the ESP-IDF environment. This example includes 'core' and 'gdbgui'.

```bash
# Control which requirement sets are installed
export ESPHOME_IDF_DEFAULT_FEATURES="core;gdbgui"
```

--------------------------------

### SPDIF Configuration Example

Source: https://esphome.io/components/speaker/i2s_audio

Example configuration for an I2S audio speaker using SPDIF mode with required settings like use_apll and sample_rate.

```yaml
# Example SPDIF speaker configuration
i2s_audio:
  - id: i2s_output


speaker:
  - platform: i2s_audio
    id: spdif_speaker
    dac_type: external
    i2s_audio_id: i2s_output
    i2s_dout_pin: GPIOXX
    spdif_mode: true
    use_apll: true
    sample_rate: 48000
    channel: stereo
    timeout: never
```

--------------------------------

### Run Headless Build Server

Source: https://esphome.io/changelog/2026.7.0

Starts the ESPHome device builder in a dedicated build box mode without a web interface.

```bash
esphome-device-builder --remote-build-only /var/lib/esphome-builder
```

--------------------------------

### Haier Climate Button Configuration

Source: https://esphome.io/components/button/haier

Example configuration entry for adding Haier climate cleaning buttons to your ESPHome setup. This requires the haier_id to be set.

```yaml
button:
  - platform: haier
    haier_id: haier_ac
    self_cleaning:
      name: Haier start self cleaning
    steri_cleaning:
      name: Haier start 56°C steri-cleaning

```

--------------------------------

### ESP32 S3 Box 3 ES8311 Configuration Example

Source: https://esphome.io/components/audio_dac/es8311

Example configuration for an ESP32 S3 Box 3 using the ES8311 DAC. This includes I2S audio output setup and a GPIO switch for speaker enable. Note the specific pin assignments for I2S and speaker.

```yaml
audio_dac:
  - platform: es8311
    id: es8311_dac
    bits_per_sample: 16bit
    sample_rate: 16000

i2s_audio:
  - id: i2s_output
    i2s_lrclk_pin: GPIO45
    i2s_bclk_pin: GPIO17
    i2s_mclk_pin: GPIO2

speaker:
  - platform: i2s_audio
    i2s_audio_id: i2s_output
    id: speaker_id
    i2s_dout_pin: GPIO15
    dac_type: external
    sample_rate: 16000
    bits_per_sample: 16bit
    channel: left
    audio_dac: es8311_dac

switch:
  - platform: gpio
    name: "Speaker Enable"
    pin: GPIO46
    restore_mode: RESTORE_DEFAULT_ON
```

--------------------------------

### Full Configuration Example with External Time Source

Source: https://esphome.io/components/time/ds1307

Integrate the DS1307 RTC with an external time source like Home Assistant. This example reads the RTC on boot, synchronizes with Home Assistant, and then writes the updated time back to the RTC.

```yaml
esphome:
  on_boot:
    then:
      # read the RTC time once when the system boots
      ds1307.read_time:
```

```yaml
time:
  - platform: ds1307
    # repeated synchronization is not necessary unless the external RTC
    # is much more accurate than the internal clock
    update_interval: never
```

```yaml
  - platform: homeassistant
    # instead try to synchronize via network repeatedly ...
    on_time_sync:
      then:
        # ... and update the RTC when the synchronization was successful
        ds1307.write_time:
```

--------------------------------

### Check for Updates with update.check

Source: https://esphome.io/components/update

The `update.check` action triggers a check for available updates without starting the installation process. Requires the update entity's ID.

```yaml
update.check:
  id: your_update_id
```

--------------------------------

### Basic Web Server OTA Setup

Source: https://esphome.io/components/ota/web_server

A minimal configuration to enable OTA updates through the web server. Requires the web_server component to be set up.

```yaml
# Basic configuration
web_server:
  port: 80


ota:
  - platform: web_server
```

--------------------------------

### Basic Uponor Smatrix Configuration

Source: https://esphome.io/components/uponor_smatrix

This is a basic configuration to get started. Upload this to your ESPHome device and connect it to the Uponor Smatrix bus to discover device addresses.

```yaml
uponor_smatrix:


```

--------------------------------

### Read Current UART Settings

Source: https://esphome.io/components/uart

Access read-only UART configuration attributes to get current settings. No setup is required beyond having the UART component configured.

```cpp
// RX buffer size
id(my_uart).get_rx_buffer_size();
// RX FIFO full threshold
id(my_uart).get_rx_full_threshold();
// RX timeout
id(my_uart).get_rx_timeout();
// Stop bits
id(my_uart).get_stop_bits();
// Data bits
id(my_uart).get_data_bits();
// Parity
id(my_uart).get_parity();
// Baud rate
id(my_uart).get_baud_rate();
```

--------------------------------

### LVGL Image Widget Configuration and Action Examples

Source: https://esphome.io/components/lvgl/widgets

Demonstrates how to define an image widget and update its source at runtime using a direct ID or a mapping component.

```yaml
# Example widget:
- image:
    align: CENTER
    src: cat_image
    id: img_id
    radius: 11
    clip_corner: true


# Example action:
on_...:
  - lvgl.image.update:
      id: img_id
      src: cat_image_bowtie
  # Select the image via a mapping component lookup
  - lvgl.image.update:
      id: img_id
      src:
        mapping: image_map     # a mapping component with `to: image`
        value: 0               # literal key; may also be a lambda
```

--------------------------------

### Base Touchscreen Configuration

Source: https://esphome.io/components/touchscreen/cst816

Configure the CST816 touchscreen platform. Ensure I2C is set up in your configuration. This example shows the basic setup with interrupt and reset pins.

```yaml
touchscreen:
  platform: cst816
  id: my_touchscreen
  interrupt_pin: GPIOXX
  reset_pin: GPIOXX
```

--------------------------------

### FSK/OOK Continuous Mode Receiver Example

Source: https://esphome.io/components/sx127x

Configure the SX127x as a receiver in FSK/OOK continuous mode. Requires a remote_receiver setup to capture demodulated data from DIO2.

```yaml
sx127x:
  cs_pin: GPIO18
  rst_pin: GPIO23
  bandwidth: 50_0kHz
  frequency: 433.92MHz
  modulation: OOK
  packet_mode: false
  rx_start: true
  rx_floor: -90


remote_receiver:
  pin: GPIO32
  dump: raw
```

--------------------------------

### MCP9808 Sensor Configuration

Source: https://esphome.io/components/sensor/mcp9808

Example configuration for the MCP9808 temperature sensor. Ensure the I²C bus is configured in your ESPHome setup. The update interval can be adjusted as needed.

```yaml
sensor:
  - platform: mcp9808
    name: "Living Room Temperature"
    update_interval: 60s
```

--------------------------------

### Example LCD Menu Configuration

Source: https://esphome.io/components/display_menu/index

This is an example configuration entry for an LCD display that uses the lcd_pcf8574 platform. It also shows how to draw the menu and handle cases where the menu is not active.

```yaml
display:
  - platform: lcd_pcf8574
    id: my_lcd
    ...
    lambda: |-
      id(my_lcd_menu).draw();
      if (!id(my_lcd_menu).is_active())
        it.print("Menu is not active");
```

--------------------------------

### Example Fingerprint Reader Configuration

Source: https://esphome.io/components/fingerprint_grow

This is an example configuration entry for the fingerprint_grow component. It shows how to set up the sensing pin, sensor power pin, and various automation triggers for fingerprint scanning events.

```yaml
fingerprint_grow:
  sensing_pin: GPIOXX
  sensor_power_pin:
      number: GPIOXX
      inverted: true
  idle_period_to_sleep: 5s


  on_finger_scan_start:
    ...
  on_finger_scan_matched:
    ...
  on_finger_scan_unmatched:
    ...
  on_finger_scan_misplaced:
    ...
  on_finger_scan_invalid:
    ...
  on_enrollment_scan:
    ...
  on_enrollment_done:
    ...
  on_enrollment_failed:
    ...
```

--------------------------------

### Example HTU31D Sensor Configuration

Source: https://esphome.io/components/sensor/htu31d

Use this configuration to set up the HTU31D sensor for temperature and humidity readings. Ensure the I²C bus is configured in your ESPHome setup.

```yaml
sensor:
  - platform: htu31d
    temperature:
      name: "Temperature"
    humidity:
      name: "Humidity"
```

--------------------------------

### Example LCD Menu Configuration

Source: https://esphome.io/components/display_menu/lcd_menu

This is an example configuration entry for the LCD menu component, showing how to integrate it with an LCD display and define custom user characters.

```yaml
display:
  - platform: lcd_pcf8574
    id: my_lcd
    dimensions: 20x4
    ...
    user_characters:
      - position: 0
        data:  # mark_back symbol
          - 0b00100
          - 0b01000
          - 0b11110
          - 0b01001
          - 0b00101
          - 0b00001
          - 0b11110
          - 0b00000
    lambda: |-
      id(my_lcd_menu).draw();
      if (!id(my_lcd_menu).is_active())
        it.print("Menu is not active")
```

--------------------------------

### Configure BL0906 2-Channel Sensor

Source: https://esphome.io/components/sensor/bl0906

Example configuration for a 2-channel BL0906 sensor setup. Ensure UART is configured with the correct baud rate (19200) and pins.

```yaml
sensor:
  - platform: bl0906
    frequency:
      name: 'Frequency'
    temperature:
      name: 'Temperature'
    voltage:
      name: 'Voltage'
    channel_1:
      current:
        name: 'Current_1'
      power:
        name: 'Power_1'
      energy:
        name: 'Energy_1'
    channel_2:
      current:
        name: 'Current_2'
      power:
        name: 'Power_2'
      energy:
        name: 'Energy_2'
    total_energy:
      name: 'Total_Energy'
    total_power:
      name: 'Total_Power'
```

--------------------------------

### ESP32 S3 Box 3 Lite Audio Setup

Source: https://esphome.io/components/audio_dac/es8156

Example configuration for an ESP32 S3 Box 3 Lite using the ES8156 DAC with I2S audio output and a speaker. This setup includes GPIO pin assignments for I2S and speaker connections, and a GPIO switch for speaker enable.

```yaml
audio_dac:
  - platform: es8156
    id: es8156_dac

i2s_audio:
  - id: i2s_output
    i2s_lrclk_pin: GPIO47
    i2s_bclk_pin: GPIO17
    i2s_mclk_pin: GPIO2

speaker:
  - platform: i2s_audio
    i2s_audio_id: i2s_output
    id: speaker_id
    i2s_dout_pin: GPIO15
    dac_type: external
    sample_rate: 16000
    bits_per_sample: 16bit
    channel: stereo
    audio_dac: es8156_dac


switch:
  - platform: gpio
    name: "Speaker Enable"
    pin: GPIO46
    restore_mode: RESTORE_DEFAULT_ON
```

--------------------------------

### Configure Onboard LED for RP2040

Source: https://esphome.io/components/rp2

Example configuration for using the onboard LED on a Raspberry Pi Pico W.

```yaml
rp2:
  board: rpipicow


output:
  - platform: gpio
    pin: LED
    id: led_output


light:
  - platform: binary
    name: "Onboard LED"
    output: led_output
```

--------------------------------

### Start Advanced RF Sniffing

Source: https://esphome.io/components/rf_bridge

Initiate listening for advanced RF protocols using the `rf_bridge.start_advanced_sniffing` action. This requires Portisch or Mightymos firmware to be installed on the RF Bridge.

```yaml
on_...:
  then:
    - rf_bridge.start_advanced_sniffing
```

--------------------------------

### NRF52 Configuration Example

Source: https://esphome.io/components/nrf52

Basic configuration for an NRF52 board in ESPHome.

```yaml
nrf52:
  board: adafruit_feather_nrf52840
```

--------------------------------

### Example Feedback Cover Configuration

Source: https://esphome.io/components/cover/feedback

This is an example configuration for the feedback cover platform. It includes actions for opening and closing, durations, and sensors for endstops and movement. Ensure that the referenced switches and sensors are defined elsewhere in your configuration.

```yaml
cover:
  - platform: feedback
    name: "Gate"


    open_action:
      - switch.turn_on: open_cover_switch
    open_duration: 2.1min
    open_endstop: open_endstop_binary_sensor
    open_sensor: open_movement_binary_sensor


    close_action:
      - switch.turn_on: close_cover_switch
    close_duration: 2min
    close_endstop: close_endstop_binary_sensor
    close_sensor: close_movement_binary_sensor


    stop_action:
      - switch.turn_off: open_cover_switch
      - switch.turn_off: close_cover_switch
```

--------------------------------

### Sample Configuration for T-Display S3 AMOLED

Source: https://esphome.io/components/touchscreen/cst816

Example configuration for the Lilygo T-Display S3 AMOLED, including I2C setup and the CST816 touchscreen. The interrupt pin is specified.

```yaml
i2c:
  sda: GPIO3
  scl: GPIO2

touchscreen:
  - platform: cst816
    id: my_touchscreen
    interrupt_pin: GPIO21
```

--------------------------------

### Configure Text Component

Source: https://esphome.io/components/text_sensor/text

Example configuration for a text component that can be used as a source for a text sensor. This setup defines a text input with specific length and mode constraints.

```yaml
text:
  - platform: template
    id: my_text
    name: "My Text"
    optimistic: true
    min_length: 0
    max_length: 100
    mode: text
```

--------------------------------

### Label Widget Configuration and Update Action

Source: https://esphome.io/components/lvgl/widgets

Examples showing how to define label widgets with custom styling and how to update them dynamically using sensor data.

```yaml
# Example widget:
- label:
    align: CENTER
    id: lbl_id
    recolor: true
    text: "#FF0000 write# #00FF00 colored# #0000FF text#"


- label:
    align: TOP_MID
    id: lbl_symbol
    text_font: montserrat_28
    text: "\uF013"


# Example action (update label with a value from a sensor):
on_...:
  - lvgl.label.update:
      id: lbl_id
      text:
        format: "%.0fdBm"
        args: [ 'id(wifi_signal_db).get_state()' ]
```

--------------------------------

### Example Audio DAC Configuration

Source: https://esphome.io/components/audio_dac

This is an example configuration entry for the audio_dac component. Specify the platform and any other required options.

```yaml
audio_dac:
  - platform: ...
```

--------------------------------

### Configure STTS22H Temperature Sensor

Source: https://esphome.io/components/sensor/stts22h

Example configuration for the STTS22H temperature sensor. Ensure the I2C bus is configured in your ESPHome setup. The default I2C address is 0x3C.

```yaml
sensor:
  - platform: stts22h
    name: "STTS22H Temperature"
    address: 0x3C
    update_interval: 60s
```

--------------------------------

### Configure MCP3204 Sensor for Pin 0

Source: https://esphome.io/components/sensor/mcp3204

Example sensor configuration for reading from pin 0 of an MCP3204. This setup is suitable for a 1.5v solar panel power rail.

```yaml
sensor:
  - platform: mcp3204             # Attached to pin 0 of the MCP3204.
    id: solar_voltage
    number: 0                     # MCP3204 pin number
```
Tokens:
Raw