Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update rf_bridge.rst #4541

Open
wants to merge 8 commits into
base: current
Choose a base branch
from
Open

Update rf_bridge.rst #4541

Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
16af21c
Update rf_bridge.rst
zd3sf Dec 28, 2024
85d5ecd
Update rf_bridge.rst
zd3sf Dec 28, 2024
dfb2dd9
Update rf_bridge.rst
zd3sf Dec 28, 2024
645683c
Update rf_bridge.rst
zd3sf Dec 28, 2024
c88557b
Merge branch 'current' into patch-1
zd3sf Dec 29, 2024
07bf647
Merge branch 'current' into patch-1
zd3sf Jan 5, 2025
44e60e4
Update rf_bridge.rst
zd3sf Jan 5, 2025
f5eaa06
Merge branch 'current' into patch-1
zd3sf Jan 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
229 changes: 171 additions & 58 deletions components/rf_bridge.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,13 @@ RF Bridge Component
:image: rf_bridge.jpg
:keywords: RF Bridge

The ``RF Bridge`` Component provides the ability to send and receive 433MHz remote codes using the
embedded EFM8BB1 microcontroller. This component implements the communication protocol
that the original ``efm8bb1`` firmware implements. The device is connected via the
The ``RF Bridge`` Component provides the ability to send and receive 433MHz signals (like RF remotes/key fobs) using radio microcontrollers founds on RF bridge devices ( eg. Sonoff RF bridge).

* The black Sonoff RF Bridge (R1, R2 V1.0) has an ESP8266 (for WIFI/ESPHome) and an embedded EFM8BB1 microcontroller (433 MHz).
* The white Sonoff RF Bridge (R2 V2.0) has ESP8266 and an embedded OB38S003 microcontroller (433 MHz).

This component implements the communication protocol between the ESP8266 and the firmware of ``EFM8BB1`` or ``OB38S003``.
The radio microcontroller is connected to the ESP8266 via the
:doc:`UART bus </components/uart>`. The uart bus must be configured at the same speed of the module
which is 19200bps.

Expand All @@ -19,17 +23,21 @@ which is 19200bps.

.. figure:: images/rf_bridge-full.jpg
:align: center
:width: 60.0%
:width: 50.0%

Sonoff RF Bridge 433, version R1 or R2 V1.0
Sonoff RF Bridge 433 (version R1 or R2 V1.0)

.. code-block:: yaml

# Example configuration entry
uart:
id: uart_hub
baud_rate: 19200
tx_pin: 1
rx_pin: 3

rf_bridge:
id: kitchen_RF_bridge
Comment on lines +34 to +40
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

Clarify UART configuration to avoid ID confusion.

Based on the PR discussion, the uart_id is causing confusion. The example should be simplified and include a note about ID usage.

 uart:
-  id: uart_hub
   baud_rate: 19200
   tx_pin: 1
   rx_pin: 3

 rf_bridge:
   id: kitchen_RF_bridge

Add this note after the configuration:

.. note::

    The UART component's ``id`` is optional and typically not needed for the RF bridge setup. 
    The ``id`` in the ``rf_bridge`` component is used for referencing the bridge in automations.

on_code_received:
- homeassistant.event:
event: esphome.rf_code_received
Expand All @@ -42,8 +50,8 @@ which is 19200bps.
Configuration variables:
------------------------

- **uart_id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID used for code generation.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the UART hub.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF bridge. Used for code generation and event tracking in home assistant.
- **on_code_received** (*Optional*, :ref:`Automation <automation>`): An action to be
performed when a code is received. See :ref:`rf_bridge-on_code_received`.

Expand All @@ -53,7 +61,7 @@ Configuration variables:
----------------------------

With this configuration option you can write complex automations whenever a code is
received. To use the code, use a :ref:`lambda <config-lambda>` template, the code
received by the bridge. To use the code, use a :ref:`lambda <config-lambda>` template. The code
and the corresponding protocol timings are available inside that lambda under the
variables named ``code``, ``sync``, ``high`` and ``low``.

Expand All @@ -74,7 +82,7 @@ variables named ``code``, ``sync``, ``high`` and ``low``.
``rf_bridge.send_code`` Action
------------------------------

Send an RF code using this action in automations.
Send a standard (0xA5) RF code using this action in automations.

.. code-block:: yaml

Expand All @@ -92,7 +100,7 @@ Configuration options:
- **low** (**Required**, int, :ref:`templatable <config-templatable>`): RF Low timing
- **high** (**Required**, int, :ref:`templatable <config-templatable>`): RF high timing
- **code** (**Required**, int, :ref:`templatable <config-templatable>`): RF code
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF Bridge if you have multiple components.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF Bridge if you have multiple bridges or multiple bridge components.

