How to adopt a device into ESPHome - the addition to the $13 voice assistant guide (M5Stack ATOM Echo)

Adding upon the great guide from the HA website, “$13 voice remote for Home Assistant”, I thought it might be helpful, to expand that a little and show how to get your new voice assistant the ATOM Echo or any other ESP device, adopted into your ESPHome Add-on for further configuration and future updates. This, unfortunately, isn’t part of the original tutorial, so here it comes.

TL;DR This guide shows you, how to get your ATOM Echo or any other pre-flashed ESP device adopted into the ESPHome software.

To make things easier, here is the original tutorial for you to take a look at:

Expand the original tutorial

“$13 voice remote for Home Assistant”

This tutorial will guide you to turn an ATOM Echo into the world’s most private voice assistant. Pick up the tiny device to talk to your smart home. Issue commands and get responses!

[edit]See here for a Youtube video how it works:
$13 voice remote for Home Assistant - YouTube

Required material

Installing the software onto the ATOM Echo

Before you can use this device with Home Assistant, you need to install a bit of software on it.

  1. Make sure this page is opened in a Chromium-based browser on a desktop. It does not work on a tablet or phone.

    • Select the Connect button below. If your browser does not support web serial, there is no button but a text.

    • For advanced users: The configuration file is available on GitHub.

  2. Connect the ATOM Echo to your computer.

    • In the popup window, view the available ports.
    • Plug the USB-C cable into the ATOM Echo and connect it to your computer.
    • In the pop-up window, there should now appear a new entry. Select this USB serial port and select Connect.
      • Depending on your computer, the entry might look different.
        Select USB port
    • If no new port shows, your system may be missing a driver. Close the pop-up window.
      • In the dialog, select the CH342 driver, install it, then Try again.
        Open My link
  3. Select Install Voice Assistant, then Install.

    • Follow the instructions provided by the installation wizard.
    • Add the ATOM Echo to your Wi-Fi:
      • When prompted, select your network from the list and enter the credentials to your 2.4 GHz Wi-Fi network.
      • Select Connect.
      • The ATOM Echo now joined your network. Select Add to Home Assistant.
  4. This opens the My link to Home Assistant.

    • If you have not used My Home Assistant before, you will need to configure it. If your Home Assistant URL is not accessible on http://homeassistant.local:8123, replace it with the URL to your Home Assistant instance.
    • Open the link.
      Open My link
  5. Select OK.

    Set up ESPHome

  6. To add the newly discovered device, select the ATOM Echo from the list.

    • Add your ATOM Echo to a room and select Finish.
  7. You should now see the ESPHome integration.
    New ESPHome device discovered

  8. Select the ESPHome integration. Under Devices, you should see the M5Stack Atom Echo listed.
    ATOM Echo discovered

    • Your ATOM Echo is connected to Home Assistant over Wi-Fi. You can now move it to any place in your home with a USB power supply.
  9. Congratulations! You can now voice control Home Assistant using a button with a built-in microphone. Now give some commands.

Controlling Home Assistant over the ATOM Echo

  1. Press the flat button with rounded shape on your ATOM Echo.
    • The rectangular button on the side is the reset button. Do not press that one.
    • As soon as you press the button, the LED will light up in blue.
    • While you are speaking, the blue LED is pulsing.
    • Once the intent has been processed, the LED lights up in green and Home Assistant confirms the action.
  2. Say a supported voice command. For example, Turn off the light in the kitchen.
    • Make sure you’re using the area name exactly as you defined it in Home Assistant.
    • You can also ask a question, such as
      • Is the front door locked?
      • Which lights are on in the living room?
  3. Your command is not supported? Add your own commands using a sentence trigger.
  4. You find ATOM Echo takes to long to start processing your command?
    • Adjust the silence detection settings. This setting defines how much silence is needed for Assist to find you’re done speaking and it can start processing your command.
    • Go to {% my integrations title=“Settings > Devices & Services” %} and select the ESPHome integration.
    • Under M5Stack ATOM Echo, select 1 device.
      Open My link


Are things not working as expected?

#################### END OF ORIGINAL GUIDE ####################

