Home Assistant / ESPHome Air Quality Monitor (No Soldering)

QT Py + Grove SEN54 - Deployment (Closeup)
QT Py + Grove SEN54 – Deployment (Closeup)

I’ve previously covered creating a Home Assistant air quality monitor system using a XAIO ESP32-C3 module and ESPHome / Home Assistant to create a 7-in-1 air quality monitor sensor. My previous article though did require a little bit of soldering to get it going.

Today I’m going to show you my latest sensor build which has completely eliminated the soldering. It’s plug and play using ESPHome and Home Assistant. I did this using the Adafruit QT Py module which has a built-in connector for connecting to a I2C (Stemma QT) device like the Grove SEN54 environmental sensor. In addition to eliminating any soldering this also saved me money by not having to buy an expansion board.

Today I’ll show you the updated build for my air quality sensor setup I’ll be using throughout my home. Let’s get started!

Hardware Used

Adafruit QT Py
Adafruit QT Py

The Adafruit QT Py ESP32-C3 is an incredibly tiny board that has WiFi/Bluetooth capabilities and is powered through USB-C

Links: Adafruit.com, Amazon.com*

Grove SEN54 Unit
Grove SEN54 Unit

The Seeed Studios SEN54 All-in-one Environmental Sensor includes measurements for particles of PM1.0/2.5/4/10, temperature and humidity and VOC (volatile organic compounds).

Links: AliExpress*, SeeedStudios.com

Overview

This updated build only consists of these two parts:

QT Py + Grove SEN54
QT Py + Grove SEN54

We simply have the QT Py and the Grove All-in-one environmental sensor from Seeed Studio. We also have a Stemma QT to Grove cable to connect the two.

All you need besides these two components is Home Assistant and ESPHome. This is a plug-and-play setup!

Adding ESPHome to Home Assistant

We are going to assume you have Home Assistant installed as installing Home Assistant is outside the scope of this guide. You can absolutely follow along though and see if it looks like something you’d like to explore. I have it installed as a supervised installation on an Orange Pi 5.

Sign into your Home Assistant instance and go to “Settings” and then “Add-ons”. Next click the “Add-on Store”.

ESPHome has it’s own section like this:

Home Assistant Add-on Store - ESPHome
Home Assistant Add-on Store – ESPHome

Select ESPHome and then click “Install”. Once the installation is finished you can click “Start” to start the service.

To make things easier choose to add the ESPHome option to your sidebar. That way you’ll see a menu choice specifically for ESPHome going forward.

Configuring ESPHome

First head to the ESPHome menu option:

ESPHome Configuration Menu
ESPHome Configuration Menu

If you don’t see the ESPHome menu option then go back to the “Add-on Store” from the previous step. Select ESPHome and enable “Show in sidebar”.

For setup we need to connect your QT Py to your device running Home Assistant with USB. This is only required for setup. It will communicate wirelessly after you’ve completed setup (if you configure it that way).

You also have the option of connecting it to a different computer but *only* if your Home Assistant instance is configured to run in HTTPS.

Click “New Device” in the bottom right hand menu. Follow the menus to add the device into your ESPHome instance.

Editing YAML Configuration

Click “Edit” on the new sensor/device you created. We are going to change the esphome and esp32 sections to this:

esphome:
  name: sensors-garage
  platformio_options:
    board_build.flash_mode: dio
  friendly_name: sensors-garage

esp32:
  board: adafruit_qtpy_esp32c3
  variant: esp32c3
  framework:
    type: esp-idf

Note that YAML is very sensitive to spacing. The editor will underline errors in red for you which definitely helps to spot them as long as you’re watching for them.

While we are in here you should save your encryption key to your clipboard or keep it handy for reference. We are going to need it in the step to add the device to Home Assistant later.

Install Configuration to Device

Finally you can begin programming the device. Click to “Install”. Select the device type and your USB device again and with any luck:

ESPHome - Successful Configuration Flash
ESPHome – Successful Configuration Flash