.. note::

Expand All @@ -103,27 +111,24 @@ Configuration options:
id(rf_bridge).send_code(0x700, 0x800, 0x1000, 0xABC123);


.. _rf_bridge-send_raw_action:
.. _rf_bridge-beep_action:

``rf_bridge.send_raw`` Action
-----------------------------
``rf_bridge.beep`` Action
--------------------------

Send a raw command to the onboard EFM8BB1 chip.
You can see a list of available commands and format in the `Portisch Wiki <https://github.com/Portisch/RF-Bridge-EFM8BB1/wiki/Commands>`__
Activate the internal buzzer to make a beep.

This can be used to send raw RF codes in automation's, mainly for protocols that are not supported.
If you have *Portisch* firmware installed, these raw codes can be obtained with the help of :ref:`rf_bridge-start_bucket_sniffing_action`

.. code-block:: yaml

on_...:
then:
- rf_bridge.send_raw:
raw: AAA5070008001000ABC12355
- rf_bridge.beep:
duration: 100

Configuration options:

- **raw** (**Required**, string, :ref:`templatable <config-templatable>`): RF raw string
- **duration** (**Required**, string, :ref:`templatable <config-templatable>`): beep duration in milliseconds.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF Bridge if you have multiple components.

.. note::
Expand All @@ -132,7 +137,7 @@ Configuration options:

.. code-block:: cpp

id(rf_bridge).send_raw("AAA5070008001000ABC12355");
id(rf_bridge).beep(100);


.. _rf_bridge-learn_action:
Expand Down Expand Up @@ -162,12 +167,51 @@ Configuration options:
id(rf_bridge).learn();



.. _rf_bridge-send_raw_action:

``rf_bridge.send_raw`` Action
-----------------------------

Send a raw command to the onboard radio chip. The OEM RF firmware is able to send raw only for standard signals (usually short), for other signals (B0 transmit), Portisch or Mightymos fimrware is needed.


This can be used to send raw RF codes in automations, mainly for protocols that are not supported.
If you have *Portisch* or *Mightymos* firmware installed, these raw codes can be obtained with the help of :ref:`rf_bridge-start_bucket_sniffing_action`

.. code-block:: yaml

on_...:
then:
- rf_bridge.send_raw: #in OEM firmware
raw: 'AAA5070008001000ABC12355'
- rf_bridge.send_raw: #in Portisch firmware
raw: 'AAB04C0408137702440111139B38192A192A1A1A19292A192A1A19292929292A1A1A1A1A192A19292A1A192A192A1A1A1A1A1A1A1A192A1A1A1A1A1A1A1A1A1A1A1A192A1929292A192A1A1929292955'

Configuration options:

- **raw** (**Required**, string, :ref:`templatable <config-templatable>`): RF raw string
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF Bridge if you have multiple components.

.. note::

This action can also be written in :ref:`lambdas <config-lambda>`:

.. code-block:: cpp

id(rf_bridge).send_raw("AAA5070008001000ABC12355");




Portisch firmware
-----------------

If you have flashed the secondary MCU with the `Portisch firmware <https://github.com/Portisch/RF-Bridge-EFM8BB1>`__,
ESPHome is able to receive the extra protocols that can be decoded as well as activate the other modes supported.

The radio microcontroller (MCU) can be flashed with an alternative firmware which allows for sniffining and transmitting
advanced protocols (e.g raw, 0xB0, 0xB1, 0xA8) in addition to the standard recieve/transmit (0xA4,0xA5).
If you have flashed the secondary MCU with the `Portisch firmware <https://github.com/Portisch/RF-Bridge-EFM8BB1>`__ or `Mightymos firmware <https://github.com/mightymos/RF-Bridge-OB38S003>`__,
ESPHome is able to receive the extra protocols that can be decoded as well as activate the other modes supported. The below Triggers/actions are only for Portisch firmware.
You can see a list of available commands and format in the `Portisch Wiki <https://github.com/Portisch/RF-Bridge-EFM8BB1/wiki/Commands>`__

.. _rf_bridge-on_advanced_code_received:

Expand Down Expand Up @@ -284,7 +328,7 @@ The raw data will be available in the log and can later be used with :ref:`rf_br
.. note::

A conversion from *B1* (received) raw format to *B0* (send) raw command format should be applied.
For this, you can use the tool `BitBucket Converter <https://bbconv.hrbl.pl/>`__
For this, you can use the tool `BitBucket Converter <https://bbconv.hrbl.pl/>`__ or `B1 Converter <https://jonajona.nl/convertB1.html/>`__

.. note::

Expand All @@ -309,34 +353,19 @@ Configuration options:

