M5Stack Atom Echo with OLED Home Assistant Voice Assistant

firmware.yaml

substitutions:
  name: m5stack-atom-echo
  friendly_name: M5Stack Atom Echo

esphome:
  name: ${name}
  name_add_mac_suffix: true
  friendly_name: ${friendly_name}
  min_version: 2025.5.0
  on_boot:
    priority: 600
    then:
      - display.page.show: page_off
      - component.update: oled_display

esp32:
  board: m5stack-atom
  cpu_frequency: 240MHz
  framework:
    type: esp-idf

logger:

api:

ota:
  - platform: esphome
    id: ota_esphome

wifi:
  ap:

captive_portal:

button:
  - platform: factory_reset
    id: factory_reset_btn
    name: Factory reset

i2c:
  - id: i2c_oled
    sda: GPIO21
    scl: GPIO25
    frequency: 400kHz
    scan: false

i2s_audio:
  - id: i2s_audio_bus
    i2s_lrclk_pin: GPIO33
    i2s_bclk_pin: GPIO19

microphone:
  - platform: i2s_audio
    id: echo_microphone
    i2s_din_pin: GPIO23
    adc_type: external
    pdm: true
    sample_rate: 16000
    correct_dc_offset: true

speaker:
  - platform: i2s_audio
    id: echo_speaker
    i2s_dout_pin: GPIO22
    dac_type: external
    bits_per_sample: 16bit
    sample_rate: 16000
    channel: mono          # Keep mono: stereo doubles RAM, and OLED display reduces headroom
    buffer_duration: 60ms  # Validated value from working config

media_player:
  - platform: speaker
    name: None
    id: echo_media_player
    volume_min: 0.4
    buffer_size: 6000      # CRITICAL FIX: caps announcement pipeline heap allocation,
                           # preventing ESP_ERR_NO_MEM in the file reader
    announcement_pipeline:
      speaker: echo_speaker
      format: WAV
    files:
      - id: timer_finished_wave_file
        file: https://github.com/esphome/wake-word-voice-assistants/raw/main/sounds/timer_finished.wav
    on_announcement:
      - if:
          condition:
            - microphone.is_capturing:
          then:
            - script.execute: stop_wake_word
      - light.turn_on:
          id: led
          blue: 100%
          red: 0%
          green: 0%
          brightness: 100%
          effect: none
    on_idle:
      - script.execute: start_wake_word
      - script.execute: reset_led

voice_assistant:
  id: va
  micro_wake_word:           # New 2025.5+ API: inline reference to top-level micro_wake_word block
  microphone:
    microphone: echo_microphone
    channels: 0              # New 2025.5+ API: explicit channel selection
    gain_factor: 4           # New 2025.5+ API: replaces old top-level microphone reference
  media_player: echo_media_player
  noise_suppression_level: 2
  auto_gain: 31dBFS

  on_listening:
    - lambda: id(scroll_offset) = 0;
    - lambda: id(voice_assistant_phase) = 2;
    - script.execute: draw_display
    - light.turn_on:
        id: led
        blue: 100%
        red: 0%
        green: 0%
        effect: "Slow Pulse"

  on_stt_end:                # Use on_stt_end (not on_stt_vad_end) to capture final recognised text
    - text_sensor.template.publish:
        id: stt_text
        state: !lambda return x;
    - lambda: id(voice_assistant_phase) = 3;
    - script.execute: draw_display
    - light.turn_on:
        id: led
        blue: 100%
        red: 0%
        green: 0%
        effect: "Fast Pulse"

  on_tts_start:
    - text_sensor.template.publish:
        id: text_response
        state: !lambda return x;
    - lambda: id(scroll_offset) = 0;
    - lambda: id(voice_assistant_phase) = 4;
    - script.execute: draw_display
    - light.turn_on:
        id: led
        blue: 100%
        red: 0%
        green: 0%
        brightness: 100%
        effect: none

  on_end:
    - wait_until:
        condition:
          - media_player.is_announcing:
        timeout: 0.5s
    - wait_until:
        - and:
            - not: media_player.is_announcing
            - not: speaker.is_playing
    - delay: 5s              # Hold the response on screen for 5 seconds
    - if:
        condition:
          not: voice_assistant.is_running  # Don't clear if a new command started during the delay
        then:
          - lambda: id(voice_assistant_phase) = 1;
          - script.execute: display_off
          - text_sensor.template.publish:
              id: text_response
              state: ""
          - text_sensor.template.publish:
              id: stt_text
              state: ""
    - if:
        condition:
          - lambda: return id(wake_word_engine_location).current_option() == "On device";
        then:
          - lambda: id(va).set_use_wake_word(false);
          - micro_wake_word.start:
          - script.execute: reset_led

  on_error:
    - lambda: id(voice_assistant_phase) = 5;
    - script.execute: draw_display
    - light.turn_on:
        id: led
        red: 100%
        green: 0%
        blue: 0%
        brightness: 100%
        effect: none
    - delay: 2s
    - lambda: id(voice_assistant_phase) = 1;
    - script.execute: display_off
    - script.execute: reset_led

  on_client_connected:
    - delay: 2s
    - script.execute: start_wake_word
  on_client_disconnected:
    - script.execute: stop_wake_word

  on_timer_finished:
    - script.execute: stop_wake_word
    - wait_until:
        not: microphone.is_capturing
    - switch.turn_on: timer_ringing
    - light.turn_on:
        id: led
        red: 0%
        green: 100%
        blue: 0%
        brightness: 100%
        effect: "Fast Pulse"
    - wait_until:
        - switch.is_off: timer_ringing
    - light.turn_off: led
    - switch.turn_off: timer_ringing

