From 2b3edea033ef6ffb2e0dfe39de7eff72f985fbc0 Mon Sep 17 00:00:00 2001 From: Jesse Hills <3060199+jesserockz@users.noreply.github.com> Date: Thu, 2 Jun 2022 17:00:24 +1200 Subject: [PATCH] Add docs for media_player and i2s_audio (#2107) --- Makefile | 2 +- components/index.rst | 1 + components/media_player/i2s_audio.rst | 54 +++++++++++++++++++++++++++ components/media_player/index.rst | 50 +++++++++++++++++++++++++ images/i2s_audio.svg | 1 + index.rst | 8 ++++ 6 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 components/media_player/i2s_audio.rst create mode 100644 components/media_player/index.rst create mode 100644 images/i2s_audio.svg diff --git a/Makefile b/Makefile index 299496721..36a481722 100644 --- a/Makefile +++ b/Makefile @@ -48,7 +48,7 @@ netlify-dependencies: copy-svg2png: cp svg2png/*.png _build/html/_images/ -netlify: netlify-dependencies netlify-api html copy-svg2png +netlify: netlify-dependencies netlify-api html svg2png copy-svg2png lint: html-strict python3 lint.py diff --git a/components/index.rst b/components/index.rst index 2fb325b11..15a1cda2c 100644 --- a/components/index.rst +++ b/components/index.rst @@ -20,4 +20,5 @@ Components stepper/index touchscreen/index lock/index + media_player/index * diff --git a/components/media_player/i2s_audio.rst b/components/media_player/i2s_audio.rst new file mode 100644 index 000000000..b3543c8f1 --- /dev/null +++ b/components/media_player/i2s_audio.rst @@ -0,0 +1,54 @@ +I2S Audio Media Player +====================== + +.. seo:: + :description: Instructions for setting up I2S 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. + +.. code-block:: yaml + + # Example configuration entry + media_player: + - 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: +------------------------ + +- **dac_type** (**Required**, enum) + + - ``external``: Use an external DAC, for example the NS4168. + - ``internal``: Use the internal DAC + +- All other options from :ref:`Media Player ` + +External DAC +************ + +- **i2s_lrclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S LRCLK signal. +- **i2s_dout_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S DOUT signal. +- **i2s_bclk_pin** (**Required**, :ref:`Pin Schema `): The GPIO pin to use for the I2S BCLK signal. +- **mode** (*Optional*, string): The mode of the I2S bus. Can be ``mono`` or ``stereo``. Defaults to ``mono``. + +Internal DAC +************ + +- **mode** (**Required**, enum): The channel mode of the internal DAC. + + - ``left`` + - ``right`` + - ``stereo`` + +See also +-------- + +- :doc:`index` +- :ghedit:`Edit` diff --git a/components/media_player/index.rst b/components/media_player/index.rst new file mode 100644 index 000000000..45005ea04 --- /dev/null +++ b/components/media_player/index.rst @@ -0,0 +1,50 @@ +Media Player Components +======================= + +.. seo:: + :description: Instructions for setting up generic media players in ESPHome. + :image: folder-open.svg + +The ``media_player`` domain includes all platforms that implement media player +functionality. + +.. note:: + + ESPHome media players require Home Assistant 2022.6 or newer. + +.. _config-media_player: + +Base Media Player Configuration +------------------------------- + +.. code-block:: yaml + + media_player: + - platform: ... + name: "Media Player Name" + +Configuration variables: + +- **name** (**Required**, string): The name of the media player. +- **icon** (*Optional*, icon): Manually set the icon to use for the + media player in the frontend. +- **internal** (*Optional*, boolean): Mark this component as internal. Internal components will + not be exposed to the frontend (like Home Assistant). Only specifying an ``id`` without + a ``name`` will implicitly set this to true. +- **disabled_by_default** (*Optional*, boolean): If true, then this entity should not be added to any client's frontend, + (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). + Defaults to ``false``. +- **entity_category** (*Optional*, string): The category of the entity. + See https://developers.home-assistant.io/docs/core/entity/#generic-properties + for a list of available options. Set to ``""`` to remove the default entity category. + +See Also +-------- + +.. toctree:: + :maxdepth: 1 + :glob: + + * + +- :ghedit:`Edit` diff --git a/images/i2s_audio.svg b/images/i2s_audio.svg new file mode 100644 index 000000000..3c863aac7 --- /dev/null +++ b/images/i2s_audio.svg @@ -0,0 +1 @@ + diff --git a/index.rst b/index.rst index 21c9f0f9c..bc1ea6fc6 100644 --- a/index.rst +++ b/index.rst @@ -631,6 +631,14 @@ Lock Components Generic Output Lock, components/lock/output, upload.svg Template Lock, components/lock/template, description.svg +Media Player Components +----------------------- + +.. imgtable:: + + Media Player Core, components/media_player/index, folder-open.svg + I2S Audio, components/media_player/i2s_audio, i2s_audio.svg + Misc Components ---------------