id(rf_bridge).start_bucket_sniffing();

.. _rf_bridge-restart radio controller:

.. _rf_bridge-beep_action:

``rf_bridge.beep`` Action
*************************

Activate the internal buzzer to make a beep.
Reset radio
***********

For *Portisch* or *Mightymos* firmware

.. code-block:: yaml

on_...:
then:
- rf_bridge.beep:
duration: 100

Configuration options:

- **duration** (**Required**, string, :ref:`templatable <config-templatable>`): beep duration in milliseconds.
- **id** (*Optional*, :ref:`config-id`): Manually specify the ID of the RF Bridge if you have multiple components.

.. note::

This action can also be written in :ref:`lambdas <config-lambda>`:

.. code-block:: cpp
- rf_bridge.send_raw: #in OEM firmware
raw: 'AAFE55'

id(rf_bridge).beep(100);

Getting started with Home Assistant
-----------------------------------
Expand All @@ -346,9 +375,18 @@ Home Assistant as events and will also setup a service so you can send codes wit

.. code-block:: yaml

uart:
tx_pin: 1
rx_pin: 3
baud_rate: 19200

logger:
baud_rate: 0

api:
actions:
- action: send_rf_code
actions: ## create actions in HA
#Send standard RF using intiger values
- action: send_rf_code
variables:
sync: int
low: int
Expand All @@ -360,20 +398,21 @@ Home Assistant as events and will also setup a service so you can send codes wit
low: !lambda 'return low;'
high: !lambda 'return high;'
code: !lambda 'return code;'

## send raw RF
- action: send_rf_code_raw
variables:
raw: string
then:
- rf_bridge.send_raw:
raw: !lambda 'return raw;'

- action: learn
then:
- rf_bridge.learn

uart:
tx_pin: 1
rx_pin: 3
baud_rate: 19200

logger:
baud_rate: 0

rf_bridge:
on_code_received:
on_code_received: #all fimrwares, can be reported as intiger, hex, or both, as desired.
then:
- homeassistant.event:
event: esphome.rf_code_received
Expand All @@ -383,10 +422,28 @@ Home Assistant as events and will also setup a service so you can send codes wit
high: !lambda 'return format_hex(data.high);'
code: !lambda 'return format_hex(data.code);'

- homeassistant.event:
event: esphome.rf_code_received
data:
sync: !lambda 'return int(data.sync);'
low: !lambda 'return int(data.low);'
high: !lambda 'return int(data.high);'
code: !lambda 'return int(data.code);'

on_advanced_code_received: ##only on Portisch or mightymos firmwares
then:
- homeassistant.event:
event: esphome.rf_advanced_code_received
data:
length: !lambda 'return format_hex(data.length);'
protocol: !lambda 'return format_hex(data.protocol);'
code: !lambda 'return data.code;'



Now your latest received code will be in an event.

To trigger the automation from Home Assistant you can invoke the service with this code:
To trigger the automation from Home Assistant you can invoke the service/action with this code:

.. code-block:: yaml

Expand All @@ -400,12 +457,68 @@ To trigger the automation from Home Assistant you can invoke the service with th
high: 0x1000
code: 0xABC123

Additional example configurations in ESPHome

.. code-block:: yaml

button:
- platform: template
name: Advanced sniffing start
on_press:
then:
- rf_bridge.start_advanced_sniffing

- platform: template
name: Advanced sniffing stop
on_press:
then:
- rf_bridge.stop_advanced_sniffing

- platform: template
name: Bucket sniffing start
on_press:
then:
- rf_bridge.start_bucket_sniffing

- platform: template
name: Beep
on_press:
then:
- rf_bridge.beep:
duration: 100

- platform: template
name: "restart radio"
id: mcu_reset
on_press:
then:
- rf_bridge.send_raw:
raw: 'AAFE55'

switch:
- platform: template
name: "example LED strip"
optimistic: true
turn_on_action:
- rf_bridge.send_code:
sync: 0x2F4A
low: 0x0166
high: 0x0483
code: 0x00C301
turn_off_action:
- rf_bridge.send_code:
sync: 0x2F1A
low: 0x0184
high: 0x048C
code: 0x00C303

See Also
--------

- :apiref:`rf_bridge/rf_bridge.h`
- :ref:`lambda_magic_rf_queues`
- `RF-Bridge-EFM8BB1 <https://github.com/Portisch/RF-Bridge-EFM8BB1>`__ by `Portisch <https://github.com/Portisch>`__
- `Mightymos firmware <https://github.com/mightymos/RF-Bridge-OB38S003>`__
- :doc:`/components/uart`
- :doc:`/components/remote_receiver`
- :doc:`/components/remote_transmitter`
Expand Down
Loading