From 52cd23c7336a453ded99fb462bcf72648f37af1b Mon Sep 17 00:00:00 2001 From: Otto Winter Date: Mon, 13 May 2019 21:51:04 +0200 Subject: [PATCH] Remote + Dev docs update --- .travis.yml | 2 +- Makefile | 5 +- changelog/v1.7.0.rst | 10 +- changelog/v1.8.0.rst | 2 +- components/binary_sensor/remote_receiver.rst | 127 ---- .../images/remote_transmitter-ui.png | Bin .../images/rf_receiver-log_raw.png | Bin components/light/index.rst | 7 +- components/remote_receiver.rst | 209 +++++++ components/remote_transmitter.rst | 544 ++++++++++++++++++ components/switch/remote_transmitter.rst | 433 -------------- guides/contributing.rst | 267 +++++++-- index.rst | 26 +- 13 files changed, 1006 insertions(+), 626 deletions(-) delete mode 100644 components/binary_sensor/remote_receiver.rst rename components/{switch => }/images/remote_transmitter-ui.png (100%) rename components/{switch => }/images/rf_receiver-log_raw.png (100%) create mode 100644 components/remote_receiver.rst create mode 100644 components/remote_transmitter.rst delete mode 100644 components/switch/remote_transmitter.rst diff --git a/.travis.yml b/.travis.yml index e0288ea25..74a11f924 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,4 +3,4 @@ python: "3.6" install: pip install -r requirements.txt script: - python3 travis.py -- make html +- make html-strict diff --git a/Makefile b/Makefile index f35226aa3..5133086ba 100644 --- a/Makefile +++ b/Makefile @@ -1,9 +1,12 @@ ESPHOME_PATH = ../esphome ESPHOME_REF = dev -.PHONY: html cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png +.PHONY: html html-strict cleanhtml deploy help webserver Makefile netlify netlify-api api netlify-dependencies svg2png copy-svg2png html: + sphinx-build -M html . _build $(O) + +html-strict: sphinx-build -M html . _build -W $(O) cleanhtml: diff --git a/changelog/v1.7.0.rst b/changelog/v1.7.0.rst index cb8a3fa0a..7991a2c1d 100644 --- a/changelog/v1.7.0.rst +++ b/changelog/v1.7.0.rst @@ -25,9 +25,9 @@ be travelling a lot (and enjoying my vacation 😎), so don't expect too many aw Duty Cycle Sensor, components/sensor/duty_cycle, percent.svg Pulse Counter for ESP8266, components/sensor/pulse_counter, pulse.svg - Remote Transmitter, components/switch/remote_transmitter, remote.svg + Remote Transmitter, components/remote_transmitter, remote.svg - Remote Receiver, components/binary_sensor/remote_receiver, remote.svg + Remote Receiver, components/remote_receiver, remote.svg New Components ************** @@ -52,8 +52,8 @@ New Components measure how much of the time a specific pin is HIGH or LOW. Can for example be used to detect if a status LED on an external device is blinking or permanently on. -- The new :doc:`remote receiver ` and - :doc:`remote transmitter ` components now allows you to use any 433MHz +- The new :doc:`remote receiver ` and + :doc:`remote transmitter ` components now allows you to use any 433MHz receivers and senders with ESPHome. Currently, you will need to use the ``raw`` data as described in :ref:`this guide `, but in the future more protocols will be supported out of the box. @@ -118,7 +118,7 @@ Breaking Changes - The ``receive_timeout`` option has been removed from the :doc:`i2c component ` as it turns out it didn't actually do anything. -- The ``ir_transmitter`` component has been renamed to :doc:`remote_transmitter ` +- The ``ir_transmitter`` component has been renamed to :doc:`remote_transmitter ` as it now works with all kinds of protocols, not just infrared-based ones. - The ``pull_mode`` option of the :doc:`Pulse Counter ` has been removed, please diff --git a/changelog/v1.8.0.rst b/changelog/v1.8.0.rst index 6dc36a9b4..b8e5f5058 100644 --- a/changelog/v1.8.0.rst +++ b/changelog/v1.8.0.rst @@ -14,7 +14,7 @@ Version 1.8.0 MAX7219, components/display/max7219, max7219.jpg LCD Display, components/display/lcd_display, lcd.jpg - RCSwitch Integration, components/switch/remote_transmitter.html#rcswitch-remote-codes, remote.svg + RCSwitch Integration, components/remote_transmitter.html#rcswitch-remote-codes, remote.svg SPI Bus, components/spi, spi.svg UART Bus, components/uart, uart.svg diff --git a/components/binary_sensor/remote_receiver.rst b/components/binary_sensor/remote_receiver.rst deleted file mode 100644 index 3def3ed33..000000000 --- a/components/binary_sensor/remote_receiver.rst +++ /dev/null @@ -1,127 +0,0 @@ -Remote Receiver -=============== - -.. seo:: - :description: Instructions for setting up remote receiver binary sensors for infrared and RF codes. - :image: remote.png - :keywords: RF, infrared - -.. _remote-receiver-component: - -Component/Hub -------------- - -The ``remote_receiver`` component lets you receive and decode any remote signal, these can -for example be infrared remotes or 433MHz signals. - -The component is split up into two parts: the remote receiver hub which can be used to -receive, decode and dump all remote codes, and individual -:ref:`remote receiver binary sensors ` which will trigger when they -hear their own configured signal. - -.. code-block:: yaml - - # Example configuration entry - remote_receiver: - pin: GPIO32 - dump: all - - -Configuration variables: -************************ - -- **pin** (**Required**, :ref:`config-pin`): The pin to receive the remote signal on. -- **dump** (*Optional*, list): Decode and dump these remote codes in the logs. Set to ``all`` to - dump all available codecs: - - - **lg**: Decode and dump LG infrared codes. - - **nec**: Decode and dump NEC infrared codes. - - **panasonic**: Decode and dump Panasonic infrared codes. - - **jvc**: Decode and dump JVC infrared codes. - - **samsung**: Decode and dump Samsung infrared codes. - - **sony**: Decode and dump Sony infrared codes. - - **rc_switch**: Decode and dump RCSwitch RF codes. - - **rc5**: Decode and dump RC5 IR codes. - - **raw**: Print all remote codes in their raw form. Useful for using arbitrary protocols. - -- **tolerance** (*Optional*, int): The percentage that the remote signal lengths can deviate in the - decoding process. Defaults to ``25%``. -- **buffer_size** (*Optional*, int): The size of the internal buffer for storing the remote codes. Defaults to ``10kb`` - on the ESP32 and ``1kb`` on the ESP8266. -- **filter** (*Optional*, :ref:`time `): Filter any pulses that are shorter than this. Useful for removing - glitches from noisy signals. Defaults to ``10us``. -- **idle** (*Optional*, :ref:`time `): The amount of time that a signal should remain stable (i.e. not - change) for it to be considered complete. Defaults to ``10ms``. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this if you have - multiple remote transmitters. - -.. note:: - - See :ref:`finding_remote_codes` for a guide for setting this up. - -.. _remote-receiver-binary-sensor: - -Binary Sensor -------------- - -The ``remote_receiver`` binary sensor lets you track when a button on a remote control is pressed. - -Each time the pre-defined signal is received, the binary sensor will briefly go ON and -then immediately OFF. - -.. code-block:: yaml - - # Example configuration entry - remote_receiver: - pin: GPIO32 - dump: all - - binary_sensor: - - platform: remote_receiver - name: "Panasonic Remote Input" - panasonic: - address: 0x4004 - command: 0x100BCBD - -Configuration variables: -************************ - -- **name** (**Required**, string): The name for the binary sensor. -- The remote code, see :ref:`remote_transmitter-codes`. Only one - of them can be specified per binary sensor. -- **remote_receiver_id** (*Optional*, :ref:`config-id`): The id of the :ref:`remote-receiver-component`. - Defaults to the first hub in your configuration. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Binary Sensor `. - -.. note:: - - See :ref:`finding_remote_codes` for a guide for setting this up. - -.. note:: - - For the Sonoff RF Bridge you can use `this hack `__ - created by the Github user wildwiz. Then use this configuration for the remote receiver/transmitter hubs: - - .. code-block:: yaml - - remote_receiver: - pin: 4 - dump: all - - remote_transmitter: - pin: 5 - carrier_duty_percent: 100% - - Supporting the RF Bridge chip directly is currently only a long-term goal for ESPHome. - - -See Also --------- - -- :doc:`index` -- :doc:`/components/switch/remote_transmitter` -- `RCSwitch `__ by `Suat Γ–zgΓΌr `__ -- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ -- :apiref:`remote/remote_receiver.h` -- :ghedit:`Edit` diff --git a/components/switch/images/remote_transmitter-ui.png b/components/images/remote_transmitter-ui.png similarity index 100% rename from components/switch/images/remote_transmitter-ui.png rename to components/images/remote_transmitter-ui.png diff --git a/components/switch/images/rf_receiver-log_raw.png b/components/images/rf_receiver-log_raw.png similarity index 100% rename from components/switch/images/rf_receiver-log_raw.png rename to components/images/rf_receiver-log_raw.png diff --git a/components/light/index.rst b/components/light/index.rst index dd6cd2059..63498aa0c 100644 --- a/components/light/index.rst +++ b/components/light/index.rst @@ -265,7 +265,7 @@ to a specific color. on_...: - light.addressable_set: id: my_light - range_from: 1 + range_from: 0 range_to: 50 red: 100% green: 0% @@ -275,9 +275,10 @@ Configuration variables: - **id** (**Required**, :ref:`config-id`): The ID of the addressable light to control. - **range_from** (*Optional*, :ref:`templatable `, int): The beginning - of the range of LEDs to control. 1-based indexing. Defaults to 1 (the beginning of the strip). + of the range of LEDs to control. 0-based indexing. Defaults to 0 (the beginning of the strip). - **range_to** (*Optional*, :ref:`templatable `, int): The end of the - range of LEDs to control. 1-based indexing. Defaults to the end of the strip. + range of LEDs to control - this is a half-open interval. 0-based indexing. + Defaults to the end of the strip (``num_leds``). - **red** (*Optional*, :ref:`templatable `, percentage): The value to set the red channel to. - **green** (*Optional*, :ref:`templatable `, percentage): The value to diff --git a/components/remote_receiver.rst b/components/remote_receiver.rst new file mode 100644 index 000000000..5ddc37535 --- /dev/null +++ b/components/remote_receiver.rst @@ -0,0 +1,209 @@ +Remote Receiver +=============== + +.. seo:: + :description: Instructions for setting up remote receiver binary sensors for infrared and RF codes. + :image: remote.png + :keywords: RF, infrared + +The ``remote_receiver`` component lets you receive and decode any remote signal, these can +for example be infrared remotes or 433MHz signals. + +The component is split up into two parts: the remote receiver hub which +handles setting the pin and some other settings, and individual +:ref:`remote receiver binary sensors ` +which will trigger when they hear their own configured signal. + +**See :ref:`remote-setting-up-infrared` and :ref:`remote-setting-up-rf` for set up guides.** + +.. code-block:: yaml + + # Example configuration entry + remote_receiver: + pin: GPIO32 + dump: all + +Configuration variables: +------------------------ + +- **pin** (**Required**, :ref:`config-pin`): The pin to receive the remote signal on. +- **dump** (*Optional*, list): Decode and dump these remote codes in the logs. Set to ``all`` to + dump all available codecs: + + - **lg**: Decode and dump LG infrared codes. + - **nec**: Decode and dump NEC infrared codes. + - **panasonic**: Decode and dump Panasonic infrared codes. + - **jvc**: Decode and dump JVC infrared codes. + - **samsung**: Decode and dump Samsung infrared codes. + - **sony**: Decode and dump Sony infrared codes. + - **rc_switch**: Decode and dump RCSwitch RF codes. + - **rc5**: Decode and dump RC5 IR codes. + - **raw**: Print all remote codes in their raw form. Useful for using arbitrary protocols. + +- **tolerance** (*Optional*, int): The percentage that the remote signal lengths can deviate in the + decoding process. Defaults to ``25%``. +- **buffer_size** (*Optional*, int): The size of the internal buffer for storing the remote codes. Defaults to ``10kb`` + on the ESP32 and ``1kb`` on the ESP8266. +- **filter** (*Optional*, :ref:`time `): Filter any pulses that are shorter than this. Useful for removing + glitches from noisy signals. Defaults to ``10us``. +- **idle** (*Optional*, :ref:`time `): The amount of time that a signal should remain stable (i.e. not + change) for it to be considered complete. Defaults to ``10ms``. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. Use this if you have + multiple remote transmitters. + +Automations: + +- **on_jvc** (*Optional*, :ref:`Automation `): An automation to perform when a + JVC remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::JVCData` + is passed to the automation for use in lambdas. +- **on_lg** (*Optional*, :ref:`Automation `): An automation to perform when a + LG remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::LGData` + is passed to the automation for use in lambdas. +- **on_nec** (*Optional*, :ref:`Automation `): An automation to perform when a + NEC remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::NECData` + is passed to the automation for use in lambdas. +- **on_sony** (*Optional*, :ref:`Automation `): An automation to perform when a + NEC remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::SonyData` + is passed to the automation for use in lambdas. +- **on_raw** (*Optional*, :ref:`Automation `): An automation to perform when a + raw remote code has been decoded. A variable ``x`` of type ``std::vector`` + is passed to the automation for use in lambdas. +- **on_rc5** (*Optional*, :ref:`Automation `): An automation to perform when a + RC5 remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::RC5Data` + is passed to the automation for use in lambdas. +- **on_samsung** (*Optional*, :ref:`Automation `): An automation to perform when a + samsung remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::SamsungData` + is passed to the automation for use in lambdas. +- **on_panasonic** (*Optional*, :ref:`Automation `): An automation to perform when a + panasonic remote code has been decoded. A variable ``x`` of type :apiclass:`remote_base::PanasonicData` + is passed to the automation for use in lambdas. + +.. _remote-receiver-binary-sensor: + +Binary Sensor +------------- + +The ``remote_receiver`` binary sensor lets you track when a button on a remote control is pressed. + +Each time the pre-defined signal is received, the binary sensor will briefly go ON and +then immediately OFF. + +.. code-block:: yaml + + # Example configuration entry + remote_receiver: + pin: GPIO32 + dump: all + + binary_sensor: + - platform: remote_receiver + name: "Panasonic Remote Input" + panasonic: + address: 0x4004 + command: 0x100BCBD + +Configuration variables: +************************ + +- **name** (**Required**, string): The name for the binary sensor. +- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. +- All other options from :ref:`Binary Sensor `. + +Remote code selection (exactly one of these has to be included): + +- **jvc**: Trigger on a decoded JVC remote code with the given data. + + - **data** (**Required**, int): The JVC code to trigger on, see dumper output for more info. + +- **lg**: Trigger on a decoded LG remote code with the given data. + + - **data** (**Required**, int): The LG code to trigger on, see dumper output for more info. + - **nbits** (*Optional*, int): The number of bits of the remote code. Defaults to ``28``. + +- **nec**: Trigger on a decoded NEC remote code with the given data. + + - **address** (**Required**, int): The address to trigger on, see dumper output for more info. + - **command** (**Required**, int): The NEC command to listen for. + +- **sony**: Trigger on a decoded Sony remote code with the given data. + + - **data** (**Required**, int): The Sony code to trigger on, see dumper output for more info. + - **nbits** (*Optional*, int): The number of bits of the remote code. Defaults to ``12``. + +- **raw**: Trigger on a raw remote code with the given code. + + - **code** (**Required**, list): The code to listen for, see :ref:`remote_transmitter-transmit_raw` + for more info. Usually you only need to copy this directly from the dumper output. + +- **rc5**: Trigger on a decoded RC5 remote code with the given data. + + - **address** (**Required**, int): The address to trigger on, see dumper output for more info. + - **command** (**Required**, int): The RC5 command to listen for. + +- **samsung**: Trigger on a decoded Samsung remote code with the given data. + + - **data** (**Required**, int): The data to trigger on, see dumper output for more info. + +- **panasonic**: Trigger on a decoded Panasonic remote code with the given data. + + - **address** (**Required**, int): The address to trigger on, see dumper output for more info. + - **command** (**Required**, int): The command. + +- **rc_switch_raw**: Trigger on a decoded RC Switch raw remote code with the given data. + + - **code** (**Required**, string): The remote code to listen for, copy this from the dumper output. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + +- **rc_switch_type_a**: Trigger on a decoded RC Switch Type A remote code with the given data. + + - **group** (**Required**, string): The group, binary string. + - **device** (**Required**, string): The device in the group, binary string. + - **state** (**Required**, boolean): The on/off state to trigger on. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + +- **rc_switch_type_b**: Trigger on a decoded RC Switch Type B remote code with the given data. + + - **address** (**Required**, int): The address, int from 1 to 4. + - **channel** (**Required**, int): The channel, int from 1 to 4. + - **state** (**Required**, boolean): The on/off state to trigger on. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + +- **rc_switch_type_c**: Trigger on a decoded RC Switch Type C remote code with the given data. + + - **family** (**Required**, string): The family. Range is ``a`` to ``p``. + - **group** (**Required**, int): The group. Range is 1 to 4. + - **device** (**Required**, int): The device. Range is 1 to 4. + - **state** (**Required**, boolean): The on/off state to trigger on. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + +- **rc_switch_type_d**: Trigger on a decoded RC Switch Type D remote code with the given data. + + - **group** (**Required**, int): The group. Range is 1 to 4. + - **device** (**Required**, int): The device. Range is 1 to 3. + - **state** (**Required**, boolean): The on/off state to trigger on. + - **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` for more info. + +.. note:: + + For the Sonoff RF Bridge you can use `this hack `__ + created by the Github user wildwiz. Then use this configuration for the remote receiver/transmitter hubs: + + .. code-block:: yaml + + remote_receiver: + pin: 4 + dump: all + + remote_transmitter: + pin: 5 + carrier_duty_percent: 100% + +See Also +-------- + +- :doc:`index` +- :doc:`/components/remote_transmitter` +- `RCSwitch `__ by `Suat Γ–zgΓΌr `__ +- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ +- :apiref:`remote/remote_receiver.h` +- :ghedit:`Edit` diff --git a/components/remote_transmitter.rst b/components/remote_transmitter.rst new file mode 100644 index 000000000..838e61875 --- /dev/null +++ b/components/remote_transmitter.rst @@ -0,0 +1,544 @@ +Remote Transmitter +================== + +.. seo:: + :description: Instructions for setting up switches that send out pre-defined sequences of IR or RF signals + :image: remote.png + :keywords: Infrared, IR, RF, Remote, TX + + +The ``remote_transmitter`` component lets you send digital packets to control +devices in your home. For example this includes infrared data or 433MHz RF signals. + +First, you need to setup a global hub that specifies which pin your remote +sender is connected to. Then you can use the available actions to send encoded +remote signals. + +**See :ref:`remote-setting-up-infrared` and :ref:`remote-setting-up-rf` for set up guides.** + +.. note:: + + This component is more accurate on the ESP32, since that chipset has a dedicated + peripheral for sending exact signal sequences. + +.. code-block:: yaml + + # Example configuration entry + remote_transmitter: + pin: GPIO32 + carrier_duty_percent: 50% + + # Individual switches + switch: + - platform: remote_transmitter + name: "Panasonic TV Off" + panasonic: + address: 0x4004 + command: 0x100BCBD + +Configuration variables: +------------------------ + +- **pin** (**Required**, :ref:`config-pin`): The pin to transmit the remote signal on. +- **carrier_duty_percent** (*Optional*, int): How much of the time the remote is on. For example, infrared + protocols modulate the signal using a carrier signal. Set this is ``50%`` if you're working with IR leds and to + ``100%`` if working with a other things like 433MHz transmitters. +- **id** (*Optional*, :ref:`config-id`): Manually specify + the ID used for code generation. Use this if you have multiple remote transmitters. + +.. _remote_transmitter-transmit_action: + +Remote Transmitter Actions +-------------------------- + +Remote transmitters support a number of :ref:`actions ` that can be used +to send remote codes. All supported protocols are listed below. All actions additionally +have these configuration variables: + +.. code-block::yaml + + on_...: + - remote_transmitter.transmit_x: + # ... + repeat: + times: 5 + wait_time: 10ms + +Configuration variables: + +- **repeat** (*Optional*): Optionally set the code to be repeated a number of times. + Defaults to sending the code only once. + + - **times** (int): The number of times to repeat the code. + - **wait_time** (:ref:`config-time`): The time to wait between repeats. + +- **transmitter_id** (*Optional*, :ref:`config-id`): The remote transmitter to send the + remote code with. Defaults to the first one defined in the configuration. + +.. _remote_transmitter-transmit_raw: + +``remote_transmitter.transmit_raw`` Action +****************************************** + +This :ref:`action ` sends a raw code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_raw: + code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022, + -1021, 1019, -1019, 511, -510, 510, -510, 1022, -1020, 1019, + -1020, 511, -511, 1018, -1022, 1020, -1019, 1021, -1019, 1020, + -511, 510, -1019, 1023, -1019, 1019, -510, 512, -508, 510, -511, + 512, -1019, 510, -509] + +Configuration variables: + +- **code** (**Required**, list): The raw code to send as a list of integers. + Positive numbers represent a digital high signal and negative numbers a digital low signal. + The number itself encodes how long the signal should last (in microseconds). +- **carrier_frequency** (*Optional*, float): Optionally set a frequency to send the signal + with for infrared signals. Defaults to ``0Hz``. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_jvc`` Action +****************************************** + +This :ref:`action ` sends a JVC infrared remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_jvc: + data: 0x1234 + +Configuration variables: + +- **data** (**Required**, int): The JVC code to send, see dumper output for more info. + +``remote_transmitter.transmit_lg`` Action +***************************************** + +This :ref:`action ` sends an LG infrared remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_lg: + data: 0x1234567 + nbits: 28 + +Configuration variables: + +- **data** (**Required**, int): The LG code to send, see dumper output for more info. +- **nbits** (*Optional*, int): The number of bits to send. Defaults to ``28``. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_nec`` Action +****************************************** + +This :ref:`action ` sends an NEC infrared remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_nec: + address: 0x1234 + command: 0x78AB + +Configuration variables: + +- **address** (**Required**, int): The address to send, see dumper output for more details. +- **command** (**Required**, int): The NEC command to send. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_sony`` Action +******************************************* + +This :ref:`action ` a Sony infrared remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmitsony: + data: 0x123 + nbits: 12 + +Configuration variables: + +- **data** (**Required**, int): The Sony code to send, see dumper output for more info. +- **nbits** (*Optional*, int): The number of bits to send. Defaults to ``12``. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_rc5`` Action +****************************************** + +This :ref:`action ` sends an RC5 infrared remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_rc5: + address: 0x1F + command: 0x3F + +Configuration variables: + +- **address** (**Required**, int): The address to send, see dumper output for more details. +- **command** (**Required**, int): The RC5 command to send. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_samsung`` Action +********************************************** + +This :ref:`action ` sends a Samsung infrared remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_samsung: + data: 0x1FEF05E4 + +Configuration variables: + +- **data** (**Required**, int): The data to send, see dumper output for more details. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_panasonic`` Action +************************************************ + +This :ref:`action ` sends a Panasonic infrared remote code to a remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_panasonic: + address: 0x1FEF + command: 0x1F3E065F + +Configuration variables: + +- **address** (**Required**, int): The address to send the command to, see dumper output for more details. +- **command** (**Required**, int): The command to send. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_rc_switch_raw`` Action +**************************************************** + +This :ref:`action ` sends a raw RC-Switch code to a +remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_rc_switch_raw: + code: '001010011001111101011011' + protocol: 1 + +Configuration variables: + +- **code** (**Required**, string): The raw code to send, copy this from the dump output. +- **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` + for more information. +- All other options from :ref:`remote_transmitter-transmit_action`. + +.. _remote_transmitter-rc_switch-protocol: + +RC Switch Protocol +^^^^^^^^^^^^^^^^^^ + +All RC Switch ``protocol`` settings have these settings: + +- Either the value is an integer, then the inbuilt protocol definition with the given number + is used. +- Or a key-value mapping is given, then there are these settings: + + - **pulse_length** (**Required**, int): The pulse length of the protocol - how many microseconds + one pulse should last for. + - **sync** (*Optional*): The number of high/low pulses for the sync header, defaults to ``[1, 31]`` + - **zero** (*Optional*): The number of high/low pulses for a zero bit, defaults to ``[1, 3]`` + - **one** (*Optional*): The number of high/low pulses for a one bit, defaults to ``[3, 1]`` + - **inverted** (*Optional*, boolean): If this protocol is inverted. Defaults to ``false``. + +``remote_transmitter.transmit_rc_switch_type_a`` Action +******************************************************* + +This :ref:`action ` sends a type A RC-Switch code to a +remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_rc_switch_type_a: + group: '01001' + device: '10110' + state: off + protocol: 1 + +Configuration variables: + +- **group** (**Required**, string): The group to send the command to. +- **device** (**Required**, string): The device in the group to send the command to. +- **state** (**Required**, boolean): The on/off state to send. +- **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` + for more information. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_rc_switch_type_b`` Action +******************************************************* + +This :ref:`action ` sends a type B RC-Switch code to a +remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_rc_switch_type_b: + address: '0100' + channel: '1011' + state: off + protocol: 1 + +Configuration variables: + +- **address** (**Required**, int): The address to send the command to. +- **channel** (**Required**, int): The channel to send the command to. +- **state** (**Required**, boolean): The on/off state to send. +- **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` + for more information. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_rc_switch_type_c`` Action +******************************************************* + +This :ref:`action ` sends a type C RC-Switch code to a +remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_rc_switch_type_c: + family: 'C' + group: 3 + device: 1 + state: off + protocol: 1 + +Configuration variables: + +- **family** (**Required**, string): The family to send the command to. Range is ``a`` to ``p``. +- **group** (**Required**, int): The group to send the command to. Range is 1 to 4. +- **device** (**Required**, int): The device to send the command to. Range is 1 to 4. +- **state** (**Required**, boolean): The on/off state to send. +- **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` + for more information. +- All other options from :ref:`remote_transmitter-transmit_action`. + +``remote_transmitter.transmit_rc_switch_type_d`` Action +******************************************************* + +This :ref:`action ` sends a type D RC-Switch code to a +remote transmitter. + +.. code-block:: yaml + + on_...: + - remote_transmitter.transmit_rc_switch_type_d: + group: 'c' + device: 1 + state: off + protocol: 1 + +Configuration variables: + +- **group** (**Required**, int): The group to send the command to. Range is 1 to 4. +- **device** (**Required**, int): The device to send the command to. Range is 1 to 3. +- **state** (**Required**, boolean): The on/off state to send. +- **protocol** (*Optional*): The RC Switch protocol to use, see :ref:`remote_transmitter-rc_switch-protocol` + for more information. +- All other options from :ref:`remote_transmitter-transmit_action`. + +.. _remote-setting-up-infrared: + +Setting up Infrared Devices +--------------------------- + +In this guide an infrared device will be set up with ESPHome. First, the remote code +will be captured with an IR receiver module (like `this one `__). +We will use ESPHome's dumping ability to output the decoded remote code directly. + +Then we will set up a new remote transmitter with an infrared LED (like +`this one `__) to transmit the +code when a switch is triggered. + +First, connect the infrared receiver module to a pin on your board and set up a +remote_receiver instance: + +.. code-block:: yaml + + remote_receiver: + pin: D0 + dump: all + +Compile and upload the code. While viewing the log output from the ESP, +press a button on an infrared remote you want to capture (one at a time). + +You should see log output like below: + +.. code-block:: text + + # If the codec is known: + [D][remote.panasonic] Received Panasonic: address=0x4004 command=0x8140DFA2 + + # Or raw output if it's not known yet + # The values may fluctuate a bit, but as long as they're similar it's ok + [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 + +If the codec is already implemented in ESPHome, you will see the decoded value directly - +otherwise you will see the raw data dump (which you can use just as well). You have +just successfully captured your first infrared code. + +Now let's use this information to emulate a button press from the ESP. First, wire up the +IR diode to a new pin on the ESP and configure a global ``remote_transmitter`` instance: + +.. code-block:: yaml + + remote_transmitter: + pin: D1 + # Infrared remotes use a 50% carrier signal + carrier_duty_percent: 50% + +This will allow us to send any data we want via the IR LED. To replicate the codes we decoded +earlier, create a new template switch that sends the infrared code when triggered: + +.. code-block:: yaml + + switch: + - platform: template + name: Panasonic Power Button + turn_on_action: + - remote_transmitter.transmit_panasonic: + address: 0x4004 + command: 0x8140DFA2 + + # Or for raw code + switch: + - platform: template + name: Raw Code Power Button + turn_on_action: + - remote_transmitter.transmit_raw: + code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] + +Recompile again, when you power up the device the next time you will see a new switch +in the frontend. Click on it and you should see the remote signal being transmitted. Done! + +.. _remote-setting-up-rf: + +Setting Up RF Devices +--------------------- + +The ``remote_transmitter`` and ``remote_receiver`` components can also be used to send +and receive 433MHz RF signals. This guide will discuss setting up a 433MHz receiver to +capture a device's remote codes. After that we will set up a 433MHz transmitter to replicate +the remote code with the press of a switch in the frontend. + +First, connect the RF module to a pin on the ESP and set up a remote_receiver instance: + +.. code-block:: yaml + + remote_receiver: + pin: D0 + dump: all + # Settings to optimize recognition of RF devices + tolerance: 50% + filter: 250us + idle: 4ms + buffer_size: 2kb + +Compile and upload the code. While viewing the log output from the ESP, +press a button on an RF remote you want to capture (one at a time). + +You should see log output like below: + +.. code-block:: text + + # If the codec is known: + [D][remote.rc_switch] Received RCSwitch: protocol=2 data='100010000000000010111110' + + # Or raw output if it's not known yet + # The values may fluctuate a bit, but as long as they're similar it's ok + [D][remote.raw] Received Raw: 4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + [D][remote.raw] -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + [D][remote.raw] 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022 + +.. note:: + + If the log output is flooded with "Received Raw" messages, you can also disable raw + remote code reporting and rely on rc_switch to decode the values. + + .. code-block:: yaml + + remote_receiver: + pin: D0 + dump: + - rc_switch + tolerance: 50% + filter: 250us + idle: 4ms + buffer_size: 2kb + +If the codec is already implemented in ESPHome, you will see the decoded value directly - +otherwise you will see the raw data dump (which you can use just as well). You have +just successfully captured your first RF code. + +Now let's use this information to emulate a button press from the ESP. First, wire up the +RF transmitter to a new pin on the ESP and configure a global ``remote_transmitter`` instance: + +.. code-block:: yaml + + remote_transmitter: + pin: D1 + # RF uses a 100% carrier signal + carrier_duty_percent: 100% + +This will allow us to send any data we want via the RF transmitter. To replicate the codes we decoded +earlier, create a new template switch that sends the RF code when triggered: + +.. code-block:: yaml + + switch: + - platform: template + name: RF Power Button + turn_on_action: + - remote_transmitter.transmit_rc_switch_raw: + code: '100010000000000010111110' + protocol: 2 + + # Or for raw code + switch: + - platform: template + name: Raw Code Power Button + turn_on_action: + - remote_transmitter.transmit_raw: + code: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, + -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, + 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022] + +Recompile again, when you power up the device the next time you will see a new switch +in the frontend. Click on it and you should see the remote signal being transmitted. Done! + +See Also +-------- + +- :doc:`index` +- :doc:`/components/remote_receiver` +- `RCSwitch `__ by `Suat Γ–zgΓΌr `__ +- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ +- :apiref:`remote_transmitter/remote_transmitter.h` +- :ghedit:`Edit` diff --git a/components/switch/remote_transmitter.rst b/components/switch/remote_transmitter.rst deleted file mode 100644 index d14e2e13e..000000000 --- a/components/switch/remote_transmitter.rst +++ /dev/null @@ -1,433 +0,0 @@ -Remote Transmitter -================== - -.. seo:: - :description: Instructions for setting up switches that send out pre-defined sequences of IR or RF signals - :image: remote.png - :keywords: Infrared, IR, RF, Remote, TX - -.. _remote-transmitter-component: - -Component/Hub -------------- - -The ``remote_transmitter`` component lets you send infrared messages to control -devices in your home. First, you need to setup a global hub that specifies which pin your remote -sender is connected to. Afterwards you can create :ref:`individual -switches ` that each send a pre-defined remote signal to a device. - -Use-cases are for example infrared remotes or 433MHz signals. - -.. note:: - - This component is *much* more accurate on the ESP32, since that chipset has a dedicated - peripheral for sending exact signal sequences. - -.. code-block:: yaml - - # Example configuration entry - remote_transmitter: - pin: GPIO32 - carrier_duty_percent: 50% - - # Individual switches - switch: - - platform: remote_transmitter - name: "Panasonic TV Off" - panasonic: - address: 0x4004 - command: 0x100BCBD - -Configuration variables: -************************ - -- **pin** (**Required**, :ref:`config-pin`): The pin to transmit the remote signal on. -- **carrier_duty_percent** (*Optional*, int): How much of the time the remote is on. For example, infrared - protocols modulate the signal using a carrier signal. Set this is ``50%`` if you're working with IR leds and to - ``100%`` if working with a other things like 433MHz transmitters. -- **id** (*Optional*, :ref:`config-id`): Manually specify - the ID used for code generation. Use this if you have multiple remote transmitters. - -.. note:: - - See :ref:`finding_remote_codes` for a guide for setting this up. - -.. _remote-transmitter-switch: - -Switch ------- - -The ``remote_transmitter`` switch platform allows you to create switches -that send a pre-defined remote control sequence -using the :ref:`remote-transmitter-component`. Every time -the switch is turned on, the configured remote signal is sent. - -Use cases include, but are not limited to, infrared remotes, 433MHz signals and so on. - -.. figure:: images/remote_transmitter-ui.png - :align: center - :width: 80.0% - -.. code-block:: yaml - - # Example configuration entry - remote_transmitter: - pin: 32 - - # Individual switches - switch: - - platform: remote_transmitter - name: "Panasonic TV Off" - panasonic: - address: 0x4004 - command: 0x100BCBD - repeat: 25 - -Configuration variables: -************************ - -- **name** (**Required**, string): The name for the switch. -- The remote code, see :ref:`remote_transmitter-codes`. Only one - of them can be specified per switch. -- **repeat** (*Optional*, int): How often the command should be sent. - - - **times** (int): The number of times the code should be sent. Defaults to ``1``. - - **wait_time** (:ref:`time `): The time to wait between repeats. - -- **remote_transmitter_id** (*Optional*, :ref:`config-id`): The id of the :ref:`remote-transmitter-component`. - Defaults to the first hub specified. -- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation. -- All other options from :ref:`Switch `. - -.. note:: - - For the Sonoff RF Bridge you can use `this hack `__ - created by the Github user wildwiz. Then use this configuration for the remote receiver/transmitter hubs: - - .. code-block:: yaml - - remote_receiver: - pin: 4 - dump: all - - remote_transmitter: - pin: 5 - carrier_duty_percent: 100% - - Supporting the RF Bridge chip directly is currently only a long-term goal for ESPHome. - -.. _remote_transmitter-codes: - -Remote Codes -************ - -Supported remote codes: - -.. code-block:: yaml - - switch: - - platform: remote_transmitter - # ... - Only one of these is allowed for one remote transmitter at a time - nec: - address: 0x4242 - command: 0x8484 - lg: - data: 0x01234567890ABC - nbits: 28 - samsung: - data: 0xE0E01234 - sony: - data: 0xABCDEF - nbits: 12 - panasonic: - address: 0x4004 - command: 0x1000BCD - jvc: - data: 0x1234 - rc_switch_raw: - code: '001010011001111101011011' - protocol: 1 - rc_switch_type_a: - group: '11001' - device: '01000' - state: True - rc_switch_type_b: - address: 4 - channel: 2 - state: True - rc_switch_type_c: - family: 'a' - group: 1 - device: 2 - state: True - rc_switch_type_d: - group: 'a' - device: 2 - state: True - rc5: - address: 0x00 - command: 0x0B - raw: - carrier_frequency: 35kHz - data: - - 1000 - - -1000 - -Configuration variables: - -- **nec**: Send a NEC IR code. - - - **address**: The address of the device. - - **command**: The command to send. - -- **lg**: Send an LG IR code. - - - **data**: The data bytes to send. - - **nbits**: The number of bits to send, defaults to 28. - -- **samsung**: Send an Samsung IR code. - - - **data**: The data bytes to send. - -- **sony**: Send an Sony IR code. - - - **data**: The data bytes to send. - - **nbits**: The number of bits to send, defaults to 12. - -- **panasonic**: Send an Panasonic IR code. - - - **address**: The address of the device. - - **command**: The command to send. - -- **jvc**: Send a JVC IR code. - - - **data**: The data bytes to send. - -- **rc_switch_raw**: Send an RCSwitch raw code. - - - **code** (**Required**, string): The code to send. Must be a string of 0s and 1s. - `For example `__ ``'001010011001111101011011'``. - - **protocol** (*Optional*, :ref:`RCSwitch protocol `): The RCSwitch protocol to use. Defaults to ``1``. - -- **rc_switch_type_a**: Send an RCSwitch `type A code `__. - - - **group** (**Required**, string): The group to address, usually the state of the first 5 DIP switches. - Must be a string of 0s and 1s. For example ``'11001``. - - **device** (**Required**, string): The device within the group, usually the state of the last 5 DIP switches. - Must be a string of 0s and 1s. For example ``'01000``. - - **state** (**Required**, boolean): Whether to send a "turn on" or "turn off" signal when this switch - is triggered. See :ref:`remote_transmitter-on_off_template`. - - **protocol** (*Optional*, :ref:`RCSwitch protocol `): The RCSwitch protocol to use. Defaults to ``1``. - -- **rc_switch_type_b**: Send an RCSwitch - `type B code `__. - - - **address** (**Required**, int): The number of the first rotary switch. For example ``4``. - - **channel** (**Required**, int): The number of the first rotary switch. For example ``2``. - - **state** (**Required**, boolean): Whether to send a "turn on" or "turn off" signal when this switch - is triggered. See :ref:`remote_transmitter-on_off_template`. - - **protocol** (*Optional*, :ref:`RCSwitch protocol `): The RCSwitch protocol to use. Defaults to ``1``. - -- **rc_switch_type_c**: Send an RCSwitch `type C code `__. - - - **family** (**Required**, string): The family of the device. Must be a character from ``a`` to ``p``. - - **group** (**Required**, int): The group of the device. For example ``4``. - - **address** (**Required**, int): The address of the device. For example ``2``. - - **state** (**Required**, boolean): Whether to send a "turn on" or "turn off" signal when this switch - is triggered. See :ref:`remote_transmitter-on_off_template`. - - **protocol** (*Optional*, :ref:`RCSwitch protocol `): The RCSwitch protocol to use. Defaults to ``1``. - -- **rc_switch_type_d**: Send an RCSwitch type D code. - - - **group** (**Required**, string): The group of the device. Must be a character from ``a`` to ``d``. - - **device** (**Required**, int): The address of the device. For example ``3``. - - **state** (**Required**, boolean): Whether to send a "turn on" or "turn off" signal when this switch - is triggered. See :ref:`remote_transmitter-on_off_template`. - - **protocol** (*Optional*, :ref:`RCSwitch protocol `): The RCSwitch protocol to use. Defaults to ``1``. - -- **rc5**: Send a RC5 IR code. - - - **address**: The address of the device. - - **command**: The command to send. - -- **raw**: Send an arbitrary signal. - - - **carrier_frequency**: The frequency to use for the carrier. A lot - of IR sensors only respond to a very specific frequency. - - **data**: List containing integers describing the signal to send. - Each value is a time in Β΅s declaring how long the carrier should - be switched on or off. Positive values mean ON, negative values - mean OFF. - -.. _finding_remote_codes: - -Finding Remote Codes --------------------- - -Each remote transmitter uses a different protocol to send its information. So to replicate an infrared or 433MHz -remote you will first need to "learn" these codes. You will first need to hook up a receiver and sniff the codes -using the :doc:`remote receiver component ` like this: - -.. code-block:: yaml - - remote_receiver: - pin: GPIO34 - # dump all signals we find - dump: all - -And then activate the remote control you want to have in ESPHome. you will see a log output like this: - -.. figure:: images/rf_receiver-log_raw.png - :align: center - - Example log output for a 433MHz proprietary remote control. - -Raw Remote Codes -**************** - -If ESPHome has a decoder set up for the code, it will spit out the decoded code in the logs. In this case, -it's a proprietary protocol which would be difficult to reverse engineer. Fortunately, we can just -do a "replay attack" by repeating the signal we just saw for our own purposes. The output you see in above image -is encoded in microseconds: A negative value represents the output being LOW for x microseconds and a positive -value denotes the output being HIGH for the specified number of microseconds. - -Now you only need to set up the remote transmitter (which well *send* the code) like this: - -.. code-block:: yaml - - remote_transmitter: - pin: GPIO23 - # Set to 100% when working with RF signals, and 50% if working with IR leds - carrier_duty_percent: 100% - -And lastly, we need to set up the switch that, when turned on, will send our pre-defined remote code: - -.. code-block:: yaml - - switch: - - platform: remote_transmitter - name: "My awesome RF switch" - raw: [4088, -1542, 1019, -510, 513, -1019, 510, -509, 511, -510, 1020, - -1020, 1022, -1019, 510, -509, 511, -510, 511, -509, 511, -510, - 1020, -1019, 510, -511, 1020, -510, 512, -508, 510, -1020, 1022, - -1021, 1019, -1019, 511, -510, 510, -510, 1022, -1020, 1019, - -1020, 511, -511, 1018, -1022, 1020, -1019, 1021, -1019, 1020, - -511, 510, -1019, 1023, -1019, 1019, -510, 512, -508, 510, -511, - 512, -1019, 510, -509] - -Note that you don't need to include the leading ``32519`` here, as it denotes a final space at the end of -a transmission. - -RCSwitch Remote Codes -********************* - -Starting with version 1.8.0 ESPHome can also recognize a bunch of 433MHz RF codes directly using `RCSwitch's `__ -remote protocol. If you have RF code dumping enabled for the receiver, you will then see log outputs like this one: - -.. code:: - - Received RCSwitch: protocol=1 data='0100010101' - -Like before with raw codes, you can then use this code to create switches: - -.. code-block:: yaml - - switch: - - platform: remote_transmitter - name: "Living Room Lights On" - rc_switch_raw: - code: '0100010101' - protocol: 1 - -Alternatively, you can use the information on `this page `__ -to manually find the RCSwitch codes without having to first find them using the remote receiver. For example, this would -be the ESPHome equivalent of the first Type-A switch on that site: - -.. code-block:: yaml - - switch: - - platform: remote_transmitter - name: "Living Room Lights On" - rc_switch_type_a: - group: '1101' - device: '0100' - state: True - -.. _remote_transmitter-on_off_template: - -On/Off template ---------------- - -Each switch of the ``remote_transmitter`` platform only sends a pre-defined remote code when switched on. -For example the RCSwitch example above always **sends the turn on** RF code to the wall plug. In some cases -you might want to have switches that can do both things, i.e. turn a light on when switched on and turn a light off -when switched off. To do this, use the :doc:`/components/switch/template` like this: - -.. code-block:: yaml - - switch: - - platform: remote_transmitter - id: living_room_lights_on - rc_switch_type_a: - group: '1101' - device: '0100' - state: True - - platform: remote_transmitter - id: living_room_lights_off - rc_switch_type_a: - group: '1101' - device: '0100' - state: False - - platform: template - name: Living Room Lights - optimistic: True - assumed_state: True - turn_on_action: - - switch.turn_on: living_room_lights_on - turn_off_action: - - switch.turn_on: living_room_lights_off - - -.. _rc_switch-protocol: - -RCSwitch Protocol ------------------ - -RCSwitch transmitters/receivers all have a ``protocol:`` option that can be used to tell ESPHome what timings to use -for the transmission. This is necessary as many remotes use different timings to encode a logic zero or one. - -RCSwitch has 7 built-in protocols that cover most use cases. You can however also choose to use custom parameters -for the protocol like so - -.. code-block:: yaml - - # Use one of RCSwitch's pre-defined protocols (1-7) - protocol: 1 - - # Use a custom protocol: - protocol: - pulse_length: 175 - sync: [1, 31] - zero: [1, 3] - one: [3, 1] - inverted: False - -Configuration options for the custom variant: - -- **pulse_length** (**Required**, int): The length of each pulse in microseconds. -- **sync** (*Optional*): The number of on and off pulses for a sync bit. Defaults to 1 pulse on and 31 pulses off. -- **zero** (*Optional*): The number of on and off pulses to encode a logic zero. Defaults to 1 pulse on and 3 pulses off. -- **one** (*Optional*): The number of on and off pulses to encode a logic one. Defaults to 3 pulses on and 1 pulse off. -- **inverted** (*Optional*, boolean): Whether to treat this protocol as inverted, i.e. encode all on pulses by logic LOWs - and vice versa. - - -See Also --------- - -- :doc:`index` -- :doc:`/components/binary_sensor/remote_receiver` -- `RCSwitch `__ by `Suat Γ–zgΓΌr `__ -- `IRRemoteESP8266 `__ by `Mark Szabo-Simon `__ -- :apiref:`remote_transmitter/remote_transmitter.h` -- :ghedit:`Edit` diff --git a/guides/contributing.rst b/guides/contributing.rst index e3dc9404c..9018d0ab9 100644 --- a/guides/contributing.rst +++ b/guides/contributing.rst @@ -78,7 +78,7 @@ RST primer: .. _my-reference-label: Section to cross-reference - ^^^^^^^^^^^^^^^^^^^^^^^^^^ + -------------------------- See :ref:`my-reference-label`, also see :doc:`/components/switch/gpio`. :doc:`Using custom text `. @@ -259,6 +259,8 @@ Some notes about the docs: esphomedocs repository. New features should be added against the ``next`` branch. - Always create new branches in your fork for each pull request. +.. _setup_dev_env: + Setting Up Development Environment ---------------------------------- @@ -342,6 +344,211 @@ a "rebase". More info `here `, you will have a folder structure +like this: + +.. code-block:: text + + esphome + β”œβ”€β”€ __main__.py + β”œβ”€β”€ automation.py + β”œβ”€β”€ codegen.py + β”œβ”€β”€ config_validation.py + β”œβ”€β”€ components + β”‚Β Β  β”œβ”€β”€ __init__.py + β”‚Β Β  β”œβ”€β”€ dht12 + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ __init__.py + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ dht12.cpp + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ dht12.h + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ sensor.py + β”‚Β Β  β”œβ”€β”€ restart + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ __init__.py + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ restart_switch.cpp + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ restart_switch.h + β”‚Β Β  β”‚Β Β  β”œβ”€β”€ switch.py + β”‚Β  ... + +As you can see, all components are in the "components" folder. Each component is in its own +subfolder which contains the python code (.py) and the C++ code (.h and .cpp). + +Suppose the user types in the following: + +.. code-block:: yaml + + hello1: + + sensor: + - platform: hello2 + +In both cases, ESPHome will automatically look for corresponding entries in the "components" +folder and find the directory with the given name. For example the first entry will make ESPHome +look at the ``esphome/components/hello1/__init__.py`` file and the second entry will result in +``esphome/components/hello2/sensor.py``. + +Let's leave what's written in those files for (2.), but for now you should also know that +whenever a component is loaded, all the C++ source files in the folder of the component +are automatically copied into the generated platformio project. So you just need to add the C++ +source files in the folder and the ESPHome core will copy them with no additional code required +by the integration developer. + +.. note:: + + Additionally, ESPHome has a ``custom_components`` mechanism like + `Home Assistant does `__. + So for testing you can also create a new ``custom_components`` folder inside of your ESPHome + config folder and create new integrations in there. + +2. Config Validation +******************** + +The first thing ESPHome does is read and validate the user config. For this ESPHome has a powerful +"config validation" mechanism. Each component defines a config schema that is validated against +the user config. + +To do this, all ESPHome python modules that can be configured by the user have a special field +called ``CONFIG_SCHEMA``. An example of such a schema is shown below: + +.. code-block:: python + + import esphome.config_validation as cv + + CONF_MY_REQUIRED_KEY = 'my_required_key' + CONF_MY_OPTIONAL_KEY = 'my_optional_key' + + CONFIG_SCHEMA = cv.Schema({ + cv.Required(CONF_MY_REQUIRED_KEY): cv.string, + cv.Optional(CONF_MY_OPTIONAL_KEY, default=10): cv.int_, + }).extend(cv.COMPONENT_SCHEMA) + +This variable is automatically loaded by the ESPHome core and validated against. +The underlying system ESPHome uses for this is `voluptuous `__. +Going into how to validate is out of scope for this guide, but the best way to learn is to look +at examples of how similar integrations validate user input. + +A few point on validation: + +- ESPHome ts a lot of effort in **strict validation** - If possible, all validation methods should be as strict + as possible and detect wrong user input at the validation stage (and not later). +- All default values should be defined in the schema (and not in C++ codebase or other code parts). +- Config keys should be descriptive - If the meaning of a key is not immediately obvious you should + always prefer long_but_descriptive_keys. + +3. Code Generation +****************** + +After the user input has been successfully validated, the last step of the python codebase +is called: Code generation. + +As you may know, ESPHome converts the user's configuration into C++ code (you can see the generated +code under ``/src/main.cpp``). Each integration must define its own ``to_code`` method +that converts the user input to C++ code. + +This method is also automatically loaded and invoked by the ESPHome core. An example of +such a method can be seen below: + +.. code-block:: python + + import esphome.codegen as cg + + def to_code(config): + var = cg.new_Pvariable(config[CONF_ID]) + yield cg.register_component(var) + + cg.add(var.set_my_required_key(config[CONF_MY_REQUIRED_KEY])) + +Again, going into all the details of ESPHome code generation would be out-of-scope. However, +ESPHome's code generation is 99% syntactic sugar - and again it's probably best to study other +integrations and just copy what they do. + +There's one important concept for the ``to_code`` method: coroutines with ``yield``. +First the problem that leads to coroutines: In ESPHome, integrations can declare (via ``cg.Pvariable``) and access variables +(``cg.get_variable()``) - but sometimes when one part of the code base requests a variable +it has not been declared yet because the code for the component creating the variable has not run yet. + +To allow for ID references, ESPHome uses so-called ``coroutines``. When you see a ``yield`` statement +in a ``to_code`` method, ESPHome will call the provided method - and if that method needs to wait +for a variable to be declared first, ``yield`` will wait until that variable has been declared. +After that, ``yield`` returns and the method will execute on the next line. + +Next, there's a special method - ``cg.add`` - that you will often use. ``cg.add()`` does a very simple +thing: Any C++ declared in the paranetheses of ``cg.add()`` will be added to the generated code. +If you do not call "add" a piece of code explicitly, it will not be added to the main.cpp file! + +4. Runtime +---------- + +Okay, the python part of the codebase is now complete - now let's talk about the C++ part of +creating a new integration. + +The two major parts of any integration roughly are: + + - Setup Phase + - Run Phase + +When you create a new integration, your new component will inherit from :apiclass:`Component`. +That class has a special ``setup()`` method that will be called once to set up the component - +at the time the ``setup()`` method is called, all the setters generated by the python codebase +have already run and the all fields are set for your class. + +The ``setup()`` method should set up the communication interface for the component and check +if communication works (if not, it should call ``mark_failed()``). + +Again, look at examples of other integrations to learn more. + +The next thing that will be called with your component is ``loop()`` (or ``update()`` for a +:apiclass:`PollingComponent`). In these methods you should retrieve the latest data from the +component and publish them with the provided methods. One thing to note in these methods +is that anything in ``loop()`` or ``setup()`` **should not block**. Specifically methods like +``delay(10)`` should be avoided and delays above ~10ms are not permitted. The reason for this +is that ESPHome uses a central single-threaded loop for all components - if your component +blocks the whole loop will be slowed down. + +Finally, your component should have a ``dump_config`` method that prints the user configuration. + +5. Extras +********* + +.. note:: + + This serves as documentation for some of ESPHome's internals and is not necessarily part of the + development guide. + +All python modules have some magic symbols that will automatically be loaded by the ESPHome +loader. These are: + +- ``CONFIG_SCHEMA``: The configuration schema to validate the user config against. +- ``to_code``: The function that will be called with the validated configuration and should + create the necessary C++ source code. +- ``DEPENDENCIES``: Mark the component to depend on other components. If the user hasn't explicitly + added these components in their configuration, a validation error will be generated. +- ``AUTO_LOAD``: Automatically load an integration if the user hasn't added it manually. +- ``MULTI_CONF``: Mark this component to accept an array of configurations. +- ``CONFLICTS_WITH``: Mark a list of components as conflicting with this integration. If the user + has one of them in the config, a validation error will be generated. + +- ``ESP_PLATFORMS``: Provide a whitelist of ESP types this integration works with. + + Codebase Standards ------------------ @@ -363,55 +570,27 @@ Standard for the esphome-core codebase: - New components should dump their configuration using ``ESP_LOGCONFIG`` at startup in ``dump_config()`` +- ESPHome uses a unified formatting tool for all source files (but this tool can be difficult to install). + When creating a new PR in GitHub, see the travis-ci output to see what formatting needs to be changed + and what potential problems are detected. + - The number of external libraries should be kept to a minimum. If the component you're developing has a simple communication interface, please consider implementing the library natively in ESPHome. + + - This depends on the communication interface of course - if the library is directly working + with pins or doesn't do any I/O itself, it's ok. However if it's something like i2c, then ESPHome's + own communication abstractions should be used. Especially if the library accesses a global variable/state + like ``Wire`` there's a problem because then the component may not modular (i.e. not possible + to create two instances of a component on one ESP) + +- Integrations **must** use the provided abstractions like ``Sensor``, ``Switch`` etc. + Integration should specifically **not** directly access other components like for example + publish to MQTT topics. + - Implementations for new devices should contain reference links for the datasheet and other sample implementations. - Please test your changes :) -Contributing to ESPHome ------------------------ - -.. figure:: /images/logo-text.svg - :align: center - :width: 60.0% - -ESPHome primarily does two things: It validates the configuration and creates C++ code. - -The configuration validation should always be very strict with validating user input - it's always -better to fail quickly if a configuration isn't right than to have the user find out the issue after -a few hours of debugging. - -Preferably, the configuration validation messages should explain the exact validation issue -and try to suggest a possible fix. - -The C++ code generation engine is 99% syntactic sugar. -Have a look around other components and you will hopefully quickly get the gist of how to interact with -the code generation engine. - -All python modules have some magic symbols that will automatically be loaded by the ESPHome -loader. These are: - -- ``CONFIG_SCHEMA``: The configuration schema to validate the user config against. -- ``to_code``: The function that will be called with the validated configuration and should - create the necessary C++ source code. -- ``DEPENDENCIES``: Mark the component to depend on other components. If the user hasn't explicitly - added these components in their configuration, a validation error will be generated. -- ``AUTO_LOAD``: Automatically load an integration if the user hasn't added it manually. -- ``MULTI_CONF``: Mark this component to accept an array of configurations. -- ``CONFLICTS_WITH``: Mark a list of components as conflicting with this integration. If the user - has one of them in the config, a validation error will be generated. - -- ``ESP_PLATFORMS``: Provide a whitelist of ESP types this integration works with. - -TODO Phases: - - - Component loading (explain paths, directory structure) - - Validation (explain how to validate properly) - - Codegen (explain how code can be generated) - - Runtime setup phase - - Runtime loop/update phase - ESPHome via Gitpod ****************** diff --git a/index.rst b/index.rst index a691bd916..f66192dd7 100644 --- a/index.rst +++ b/index.rst @@ -152,7 +152,6 @@ Binary Sensor Components MPR121 Capacitive Touch Sensor, components/binary_sensor/mpr121, mpr121.jpg Nextion Touch, components/binary_sensor/nextion, nextion.jpg Template Binary Sensor, components/binary_sensor/template, description.svg - Remote Receiver, components/binary_sensor/remote_receiver, remote.svg PN532, components/binary_sensor/pn532, pn532.jpg RDM6300, components/binary_sensor/rdm6300, rdm6300.jpg TTP229, components/binary_sensor/ttp229, ttp229.jpg @@ -200,7 +199,6 @@ Switch Components Switch Core, components/switch/index, folder-open.svg GPIO Switch, components/switch/gpio, pin.svg - Remote Transmitter, components/switch/remote_transmitter, remote.svg Restart Switch, components/switch/restart, restart.svg Shutdown Switch, components/switch/shutdown, power_settings.svg Generic Output Switch, components/switch/output, upload.svg @@ -265,19 +263,25 @@ Misc Components .. imgtable:: - Debug Component, components/debug, bug-report.svg - PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg - MCP23017 I/O Expander, components/mcp23017, mcp23017.svg + Remote Receiver, components/remote_receiver, remote.svg + Remote Transmitter, components/remote_transmitter, remote.svg + Status LED, components/status_led, led-on.svg + + Time, components/time, clock-outline.svg + Sun, components/sun, weather-sunny.svg + GPS, components/gps, crosshairs-gps.svg + ESP32 BLE Tracker, components/esp32_ble_tracker, bluetooth.svg ESP32 BLE Beacon, components/esp32_ble_beacon, bluetooth.svg - Status LED, components/status_led, led-on.svg - Time, components/time, clock-outline.svg + ESP32 Ethernet, components/ethernet, ethernet.svg + + ESP32 Camera, components/esp32_camera, camera.svg Stepper, components/stepper/index, stepper.svg Servo, components/servo, servo.svg - Sun, components/sun, weather-sunny.svg - ESP32 Ethernet, components/ethernet, ethernet.svg - ESP32 Camera, components/esp32_camera, camera.svg - GPS, components/gps, crosshairs-gps.svg + + PCF8574 I/O Expander, components/pcf8574, pcf8574.jpg + MCP23017 I/O Expander, components/mcp23017, mcp23017.svg + Debug Component, components/debug, bug-report.svg Additional Custom Components ----------------------------