diff --git a/Doxygen b/Doxygen index 4c832f84f..d8beab513 100644 --- a/Doxygen +++ b/Doxygen @@ -38,7 +38,7 @@ PROJECT_NAME = "ESPHome" # could be handy for archiving the generated documentation or if some version # control system is used. -PROJECT_NUMBER = 2022.11.4 +PROJECT_NUMBER = 2022.12.0b1 # Using the PROJECT_BRIEF tag one can provide an optional one line description # for a project that appears at the top of each page and should give viewer a diff --git a/Makefile b/Makefile index b64c732a5..bfa492d16 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2022.11.4 +ESPHOME_REF = 2022.12.0b1 .PHONY: html html-strict cleanhtml deploy help live-html Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png minify diff --git a/_static/changelog-2022.12.0.png b/_static/changelog-2022.12.0.png new file mode 100644 index 000000000..7eff5ae2e Binary files /dev/null and b/_static/changelog-2022.12.0.png differ diff --git a/_static/version b/_static/version index 506309702..50820cef9 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2022.11.4 \ No newline at end of file +2022.12.0b1 \ No newline at end of file diff --git a/changelog/2022.11.0.rst b/changelog/2022.11.0.rst index ac2301b55..ca168fb39 100644 --- a/changelog/2022.11.0.rst +++ b/changelog/2022.11.0.rst @@ -121,6 +121,11 @@ Release 2022.11.4 - December 1 - Dashboard fix relative url after login :esphomepr:`4103` by :ghuser:`ngraziano` - Fix queuing scripts not compiling :esphomepr:`4077` by :ghuser:`jesserockz` +Release 2022.11.5 - December 6 +------------------------------ + +- Fix board pin alias lookup :esphomepr:`4147` by :ghuser:`jesserockz` + Full list of changes -------------------- diff --git a/changelog/2022.12.0.rst b/changelog/2022.12.0.rst new file mode 100644 index 000000000..400390c91 --- /dev/null +++ b/changelog/2022.12.0.rst @@ -0,0 +1,163 @@ +ESPHome 2022.12.0 - 14th December 2022 +====================================== + +.. seo:: + :description: Changelog for ESPHome 2022.12.0. + :image: /_static/changelog-2022.12.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 3 + + ESP32, components/esp32, esp32.svg + Bluetooth Proxy, components/bluetooth_proxy, bluetooth.svg + SN74HC165 I/O Expander, components/sn74hc165, sn74hc595.jpg + +The festive holidays are coming early and bring you an ESPHome release 1 week earlier than normal. +This release does not bring a bunch of new components like most releases, but instead the focus +has been on upgrading the core Arduino and ESP-IDF versions used for the ESP32 based devices. + +The Bluetooth Proxy has also had a whole lot of work done by :ghuser:`bdraco` under the hood to +improve the stability, speed and reliability between Home Assistant and the bluetooth devices +that get proxied through. + +Full list of changes +-------------------- + +New Features +^^^^^^^^^^^^ + +- PID Climate - deadband and output sampling :esphomepr:`3254` by :ghuser:`patrickcollins12` (new-feature) + +New Components +^^^^^^^^^^^^^^ + +- Add sn74hc165 input shift register :esphomepr:`4151` by :ghuser:`jesserockz` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Update esp32 arduino and platform versions :esphomepr:`3564` by :ghuser:`jesserockz` (notable-change) (breaking-change) + +Notable Changes +^^^^^^^^^^^^^^^ + +- Update esp32 arduino and platform versions :esphomepr:`3564` by :ghuser:`jesserockz` (notable-change) (breaking-change) +- Update ESP-IDF and platform version :esphomepr:`3565` by :ghuser:`jesserockz` (notable-change) + +All changes +^^^^^^^^^^^ + +- Bump colorama from 0.4.5 to 0.4.6 :esphomepr:`4010` by :ghuser:`dependabot[bot]` +- Bump frenck/action-yamllint from 1.3.0 to 1.3.1 :esphomepr:`4011` by :ghuser:`dependabot[bot]` +- add two new icons :esphomepr:`3963` by :ghuser:`nagyrobi` +- Move CONF_INTERRUPT_PIN to const.py :esphomepr:`4014` by :ghuser:`jesserockz` +- Bump pyupgrade from 3.2.0 to 3.2.2 :esphomepr:`4017` by :ghuser:`dependabot[bot]` +- Add reset_reason text sensor to debug component :esphomepr:`3814` by :ghuser:`kuba2k2` +- remove unused variable last_save in total_daily_energy :esphomepr:`4039` by :ghuser:`bkaufx` +- Bump base image versions to latest :esphomepr:`4016` by :ghuser:`jesserockz` +- Add number device class support :esphomepr:`4042` by :ghuser:`frenck` +- Update esp32 arduino and platform versions :esphomepr:`3564` by :ghuser:`jesserockz` (notable-change) (breaking-change) +- Update esp32 boards list :esphomepr:`4056` by :ghuser:`jesserockz` +- Add Lolin S2 Mini board :esphomepr:`3264` by :ghuser:`jhamhader` +- Add pin aliases for upesy boards :esphomepr:`3794` by :ghuser:`uPesy` +- Bump pylint from 2.15.5 to 2.15.6 :esphomepr:`4058` by :ghuser:`dependabot[bot]` +- fix display_menu recursive schema gen :esphomepr:`4045` by :ghuser:`glmnet` +- Remove manual handling of ethernet power pin :esphomepr:`4062` by :ghuser:`jesserockz` +- Bump aioesphomeapi from 11.4.3 to 12.0.0 :esphomepr:`4070` by :ghuser:`dependabot[bot]` +- Update ESP-IDF and platform version :esphomepr:`3565` by :ghuser:`jesserockz` (notable-change) +- Always use brackets around single log macros :esphomepr:`4072` by :ghuser:`jesserockz` +- Midea ir templatable code :esphomepr:`4053` by :ghuser:`reidprojects` +- Boards: Adafruit QT Py ESP32 Pico/C3/S2 :esphomepr:`4064` by :ghuser:`jenscski` +- Dont set esp32 pin drive strength unless pin is set for output :esphomepr:`4075` by :ghuser:`jesserockz` +- Don't allow debug component if you don't have at least debug logging level :esphomepr:`4076` by :ghuser:`jesserockz` +- Remove a bunch of unnecessary pylint disabling :esphomepr:`4079` by :ghuser:`jesserockz` +- Update ESP32-audioI2S library :esphomepr:`4073` by :ghuser:`jesserockz` +- Add vector includes :esphomepr:`4080` by :ghuser:`jesserockz` +- Allow manually specifying binary file to OTA :esphomepr:`4054` by :ghuser:`jesserockz` +- Fix regressed 'esphome run' :esphomepr:`4094` by :ghuser:`mmakaay` +- Make parse_characteristics and parse_descriptors lazy to reduce memory pressure :esphomepr:`4063` by :ghuser:`bdraco` +- Speed up BLE connections :esphomepr:`4093` by :ghuser:`bdraco` +- Align BLE service logging :esphomepr:`4095` by :ghuser:`bdraco` +- Suppress logging unhandled ESP_BLE_AD_TYPE_INT_RANGE :esphomepr:`4096` by :ghuser:`bdraco` +- Make sure all BLE address strings are uppercase :esphomepr:`4097` by :ghuser:`bdraco` +- Add logging for BLE connection slots :esphomepr:`4098` by :ghuser:`bdraco` +- Fix registering for gatt notify when characteristic only support indicate :esphomepr:`4092` by :ghuser:`bdraco` +- Fix descriptors not being deleted :esphomepr:`4104` by :ghuser:`bdraco` +- Improve reliability of bluetooth active connections :esphomepr:`4049` by :ghuser:`bdraco` +- Always use generated api options from aioesphomeapi :esphomepr:`4116` by :ghuser:`jesserockz` +- Fix bluetooth_gatt_write_descriptor never getting a response :esphomepr:`4112` by :ghuser:`bdraco` +- Combine the scanner failure check so we only stop the scanner once :esphomepr:`4111` by :ghuser:`bdraco` +- Reduce memory needed to send the services list :esphomepr:`4110` by :ghuser:`bdraco` +- Avoid parsing characteristics and descriptors to reduce memory pressure :esphomepr:`4109` by :ghuser:`bdraco` +- Send device address type alongside ble advertisements :esphomepr:`4115` by :ghuser:`jesserockz` +- Remove uuid lookups from BLE read/write/notify characteristics :esphomepr:`4102` by :ghuser:`bdraco` +- Active BLE connection v3 :esphomepr:`4113` by :ghuser:`bdraco` +- preprocess out proto_enum_to_string if not needed :esphomepr:`4119` by :ghuser:`jesserockz` +- Bump aioesphomeapi from 12.0.0 to 12.2.0 :esphomepr:`4120` by :ghuser:`dependabot[bot]` +- Avoid parsing services with v3 connections without cache :esphomepr:`4117` by :ghuser:`bdraco` +- FIX: Unnecessary flash writes by ModbusSwitch component :esphomepr:`3648` by :ghuser:`jpeletier` +- Speed up uuid parsing when fetching the service list :esphomepr:`4121` by :ghuser:`bdraco` +- modbus_switch: honor switch:restore_mode :esphomepr:`4122` by :ghuser:`jpeletier` +- PID Climate - deadband and output sampling :esphomepr:`3254` by :ghuser:`patrickcollins12` (new-feature) +- Allow auto setting of ble client id if there is only 1 in config :esphomepr:`4125` by :ghuser:`jesserockz` +- fix RESTORE_INVERTED switch:restore_mode :esphomepr:`4129` by :ghuser:`jpeletier` +- Bump pylint from 2.15.6 to 2.15.7 :esphomepr:`4127` by :ghuser:`dependabot[bot]` +- Allow global setting of compile process limit :esphomepr:`4081` by :ghuser:`jesserockz` +- Bump flake8 from 5.0.4 to 6.0.0 :esphomepr:`4084` by :ghuser:`dependabot[bot]` +- Bump arduino pico and update wifi methods :esphomepr:`4144` by :ghuser:`jesserockz` +- Bump aioesphomeapi from 12.2.0 to 12.2.1 :esphomepr:`4133` by :ghuser:`dependabot[bot]` +- Bump esptool from 3.3.1 to 4.4 :esphomepr:`4071` by :ghuser:`dependabot[bot]` +- Fix mismatched flake8 version in pre-commit :esphomepr:`4145` by :ghuser:`jesserockz` +- Detect BLE stack unrecoverable state :esphomepr:`4128` by :ghuser:`bdraco` +- Bump pylint from 2.15.7 to 2.15.8 :esphomepr:`4148` by :ghuser:`dependabot[bot]` +- Fix crash with bluetooth tracker and esp-idf :esphomepr:`4140` by :ghuser:`bdraco` +- Use ENTITY_CATEGORY_CONFIG for sprinkler config switches. :esphomepr:`4141` by :ghuser:`schinckel` +- fix switch initialization :esphomepr:`4153` by :ghuser:`ssieb` +- Change 4 chip limit on sn74hc595 to 256 :esphomepr:`4108` by :ghuser:`jesserockz` +- Add reports fahrenheit to tuya climate :esphomepr:`4032` by :ghuser:`jesserockz` +- Allow dashboard import to pull complete file from github :esphomepr:`3982` by :ghuser:`jesserockz` +- Invalid config for waveshare models with no full_update_every :esphomepr:`4066` by :ghuser:`Nizzle` +- Add sn74hc165 input shift register :esphomepr:`4151` by :ghuser:`jesserockz` (new-integration) +- Fixed deep sleep for ESP32C3 :esphomepr:`4143` by :ghuser:`pistifonok` +- ESP32 IDF: Override toolchain-esp32ulp with espressifs own published version :esphomepr:`4155` by :ghuser:`jesserockz` +- Add API for dashboard to get boards list :esphomepr:`4154` by :ghuser:`jesserockz` +- Bump pytest-asyncio from 0.20.1 to 0.20.2 :esphomepr:`4019` by :ghuser:`dependabot[bot]` +- Bump pyupgrade from 3.2.2 to 3.3.0 :esphomepr:`4137` by :ghuser:`dependabot[bot]` +- Bump dessant/lock-threads from 3 to 4 :esphomepr:`4150` by :ghuser:`dependabot[bot]` +- Bump aioesphomeapi from 12.2.1 to 13.0.1 :esphomepr:`4149` by :ghuser:`dependabot[bot]` +- Bump esphome-dashboard to 20221207.0 :esphomepr:`4156` by :ghuser:`jesserockz` + +Past Changelogs +--------------- + +- :doc:`2022.11.0` +- :doc:`2022.10.0` +- :doc:`2022.9.0` +- :doc:`2022.8.0` +- :doc:`2022.6.0` +- :doc:`2022.5.0` +- :doc:`2022.4.0` +- :doc:`2022.3.0` +- :doc:`2022.2.0` +- :doc:`2022.1.0` +- :doc:`2021.12.0` +- :doc:`2021.11.0` +- :doc:`2021.10.0` +- :doc:`2021.9.0` +- :doc:`2021.8.0` +- :doc:`v1.20.0` +- :doc:`v1.19.0` +- :doc:`v1.18.0` +- :doc:`v1.17.0` +- :doc:`v1.16.0` +- :doc:`v1.15.0` +- :doc:`v1.14.0` +- :doc:`v1.13.0` +- :doc:`v1.12.0` +- :doc:`v1.11.0` +- :doc:`v1.10.0` +- :doc:`v1.9.0` +- :doc:`v1.8.0` +- :doc:`v1.7.0` diff --git a/components/climate/climate_ir.rst b/components/climate/climate_ir.rst index c60fa8b46..8484d2cc1 100644 --- a/components/climate/climate_ir.rst +++ b/components/climate/climate_ir.rst @@ -184,6 +184,7 @@ Configuration variables: .. note:: + - See :ref:`Transmit Midea` to send custom commands, including Follow Me mode. - See :ref:`Toshiba` below if you are looking for compatibility with Midea model MAP14HS1TBL or similar. diff --git a/components/climate/images/deadband1.png b/components/climate/images/deadband1.png new file mode 100644 index 000000000..a16a6edcf Binary files /dev/null and b/components/climate/images/deadband1.png differ diff --git a/components/climate/images/deadband2.png b/components/climate/images/deadband2.png new file mode 100644 index 000000000..1ef8ee649 Binary files /dev/null and b/components/climate/images/deadband2.png differ diff --git a/components/climate/pid.rst b/components/climate/pid.rst index add12f42c..4b9539d53 100644 --- a/components/climate/pid.rst +++ b/components/climate/pid.rst @@ -28,12 +28,17 @@ but there's a nice article explaining the function principle `here ` @@ -53,6 +58,38 @@ 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 + 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 + 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`` + which is no sampling/averaging. + +- **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 + 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``. + + - **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 `. @@ -75,6 +112,76 @@ 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 ``1s`` on the sensor. + 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. + +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. + +The most basic setup specifies the threshold around the target temperature as follows: + +.. code-block:: yaml + + default_target_temperature: 21°C + ... + deadband_parameters: + 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 +variation inside this deadband. How it limits depends on how you set the `Deadband Multipliers`_. + +.. figure:: images/deadband1.png + +Deadband Multipliers +******************** + +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. + +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. + +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 + + default_target_temperature: 21°C + ... + deadband_parameters: + 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 + kd_multiplier: 0.0 # derviative is turned off inside deadband + deadband_output_averaging_samples: 15 # average the output over 15 samples within the deadband + +.. figure:: images/deadband2.png + +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 +with temperature and controller stability. + .. _pid-autotune: Autotuning diff --git a/components/climate/tuya.rst b/components/climate/tuya.rst index cbc00eba7..10f61618d 100644 --- a/components/climate/tuya.rst +++ b/components/climate/tuya.rst @@ -60,6 +60,7 @@ Configuration variables: - **temperature_multiplier** (*Optional*, float): A multiplier to modify the incoming and outgoing temperature values - :ref:`see below `. - **eco_datapoint** (*Optional*, int): The datapoint id number of the eco mode state. - **eco_temperature** (*Optional*, float): The target temperature the controller uses while the eco mode is active. +- **reports_fahrenheit** (*Optional*, boolean): Set to ``true`` if the device reports temperatures in Fahrenheit. ESPHome expects all climate temperatures to be in Celcius, otherwise unexpected conversions will take place when it is published to Home Assistant. Defaults to ``false``. If the device has different multipliers for current and target temperatures, **temperature_multiplier** can be replaced with both of: diff --git a/components/debug.rst b/components/debug.rst index 5a3f928c8..96970fa8c 100644 --- a/components/debug.rst +++ b/components/debug.rst @@ -25,6 +25,8 @@ ESP heap memory (free space, maximum free block size and fragmentation level) an - platform: debug device: name: "Device Info" + reset_reason: + name: "Reset Reason" sensor: - platform: debug @@ -70,6 +72,13 @@ Configuration variables: - **name** (**Required**, string): The name of the sensor. - All other options from :ref:`Text Sensor `. +- **reset_reason** (*Optional*): Reports the last reboot reason in a human-readable form. + + Accepts these options: + + - **name** (**Required**, string): The name of the sensor. + - All other options from :ref:`Text Sensor `. + Sensor ------- Configuration variables: diff --git a/components/number/index.rst b/components/number/index.rst index 0ed07ad20..e3a708bcc 100644 --- a/components/number/index.rst +++ b/components/number/index.rst @@ -48,6 +48,9 @@ Configuration variables: See https://developers.home-assistant.io/docs/core/entity/number/#properties for a list of available options. Requires Home Assistant Core 2021.12 or newer. Defaults to ``"auto"``. +- **device_class** (*Optional*, string): The device class for the number. + See https://developers.home-assistant.io/docs/core/entity/number/#available-device-classes + for a list of available options. Automations: diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index 366a9b19f..f2a36e405 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -207,10 +207,16 @@ 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 |- + // Send a FollowMe code with the current temperature. + return {0xA4, 0x82, 0x48, 0x7F, (uint8_t)(id(temp_sensor).state + 1)}; Configuration variables: -- **code** (**Required**, list): The 40-bit Midea code to send as a list of hex or integers. +- **code** (**Required**, list, :ref:`templatable `): The 40-bit Midea code to send as a list of hex or integers. - All other options from :ref:`remote_transmitter-transmit_action`. ``remote_transmitter.transmit_nec`` Action diff --git a/components/sn74hc165.rst b/components/sn74hc165.rst new file mode 100644 index 000000000..28b365c54 --- /dev/null +++ b/components/sn74hc165.rst @@ -0,0 +1,66 @@ +SN74HC165 I/O Expander (shift register) +======================================= + +.. seo:: + :description: Instructions for setting up SN74HC165 shift registers as digital port expanders in ESPHome. + +The SN74HC165 component allows you to use SN74HC165 shift registers as I/O expanders (Input only, use SN74HC595 for outputs) +(`datasheet `__) in ESPHome. It uses 3 wires (optionally 4) for communication. + +Once configured, you can use any of the 8 pins for your projects. Up-to 256 shift registers can be daisy-chained +to provide more pins, without using more GPIO pins on the controller. They are linked by connecting pin Q of the closer +shift register to the pin QH of the next shift register. + + +.. code-block:: yaml + + # Example configuration entry + sn74hc165: + - id: sn74hc165_hub + clock_pin: GPIO16 + data_pin: GPIO17 + load_pin: GPIO4 + clock_inhibit_pin: GPIO18 + sr_count: 2 + + # Individual inputs + binary_sensor: + - platform: gpio + name: "SN74HC165 Pin #0" + pin: + sn74hc595: sn74hc165_hub + # Use pin number 0 + number: 0 + inverted: false + + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this SN74HC165 component. +- **data_pin** (**Required**, :ref:`Pin Schema `): Pin connected to SN74HC165 Serial Output (QH) input. +- **clock_pin** (**Required**, :ref:`Pin Schema `): Pin connected to SN74HC165 Clock (CLK) pin +- **load_pin** (**Required**, :ref:`Pin Schema `): Pin connected to SN74HC165 Load input (SH/LD) pin +- **clock_inhibit_pin** (**Required**, :ref:`Pin Schema `): Pin connected to SN74HC165 Clock Inhibit (CLK INH) pin +- **sr_count** (*Optional*, int): Number of daisy-chained shift registers, up-to 256. Defaults to ``1``. + + +Pin configuration variables: +**************************** + +- **SN74HC165** (**Required**, :ref:`config-id`): The id of the SN74HC165 component of the pin. +- **number** (**Required**, int): The pin number. +- **inverted** (*Optional*, boolean): If received value should be treated as inverted. + Defaults to ``false``. + +.. note:: + + Pin number 0 is Pin A on the SN74HC165 that is furthest away from the microcontroller. + +See Also +-------- + + +- :doc:`binary_sensor/gpio` +- :apiref:`SN74HC165/SN74HC165.h` +- :ghedit:`Edit` diff --git a/components/sn74hc595.rst b/components/sn74hc595.rst index 5bc063f86..a3614c001 100644 --- a/components/sn74hc595.rst +++ b/components/sn74hc595.rst @@ -8,7 +8,7 @@ The SN74HC595 component allows you to use SN74HC595 shift registers as I/O expan (`datasheet `__, `SparkFun`_) in ESPHome. It uses 3 wires (optionally 4) for communication. -Once configured, you can use any of the 8 pins for your projects. Up-to 4 shift registers can be daisy-chained +Once configured, you can use any of the 8 pins for your projects. Up-to 256 shift registers can be daisy-chained to provide more pins, without using more GPIO pins on the controller. Use of the OE pin is optional. If used, the pin should be pulled up externally. @@ -50,7 +50,7 @@ Configuration variables: - **clock_pin** (**Required**, :ref:`Pin Schema `): Pin connected to SN74HC595 SRCLK (SH_CP) pin - **latch_pin** (**Required**, :ref:`Pin Schema `): Pin connected to SN74HC595 RCLK (ST_CP) pin - **oe_pin** (*Optional*, :ref:`Pin Schema `): Pin connected to SN74HC595 OE pin -- **sr_count** (*Optional*, int): Number of daisy-chained shift registers, up-to 4. Defaults to ``1``. +- **sr_count** (*Optional*, int): Number of daisy-chained shift registers, up-to 256. Defaults to ``1``. Pin configuration variables: diff --git a/components/switch/gpio.rst b/components/switch/gpio.rst index 29ebf0819..4d69d4c5b 100644 --- a/components/switch/gpio.rst +++ b/components/switch/gpio.rst @@ -28,17 +28,6 @@ Configuration variables: GPIO pin to use for the switch. - **name** (**Required**, string): The name for the switch. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **restore_mode** (*Optional*): Control how the GPIO Switch attempts to restore state on bootup. - For restoring on ESP8266s, also see ``restore_from_flash`` in the - :doc:`esp8266 section `. - - - ``RESTORE_DEFAULT_OFF`` (Default) - Attempt to restore state and default to OFF if not possible to restore. - - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. - - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF. - - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON. - - ``ALWAYS_OFF`` - Always initialize the pin as OFF on bootup. - - ``ALWAYS_ON`` - Always initialize the pin as ON on bootup. - - **interlock** (*Optional*, list): A list of other GPIO switches in an interlock group. See :ref:`switch-gpio-interlocking`. - **interlock_wait_time** (*Optional*, :ref:`config-time`): For interlocking mode, set how long diff --git a/components/switch/index.rst b/components/switch/index.rst index 4fe558fa6..e14ddf99c 100644 --- a/components/switch/index.rst +++ b/components/switch/index.rst @@ -31,6 +31,22 @@ Configuration variables: - **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. +- **restore_mode** (*Optional*): Control how the switch attempts to restore state on bootup. + **NOTE** : Not all components consider **restore_mode**. Check the documentation of the specific component to understand how + this feature works for a particular component or device. + For restoring on ESP8266s, also see ``restore_from_flash`` in the + :doc:`esp8266 section `. + + - ``RESTORE_DEFAULT_OFF`` - Attempt to restore state and default to OFF if not possible to restore. + - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. + - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF. + - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON. + - ``ALWAYS_OFF`` - Always initialize the switch as OFF on bootup. + - ``ALWAYS_ON`` - Always initialize the switch as ON on bootup. + - ``DISABLED`` - Does nothing and leaves it up to the downstream platform component to decide. For example, the component could read hardware and determine the state, or have a specific configuration option to regulate initial state. + + Unless a specific platform defines another default value, the default is ``RESTORE_DEFAULT_OFF``. + - **on_turn_on** (*Optional*, :ref:`Action `): An automation to perform when the switch is turned on. See :ref:`switch-on_turn_on_off_trigger`. - **on_turn_off** (*Optional*, :ref:`Action `): An automation to perform diff --git a/components/switch/modbus_controller.rst b/components/switch/modbus_controller.rst index 8d0ead3e3..2b5b2541a 100644 --- a/components/switch/modbus_controller.rst +++ b/components/switch/modbus_controller.rst @@ -13,6 +13,9 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **name** (**Required**, string): The name of the sensor. +- **restore_mode** (*Optional*): See :ref:`Switch `, since this configuration variable is inherited. The default value for this setting is ``DISABLED`` (recommended). + ``DISABLED`` leaves the initial state up to the hardware: usually the state lives in the device and ESPHome does not need to remember it. The switch frontend will show an undetermined + state until the real state is retrieved from the device on the next refresh. Use any other setting if a reboot of your ESPHome device is tied to a reboot of the modbus device. - **register_type** (**Required**): type of the modbus register. - **address** (**Required**, int): start address of the first register in a range - **offset** (*Optional*, int): not required in most cases diff --git a/components/switch/output.rst b/components/switch/output.rst index daddefae1..b637b250c 100644 --- a/components/switch/output.rst +++ b/components/switch/output.rst @@ -29,16 +29,6 @@ Configuration variables: - **output** (**Required**, :ref:`config-id`): The ID of the output component to use. - **name** (**Required**, string): The name for the switch. - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- **restore_mode** (*Optional*): Control how the switch attempts to restore state on bootup. - For restoring on ESP8266s, also see ``esp8266_restore_from_flash`` in the - :doc:`esphome section `. - - - ``RESTORE_DEFAULT_OFF`` (Default) - Attempt to restore state and default to OFF if not possible to restore. - - ``RESTORE_DEFAULT_ON`` - Attempt to restore state and default to ON. - - ``RESTORE_INVERTED_DEFAULT_OFF`` - Attempt to restore state inverted from the previous state and default to OFF. - - ``RESTORE_INVERTED_DEFAULT_ON`` - Attempt to restore state inverted from the previous state and default to ON. - - ``ALWAYS_OFF`` - Always initialize the pin as OFF on bootup. - - ``ALWAYS_ON`` - Always initialize the pin as ON on bootup. - All other options from :ref:`Switch `. diff --git a/conf.py b/conf.py index cc8f42331..d6681ab82 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ author = "ESPHome" # built documents. # # The short X.Y version. -version = "2022.11" +version = "2022.12" # The full version, including alpha/beta/rc tags. -release = "2022.11.4" +release = "2022.12.0b1" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/guides/supporters.rst b/guides/supporters.rst index 471cb19e5..97de10c27 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -204,12 +204,10 @@ Contributors - `Dav-id (@dav-id-org) `__ - `DAVe3283 (@DAVe3283) `__ - `Dave Richer (@davericher) `__ -- `davestubbs (@davestubbs) `__ - `Dave T (@davet2001) `__ - `Dave Wongillies (@davewongillies) `__ - `David De Sloovere (@DavidDeSloovere) `__ - `David Beitey (@davidjb) `__ -- `davidmonro (@davidmonro) `__ - `David Zovko (@davidzovko) `__ - `Davy Landman (@DavyLandman) `__ - `Darren Tucker (@daztucker) `__ @@ -397,7 +395,7 @@ Contributors - `Lorenzo Ortiz (@Infinitte) `__ - `Dom (@Ing-Dom) `__ - `Ingurum (@Ingurum) `__ -- `Ivo Roefs (@Ironirc) `__ +- `Ivo Roefs (@ironirc) `__ - `irtimaled (@irtimaled) `__ - `Ingo Theiss (@itn3rd77) `__ - `Ivan Shvedunov (@ivan4th) `__ @@ -643,12 +641,14 @@ Contributors - `niklasweber (@niklasweber) `__ - `Niorix (@Niorix) `__ - `Zvonimir Haramustek (@nitko12) `__ +- `Dennis (@Nizzle) `__ - `nldroid (@nldroid) `__ - `Niccolò Maggioni (@nmaggioni) `__ - `Jan Sandbrink (@NobodysNightmare) `__ - `Łukasz Śliwiński (@nonameplum) `__ - `Greg Johnson (@notgwj) `__ - `nouser2013 (@nouser2013) `__ +- `Stephen Edgar (@ntwb) `__ - `Stanislav Meduna (@numo68) `__ - `Nuno Sousa (@nunofgs) `__ - `Maksym Lunin (@nut-code-monkey) `__ @@ -747,6 +747,7 @@ Contributors - `Jan Čermák (@sairon) `__ - `sascha lammers (@sascha432) `__ - `Søren Christian Aarup (@scaarup) `__ +- `Matthew Schinckel (@schinckel) `__ - `Nils Schulte (@Schnilz) `__ - `Wolle (@schreibfaul1) `__ - `Ville Skyttä (@scop) `__ @@ -903,4 +904,4 @@ Contributors - `Zack Barett (@zsarnett) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated December 1, 2022.* +*This page was last updated December 7, 2022.* diff --git a/index.rst b/index.rst index 67854888f..e72ccc8a6 100644 --- a/index.rst +++ b/index.rst @@ -680,6 +680,7 @@ Misc Components TCA9548A I²C Multiplexer, components/tca9548a, tca9548a.jpg MCP23SXX I/O Expander - SPI Bus, components/mcp23Sxx, mcp230xx.svg SX1509 I/O Expander, components/sx1509, sx1509.jpg + SN74HC165 I/O Expander, components/sn74hc165, sn74hc595.jpg SN74HC595 I/O Expander, components/sn74hc595, sn74hc595.jpg SIM800L, components/sim800l, sim800l.jpg DFPlayer, components/dfplayer, dfplayer.svg