diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index caae29e56..6dc7c8f1e 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,10 +1,10 @@ // https://github.com/microsoft/vscode-dev-containers/tree/v0.183.0/containers/python-3 { "name": "ESPHome - docs", - "image": "mcr.microsoft.com/vscode/devcontainers/python:0-3.6", + "image": "mcr.microsoft.com/vscode/devcontainers/python:0-3.10", "postCreateCommand": "pip3 install -r requirements.txt -r requirements_test.txt", "forwardPorts": [8000], - "settings": { + "settings": { "python.pythonPath": "/usr/local/bin/python", "python.languageServer": "Pylance", "python.linting.enabled": true, diff --git a/Doxygen b/Doxygen index f048e0343..1cb95e50d 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.12.7 +PROJECT_NUMBER = 2023.2.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 2c3377702..dde7b1cb7 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,5 @@ ESPHOME_PATH = ../esphome -ESPHOME_REF = 2022.12.7 +ESPHOME_REF = 2023.2.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-2023.2.0.png b/_static/changelog-2023.2.0.png new file mode 100644 index 000000000..fca4fc731 Binary files /dev/null and b/_static/changelog-2023.2.0.png differ diff --git a/_static/version b/_static/version index 2446c62fb..113da1adc 100644 --- a/_static/version +++ b/_static/version @@ -1 +1 @@ -2022.12.7 \ No newline at end of file +2023.2.0b1 \ No newline at end of file diff --git a/changelog/2022.12.0.rst b/changelog/2022.12.0.rst index bad16e934..ebe6fb940 100644 --- a/changelog/2022.12.0.rst +++ b/changelog/2022.12.0.rst @@ -94,6 +94,14 @@ Release 2022.12.7 - January 26 - Fix BME280 initialization before wifi setup :esphomepr:`4190` by :ghuser:`pxe-la` - Add a soft reset in setup() for bmp280 :esphomepr:`4329` by :ghuser:`melyux` +Release 2022.12.8 - January 27 +------------------------------ + +- Upgrades add-on base image to 6.2.0 :esphomepr:`4310` by :ghuser:`frenck` +- Migrate old-style S6 scripts to s6-rc.d :esphomepr:`4311` by :ghuser:`frenck` +- Refactor NGINX configuration of Home Assistant Add-on :esphomepr:`4312` by :ghuser:`frenck` +- Add Home Assistant integration discovery :esphomepr:`4328` by :ghuser:`frenck` + Full list of changes -------------------- diff --git a/changelog/2023.2.0.rst b/changelog/2023.2.0.rst new file mode 100644 index 000000000..b04a832bd --- /dev/null +++ b/changelog/2023.2.0.rst @@ -0,0 +1,213 @@ +ESPHome 2023.2.0 - 15th February 2023 +===================================== + +.. seo:: + :description: Changelog for ESPHome 2023.2.0. + :image: /_static/changelog-2023.2.0.png + :author: Jesse Hills + :author_twitter: @jesserockz + +.. imgtable:: + :columns: 4 + + PCA9554 I/O Expander, components/pca9554, pca9554a.jpg + BP1658CJ, components/output/bp1658cj, bp1658cj.svg + BP5758D, components/output/bp5758d, bp5758d.svg + SM2235, components/output/sm2235, sm2235.svg + SM2335, components/output/sm2335, sm2335.svg + PCF85063 RTC, components/time/pcf85063, clock-outline.svg + Matrix Keypad, components/matrix_keypad, matrix_keypad.jpg + X9C Potentiometer, components/output/x9c, x9c.jpg + EE895, components/sensor/ee895, EE895.png + HTE501, components/sensor/hte501, HTE501.png + TEE501, components/sensor/tee501, TEE501.png + Sigma-Delta Output, components/output/sigma_delta, sigma-delta.svg + Wiegand Reader, components/wiegand, wiegand.jpg + MiCS-4514, components/sensor/mics_4514, mics_4514.jpg + LD2410, components/sensor/ld2410, ld2410.jpg + Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg + + +Friendly Name +------------- + +ESPHome now supports setting a ``friendly_name`` which is sent to Home Assistant. This name will be used for the config entry, +the device name, and will be automatically prefixed to all of the entities where needed by Home Assistant. +If you opt to use this new friendly name, take note that you should remove any friendly name (substitition) that +you currently prepend onto entity ``name`` in YAML. + +.. code-block:: yaml + + esphome: + name: living-room + friendly_name: Living Room + + +Full list of changes +-------------------- + +New Components +^^^^^^^^^^^^^^ + +- Add Pca9554 component :esphomepr:`4192` by :ghuser:`hwstar` (new-integration) +- Add support for BP5758D LED driver :esphomepr:`4021` by :ghuser:`Cossid` (new-integration) +- Add support for BP1658CJ LED driver :esphomepr:`4020` by :ghuser:`Cossid` (new-integration) +- Add support for SM2235 and SM2335 LED drivers :esphomepr:`3924` by :ghuser:`Cossid` (new-integration) +- PCF85063 RTC chip :esphomepr:`3873` by :ghuser:`brogon` (new-integration) +- Add support for matrix keypads :esphomepr:`4241` by :ghuser:`ssieb` (new-integration) +- Add X9C Potentiometer component :esphomepr:`4183` by :ghuser:`EtienneMD` (new-integration) +- add key collector component :esphomepr:`4242` by :ghuser:`ssieb` (new-integration) +- Add support for EE895 :esphomepr:`3771` by :ghuser:`Stock-M` (new-integration) +- Add support for HTE501 :esphomepr:`3772` by :ghuser:`Stock-M` (new-integration) +- Add support for TEE501 :esphomepr:`3773` by :ghuser:`Stock-M` (new-integration) +- Implement a slow sigma-delta modulation based output :esphomepr:`4132` by :ghuser:`Cat-Ion` (new-integration) +- add Wiegand reader component :esphomepr:`4288` by :ghuser:`ssieb` (new-integration) +- Add MICS-4514 gas sensor :esphomepr:`4316` by :ghuser:`jesserockz` (new-integration) +- Add Ld2410 Support :esphomepr:`3919` by :ghuser:`sebcaps` (new-integration) +- add Resol VBus support :esphomepr:`3976` by :ghuser:`ssieb` (new-integration) + +Breaking Changes +^^^^^^^^^^^^^^^^ + +- Use NAN values for TSL2591 saturation :esphomepr:`3931` by :ghuser:`mdonoughe` (breaking-change) +- set_retry: add retries remaining parameter to the provided function :esphomepr:`4251` by :ghuser:`e28eta` (breaking-change) + +All changes +^^^^^^^^^^^ + +- Expose lambda action to reset a cycle in `slow_pwm` :esphomepr:`4158` by :ghuser:`johndbritton` +- climate: Add features to generic Toshiba model :esphomepr:`3912` by :ghuser:`zagor` +- Fix UUID displaying incorrectly in BLE Tracker logs :esphomepr:`4187` by :ghuser:`deunlee` +- Bump actions/stale from 6 to 7 :esphomepr:`4217` by :ghuser:`dependabot[bot]` +- Add Pca9554 component :esphomepr:`4192` by :ghuser:`hwstar` (new-integration) +- Bump aioesphomeapi from 13.0.1 to 13.0.2 :esphomepr:`4188` by :ghuser:`dependabot[bot]` +- Bump pytest-asyncio from 0.20.2 to 0.20.3 :esphomepr:`4164` by :ghuser:`dependabot[bot]` +- Handle deprecated sdkconfig option :esphomepr:`4204` by :ghuser:`mmakaay` +- feat: set a wider range for jpeg quality :esphomepr:`3872` by :ghuser:`sisco0` +- Bump black from 22.10.0 to 22.12.0 :esphomepr:`4167` by :ghuser:`dependabot[bot]` +- Use NAN values for TSL2591 saturation :esphomepr:`3931` by :ghuser:`mdonoughe` (breaking-change) +- Ili9341 8bit indexed mode pt2 :esphomepr:`2502` by :ghuser:`davet2001` +- Allow ignoring of failed Modbus response CRC :esphomepr:`3930` by :ghuser:`jangrewe` +- calc LEDC PWM Resolution with LEDC_TIMER_BIT_MAX :esphomepr:`3820` by :ghuser:`MFlasskamp` +- Component::set_retry updates :esphomepr:`3305` by :ghuser:`e28eta` +- Fix race condition in web_server scheduler on ESP32 :esphomepr:`3951` by :ghuser:`tomaszduda23` +- Fix saving light state for restore modes LIGHT_RESTORE_AND_OFF/ON :esphomepr:`4131` by :ghuser:`myhomeiot` +- Add precipitation device class :esphomepr:`4219` by :ghuser:`jesserockz` +- Add support for BP5758D LED driver :esphomepr:`4021` by :ghuser:`Cossid` (new-integration) +- Add support for BP1658CJ LED driver :esphomepr:`4020` by :ghuser:`Cossid` (new-integration) +- Add support for SM2235 and SM2335 LED drivers :esphomepr:`3924` by :ghuser:`Cossid` (new-integration) +- Fix broken PULSE_METER :esphomepr:`4199` by :ghuser:`cstaahl` +- PCF85063 RTC chip :esphomepr:`3873` by :ghuser:`brogon` (new-integration) +- Add API for dashboard to get boards list by platform :esphomepr:`4168` by :ghuser:`kuba2k2` +- Bump dashboard to 20221231.0 :esphomepr:`4248` by :ghuser:`balloob` +- Bump zeroconf to 0.47.1 :esphomepr:`4268` by :ghuser:`bdraco` +- Don't match words containing "id" :esphomepr:`4265` by :ghuser:`ssieb` +- Add support for matrix keypads :esphomepr:`4241` by :ghuser:`ssieb` (new-integration) +- Fix Template Switch restore_mode support :esphomepr:`4280` by :ghuser:`SharpEdgeMarshall` +- Correct decimals in Growatt energy reporting :esphomepr:`4277` by :ghuser:`rfpronk` +- Bump pylint from 2.15.8 to 2.15.10 :esphomepr:`4278` by :ghuser:`dependabot[bot]` +- Fix frequency limit for MCP9600 :esphomepr:`4276` by :ghuser:`jowgn` +- fix: json compilation error on rp2040 :esphomepr:`4273` by :ghuser:`kellertk` +- http_request: add request duration logging :esphomepr:`4272` by :ghuser:`stas-sl` +- Fix HttpRequestResponseTrigger :esphomepr:`4270` by :ghuser:`gmbuell` +- Fix HttpRequestResponseTrigger again :esphomepr:`4285` by :ghuser:`gmbuell` +- Add X9C Potentiometer component :esphomepr:`4183` by :ghuser:`EtienneMD` (new-integration) +- small DisplayBuffer images and font update :esphomepr:`4044` by :ghuser:`nielsnl68` +- Fix use of dangling pointers in esp-idf MQTT backend :esphomepr:`4239` by :ghuser:`aaliddell` +- Ensure we never write zero bytes :esphomepr:`4284` by :ghuser:`bdraco` +- Fix off-by-one bedjet fan speed (#3873) :esphomepr:`4292` by :ghuser:`jhansche` +- Clean up dashboard ping result post-rename/delete :esphomepr:`4170` by :ghuser:`balloob` +- Calculate PWM wrap dynamically whenever the frequency is changed :esphomepr:`4294` by :ghuser:`tradeJmark` +- Remove baud check in tuya dump_config :esphomepr:`4298` by :ghuser:`jesserockz` +- Add friendly_name to device :esphomepr:`4296` by :ghuser:`jesserockz` +- allow multiple dsmr :esphomepr:`4299` by :ghuser:`ssieb` +- Bump pytest from 7.2.0 to 7.2.1 :esphomepr:`4300` by :ghuser:`dependabot[bot]` +- Bump aioesphomeapi from 13.0.2 to 13.1.0 :esphomepr:`4301` by :ghuser:`dependabot[bot]` +- Display the configured esphome:comment on the WebServer :esphomepr:`4246` by :ghuser:`grillp` +- Allow 0xA8 ID for APDS9960 :esphomepr:`4287` by :ghuser:`reubn` +- Dont default CORE.friendly_name :esphomepr:`4305` by :ghuser:`jesserockz` +- add key collector component :esphomepr:`4242` by :ghuser:`ssieb` (new-integration) +- Tsl2591 gain publish :esphomepr:`4291` by :ghuser:`z3liff` +- Add support for EE895 :esphomepr:`3771` by :ghuser:`Stock-M` (new-integration) +- Add support for HTE501 :esphomepr:`3772` by :ghuser:`Stock-M` (new-integration) +- Add support for TEE501 :esphomepr:`3773` by :ghuser:`Stock-M` (new-integration) +- PCA9685, fix reset device and add option EXTCLK :esphomepr:`3845` by :ghuser:`standahabich` +- Implement a slow sigma-delta modulation based output :esphomepr:`4132` by :ghuser:`Cat-Ion` (new-integration) +- set_retry: add retries remaining parameter to the provided function :esphomepr:`4251` by :ghuser:`e28eta` (breaking-change) +- add Wiegand reader component :esphomepr:`4288` by :ghuser:`ssieb` (new-integration) +- Format docker/build.py :esphomepr:`4313` by :ghuser:`jesserockz` +- Add macro for sub sensor defining :esphomepr:`4315` by :ghuser:`jesserockz` +- Add friendly name in MDNS records if it is not empty :esphomepr:`4317` by :ghuser:`catalin2402` +- Add upload dashboard api :esphomepr:`4318` by :ghuser:`balloob` +- Bump esphome-dashboard to 20230120.0 :esphomepr:`4319` by :ghuser:`jesserockz` +- Hydreon: Use new device classes water and precipitation_intensity :esphomepr:`3993` by :ghuser:`functionpointer` +- Dont fail workflows if lint building fails :esphomepr:`4336` by :ghuser:`jesserockz` +- Add MICS-4514 gas sensor :esphomepr:`4316` by :ghuser:`jesserockz` (new-integration) +- Refactor esp32_ble_tracker to use esp32_ble core ble setup code :esphomepr:`4173` by :ghuser:`jesserockz` +- Add next_url to improv serial component config :esphomepr:`4343` by :ghuser:`jesserockz` (new-integration) +- Remove state class from uptime sensor :esphomepr:`4345` by :ghuser:`jesserockz` +- Fix esp32_ble_tracker setup priority :esphomepr:`4346` by :ghuser:`jesserockz` +- Fix in ble client base address parsing :esphomepr:`4347` by :ghuser:`jesserockz` +- Added support for ADS1015 :esphomepr:`4281` by :ghuser:`xvil` +- Fix "BLE server / advertising always on" :esphomepr:`4353` by :ghuser:`Mat931` +- Dump full parsed config to json-config api call :esphomepr:`4373` by :ghuser:`jesserockz` +- Fix pressure compensation in SCD4X :esphomepr:`4357` by :ghuser:`CarlosGS` +- Allow mdns services to be exposed by config :esphomepr:`4202` by :ghuser:`elupus` +- Allow final validate of uart stop bits and parity :esphomepr:`4376` by :ghuser:`jesserockz` +- Update sim800l.cpp :esphomepr:`4223` by :ghuser:`fbeek` +- SCD30 Added support for manual calibration :esphomepr:`4362` by :ghuser:`ftrueck` +- Add Ld2410 Support :esphomepr:`3919` by :ghuser:`sebcaps` (new-integration) +- add Resol VBus support :esphomepr:`3976` by :ghuser:`ssieb` (new-integration) +- Allow dashboard import to specify if api encryption key should be generated :esphomepr:`4393` by :ghuser:`jesserockz` +- modify SGP4X integration to report device_class as air quality index :esphomepr:`4327` by :ghuser:`alexd321` +- Remove unneeded validation for esp32 gpio pins :esphomepr:`4394` by :ghuser:`jesserockz` +- Fix shelly dimmer current sensor device class :esphomepr:`4385` by :ghuser:`trvrnrth` +- Added Ethernet Component for ESP IDF with JL1101 PHY driver :esphomepr:`4009` by :ghuser:`mobrembski` +- adds gpio INPUT_OUTPUT_OPEN_DRAIN :esphomepr:`4360` by :ghuser:`tomaszduda23` +- Merge components in packages :esphomepr:`3555` by :ghuser:`quentinmit` +- Update ld2410 logging :esphomepr:`4395` by :ghuser:`jesserockz` +- Update log for mics4514 to state 3 minute start time. :esphomepr:`4396` by :ghuser:`jesserockz` +- mDNS updates :esphomepr:`4399` by :ghuser:`jesserockz` +- Dont keep logging on improv start :esphomepr:`4401` by :ghuser:`jesserockz` +- Add support for Lippert LP sensors in mopeka_pro_check component :esphomepr:`4118` by :ghuser:`rperciaccante` +- climate: add support for quiet fan mode :esphomepr:`3609` by :ghuser:`MichaelMure` +- add MQTT preset support for Climate components :esphomepr:`4379` by :ghuser:`jmichiel` +- Added CanalSat and CanalSatLD protocol support :esphomepr:`3513` by :ghuser:`Emrvb` +- Remove unused manifest handler :esphomepr:`4169` by :ghuser:`balloob` +- Use the github-script action to call the workflow :esphomepr:`4400` by :ghuser:`jesserockz` +- Convert secrets constant to a tuple :esphomepr:`4245` by :ghuser:`balloob` +- Verify rel_path output is relative :esphomepr:`4247` by :ghuser:`balloob` + +Past Changelogs +--------------- + +- :doc:`2022.12.0` +- :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/changelog/index.rst b/changelog/index.rst index 69bb6cf0b..c53744b1a 100644 --- a/changelog/index.rst +++ b/changelog/index.rst @@ -2,7 +2,7 @@ Changelog ========= .. redirect:: - :url: /changelog/2022.12.0.html + :url: /changelog/2023.2.0.html .. toctree:: :glob: diff --git a/components/climate/index.rst b/components/climate/index.rst index 7461c0ecf..25c333cdc 100644 --- a/components/climate/index.rst +++ b/components/climate/index.rst @@ -95,8 +95,6 @@ Configuration variables: lower target temperature of a climate device with a two-point target temperature. - **target_temperature_high** (*Optional*, float, :ref:`templatable `): Set the higher target temperature of a climate device with a two-point target temperature. -- **away** (*Optional*, boolean, :ref:`templatable `): Set the away mode - of the climate device. - **preset** (*Optional*, string, :ref:`templatable `): Set the preset of the climate device. One of ``ECO``, ``AWAY``, ``BOOST``, ``COMFORT``, ``HOME``, ``SLEEP``, ``ACTIVITY``. @@ -104,7 +102,7 @@ Configuration variables: supported custom_presets of the climate device. - **fan_mode** (*Optional*, string, :ref:`templatable `): Set the fan mode of the climate device. One of ``ON``, ``OFF``, ``AUTO``, ``LOW``, ``MEDIUM``, ``HIGH``, ``MIDDLE``, - ``FOCUS``, ``DIFFUSE``. + ``FOCUS``, ``DIFFUSE``, ``QUIET``. - **custom_fan_mode** (*Optional*, string, :ref:`templatable `): Set one of the supported custom_fan_modes of the climate device. - **swing_mode** (*Optional*, string, :ref:`templatable `): Set the swing mode @@ -132,14 +130,19 @@ advanced stuff. id(my_climate).target_temperature_low // High Target temperature, type: float (degrees) id(my_climate).target_temperature_high - // Away mode, type: bool - id(my_climate).away // Fan mode, type: FanMode (enum) id(my_climate).fan_mode + // Custom Fan mode, type: string + id(my_climate).custom_fan_mode // Swing mode, type: SwingMode (enum) id(my_climate).swing_mode // Current action (currentl on idle, cooling, heating, etc.), ClimateAction (enum) id(my_climate).action + // Preset, type: Preset (enum) + id(my_climate).preset + // Custom Preset, type: string + id(my_climate).custom_preset + - ``.make_call``: Control the climate device @@ -170,10 +173,6 @@ MQTT options: - **action_state_topic** (*Optional*, string): The topic to publish climate device action changes to. -- **away_state_topic** (*Optional*, string): The topic to publish - away mode changes on. -- **away_command_topic** (*Optional*, string): The topic to receive - away mode commands on. - **current_temperature_state_topic** (*Optional*, string): The topic to publish current temperature changes to. - **fan_mode_state_topic** (*Optional*, string): The topic to publish @@ -184,6 +183,10 @@ MQTT options: climate device mode changes to. - **mode_command_topic** (*Optional*, string): The topic to receive climate device mode commands on. +- **preset_state_topic** (*Optional*, string): The topic to publish + preset changes to. +- **preset_command_topic** (*Optional*, string): The topic to receive + preset commands on. - **swing_mode_state_topic** (*Optional*, string): The topic to publish swing mode changes to. - **swing_mode_command_topic** (*Optional*, string): The topic to receive diff --git a/components/climate/thermostat.rst b/components/climate/thermostat.rst index 7b7e6fa3c..2c281f102 100644 --- a/components/climate/thermostat.rst +++ b/components/climate/thermostat.rst @@ -257,6 +257,8 @@ These should be used to control the fan only, if available. should direct its airflow at a specific area. - **fan_mode_diffuse_action** (*Optional*, :ref:`Action `): The action to call when the fan should direct its airflow over a broad area. +- **fan_mode_quiet_action** (*Optional*, :ref:`Action `): The action to call when the fan + should run at quiet speed. Swing Mode Actions ****************** @@ -331,6 +333,7 @@ experience and automation. - ``middle`` - ``focus`` - ``diffuse`` + - ``quiet`` - **swing_mode** (*Optional*, climate swing mode): The fan swing mode the thermostat should switch to when this preset is activated. If not specified, the thermostat's fan swing mode will remain unchanged when the preset is activated. One of: diff --git a/components/deep_sleep.rst b/components/deep_sleep.rst index a2c428b0d..3eb6b2d61 100644 --- a/components/deep_sleep.rst +++ b/components/deep_sleep.rst @@ -30,6 +30,10 @@ even Over The Air updates. run_duration: 10s sleep_duration: 10min +.. note:: + + ESP8266 that have an onboard USB chip (e.g. D1 mini) one the chips' control lines is connected to the RST pin. This enables the flasher can reboot the ESP when required. This may interfere with deep sleep on some devices and prevent the ESP from waking when it's powered through its USB connector. Powering the ESP from a separate 3.3V source connected to the 3.3V pin and GND will solve this issue. In these cases using a USB to TTL adapter will allow you to log ESP activity. + Configuration variables: ------------------------ diff --git a/components/display/ili9341.rst b/components/display/ili9341.rst index 07e86feb0..83a36c2a5 100644 --- a/components/display/ili9341.rst +++ b/components/display/ili9341.rst @@ -65,6 +65,8 @@ Configuration variables: - ``NONE`` (default) - ``GRAYSCALE`` + - ``IMAGE_ADAPTIVE`` +- **color_palette_images** (*Optional*): A list of image files that will be used to generate the color pallet for the display. This should only be used in conjunction with ``-color_palette: IMAGE_ADAPTIVE`` above. The images will be analysed at compile time and a custom color pallet will be created based on the most commonly occuring colors. A typical setting would be a sample image that represented the fully populated display. This can significantly improve the quality of displayed images. Note that these images are not stored on the ESP device, just the 256byte color pallet created from them. Configuration examples ********************** @@ -126,6 +128,32 @@ To configure a dimmable backlight: id: back_light restore_mode: ALWAYS_ON +To configure an image adaptive color pallet to show greater than 8 bit color depth with a RAM limited screen buffer: + +.. code-block:: yaml + + image: + - file: "sample_100x100.png" + id: myimage + resize: 100x100 + type: RGB24 + + display: + - platform: ili9341 + model: TFT 2.4 + cs_pin: 5 + dc_pin: 4 + led_pin: 15 + reset_pin: 22 + rotation: 90 + id: tft_ha + color_palette: IMAGE_ADAPTIVE + color_palette_images: + - "sample_100x100.png" + - "display_design.png" + lambda: |- + it.image(0, 0, id(myimage)); + See Also -------- diff --git a/components/display/index.rst b/components/display/index.rst index 04d8937b9..5d8e1067d 100644 --- a/components/display/index.rst +++ b/components/display/index.rst @@ -170,6 +170,13 @@ Next, create a ``font:`` section in your configuration: id: roboto size: 20 + - file: + type: gfonts + family: Roboto + weight: 900 + id: font2 + size: 16 + - file: "fonts/tom-thumb.bdf" id: tomthumb @@ -479,6 +486,7 @@ Configuration variables: - **traces** (*Optional*): Use this to specify more than a single trace. Trace specific fields: + - **sensor** (*Optional*, :ref:`config-id`): The sensor value to plot - **line_thickness** (*Optional*): Defaults to 3 - **line_type** (*Optional*): Specifies the plot line-type. Can be one of the following: ``SOLID``, ``DOTTED``, ``DASHED``. Defaults to ``SOLID``. diff --git a/components/display/st7789v.rst b/components/display/st7789v.rst index 39a36ef54..642e98614 100644 --- a/components/display/st7789v.rst +++ b/components/display/st7789v.rst @@ -217,35 +217,38 @@ appropriate lines of C code in the lambda to hide or show the image or text as y name: "T-Display Button Input 1" id: tdisplay_button_input_1 - # We can still control the backlight independently - switch: - - platform: gpio - pin: GPIO4 - name: "Backlight" - id: backlight + # Allow dimmable control of the backlight (pin GPIO4) + output: + - platform: ledc + pin: GPIO4 + id: gpio4 - image: - - file: "image.png" - id: my_image - resize: 200x200 - type: RGB24 + light: + - platform: monochromatic + output: gpio4 + name: "Backlight" - time: - - platform: homeassistant - id: esptime + image: + - file: "image.png" + id: my_image + resize: 200x200 + type: RGB24 - spi: - clk_pin: GPIO18 - mosi_pin: GPIO19 + time: + - platform: homeassistant + id: esptime - display: - - platform: st7789v - backlight_pin: GPIO4 - cs_pin: GPIO5 - dc_pin: GPIO16 - reset_pin: GPIO23 - rotation: 270 - lambda: |- + spi: + clk_pin: GPIO18 + mosi_pin: GPIO19 + + display: + - platform: st7789v + cs_pin: GPIO5 + dc_pin: GPIO16 + reset_pin: GPIO23 + rotation: 270 + lambda: |- it.rectangle(0, 0, it.get_width(), it.get_height(), id(my_blue)); it.rectangle(0, 20, it.get_width(), it.get_height(), id(my_blue)); // header bar @@ -263,6 +266,7 @@ appropriate lines of C code in the lambda to hide or show the image or text as y it.print(235, 5, id(helvetica_12), id(my_red), TextAlign::TOP_RIGHT, "Offline"); } + See Also -------- diff --git a/components/ethernet.rst b/components/ethernet.rst index f14f0922a..cd49e1308 100644 --- a/components/ethernet.rst +++ b/components/ethernet.rst @@ -31,8 +31,16 @@ This component and the Wi-Fi component may **not** be used simultaneously, even Configuration variables: ------------------------ -- **type** (**Required**, string): The type of LAN chipset/phy. Must be one of - ``LAN8720``, ``RTL8201``, ``DP83848`` or ``IP101``. +- **type** (**Required**, string): The type of LAN chipset/phy. + + Supported chipsets are: + + - ``LAN8720`` + - ``RTL8201`` + - ``DP83848`` + - ``IP101`` + - ``JL1101`` + - **mdc_pin** (**Required**, :ref:`config-pin`): The MDC pin of the board. Usually this is ``GPIO23``. - **mdio_pin** (**Required**, :ref:`config-pin`): The MDIO pin of the board. @@ -122,7 +130,7 @@ Configuration examples clk_mode: GPIO0_OUT phy_addr: 0 power_pin: GPIO04 - + **Wireless Tag WT32-ETH01** and **SMLIGHT SLZB-06 PoE Zigbee**: .. code-block:: yaml @@ -146,7 +154,7 @@ Configuration examples clk_mode: GPIO0_IN phy_addr: 1 power_pin: GPIO5 - + **AiThinker ESP32-G Gateway**: .. code-block:: yaml diff --git a/components/http_request.rst b/components/http_request.rst index 791936439..ef7f7da45 100644 --- a/components/http_request.rst +++ b/components/http_request.rst @@ -63,9 +63,10 @@ This :ref:`action ` sends a GET request. on_response: then: - logger.log: - format: 'Response status: %d' + format: 'Response status: %d, Duration: %u ms' args: - status_code + - duration_ms # Short form - http_request.get: https://esphome.io @@ -135,8 +136,10 @@ Configuration variables: ``on_response`` Trigger ----------------------- -This automation will be triggered when the HTTP request is finished and will supply the -http response code in parameter ``status_code`` as an ``int``. +This automation will be triggered when the HTTP request is finished and will supply these parameters: + +* ``status_code`` as ``int`` - http response code +* ``duration_ms`` as ``uint32`` - time taken to complete the request .. code-block:: yaml @@ -148,9 +151,10 @@ http response code in parameter ``status_code`` as an ``int``. on_response: then: - logger.log: - format: "Response status: %d" + format: "Response status: %d, Duration: %u ms" args: - status_code + - duration_ms .. _http_request-examples: diff --git a/components/improv_serial.rst b/components/improv_serial.rst index 5ba3ae0bd..206df451a 100644 --- a/components/improv_serial.rst +++ b/components/improv_serial.rst @@ -20,7 +20,26 @@ The ``improv_serial`` component requires the serial ``logger`` to be configured. improv_serial: -No configuration variables. +Configuration variables +----------------------- + +- **next_url** (*Optional*, url): A URL that can be used to forward the user to after setting credentials with improv. + +Next URL +-------- + +Substitutions can be inserted into the URL, such as project name and version and there are some special substitutions +that can be performed by ESPHome when wrapped in double braces ``{{ }}``: + +- **device_name**: This will substitute the device name including the mac address suffix. +- **ip_address**: This will substitute the IP address of the device. +- **esphome_version**: This will substitute the version of ESPHome that is running on the device. + +.. code-block:: yaml + + # Example next_url + improv_serial: + next_url: http://example.com/?device_name={{device_name}}&ip_address={{ip_address}}&esphome_version={{esphome_version}} See Also -------- diff --git a/components/key_collector.rst b/components/key_collector.rst new file mode 100644 index 000000000..ff9db7e3d --- /dev/null +++ b/components/key_collector.rst @@ -0,0 +1,94 @@ +.. _key_collector: + +Key collector component +======================= + +.. seo:: + :description: Key collector component + +The ``key_collector`` component collects key presses from +components like :ref:`matrix_keypad` or ``wiegand``. It allows you to process +key sequences and treat them as one, for example to allow inputting of +a PIN code or a passkey. The component outputs the result of the keypress +sequence as a variable usable in automations. + + +Component +--------- + +.. code-block:: yaml + + # Example configuration entry + key_collector: + - id: pincode_reader + source_id: mykeypad + min_length: 4 + max_length: 4 + end_keys: "#" + end_key_required: true + back_keys: "*" + clear_keys: "C" + allowed_keys: "0123456789" + timeout: 5s + on_progress: + - logger.log: + format: "input progress: '%s', started by '%c'" + args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ] + on_result: + - logger.log: + format: "input result: '%s', started by '%c', ended by '%c'" + args: [ 'x.c_str()', "(start == 0 ? '~' : start)", "(end == 0 ? '~' : end)" ] + on_timeout: + - logger.log: + format: "input timeout: '%s', started by '%c'" + args: [ 'x.c_str()', "(start == 0 ? '~' : start)" ] + + + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): Set the ID of this entry for use in lambdas. +- **source_id** (*Optional*, :ref:`config-id`): The ID of the key input device. +- **min_length** (*Optional*, integer): The minimal length of the desired key sequence. Below + this, ``on_result`` automation will not trigger even if any of the ``end_keys`` was pressed. +- **max_length** (*Optional*, integer): The maximum length of the desired key sequence, after + which the sequence will trigger the ``on_result`` automation witout having to press any of the ``end_keys`` +- **end_keys** (*Optional*, string): Keys used to *enter* the sequence. +- **end_key_required** (*Optional*, boolean): Only trigger ``on_result`` automation when one of + the ``end_keys`` was pressed. Defaults to ``false``. +- **back_keys** (*Optional*, string): Keys used to delete the last pressed key. Like *Backspace* on a keyboard. +- **clear_keys** (*Optional*, string): Keys used to entirely clear the sequence, all the pressed keys. +- **allowed_keys** (*Optional*, string): Keys allowed to be used. If not specified, then any otherwise + unused keys will be allowed. +- **timeout** (*Optional*, :ref:`config-time`): Timeout after which to cancel building the sequence and delete all the keys. + +At least one of ``end_keys`` or ``max_length`` have to be specified. The rest are optional. +If both ``end_keys`` and ``max_length`` are specified, then once ``max_length`` keys are collected, no more will be +accepted until an end key is pressed. + +Automations: +------------ + +- **on_progress** (*Optional*, :ref:`Automation `): An automation to perform + when keys are pressed. The current sequence of pressed keys is placed in a ``vector`` variable ``x`` + and ``start`` holds the start key that activated this sequence or else ``0``. + Useful if you want to have a display showing the current value or number of key presses, + or a speaker beeping when keys are being pressed. +- **on_result** (*Optional*, :ref:`Automation `): An automation to perform + when the sequence has been finished (eg. ``max_length`` has been reached or one of + the ``end_keys`` was pressed). The finalized key sequence is placed in a ``vector`` variable ``x``, + ``start`` holds the start key that activated this sequence or else ``0``, and + ``end`` holds the end key that terminated this sequence or else ``0``. +- **on_timeout** (*Optional*, :ref:`Automation `): An automation to perform + if the timeout happens. The current sequence of pressed keys is placed in a ``vector`` variable ``x`` + and ``start`` holds the start key that activated this sequence or else ``0``. + + +See Also +-------- + +- :doc:`/components/matrix_keypad` + +.. - :doc:`/components/wiegand` + +- :ghedit:`Edit` diff --git a/components/light/index.rst b/components/light/index.rst index 26f680a33..6dd4506dd 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -203,6 +203,13 @@ them to zero. // perform action: call.perform(); + Shorter example using auto call , call.set_brightness and call.perform. + + .. code-block:: cpp + + id(light_1).turn_on().set_brightness(1.0).perform(); + + .. note:: The ``red``, ``green`` and ``blue`` values only control the color of the light, not its diff --git a/components/matrix_keypad.rst b/components/matrix_keypad.rst new file mode 100644 index 000000000..3fd3e579f --- /dev/null +++ b/components/matrix_keypad.rst @@ -0,0 +1,92 @@ +.. _matrix_keypad: + +Matrix keypad +============= + +.. seo:: + :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. + +.. figure:: ../images/matrix_keypad.jpg + :align: center + + +Component +--------- + +.. code-block:: yaml + + # Example configuration entry + matrix_keypad: + id: mykeypad + rows: + - pin: 21 + - pin: 19 + - pin: 18 + - pin: 5 + columns: + - pin: 17 + - pin: 16 + - pin: 4 + - pin: 15 + keys: "123A456B789C*0#D" + has_diodes: false + + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): Set the ID of this device for use in lambdas. +- **rows** (**Required**, list): A list of :ref:`pins ` where the horrizontal + matrix lines are connected, in order from top to bottom. +- **columns** (**Required**, list): A list of :ref:`pins ` where the vertical + matrix lines are connected, in order from left to 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 + connected with diodes. Defaults to ``false``. + + +Binary Sensors +-------------- + +Individual keys can be added independently to ESPHome as ``binary_sensor``: + +.. code-block:: yaml + + # Example configuration entry + binary_sensor: + - platform: matrix_keypad + keypad_id: mykeypad + id: key4 + row: 1 + col: 0 + - platform: keypad + id: keyA + key: A + +Configuration variables: + +- **keypad_id** (*Optional*, :ref:`config-id`): The ID of the keypad to process keypresses from. +- **id** (*Optional*, :ref:`config-id`): Set the ID of this key for use in lambdas. +- **row** (*Optional*, integer): The row of the key. +- **col** (*Optional*, integer): The column of the key. +- **key** (*Optional*, string): The key from ``keys`` configuration entry above. +- All other options from :ref:`Binary Sensor `. + +Either the ``row`` and ``col`` parameters, or the ``key`` parameter has to be provided. + + +.. note:: + + Automatic handling of multiple keys (e.g. PIN code entry) is possible with the + the :ref:`Key Collector ` component. + +See Also +-------- + +- :doc:`/components/key_collector` +- :ref:`Binary Sensor ` +- :ghedit:`Edit` diff --git a/components/mdns.rst b/components/mdns.rst index 4abc18dbc..ed388627d 100644 --- a/components/mdns.rst +++ b/components/mdns.rst @@ -22,7 +22,33 @@ It is recommended to leave mDNS enabled. .. _mdns-configuration_variables: + +Services: +--------- + +Additional mdns services can be added as exposed by the esphome node. + +.. code-block:: yaml + + # Example configuration entry with additional service + mdns: + services: + - service: "_custom_service" + protocol: "_tcp" + port: 8080 + txt: + txt_key_1: txt_value_1 + +.. _mdns-custom_services: + + 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 diff --git a/components/modbus.rst b/components/modbus.rst index 3b1b07695..21f319560 100644 --- a/components/modbus.rst +++ b/components/modbus.rst @@ -31,6 +31,8 @@ Configuration variables: If multiple modbus devices are attached increasing this value can help avoiding to to overlapping reads. When 2 devices are sending a command at the same the response read from uart can't be assigned to the proper design. This value defines the maximum queuing time for a command before it is send anyways. + +- **disable_crc** (*Optional*, boolean): Ignores a bad CRC if set to ``true``. Defaults to ``false`` See Also diff --git a/components/output/bp1658cj.rst b/components/output/bp1658cj.rst new file mode 100644 index 000000000..a961e7f33 --- /dev/null +++ b/components/output/bp1658cj.rst @@ -0,0 +1,168 @@ +BP1658CJ LED driver +=================== + +.. seo:: + :description: Instructions for setting up BP1658CJ LED drivers in ESPHome. + :keywords: BP1658CJ, Orein OS0100411267 RGBCT Bulb + +.. _bp1658cj-component: + +Component/Hub +------------- + +The BP1658CJ component represents a BP1658CJ LED diver chain in +ESPHome. Communication is done with two GPIO pins (DATA and CLK). + +To use the channels of this components, you first need to setup the +global ``bp1658cj`` hub and give it an id, and then define the +:ref:`individual output channels `. +It is used in some smart light bulbs: + +- Orein OS0100411267 RGBCT Bulb + +.. code-block:: yaml + + # Example configuration entry + bp1658cj: + data_pin: GPIO6 + clock_pin: GPIO7 + max_power_color_channels: 4 # Valid values 0-15 + max_power_white_channels: 6 # Valid values 0-15 + +Configuration variables: +************************ + +- **data_pin** (**Required**, :ref:`Pin Schema `): The pin used for DATA. +- **clock_pin** (**Required**, :ref:`Pin Schema `): The pin which CLK is + connected to. +- **id** (*Optional*, :ref:`config-id`): The id to use for + this ``bp1658cj`` component. Use this if you have multiple BP1658CJ chains + connected at the same time. +- **max_power_color_channels** (*Optional*, int 0-15): Adjusts the current supplied to the + color channels, higher is more power. Default is 2 per BP1658CJ datasheet. See table below. +- **max_power_white_channels** (*Optional*, int 0-15): Adjusts the current supplied to the + white channels, higher is more power. Default is 4 per BP1658CJ datasheet. See table below. + +.. note:: + + The LED driver may be able to tolerate more power than + the bulb is designed to handle, start with lower values + and increase slowly, comparing to a stock bulb to verify + what is safe for your model. + ++---------------------------------+-----------------+ +| max_power_white_channels value | actual current | ++=================================+=================+ +| 0 | 0 mA | ++---------------------------------+-----------------+ +| 1 | 5 mA | ++---------------------------------+-----------------+ +| 2 | 10 mA | ++---------------------------------+-----------------+ +| 3 | 15 mA | ++---------------------------------+-----------------+ +| 4 | 20 mA | ++---------------------------------+-----------------+ +| 5 | 25 mA | ++---------------------------------+-----------------+ +| 6 | 30 mA (default) | ++---------------------------------+-----------------+ +| 7 | 35 mA | ++---------------------------------+-----------------+ +| 8 | 40 mA | ++---------------------------------+-----------------+ +| 9 | 45 mA | ++---------------------------------+-----------------+ +| 10 | 50 mA | ++---------------------------------+-----------------+ +| 11 | 55 mA | ++---------------------------------+-----------------+ +| 12 | 60 mA | ++---------------------------------+-----------------+ +| 13 | 65 mA | ++---------------------------------+-----------------+ +| 14 | 70 mA | ++---------------------------------+-----------------+ +| 15 | 75 mA | ++---------------------------------+-----------------+ + ++---------------------------------+-----------------+ +| max_power_color_channels value | actual current | ++=================================+=================+ +| 0 | 0 mA | ++---------------------------------+-----------------+ +| 1 | 10 mA | ++---------------------------------+-----------------+ +| 2 | 20 mA | ++---------------------------------+-----------------+ +| 3 | 30 mA | ++---------------------------------+-----------------+ +| 4 | 40 mA (default) | ++---------------------------------+-----------------+ +| 5 | 50 mA | ++---------------------------------+-----------------+ +| 6 | 60 mA | ++---------------------------------+-----------------+ +| 7 | 70 mA | ++---------------------------------+-----------------+ +| 8 | 80 mA | ++---------------------------------+-----------------+ +| 9 | 90 mA | ++---------------------------------+-----------------+ +| 10 | 100 mA | ++---------------------------------+-----------------+ +| 11 | 110 mA | ++---------------------------------+-----------------+ +| 12 | 120 mA | ++---------------------------------+-----------------+ +| 13 | 130 mA | ++---------------------------------+-----------------+ +| 14 | 140 mA | ++---------------------------------+-----------------+ +| 15 | 150 mA | ++---------------------------------+-----------------+ + +.. _bp1658cj-output: + +Output +------ + +The BP1658CJ output component exposes a BP1658CJ channel of a global +:ref:`bp1658cj-component` as a float output. + +.. code-block:: yaml + + # Individual outputs + output: + - platform: bp1658cj + id: output_red + channel: 1 + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this output component. +- **channel** (**Required**, int): Chose the channel of the BP1658CJ chain of + this output component. +- **bp1658cj_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the + :ref:`bp1658cj-component`. + Use this if you have multiple BP1658CJ chains you want to use at the same time. +- All other options from :ref:`Output `. + +.. note:: + + This driver does support enabling of both the color and the white channels + at the same time, but it is not encourage. Therefore, the :ref:`rgbw_color_interlock` + should be set to true when using this driver for safest operation. + +See Also +-------- + +- :doc:`/components/output/index` +- :doc:`/components/output/esp8266_pwm` +- :doc:`/components/output/sm2135` +- :doc:`/components/light/rgb` +- :doc:`/components/light/rgbw` +- :doc:`/components/light/rgbww` +- :doc:`/components/power_supply` +- :ghedit:`Edit` diff --git a/components/output/bp5758d.rst b/components/output/bp5758d.rst new file mode 100644 index 000000000..6cd42d023 --- /dev/null +++ b/components/output/bp5758d.rst @@ -0,0 +1,93 @@ +BP5758D LED driver +================== + +.. seo:: + :description: Instructions for setting up BP5758D LED drivers in ESPHome. + :keywords: BP5758D, DoHome G25 Globe bulb + +.. _bp5758d-component: + +Component/Hub +------------- + +The BP5758D component represents a BP5758D LED diver chain in +ESPHome. Communication is done with two GPIO pins (DATA and CLK). + +To use the channels of this components, you first need to setup the +global ``bp5758d`` hub and give it an id, and then define the +:ref:`individual output channels `. +It is used in some smart light bulbs: + +- DoHome G25 Globe bulb + +.. code-block:: yaml + + # Example configuration entry + bp5758d: + data_pin: GPIO3 + clock_pin: GPIO5 + + +Configuration variables: +************************ + +- **data_pin** (**Required**, :ref:`Pin Schema `): The pin used for DATA. +- **clock_pin** (**Required**, :ref:`Pin Schema `): The pin which CLK is + connected to. +- **id** (*Optional*, :ref:`config-id`): The id to use for + this ``bp5758d`` component. Use this if you have multiple BP5758D chains + connected at the same time. + +.. note:: + + The LED driver may be able to tolerate more power than + the bulb is designed to handle, start with lower values + and increase slowly, comparing to a stock bulb to verify + what is safe for your model. + +.. _bp5758d-output: + +Output +------ + +The BP5758D output component exposes a BP5758D channel of a global +:ref:`bp5758d-component` as a float output. + +.. code-block:: yaml + + # Example configuration entry + output: + - platform: bp5758d + id: output_red + channel: 2 # Valid values 1-5 to match OUT1-OUT5 + current: 10 # In mA, valid values 0-90, default 10 + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this output component. +- **channel** (**Required**, int): Chose the channel of the BP5758D chain of + this output component. Valid values are 1-5 + **current** (*Optional*, int): Current in mA, valid values are 0-90, default 10. +- **bp5758d_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the + :ref:`bp5758d-component`. + Use this if you have multiple BP5758D chains you want to use at the same time. +- All other options from :ref:`Output `. + +.. note:: + + This driver does support enabling of both the color and the white channels + at the same time, but it is not encourage. Therefore, the :ref:`rgbw_color_interlock` + should be set to true when using this driver for safest operation. + +See Also +-------- + +- :doc:`/components/output/index` +- :doc:`/components/output/esp8266_pwm` +- :doc:`/components/output/sm2135` +- :doc:`/components/light/rgb` +- :doc:`/components/light/rgbw` +- :doc:`/components/light/rgbww` +- :doc:`/components/power_supply` +- :ghedit:`Edit` diff --git a/components/output/images/sigma-delta-example.png b/components/output/images/sigma-delta-example.png new file mode 100644 index 000000000..c4cebdc28 Binary files /dev/null and b/components/output/images/sigma-delta-example.png differ diff --git a/components/output/images/x9c.jpg b/components/output/images/x9c.jpg new file mode 100644 index 000000000..b355f2679 Binary files /dev/null and b/components/output/images/x9c.jpg differ diff --git a/components/output/index.rst b/components/output/index.rst index 2dc33f38d..949f5fab0 100644 --- a/components/output/index.rst +++ b/components/output/index.rst @@ -43,7 +43,7 @@ Configuration variables: Float outputs only: - **min_power** (*Optional*, float): Sets the minimum output value of this output platform. - Must be in range from 0 to max_power. Defaults to ``0``. + Must be in range from 0 to max_power. Defaults to ``0``. If zero_means_zero is ``false`` this will be output value when the entity is turned off. - **max_power** (*Optional*, float): Sets the maximum output value of this output platform. Must be in range from min_power to 1. Defaults to ``1``. - **zero_means_zero** (*Optional*, boolean): Sets the output to use actual 0 instead of ``min_power``. diff --git a/components/output/modbus_controller.rst b/components/output/modbus_controller.rst index 3318fa50c..3ca458f87 100644 --- a/components/output/modbus_controller.rst +++ b/components/output/modbus_controller.rst @@ -12,7 +12,7 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. - **name** (**Required**, string): The name of the sensor. - **address** (**Required**, int): start address of the first register in a range -- **value_type** (**Required**): datatype of the modbus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first) +- **value_type** (**Required**): data type of the modbus register data. The default data type for modbus is a 16 bit integer in big endian format (MSB first) - ``U_WORD`` (unsigned 16 bit integer from 1 register = 16bit) - ``S_WORD`` (signed 16 bit integer from 1 register = 16bit) @@ -21,9 +21,9 @@ Configuration variables: - ``U_DWORD_R`` (unsigned 32 bit integer from 2 registers low word first) - ``S_DWORD_R`` (signed 32 bit integer from 2 registers low word first) - ``U_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) - - ``S_QWORD`` (unsigned 64 bit integer from 4 registers = 64bit) + - ``S_QWORD`` (signed 64 bit integer from 4 registers = 64bit) - ``U_QWORD_R`` (unsigned 64 bit integer from 4 registers low word first) - - ``U_QWORD_R`` signed 64 bit integer from 4 registers low word first) + - ``S_QWORD_R`` signed 64 bit integer from 4 registers low word first) - ``FP32`` (32 bit IEEE 754 floating point from 2 registers) - ``FP32_R`` (32 bit IEEE 754 floating point - same as FP32 but low word first) diff --git a/components/output/pca9685.rst b/components/output/pca9685.rst index e5326967b..63c8d9f56 100644 --- a/components/output/pca9685.rst +++ b/components/output/pca9685.rst @@ -33,14 +33,35 @@ global ``pca9685`` hub and give it an id, and then define the pca9685_id: 'pca9685_hub1' channel: 0 +.. code-block:: yaml + + # Example configuration entry with external clock enable and clock source from ESP32 + pca9685: + - id: pca9685_hub1 + external_clock_input: true + + # Individual outputs + output: + # generate PWM from ESP32 ledc + - platform: ledc + pin: 25 + id: extclk + min_power: 1 + frequency: 40MHz + + - platform: pca9685 + pca9685_id: 'pca9685_hub1' + channel: 0 + Configuration variables: ************************ -- **frequency** (**Required**, float): The frequency to let the +- **frequency** (*Optional*, float): The frequency to let the component drive all PWM outputs at. Must be in range from 24Hz to - 1525.88Hz. + 1525.88Hz. Default ``1000Hz``. +- **external_clock_input** (*Optional*, bool): Enable external clock input. PRE_SCALE register will by set to 3. Default to ``false``. - **address** (*Optional*, int): The I²C address of the driver. - Defaults to ``0x00``. + Defaults to ``0x40``. - **id** (*Optional*, :ref:`config-id`): The id to use for this pca9685 component. Use this if you have multiple PCA9685s connected at the same time diff --git a/components/output/sigma_delta.rst b/components/output/sigma_delta.rst new file mode 100644 index 000000000..f8938c314 --- /dev/null +++ b/components/output/sigma_delta.rst @@ -0,0 +1,81 @@ +Sigma-Delta Output +================== + +This integration uses `sigma-delta modulation `__ +to output a floating-point value on a binary output. Unlike with :doc:`/components/output/slow_pwm`, +it is possible to update the output value with each update cycle, not just at the end of a longer period. + +.. figure:: images/sigma-delta-example.png + :align: center + :width: 65.0% + + Comparison between a *Slow PWM* with a period of 100s and a *sigma-delta output* with an update interval of 1s + +For example, if you choose to toggle the output at most once every 1 second and decide on a +PWM period of 10 seconds, for reasonably frequent updates, with :doc:`/components/output/slow_pwm` +there are only 10 possible levels, and for higher precision a longer update interval is needed, +restricting the update rate. + +A *sigma-delta* output is updated during each cycle, thus a higher precision can be achieved, without +being constrained by a calculation timeframe (=period). + +So instead of having to define a ``period`` where the width of the pulse determines the output level, here you +choose an ``update_interval`` which acts like a clock signal from where the pulse density determines the output level. + +This component can be used as a drop-in replacement for :doc:`/components/output/slow_pwm` by changing the ``platform`` to +``sigma_delta_output`` and changing ``period`` to ``update_interval`` (you usually want to set the *sigma-delta*'s +``update_interval`` as a fraction of *Slow PWM*'s ``period`` for similar results) + +.. code-block:: yaml + + # Example configuration entry + output: + - platform: sigma_delta_output + update_interval: 10s + id: sd_heater_output + + # Output to a pin + pin: 15 + + # Use the same output, but through automations + turn_on_action: + then: + - output.turn_on: heater_relay + turn_off_action: + then: + - output.turn_off: heater_relay + + - platform: gpio + pin: 15 + id: heater_relay + +Configuration variables: + +- **update_interval** (**Required**, :ref:`Time `): The cycle interval at which the output is recalculated. +- **pin** (*Optional*, :ref:`Pin Schema `): The pin to pulse. +- **state_change_action** (*Optional*, :ref:`Automation `): An automation to perform when the load is switched. If a lambda is used the boolean ``state`` parameter holds the new status. +- **turn_on_action** (*Optional*, :ref:`Automation `): An automation to perform when the load is turned on. Can be used to control for example a switch or output component. +- **turn_off_action** (*Optional*, :ref:`Automation `): An automation to perform when the load is turned off. ``turn_on_action`` and ``turn_off_action`` must be configured together. +- All options from :ref:`Output `. + +.. note:: + + - If ``pin`` is defined, the GPIO pin state is writen before any action is executed. + - ``state_change_action`` and ``turn_on_action``/``turn_off_action`` can be used togther. ``state_change_action`` is called before ``turn_on_action``/``turn_off_action``. It's recommended to use either ``state_change_action`` or ``turn_on_action``/``turn_off_action`` to change the state of an output. Using both automations together is only recommended for monitoring. + + +.. note:: + + If the output must not be active for more than some fixed time before it has + to be off for a while to e.g. cool down, :doc:`/components/output/slow_pwm` + should be used with a ``max_power`` setting to better control the duty + cycle. + +See Also +-------- + +- :doc:`/components/output/index` +- `Sigma-Delta `__ +- :doc:`/components/output/slow_pwm` +- :apiref:`sigma_delta_output/sigma_delta_output.h` +- :ghedit:`Edit` diff --git a/components/output/slow_pwm.rst b/components/output/slow_pwm.rst index 6f3ec6f83..9c129f4d9 100644 --- a/components/output/slow_pwm.rst +++ b/components/output/slow_pwm.rst @@ -67,12 +67,21 @@ Example: - output.turn_off: output1 +.. note:: + + If the duty cycle is not constrained to a maximum value, the + :doc:`/components/output/sigma_delta` 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. + See Also -------- - :doc:`/components/output/index` - :doc:`/components/output/esp8266_pwm` - :doc:`/components/output/ledc` +- :doc:`/components/output/sigma_delta` - :doc:`/components/light/monochromatic` - :doc:`/components/fan/speed` - :doc:`/components/power_supply` diff --git a/components/output/sm16716.rst b/components/output/sm16716.rst index e61270806..25144acbd 100644 --- a/components/output/sm16716.rst +++ b/components/output/sm16716.rst @@ -102,7 +102,7 @@ Configuration variables: Feit Electric A19 Smart WiFi Bulb --------------------------------- -This component can be used with a Feit Electric A19 smart light bulb. You can use +This component can be used with a version of a Feit Electric A19 smart light bulb. You can use tuya-convert to flash the bulb. The cold white LEDs are connected to PWM1 and the warm white LEDs are connected to PWM2. The RGB LEDs are connected to a SM16716 chip that is connected to GPIO4 for clock, GPIO14 for data, and GPIO13 for power. @@ -174,7 +174,58 @@ A complete configuration for a Feit Electric A19 looks like: The white LEDs are much brighter than the color LEDs and will fully overpower the set color when the white level is set even a little bit high. You will need to set the white level to 0 in order to get usable colors from this bulb. + +Alternative Costco Feit A19 RGBCT bulb configuration: +.. code-block:: yaml + + sm16716: + data_pin: GPIO12 + clock_pin: GPIO14 + num_channels: 3 + num_chips: 1 + + output: + - platform: sm16716 + id: output_red + channel: 2 + power_supply: rgb_power + - platform: sm16716 + id: output_green + channel: 1 + power_supply: rgb_power + - platform: sm16716 + id: output_blue + channel: 0 + power_supply: rgb_power + - platform: esp8266_pwm + id: output_color_temperature + inverted: true + pin: GPIO5 + - platform: esp8266_pwm + id: output_brightness + min_power: 0.05 + zero_means_zero: true + pin: GPIO4 + + light: + - platform: rgbct + name: ${friendly_name} + id: outside + red: output_red + green: output_green + blue: output_blue + color_temperature: output_color_temperature + white_brightness: output_brightness + cold_white_color_temperature: 153 mireds + warm_white_color_temperature: 370 mireds + color_interlock: true + + power_supply: + - id: rgb_power + pin: GPIO13 + + See Also -------- diff --git a/components/output/sm2235.rst b/components/output/sm2235.rst new file mode 100644 index 000000000..faf8307ea --- /dev/null +++ b/components/output/sm2235.rst @@ -0,0 +1,167 @@ +SM2235 LED driver +================== + +.. seo:: + :description: Instructions for setting up SM2235 LED drivers in ESPHome. + :keywords: SM2235 + +.. _sm2235-component: + +Component/Hub +------------- + +The SM2235 component represents a SM2235 LED diver chain in +ESPHome. Communication is done with two GPIO pins (DATA and CLK). + +To use the channels of this components, you first need to setup the +global ``sm2235`` hub and give it an id, and then define the +:ref:`individual output channels `. + +.. code-block:: yaml + + # Example configuration entry + sm2235: + data_pin: GPIO4 + clock_pin: GPIO5 + max_power_color_channels: 9 + max_power_white_channels: 9 + +Configuration variables: +************************ + +- **data_pin** (**Required**, :ref:`Pin Schema `): The pin used for DATA. +- **clock_pin** (**Required**, :ref:`Pin Schema `): The pin which CLK is + connected to. +- **id** (*Optional*, :ref:`config-id`): The id to use for + this ``sm2235`` component. Use this if you have multiple SM2235 chains + connected at the same time. +- **max_power_color_channels** (*Optional*, int 0-15): Adjusts the current supplied to the + color channels, higher is more power. Default is 2 per SM2235 datasheet. See table below. +- **max_power_white_channels** (*Optional*, int 0-15): Adjusts the current supplied to the + white channels, higher is more power. Default is 4 per SM2235 datasheet. See table below. + +.. note:: + + The LED driver may be able to tolerate more power than + the bulb is designed to handle, start with lower values + and increase slowly, comparing to a stock bulb to verify + what is safe for your model. + ++---------------------------------+-----------------+ +| max_power_white_channels value | actual current | ++=================================+=================+ +| 0 | 5 mA | ++---------------------------------+-----------------+ +| 1 | 10 mA | ++---------------------------------+-----------------+ +| 2 | 15 mA | ++---------------------------------+-----------------+ +| 3 | 20 mA | ++---------------------------------+-----------------+ +| 4 | 25 mA (default) | ++---------------------------------+-----------------+ +| 5 | 30 mA | ++---------------------------------+-----------------+ +| 6 | 35 mA | ++---------------------------------+-----------------+ +| 7 | 40 mA | ++---------------------------------+-----------------+ +| 8 | 45 mA | ++---------------------------------+-----------------+ +| 9 | 50 mA | ++---------------------------------+-----------------+ +| 10 | 55 mA | ++---------------------------------+-----------------+ +| 11 | 60 mA | ++---------------------------------+-----------------+ +| 12 | 65 mA | ++---------------------------------+-----------------+ +| 13 | 70 mA | ++---------------------------------+-----------------+ +| 14 | 75 mA | ++---------------------------------+-----------------+ +| 15 | 80 mA | ++---------------------------------+-----------------+ + ++---------------------------------+-----------------+ +| max_power_color_channels value | actual current | ++=================================+=================+ +| 0 | 4 mA | ++---------------------------------+-----------------+ +| 1 | 8 mA | ++---------------------------------+-----------------+ +| 2 | 12 mA (default) | ++---------------------------------+-----------------+ +| 3 | 16 mA | ++---------------------------------+-----------------+ +| 4 | 20 mA | ++---------------------------------+-----------------+ +| 5 | 24 mA | ++---------------------------------+-----------------+ +| 6 | 28 mA | ++---------------------------------+-----------------+ +| 7 | 32 mA | ++---------------------------------+-----------------+ +| 8 | 36 mA | ++---------------------------------+-----------------+ +| 9 | 40 mA | ++---------------------------------+-----------------+ +| 10 | 44 mA | ++---------------------------------+-----------------+ +| 11 | 48 mA | ++---------------------------------+-----------------+ +| 12 | 52 mA | ++---------------------------------+-----------------+ +| 13 | 56 mA | ++---------------------------------+-----------------+ +| 14 | 60 mA | ++---------------------------------+-----------------+ +| 15 | 64 mA | ++---------------------------------+-----------------+ + +.. _sm2235-output: + +Output +------ + +The SM2235 output component exposes a SM2235 channel of a global +:ref:`sm2235-component` as a float output. + +.. code-block:: yaml + + # Individual outputs + output: + - platform: sm2235 + id: output_red + channel: 1 + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this output component. +- **channel** (**Required**, int): Chose the channel of the SM2235 chain of + this output component. +- **sm2235_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the + :ref:`sm2235-component`. + Use this if you have multiple SM2235 chains you want to use at the same time. +- All other options from :ref:`Output `. + +.. note:: + + This driver does support enabling of both the color and the white channels + at the same time, but it is not encourage. Therefore, the :ref:`rgbw_color_interlock` + should be set to true when using this driver for safest operation. + +See Also +-------- + +- :doc:`/components/output/index` +- :doc:`/components/output/esp8266_pwm` +- :doc:`/components/output/sm2135` +- :doc:`/components/output/sm2335` +- :doc:`/components/light/rgb` +- :doc:`/components/light/rgbw` +- :doc:`/components/light/rgbww` +- :doc:`/components/power_supply` +- :apiref:`output/sm2235_output_component.h` +- :ghedit:`Edit` diff --git a/components/output/sm2335.rst b/components/output/sm2335.rst new file mode 100644 index 000000000..a49fad0e5 --- /dev/null +++ b/components/output/sm2335.rst @@ -0,0 +1,169 @@ +SM2335 LED driver +================== + +.. seo:: + :description: Instructions for setting up SM2335 LED drivers in ESPHome. + :keywords: SM2335, SwitchBot Color Bulb W1401400 + +.. _sm2335-component: + +Component/Hub +------------- + +The SM2335 component represents a SM2335 LED diver chain in +ESPHome. Communication is done with two GPIO pins (DATA and CLK). +It is used in some smart light bulbs: + +- SwitchBot Color Bulb W1401400 + +To use the channels of this components, you first need to setup the +global ``sm2335`` hub and give it an id, and then define the +:ref:`individual output channels `. + +.. code-block:: yaml + + # Example configuration entry + sm2335: + data_pin: GPIO4 + clock_pin: GPIO5 + max_power_color_channels: 9 + max_power_white_channels: 9 + +Configuration variables: +************************ + +- **data_pin** (**Required**, :ref:`Pin Schema `): The pin used for DATA. +- **clock_pin** (**Required**, :ref:`Pin Schema `): The pin which CLK is + connected to. +- **id** (*Optional*, :ref:`config-id`): The id to use for + this ``sm2335`` component. Use this if you have multiple SM2335 chains + connected at the same time. +- **max_power_color_channels** (*Optional*, int 0-15): Adjusts the current supplied to the + color channels, higher is more power. Default is 2 per SM2335 datasheet. See table below. +- **max_power_white_channels** (*Optional*, int 0-15): Adjusts the current supplied to the + white channels, higher is more power. Default is 4 per SM2335 datasheet. See table below. + +.. note:: + + The LED driver may be able to tolerate more power than + the bulb is designed to handle, start with lower values + and increase slowly, comparing to a stock bulb to verify + what is safe for your model. + ++---------------------------------+-----------------+ +| max_power_white_channels value | actual current | ++=================================+=================+ +| 0 | 5 mA | ++---------------------------------+-----------------+ +| 1 | 10 mA | ++---------------------------------+-----------------+ +| 2 | 15 mA | ++---------------------------------+-----------------+ +| 3 | 20 mA | ++---------------------------------+-----------------+ +| 4 | 25 mA (default) | ++---------------------------------+-----------------+ +| 5 | 30 mA | ++---------------------------------+-----------------+ +| 6 | 35 mA | ++---------------------------------+-----------------+ +| 7 | 40 mA | ++---------------------------------+-----------------+ +| 8 | 45 mA | ++---------------------------------+-----------------+ +| 9 | 50 mA | ++---------------------------------+-----------------+ +| 10 | 55 mA | ++---------------------------------+-----------------+ +| 11 | 60 mA | ++---------------------------------+-----------------+ +| 12 | 65 mA | ++---------------------------------+-----------------+ +| 13 | 70 mA | ++---------------------------------+-----------------+ +| 14 | 75 mA | ++---------------------------------+-----------------+ +| 15 | 80 mA | ++---------------------------------+-----------------+ + ++---------------------------------+-----------------+ +| max_power_color_channels value | actual current | ++=================================+=================+ +| 0 | 10 mA | ++---------------------------------+-----------------+ +| 1 | 20 mA | ++---------------------------------+-----------------+ +| 2 | 30 mA (default) | ++---------------------------------+-----------------+ +| 3 | 40 mA | ++---------------------------------+-----------------+ +| 4 | 50 mA | ++---------------------------------+-----------------+ +| 5 | 60 mA | ++---------------------------------+-----------------+ +| 6 | 70 mA | ++---------------------------------+-----------------+ +| 7 | 80 mA | ++---------------------------------+-----------------+ +| 8 | 90 mA | ++---------------------------------+-----------------+ +| 9 | 100 mA | ++---------------------------------+-----------------+ +| 10 | 110 mA | ++---------------------------------+-----------------+ +| 11 | 120 mA | ++---------------------------------+-----------------+ +| 12 | 130 mA | ++---------------------------------+-----------------+ +| 13 | 140 mA | ++---------------------------------+-----------------+ +| 14 | 150 mA | ++---------------------------------+-----------------+ +| 15 | 160 mA | ++---------------------------------+-----------------+ + +.. _sm2335-output: + +Output +------ + +The SM2335 output component exposes a SM2335 channel of a global +:ref:`sm2335-component` as a float output. + +.. code-block:: yaml + + # Individual outputs + output: + - platform: sm2335 + id: output_red + channel: 1 + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this output component. +- **channel** (**Required**, int): Chose the channel of the SM2335 chain of + this output component. +- **sm2335_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the + :ref:`sm2335-component`. + Use this if you have multiple SM2335 chains you want to use at the same time. +- All other options from :ref:`Output `. + +.. note:: + + This driver does support enabling of both the color and the white channels + at the same time, but it is not encourage. Therefore, the :ref:`rgbw_color_interlock` + should be set to true when using this driver for safest operation. + +See Also +-------- + +- :doc:`/components/output/index` +- :doc:`/components/output/esp8266_pwm` +- :doc:`/components/output/sm2135` +- :doc:`/components/output/sm2235` +- :doc:`/components/light/rgb` +- :doc:`/components/light/rgbw` +- :doc:`/components/light/rgbww` +- :doc:`/components/power_supply` +- :ghedit:`Edit` diff --git a/components/output/x9c.rst b/components/output/x9c.rst new file mode 100644 index 000000000..b3b496c05 --- /dev/null +++ b/components/output/x9c.rst @@ -0,0 +1,56 @@ +X9C Potentiometer Output +======================== + +.. seo:: + :description: Instructions for setting up a X9C digital potentiometer with ESPHome. + :image: description.svg + +The ``x9c`` output platform allows you to an output that controls a `X9C digital potentiometer `__. + +.. figure:: images/x9c.jpg + :align: center + :width: 70.0% + + X9C digital potentiometer + +The X9C family of digital potentiometers are available in different resistance values. + +==================== ===================== +``X9C102`` ``1kΩ`` +-------------------- --------------------- +``X9C103`` ``10kΩ`` +-------------------- --------------------- +``X9C503`` ``50kΩ`` +-------------------- --------------------- +``X9C104`` ``100kΩ`` +==================== ===================== + +All chips are controlled by a three wire interface and feature 100 possible wiper positions. + +.. code-block:: yaml + + # Example configuration entry + output: + - platform: x9c + id: x9c_pot + cs_pin: GPIO25 + inc_pin: GPIO27 + ud_pin: GPIO26 + initial_value: 0.5 + +Configuration variables: +------------------------ + +- **id** (**Required**, :ref:`config-id`): The id to use for this output component. +- **cs_pin** (**Required**, :ref:`Pin Schema `): Chip Select pin +- **inc_pin** (**Required**, :ref:`Pin Schema `): Increment pin +- **ud_pin** (**Required**, :ref:`Pin Schema `): Up/Down pin +- **initial_value** (*Optional*, float): Manually specify the initial potentiometer value, between ``0.01`` and ``1.0``. Defaults to ``1.0``. +- All other options from :ref:`Output `. + +See Also +-------- + +- :doc:`/components/output/index` +- :apiref:`x9c/x9c.h` +- :ghedit:`Edit` diff --git a/components/pca9554.rst b/components/pca9554.rst new file mode 100644 index 000000000..373466cf4 --- /dev/null +++ b/components/pca9554.rst @@ -0,0 +1,83 @@ +PCA9554 I/O Expander +==================== + +The PCA9554 component allows you to use PCA9554, PCA9554A or PCA9536 I/O expanders +(`PCA9554 datasheet `__, +`PCA9554A datasheet `__, +`PCA9536 datasheet `__) in ESPHome. +It uses :ref:`I²C Bus ` for communication. + +Once configured, you can use any of the 8 pins (PCA9554, PCA9554A) or 4 pins (PCA9536) as +pins for your projects. Within ESPHome they emulate a real internal GPIO pin +and can therefore be used with many of ESPHome's components such as the GPIO +binary sensor or GPIO switch. + +The 7 bit I2C device address ranges are: + +PCA9554 : 0x20 to 0x27 + +PCA9554A : 0x38 to 0x3F + +PCA9536 : 0x41 + +For the PCA9554 and PCA9554A, the actual choice of the I2C device address depends on state of the 3 address pins. +Please refer to the individual datasheets for further details. + +Up to eight PCA9554 and an additional eight PCA9554A devices can reside on the same I2C bus. +Please note that only one PCA9536 device is allowed per I2C bus due to its fixed address. + +The PCA9554 and PCA9554A provide 8 bits of GPIO's (pin numbers 0-7) +The PCA9536 provides 4 bits of GPIO's (pin numbers 0-3). + +Any option accepting a :ref:`Pin Schema ` can theoretically be used, but some more +complicated components that do communication through this I/O expander will +not work. + +.. code-block:: yaml + + # Example configuration entry + pca9554: + - id: 'pca9554a_device' + address: 0x38 + + + # Individual outputs + switch: + - platform: gpio + name: "PCF9554A Pin #0" + pin: + pca9554: pcf9554a_device + # Use pin number 0 + number: 0 + # One of INPUT or OUTPUT + mode: + output: true + inverted: false + +Configuration variables: +************************ + +- **id** (**Required**, :ref:`config-id`): The id to use for this PCF9554 component. +- **address** (*Optional*, int): The I²C address of the driver. + Defaults to ``0x20``. + + + +Pin configuration variables: +**************************** + +- **pca9554** (**Required**, :ref:`config-id`): The id of the PCA9554 component of the pin. +- **number** (**Required**, int): The pin number. +- **inverted** (*Optional*, boolean): If all read and written values + should be treated as inverted. Defaults to ``false``. +- **mode** (*Optional*, string): A pin mode to set for the pin at. One of ``INPUT`` or ``OUTPUT``. + + +See Also +-------- + +- :ref:`i2c` +- :doc:`switch/gpio` +- :doc:`binary_sensor/gpio` +- :apiref:`pca9554/pca9554.h` +- :ghedit:`Edit` diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst index f7ca562f3..25954d009 100644 --- a/components/remote_receiver.rst +++ b/components/remote_receiver.rst @@ -31,6 +31,8 @@ Configuration variables: Set to ``all`` to dump all available codecs: - **aeha**: Decode and dump AEHA infrared codes. + - **canalsat**: Decode and dump CanalSat infrared codes. + - **canalsatld**: Decode and dump CanalSatLD infrared codes. - **coolix**: Decode and dump Coolix infrared codes. - **dish**: Decode and dump Dish infrared codes. - **jvc**: Decode and dump JVC infrared codes. @@ -69,6 +71,12 @@ Automations: - **on_aeha** (*Optional*, :ref:`Automation `): An automation to perform when a AEHA remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::AEHAData` is passed to the automation for use in lambdas. +- **on_canalsat** (*Optional*, :ref:`Automation `): An automation to perform when a + CanalSat remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::CanalSatData` + is passed to the automation for use in lambdas. +- **on_canalsatld** (*Optional*, :ref:`Automation `): An automation to perform when a + CanalSatLD remote code has been decoded. A variable ``x`` of type :apistruct:`remote_base::CanalSatLDData` + is passed to the automation for use in lambdas. - **on_coolix** (*Optional*, :ref:`Automation `): An automation to perform when a Coolix remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::CoolixData` is passed to the automation for use in lambdas. @@ -174,6 +182,28 @@ Remote code selection (exactly one of these has to be included): - **data** (**Required**, 3-35 bytes list): The code to listen for, see :ref:`remote_transmitter-transmit_aeha` for more info. Usually you only need to copy this directly from the dumper output. +- **canalsat**: Trigger on a decoded CanalSat remote code with the given data. + + .. note:: + + The CanalSat and CanalSatLD protocols use a higher carrier frequency (56khz) and are very similar. + Depending on the hardware used they may interfere with each other when enabled simultaneously. + + - **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`` + - **command** (**Required**, int): The command to listen for. + +- **canalsatld**: Trigger on a decoded CanalSatLD remote code with the given data. + + .. note:: + + The CanalSat and CanalSatLD protocols use a higher carrier frequency (56khz) and are very similar. + Depending on the hardware used they may interfere with each other when enabled simultaneously. + + - **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`` + - **command** (**Required**, int): The command to listen for. + - **coolix**: Trigger on a decoded Coolix remote code with the given data. - **data** (**Required**, int): The 24-bit Coolix code to trigger on, see dumper output for more info. diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst index f2a36e405..dcc159f23 100644 --- a/components/remote_transmitter.rst +++ b/components/remote_transmitter.rst @@ -99,6 +99,60 @@ Configuration variables: AEHA refers to the Association for Electric Home Appliances in Japan, a format used by Panasonic and many other companies. +.. _remote_transmitter-transmit_canalsat: + +``remote_transmitter.transmit_canalsat`` Action +*********************************************** + +This :ref:`action ` sends a CanalSat infrared remote code to a remote transmitter. + +.. note:: + + The CanalSat and CanalSatLD protocols use a higher carrier frequency (56khz) and are very similar. + Depending on the hardware used they may interfere with each other when enabled simultaneously. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_canalsat: + device: 0x25 + address: 0x00 + command: 0x02 + +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`` +- **command** (**Required**, int): The command to send. +- All other options from :ref:`remote_transmitter-transmit_action`. + +.. _remote_transmitter-transmit_canalsatld: + +``remote_transmitter.transmit_canalsatld`` Action +************************************************* + +This :ref:`action ` sends a CanalSatLD infrared remote code to a remote transmitter. + +.. note:: + + The CanalSat and CanalSatLD protocols use a higher carrier frequency (56khz) and are very similar. + Depending on the hardware used they may interfere with each other when enabled simultaneously. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_canalsatld: + device: 0x25 + address: 0x00 + command: 0x02 + +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`` +- **command** (**Required**, int): The command to send. +- All other options from :ref:`remote_transmitter-transmit_action`. + .. _remote_transmitter-transmit_coolix: ``remote_transmitter.transmit_coolix`` Action diff --git a/components/rp2040.rst b/components/rp2040.rst index 94387f906..0bead367b 100644 --- a/components/rp2040.rst +++ b/components/rp2040.rst @@ -34,7 +34,7 @@ This component contains platform-specific options for the RP2040 platform. Configuration variables: ------------------------ -- **board** (*Optional*, string): The board type. Valid options are ``rpipico`` and ``rpipicow``. +- **board** (*Optional*, string): The board type. Valid option is ``rpipicow``. See Also -------- diff --git a/components/sensor/ads1115.rst b/components/sensor/ads1115.rst index bdd361ed3..ae2c30c10 100644 --- a/components/sensor/ads1115.rst +++ b/components/sensor/ads1115.rst @@ -2,9 +2,9 @@ ADS1115 Sensor ============== .. seo:: - :description: Instructions for setting up ADS1115 multiplexed analog voltage sensors. + :description: Instructions for setting up ADS1115/ADS1015 multiplexed analog voltage sensors. :image: ads1115.jpg - :keywords: ADS1115 + :keywords: ADS1115 ADS1015 .. _ads1115-component: @@ -21,7 +21,9 @@ To use this hub, first setup the :ref:`I²C Bus ` and connect the sensor to ADS1115 16-Bit ADC. -.. _Adafruit: https://www.adafruit.com/product/1085 +.. _Adafruit_ADS1115: https://www.adafruit.com/product/1085 + +.. _Adafruit_ADS1015: https://www.adafruit.com/product/1083 .. code-block:: yaml @@ -59,7 +61,7 @@ Sensor ------ The ``ads1115`` sensor allows you to use your ADS1115 sigma-delta ADC -sensors (`datasheet `__, `Adafruit`_) with ESPHome. +sensors (`datasheet `__, `Adafruit_ADS1115`_) or your ADS1015 sigma-delta ADC sensors (`datasheet `__, `Adafruit_ADS1015`_) with ESPHome. First, setup an :ref:`ADS1115 Hub ` for your ADS1115 sensor and then use this sensor platform to create individual sensors that will report the voltage to Home Assistant. @@ -92,6 +94,11 @@ Configuration variables: - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. - **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** + Multiplexer and Gain -------------------- @@ -121,7 +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/ccs811.rst b/components/sensor/ccs811.rst index 9d9cdf615..831d95ea8 100644 --- a/components/sensor/ccs811.rst +++ b/components/sensor/ccs811.rst @@ -1,11 +1,11 @@ -CCS811 CO_2 and Volatile Organic Compound Sensor -================================================ +CCS811 eCO_2 and Volatile Organic Compound Sensor +================================================= .. seo:: :description: Instructions for setting up CCS811 sensors. :image: ccs811.jpg -The ``ccs811`` sensor platform allows you to use CCS811 CO_2 and volatile organic compound sensors +The ``ccs811`` sensor platform allows you to use CCS811 eCO_2 and volatile organic compound sensors (`Adafruit`_) with ESPHome. .. note:: diff --git a/components/sensor/dallas.rst b/components/sensor/dallas.rst index a0fb606cd..2c0698774 100644 --- a/components/sensor/dallas.rst +++ b/components/sensor/dallas.rst @@ -89,7 +89,7 @@ Configuration variables: - **index** (**Required**, int): The index of the sensor starting with 0. So the first sensor will for example have index 0. :ref:`It’s recommended to use address instead `. -- **resolution** (*Optional*, int): An optional resolution from 8 to +- **resolution** (*Optional*, int): An optional resolution from 9 to 12. Higher means more accurate. Defaults to the maximum for most Dallas temperature sensors: 12. - **dallas_id** (*Optional*, :ref:`config-id`): The ID of the :ref:`dallas hub `. Use this if you have multiple dallas hubs. diff --git a/components/sensor/daly_bms.rst b/components/sensor/daly_bms.rst index 77ae91737..cdb28600b 100644 --- a/components/sensor/daly_bms.rst +++ b/components/sensor/daly_bms.rst @@ -228,6 +228,136 @@ Configuration variables: - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. - All other options from :ref:`Binary Sensor `. + +Control BMS +----------- +At this moment Daly sensor platform don't suppport controlling you BMS, but you can make some stuff using uart.write + +First you need to setup binary sensors for charging and disharging MOS + +.. code-block:: yaml + + + binary_sensor: + - platform: daly_bms + charging_mos_enabled: + name: "Daly Charging MOS" + id: bin_daly_chg_mos # binary MOS sensor must have ID to use with switch + internal: True # but you can make it internal to avoid duplication + discharging_mos_enabled: + name: "Daly Discharging MOS" + id: bin_daly_dischg_mos # binary MOS sensor must have ID to use with switch + internal: True # but you can make it internal to avoid duplication + +Then you can add switches + +.. code-block:: yaml + + + switch: + - platform: template + name: "Daly Charging MOS" + lambda: |- + if (id(bin_daly_chg_mos).state) { + return true; + } else { + return false; + } + turn_on_action: + - uart.write: + data: [0xA5, 0x40, 0xDA, 0x08, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xC8] + - logger.log: + format: "Send cmd to Daly: Set charge MOS on" + turn_off_action: + - uart.write: + data: [0xA5, 0x40, 0xDA, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xC7] + - logger.log: + format: "Send cmd to Daly: Set charge MOS off" + + - platform: template + name: "Daly Discharging MOS" + lambda: |- + if (id(bin_daly_dischg_mos).state) { + return true; + } else { + return false; + } + turn_on_action: + - uart.write: + data: [0xA5, 0x40, 0xD9, 0x08, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xC7] + - logger.log: + format: "Send cmd to Daly: Set discharge MOS on" + turn_off_action: + - uart.write: + data: [0xA5, 0x40, 0xD9, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xC6] + - logger.log: + format: "Send cmd to Daly: Set discharge MOS off" + + +Also you can add select to change battery level + +.. code-block:: yaml + + + select: + - platform: template + name: "Daly Battery Level setup" + optimistic: True + options: + - 100% + - 75% + - 50% + - 25% + - 0% + initial_option: 100% + set_action: + then: + - if: + condition: + lambda: 'return x == "100%";' + then: + - uart.write: + data: [0xA5, 0x40, 0x21, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x03, 0xE8, 0xF9] + - logger.log: + format: "Send cmd to Daly: Set SOC to 100%" + else: + - if: + condition: + lambda: 'return x == "75%";' + then: + - uart.write: + data: [0xA5, 0x40, 0x21, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xEE, 0xFE] + - logger.log: + format: "Send cmd to Daly: Set SOC to 75%" + else: + - if: + condition: + lambda: 'return x == "50%";' + then: + - uart.write: + data: [0xA5, 0x40, 0x21, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0xF4, 0x03] + - logger.log: + format: "Send cmd to Daly: Set SOC to 50%" + else: + - if: + condition: + lambda: 'return x == "25%";' + then: + - uart.write: + data: [0xA5, 0x40, 0x21, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFA, 0x08] + - logger.log: + format: "Send cmd to Daly: Set SOC to 25%" + else: + - if: + condition: + lambda: 'return x == "0%";' + then: + - uart.write: + data: [0xA5, 0x40, 0x21, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0E] + - logger.log: + format: "Send cmd to Daly: Set SOC to 0%" + + UART Connection --------------- diff --git a/components/sensor/ee895.rst b/components/sensor/ee895.rst new file mode 100644 index 000000000..f5b4f1b8a --- /dev/null +++ b/components/sensor/ee895.rst @@ -0,0 +1,72 @@ +EE895 CO₂, Temperature and Pressure Sensor +=================================================== + +.. seo:: + :description: Instructions for setting up EE895 CO₂ Temperature and Pressure + :image: EE895.png + +The ``ee895`` sensor platform allows you to use your EE895 CO₂ +(`datasheet `__, +`E+E TEE501 `__) sensor with ESPHome. +The :ref:`I²C Bus ` is required to be set up in your configuration for this sensor to work. We recommend the use of pull up resistors. + +.. figure:: images/EE895.png + :align: center + :width: 80.0% + + + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: ee895 + co2: + name: "Office CO2" + accuracy_decimals: 0 + temperature: + name: "Office Temperature" + accuracy_decimals: 2 + pressure: + name: "Office Pressure" + accuracy_decimals: 1 + address: 0x5F + update_interval: 15s + +Configuration variables: +------------------------ + +- **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. + + - **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. + + - **name** (**Required**, string): The name for the Pressure sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. + Defaults to ``0x5F``. + +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`tee501` +- :doc:`hte501` +- :doc:`dht` +- :doc:`dht12` +- :apiref:`ee895/ee895.h` +- :ghedit:`Edit` diff --git a/components/sensor/hte501.rst b/components/sensor/hte501.rst new file mode 100644 index 000000000..6f9badbaa --- /dev/null +++ b/components/sensor/hte501.rst @@ -0,0 +1,60 @@ +HTE501 Temperature+Humidity Sensor +=================================== + +.. seo:: + :description: Instructions for setting up HTE501 temperature and humidity sensors + :image: HTE501.png + +The ``hte501`` sensor platform Temperature+Humidity sensor allows you to use your HTE501 +(`datasheet `__ , +`E+E HTE501 `__) sensor with +ESPHome. The :ref:`I²C Bus ` is +required to be set up in your configuration for this sensor to work. + + +.. figure:: images/HTE501.png + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: hte501 + temperature: + name: "Office Temperature" + humidity: + name: "Office Humidity" + address: 0x40 + update_interval: 60s + +Configuration variables: +------------------------ + +- **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 `. + +- **humidity** (**Required**): The information for the humidity sensor. + + - **name** (**Required**, string): The name for the humidity sensor. + - **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. + - All other options from :ref:`Sensor `. + +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. + Defaults to ``0x40``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`tee501` +- :doc:`ee895` +- :doc:`dht` +- :doc:`dht12` +- :apiref:`hte501/hte501.h` +- :ghedit:`Edit` diff --git a/components/sensor/images/EE895.png b/components/sensor/images/EE895.png new file mode 100644 index 000000000..f1cecf047 Binary files /dev/null and b/components/sensor/images/EE895.png differ diff --git a/components/sensor/images/HTE501.png b/components/sensor/images/HTE501.png new file mode 100644 index 000000000..d719fb7db Binary files /dev/null and b/components/sensor/images/HTE501.png differ diff --git a/components/sensor/images/TEE501.png b/components/sensor/images/TEE501.png new file mode 100644 index 000000000..c3b853066 Binary files /dev/null and b/components/sensor/images/TEE501.png differ diff --git a/components/sensor/images/ld2410.jpg b/components/sensor/images/ld2410.jpg new file mode 100644 index 000000000..5052b9110 Binary files /dev/null and b/components/sensor/images/ld2410.jpg differ diff --git a/components/sensor/images/mopeka_pro_check_lippert.jpg b/components/sensor/images/mopeka_pro_check_lippert.jpg new file mode 100644 index 000000000..c795d3468 Binary files /dev/null and b/components/sensor/images/mopeka_pro_check_lippert.jpg differ diff --git a/components/sensor/index.rst b/components/sensor/index.rst index a57f9f25d..edbcf8e10 100644 --- a/components/sensor/index.rst +++ b/components/sensor/index.rst @@ -433,7 +433,7 @@ An average over the ``specified time period``, potentially throttling incoming v For example a ``throttle_average: 60s`` will push out a value every 60 seconds, in case at least one sensor value is received within these 60 seconds. -In comparison to the ``throttle`` filter it won't discard any values. In comparison to the ``sliding_window_moving_average`` filter it supports variable sensor reporting rates without influencing the filter reporting interval (except for the first edge case). +In comparison to the ``throttle`` filter, it won't discard any values. In comparison to the ``sliding_window_moving_average`` filter, it supports variable sensor reporting rates without influencing the filter reporting interval (except for the first edge case). ``heartbeat`` ************* @@ -648,7 +648,7 @@ advanced stuff (see the full API Reference for more info). // For example, create a custom log message when a value is received: ESP_LOGI("main", "Value of my sensor: %f", id(my_sensor).state); -- ``raw_state``: Retrieve the current value of the sensor that has not passed through any filters +- ``raw_state``: Retrieve the current value of the sensor that has not passed through any filters. Is ``NAN`` if no value has been pushed by the sensor itself yet. .. code-block:: cpp diff --git a/components/sensor/ld2410.rst b/components/sensor/ld2410.rst new file mode 100644 index 000000000..dd0798239 --- /dev/null +++ b/components/sensor/ld2410.rst @@ -0,0 +1,186 @@ +LD2410 Sensor +============= + +.. seo:: + :description: Instructions for setting up LD2410 sensors. + :image: ld2410.jpg + +Component/Hub +------------- +.. _ld2410-component: + +The ``ld2410`` sensor platform allows you to use HI-LINK LD2410 motion and presence sensor. +(`datasheet and user manual `__) with ESPHome. +The :ref:`UART ` is required to be set up in your configuration for this sensor to work. + +Use of hardware UART pins is highly recommended, in order to support the out-of-the-box 256000 baud rate of the LD2410 sensor. + +.. figure:: images/ld2410.jpg + :align: center + :width: 50.0% + + LD2410 motion and presence sensor + +.. code-block:: yaml + + # Example configuration entry + uart: + id: uart1 + tx_pin: REPLACEME + rx_pin: REPLACEME + baud_rate: 256000 + parity: NONE + stop_bits: 1 + + ld2410: + timeout: 150s + max_move_distance : 6m + max_still_distance: 0.75m + g0_move_threshold: 10 + g0_still_threshold: 20 + g1_move_threshold: 10 + g1_still_threshold: 20 + g2_move_threshold: 20 + g2_still_threshold: 21 + g3_move_threshold: 30 + g3_still_threshold: 31 + g4_move_threshold: 40 + g4_still_threshold: 41 + g5_move_threshold: 50 + g5_still_threshold: 51 + g6_move_threshold: 60 + g6_still_threshold: 61 + g7_move_threshold: 70 + g7_still_threshold: 71 + g8_move_threshold: 80 + g8_still_threshold: 81 + + +.. note:: + + For UART configuration, ``baud_rate``, ``parity`` and ``stop_bits`` **must be** respectively ``256000``, ``NONE`` and ``1``. + + Use of hardware UART pins is highly recommended, in order to support the out-of-the-box 256000 baud rate of the LD2410 sensor. + +Configuration variables: +************************ + +The configuration is made up of three parts: The central component, individual sensors, +and binary sensors. + +- **timeout** (*Optional*, int): Time in seconds during which presence state will stay present + after leaving. Defaults to ``5s``. +- **max_move_distance** (*Optional*, int): Maximum distance for movement detection. + Value between ``0.75m`` and ``6m`` inclusive. Defaults to ``4.5m``. +- **max_still_distance** (*Optional*, int): Maximum distance for still detection. + 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). + 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 + :widths: 25 25 25 + :header-rows: 1 + + * - Gate + - Default Move threshold + - Default Still threshold + * - 0 + - 50 + - 0 + * - 1 + - 50 + - 0 + * - 2 + - 40 + - 40 + * - 3 + - 40 + - 40 + * - 4 + - 40 + - 40 + * - 5 + - 40 + - 40 + * - 6 + - 30 + - 15 + * - 7 + - 30 + - 15 + * - 8 + - 30 + - 15 + +Sensor +------ + +The ``ld2410`` sensor allows you to use your :doc:`ld2410` to perform different +measurements. + +.. code-block:: yaml + + sensor: + - platform: ld2410 + moving_distance: + name : Moving Distance + still_distance: + name: Still Distance + moving_energy: + name: Move Energy + still_energy: + name: Still Energy + detection_distance: + name: Detection Distance + +Configuration variables: +************************ + +- **moving_distance** (*Optional*): Distance of detected moving target. + All options from :ref:`Sensor `. +- **still_distance** (*Optional*): Distance of detected still target. + All options from :ref:`Sensor `. +- **moving_energy** (*Optional*): Energy for moving target. + All options from :ref:`Sensor `. +- **still_energy** (*Optional*): Energy for still target. + All options from :ref:`Sensor `. +- **detection_distance** (*Optional*): Distance in cm of target. + All options from :ref:`Sensor `. + +Binary Sensor +------------- + +The ``ld2410`` binary sensor allows you to use your :doc:`ld2410` to perform different +measurements. + +.. code-block:: yaml + + binary_sensor: + - platform: ld2410 + has_target: + name: Presence + has_moving_target: + name: Moving Target + has_still_target: + name: Still Target + +Configuration variables: +************************ + +- **has_target** (*Optional*): If true target detect either still or in movement. + All options from :ref:`Binary Sensor `. +- **has_moving_target** (*Optional*): If true a moving target is detected. + All options from :ref:`Binary Sensor `. +- **has_still_target** (*Optional*): If true a still target is detected. + All options from :ref:`Binary Sensor `. + + +See Also +-------- + +- `Official Datasheet and user manuals `_ +- `Source of inspiration for implementation `_ +- :apiref:`ld2410/ld2410.h` +- :ghedit:`Edit` diff --git a/components/sensor/mics_4514.rst b/components/sensor/mics_4514.rst new file mode 100644 index 000000000..b337c59ef --- /dev/null +++ b/components/sensor/mics_4514.rst @@ -0,0 +1,53 @@ +MiCS 4514 Gas Sensor +==================== + +.. seo:: + :description: Instructions for setting up MiCS 4514 Gas sensors. + :image: mics_4514.jpg + :keywords: MiCS, 4514, MICS-4514 + +This component exposes the different gas concentration sensors from the `MiCS-4514 `__. + +.. note:: + + The sensor has a 3-minute warmup period where data is unreliable and ESPHome will only start publishing sensor values after this time. + If the sensor was already powered only, such as if you restarted or updated your ESPHome device, then it will start publishing immediately. + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: mics_4514 + nitrogen_dioxide: + name: Nitrogen Dioxide + carbon_monoxide: + name: Carbon Monoxide + hydrogen: + name: Hydrogen + ethanol: + name: Ethanol + methane: + name: Methane + ammonia: + name: Ammonia + update_interval: 60s + +Configuration variables: +------------------------ + +- **pin** (**Required**, :ref:`config-pin`): The pin where the DHT bus is connected. +- **nitrogen_dioxide** (*Optional*): All options from :ref:`Sensor ` +- **carbon_monoxide** (*Optional*): All options from :ref:`Sensor ` +- **hydrogen** (*Optional*): All options from :ref:`Sensor ` +- **ethanol** (*Optional*): All options from :ref:`Sensor ` +- **methane** (*Optional*): All options from :ref:`Sensor ` +- **ammonia** (*Optional*): All options from :ref:`Sensor ` +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. + +See Also +-------- + +- :ref:`sensor-filters` +- :apiref:`mics_4514/mics_4514.h` +- :ghedit:`Edit` diff --git a/components/sensor/mopeka_pro_check.rst b/components/sensor/mopeka_pro_check.rst index 0e41101d1..49f63091d 100644 --- a/components/sensor/mopeka_pro_check.rst +++ b/components/sensor/mopeka_pro_check.rst @@ -2,25 +2,31 @@ Mopeka Pro Check BLE Sensor =========================== .. seo:: - :description: Instructions for setting up Mopeka Pro Check bluetooth-based sensors in ESPHome. + :description: Instructions for setting up Mopeka Pro Check or Lippert Propane Tank bluetooth-based sensors in ESPHome. :image: mopeka_pro_check.jpg - :keywords: Mopeka, Mopeka Pro Check, Mopeka Pro Plus, BLE, Bluetooth + :keywords: Mopeka, Mopeka Pro Check, Mopeka Pro Plus, Lippert, Lippert Propane, Lippert Propane Sensor, Lippert Propane Tank Sensor, BLE, Bluetooth -The ``mopeka_pro_check`` sensor platform lets you track the output of Mopeka -Pro Check LP and Mopeka Pro Plus Bluetooth Low Energy devices using the -:doc:`/components/esp32_ble_tracker`. This component will track the tank level, -distance, temperature, and battery percentage of a Mopeka Pro Check LP or Mopeka -Pro Plus Residential BLE device every time the sensor sends out a BLE broadcast. +The ``mopeka_pro_check`` sensor platform lets you track the output of Mopeka Pro +Check LP, Mopeka Pro Plus, or Lippert Propane Tank Sensors, Bluetooth Low +Energy devices using the :doc:`/components/esp32_ble_tracker`. This component +will track the tank level, distance, temperature, and battery percentage of a +Mopeka Pro Check LP or Mopeka Pro Plus Residential BLE device every time the +sensor sends out a BLE broadcast. .. warning:: - This sensor component only supports the Mopeka Pro Check and Pro Plus devices. - The original Mopeka Check sensors are not supported. + This sensor component only supports the following sensors: + + Mopeka Pro Check devices + + Mopeka Pro Plus devices + + Lippert Propane Tank Sensor, part number 2021130655 -.. figure:: images/mopeka_pro_check.jpg - :align: center +(images/mopeka_pro_check.jpg) +(images/mopeka_pro_check_lippert.jpg) - Mopeka Pro Check LP over BLE. +The original Mopeka Check sensors are not supported. + +Mopeka Pro Check LP over BLE: +----------------------------- .. code-block:: yaml @@ -59,7 +65,7 @@ Pro Plus Residential BLE device every time the sensor sends out a BLE broadcast. Configuration variables: ------------------------ -- **mac_address** (**Required**, MAC Address): The MAC address of the Mopeka +- **mac_address** (**Required**, MAC Address): The MAC address of the Mopeka/Lippert device. - **tank_type** (**Required**): The tank type the sensor is measuring. See below. @@ -101,7 +107,7 @@ Currently supported Tank types are: Setting Up Devices ------------------ -To set up Mopeka Pro Check / Pro Plus devices you first need to find their MAC Address so that +To set up Mopeka Pro Check / Mopeka Pro Plus / Lippert Propane Tank Sensor devices you first need to find their MAC Address so that ESPHome can identify them. So first, create a simple configuration with the ``esp32_ble_tracker`` and the ``mopeka_ble`` component like so: @@ -112,7 +118,7 @@ and the ``mopeka_ble`` component like so: mopeka_ble: After uploading, the ESP32 will immediately try to scan for BLE devices. For Mopeka Pro -Check / Pro Plus devices you must press and hold the green sync button for it to be identified. +Check / Pro Plus / Lippert devices you must press and hold the green sync button for it to be identified. For all sensors found the ``mopeka_ble`` component will print a message like this one: .. code:: @@ -124,7 +130,7 @@ Then just copy the address (``D3:75:F2:DC:16:91``) into a new .. note:: - The ESPHome Mopeka Pro Check BLE integration listens passively to packets the Mopeka device sends by itself. + The ESPHome Mopeka Pro Check BLE integration listens passively to packets the Mopeka/Lippert device sends by itself. ESPHome therefore has no impact on the battery life of the device. See Also @@ -134,4 +140,5 @@ See Also - :doc:`/components/sensor/index` - :apiref:`mopeka_pro_check/mopeka_pro_check.h` - `Mopeka `__ +- `Lippert `__ - :ghedit:`Edit` diff --git a/components/sensor/scd30.rst b/components/sensor/scd30.rst index 65950b4f6..73fd2a452 100644 --- a/components/sensor/scd30.rst +++ b/components/sensor/scd30.rst @@ -74,6 +74,36 @@ Configuration variables: - **update_interval** (*Optional*, :ref:`config-time`): The interval to check the sensor. Defaults to ``60s``. + +Manual calibration: +------------------------ + +.. code-block:: yaml + + # Example on how to implement a UI section in HA for manual calibration. + # Note: Please enter first a CO2 value before pressing the button. + button: + - platform: template + name: "SCD30 Force manual calibration" + entity_category: "config" + on_press: + then: + - scd30.force_recalibration_with_reference: + value: !lambda 'return id(co2_cal).state;' + + number: + - platform: template + name: "CO2 calibration value" + optimistic: true + min_value: 350 + max_value: 4500 + step: 1 + id: co2_cal + icon: "mdi:molecule-co2" + entity_category: "config" + + + See Also -------- diff --git a/components/sensor/tee501.rst b/components/sensor/tee501.rst new file mode 100644 index 000000000..6901247f3 --- /dev/null +++ b/components/sensor/tee501.rst @@ -0,0 +1,47 @@ +TEE501 Temperature Sensor +========================== + +.. seo:: + :description: Instructions for setting up TEE501 temperature sensors + :image: TEE501.png + +The ``hte501`` sensor platform Temperature sensor allows you to use your TEE501 +(`datasheet `__, +`E+E TEE501 `__) sensor with +ESPHome. The :ref:`I²C Bus ` is +required to be set up in your configuration for this sensor to work. + +.. figure:: images/TEE501.png + :align: center + :width: 80.0% + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: tee501 + name: "Office Temperature" + address: 0x48 + update_interval: 60s + +Configuration variables: +------------------------ + +- **name** (**Required**, string): The name for the temperature sensor. +- **address** (*Optional*, int): Manually specify the I²C address of the sensor. + Defaults to ``0x48``. +- **update_interval** (*Optional*, :ref:`config-time`): The interval to check the + sensor. Defaults to ``60s``. +- **id** (*Optional*, :ref:`config-id`): Set the ID of this sensor for use in lambdas. +- All other options from :ref:`Sensor `. + +See Also +-------- + +- :ref:`sensor-filters` +- :doc:`hte501` +- :doc:`ee895` +- :doc:`dht` +- :doc:`dht12` +- :apiref:`tee501/tee501.h` +- :ghedit:`Edit` diff --git a/components/sensor/tsl2591.rst b/components/sensor/tsl2591.rst index cb4092d79..a7df0e95e 100644 --- a/components/sensor/tsl2591.rst +++ b/components/sensor/tsl2591.rst @@ -59,6 +59,10 @@ Since those are two different physical infrared sensor readings, there is the po If you are not happy with that built-in calculation, you have the raw data you need to do your own. The manufacturer, AMS, has a few application notes that discuss this topic. See the references. +- **actual_gain**: The actual gain value being used for values reported. Updates whenever ``gain`` is changed, + which is especially useful when the sensor is set to ``gain: auto`` to help denote relative brightness when + extreme changes in brightness are encountered. + Values reported are said to be in units of ``lux``, but there are some things to understand about that. @@ -85,6 +89,7 @@ Values reported are said to be in units of ``lux``, but there are some things to id: "my_tls2591" address: 0x29 update_interval: 60s + gain: auto device_factor: 53 glass_attenuation_factor: 14.4 visible: @@ -96,6 +101,9 @@ Values reported are said to be in units of ``lux``, but there are some things to calculated_lux: id: i_lux name: "TSL2591 Lux" + actual_gain: + id: "actual_gain" + name: "TSL2591 actual gain" Configuration variables: ------------------------ @@ -164,6 +172,11 @@ Each configured sensor is reported separately on each ``update_interval``. - **name** (**Required**, string): The name for the sensor. - All other options from :ref:`Sensor `. +- **actual_gain** (*Optional*): The value of gain used for reported values. Particularly useful when gain is set to "auto". + + - **name** (**Required**, string): The name for the sensor. + - All other options from :ref:`Sensor `. + Power save mode ............... Sensor readings are only taken when the device indicates that the ADC values are valid. diff --git a/components/time/pcf85063.rst b/components/time/pcf85063.rst new file mode 100644 index 000000000..31e2bf4be --- /dev/null +++ b/components/time/pcf85063.rst @@ -0,0 +1,99 @@ +PCF85063 Time Source +==================== + +You first need to set up the :doc:`I2C ` component. + +.. code-block:: yaml + + # Example configuration entry + time: + - platform: pcf85063 + id: pcf85063_time + +Configuration variables +----------------------- + +- **address** (*Optional*, int): Manually specify the I²C address of the RTC. Defaults to ``0x51``. +- All other options from :ref:`base_time_config`. + + +.. _pcf85063-write_time_action: + +``pcf85063.write_time`` Action +------------------------------ + +This :ref:`Action ` triggers a synchronization of the current system time to the RTC hardware. + +.. note:: + + PCFe pcf85063 component will *not* write the RTC clock if not triggered *explicitly* by this action. + +.. code-block:: yaml + + on_...: + - pcf85063.write_time + + # in case you need to specify the DS1307 id + - pcf85063.write_time: + id: pcf85063_time + + +.. _pcf85063-read_time_action: + +``pcf85063.read_time`` Action +----------------------------- + +This :ref:`Action ` triggers a synchronization of the current system time from the RTC hardware. + +.. note:: + + The PCF85063 component will automatically read the RTC clock every 15 minutes by default and synchronize the + system clock when a valid timestamp was read from the RTC. (The ``update_interval`` can be changed.) + This action can be used to trigger *additional* synchronizations. + +.. code-block:: yaml + + on_...: + - pcf85063.read_time + + # in case you need to specify the DS1307 id + - pcf85063.read_time: + id: pcf85063_time + + +.. _pcf85063-config_example: + +Full Configuration Example +-------------------------- + +In a typical setup, you will have at least one additional time source to synchronize the RTC with. Such an +external time source might not always be available e.g. due to a limited network connection. +In order to have a valid, reliable system time, the system should read the RTC once at start and then try to +synchronize with an external reliable time source. +When a synchronization to another time source was successful, the RTC can be resynchronized. + +.. code-block:: yaml + + esphome: + on_boot: + then: + # read the RTC time once when the system boots + pcf85063.read_time: + + time: + - platform: pcf85063 + # repeated synchronization is not necessary unless the external RTC + # is much more accurate than the internal clock + update_interval: never + - platform: homeassistant + # instead try to synchronize via network repeatedly ... + on_time_sync: + then: + # ... and update the RTC when the synchronization was successful + pcf85063.write_time: + + +See Also +-------- + +- :ghedit:`Edit` diff --git a/components/vbus.rst b/components/vbus.rst new file mode 100644 index 000000000..9cb76c84b --- /dev/null +++ b/components/vbus.rst @@ -0,0 +1,274 @@ +VBus Component +============== + +.. seo:: + :description: Instructions for integrating a solar energy collector controller using VBus protocol in ESPHome. + :image: resol_deltasol_bs_plus.jpg + :keywords: VBUS RESOL SOLAR + +The ``VBus`` Component provides status reading connectivity to solar heat energy collector controllers using VBus +protocol. These devices are mainly produced by Resol, often also found under different brand names like Viessmann, +Kioto, Wagner etc. The component currently supports natively Resol DeltaSol C, DeltaSol CS2, DeltaSol CS Plus, and DeltaSol BS Plus +but any device can be added via lambda by knowing `its packet structure `__. + +.. figure:: ../images/resol_deltasol_bs_plus.jpg + :align: center + +The device must be connected via a :doc:`UART bus ` supporting the receiving line only. The UART bus +must be configured at the same speed of the module which is by default 9600bps. The controller outputs data every second. + +To connect to this and read data from the bus a level shifting is needed as the voltage is around 8V (direct connection +would damage the MCU). Although this is a symmetric connection supporting long wires, for our read-only purposes it's +enough to adapt the level appropriately to 3.3V using a circuit like below: + +.. figure:: ../images/resol_vbus_adapter_schematic.png + :align: center + +Another approach, with PCB design ready to be manufactured `can be found here `__. + +.. warning:: + + Do not connect the GND pin of your module with the ground of Resol unit as that may damage the output port of it. + The output of the device is symmetric, meaning that the signal is not referenced to the ground, but rather it's a + differential signal between the two wires. However, the MCU references the signal against the ground, so the two + grounds are not supposed to be connected to each other as can be seen in the circuit depicted above. + + +Component +--------- + +.. code-block:: yaml + + # Example configuration entry + uart: + id: resol + rx_pin: GPIO3 + baud_rate: 9600 + + vbus: + uart_id: resol + + logger: + baud_rate: 0 # disable uart logger on ESP8266 + +.. warning:: + + If you are using the :doc:`logger` make sure you are not using the same pins for it or otherwise disable the UART + logging with the ``baud_rate: 0`` option. + +Configuration variables: + +- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub used to connect to the device. + +.. note:: + + Functionality of the sensors depends on the type of the device and the the scheme arrangement of the hydraulic + system it controls. The actual arrangement number set up can be determined from the settings of the device. Please + check the user manual and assess your arrangement to determine the functionality of each sensor and name them + accordingly. + + +Sensor +------ + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: vbus + model: deltasol_bs_plus + temperature_1: + name: Temperature 1 + temperature_2: + name: Temperature 2 + temperature_3: + name: Temperature 3 + temperature_4: + name: Temperature 4 + pump_speed_1: + name: Pump Speed 1 + pump_speed_2: + name: Pump Speed 2 + operating_hours_1: + name: Operating Hours 1 + operating_hours_2: + name: Operating Hours 2 + heat_quantity: + name: Heat Quantity + time: + name: Device Time + version: + name: Device firmware version + + +Configuration variables: + +- **model** (**Required**): Specify the model of the connected controller. Currently supported models are: ``deltasol_bs_plus``, ``deltasol_c``, ``deltasol_cs2``, ``deltasol_cs_plus``. + + +Supported sensors: + +- for **deltasol_bs_plus**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``pump_speed_1``, ``pump_speed_2``, ``operating_hours_1``, ``operating_hours_2``, ``heat_quantity``, ``time``, ``version``. +- for **deltasol_c**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``pump_speed_1``, ``pump_speed_2``, ``operating_hours_1``, ``operating_hours_2``, ``heat_quantity``, ``time``. +- for **deltasol_cs2**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``pump_speed``, ``operating_hours``, ``heat_quantity``, ``version``. +- for **deltasol_cs_plus**: ``temperature_1``, ``temperature_2``, ``temperature_3``, ``temperature_4``, ``temperature_5``, ``pump_speed_1``, ``pump_speed_2``, ``operating_hours_1``, ``operating_hours_2``, ``heat_quantity``, ``time``, ``version``, ``flow_rate``. + + +All sensors are *Optional* and support all other options from :ref:`Sensor `. + +.. note:: + + Sensors are updated every time a data packet is sent by the device. Some models send data very often, possibly every second. If you are + concerned about the load on the receiving database, you can add a ``throttle`` filter to the sensors. + + + +Binary Sensor +------------- + +.. code-block:: yaml + + # Example configuration entry + binary_sensor: + - platform: vbus + model: deltasol_bs_plus + relay1: + name: Relay 1 On + relay2: + name: Relay 2 On + sensor1_error: + name: Sensor 1 Fault + sensor2_error: + name: Sensor 2 Fault + sensor3_error: + name: Sensor 3 Fault + sensor4_error: + name: Sensor 4 Fault + collector_max: + name: Option Collector Max + collector_min: + name: Option Collector Min + collector_frost: + name: Option Collector Frost + tube_collector: + name: Option Tube Collector + recooling: + name: Option Recooling + hqm: + name: Option Heat Quantity Measurement + + +Configuration variables: + +- **model** (**Required**): Specify the model of the connected controller. Currently supported models are: ``deltasol_bs_plus``, ``deltasol_c``, ``deltasol_cs2``, ``deltasol_cs_plus``. + +Supported sensors: + +- 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_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``. + + +All binary sensors are *Optional* and support all other options from :ref:`Binary Sensor `. + + +``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. + + +.. code-block:: yaml + + sensor: + - platform: vbus + model: custom + dest: 0x10 + source: 0x1234 + command: 0x100 + sensors: + - id: temp1 + name: Temp 1 + lambda: return ((x[1] << 8) + x[0]) / 10.0; + + +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`. + + +``custom`` VBus binary sensors +------------------------------ + +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). +- **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`. + +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. + +To extract the values with a :ref:`lambda `, look in the packet structure by clicking the **Bytes** link in the table. Each value is placed at an ``offset`` within the packet. +For ``float`` values, let's look at the temperature example: the value is stored as a ``16``-bit value in ``2`` bytes little-endian format. Since it's always the second byte containing the upper byte, it needs to be shifted by ``8`` bits (multiplied by ``256``) (e.g. ``0x34, 0x12 -> 0x1234``). The result needs to be multiplied by the factor, which is ``0.1``, to obtain the correct values: ``((x[1] << 8) + x[0]) * 0.1f)``. The number within the square brackets is the ``[offset]``. +For ``binary`` values, multiple binary values are stored within a single numeric value encoded with a bitmask. To extract the binary value all you have to do is to apply *bitwise AND* operator ``&`` between the value at the corresponding offset and the ``mask`` shown in the table. + +For example to decode some sensors of `DeltaSol BS Plus` via lambdas: + +.. code-block:: yaml + + # Example configuration entry + sensor: + - platform: vbus + model: custom + dest: 0x10 + source: 0x4221 + command: 0x100 + sensors: + - id: scheme + name: Arrangement scheme + icon: mdi:pipe-wrench + accuracy_decimals: 0 + entity_category: diagnostic + lambda: return x[14]; // Configured arrangement scheme + - id: temp2 + name: Temperature DHW + state_class: measurement + unit_of_measurement: "°C" + lambda: return ((x[3] << 8) + x[2]) * 0.1f; // Temperature 2 + + binary_sensor: + - platform: vbus + model: custom + dest: 0x10 + source: 0x4221 + command: 0x100 + binary_sensors: + - name: Heat Quantity Measurement On + id: bin_hqm + icon: mdi:counter + lambda: return x[15] & 0x20; // Option Heat Quantity Measurement enabled + + +See Also +-------- + +- :doc:`/components/uart` +- :doc:`/components/binary_sensor/index` +- :doc:`/components/sensor/index` +- `Resol manuals `__ +- `VBus protocol `__ +- :ghedit:`Edit` diff --git a/components/wiegand.rst b/components/wiegand.rst new file mode 100644 index 000000000..c59c92951 --- /dev/null +++ b/components/wiegand.rst @@ -0,0 +1,77 @@ +Wiegand keypad and tag reader +============================= + +.. seo:: + :description: Wiegand-standard key input and card/tag reader panel + :image: wiegand.jpg + +The ``wiegand`` component allows you to integrate Wiegand-standard key +input and card or tag reader panels in Home Assistant. + +.. figure:: ../images/wiegand.jpg + :align: center + + S20-ID keypad and tag reader + + +.. note:: + + Some keypads are preconfigured by the factory to act as Wiegand input + devices. In order to work with this component, they may need to + be reconfigured to act as *Wiegand 26 output* or *Wiegand 34 output* + devices. + + +Component +--------- + +.. code-block:: yaml + + # Example configuration entry + wiegand: + - id: mykeypad + d0: GPIO5 + d1: GPIO4 + on_key: + - lambda: ESP_LOGI("KEY", "received key %d", x); + on_tag: + - lambda: ESP_LOGI("TAG", "received tag %s", x.c_str()); + on_raw: + - lambda: ESP_LOGI("RAW", "received raw %d bits, value %llx", bits, value); + + + +Configuration variables: + +- **id** (*Optional*, :ref:`config-id`): Set the ID of this device for use in lambdas. +- **d0** (**Required**, :ref:`Pin Schema `): The pin where the ``D0`` output + of the Wiegand's interface connects. +- **d1** (**Required**, :ref:`Pin Schema `): The pin where the ``D1`` output + of the Wiegand's interface connects. + + +Automations: +------------ + +- **on_key** (*Optional*, :ref:`Automation `): An automation to perform + when a key has been pressed on the pad. The key is in a variable called ``x``. +- **on_tag** (*Optional*, :ref:`Automation `): An automation to perform + when a Wiegand-compatible card or a tag has been read by the device. The tag code is + in a variable called ``x``. +- **on_raw** (*Optional*, :ref:`Automation `): An automation to perform + for any data sent by the device. The value is in a variable called ``value``, the number of + bits is in a variable called ``bits``. Note that this will include parity bits as well and + no parity checking is done. + + +.. note:: + + Automatic handling of multiple keys (e.g. PIN code entry) is possible with the + the :ref:`Key Collector ` component. + + +See Also +-------- + +- :doc:`/components/key_collector` +- :ghedit:`Edit` diff --git a/conf.py b/conf.py index e2a16aa86..117d93052 100644 --- a/conf.py +++ b/conf.py @@ -67,9 +67,9 @@ author = "ESPHome" # built documents. # # The short X.Y version. -version = "2022.12" +version = "2023.2" # The full version, including alpha/beta/rc tags. -release = "2022.12.7" +release = "2023.2.0b1" # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/cookbook/iaq_board.rst b/cookbook/iaq_board.rst index 53ae96af6..260866611 100644 --- a/cookbook/iaq_board.rst +++ b/cookbook/iaq_board.rst @@ -50,6 +50,7 @@ See Also - :doc:`/devices/nodemcu_esp8266` - :doc:`/components/display/ssd1306` - :doc:`/components/sensor/bme280` +- :doc:`/components/sensor/ee895` - :doc:`/components/sensor/pmsx003` - :doc:`/components/sensor/mhz19` - :doc:`/components/sensor/sgp30` diff --git a/guides/automations.rst b/guides/automations.rst index 32e4a6083..638376364 100644 --- a/guides/automations.rst +++ b/guides/automations.rst @@ -394,6 +394,7 @@ All Actions - :ref:`rf_bridge.send_code ` - :ref:`rf_bridge.learn ` - :ref:`ds1307.read_time ` / :ref:`ds1307.write_time ` +- :ref:`pcf85063.read_time ` / :ref:`pcf85063.write_time ` - :ref:`cs5460a.restart ` - :ref:`pzemac.reset_energy ` - :ref:`number.set ` / :ref:`number.to_min ` / :ref:`number.to_max ` / :ref:`number.decrement ` / :ref:`number.increment ` / :ref:`number.operation ` @@ -712,8 +713,8 @@ Configuration variables: - **max_runs** (*Optional*, int): Allows limiting the maxiumun number of runs when using script modes ``queued`` and ``parallel``, use value ``0`` for unlimited runs. Defaults to ``0``. -- **parameters** (*Optional*, :ref:`Script Parameters `): A script can define one - or more parameters that must be provided in order to execute. All parameters defined here are +- **parameters** (*Optional*, :ref:`Script Parameters `): A script can define one + or more parameters that must be provided in order to execute. All parameters defined here are mandatory and must be given when calling the script. - **then** (**Required**, :ref:`Action `): The action to perform. @@ -723,7 +724,7 @@ Configuration variables: ``Script Parameters`` --------------------- -Scripts can be defined with parameters. The arguments given when calling the script can be used within +Scripts can be defined with parameters. The arguments given when calling the script can be used within the script's lambda actions. To define the parameters, add the parameter names under `parameters:` key and specify the data type for that parameter. @@ -765,7 +766,7 @@ script was already running. on_...: then: - script.execute: my_script - + # Calling a non-parameterised script in a lambda - lambda: id(my_script).execute(); @@ -806,7 +807,7 @@ will not be executed. or as lambda -.. code-block:: yaml +.. code-block:: yaml lambda: 'id(my_script).stop();' diff --git a/guides/configuration-types.rst b/guides/configuration-types.rst index 5fd0f0248..a8a0dcc53 100644 --- a/guides/configuration-types.rst +++ b/guides/configuration-types.rst @@ -110,6 +110,7 @@ Configuration variables: - ``ANALOG`` - ``INPUT_PULLUP`` - ``INPUT_PULLDOWN`` + - ``INPUT_OUTPUT_OPEN_DRAIN`` Advanced options: diff --git a/guides/creators.rst b/guides/creators.rst index 05389b7ca..4f7bc7189 100644 --- a/guides/creators.rst +++ b/guides/creators.rst @@ -61,6 +61,7 @@ Example configuration # Sets up the improv via serial client for Wi-Fi provisioning improv_serial: + next_url: https://example.com/project-template/manual?ip={{ip_address}}&name={{device_name}}&version={{esphome_version}} Relevant Documentation diff --git a/guides/diy.rst b/guides/diy.rst index 52df042d5..5c328f1a1 100644 --- a/guides/diy.rst +++ b/guides/diy.rst @@ -57,6 +57,7 @@ Blog Posts & Videos - `Little thermostat based on AZ-Touch hardware and esphome `_ by ingbenna - `Converting a Carro Home DC Fan to ESPHome `__ by `Bill Church `__ - `Automated Coffee Bean Roaster `__ by `brooksben11 `__ +- `Droplet Smart Irrigation System `__ by `PricelessToolkit `__ Custom Components & Code ------------------------ diff --git a/guides/getting_started_command_line.rst b/guides/getting_started_command_line.rst index 4f59111e3..ca0257553 100644 --- a/guides/getting_started_command_line.rst +++ b/guides/getting_started_command_line.rst @@ -133,7 +133,7 @@ to your docker command to map a local USB device. Docker on Mac will not be able .. code-block:: bash - docker run --rm -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome run livingroom.yaml + docker run --rm --privileged -v "${PWD}":/config --device=/dev/ttyUSB0 -it esphome/esphome run livingroom.yaml Now when you go to the Home Assistant "Integrations" screen (under "Configuration" panel), you should see the ESPHome device show up in the discovered section (although this can take up to 5 minutes). diff --git a/guides/migrate_sonoff_tasmota.rst b/guides/migrate_sonoff_tasmota.rst index 8f3accd06..bfcc19f35 100644 --- a/guides/migrate_sonoff_tasmota.rst +++ b/guides/migrate_sonoff_tasmota.rst @@ -58,7 +58,7 @@ Happy Hacking! .. note:: - If you are using Tasmota 8+ and get an error after uploading the firmware, go to the console and type ```SetOption78 1```, then restart the device and try the firmware again. + If you are using Tasmota 8+ on ESP8266 and get an error after uploading the firmware, first upload ``tasmota-minimal.bin.gz`` from Tasmota repository, next upload firmware generated from ESPHome. Another way to try is to simply ``gzip`` the ESPHome binary and upload the ``.gz`` file instead. See Also -------- diff --git a/guides/supporters.rst b/guides/supporters.rst index 1d5f949ac..3497c9373 100644 --- a/guides/supporters.rst +++ b/guides/supporters.rst @@ -256,6 +256,7 @@ Contributors - `Sergey V. DUDANOV (@dudanov) `__ - `David Girón (@duhow) `__ - `Duncan Findlay (@duncf) `__ +- `Jannick (@DutchDeffy) `__ - `dyarkovoy (@dyarkovoy) `__ - `Janez Troha (@dz0ny) `__ - `Dimitris Zervas (@dzervas) `__ @@ -272,6 +273,7 @@ Contributors - `Eike (@ei-ke) `__ - `Elazar Leibovich (@elazarl) `__ - `Elkropac (@Elkropac) `__ +- `Joakim Plate (@elupus) `__ - `EmbeddedDevver (@EmbeddedDevver) `__ - `EmmanuelLM (@EmmanuelLM) `__ - `Emory Dunn (@emorydunn) `__ @@ -296,6 +298,7 @@ Contributors - `Fabian Affolter (@fabaff) `__ - `Federico Ariel Castagnini (@facastagnini) `__ - `C W (@fake-name) `__ +- `Florian idB (@fbeek) `__ - `Fabian Berthold (@fbrthld) `__ - `Felix Storm (@felixstorm) `__ - `Christian Ferbar (@ferbar) `__ @@ -320,6 +323,7 @@ Contributors - `frippe75 (@frippe75) `__ - `Fritz Mueller (@fritzm) `__ - `Marc Egli (@frog32) `__ +- `Florian Trück (@ftrueck) `__ - `functionpointer (@functionpointer) `__ - `mr G1K (@G1K) `__ - `Aljaž Srebrnič (@g5pw) `__ @@ -391,7 +395,6 @@ Contributors - `Ignacio Hernandez-Ros (@IgnacioHR) `__ - `Petko Bordjukov (@ignisf) `__ - `ikatkov (@ikatkov) `__ -- `Tim Smeets (@ikilledmypc) `__ - `iKK001 (@iKK001) `__ - `imgbot[bot] (@imgbot[bot]) `__ - `ImSorryButWho (@ImSorryButWho) `__ @@ -439,6 +442,7 @@ Contributors - `Jesse Hills (@jesserockz) `__ - `Yuval Brik (@jhamhader) `__ - `Joe (@jhansche) `__ +- `Jan Pieter Waagmeester (@jieter) `__ - `Jim Bauwens (@jimbauwens) `__ - `jimtng (@jimtng) `__ - `Jérémy JOURDIN (@JJK801) `__ @@ -486,7 +490,6 @@ Contributors - `Keilin Bickar (@kbickar) `__ - `Keith Burzinski (@kbx81) `__ - `Ken Piper (@Kealper) `__ -- `Tom Keller (@kellertk) `__ - `Robert Kiss (@kepten) `__ - `Kevin O'Rourke (@kevinior) `__ - `Khoi Hoang (@khoih-prog) `__ @@ -564,13 +567,13 @@ Contributors - `maringeph (@maringeph) `__ - `Mario (@mario-tux) `__ - `Marek Marczykowski-Górecki (@marmarek) `__ -- `Matthew Harrold (@marrold) `__ - `marsjan155 (@marsjan155) `__ - `Martin (@martgras) `__ - `Martin Hjelmare (@MartinHjelmare) `__ - `MartinWelsch (@MartinWelsch) `__ - `MasterTim17 (@MasterTim17) `__ - `Christopher Masto (@masto) `__ +- `Mat931 (@Mat931) `__ - `Mateus Demboski (@mateusdemboski) `__ - `matikij (@matikij) `__ - `Michel Marti (@matoxp) `__ @@ -593,13 +596,13 @@ Contributors - `Marco Lusini (@met67) `__ - `Martin Flasskamp (@MFlasskamp) `__ - `Michael Gorven (@mgorven) `__ +- `Michael Muré (@MichaelMure) `__ - `Micha Nordmann (@Michanord) `__ - `Pauline Middelink (@middelink) `__ - `Mikko Tervala (@MikkoTervala) `__ - `MiKuBB (@MiKuBB) `__ - `André Klitzing (@misery) `__ - `Tomasz (@Misiu) `__ -- `Matthew Edwards (@mje-nz) `__ - `Matthew Garrett (@mjg59) `__ - `Maarten (@mjkl-gh) `__ - `Morton Jonuschat (@mjonuschat) `__ @@ -609,6 +612,7 @@ Contributors - `mmanza (@mmanza) `__ - `mnltake (@mnltake) `__ - `Matt N. (@mnoorenberghe) `__ +- `Michał Obrembski (@mobrembski) `__ - `Moritz Glöckl (@moritzgloeckl) `__ - `Chris Laplante (@mostthingsweb) `__ - `Sam Hughes (@MrEditor97) `__ @@ -688,7 +692,6 @@ Contributors - `Philippe FOUQUET (@Philippe12) `__ - `pieterbrink123 (@pieterbrink123) `__ - `Piotr Kubiak (@piotr-kubiak) `__ -- `Tommy van der Vorst (@pixelspark) `__ - `Peter Kuehne (@pkuehne) `__ - `Plácido Revilla (@placidorevilla) `__ - `Marcus Kempe (@plopp) `__ @@ -741,6 +744,7 @@ Contributors - `Roi Tagar (@roitagar) `__ - `Jérôme W. (@RomRider) `__ - `rotarykite (@rotarykite) `__ +- `Bob Perciaccante (@rperciaccante) `__ - `rradar (@rradar) `__ - `rspaargaren (@rspaargaren) `__ - `rsumner (@rsumner) `__ @@ -836,15 +840,12 @@ Contributors - `Tijs-B (@Tijs-B) `__ - `Aidan Timson (@timmo001) `__ - `Tim Niemueller (@timn) `__ -- `Tim P (@timpur) `__ - `Tim Savage (@timsavage) `__ - `Snōwball (@tobias-) `__ - `Philipp Tölke (@toelke) `__ - `tomaszduda23 (@tomaszduda23) `__ - `Tom Brien (@TomBrien) `__ -- `TomFahey (@TomFahey) `__ - `tomlut (@tomlut) `__ -- `Tom Matheussen (@Tommatheussen) `__ - `tomle (@tomole444) `__ - `Tom Price (@tomtom5152) `__ - `David Kiliani (@torfbolt) `__ @@ -907,4 +908,4 @@ Contributors - `Zack Barett (@zsarnett) `__ - `Christian Zufferey (@zuzu59) `__ -*This page was last updated January 26, 2023.* +*This page was last updated February 9, 2023.* diff --git a/images/EE895.png b/images/EE895.png new file mode 100644 index 000000000..873466d1a Binary files /dev/null and b/images/EE895.png differ diff --git a/images/HTE501.png b/images/HTE501.png new file mode 100644 index 000000000..f03abe5e6 Binary files /dev/null and b/images/HTE501.png differ diff --git a/images/TEE501.png b/images/TEE501.png new file mode 100644 index 000000000..e7383fe72 Binary files /dev/null and b/images/TEE501.png differ diff --git a/images/bp1658cj.svg b/images/bp1658cj.svg new file mode 100644 index 000000000..f900e8372 --- /dev/null +++ b/images/bp1658cj.svg @@ -0,0 +1 @@ +BP1658CJ \ No newline at end of file diff --git a/images/bp5758d.svg b/images/bp5758d.svg new file mode 100644 index 000000000..e0a9d8980 --- /dev/null +++ b/images/bp5758d.svg @@ -0,0 +1 @@ +BP5758D \ No newline at end of file diff --git a/images/ld2410.jpg b/images/ld2410.jpg new file mode 100644 index 000000000..5052b9110 Binary files /dev/null and b/images/ld2410.jpg differ diff --git a/images/matrix_keypad.jpg b/images/matrix_keypad.jpg new file mode 100644 index 000000000..eec629e7d Binary files /dev/null and b/images/matrix_keypad.jpg differ diff --git a/images/mics_4514.jpg b/images/mics_4514.jpg new file mode 100644 index 000000000..da99e90f1 Binary files /dev/null and b/images/mics_4514.jpg differ diff --git a/images/pca9554a.jpg b/images/pca9554a.jpg new file mode 100644 index 000000000..2085ce232 Binary files /dev/null and b/images/pca9554a.jpg differ diff --git a/images/resol_deltasol_bs_plus.jpg b/images/resol_deltasol_bs_plus.jpg new file mode 100644 index 000000000..0eaf55349 Binary files /dev/null and b/images/resol_deltasol_bs_plus.jpg differ diff --git a/images/resol_vbus_adapter_schematic.png b/images/resol_vbus_adapter_schematic.png new file mode 100644 index 000000000..c77c57cb3 Binary files /dev/null and b/images/resol_vbus_adapter_schematic.png differ diff --git a/images/sigma-delta.svg b/images/sigma-delta.svg new file mode 100644 index 000000000..56a417c2f --- /dev/null +++ b/images/sigma-delta.svg @@ -0,0 +1,50 @@ + + + + + + + + + + + diff --git a/images/sm2235.svg b/images/sm2235.svg new file mode 100644 index 000000000..f04d064ee --- /dev/null +++ b/images/sm2235.svg @@ -0,0 +1 @@ +SM2235 \ No newline at end of file diff --git a/images/sm2335.svg b/images/sm2335.svg new file mode 100644 index 000000000..ae3cd6603 --- /dev/null +++ b/images/sm2335.svg @@ -0,0 +1 @@ +SM2335 \ No newline at end of file diff --git a/images/wiegand.jpg b/images/wiegand.jpg new file mode 100644 index 000000000..481c69123 Binary files /dev/null and b/images/wiegand.jpg differ diff --git a/images/x9c.jpg b/images/x9c.jpg new file mode 100644 index 000000000..b355f2679 Binary files /dev/null and b/images/x9c.jpg differ diff --git a/index.rst b/index.rst index 8dad5e4a2..90af27ca5 100644 --- a/index.rst +++ b/index.rst @@ -171,8 +171,10 @@ Air Quality AirThings BLE, components/sensor/airthings_ble, airthings_logo.png, Radon, CO2, Volatile organics CCS811, components/sensor/ccs811, ccs811.jpg, CO2 & Volatile organics + EE895, components/sensor/ee895, EE895.png, CO2 & Temperature & Pressure HM3301, components/sensor/hm3301, hm3301.jpg, Particulate MH-Z19, components/sensor/mhz19, mhz19.jpg, CO2 & Temperature + MiCS-4514, components/sensor/mics_4514, mics_4514.jpg, Gas concentration PM1006 Sensor, components/sensor/pm1006, pm1006.jpg, Particulate PMSA003I, components/sensor/pmsa003i, pmsa003i.jpg, Particulate PMSX003, components/sensor/pmsx003, pmsx003.svg, Particulate @@ -287,6 +289,7 @@ Environmental DPS310, components/sensor/dps310, dps310.jpg, Temperature & Pressure ENS210, components/sensor/ens210, ens210.jpg, Temperature & Humidity HDC1080, components/sensor/hdc1080, hdc1080.jpg, Temperature & Humidity + HTE501, components/sensor/hte501, HTE501.png, Temperature & Humidity Honeywell ABP, components/sensor/honeywellabp, honeywellabp.jpg, Pressure & Temperature HTU21D / Si7021 / SHT21, components/sensor/htu21d, htu21d.jpg, Temperature & Humidity Hydreon Rain Sensor, components/sensor/hydreon_rgxx, hydreon_rg9.jpg, Rain @@ -307,6 +310,7 @@ Environmental SHTCx, components/sensor/shtcx, shtc3.jpg, Temperature & Humidity SMT100, components/sensor/smt100, smt100.jpg, Moisture & Temperature STS3X, components/sensor/sts3x, sts3x.jpg, Temperature + TEE501, components/sensor/tee501, TEE501.png, Temperature TMP102, components/sensor/tmp102, tmp102.jpg, Temperature TMP117, components/sensor/tmp117, tmp117.jpg, Temperature @@ -354,6 +358,7 @@ Miscellaneous TX20, components/sensor/tx20, tx20.jpg, Wind speed & Wind direction uFire EC sensor, components/sensor/ufire_ec, ufire_ec.png, EC & Temperature uFire ISE sensor, components/sensor/ufire_ise, ufire_ise.png, pH & Temperature + Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg Motion @@ -364,6 +369,7 @@ Motion MPU6050, components/sensor/mpu6050, mpu6050.jpg, Accelerometer & Gyroscope MPU6886, components/sensor/mpu6886, mpu6886.jpg, Accelerometer & Gyroscope RuuviTag, components/sensor/ruuvitag, ruuvitag.jpg, Temperature & Humidity & Accelerometer + LD2410, components/sensor/ld2410, ld2410.jpg, Motion & Presence Thermocouple @@ -415,6 +421,8 @@ Binary Sensor Components XPT2046, components/binary_sensor/xpt2046, xpt2046.jpg CAP1188 Capacitive Touch Sensor, components/binary_sensor/cap1188, cap1188.jpg Touchscreen, components/touchscreen/index, touch.svg + Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg + LD2410, components/sensor/ld2410, ld2410.jpg Custom Binary Sensor, components/binary_sensor/custom, language-cpp.svg Output Components @@ -435,6 +443,8 @@ Output Components MY9231/MY9291, components/output/my9231, my9231.svg SM16716, components/output/sm16716, sm16716.svg SM2135, components/output/sm2135, sm2135.svg + SM2235, components/output/sm2235, sm2235.svg + SM2335, components/output/sm2335, sm2335.svg MCP4725, components/output/mcp4725, mcp4725.jpg MCP4728, components/output/mcp4728, mcp4728.jpg MCP47A1, components/output/mcp47a1, mcp47a1.svg @@ -442,7 +452,11 @@ 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 Template Output, components/output/template, description.svg + BP1658CJ, components/output/bp1658cj, bp1658cj.svg + BP5758D, components/output/bp5758d, bp5758d.svg + X9C Potentiometer, components/output/x9c, x9c.jpg Light Components ---------------- @@ -655,6 +669,7 @@ Time Components SNTP, components/time/sntp, clock-outline.svg GPS Time, components/time/gps, crosshairs-gps.svg DS1307 RTC, components/time/ds1307, clock-outline.svg + PCF85063 RTC, components/time/pcf85063, clock-outline.svg Misc Components --------------- @@ -666,6 +681,8 @@ Misc Components Status LED, components/status_led, led-on.svg Display Menu Core, components/display_menu/index, folder-open.svg LCD Menu, components/display_menu/lcd_menu, lcd_menu.png + Matrix Keypad, components/matrix_keypad, matrix_keypad.jpg + Wiegand Reader, components/wiegand, wiegand.jpg HTTP Request, components/http_request, connection.svg mDNS, components/mdns, radio-tower.svg @@ -685,6 +702,7 @@ Misc Components Servo, components/servo, servo.svg Sprinkler, components/sprinkler, sprinkler-variant.svg + PCA9554 I/O Expander, components/pca9554, pca9554a.jpg PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg MCP230XX I/O Expander - I²C Bus, components/mcp230xx, mcp230xx.svg TCA9548A I²C Multiplexer, components/tca9548a, tca9548a.jpg @@ -709,6 +727,7 @@ Misc Components Grow Fingerprint Reader, components/fingerprint_grow, fingerprint.svg SML, components/sml, sml.svg Atlas Scientific Peristaltic Pump, components/ezo_pmp, ezo-pmp.jpg + Resol VBus, components/vbus, resol_deltasol_bs_plus.jpg Demo, components/demo, description.svg Copy, components/copy, content-copy.svg