Above you can see it connected to my WiFi point and that everything ran successfully. That is without ever programming the ESP32. ESPHome did all of the programming for us!

Adding Device to Home Assistant

Now head back to your “Settings” menu for Home Assistant and click “Devices”. You should see your new sensor with the name you specified in the configuration.

Check to see if the sensor is online. With any luck it is like my example above. Now click “Configure”:

Home Assistant - Devices Menu - Configure ESPHome
Home Assistant – Devices Menu – Configure ESPHome

It should ask you if you want to add the node to Home Assistant. Select “Submit” and then it will ask you for your encryption key it gave us earlier. If you don’t have this just go back to the ESPHome menu and select “Edit”. You will see the key in plain text under “encryption” and then “key”.

If everything goes well the device should come online and be successfully paired with Home Assistant. From this point forward we will be able to update and push the configuration wirelessly to the device.

Adding Sensor to YAML Configuration

Here’s the full configuration I used for the sensor:

esphome:
  name: sensors-garage
  platformio_options:
    board_build.flash_mode: dio
  friendly_name: sensors-garage

esp32:
  board: adafruit_qtpy_esp32c3
  variant: esp32c3
  framework:
    type: esp-idf
    
# Enable logging
logger:

# Enable Home Assistant API
api:
  encryption:
    key: "XXX"

ota:
  password: "XXX"

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  domain: .jamesachambers.net
  power_save_mode: none

i2c:
  sda: 5
  scl: 6
    
sensor:
  - platform: sen5x
    id: sen54
    pm_1_0:
      name: " PM <1µm Weight concentration"
      id: pm_1_0
      accuracy_decimals: 1
    pm_2_5:
      name: " PM <2.5µm Weight concentration"
      id: pm_2_5
      accuracy_decimals: 1
    pm_4_0:
      name: " PM <4µm Weight concentration"
      id: pm_4_0
      accuracy_decimals: 1
    pm_10_0:
      name: " PM <10µm Weight concentration"
      id: pm_10_0
      accuracy_decimals: 1
    temperature:
      name: "Temperature"
      accuracy_decimals: 1
    humidity:
      name: "Humidity"
      accuracy_decimals: 0
    voc:
      name: "VOC"
      algorithm_tuning:
        index_offset: 100
        learning_time_offset_hours: 12
        learning_time_gain_hours: 12
        gating_max_duration_minutes: 180
        std_initial: 50
        gain_factor: 230
    temperature_compensation:
      offset: 0
      normalized_offset_slope: 0
      time_constant: 0
    acceleration_mode: low
    store_baseline: true
    address: 0x69
    update_interval: 10s

Save and install the configuration to the device.

Configured Result

Now you should have a new entity within Home Assistant that looks like this:

Home Assistant QT Py SEN54 Air Sensors
Home Assistant QT Py SEN54 Air Sensors

I put them in my garage here:

QT Py + Grove SEN54 Deployed
QT Py + Grove SEN54 Deployed

You can see I put a little mount for the sensor unit to sit on and faced the inlet and outlets away from the wall. This is so I’m getting good airflow and accurate readings.

The other equipment in the picture is my whole house outdoor RGB lighting as well as my sprinkler box. The plug is a Z-Wave enabled smart plug with power monitoring features.

QT Py + Grove SEN54 - Deployment (Closeup)
QT Py + Grove SEN54 – Deployment (Closeup)

Conclusion

This is the design I will be using for all of my environmental sensors from now on. Although the soldering isn’t a big deal for me now that I have the Pinecil there’s no question that plug-and-play is a much nicer way to work with these. You also save money by not having to buy the expansion board.

This will be a much easier way to get started with these as a beginner. If you already have Home Assistant (and bonus points for already having ESPHome) everything will be configured within there. Even the flashing is done by ESPHome within Home Assistant. It really is as easy as I’ve made it look here.

I highly recommend the open source hardware and software solution for sensors. You don’t need proprietary units for these to have to avoid soldering. There are good ways to do this using a cheap <$10 ESP32 module without making any compromises!