Let’s start with some definitions of what we are talking about here.

  • ESPHome Add-on or standalone ESPHome install
    The ESPHome Add-on for Home Assistant OS or a standalone installation of ESPHome. This is the ESPHome software, where you configure, generate and flash your ESP device(s). This is, where the firmware for your ESP devices is made.
  • ESPHome integration in HA
    This is the integration, that ties together your ESP device and your HA installation. It has nothing to do with how your ESP device was configured and flashed, it is “only” the communication basis so HA and your ESP device can talk with each other. Eg. you could buy a pre-flashed device or you have used the original tutorial to flash your ESP device, in this case the ATOM Echo, and for that device to talk to HA and vice versa, it needs this integration.
    Expand for an example

    Take your TV as a real world example. The TV is our device (=ESPdevice). You as user (=HA) can do different things with your TV, turn the volume up or down, switch channels and so on. That is what the integration does, it connects the device (=TV) to you (=HA) to communicate with each other.
    But how does the TV know, what it should do, even that it’s a TV? That is, what the firmware does, that is programmed into the TV. This is normally done by the manufacturer like Samsung, Sony, LG or …! In our example this would be the ESPHome Add-on (or standalone install) where you configure the firmware for your ESP device and upload it. I hope that gives a little more insight.

  • ESP device
    An ESP device is every device with an ESP8266 or ESP32 chip. There are numerous devices for practically every situation, that run on an ESP processor. These devices range from simple Bluetooth proxies to complete weather stations or LED stripe controllers, over to A/C control, and doesn’t end with various sensors to connect to, like rain, temperature or humidity sensors or cameras or …! If you take a look at the ESPHome website, you’ll get overwhelmed by the sheer number of devices and sensors, the possibilities are near endless. In the course of this tutorial we are talking about an ATOM Echo, but in the end, this is a normal ESP device, too. So this guide can be used for everything ESP powered, eg. the Bluetooth Proxy from the ESPHome website.

Let’s go and see what we need to have right now:

  • an ATOM Echo, flashed via the original guide (it can be, but it didn’t need to be connected to HA)
  • a running Home Assistant install to connect to
  • some computer, where you can install the ESPHome Add-on or the standalone version of ESPHome (see the next paragraph on how to decide what you need here)
  • a little time to get things running, and a HA install that can be restarted a few times, if necessary (that means, no people depend on HA while you’re working on it)

The first thing we need to do, is to install the ESPHome Add-on or the standalone version.

  • You are running Home Assistant via Home Assistant OS or as a supervised install
    In this case, the best way is to install ESPHome as Add-on via the HA store. There is an always up-to-date guide on the ESPHome website, where the installation process is outlined. It will take you just a few minutes to install ESPHome and have it ready to work with. Just stop before you start using the wizard to setup a new device, we’ll do that later or you can come back to that after this guide.
    Getting Started with ESPHome and Home Assistant — ESPHome
  • You are running any other installation method for Home Assistant, doesn’t matter if “venv”, “core” or as a “(docker) container”
    Then you need to do a standalone install of ESPHome. This isn’t very complicated, just take a look at the up-to-date guide on the ESPHome website:
    Installing ESPHome Manually — ESPHome

Now that we have ESPHome installed, you should be presented with an empty ESPHome dashboard:

If things worked really well, there already could be a discovered device, eg. the ATOM Echo. If not, don’t worry, we’ll get there!

ESPHome is now automagically searching your local network for any new devices, that could be adopted into the dashboard. This might take a little while, as a general rule between five to ten minutes should be enough. If a device is discovered, it will show up in your ESPHome dashboard. Should look like this, the name might be different than the one in the screenshot, depending on what you’re working on (eg. the ATOM Echo or a BT proxy).

thanks a lot to @aPugLife for kindly providing this screenshot

If you got your device discovered, everything is fine, click “ADOPT” and in the upcoming popup, set the name to something useful (aka something you can remember) and click “ADOPT” again. Congratulations, you have setup your first device in ESPHome and from now on, you can change and/or update your ATOM Echo via the ESPHome dashboard. I suggest to take a look now to all the other components that ESPHome offers to integrate.

But as we all know, sometimes things don’t go as expected and for these cases we now do some troubleshooting.

You have trouble installing the ESPHome Add-on in HA-OS or supervised

