mirror of
https://github.com/esphome/esphome-docs.git
synced 2025-04-05 18:35:52 +02:00
Remote + Dev docs update
This commit is contained in:
Otto Winter
parent
ef49ff813d
commit
52cd23c733
@ -3,4 +3,4 @@ python: "3.6"
|
||||
install: pip install -r requirements.txt
|
||||
script:
|
||||
- python3 travis.py
|
||||
- make html
|
||||
- make html-strict
|
||||
|
||||
5
Makefile
5
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:
|
||||
|
||||
@ -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 </components/binary_sensor/remote_receiver>` and
|
||||
:doc:`remote transmitter </components/switch/remote_transmitter>` components now allows you to use any 433MHz
|
||||
- The new :doc:`remote receiver </components/remote_receiver>` and
|
||||
:doc:`remote transmitter </components/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 <finding_remote_codes>`, 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 </components/i2c>` as it
|
||||
turns out it didn't actually do anything.
|
||||
|
||||
- The ``ir_transmitter`` component has been renamed to :doc:`remote_transmitter </components/switch/remote_transmitter>`
|
||||
- The ``ir_transmitter`` component has been renamed to :doc:`remote_transmitter </components/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 </components/sensor/pulse_counter>` has been removed, please
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 <remote-receiver-binary-sensor>` 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 <config-time>`): Filter any pulses that are shorter than this. Useful for removing
|
||||
glitches from noisy signals. Defaults to ``10us``.
|
||||
- **idle** (*Optional*, :ref:`time <config-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 <config-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 <https://github.com/xoseperez/espurna/wiki/Hardware-Itead-Sonoff-RF-Bridge---Direct-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 <https://github.com/sui77/rc-switch>`__ by `Suat Özgür <https://github.com/sui77>`__
|
||||
- `IRRemoteESP8266 <https://github.com/markszabo/IRremoteESP8266/>`__ by `Mark Szabo-Simon <https://github.com/markszabo>`__
|
||||
- :apiref:`remote/remote_receiver.h`
|
||||
- :ghedit:`Edit`
|
||||
|
Before Width: | Height: | Size: 3.2 KiB After Width: | Height: | Size: 3.2 KiB |
|
Before Width: | Height: | Size: 28 KiB After Width: | Height: | Size: 28 KiB |
@ -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 <config-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 <config-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 <config-templatable>`, percentage): The value to
|
||||
set the red channel to.
|
||||
- **green** (*Optional*, :ref:`templatable <config-templatable>`, percentage): The value to
|
||||
|
||||
209
components/remote_receiver.rst
Normal file
209
components/remote_receiver.rst
Normal file
@ -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 <remote-receiver-binary-sensor>`
|
||||
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 <config-time>`): Filter any pulses that are shorter than this. Useful for removing
|
||||
glitches from noisy signals. Defaults to ``10us``.
|
||||
- **idle** (*Optional*, :ref:`time <config-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 <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 <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 <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 <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 <automation>`): An automation to perform when a
|
||||
raw remote code has been decoded. A variable ``x`` of type ``std::vector<int>``
|
||||
is passed to the automation for use in lambdas.
|
||||
- **on_rc5** (*Optional*, :ref:`Automation <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 <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 <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 <config-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 <https://github.com/xoseperez/espurna/wiki/Hardware-Itead-Sonoff-RF-Bridge---Direct-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 <https://github.com/sui77/rc-switch>`__ by `Suat Özgür <https://github.com/sui77>`__
|
||||
- `IRRemoteESP8266 <https://github.com/markszabo/IRremoteESP8266/>`__ by `Mark Szabo-Simon <https://github.com/markszabo>`__
|
||||
- :apiref:`remote/remote_receiver.h`
|
||||
- :ghedit:`Edit`
|
||||
544
components/remote_transmitter.rst
Normal file
544
components/remote_transmitter.rst
Normal file
@ -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 <config-action>` 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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <config-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 <https://www.sparkfun.com/products/10266>`__).
|
||||
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 <https://learn.sparkfun.com/tutorials/ir-communication/all>`__) 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 <https://github.com/sui77/rc-switch>`__ by `Suat Özgür <https://github.com/sui77>`__
|
||||
- `IRRemoteESP8266 <https://github.com/markszabo/IRremoteESP8266/>`__ by `Mark Szabo-Simon <https://github.com/markszabo>`__
|
||||
- :apiref:`remote_transmitter/remote_transmitter.h`
|
||||
- :ghedit:`Edit`
|
||||
@ -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 <remote-transmitter-switch>` 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 <config-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 <config-switch>`.
|
||||
|
||||
.. note::
|
||||
|
||||
For the Sonoff RF Bridge you can use `this hack <https://github.com/xoseperez/espurna/wiki/Hardware-Itead-Sonoff-RF-Bridge---Direct-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 <https://github.com/sui77/rc-switch/wiki/HowTo_OperateLowCostOutlets#type-d-status>`__ ``'001010011001111101011011'``.
|
||||
- **protocol** (*Optional*, :ref:`RCSwitch protocol <rc_switch-protocol>`): The RCSwitch protocol to use. Defaults to ``1``.
|
||||
|
||||
- **rc_switch_type_a**: Send an RCSwitch `type A code <https://github.com/sui77/rc-switch/wiki/HowTo_OperateLowCostOutlets#type-a-10-pole-dip-switches>`__.
|
||||
|
||||
- **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 <rc_switch-protocol>`): The RCSwitch protocol to use. Defaults to ``1``.
|
||||
|
||||
- **rc_switch_type_b**: Send an RCSwitch
|
||||
`type B code <https://github.com/sui77/rc-switch/wiki/HowTo_OperateLowCostOutlets#type-b-two-rotarysliding-switches>`__.
|
||||
|
||||
- **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 <rc_switch-protocol>`): The RCSwitch protocol to use. Defaults to ``1``.
|
||||
|
||||
- **rc_switch_type_c**: Send an RCSwitch `type C code <https://github.com/sui77/rc-switch/wiki/HowTo_OperateLowCostOutlets#type-c-intertechno>`__.
|
||||
|
||||
- **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 <rc_switch-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 <rc_switch-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 </components/binary_sensor/remote_receiver>` 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 <https://github.com/sui77/rc-switch>`__
|
||||
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 <https://github.com/sui77/rc-switch/wiki/HowTo_OperateLowCostOutlets>`__
|
||||
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 <https://github.com/sui77/rc-switch>`__ by `Suat Özgür <https://github.com/sui77>`__
|
||||
- `IRRemoteESP8266 <https://github.com/markszabo/IRremoteESP8266/>`__ by `Mark Szabo-Simon <https://github.com/markszabo>`__
|
||||
- :apiref:`remote_transmitter/remote_transmitter.h`
|
||||
- :ghedit:`Edit`
|
||||
@ -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 </components/switch/gpio>`.
|
||||
@ -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 <https://developers.home-assistant.io/docs/en/develo
|
||||
git fetch upstream dev
|
||||
git rebase upstream/dev
|
||||
|
||||
Contributing to ESPHome
|
||||
-----------------------
|
||||
|
||||
.. figure:: /images/logo-text.svg
|
||||
:align: center
|
||||
:width: 60.0%
|
||||
|
||||
This is a guide to contributing to the ESPHome codebase. ESPHome uses two languages for its project:
|
||||
Python and C++.
|
||||
|
||||
The user configuration is read, validated and transformed into a custom firmware
|
||||
with the python side of the firmware.
|
||||
|
||||
The C++ codebase is what's actually running on the ESP and called the "runtime". This part of
|
||||
the codebase should first set up the communication interface to a sensor/component/etc and
|
||||
communicate with the ESPHome core via the defined interfaces (like Sensor, BinarySensor, Switch).
|
||||
|
||||
1. Directory Structure
|
||||
**********************
|
||||
|
||||
After you've :ref:`set up development environment <setup_dev_env>`, 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 <https://developers.home-assistant.io/docs/en/creating_component_loading.html>`__.
|
||||
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 <https://github.com/alecthomas/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 ``<NODE_NAME>/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
|
||||
******************
|
||||
|
||||
|
||||
26
index.rst
26
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
|
||||
----------------------------
|
||||
|
||||
Loading…
Reference in New Issue
Block a user