Other Resources

You can see my old guide using a Seeed XAIO chip + expansion board to accomplish the same thing here

I’ve also covered using Z-Wave door and window sensors within Home Assistant here

I’ve covered a similar Z-Wave smart plug to what the USB cable is plugged into in the pictures above here

See here for all of my articles related to Home Assistant

Subscribe
Notify of
guest

29 Comments
Inline Feedbacks
View all comments
Brandon
Brandon
9 months ago

What exactly is the seeedstudio enclosure adding to the SEN55 sensor? Have you had a chance to crack it open and see what’s inside? Looks like seeedstudio is selling their enclosed version for $55 but the sensor itself can be bought for significantly less at ~$21 and it already has a 5 pin output that can probably be connected to an ESP32 easily.

john
john
9 months ago

Thank you for sharing this! i keep running into issue:
[23:06:10][W][wifi_esp32:504]: Event: Disconnected ssid='chowchow' bssid=[redacted] reason='Auth Expired'
[23:06:10][W][wifi:588]: Error while connecting to network.
[23:06:10][W][wifi:624]: Restarting WiFi adapter...

is there a way to fix it?
Thank you!

john
john
9 months ago

That works! thank you so much!! now after i clicked configure, nothing shows up in my devices tab. only ESPHome shows up with one device (adafruit_qtpy_esp32c3) even with my sensor connected. it did not ask me to put encryption key at all. where should i add it?

john
john
9 months ago

Thank you so much! got everything to work!! please ignore my previous question. I got the wifi to work and had all the sensors show up when it is connected to my Raspberry pi, but after i disconnect it from the pie and plug it into a wall plug, it won’t connect to the wifi anymore. What should I do?

john
john
9 months ago

Hi James, sorry actually for some reason during installation, it stucks at a point: INFO Starting log output from /dev/ttyACM0 with baud rate 115200
[22:43:52]I (147) esp_image: segment 1: paddr=0002ffd0 vaddr=3fc90400 size=00048h ( 72) load
[22:43:52]I (147) esp_image: segment 2: paddr=00030020 vaddr=42000020 size=8f658h (587352) map
[22:43:52]I (246) esp_image: segment 3: paddr=000bf680 vaddr=3fc90448 size=02b04h ( 11012) load
[22:43:52]I (249) esp_image: segment 4: paddr=000c218c vaddr=40380000 size=10260h ( 66144) load
[22:43:52]I (269) boot: Loaded app from partition at offset 0x10000
[22:43:52]I (307) boot: Set actual ota_seq=1 in otadata[0]
[22:43:52]I (307) boot: Disabling RNG early entropy source...
[22:43:52]I (318) cpu_start: Pro cpu up.
[22:43:52]I (327) cpu_start: Pro cpu start user code
[22:43:52]I (327) cpu_start: cpu freq: 160000000
[22:43:52]I (327) cpu_start: Application information:
[22:43:52]I (329) cpu_start: Project name: sensors-garage
[22:43:52]I (335) cpu_start: App version: 2023.7.0
[22:43:52]I (340) cpu_start: Compile time: Jul 27 2023 22:33:48
[22:43:52]I (346) cpu_start: ELF file SHA256: ade1211c73b9313b...
[22:43:52]I (352) cpu_start: ESP-IDF: 4.4.4
[22:43:52]I (357) heap_init: Initializing. RAM available for dynamic allocation:
[22:43:52]I (364) heap_init: At 3FC96EC0 len 00045850 (278 KiB): DRAM
[22:43:52]I (370) heap_init: At 3FCDC710 len 00002950 (10 KiB): STACK/DRAM
[22:43:52]I (377) heap_init: At 50000020 len 00001FE0 (7 KiB): RTCRAM
[22:43:52]I (384) spi_flash: detected chip: generic
[22:43:52]I (388) spi_flash: flash io: dio
[22:43:52]I (392) sleep: Configure to isolate all GPIO pins in sleep state
[22:43:52]I (399) sleep: Enable automatic switching of GPIO sleep configuration
[22:43:52]I (406) cpu_start: Starting scheduler.