Open up a topic in this sub-forum (Installation > Home Assistant OS), ideally providing the logs for the time frame you tried to install the ESPHome Add-on.

The logs you need are:

  • Supervisor logs
  • HA core logs
  • ESPHome Add-on logs

You can find them under Settings > System > Logs. As a default you will be presented with the HA core log, but in the upper right corner you see a button/pull down menu (depending on what log you are presented with), that you can open and choose the log accordingly. After selecting the log (see the list above), go to the bottom of the screen and either download the complete log, or “load full logs”. Copy the full log and paste it into the topic you opened. Please take care of a proper formatting, take a look at this thread how to do that.

ESPHome has trouble discovering your device

If the device is not discovered by ESPHome, it doesn’t show up in your dashboard, even after waiting longer than ten minutes. The topics in the forum from the last weeks show, that in almost every case of not discovering a device, mDNS is some kind of involved. ESPHome needs mDNS to be enabled and working to discover any device! If mDNS isn’t working correctly, ESPHome won’t find your device, and thus won’t let you adopt it.

There are a few places, where mDNS can take the wrong turn. These are (not in any order):

  • Your ESPHome device firmware has mDNS disabled
    Look for the following setting in your devices YAML in the ESPHome dashboard. If you have this entry, set it to false, if you don’t have this entry, don’t specifically set it, the default is mDNS enabled (disabled: false). See here for the documentation.
      disabled: true
  • Your router
    Many routers have an integrated DHCP server, this means your router takes care of the IP addresses assigned to all of your connected devices, from the TV to your company laptop. The default with nearly all users is that your router automatically takes care of this, and so you don’t need to change any settings here. But nonetheless check, if your router does have any settings regarding mDNS and if they have been changed somehow. In doubt, ask Google about your specific router model and mDNS.
    If you use your own DHCP server, you should know what you’re doing, so check the manual for your DHCP server for mDNS related settings.
  • Your firewall, especially if you use different vLANs
    MDNS isn’t able by default to jump between different zones or vLANs in your firewall. Make sure, if you use a firewall (like pfSense), that the mDNS packages from ESPHome can reach the ESP device and vice versa, regardless of different vLANs.
    Take a look at this post from @aPugLife, where he explains his findings and settings in pfSense: Click here
The device can't be adopted (ie. a greyed out adopt button)

Sometimes the button to adopt the device, especially in the upcoming pop-up, is greyed out so you can’t click it.

  • Try to click it
    Really, try it! There are sometimes settings in your theme, that change the look, so it seems, the button is greyed out. Honestly, wouldn’t know, if I hadn’t experienced it by myself. :laughing:
  • ESPHome Add-on configuration error
    The “ADOPT” button get’s greyed out, if something in your configuration isn’t right. Check eg. if your secrets.yaml file has any duplicates. It must be something in your ESPHome Add-on configuration, because the YAML from that device is pre-flashed, so presumable working, and it is not yet loaded into your ESPHome Add-on or dashboard, so can’t be a source of error. That leaves unfortunately only the config of the Add-on. See the logs from the ESPHome Add-on for any details. You can find them under Settings > System > Logs. As a default you will be presented with the HA core log, but in the upper right corner you see a button/pull down menu (depending on what log you are presented with), that you can open and choose ESPHome.
The last resort...

If all of the above doesn’t work for you, there is still one last resort to get your device “adopted”, as long as you have the ESPHome Add-on running, and that is the “old-school” manual way. You can always setup and configure the device manually, like you would do, if you’d write the code by yourself. You’ll likely do this in the future, as you now have setup ESPHome and the next device will come, rest asure. :laughing: Don’t be afraid, it’s nothing you can’t do!

At the moment there are only two websites, where you can flash your device with this pre-produced code:

