How to Announce Sensor Data via TTS in Home Assistant: PM2.5 Values and Advice

This is a detailed beginner tutorial based on features of Home Assistant 2025.12.x.

During the 2024-2025 evolution, the TTS (text-to-speech) logic in Home Assistant (HA) has become highly standardized. It is recommended to use the generic tts.speak service rather than the old platform-specific services (such as tts.google_translate_say), so that even if you switch speech engines in the future, your automation scripts will not need to be modified.

Core principle

TTS integration: converts text into an audio stream (such as Google Translate, Edge TTS, Piper, etc.).
Media player: the device that plays the audio (such as Xiao Ai, HomePod, a browser, or a Bluetooth speaker).
Jinja2 template: fetches sensor data and embeds it into the text.

Preparation

Home Assistant: version 2025.12.2 (or a similar version).
Playback device: a media player already integrated with HA (example entity ID: media_player.living_room_speaker).
Sensor: an already integrated PM2.5 sensor (example entity ID: sensor.living_room_pm25).

Step 1: Configure the TTS service (Text-to-Speech)

For beginners, the simplest option that requires no extra hardware is the built-in Google Translate TTS (requires a suitable network environment), or install Edge TTS through HACS (recommended, sounds more natural). Here we demonstrate the official built-in flow.

Open the HA left menu, Settings -> Devices & Services.
Click Add Integration in the bottom right corner.
Search for Google Translate text-to-speech and click to add it.
Configure the language code; for Chinese it is recommended to enter zh-cn, then click Submit.
The system will automatically generate an entity, usually tts.google_zh_cn.

Note

: if you want offline operation or better Chinese quality, consider searching for and installing “Piper” (official local add-on) or “Edge TTS” (HACS); the logic after configuration is exactly the same as below.

Step 2: Verify that TTS can produce sound

Before writing the automation, first make sure sound can be played.

Open the left menu, Developer Tools -> Services (Services/Actions).
In the search action box, enter: tts.speak (this is the standard modern HA speak action).
Target: select the TTS entity you just added (such as tts.google_zh_cn).
Media Player Entity: select your speaker (such as media_player.browser or your smart speaker).
Message: enter “Hello, this is a test”.
Click Perform Action.

If the speaker makes a sound, you can proceed to the next step. If not, check the network or the speaker volume.

Step 3: Write the announcement automation (UI visual mode)

We want to achieve: every day at 8 AM, announce the current PM2.5 value and give advice on whether to open the windows.

Open Settings -> Automations & Scenes -> Create Automation -> Create new automation.

1. Set the Triggers

Click Add Trigger -> select Time.
Set a fixed time, for example 08:00:00.

2. Set the Actions – the core part

Click Add Action -> search for and select TTS: Speak (or displayed as Send text to speech).
TTS entity: select tts.google_zh_cn.
Media player entity: select your speaker.
Message: this is the most critical step; we need to use a Template to insert variables. Please copy the following code into the message box:

codeJinja2

Good morning. The current living room PM2.5 index is {{ states(‘sensor.living_room_pm25’) }} micrograms per cubic meter.{% set pm = states(‘sensor.living_room_pm25’) | float(0) %}Advice:{% if pm

Beginner-friendly explanation of the code:
{{ states(‘…’) }}: this is the standard way to extract a sensor value. Be sure to replace sensor.living_room_pm25 with the sensor ID in your own system.
{% set pm = … %}: defines a variable called pm for later comparisons. float(0) is to prevent an error when the sensor is unavailable, defaulting to 0.

{% if … %}: a logical check that makes the speaker say different things depending on the value. Language: can be left empty or set to zh-cn.

3. Save the automation

Click Save in the bottom right corner and name it “Daily Air Quality Announcement”.

Step 4: Advanced tips (YAML mode)

If you want to configure it directly with YAML code or share it with others, click the three dots in the top right corner of the automation editor and select Edit in YAML.

Below is a complete, standardized automation YAML configuration (based on the HA 2025 standard):

alias: 每日空气质量播报description: "通过TTS播报PM2.5及建议"trigger:
 - platform: time
 at: "08:00:00"condition: action:
 - action: tts.speak
 target:
 entity_id: tts.google_zh_cn
 # 你的TTS实体
 data:
 media_player_entity_id: media_player.living_room_speaker
# 你的音箱实体
 message: >- 现在是 {{ now().strftime('%H点%M分') }}。 当前 PM2.5 数值为 {{ states('sensor.living_room_pm25') }}。 {% set pm = states('sensor.living_room_pm25') | float(0) %} {% if pm > 75 %} 空气不好，我已经为您自动开启了净化器。 {% else %} 空气清新，祝您心情愉快。 {% endif %}mode: single

Common problems and troubleshooting guide

The value is read out as “Unknown” or “Unavailable”:
Cause: the sensor was offline at that moment or the ID was entered incorrectly.
Solution: in Developer Tools -> States, confirm whether the sensor ID is correct and has a concrete value.

Google TTS produces no sound:

Cause: Google’s service may not be reachable in your network environment.
Solution:
Option A: configure your network environment (at the router level).
Option B (recommended): download the Edge TTS integration in HACS. It uses Microsoft Edge’s interface, connects extremely fast in mainland China and sounds natural. The configuration method is exactly the same as the steps above; you only need to change the entity in the action to tts.edge_tts.

How do I round the value?

If you do not want to hear “PM2.5 is 25.3421…”, you can add round in the template:
{{ states(‘sensor.living_room_pm25’) | float(0) | round(0) }}

The player is not supported:

If you are using a simple buzzer gateway such as Sonoff, it does not support TTS. You need a real media player (such as HomePod, Sonos, Google Nest, or a speaker connected via DLNA).

With the steps above you can implement smart voice announcements in Home Assistant 2025. It is recommended to get a simple “Hello” working first, then gradually add sensor data.