diff --git a/components/climate/haier.rst b/components/climate/haier.rst index 62be42893..68a2b7685 100644 --- a/components/climate/haier.rst +++ b/components/climate/haier.rst @@ -5,7 +5,7 @@ Haier Climate :description: Instructions for setting up a Haier climate devices. :image: air-conditioner.svg -The `haier` climate platform creates a Haier climate device. +The ``haier`` climate platform creates a Haier climate device. The component can be used as a replacement of a Haier proprietary WiFi modules such as KZW-W001 and KZW-W002. This component requires a :ref:`uart` to be setup. @@ -33,7 +33,7 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **name** (**Required**, string): The name of the climate device. -- **update_interval** (*Optional*, :ref:`config-time`): How often device will be polled for status. Defaults to `5s`. +- **update_interval** (*Optional*, :ref:`config-time`): How often device will be polled for status. Defaults to ``5s``. - **supported_swing_modes** (*Optional*, list): List of supported swing modes. Possible values are: ``VERTICAL``, ``HORIZONTAL``, ``BOTH``. - All other options from :ref:`Climate `. @@ -42,10 +42,10 @@ Hardware setup Most units will have a dedicated USB-A port for Haier WiFi module. The physical USB port is in fact UART and does not "speak" USB protocol. -It uses four USB pins as 5V, GND, RX, TX. +It uses four USB pins as 5V, GND, RX, TX. You can use spare male USB cable to connect esphome device directly to the climate appliance. -Other units will not have USB ports, but will still probably have UART exposed somewhere on the main board. +Other units will not have USB ports, but will still probably have UART exposed somewhere on the main board. .. list-table:: Haier UART pinout :header-rows: 1 diff --git a/components/climate/index.rst b/components/climate/index.rst index ceebe2525..7a49b5e12 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -52,8 +52,8 @@ Configuration variables: - **temperature_step** (*Optional*, float): The granularity with which the target temperature can be controlled. Can be a single number, or split as below: - - **target_temperature** (**Required**, float) - - **current_temperature** (**Required**, float) + - **target_temperature** (**Required**, float): The granularity for target temperature + - **current_temperature** (**Required**, float): The granularity for current temperature Advanced options: diff --git a/components/climate/pid.rst b/components/climate/pid.rst index 38f711eec..32a317560 100644 --- a/components/climate/pid.rst +++ b/components/climate/pid.rst @@ -15,12 +15,12 @@ temperature to a user-specified setpoint. .. note:: PID is like cruise control in the cars: it keeps the car's speed constant by continuously - adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill, + adjusting the fuel quantity, based on load measurements. Eg when the car has to go up on a hill, the system notices the load increase thus immediately gives more fuel to the engine; and when it goes down on the other side of the hill, it notices the load decrease thus reduces or cuts off fuel completely so that car speed remains as constant as possible. The calculation takes in consideration - constants like car weight, wind resistance etc. - + constants like car weight, wind resistance etc. + This kind of math can be used for a heating or cooling system too, and an auto-tuning algorithm can help determining such constants, which mainly describe the heat loss of the room or building. Goal is to keep the temperature as constant as possible, and smooth out oscillations otherwise produced by @@ -47,12 +47,12 @@ but there's a nice article explaining the function principle `here ` @@ -72,37 +72,35 @@ Configuration variables: ``ki`` to prevent windup. Defaults to ``-1``. - **max_integral** (*Optional*, float): The minimum value of the integral term multiplied by ``ki`` to prevent windup. Defaults to ``1``. - - **starting_integral_term** (*Optional*, float): Set the initial output, by priming the integral - term. This is useful for when your system is rebooted and you don't want to wait + - **starting_integral_term** (*Optional*, float): Set the initial output, by priming the integral + term. This is useful for when your system is rebooted and you don't want to wait for it to get back equilibrium. - - **output_averaging_samples** (*Optional*, int): average the output over this many samples. PID controllers - can be quite sensitive to small changes on the input sensor. By averaging the last X output samples, - the temperature can be more stable. However, the larger the sampling window, the less responsive the + - **output_averaging_samples** (*Optional*, int): average the output over this many samples. PID controllers + can be quite sensitive to small changes on the input sensor. By averaging the last X output samples, + the temperature can be more stable. However, the larger the sampling window, the less responsive the PID controller. Defaults to ``1`` which is no sampling/averaging. - - **derivative_averaging_samples** (*Optional*, int): average the derivative term over this many samples. Many - controllers don't use the derivative term because it is sensitive to slight changes in the input sensor. - By taking an average of the derivative term it might become more useful for you. Most PID controllers call - this derivative filtering. The derivative term is used to pre-act so don't filter too much. Defaults to ``1`` + - **derivative_averaging_samples** (*Optional*, int): average the derivative term over this many samples. Many + controllers don't use the derivative term because it is sensitive to slight changes in the input sensor. + By taking an average of the derivative term it might become more useful for you. Most PID controllers call + this derivative filtering. The derivative term is used to pre-act so don't filter too much. Defaults to ``1`` which is no sampling/averaging. -- **deadband_parameters** (*Optional*): Enables a deadband to stabilise and minimise changes in the +- **deadband_parameters** (*Optional*): Enables a deadband to stabilise and minimise changes in the output when the temperature is close to the target temperature. See `Deadband Setup`_. - - **threshold_low/threshold_high** (**Required**, float): Specifies a high/low - threshold defining the deadband - around the target temperature. For instance with `default_target_temperature` of ``21°C`` and - thresholds of ``+/-0.5°C``, the deadband will be + - **threshold_high/threshold_low** (**Required**, float): Specifies a high/low + threshold defining the deadband around the target temperature. For instance with + ``default_target_temperature`` of ``21°C`` and thresholds of ``+/-0.5°C``, the deadband will be between ``20.5°C - 21.5°C``. The PID controller will limit output changes within the deadband. + - **kp_multiplier** (*Optional*, float): Set the ``kp`` gain when inside the deadband. Defaults to ``0``. + - **ki_multiplier** (*Optional*, float): Set the ``ki`` gain when inside the deadband. Defaults to ``0``. + - **kd_multiplier** (*Optional*, float): Set the ``kd`` gain when inside the deadband. Recommended this + is set to ``0``. Defaults to ``0``. - - **kp_multiplier** (**Optional**, float): Set the ``kp`` gain when inside the deadband. Defaults to ``0``. - - **ki_multiplier** (**Optional**, float): Set the ``ki`` gain when inside the deadband. Defaults to ``0``. - - **kd_multiplier** (**Optional**, float): Set the ``kd`` gain when inside the deadband. Recommended this - is set to 0. Defaults to ``0``. - - - **deadband_output_averaging_samples** (**Optional**, int): Typically when inside the deadband the PID Controller has - reached a state of equilibrium, so it advantageous to use a higher number of output samples + - **deadband_output_averaging_samples** (*Optional*, int): Typically when inside the deadband the PID Controller has + reached a state of equilibrium, so it advantageous to use a higher number of output samples like 10-30 samples. Defaults to ``1`` which is no sampling/averaging. - All other options from :ref:`Climate `. @@ -116,7 +114,7 @@ To set up a PID climate controller, you need a couple of components: - A :ref:`Sensor ` to read the current temperature (``sensor``). - At least one :ref:`float output ` to drive for heating or cooling (or both). - This could for example be a PWM output via :doc:`/components/output/sigma_delta` or :doc:`/components/output/slow_pwm` that drives a heating unit. + This could for example be a PWM output via :doc:`/components/output/sigma_delta_output` or :doc:`/components/output/slow_pwm` that drives a heating unit. Please note the output *must* be controllable with continuous value (not only ON/OFF, but any state in between for example 50% heating power). @@ -126,22 +124,22 @@ To set up a PID climate controller, you need a couple of components: The sensor should have a short update interval. The PID update frequency is tied to the update interval of the sensor. Set a short ``update_interval`` like ``5s`` on the sensor. - We recommend putting a filter on the sensor (see filters in :doc:`/components/sensor/index`) and + We recommend putting a filter on the sensor (see filters in :doc:`/components/sensor/index`) and using ``output_averaging_samples`` to calm the PID sensor from a noisy input sensor. Deadband Setup -------------- -A deadband is used to prevent the PID controller from further adjusting the power -once the temperature has settled within a range of the target temperature. +A deadband is used to prevent the PID controller from further adjusting the power +once the temperature has settled within a range of the target temperature. -We do this by specifying a high/low threshold of the target temperature. +We do this by specifying a high/low threshold of the target temperature. -To understand the benefit, consider a heating/cooling HVAC which is constantly -oscillating between heating and cooling as the thermostat records very minor -changes from +0.1º to -0.1º. Clearly this is undesirable and will cause wear -and tear as the HVAC oscillates. With a deadband in place the heater won't -activate until the thermostat breaches the low_threshold and the cooler won't activate -until the thermostat breaches the high_threshold. +To understand the benefit, consider a heating/cooling HVAC which is constantly +oscillating between heating and cooling as the thermostat records very minor +changes from +0.1º to -0.1º. Clearly this is undesirable and will cause wear +and tear as the HVAC oscillates. With a deadband in place the heater won't +activate until the thermostat breaches the low_threshold and the cooler won't activate +until the thermostat breaches the high_threshold. The most basic setup specifies the threshold around the target temperature as follows: @@ -153,7 +151,7 @@ The most basic setup specifies the threshold around the target temperature as fo threshold_high: 0.5°C threshold_low: -1.0°C -In this example the deadband is between ``20.0°C - 21.5°C``. The PID controller will limit any output +In this example the deadband is between ``20.0°C - 21.5°C``. The PID controller will limit any output variation inside this deadband. How it limits depends on how you set the `Deadband Multipliers`_. .. figure:: images/deadband1.png @@ -161,19 +159,19 @@ variation inside this deadband. How it limits depends on how you set the `Deadba Deadband Multipliers ******************** -Deadband Multipliers tell the controller how to operate when inside of the deadband. +Deadband Multipliers tell the controller how to operate when inside of the deadband. -Each of the p,i and d terms can be controlled using the kp, ki and kd multipliers. For instance, if the kp_multiplier -is set to 0.05 then the final proportional term will be set to 5% of its normal value within the deadband. +Each of the p,i and d terms can be controlled using the kp, ki and kd multipliers. For instance, if the kp_multiplier +is set to 0.05 then the final proportional term will be set to 5% of its normal value within the deadband. -If all of the multipliers are set to 0, then the controller will not adjust power at all within the +If all of the multipliers are set to 0, then the controller will not adjust power at all within the deadband. This is the default behavior. -Most deadband implementations set kp and ki multipliers to a small gain like ``0.05`` and set -derivative to 0. This means that the PID output will calmly make minor adjustments over a 20x longer -timeframe to stay within the deadband zone. +Most deadband implementations set kp and ki multipliers to a small gain like ``0.05`` and set +derivative to 0. This means that the PID output will calmly make minor adjustments over a 20x longer +timeframe to stay within the deadband zone. -To start with we recommend just setting the ``ki_multiplier`` to ``0.05`` (5%). Then +To start with we recommend just setting the ``ki_multiplier`` to ``0.05`` (5%). Then set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the deadband too often. .. code-block:: yaml @@ -184,7 +182,7 @@ set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the d threshold_high: 0.5°C threshold_low: -1.0°C kp_multiplier: 0.0 # proportional gain turned off inside deadband - ki_multiplier: 0.05 # integral accumulates at only 5% of normal ki + ki_multiplier: 0.05 # integral accumulates at only 5% of normal ki kd_multiplier: 0.0 # derviative is turned off inside deadband deadband_output_averaging_samples: 15 # average the output over 15 samples within the deadband @@ -192,8 +190,8 @@ set ``kp_multiplier`` to ``0.05`` (5%) if the controller is falling out of the d Deadband Output Averaging Samples ********************************* -Since we expect the PID Controller to be at equilibrium while inside the deadband, we can -average the output over a longer range of samples, like 15 samples. This helps even further +Since we expect the PID Controller to be at equilibrium while inside the deadband, we can +average the output over a longer range of samples, like 15 samples. This helps even further with temperature and controller stability. .. _pid-autotune: @@ -249,7 +247,7 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat device can reach. For example if the temperature of a room is to be controlled, the setpoint needs to be above the ambient temperature. If the ambient temperature is 20°C, the setpoint of the climate device should be set to at least ~24°C so that an oscillation can be induced. - + Also take care of external influences, like for example when room temperature is severely affected by outdoor weather like sun, if it starts to warm up the room in parallel with the heating autotune will likely fail or give false results. @@ -273,10 +271,10 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat .. note:: In the output above, the autotuner is driving the heating output at 100% and trying to reach 24.25 °C. - + This will continue for some time until data for 3 phases (6 crossings of the setpoint; or a bit more, depending on the data quality) have been acquired. - + The autotune algorithm may take a long time to complete, it depends on the time needed to reproduce the heating up and cooling down oscillations the required number of times. @@ -298,7 +296,7 @@ is automatically calculated. To do this, it needs to observe at least 3 oscillat As soon as the the autotune procedure finishes, the climate starts to work with the calculated parameters so that expected operation can be immediately verified. - + If satisfied, copy the values in ``control_parameters`` into your configuration: .. code-block:: yaml @@ -349,7 +347,7 @@ Configuration variables: Defaults to ``-1.0``. The ``positive_output`` and ``negative_output`` parameters can be used to compensate the heating or the -cooling process during the autotune, in the cases when they are not changing the temperature at the +cooling process during the autotune, in the cases when they are not changing the temperature at the same rate, resulting in a not symmetrical oscillation. The autotune result will print a message when it's recommended to repeat the entire procedure with such parameters configured. @@ -435,7 +433,7 @@ See Also - Åström, K. J. and T. Hägglund (1984a), 'Automatic tuning of simple regulators', Proceedings of IFAC 9th World Congress, Budapest, 1867-1872 - :doc:`/components/climate/index` -- :doc:`/components/output/sigma_delta` +- :doc:`/components/output/sigma_delta_output` - :doc:`/components/output/slow_pwm` - `Principles of PID `__ - :apiref:`pid/pid_climate.h` diff --git a/components/matrix_keypad.rst b/components/matrix_keypad.rst index c546e0261..caf143c24 100644 --- a/components/matrix_keypad.rst +++ b/components/matrix_keypad.rst @@ -7,8 +7,8 @@ Matrix keypad :description: Matrix key input panel The ``matrix_keypad`` component allows you to integrate pads which -have the keys connected at the intersection points of the rows and columns -of a matrix. +have the keys connected at the intersection points of the rows and columns +of a matrix. .. figure:: ../images/matrix_keypad.jpg :align: center @@ -44,14 +44,14 @@ Configuration variables: - **columns** (**Required**, list): A list of :ref:`pins ` where the vertical matrix lines are connected, in order from left to right. These pins need to be input capable with pullups enabled. If there is no internal pullup, then an external one is required. -- **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right, +- **keys** (*Optional*, string): The keys present on the matrix, from top left to bottom right, row by row. Required for ``key_collector`` and ``binary_sensor`` (if using key selection). -- **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are +- **has_diodes** (*Optional*, boolean): For pads where row pins are outputs, and the keys are connected with diodes. Defaults to ``false``. -Binary Sensors --------------- +Binary Sensor +------------- Individual keys can be added independently to ESPHome as ``binary_sensor``: @@ -82,7 +82,7 @@ Either the ``row`` and ``col`` parameters, or the ``key`` parameter has to be pr .. note:: - Automatic handling of multiple keys (e.g. PIN code entry) is possible with the + Automatic handling of multiple keys (e.g. PIN code entry) is possible with the the :ref:`Key Collector ` component. See Also diff --git a/components/mdns.rst b/components/mdns.rst index ed388627d..6b14f6dca 100644 --- a/components/mdns.rst +++ b/components/mdns.rst @@ -48,7 +48,7 @@ Configuration variables: - **disabled** (*Optional*, boolean): Set to true to disable mDNS usage. Defaults to false. - **services** (*Optional*, list): List of additional services to expose. - - **service** (*Required*, string): Name of extra service - - **protocol** (*Required*, string): Protocol of service (_udp or _tcp) - - **port** (*Optional*, int): Port number of extra service - - **txt** (*Optional*, mapping): Additional text records to add to service + - **service** (**Required**, string): Name of extra service. + - **protocol** (**Required**, string): Protocol of service (_udp or _tcp). + - **port** (*Optional*, int): Port number of extra service. + - **txt** (*Optional*, mapping): Additional text records to add to service. diff --git a/components/output/index.rst b/components/output/index.rst index 66f689fd6..7c00c46dc 100644 --- a/components/output/index.rst +++ b/components/output/index.rst @@ -98,7 +98,7 @@ This action turns the output with the given ID off when executed. *************************** This action sets the float output to the given level when executed. Note: This only -works with floating point outputs like :doc:`/components/output/esp8266_pwm`, :doc:`/components/output/ledc`, :doc:`/components/output/sigma_delta`, :doc:`/components/output/slow_pwm`. +works with floating point outputs like :doc:`/components/output/esp8266_pwm`, :doc:`/components/output/ledc`, :doc:`/components/output/sigma_delta_output`, :doc:`/components/output/slow_pwm`. .. code-block:: yaml diff --git a/components/output/sigma_delta.rst b/components/output/sigma_delta_output.rst similarity index 100% rename from components/output/sigma_delta.rst rename to components/output/sigma_delta_output.rst diff --git a/components/output/slow_pwm.rst b/components/output/slow_pwm.rst index 9c129f4d9..34d6c8aa7 100644 --- a/components/output/slow_pwm.rst +++ b/components/output/slow_pwm.rst @@ -70,7 +70,7 @@ Example: .. note:: If the duty cycle is not constrained to a maximum value, the - :doc:`/components/output/sigma_delta` component offers faster updates and + :doc:`/components/output/sigma_delta_output` component offers faster updates and greater control over the switching frequency. This is better for loads that need some time to fully change between on and off, like eletric thermal actuator heads or fans. @@ -81,7 +81,7 @@ See Also - :doc:`/components/output/index` - :doc:`/components/output/esp8266_pwm` - :doc:`/components/output/ledc` -- :doc:`/components/output/sigma_delta` +- :doc:`/components/output/sigma_delta_output` - :doc:`/components/light/monochromatic` - :doc:`/components/fan/speed` - :doc:`/components/power_supply` diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index 9c866f45f..640a3170c 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -204,13 +204,13 @@ Remote code selection (exactly one of these has to be included): - **canalsat**: Trigger on a decoded CanalSat remote code with the given data. - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - - **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` + - **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` - **command** (**Required**, int): The command to listen for. - **canalsatld**: Trigger on a decoded CanalSatLD remote code with the given data. - **device** (**Required**, int): The device to trigger on, see dumper output for more info. - - **address** (**Optional**, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` + - **address** (*Optional*, int): The address (or subdevice) to trigger on, see dumper output for more info. Defaults to ``0`` - **command** (**Required**, int): The command to listen for. - **coolix**: Trigger on a decoded Coolix remote code with the given data. diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index 43c7ff85d..62c36ae95 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -122,7 +122,7 @@ This :ref:`action ` sends a CanalSat infrared remote code to a re Configuration variables: - **device** (**Required**, int): The device to send to, see dumper output for more details. -- **address** (**Optional**, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` +- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` - **command** (**Required**, int): The command to send. - All other options from :ref:`remote_transmitter-transmit_action`. @@ -149,7 +149,7 @@ This :ref:`action ` sends a CanalSatLD infrared remote code to a Configuration variables: - **device** (**Required**, int): The device to send to, see dumper output for more details. -- **address** (**Optional**, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` +- **address** (*Optional*, int): The address (or subdevice) to send to, see dumper output for more details. Defaults to ``0`` - **command** (**Required**, int): The command to send. - All other options from :ref:`remote_transmitter-transmit_action`. @@ -283,7 +283,7 @@ This :ref:`action ` sends a 40-bit Midea code to a remote transmi on_...: - remote_transmitter.transmit_midea: code: [0xA2, 0x08, 0xFF, 0xFF, 0xFF] - + on_...: - remote_transmitter.transmit_midea: code: !lambda |- diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst index 09ef99c54..cc1640bcc 100644 --- a/components/sensor/ads1115.rst +++ b/components/sensor/ads1115.rst @@ -96,8 +96,8 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **resolution** (*Optional*, string): the resolution of this sensor. Defaults to ``16 bits``. - - **16 bits** - - **12 bits** + - ``16 bits`` + - ``12 bits`` Multiplexer and Gain @@ -105,10 +105,10 @@ Multiplexer and Gain .. note:: - As per (`datasheet `__, `Adafruit`_) Section 7.3 Note 2: + As per (`datasheet `__, `Adafruit`_) Section 7.3 Note 2: "No more than VDD + 0.3V must be applied to the analog inputs of the device." This means if you power the device with 3.3V, take care not to supply the 4 AIN pins with more than 3.6V. - + The ADS1115 has a multiplexer that can be configured to measure voltage between several pin configurations. These are: - ``A0_A1`` (between Pin 0 and Pin 1) @@ -128,11 +128,11 @@ Additionally, the ADS1115 has a Programmable Gain Amplifier (PGA) that can help - ``1.024`` (measures up to 1.024V) - ``0.512`` (measures up to 0.512V) - ``0.256`` (measures up to 0.256V) - + The ADS1115 can be used with defaults settings. When using an ADS1015, the resolution has to be specified and should be defined to ``12_BITS`` (or equivalent notations like ``12 BITS`` or ``12 bits``). - + See Also -------- diff --git a/components/sensor/ee895.rst b/components/sensor/ee895.rst index d56db1579..dfb5f2b7d 100644 --- a/components/sensor/ee895.rst +++ b/components/sensor/ee895.rst @@ -36,19 +36,19 @@ The :ref:`I²C Bus ` is required to be set up in your configuration for thi Configuration variables: ------------------------ -- **temperature** (*Required*): The information for the Temperature sensor. +- **temperature** (**Required**): The information for the Temperature sensor. - **name** (**Required**, string): The name for the temperature sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. -- **co2** (*Required*): The information for the CO₂ sensor. +- **co2** (**Required**): The information for the CO₂ sensor. - **name** (**Required**, string): The name for the CO₂eq sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Sensor `. -- **Pressure** (*Required*): The information for the Pressure sensor. +- **pressure** (**Required**): The information for the Pressure sensor. - **name** (**Required**, string): The name for the Pressure sensor. - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. diff --git a/components/sensor/index.rst b/components/sensor/index.rst index 3b15ff77e..3fb874c7e 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -415,7 +415,7 @@ Configuration variables: ``skip_initial`` **************** -A simple skip filter; `skip_initial: N` skips the first `N` sensor readings and passes on the +A simple skip filter; ``skip_initial: N`` skips the first ``N`` sensor readings and passes on the rest. This can be used when the sensor needs a few readings to 'warm up'. After the initial readings have been skipped, this filter does nothing. diff --git a/components/sensor/kuntze.rst b/components/sensor/kuntze.rst index b4727c693..6bd2372d7 100644 --- a/components/sensor/kuntze.rst +++ b/components/sensor/kuntze.rst @@ -5,7 +5,7 @@ Kuntze pool monitor :description: Instructions for setting up Kuntze pool monitor in ESPHome. :image: kuntze.jpg -The ``kuntze`` component allows you to integrate the Kuntze water measurement +The ``kuntze`` component allows you to integrate the Kuntze water measurement instrument in ESPHome. It uses :ref:`UART ` (ModBUS) for communication. Once configured you can use sensors as described below for your projects. @@ -19,25 +19,25 @@ Once configured you can use sensors as described below for your projects. Overview -------- -Kuntze devices have an RS485 (ModBUS RTU) communication port. Please see the +Kuntze devices have an RS485 (ModBUS RTU) communication port. Please see the Kuntze papers for the pinout of the RS485 connector on your unit. ModBUS line has to be terminated properly (with a ``120Ω`` resistor), and since this is likely your only unit connected to ESPHome, you should activate bus termination in the -Network menu (this component doesn't support multiple Kuntze devices on the same +Network menu (this component doesn't support multiple Kuntze devices on the same bus). ModBUS address should remain at factory default value. -The device communicates at ``19200`` baud ``8E1``. To connect to ESPHome, an RS485 -transceiver is needed. Choose a type which does not need a trigger to send and +The device communicates at ``19200`` baud ``8E1``. To connect to ESPHome, an RS485 +transceiver is needed. Choose a type which does not need a trigger to send and receive data, for example: .. figure:: ../../images/rs485.jpg -The controller connects to the UART of the MCU. For ESP32 GPIO `16` to `TXD` and `17` +The controller connects to the UART of the MCU. For ESP32 GPIO `16` to `TXD` and `17` to RXD are the default ones but any other pins can be used as well. 3.3V to VCC and GND to GND. .. warning:: - If you are using the :ref:`logger` make sure you are not using the same pins for it or otherwise disable the UART + If you are using the :ref:`logger` make sure you are not using the same pins for it or otherwise disable the UART logging with the ``baud_rate: 0`` option. Component @@ -66,14 +66,13 @@ A configured modbus component is optional. It will be automatically created. Configuration variables: -- **ph**: Measured pH value -- **temperature**: Measured temperature value -- **dis1**: Measured DIS 1 value -- **dis2**: Measured DIS 2 value -- **redox**: Measured Redox value -- **ec**: Measured EC value -- **oci**: Measured OCI value - +- **ph** (*Optional*): Measured pH value. +- **temperature** (*Optional*): Measured temperature value. +- **dis1** (*Optional*): Measured DIS 1 value. +- **dis2** (*Optional*): Measured DIS 2 value. +- **redox** (*Optional*): Measured Redox value. +- **ec** (*Optional*): Measured EC value. +- **oci** (*Optional*): Measured OCI value. All sensors are *Optional* and support all other options from :ref:`Sensor `. diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst index 813ef999b..751388ca2 100644 --- a/components/sensor/ld2410.rst +++ b/components/sensor/ld2410.rst @@ -75,7 +75,7 @@ and binary sensors. Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``. - **gX_move_threshold** (*Optional*, int): Threshold for the Xth gate for motion detection (X => 0 to 8). Above this level for the considered gate (distance), movement detection will be triggered. Defaults to ``see table below``. -- **gX _still_threshold** (*Optional*, int): Threshold for the Xth gate for still detection. (X => 0 to 8). +- **gX_still_threshold** (*Optional*, int): Threshold for the Xth gate for still detection. (X => 0 to 8). Above this level for the considered gate (distance), still detection will be triggered. Defaults to ``see table below``. .. list-table:: Default values for gate threshold diff --git a/components/vbus.rst b/components/vbus.rst index 9cb76c84b..72dd10720 100644 --- a/components/vbus.rst +++ b/components/vbus.rst @@ -176,8 +176,8 @@ All binary sensors are *Optional* and support all other options from :ref:`Binar ``Custom`` VBus sensors ----------------------- -Devices on a VBus are identified with a source address. There can be multiple devices on the same bus, -each device type has a different address. +Devices on a VBus are identified with a source address. There can be multiple devices on the same bus, +each device type has a different address. .. code-block:: yaml @@ -203,7 +203,7 @@ Configuration variables: - **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`. + The data packet is in a ``std::vector`` called ``x``. ``custom`` VBus binary sensors @@ -218,7 +218,7 @@ Configuration variables: - **binary_sensors** (**Required**): A list of :ref:`Binary Sensor ` definitions that include a ``lambda`` to do the decoding and return a ``bool`` 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`. + The data packet is in a ``std::vector`` called ``x``. To determine the correct values for the parameters above, visit `packet definitions list `__. In the search field of the **Packets** table, enter the name of your device. diff --git a/index.rst b/index.rst index 9dc0dd604..d18f343e4 100644 --- a/index.rst +++ b/index.rst @@ -499,7 +499,7 @@ Output Components BLE Binary Output, components/output/ble_client, bluetooth.svg Modbus Output, components/output/modbus_controller, modbus.png Custom Output, components/output/custom, language-cpp.svg - Sigma-Delta Output, components/output/sigma_delta, sigma-delta.svg + Sigma-Delta Output, components/output/sigma_delta_output, sigma-delta.svg Template Output, components/output/template, description.svg BP1658CJ, components/output/bp1658cj, bp1658cj.svg BP5758D, components/output/bp5758d, bp5758d.svg diff --git a/schema_doc.py b/schema_doc.py index 9dc5869eb..9607ff415 100644 --- a/schema_doc.py +++ b/schema_doc.py @@ -81,6 +81,8 @@ PLATFORMS_TITLES = { "Stepper": "stepper", "Switch": "switch", "I²C": "i2c", + "Media Player": "media_player", + "Microphone": "microphone", } CUSTOM_DOCS = { @@ -196,6 +198,8 @@ CUSTOM_DOCS = { }, } +REQUIRED_OPTIONAL_TYPE_REGEX = r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s" + def get_node_title(node): return list(node.traverse(nodes.title))[0].astext() @@ -250,7 +254,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): ] else: # sub component, e.g. output/esp8266_pwm - # components here might have a core / hub, eg. dallas, ads1115 # and then they can be a binary_sensor, sensor, etc. self.platform = self.path[1] @@ -775,7 +778,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): and (self.props or self.multi_component) and self.bullet_list_level > 1 ): - self.prop_stack.append((self.current_prop, node)) self.accept_props = True return @@ -844,7 +846,7 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): try: name_type = markdown[: markdown.index(": ") + 2] ntr = re.search( - r"(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s", + REQUIRED_OPTIONAL_TYPE_REGEX, name_type, re.IGNORECASE, ) @@ -875,7 +877,6 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): return markdown def update_prop(self, node, props): - prop_name = None for s_prop, n in self.prop_stack: @@ -901,10 +902,10 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): found = True if enum_docs: enum_docs = enum_docs.strip() - if "values_docs" not in inner: - inner["values_docs"] = {name: enum_docs} + if inner["values"][name] is None: + inner["values"][name] = {"docs": enum_docs} else: - inner["values_docs"][name] = enum_docs + inner["values"][name]["docs"] = enum_docs statistics.props_documented += 1 statistics.enums_good += 1 if not found: @@ -941,12 +942,19 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): return prop_name, False # Example properties formats are: - # **name** (**Required**, string): Long Description... - # **name** (*Optional*, string): Long Description... Defaults to ``value``. - # **name** (*Optional*): Long Description... Defaults to ``value``. + # **prop_name** (**Required**, string): Long Description... + # **prop_name** (*Optional*, string): Long Description... Defaults to ``value``. + # **prop_name** (*Optional*): Long Description... Defaults to ``value``. + # **prop_name** can be a list of names separated by / e.g. **name1/name2** (*Optional*) see climate/pid/ threshold_low/threshold_high + + PROP_NAME_REGEX = r"\*\*(\w*(?:/\w*)*)\*\*" + + FULL_ITEM_PROP_NAME_TYPE_REGEX = ( + r"\* " + PROP_NAME_REGEX + r"\s" + REQUIRED_OPTIONAL_TYPE_REGEX + ) ntr = re.search( - r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s", + FULL_ITEM_PROP_NAME_TYPE_REGEX, name_type, re.IGNORECASE, ) @@ -956,14 +964,14 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): param_type = ntr.group(7) else: s2 = re.search( - r"\* \*\*(\w*)\*\*\s(\(((\*\*Required\*\*)|(\*Optional\*))(,\s(.*))*)\):\s", + FULL_ITEM_PROP_NAME_TYPE_REGEX, markdown, re.IGNORECASE, ) if s2: # this is e.g. when a property has a list inside, and the list inside are the options. # just validate **prop_name** - s3 = re.search(r"\* \*\*(\w*)\*\*:\s", name_type) + s3 = re.search(r"\* " + PROP_NAME_REGEX + r"*:\s", name_type) if s3 is not None: prop_name = s3.group(1) else: @@ -977,61 +985,61 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): ) return prop_name, False - k = str(prop_name) + prop_names = str(prop_name) + for k in prop_names.split("/"): + config_var = props.get(k) - config_var = props.get(k) + if not config_var: + # Create docs for common properties when descriptions are overridden + # in the most specific component. - if not config_var: - # Create docs for common properties when descriptions are overridden - # in the most specific component. - - if k in [ - "id", - "name", - "internal", - # i2c - "address", - "i2c_id", - # polling component - "update_interval", - # uart - "uart_id", - # light - "effects", - "gamma_correct", - "default_transition_length", - "flash_transition_length", - "color_correct", - # display - "lambda", - "pages", - "rotation", - # spi - "spi_id", - "cs_pin", - # output (binary/float output) - "inverted", - "power_supply", - # climate - "receiver_id", - ]: - config_var = props[k] = {} - else: - if self.path[1] == "esphome" and k in [ - # deprecated esphome - "platform", - "board", - "arduino_version", - "esp8266_restore_from_flash", + if k in [ + "id", + "name", + "internal", + # i2c + "address", + "i2c_id", + # polling component + "update_interval", + # uart + "uart_id", + # light + "effects", + "gamma_correct", + "default_transition_length", + "flash_transition_length", + "color_correct", + # display + "lambda", + "pages", + "rotation", + # spi + "spi_id", + "cs_pin", + # output (binary/float output) + "inverted", + "power_supply", + # climate + "receiver_id", ]: - return prop_name, True - return prop_name, False + config_var = props[k] = {} + else: + if self.path[1] == "esphome" and k in [ + # deprecated esphome + "platform", + "board", + "arduino_version", + "esp8266_restore_from_flash", + ]: + return prop_name, True + return prop_name, False - desc = markdown[markdown.index(": ") + 2 :].strip() - if param_type: - desc = "**" + param_type + "**: " + desc + desc = markdown[markdown.index(": ") + 2 :].strip() + if param_type: + desc = "**" + param_type + "**: " + desc - config_var["docs"] = desc + config_var["docs"] = desc statistics.props_documented += 1 @@ -1084,7 +1092,11 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): def _find_extended(self, component, key): for extended in component.get("extends", []): - schema = self.visitor.get_component_schema(extended).get("schema", {}) + c = self.visitor.get_component_schema(extended) + if c.get("type") == "typed": + p = self.visitor.Props(self.visitor, c) + return p[key] + schema = c.get("schema", {}) for k, cv in schema.get("config_vars", {}).items(): if k == key: return SetObservable( @@ -1124,7 +1136,7 @@ class SchemaGeneratorVisitor(nodes.NodeVisitor): ) def _set_typed(self, inner_key, original_dict, key, value): - if inner_key == self.component.get("typed_key"): + if inner_key == self.component.get("typed_key", "type"): self.component[key] = value else: for tk, tv in self.component["types"].items():