mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-05-04 18:18:58 +00:00
1aca7b08cf
* e.g. to e.g., and proper case for Home Assistant * Instructions how to -> Instructions on how to
140 lines
6.7 KiB
Markdown
140 lines
6.7 KiB
Markdown
---
|
|
layout: page
|
|
title: "RFXtrx Binary Sensor"
|
|
description: "Instructions on how to integrate RFXtrx binary sensors into Home Assistant."
|
|
date: 2017-03-26 12:45
|
|
sidebar: true
|
|
comments: false
|
|
sharing: true
|
|
footer: true
|
|
logo: rfxtrx.png
|
|
ha_category: Binary Sensor
|
|
---
|
|
|
|
The `rfxtrx` platform support binary sensors that communicate in the frequency range of 433.92 MHz. The rfxtrx binary sensor component provides support for them.
|
|
|
|
Many cheap sensors available on the web today are based on a particular RF chip called *PT-2262*. Depending on the running firmware on the RFXcom box, some of them may be recognized under the X10 protocol but most of them are recognized under the *Lighting4* protocol. The rfxtrx binary sensor component provides some special options for them, while other rfxtrx protocols should work too.
|
|
|
|
# Setting up your devices
|
|
Once you have set up your [rfxtrx hub](/components/rfxtrx/), the easiest way to find your binary sensors is to add this to your `configuration.yaml`:
|
|
|
|
```yaml
|
|
# Example configuration.yaml entry
|
|
binary_sensor:
|
|
platform: rfxtrx
|
|
automatic_add: True
|
|
```
|
|
|
|
Open your local home-assistant web UI and go to the "states" page. Then make sure to trigger your sensor. You should see a new entity appear in the *Current entities* list, starting with "binary_sensor." and some hexadecimal digits. Those hexadecimal digits are your device id.
|
|
|
|
For example: "binary_sensor.0913000022670e013b70". Here your device id is `0913000022670e013b70`. Then you should update your configuration to:
|
|
|
|
```yaml
|
|
# Example configuration.yaml entry
|
|
binary_sensor:
|
|
platform: rfxtrx
|
|
devices:
|
|
0913000022670e013b70:
|
|
name: device_name
|
|
```
|
|
|
|
Do not forget to tweak the configuration variables:
|
|
|
|
- **automatic_add** (*Optional*): To enable the automatic addition of new binary sensors.
|
|
- **device_class** (*Optional*): The [type or class of the sensor](/components/binary_sensor/) to set the icon in the frontend.
|
|
- **off_delay** (*Optional*): For sensors that only sends 'On' state updates, this variable sets a delay after which the sensor state will be updated back to 'Off'.
|
|
|
|
<p class='note warning'>
|
|
This component and the [rfxtrx switch](/components/switch/rfxtrx/) can steal each other's devices when setting the `automatic_add` configuration parameter to `true`. Set `automatic_add` only when you have some devices to add to your installation, otherwise leave it to `False`.
|
|
</p>
|
|
|
|
Binary sensors have only two states - "on" and "off". Many door or window opening sensors will send a signal each time the door/window is open or closed. However, depending on their hardware or on their purpose, some sensors are only able to signal their "on" state:
|
|
|
|
- Most motion sensors send a signal each time they detect motion. They stay "on" for a few seconds and go back to sleep, ready to signal other motion events. Usually, they do not send a signal when they go back to sleep.
|
|
- Some doorbells may also only send "on" signals when their toggle switch is pressed, but no "off" signal when the switch is released.
|
|
|
|
For those devices, use the *off_delay* parameter. It defines a delay after which a device will go back to an "Off" state. That "Off" state will be fired internally by Home Assistant, just as if the device fired it by itself. If a motion sensor can only send signals once every 5 seconds, sets the *off_delay* parameter to *seconds: 5*.
|
|
|
|
|
|
Example configuration:
|
|
|
|
```yaml
|
|
# Example configuration.yaml entry
|
|
binary_sensor:
|
|
platform: rfxtrx
|
|
automatic_add: True
|
|
devices:
|
|
091300006ca2c6001080:
|
|
name: motion_hall
|
|
device_class: motion
|
|
off_delay:
|
|
seconds: 5
|
|
```
|
|
|
|
## Options for PT-2262 devices under the Lighting4 protocol
|
|
|
|
When a data packet is transmitted by a PT-2262 device using the Lighting4 protocol, there is no way to automatically extract the device identifier and the command from the packet. Each device has its own id/command length combination and the fields lengths are not included in the data. One device that sends 2 different commands will be seen as 2 devices on Home Assistant. For such cases, the following options are available in order to circumvent the problem:
|
|
|
|
- **data_bits** (*Optional*): Defines how many bits are used for commands inside the data packets sent by the device.
|
|
- **command_on** (*Optional*): Defines the data bits value that is sent by the device upon an 'On' command.
|
|
- **command_off** (*Optional*): Defines the data bits value that is sent by the device upon an 'Off' command.
|
|
|
|
Let's try to add a new PT-2262 sensor using the "automatic_add" option and have a look at Home Assistant system log.
|
|
|
|
Have your sensor trigger the "On" state for the first time. Some messages will appear:
|
|
|
|
```
|
|
INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 0913000022670e013970 (Device_id: 22670e Class: LightingDevice Sub: 0)
|
|
```
|
|
|
|
Here the sensor has the id *22670e*.
|
|
|
|
Now have your sensor trigger the "Off" state and look for the following message in the Home Assistant log. You should see that your device has been detected as a *new* device when triggering its "Off" state:
|
|
|
|
```
|
|
INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 09130000226707013d70 (Device_id: 226707 Class: LightingDevice Sub: 0)
|
|
```
|
|
|
|
Here the device id is *226707*, which is almost similar to the *22670e* we had on the "On" event a few seconds ago.
|
|
|
|
From those two values, you can guess that the actual id of your device is *22670*, and that *e* and *7* are commands for "On" and "Off" states respectively. As one hexadecimal digit uses 4 bits, we can conclude that the device is using 4 data bits.
|
|
|
|
So here is the actual configuration section for the binary sensor:
|
|
|
|
```yaml
|
|
platform: rfxtrx
|
|
automatic_add: True
|
|
devices:
|
|
0913000022670e013b70:
|
|
name: window_room2
|
|
device_class: opening
|
|
data_bits: 4
|
|
command_on: 0xe
|
|
command_off: 0x7
|
|
```
|
|
|
|
The *automatic_add* option makes the rfxtrx binary sensor component calculate and display the configuration options for you in the Home Assistant logs:
|
|
|
|
```
|
|
INFO (Thread-6) [homeassistant.components.rfxtrx] rfxtrx: found possible device 226707 for 22670e with the following configuration:
|
|
data_bits=4
|
|
command_on=0xe
|
|
command_off=0x7
|
|
INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Found possible matching deviceid 22670e.
|
|
```
|
|
|
|
This automatic guess should work most of the time but there is no guarantee on that. You should activate it only when you want
|
|
to configure your new devices and leave it off otherwise.
|
|
|
|
## Known working devices
|
|
|
|
The following devices are known to work with the rfxtrx binary sensor component. There are too many other to list.
|
|
|
|
- Motion detectors:
|
|
- Kerui P817 and P829.
|
|
- Chuango PIR-700.
|
|
|
|
- Door / window sensors:
|
|
- Kerui D026 door / window sensor: can trigger on "open" and "close". Has a tamper switch.
|
|
- Nexa LMST-606.
|