nothing goes after starting scheduler

john
john
9 months ago

Hi James,

i’m using Adafruit QT Py ESP32-C3. it seems to work when i replace the framework from type: esp-idf to type: arduino. However, I’m stuck connecting to the wifi again, even though the board is right next to the router. it will not connect.

john
john
9 months ago

Thank you, James! Would you mind advising on opening debug console? is this the right code? logger:
baud_rate: 115200
much appreciate it!

john
john
9 months ago

the wifi won’t connect. so it just still stuck at starting scheduler…Hard resetting via RTS pin…
INFO Successfully uploaded program.
INFO Starting log output from /dev/ttyACM0 with baud rate 115200
[22:47:41]I (110) boot_comm: chip revision: 4, min. application chiI (147) esp_image: segment 1: paddr=0003002c vaddr=3fc90400 size=02b4ch ( 11084) load
[22:47:41]I (149) esp_image: segment 2: paddr=00032b80 vaddr=40380000 size=0d498h ( 54424) load
[22:47:41]I (163) esp_image: segment 3: paddr=00040020 vaddr=42000020 size=8f684h (587396) map
[22:47:41]I (257) esp_image: segment 4: paddr=000cf6ac vaddr=4038d498 size=02dc8h ( 11720) load
[22:47:41]I (264) boot: Loaded app from partition at offset 0x10000
[22:47:41]I (302) boot: Set actual ota_seq=1 in otadata[0]
[22:47:41]I (302) boot: Disabling RNG early entropy source...
[22:47:41]I (313) cpu_start: Pro cpu up.
[22:47:41]I (321) cpu_start: Pro cpu start user code
[22:47:41]I (322) cpu_start: cpu freq: 160000000
[22:47:41]I (322) cpu_start: Application information:
[22:47:41]I (324) cpu_start: Project name: sensors-garage
[22:47:41]I (330) cpu_start: App version: 2023.7.1
[22:47:41]I (335) cpu_start: Compile time: Aug 2 2023 22:44:06
[22:47:41]I (341) cpu_start: ELF file SHA256: ef21c703395bf60c...
[22:47:41]I (347) cpu_start: ESP-IDF: 4.4.4
[22:47:41]I (352) heap_init: Initializing. RAM available for dynamic allocation:
[22:47:41]I (359) heap_init: At 3FC96EC0 len 00045850 (278 KiB): DRAM
[22:47:41]I (365) heap_init: At 3FCDC710 len 00002950 (10 KiB): STACK/DRAM
[22:47:41]I (372) heap_init: At 50000020 len 00001FE0 (7 KiB): RTCRAM
[22:47:41]I (379) spi_flash: detected chip: generic
[22:47:41]I (383) spi_flash: flash io: dio
[22:47:41]I (387) sleep: Configure to isolate all GPIO pins in sleep state
[22:47:41]I (394) sleep: Enable automatic switching of GPIO sleep configuration
[22:47:41]I (401) cpu_start: Starting scheduler.

john
john
9 months ago

Update: i’m able to get it online by adding output_power: 8.5
however, it seems like the code does not run automatically.– i have to plug it into a computer or my pi, and manually choose “log” to trigger the start. is there a command like “run” that i can add to the end of the code to make it run automatically when i just connect it to a wall plug?

john
john
8 months ago

it wont process using esp-idf unfortunately. it stuck at ” cpu_start: Starting scheduler.” what would cause this problem?

john
john
8 months ago

Thank you so much for the details. I do have one from adafruit and used the one board name. i do see this message:

esphome 2023.7.1 requires click==8.1.3, but you have click 8.1.6 which is incompatible.
esphome 2023.7.1 requires pyparsing>=3.0, but you have pyparsing 2.3.1 which is incompatible.

how should i address these issues? maybe this is what causing the scheduler problem?

Steffen
Steffen
8 months ago

