mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-01-24 22:02:04 +01:00
Initial voice assistant documentation (#2813)
This commit is contained in:
parent
f44e9b3e8f
commit
c745a29af7
29
components/i2s_audio.rst
Normal file
29
components/i2s_audio.rst
Normal file
@ -0,0 +1,29 @@
|
||||
I²S Audio Component
|
||||
===================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up I²S based devices in ESPHome.
|
||||
:image: i2s_audio.svg
|
||||
|
||||
The ``i2s_audio`` component allows for sending and receiving audio via I²S.
|
||||
This component only works on ESP32 based chips.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
i2s_audio:
|
||||
i2s_lrclk_pin: GPIO33
|
||||
i2s_bclk_pin: GPIO19
|
||||
|
||||
Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I²S LRCLK (Word Select or Left/Right Clock) signal.
|
||||
- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I²S BCLK (Bit Clock) signal.
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
- :doc:`microphone/i2s_audio`
|
||||
- :doc:`media_player/i2s_audio`
|
||||
- :ghedit:`Edit`
|
@ -23,5 +23,6 @@ Components
|
||||
lock/index
|
||||
display_menu/index
|
||||
media_player/index
|
||||
microphone/index
|
||||
time/index
|
||||
*
|
||||
|
@ -2,11 +2,11 @@ I2S Audio Media Player
|
||||
======================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up I2S based media players in ESPHome.
|
||||
:description: Instructions for setting up I²S based media players in ESPHome.
|
||||
:image: i2s_audio.svg
|
||||
|
||||
The ``i2s_audio`` media player platform allows you to play media from webservers and web streams
|
||||
via the I2S bus. This platform only works on ESP32 based chips.
|
||||
via the :doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
@ -15,9 +15,7 @@ via the I2S bus. This platform only works on ESP32 based chips.
|
||||
- platform: i2s_audio
|
||||
name: ESPHome I2S Media Player
|
||||
dac_type: external
|
||||
i2s_lrclk_pin: GPIO33
|
||||
i2s_dout_pin: GPIO22
|
||||
i2s_bclk_pin: GPIO19
|
||||
mode: mono
|
||||
|
||||
Configuration variables:
|
||||
@ -33,10 +31,8 @@ Configuration variables:
|
||||
External DAC
|
||||
************
|
||||
|
||||
- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S LRCLK (Word Select or Left/Right Clock) signal.
|
||||
- **i2s_dout_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S DOUT (Data Out) signal.
|
||||
- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I2S BCLK (Bit Clock) signal.
|
||||
- **mode** (*Optional*, string): The mode of the I2S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
|
||||
- **i2s_dout_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I²S DOUT (Data Out) signal.
|
||||
- **mode** (*Optional*, string): The mode of the I²S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``.
|
||||
|
||||
For best results, keep the wires as short as possible.
|
||||
|
||||
|
29
components/microphone/i2s_audio.rst
Normal file
29
components/microphone/i2s_audio.rst
Normal file
@ -0,0 +1,29 @@
|
||||
I²S Audio Microphone
|
||||
====================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up I²S based microphones in ESPHome.
|
||||
:image: i2s_audio.svg
|
||||
|
||||
The ``i2s_audio`` microphone platform allows you to receive audio via the the
|
||||
:doc:`/components/i2s_audio`. This platform only works on ESP32 based chips.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
# Example configuration entry
|
||||
microphone:
|
||||
- platform: i2s_audio
|
||||
i2s_din_pin: GPIO23
|
||||
|
||||
Configuration variables:
|
||||
------------------------
|
||||
|
||||
- **i2s_din_pin** (**Required**, :ref:`Pin Schema <config-pin_schema>`): The GPIO pin to use for the I²S DIN (Data In) signal.
|
||||
|
||||
- All other options from :ref:`Microphone <config-microphone>`
|
||||
|
||||
See also
|
||||
--------
|
||||
|
||||
- :doc:`index`
|
||||
- :ghedit:`Edit`
|
109
components/microphone/index.rst
Normal file
109
components/microphone/index.rst
Normal file
@ -0,0 +1,109 @@
|
||||
Microphone Components
|
||||
=====================
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up microphones in ESPHome.
|
||||
:image: folder-open.svg
|
||||
|
||||
The ``microphone`` domain contains common functionality shared across the
|
||||
microphone platforms.
|
||||
|
||||
.. _config-microphone:
|
||||
|
||||
Base Microphone Configuration
|
||||
-----------------------------
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **on_data** (*Optional*, :ref:`Automation <automation>`): An automation to
|
||||
perform when new data is received.
|
||||
|
||||
.. _microphone-actions:
|
||||
|
||||
Microphone Actions
|
||||
------------------
|
||||
|
||||
All ``microphone`` actions can be used without specifying an ``id`` if you have only one ``microphone`` in
|
||||
your configuration YAML.
|
||||
|
||||
Configuration variables:
|
||||
|
||||
**id** (*Optional*, :ref:`config-id`): The microphone to control. Defaults to the only one in YAML.
|
||||
|
||||
|
||||
.. _microphone-capture:
|
||||
|
||||
``microphone.capture`` Action
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This action will start capturing audio data from the microphone. The data will be passed to any components listening
|
||||
and will be available in the ``on_data`` trigger.
|
||||
|
||||
.. _microphone-stop_capture:
|
||||
|
||||
``microphone.stop_capture`` Action
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This action will stop capturing audio data from the microphone.
|
||||
|
||||
|
||||
.. _microphone-triggers:
|
||||
|
||||
Microphone Triggers
|
||||
-------------------
|
||||
|
||||
.. _microphone-on_data:
|
||||
|
||||
``microphone.on_data`` Trigger
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This trigger will fire when new data is received from the microphone.
|
||||
The data is available as a ``std::vector<uint8_t>`` in the variable ``x``.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microphone:
|
||||
- platform: ...
|
||||
on_data:
|
||||
- logger.log:
|
||||
format: "Received %d bytes"
|
||||
args: ['x.size()']
|
||||
|
||||
Configuration variables:
|
||||
|
||||
- **id** (*Optional*, :ref:`config-id`): The microphone to check. Defaults to the only one in YAML.
|
||||
|
||||
|
||||
.. _microphone-conditions:
|
||||
|
||||
Microphone Conditions
|
||||
---------------------
|
||||
|
||||
All ``microphone`` conditions can be used without specifying an ``id`` if you have only one ``microphone`` in
|
||||
your configuration YAML.
|
||||
|
||||
Configuration variables:
|
||||
|
||||
**id** (*Optional*, :ref:`config-id`): The microphone to check. Defaults to the only one in YAML.
|
||||
|
||||
.. _microphone-is_capturing:
|
||||
|
||||
``microphone.is_capturing`` Condition
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
This condition will check if the microphone is currently capturing audio data.
|
||||
|
||||
|
||||
Platforms
|
||||
---------
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:glob:
|
||||
|
||||
*
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :ghedit:`Edit`
|
64
components/voice_assistant.rst
Normal file
64
components/voice_assistant.rst
Normal file
@ -0,0 +1,64 @@
|
||||
Voice Assistant
|
||||
===============
|
||||
|
||||
.. seo::
|
||||
:description: Instructions for setting up a Voice Assistant in ESPHome.
|
||||
:image: voice-assistant.svg
|
||||
|
||||
ESPHome devices with a microphone are able to stream the audio to Home Assistant and be processed there by `assist <https://www.home-assistant.io/docs/assist/>`__.
|
||||
|
||||
.. note::
|
||||
|
||||
Voice Assistant requires Home Assistant 2023.5 or later.
|
||||
|
||||
Configuration:
|
||||
--------------
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
microphone:
|
||||
- platform: ...
|
||||
id: mic_id
|
||||
|
||||
voice_assistant:
|
||||
microphone: mic_id
|
||||
|
||||
- **microphone** (**Required**, :ref:`config-id`): The microphone to use for input.
|
||||
|
||||
|
||||
.. _voice_assistant-actions:
|
||||
|
||||
Voice Assistant Actions
|
||||
-----------------------
|
||||
|
||||
The following actions are available for use in automations:
|
||||
|
||||
- ``voice_assistant.start`` - Start listening for voice commands.
|
||||
- ``voice_assistant.stop`` - Stop listening for voice commands.
|
||||
|
||||
|
||||
Push to Talk
|
||||
------------
|
||||
|
||||
Here is an example offering Push to Talk with a :doc:`/components/binary_sensor/index`.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
voice_assistant:
|
||||
microphone: mic_id
|
||||
|
||||
binary_sensor:
|
||||
- platform: gpio
|
||||
pin: ...
|
||||
on_press:
|
||||
- voice_assistant.start:
|
||||
on_release:
|
||||
- voice_assistant.stop:
|
||||
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- :doc:`microphone/index`
|
||||
- :apiref:`voice_assistant/voice_assistant.h`
|
||||
- :ghedit:`Edit`
|
1
images/microphone.svg
Normal file
1
images/microphone.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12,2A3,3 0 0,1 15,5V11A3,3 0 0,1 12,14A3,3 0 0,1 9,11V5A3,3 0 0,1 12,2M19,11C19,14.53 16.39,17.44 13,17.93V21H11V17.93C7.61,17.44 5,14.53 5,11H7A5,5 0 0,0 12,16A5,5 0 0,0 17,11H19Z" /></svg>
|
After Width: | Height: | Size: 260 B |
1
images/voice-assistant.svg
Normal file
1
images/voice-assistant.svg
Normal file
@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9,22A1,1 0 0,1 8,21V18H4A2,2 0 0,1 2,16V4C2,2.89 2.9,2 4,2H20A2,2 0 0,1 22,4V16A2,2 0 0,1 20,18H13.9L10.2,21.71C10,21.9 9.75,22 9.5,22V22H9M10,16V19.08L13.08,16H20V4H4V16H10M17,11H15V9H17V11M13,11H11V9H13V11M9,11H7V9H9V11Z" /></svg>
|
After Width: | Height: | Size: 303 B |
23
index.rst
23
index.rst
@ -668,6 +668,14 @@ Media Player Components
|
||||
Media Player Core, components/media_player/index, folder-open.svg
|
||||
I2S Audio, components/media_player/i2s_audio, i2s_audio.svg
|
||||
|
||||
Microphone Components
|
||||
---------------------
|
||||
|
||||
.. imgtable::
|
||||
|
||||
Microphone Core, components/microphone/index, microphone.svg
|
||||
I2S Microphone, components/microphone/i2s_audio, i2s_audio.svg
|
||||
|
||||
Time Components
|
||||
---------------
|
||||
|
||||
@ -680,6 +688,17 @@ Time Components
|
||||
DS1307 RTC, components/time/ds1307, clock-outline.svg
|
||||
PCF85063 RTC, components/time/pcf85063, clock-outline.svg
|
||||
|
||||
Home Assistant Companion Components
|
||||
-----------------------------------
|
||||
|
||||
.. imgtable::
|
||||
|
||||
Bluetooth Proxy, components/bluetooth_proxy, bluetooth.svg
|
||||
Voice Assistant, components/voice_assistant, voice-assistant.svg
|
||||
Sensor, components/sensor/homeassistant, home-assistant.svg
|
||||
Text Sensor, components/text_sensor/homeassistant, home-assistant.svg
|
||||
Binary Sensor, components/binary_sensor/homeassistant, home-assistant.svg
|
||||
|
||||
Misc Components
|
||||
---------------
|
||||
|
||||
@ -707,6 +726,8 @@ Misc Components
|
||||
ESP32 Camera, components/esp32_camera, camera.svg
|
||||
ESP32 Camera Web Server, components/esp32_camera_web_server, camera.svg
|
||||
|
||||
I²S Audio, components/i2s_audio, i2s_audio.svg
|
||||
|
||||
Stepper, components/stepper/index, stepper.svg
|
||||
Servo, components/servo, servo.svg
|
||||
Sprinkler, components/sprinkler, sprinkler-variant.svg
|
||||
@ -785,7 +806,7 @@ Cookbook
|
||||
IWOOLE Table Lamp, cookbook/iwoole_rgbw_table_lamp, iwoole_rgbw_table_lamp.png
|
||||
EPEVER Tracer, cookbook/tracer-an, tracer-an.jpg
|
||||
Ilonda Wifi Smart Fish Feeder, cookbook/ilonda-wifi-smart-fish-feeder, ilonda-wifi-smart-fish-feeder-cookbook.jpg
|
||||
AirGradient DIY Air Quality Sensor, cookbook/air_gradient_diy_air_quality_sensor, air_gradient_diy_air_quality_sensor.jpg
|
||||
AirGradient DIY Air Quality Sensor, cookbook/air_gradient_diy_air_quality_sensor, air_gradient_diy_air_quality_sensor.jpg
|
||||
Geiger Counter, cookbook/geiger-counter, radiationD-v1-1-cajoe_small.jpg
|
||||
EHMTX a matrix status/text display, cookbook/ehmtx, ehmtx.jpg
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user