For our guide we take the YAML for the ATOM Echo and set it up in ESPHome.

  1. Make sure, your ATOM Echo is connected to your local network.
  2. Go to your router (or own DHCP server) and lookup the IP address of your ATOM Echo.
  3. Ensure, that your device get’s always the same IP address from your router (or own DHCP server), otherwise you need to set a static IP in the YAML in ESPHome!
  4. Go to your ESPHome dashboard and have a close look, if your device isn’t already connected or able to adopt.
  5. Click on the button in the bottom right corner to add a new device
  6. You will be presented with the wizard to add a new device. First enter a name for the device, should be something you can remember and it should be describing (eg. ATOM-Echo-kitchen).
    If you get a pop-up, that tells you, your connection to the ESPHome dashboard isn’t over https, just click continue, it doesn’t matter for now.
  7. In the following pop-up choose any type you want, eg. ESP32, it doesn’t matter at the moment, because we’re overwriting the YAML anyway.
  8. All should be done by now, ESPHome tells you about the finished configuration. Click “SKIP” to go back to the dashboard and look for your newly added device and click on “EDIT”.
  9. You will be presented with a YAML file editor filled with the generated code for the device. Select all and delete it. Yes, this is where we overwrite the YAML with our “own” code.
  10. Copy the YAML from the link above or right here (for convenience) and paste it in the YAML file editor in ESPHome (where you just deleted everything).
    Expand to see the YAML code for the ATOM Echo
      name: "m5stack-atom-echo"
      friendly_name: "M5Stack Atom Echo"
      name: "${name}"
      friendly_name: "${friendly_name}"
      name_add_mac_suffix: true
        name: m5stack.atom-echo-voice-assistant
        version: "1.0"
      min_version: 2023.7.0
      board: m5stack-atom
        type: esp-idf
      package_import_url: github://esphome/firmware/voice-assistant/m5stack-atom-echo.yaml@main
      i2s_lrclk_pin: GPIO33
      i2s_bclk_pin: GPIO19
      - platform: i2s_audio
        id: echo_microphone
        i2s_din_pin: GPIO23
        adc_type: external
        pdm: true
      - platform: i2s_audio
        id: echo_speaker
        i2s_dout_pin: GPIO22
        dac_type: external
        mode: mono
      microphone: echo_microphone
      speaker: echo_speaker
      silence_detection: true
        - light.turn_on:
            id: led
            blue: 100%
            red: 0%
            green: 0%
            brightness: 50%
        - light.turn_on:
            id: led
            blue: 100%
            red: 0%
            green: 0%
            brightness: 100%
            effect: pulse
        - light.turn_on:
            id: led
            blue: 0%
            red: 0%
            green: 100%
            brightness: 100%
            effect: none
        - light.turn_on:
            id: led
            blue: 0%
            red: 0%
            green: 100%
            brightness: 100%
            effect: pulse
        - delay: 100ms
        - wait_until:
        - light.turn_off: led
        - light.turn_on:
            id: led
            blue: 0%
            red: 100%
            green: 0%
            brightness: 100%
            effect: none
        - delay: 1s
        - light.turn_off: led
      - platform: gpio
          number: GPIO39
          inverted: true
        name: Button
        disabled_by_default: true
        entity_category: diagnostic
        id: echo_button
          - if:
              condition: voice_assistant.is_running
                - light.turn_off: led
                - voice_assistant.stop:
                - light.turn_on:
                    id: led
                    blue: 100%
                    red: 0%
                    green: 0%
                    brightness: 50%
                    effect: none
                - voice_assistant.start:
      - 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
        rmt_channel: 0
          - pulse:
              transition_length: 250ms
              update_interval: 250ms
  11. Before we can install the firmware again on the device, we need to make some changes to the YAML.
    First, change the substitutions to the name you choose in the wizard for your device.
      name: "atom-echo-kitchen"
      friendly_name: "ATOM-Echo-kitchen"
  12. Save the YAML (top right corner)
  13. If you have set a permanent IP address for the device in your router, go right to the next step, otherwise you need to change the following in YAML.
        static_ip: # Your IP address for this device
        gateway: # Your gateway IP Address, this is normally the IP of your router
        subnet: # Your subnet, this you can find in your router
  14. Now you can click install and watch ESPHome compile and upload the firmware top your device. It will get restarted during the process, but after that you will see the actual log from the device, how it is connected, and if any errors occured.
  15. Congrats, you have mastered te difficult route in adding a device in ESPHome manually! Be proud of your victory and checkout the other cool things you can do with ESPHome powered devices.