I am on a later Version and still have the bug. Do you have an Idea how I could it get to work?

maarten
maarten
1 year ago

I just got the new IKEA
that includes the SEN54 sensor combined with a nice display and Zigbee, over Zigbee it only reports PM 2.5 temp and humidity but it’s really easy to add a ESP32 or ESP8266 inside and use ESPHome + the display keeps working 🙂

The Ikea vindstyrka is €40,- here in The Netherlands

Razor Burn
Razor Burn
1 year ago

Thanks for sharing another informative guide and I swear each time you do one of these guides I’m left googling for new products to research and seeing your lighting and sprinkler setup has me super envious so great work!

You’ve done a wonderful job show casing different ways to run environmental sensors using Home Assistant and it still amazes me to see such advanced sensors being run by a tiny ESP32-C3 microcontroller that uses very little power and packs onboard wireless/bluetooth.

Its encouraging to see Espressif deciding to use RISC-V technology moving forward and the newly announced C6 and P4 chips look highly promising with hopes of seeing them used in these tiny sized boards for more tasking projects in the future but in the interim the XIAO and Adafruit offerings do perfectly fine and for the price you can’t go wrong adding them to your projects.

Thanks again for the detailed and inspiring guides as I’m sure to dedicate some spare time over the coming weekend to make a start on my HA setup and you’ve convinced me to try this example for my garage as its really easy and that way I can use the expansion boards for other projects around the home… Take care!

Razor Burn
Razor Burn
1 year ago

I was too slow to jump on the Adafruit ESP32-S3 Reverse TFT Feather as the email notification said 97 available boards so I left it a few hours, had a check and saw they all sold out so I’ll need to be quicker next time. I may wait for stock to arrive with local vendors as its quite expensive shipping to Australia from the US and I’m still waiting on my earlier order to arrive after a few weeks stuck in transit.

It pays to do a bulk order yet I’ve noticed the popular items sellout quickly and have been caught out myself rushing an order only to see something I wanted restock but thankfully they do a fabulous job keeping inventory regular and they’re transparent if an item won’t be available due to component shortages or replaced with a newer version which is great to see.

Adafruit do sell a mid sized ESP32-C3 Dev board however I much prefer the microcontrollers for projects and have amassed a nice collection of XIAO and Adafruit QT PY boards using different chips and will certainly grab any new versions as they’re fairly cheap with the conversion rate and such a joy to use. Hopefully the discounted pricing flows its way to Australia as I’d happily grab a few more C3 boards for sensors and hope you’re correct about a possible upgrade with a newer chip yet my understanding is the C6 and P4 are still under going development so far off consumer use unless there’s another chip they’re targeting as the S2 and S3 feel old for todays standards…?

I look forward to seeing your review of the Reverse TFT Feather as judging by the feedback from users/testers they did a great job having the display on the back as its cleaner and makes for better mounting in projects. Until then take care good sir!

Razor Burn
Razor Burn
1 year ago

Yeah Adafruit have a professional setup and its great seeing the staff proudly showcasing all the neat tech with “Ladyada” being an expert at finding cool components on Digikey for use in their newest devices so normally popular items get restocked fairly quickly which is great for consumers.

I should receive my ESP32-C6 Dev board any day now with the understanding that I won’t be able to do anything with it currently as I have no experience using ESP IDF but Adafruit seem to be the only place selling them and I’m confident we’ll see Arduino IDE and CircuitPython supported soon and when that happens I hope to integrate it into my Home Assistant project as from what I’ve read Zigbee seems to be lower energy and more stable than Z-Wave but that’s a subject I know very little about and why your recent reviews/guides have been so informative and helpful for me.

I see you posted another colourful guide showing off the Adafruit WiFi Action Key and the BFF plug in PCBs are awesome as they transform the tiny MCUs into a functioning button with flashing lights or you can add the microSD Card BFF Add-On for added storage or programming. Really cool stuff that I’d never had thought to try for myself if I hadn’t seen them being used on this blog so thank you for enlightening me with something so simple yet practical!