binary_sensor:
  - platform: gpio
    pin:
      number: GPIO39
      inverted: true
    name: Button
    disabled_by_default: true
    entity_category: diagnostic
    id: echo_button
    on_multi_click:
      - timing:
          - ON for at least 50ms
          - OFF for at least 50ms
        then:
          - if:
              condition:
                switch.is_on: timer_ringing
              then:
                - switch.turn_off: timer_ringing
              else:
                - voice_assistant.start:
      - timing:
          - ON for at least 10s
        then:
          - button.press: factory_reset_btn

light:
  - platform: esp32_rmt_led_strip
    id: led
    name: None
    disabled_by_default: true
    entity_category: config
    pin: GPIO27
    default_transition_length: 0s
    chipset: SK6812
    num_leds: 1
    rgb_order: grb
    effects:
      - pulse:
          name: "Slow Pulse"
          transition_length: 250ms
          update_interval: 250ms
          min_brightness: 50%
          max_brightness: 100%
      - pulse:
          name: "Fast Pulse"
          transition_length: 100ms
          update_interval: 100ms
          min_brightness: 50%
          max_brightness: 100%

font:
  - file: "gfonts://LINE+Seed+JP"
    id: oled_font
    size: 11
    glyphs: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 .,-!?':;/()@#&"

text_sensor:
  - id: text_response
    platform: template
    name: Voice Response
  - id: stt_text
    platform: template
    name: STT Text

globals:
  - id: voice_assistant_phase
    type: int
    initial_value: "0"
    restore_value: false
  - id: scroll_offset
    type: int
    initial_value: "0"
    restore_value: false

interval:
  - interval: 50ms
    then:
      - if:
          condition:
            lambda: return id(voice_assistant_phase) == 4;
          then:
            - lambda: |-
                auto text = id(text_response).state;
                if (!text.empty()) {
                  int text_width = text.length() * 6;
                  int display_width = 128;
                  if (text_width > display_width) {
                    if (id(scroll_offset) < text_width) {
                      id(scroll_offset) += 3;
                      if (id(scroll_offset) > text_width) {
                        id(scroll_offset) = text_width;
                      }
                      id(oled_display).update();
                    }
                  }
                }

display:
  - platform: ssd1306_i2c
    id: oled_display
    model: "SSD1306 128x32"
    i2c_id: i2c_oled
    address: 0x3C
    update_interval: never
    pages:
      - id: page_off
        lambda: |-
          it.fill(COLOR_OFF);
      - id: page_listening
        lambda: |-
          it.fill(COLOR_OFF);
          it.printf(64, 16, id(oled_font), COLOR_ON, TextAlign::CENTER, "Listening...");
      - id: page_thinking
        lambda: |-
          it.fill(COLOR_OFF);
          it.printf(64, 6, id(oled_font), COLOR_ON, TextAlign::CENTER, "%s", id(stt_text).state.c_str());
          it.printf(64, 22, id(oled_font), COLOR_ON, TextAlign::CENTER, "Thinking...");
      - id: page_replying
        lambda: |-
          it.fill(COLOR_OFF);
          auto text = id(text_response).state;
          if (!text.empty()) {
            int char_width = 6;
            int text_width = text.length() * char_width;
            int display_width = it.get_width();
            if (text_width <= display_width) {
              it.printf(display_width / 2, 16, id(oled_font), COLOR_ON, TextAlign::CENTER, "%s", text.c_str());
            } else {
              int x = display_width - id(scroll_offset);
              it.printf(x, 16, id(oled_font), COLOR_ON, TextAlign::LEFT, "%s", text.c_str());
            }
          }
      - id: page_error
        lambda: |-
          it.fill(COLOR_OFF);
          it.printf(64, 16, id(oled_font), COLOR_ON, TextAlign::CENTER, "Error");