That’s it, thank you for reading to the end! :slight_smile: Please feel free to edit this post, as the “Community Guides” sub-forum specifically allows for the edit of the first post for everyone. So if you find any errors, faults, something missing, just go ahead and change it or let me know what to change! :slight_smile: It would be nice, if you could make a seperate post informing others about your change, but it is in no way necessary.

If you have any questions or problems, just post either in this topic or open your own topic in the corresponding forum.

  • 07-31-23 Added last resort
  • 07-30-23 Initial

Thanks, I think this will be helpful to point people to. Explained with your customary clarity @paddy0174 .

1 Like

Thank you for this nice guide.
I’d like to know what configurations are needed within the yaml to make the device work for homeassistant;
i2saudio; microphone;speaker;binarysensor;… those are all things I found on the web, but until now my device won’t work.

You need to be a little more precise about what is not working and how it’s not working. And, what would be helpful as well, would be the YAML code from this device in ESPHome. :slight_smile:

to be honest, the device is adopted into ESPhome and that’s about it. It exposes a sensor “assist in progress” and 2 configuration items in home assistant.
I added lots of stuff in the yaml I found from internet but I have no idea what it does/if it’s necessary.
This is my code: atom echo -
basically, I’m still trying to find my way around and not really understanding the whole proces.
I probably should have first setup the voice pipeline; test it with my computer and then decide if I would buy an atom echo.
(as of now, the recognition is too poor to use in dutch).

Can I use this to trigger this device to play songs from my spotify account? So for example have this device connected to a dedicated speaker and voice command it to play my spotify favorites on that speaker? Would spotify see this speaker as a source?

