Initial voice assistant documentation (#2813)

This commit is contained in:
Jesse Hills 2023-04-12 11:53:24 +12:00 committed by GitHub
parent f44e9b3e8f
commit c745a29af7
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 260 additions and 9 deletions

29
components/i2s_audio.rst Normal file
View 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`

View File

@ -23,5 +23,6 @@ Components
lock/index
display_menu/index
media_player/index
microphone/index
time/index
*

View File

@ -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.

View 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`

View 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`

View 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
View 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

View 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

View File

@ -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