script:
  - id: display_off
    then:
      - display.page.show: page_off
      - component.update: oled_display

  - id: draw_display
    then:
      - lambda: |-
          switch (id(voice_assistant_phase)) {
            case 2:   id(oled_display).show_page(id(page_listening)); break;
            case 3:   id(oled_display).show_page(id(page_thinking));  break;
            case 4:   id(oled_display).show_page(id(page_replying));  break;
            case 5:   id(oled_display).show_page(id(page_error));     break;
            default:  id(oled_display).show_page(id(page_off));       break;
          }
          id(oled_display).update();

  - id: reset_led
    then:
      - if:
          condition:
            - lambda: return id(wake_word_engine_location).current_option() == "On device";
            - switch.is_on: use_listen_light
          then:
            - light.turn_on:
                id: led
                red: 100%
                green: 89%
                blue: 71%
                brightness: 60%
                effect: none
          else:
            - if:
                condition:
                  - lambda: return id(wake_word_engine_location).current_option() == "In Home Assistant";
                  - switch.is_on: use_listen_light
                then:
                  - light.turn_on:
                      id: led
                      red: 0%
                      green: 100%
                      blue: 100%
                      brightness: 60%
                      effect: none
                else:
                  - light.turn_off: led

  - id: start_wake_word
    then:
      - if:
          condition:
            and:
              - not: voice_assistant.is_running
              - lambda: return id(wake_word_engine_location).current_option() == "On device";
          then:
            - lambda: id(va).set_use_wake_word(false);
            - micro_wake_word.start:
      - if:
          condition:
            and:
              - not: voice_assistant.is_running
              - lambda: return id(wake_word_engine_location).current_option() == "In Home Assistant";
          then:
            - lambda: id(va).set_use_wake_word(true);
            - voice_assistant.start_continuous:

  - id: stop_wake_word
    then:
      - if:
          condition:
            lambda: return id(wake_word_engine_location).current_option() == "In Home Assistant";
          then:
            - lambda: id(va).set_use_wake_word(false);
            - voice_assistant.stop:
      - if:
          condition:
            lambda: return id(wake_word_engine_location).current_option() == "On device";
          then:
            - micro_wake_word.stop:

switch:
  - platform: template
    name: Use listen light
    id: use_listen_light
    optimistic: true
    restore_mode: RESTORE_DEFAULT_ON
    entity_category: config
    on_turn_on:
      - script.execute: reset_led
    on_turn_off:
      - script.execute: reset_led

  - platform: template
    id: timer_ringing
    optimistic: true
    restore_mode: ALWAYS_OFF
    on_turn_off:
      - lambda: |-
          id(echo_media_player)
            ->make_call()
            .set_command(media_player::MediaPlayerCommand::MEDIA_PLAYER_COMMAND_REPEAT_OFF)
            .set_announcement(true)
            .perform();
          id(echo_media_player)->set_playlist_delay_ms(speaker::AudioPipelineType::ANNOUNCEMENT, 0);
      - media_player.stop:
          announcement: true
    on_turn_on:
      - lambda: |-
          id(echo_media_player)
            ->make_call()
            .set_command(media_player::MediaPlayerCommand::MEDIA_PLAYER_COMMAND_REPEAT_ONE)
            .set_announcement(true)
            .perform();
          id(echo_media_player)->set_playlist_delay_ms(speaker::AudioPipelineType::ANNOUNCEMENT, 1000);
      - media_player.speaker.play_on_device_media_file:
          media_file: timer_finished_wave_file
          announcement: true
      - delay: 15min
      - switch.turn_off: timer_ringing

select:
  - platform: template
    entity_category: config
    name: Wake word engine location
    id: wake_word_engine_location
    optimistic: true
    restore_value: true
    options:
      - "In Home Assistant"
      - "On device"
    initial_option: "On device"
    on_value:
      - if:
          condition:
            lambda: return x == "In Home Assistant";
          then:
            - micro_wake_word.stop:
            - delay: 500ms
            - lambda: id(va).set_use_wake_word(true);
            - voice_assistant.start_continuous:
      - if:
          condition:
            lambda: return x == "On device";
          then:
            - lambda: id(va).set_use_wake_word(false);
            - voice_assistant.stop:
            - delay: 500ms
            - micro_wake_word.start:

micro_wake_word:
  on_wake_word_detected:
    - voice_assistant.start:
        wake_word: !lambda return wake_word;
  vad:                       # From working config: enables voice activity detection
  models:
    - model: okay_nabu
    - model: alexa     # Two models chosen to leave headroom for OLED display