Have a Atom Echo recieved yesterday and installed it. But have it running on a Pi4 with SSD. Have installed the Pipeline with Wakeword addon all local. But it not reacts on the wakeword and when I press the button it turns on blue but no action reacts. It works when I type the action on my Android phone assist. Text won`t work there eather.
Did I do something wrong or is the Raspberry Pi4 to slow for this?

I have the same issue, I have followed the howto multiple times to make sure I followed it correctly. Assist works via the app with both text and voice, but the Atom Echo does not work. With wakeword on, the light is constantly purple, with wakeword off, press the button and it turns blue then times out after a while.

i got the same always purple light issue and no response

I get it working, great thanks so far. One question, in the video of introducing the openwakeword voice assistent, Mike get a response trough the echo atom.

How can I achieve this?

Can anyone provide some idea what’s going on with the 0 response from the Atom Echo? I have uninstalled everything and re-installed from scratch - yet the Atom Echo does nothing. I can trigger voice assistant via my HA app my iPhone, so I know the pipeline works.

Could the Atom Echo be faulty?

For clarification: With wakeword on, the light is constantly purple yet does not respond to the wake word (e.g. does not turn blue), with wakeword off, press the button and it turns blue then times out after a while. Here is the device logs:

[17:58:06][D][binary_sensor:036]: 'Button': Sending state ON
[17:58:06][D][binary_sensor:036]: 'Button': Sending state OFF
[17:58:06][D][voice_assistant:366]: State changed from IDLE to START_PIPELINE
[17:58:06][D][voice_assistant:372]: Desired state set to START_MICROPHONE
[17:58:06][D][voice_assistant:124]: microphone not running
[17:58:06][D][voice_assistant:206]: Requesting start...
[17:58:06][D][voice_assistant:366]: State changed from START_PIPELINE to STARTING_PIPELINE
[17:58:06][D][voice_assistant:387]: Client started, streaming microphone
[17:58:06][D][voice_assistant:366]: State changed from STARTING_PIPELINE to START_MICROPHONE
[17:58:06][D][voice_assistant:372]: Desired state set to STREAMING_MICROPHONE
[17:58:06][D][voice_assistant:159]: Starting Microphone
[17:58:06][D][voice_assistant:366]: State changed from START_MICROPHONE to STARTING_MICROPHONE
[17:58:06][D][esp-idf:000]: I (2078801) I2S: DMA Malloc info, datalen=blocksize=1024, dma_buf_count=4

[17:58:06][D][voice_assistant:468]: Event Type: 1
[17:58:06][D][voice_assistant:471]: Assist Pipeline running
[17:58:06][D][voice_assistant:366]: State changed from STARTING_MICROPHONE to STREAMING_MICROPHONE
[17:58:06][D][voice_assistant:468]: Event Type: 3
[17:58:06][D][voice_assistant:482]: STT Started
[17:58:06][D][light:036]: 'M5Stack Atom Echo 9d1460' Setting:
[17:58:06][D][light:047]:   State: ON
[17:58:06][D][light:051]:   Brightness: 100%
[17:58:06][D][light:059]:   Red: 0%, Green: 0%, Blue: 100%
[17:58:06][D][light:109]:   Effect: 'Pulse'
[17:58:21][D][voice_assistant:468]: Event Type: 12
[17:58:21][D][voice_assistant:599]: Unhandled event type: 12
[17:58:25][D][voice_assistant:468]: Event Type: 0
[17:58:25][E][voice_assistant:580]: Error: stt-no-text-recognized - No text recognized
[17:58:25][D][voice_assistant:462]: Signaling stop...
[17:58:25][D][voice_assistant:366]: State changed from STREAMING_MICROPHONE to STOP_MICROPHONE
[17:58:25][D][voice_assistant:372]: Desired state set to IDLE
[17:58:25][D][light:036]: 'M5Stack Atom Echo 9d1460' Setting:
[17:58:25][D][light:051]:   Brightness: 100%
[17:58:25][D][light:059]:   Red: 100%, Green: 0%, Blue: 0%
[17:58:25][D][light:109]:   Effect: 'None'
[17:58:25][D][voice_assistant:366]: State changed from STOP_MICROPHONE to STOPPING_MICROPHONE
[17:58:25][D][esp-idf:000]: I (2097387) I2S: DMA queue destroyed

[17:58:25][D][voice_assistant:468]: Event Type: 2
[17:58:25][D][voice_assistant:550]: Assist Pipeline ended
[17:58:25][D][voice_assistant:366]: State changed from STOPPING_MICROPHONE to IDLE
[17:58:25][D][light:036]: 'M5Stack Atom Echo 9d1460' Setting:
[17:58:25][D][light:047]:   State: OFF
[17:58:26][D][light:036]: 'M5Stack Atom Echo 9d1460' Setting:

Here is my voice pipeline setup:

1 Like

I found that mine goes unresponsive after a while, saw some similar posts a few days back.

If I turn wake word off then back on it works but then goes back to unresponsive. Have not measured how long until it dies out.

1 Like

I tried to use a M5Stack Atom S3 Lite module with a INMP441 mic but it never works. Wondered if anyone managed to make something as such work.

I’m also experiencing the unresponsiveness problem with my m5stack atom echo, and toggling wake word fixes it for a short while. It doesn’t take very long for mine to become unresponsive. Usually after just a few minutes. There is nothing printed to the console when this happens, and the last message I see is usually “State changed from WAIT_FOR_VAD to WAITING_FOR_VAD”. Someone else noted the problem here and mentioned they fixed it, but they didn’t say how. Hopefully someone else chimes in with the fix.

Im having the exact same issue, I had the m5 echo working three times about a month ago, since then just purple light

In case anyone has the same problem as me. If using VLAN’s make sure you are on the same one as Home Assistant. I was getting the constant purple light and no response until I switched VLAN’s. I have a firewall rule in place and have never had an issue with segmented devices before. Interested if anyone else has this issue and can provide a fix so I can move this back to my IOT network.

I’m having the same issue. Installed several times. Either with a vanilla ESP config or a more elaborate one. When the wake word is on, the light is constantly white. Without wakeword, it turns blue upon click. But no reaction to the spoken word. I’m wondering if the latest firmware is not compatible anymore.

Device info

atom-echo-voice-assistant by m5stack
Firmware: 2023.11.4 (Nov 24 2023, 15:55:44)
Hardware: 1.0

The Lite version will never work. Don’t know why tho. I have both, the echo worked at first try, the lite still isnt working after trying like 20 different things.

I’m trying it in my native language now ( Dutch ) and this works like 2 out of 10 times… Response if fast tho

My experience is it works 2 out of 20 times - to me this Implies I’ve got it setup correctly within Home Assistant but the Atom Echo itself does not work reliably. I’m thinking this is what you get for 13 bucks.