From c305a836f9c34954ca5028e49f175b203b72f5d7 Mon Sep 17 00:00:00 2001 From: Guillermo Ruffino Date: Tue, 10 Oct 2023 21:13:24 -0300 Subject: [PATCH] fixes docs for 202310 (#3251) Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com> --- components/alarm_control_panel/index.rst | 12 ++++----- components/display/st7789v.rst | 24 +++++++++--------- components/grove_tb6612fng.rst | 8 +++--- components/{light => }/images/lightwaverf.jpg | Bin components/{light => }/lightwaverf.rst | 4 +-- components/mqtt.rst | 2 +- components/number/tuya.rst | 4 +-- components/remote_receiver.rst | 2 +- components/remote_transmitter.rst | 2 +- components/sensor/gcja5.rst | 22 ++++++++++++---- components/sensor/ld2410.rst | 6 ++++- components/sensor/pmwcs3.rst | 10 ++++---- components/vbus.rst | 19 +++++++------- index.rst | 2 +- schema_doc.py | 8 ++++++ 15 files changed, 74 insertions(+), 51 deletions(-) rename components/{light => }/images/lightwaverf.jpg (100%) rename components/{light => }/lightwaverf.rst (98%) diff --git a/components/alarm_control_panel/index.rst b/components/alarm_control_panel/index.rst index 6fe6b8656..24610ace1 100644 --- a/components/alarm_control_panel/index.rst +++ b/components/alarm_control_panel/index.rst @@ -29,19 +29,19 @@ Configuration variables: - **on_state** (*Optional*, :ref:`Action `): An automation to perform when the alarm changes state. See :ref:`alarm_control_panel_on_state_trigger`. - **on_arming** (*Optional*, :ref:`Action `): An automation to perform - when the alarm state changes to `arming`. See :ref:`alarm_control_panel_on_arming_trigger`. + when the alarm state changes to ``arming``. See :ref:`alarm_control_panel_on_arming_trigger`. - **on_pending** (*Optional*, :ref:`Action `): An automation to perform - when the alarm state changes to `pending`. See :ref:`alarm_control_panel_on_pending_trigger`. + when the alarm state changes to ``pending``. See :ref:`alarm_control_panel_on_pending_trigger`. - **on_armed_home** (*Optional*, :ref:`Action `): An automation to perform - when the alarm state changes to `armed_home`. See :ref:`alarm_control_panel_on_armed_home_trigger`. + when the alarm state changes to ``armed_home``. See :ref:`alarm_control_panel_on_armed_home_trigger`. - **on_armed_night** (*Optional*, :ref:`Action `): An automation to perform - when the alarm state changes to `armed_night`. See :ref:`alarm_control_panel_on_armed_night_trigger`. + when the alarm state changes to ``armed_night``. See :ref:`alarm_control_panel_on_armed_night_trigger`. - **on_armed_away** (*Optional*, :ref:`Action `): An automation to perform - when the alarm state changes to `armed_away`. See :ref:`alarm_control_panel_on_armed_away_trigger`. + when the alarm state changes to ``armed_away``. See :ref:`alarm_control_panel_on_armed_away_trigger`. - **on_triggered** (*Optional*, :ref:`Action `): An automation to perform when the alarm triggers. See :ref:`alarm_control_panel_on_triggered_trigger`. - **on_disarmed** (*Optional*, :ref:`Action `): An automation to perform - when the alarm state changes to `disarmed`. See :ref:`alarm_control_panel_on_disarmed_trigger`. + when the alarm state changes to ``disarmed``. See :ref:`alarm_control_panel_on_disarmed_trigger`. - **on_cleared** (*Optional*, :ref:`Action `): An automation to perform when the alarm clears. See :ref:`alarm_control_panel_on_cleared_trigger`. diff --git a/components/display/st7789v.rst b/components/display/st7789v.rst index c4a126709..4ae3efefa 100644 --- a/components/display/st7789v.rst +++ b/components/display/st7789v.rst @@ -62,8 +62,8 @@ to an ESP module. Configuration variables: ************************ -Options below marked **Required** *unless preset* must be provided but may be defined by a preset depending on the selected model, so -may not need to be explicitly specified in your YAML file. If you do specify them they will override any preset. +Options below marked **Required** might have default values set for some models and do not need to be set. +If you do specify them they will override any default. - **model** (**Required**, string): The display model to use. One of the following options: @@ -74,17 +74,17 @@ may not need to be explicitly specified in your YAML file. If you do specify the - ``LILYGO T-Embed 170X320`` - ``Custom`` For other displays not listed above -- **height** (**Required** *unless preset*, int): Sets height of display in pixels. -- **width** (**Required** *unless preset*, int): Sets width of display. -- **offset_height** (**Required** *unless preset*, int): When ``model`` is set to "Custom", use this to specify the display's vertical - offset in pixels. This option may not be specified when the ``model`` is not set to "Custom". -- **offset_width** (**Required** *unless preset*, int): When ``model`` is set to "Custom", use this to specify the display's horizontal - offset in pixels. This option may not be specified when the ``model`` is not set to "Custom". -- **cs_pin** (**Required** *unless preset*, :ref:`Pin Schema `): The CS pin. -- **dc_pin** (**Required** *unless preset*, :ref:`Pin Schema `): The DC pin. -- **reset_pin** (**Required** *unless preset*, :ref:`Pin Schema `): The RESET pin. +- **height** (**Required**, int): Sets height of display in pixels. Defaults depends ``model``. +- **width** (**Required**, int): Sets width of display. Defaults depends ``model``. +- **offset_height** (**Required**, int): When ``model`` is set to "Custom", use this to specify the display's vertical + offset in pixels. This option may not be specified when the ``model`` is not set to "Custom". Defaults depends ``model``. +- **offset_width** (**Required**, int): When ``model`` is set to "Custom", use this to specify the display's horizontal + offset in pixels. This option may not be specified when the ``model`` is not set to "Custom". Defaults depends ``model``. +- **cs_pin** (**Required**, :ref:`Pin Schema `): The CS pin. Defaults depends ``model``. +- **dc_pin** (**Required**, :ref:`Pin Schema `): The DC pin. Defaults depends ``model``. +- **reset_pin** (**Required**, :ref:`Pin Schema `): The RESET pin. Defaults depends ``model``. - **eightbitcolor** (*Optional*, boolean): Limits the supported color depth to eight bits. May be useful on - memory-constrained devices. Defaults to false. + memory-constrained devices. Defaults to ``false``. - **backlight_pin** (*Optional*, :ref:`Pin Schema `): The display's backlight pin. May be required depending on the hardware configuration. - **power_supply** (*Optional*, :ref:`config-id`): The :doc:`power supply ` to connect to diff --git a/components/grove_tb6612fng.rst b/components/grove_tb6612fng.rst index f3b3b9d93..26ac3a071 100644 --- a/components/grove_tb6612fng.rst +++ b/components/grove_tb6612fng.rst @@ -43,12 +43,12 @@ Configuration variables: - **id** (**Required**, :ref:`config-id`): The id to use for this TB6612FNG component. - **address** (*Optional*, int): The I²C address of the driver. Defaults to ``0x14``. -- **name** (*Required*, boolean): The name of the component +- **name** (**Required**, boolean): The name of the component .. grove_tb6612fng.run: ``grove_tb6612fng.run`` Action ------------------------------------- +------------------------------ Set the motor to spin by defining the direction and speed of the rotation, speed is a range from 0 to 255 @@ -67,7 +67,7 @@ Set the motor to spin by defining the direction and speed of the rotation, speed ``grove_tb6612fng.stop`` Action -------------------------------------- +------------------------------- Set the motor to stop motion but wont stop to spin in case there is a force pulling down, you would want to use break action if this is your case @@ -84,7 +84,7 @@ Set the motor to stop motion but wont stop to spin in case there is a force pull ``grove_tb6612fng.break`` Action --------------------------------------- +-------------------------------- Set the motor channel to be on break mode which it ensure the wheel wont spin even if forced or pushed diff --git a/components/light/images/lightwaverf.jpg b/components/images/lightwaverf.jpg similarity index 100% rename from components/light/images/lightwaverf.jpg rename to components/images/lightwaverf.jpg diff --git a/components/light/lightwaverf.rst b/components/lightwaverf.rst similarity index 98% rename from components/light/lightwaverf.rst rename to components/lightwaverf.rst index 10904467b..78bcac9e5 100644 --- a/components/light/lightwaverf.rst +++ b/components/lightwaverf.rst @@ -1,5 +1,5 @@ -LightWaveRF Switch -================== +LightWaveRF +=========== .. seo:: :description: LightWaveRF Switch Lights diff --git a/components/mqtt.rst b/components/mqtt.rst index 43e9d9880..4412fbc94 100644 --- a/components/mqtt.rst +++ b/components/mqtt.rst @@ -63,7 +63,7 @@ Configuration variables: messages. Should not contain trailing slash. Defaults to ````. - **log_topic** (*Optional*, :ref:`mqtt-message`): The topic to send MQTT log - messages to. Use `null` if you want to disable sending logs to MQTT. + messages to. Use ``null`` if you want to disable sending logs to MQTT. The ``log_topic`` has an additional configuration option: diff --git a/components/number/tuya.rst b/components/number/tuya.rst index 929e6fdf7..8db9bdf5c 100644 --- a/components/number/tuya.rst +++ b/components/number/tuya.rst @@ -69,8 +69,8 @@ Configuration variables: - **number_datapoint** (**Required**, int): The datapoint id number of the number. - **min_value** (**Required**, float): The minimum value this number can be. - **max_value** (**Required**, float): The maximum value this number can be. -- **step** (**Optional**, float): The granularity with which the number can be set. Defaults to 1. -- **multiply** (**Optional**, float): multiply the new value with this factor before sending the requests. +- **step** (*Optional*, float): The granularity with which the number can be set. Defaults to 1. +- **multiply** (*Optional*, float): multiply the new value with this factor before sending the requests. - All other options from :ref:`Number `. diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 8e042af9f..08c0dd893 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -217,7 +217,7 @@ Remote code selection (exactly one of these has to be included): it will be checked for a match to at least one of the two received packets. The main configuration scheme is below. - **first** (**Required**, uint32_t): The first 24-bit Coolix code to trigger on, see dumper output for more info. - - **second** (**Optional**, uint32_t): The second 24-bit Coolix code to trigger on, see dumper output for more info. + - **second** (*Optional*, uint32_t): The second 24-bit Coolix code to trigger on, see dumper output for more info. If not set, trigger on on only single non-strict packet, specified by the ``first`` parameter. - **dish**: Trigger on a decoded Dish Network remote code with the given data. diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index 7a8144ccc..ebccf040f 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -170,7 +170,7 @@ This :ref:`action ` sends one or two (stricted or not) 24-bit Coo Configuration variables: - **first** (**Required**, :ref:`templatable `, uint32_t): The first 24-bit Coolix code to send, see dumper output for more info. -- **second** (**Optional**, :ref:`templatable `, uint32_t): The second 24-bit Coolix code to send, see dumper output for more info. +- **second** (*Optional*, :ref:`templatable `, uint32_t): The second 24-bit Coolix code to send, see dumper output for more info. .. _remote_transmitter-transmit_dish: diff --git a/components/sensor/gcja5.rst b/components/sensor/gcja5.rst index 1f6e9de42..e03c11bd0 100644 --- a/components/sensor/gcja5.rst +++ b/components/sensor/gcja5.rst @@ -33,14 +33,26 @@ Based on continous runtime, the sensor is rated to last at least 5 years. Configuration variables: ------------------------ -- **pm_1_0_std** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter at standard particle. +- **pm_1_0** (*Optional*): Mass of particles with a diameter of 1 micrometres or less (μg/m^3). All options from :ref:`Sensor `. -- **pm_2_5_std** (*Optional*): Use the concentration of particulates of size less than 2.5µm in µg per cubic meter at standard particle. +- **pm_2_5** (*Optional*): Mass of particles with a diameter of 2.5 micrometres or less (μg/m^3). All options from :ref:`Sensor `. -- **pm_10_0_std** (*Optional*): Use the concentration of particulates of size less than 10.0µm in µg per cubic meter at standard particle. +- **pm_10_0** (*Optional*): Mass of particles with a diameter of 10 micrometres or less (μg/m^3). + All options from :ref:`Sensor `. +- **pm_10_0** (*Optional*): Mass of particles with a diameter of 10 micrometres or less (μg/m^3). + All options from :ref:`Sensor `. +- **pmc_0_3** (*Optional*): Count of particles with diameter > 0.3 um in 0.1 L of air (#/0.1L). + All options from :ref:`Sensor `. +- **pmc_0_5** (*Optional*): Count of particles with diameter > 0.5 um in 0.1 L of air (#/0.1L). + All options from :ref:`Sensor `. +- **pmc_1_0** (*Optional*): Count of particles with diameter > 1 um in 0.1 L of air (#/0.1L). + All options from :ref:`Sensor `. +- **pmc_2_5** (*Optional*): Count of particles with diameter > 2.5 um in 0.1 L of air (#/0.1L). + All options from :ref:`Sensor `. +- **pmc_5_0** (*Optional*): Count of particles with diameter > 5 um in 0.1 L of air (#/0.1L). + All options from :ref:`Sensor `. +- **pmc_10_0** (*Optional*): Count of particles with diameter > 10 um in 0.1 L of air (#/0.1L). All options from :ref:`Sensor `. -- **pm_1_0** (*Optional*): Use the concentration of particulates of size less than 1.0µm in µg per cubic meter under atmospheric environment. - See Also -------- diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index 0a032b55e..154d963b6 100644 --- a/components/sensor/ld2410.rst +++ b/components/sensor/ld2410.rst @@ -156,12 +156,14 @@ Configuration variables: - **detection_distance** (*Optional*, int): Distance in cm of target. All options from :ref:`Sensor `. - **gX** (*Optional*): Energies for the Xth gate (X => 0 to 8). + - **move_energy** (*Optional*, int): When in :ref:`engineering mode`, the move energy of the gate, otherwise ``unknown``. Value between ``0`` and ``100`` inclusive. All options from :ref:`Sensor `. - **still_energy** (*Optional*, int): When in :ref:`engineering mode`, the still energy of the gate, otherwise ``unknown``. Value between ``0`` and ``100`` inclusive. All options from :ref:`Sensor `. + - **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. Switch @@ -274,6 +276,7 @@ Configuration variables: Value between ``2`` and ``8`` inclusive. Defaults to ``8``. All options from :ref:`Number `. - **gX** (*Optional*): Thresholds for the Xth gate (X => 0 to 8). + - **move_threshold** (**Required**, int): Threshold for the gate for motion detection. Above this level for the considered gate (distance), movement detection will be triggered. Value between ``0`` and ``100`` inclusive. See default values below. @@ -282,6 +285,7 @@ Configuration variables: Above this level for the considered gate (distance), still detection will be triggered. Value between ``0`` and ``100`` inclusive. See default values below. All options from :ref:`Number `. + - **ld2410_id** (*Optional*, :ref:`config-id`): Manually specify the ID for the :doc:`ld2410` component if you are using multiple components. .. list-table:: Default values for gate threshold @@ -421,7 +425,7 @@ Configuration variables: - **id** (**Required**, :ref:`config-id`): The ID of the :doc:`ld2410` component to set. - **password** (**Required**, string, :ref:`templatable `): - The password to set. Case sensitive. Must be exactly 6 characters long. Default password is `HiLink`. + The password to set. Case sensitive. Must be exactly 6 characters long. Default password is ``HiLink``. To change the password from HA you can use the following example config: diff --git a/components/sensor/pmwcs3.rst b/components/sensor/pmwcs3.rst index e282e3de5..14e2e98e3 100644 --- a/components/sensor/pmwcs3.rst +++ b/components/sensor/pmwcs3.rst @@ -101,8 +101,8 @@ Configuration option: .. _sensor-PMWCS3NewI2cAddressAction: -``pmwcs3.newi2caddress`` Action ------------------------------------ +``pmwcs3.new_i2c_address`` Action +--------------------------------- A new I2C address can be set (for multi-probes cases for example) @@ -116,14 +116,14 @@ A new I2C address can be set (for multi-probes cases for example) # in some trigger on_...: - - sensor.pmwcs3_id.newi2caddress: + - sensor.pmwcs3_id.new_i2c_address: id: pmwcs3_id - newaddress: 0x65 + address: 0x65 Configuration options: - **id** (**Required**, :ref:`config-id`): The ID of the pmwcs3 sensor. -- **newaddress** (**Required**, int): New I2C address. +- **address** (**Required**, int): New I2C address. See Also -------- diff --git a/components/vbus.rst b/components/vbus.rst index ecc1d0f01..6ff20add9 100644 --- a/components/vbus.rst +++ b/components/vbus.rst @@ -195,18 +195,19 @@ Configuration variables: - **model** (**Required**): Specify the model of the connected controller. Choose one of the config values listed in the table of supported models above. -Supported sensors: + Supported models: -- for **deltasol_bs_plus**: ``relay1``, ``relay2``, ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``, ``collector_max``, ``collector_min``, ``collector_frost``, ``tube_collector``, ``recooling``, ``hqm``. -- for **deltasol_bs_2009**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``, ``frost_protection_active``. -- for **deltasol_c**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. -- for **deltasol_cs2**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. -- for **deltasol_cs_plus**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. + - **``deltasol_bs_plus``**: ``relay1``, ``relay2``, ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``, ``collector_max``, ``collector_min``, ``collector_frost``, ``tube_collector``, ``recooling``, ``hqm``. + - **``deltasol_bs_2009``**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``, ``frost_protection_active``. + - **``deltasol_c``**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. + - **``deltasol_cs2``**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. + - **``deltasol_cs_plus``**: ``sensor1_error``, ``sensor2_error``, ``sensor3_error``, ``sensor4_error``. + - **``custom``**: See below. All binary sensors are *Optional* and support all other options from :ref:`Binary Sensor `. -``Custom`` VBus sensors +``custom`` VBus sensors ----------------------- Devices on a VBus are identified with a source address. There can be multiple devices on the same bus, @@ -229,12 +230,11 @@ each device type has a different address. Configuration variables: -- **model** (**Required**): Set to ``custom``. - **dest** (**Required**): The ``DFA`` value corresponding to your device (see below). - **source** (**Required**): The address corresponding to ``your device model`` (see below). - **command** (**Required**): The ``command`` corresponding to your device (see below). - **sensors** (**Required**): A list of :ref:`Sensor ` definitions that include a ``lambda`` to do the decoding and return a ``float`` value. - + - **lambda** (**Required**, :ref:`lambda `): Code to parse a value from the incoming data packets and return it. The data packet is in a ``std::vector`` called ``x``. @@ -244,7 +244,6 @@ Configuration variables: Configuration variables: -- **model** (**Required**): Set to ``custom``. - **dest** (**Required**): The ``DFA`` value corresponding to your device (see below). - **source** (**Required**): The address corresponding to ``your device model`` (see below). - **command** (**Required**): The ``command`` corresponding to your device (see below). diff --git a/index.rst b/index.rst index e37eb7757..2efd3afbb 100644 --- a/index.rst +++ b/index.rst @@ -560,7 +560,7 @@ Light Components Tuya Dimmer, components/light/tuya, tuya.png Shelly Dimmer, components/light/shelly_dimmer, shellydimmer2.jpg Custom Light, components/light/custom, language-cpp.svg, dark-invert - LightWaveRF, components/light/lightwaverf, brightness-medium.svg + LightWaveRF, components/lightwaverf, brightness-medium.svg H-bridge Light, components/light/hbridge, brightness-medium.svg, dark-invert Sonoff D1 Dimmer, components/light/sonoff_d1, sonoff_d1.jpg diff --git a/schema_doc.py b/schema_doc.py index 8bd1feb04..36655981a 100644 --- a/schema_doc.py +++ b/schema_doc.py @@ -201,6 +201,14 @@ CUSTOM_DOCS = { "components/alarm_control_panel/index": { "Base Alarm Control Panel Configuration": "template.alarm_control_panel.schemas.CONFIG_SCHEMA", }, + "components/vbus": { + "custom VBus sensors": "vbus.platform.sensor.schemas.CONFIG_SCHEMA.types.custom", + "custom VBus binary sensors": "vbus.platform.binary_sensor.schemas.CONFIG_SCHEMA.types.custom", + }, + "components/spi": { + "Generic SPI device component:": "spi_device.schemas.CONFIG_SCHEMA" + }, + "components/libretiny": {"LibreTiny Platform": "bk72xx.schemas.CONFIG_SCHEMA"}, } REQUIRED_OPTIONAL_TYPE_REGEX = r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s"