|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: "RFXtrx Binary Sensor" |
| 4 | +description: "Instructions how to integrate RFXtrx binary sensors into Home Assistant." |
| 5 | +date: 2017-03-26 12:45 |
| 6 | +sidebar: true |
| 7 | +comments: false |
| 8 | +sharing: true |
| 9 | +footer: true |
| 10 | +logo: rfxtrx.png |
| 11 | +ha_category: Binary Sensor |
| 12 | +--- |
| 13 | + |
| 14 | +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. |
| 15 | + |
| 16 | +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. |
| 17 | + |
| 18 | +# Setting up your devices |
| 19 | +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`: |
| 20 | + |
| 21 | +```yaml |
| 22 | +# Example configuration.yaml entry |
| 23 | +binary_sensor: |
| 24 | + platform: rfxtrx |
| 25 | + automatic_add: True |
| 26 | +``` |
| 27 | +
|
| 28 | +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 entites* list, starting with "binary_sensor." and some hexadecimal digits. Those hexadecimal digits are your device id. |
| 29 | +
|
| 30 | +For example: "binary_sensor.0913000022670e013b70". Here your device id is `0913000022670e013b70`. Then you should update your configuration to: |
| 31 | + |
| 32 | +```yaml |
| 33 | +# Example configuration.yaml entry |
| 34 | +binary_sensor: |
| 35 | + platform: rfxtrx |
| 36 | + devices: |
| 37 | + 0913000022670e013b70: |
| 38 | + name: device_name |
| 39 | +``` |
| 40 | + |
| 41 | +Do not forget to tweak the configuration variables: |
| 42 | + |
| 43 | +- **automatic_add** (*Optional*): To enable the automatic addition of new binary sensors. |
| 44 | +- **device_class** (*Optional*): The [type or class of the sensor](/components/binary_sensor/) to set the icon in the frontend. |
| 45 | +- **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'. |
| 46 | + |
| 47 | + |
| 48 | +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: |
| 49 | + |
| 50 | +- 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. |
| 51 | +- Some doorbells may also only send "on" signals when their toggle switch is pressed, but no "off" signal when the switch is released. |
| 52 | + |
| 53 | +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*. |
| 54 | + |
| 55 | + |
| 56 | +Example configuration: |
| 57 | + |
| 58 | +```yaml |
| 59 | +# Example configuration.yaml entry |
| 60 | +binary_sensor: |
| 61 | + platform: rfxtrx |
| 62 | + automatic_add: True |
| 63 | + devices: |
| 64 | + 091300006ca2c6001080: |
| 65 | + name: motion_hall |
| 66 | + device_class: motion |
| 67 | + off_delay: |
| 68 | + seconds: 5 |
| 69 | +``` |
| 70 | + |
| 71 | +## Options for PT-2262 devices under the Lighting4 protocol |
| 72 | + |
| 73 | +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 sur cases, the following options are available in order to circumvent the problem: |
| 74 | + |
| 75 | +- **data_bits** (*Optional*): Defines how many bits are used for commands inside the data packets sent by the device. |
| 76 | +- **command_on** (*Optional*): Defines the data bits value that is sent by the device upon an 'On' command. |
| 77 | +- **command_off** (*Optional*): Defines the data bits value that is sent by the device upon an 'Off' command. |
| 78 | + |
| 79 | +Let's try to add a new PT-2262 sensor using the "automatic_add" option and have a look at Home Assistant system log. |
| 80 | + |
| 81 | +Have your sensor trigger the "On" state for the first time. Some messages will appear: |
| 82 | + |
| 83 | +``` |
| 84 | +INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 0913000022670e013970 (Device_id: 22670e Class: LightingDevice Sub: 0) |
| 85 | +``` |
| 86 | + |
| 87 | +Here the sensor has the id *22670e*. |
| 88 | + |
| 89 | +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: |
| 90 | + |
| 91 | +``` |
| 92 | +INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 09130000226707013d70 (Device_id: 226707 Class: LightingDevice Sub: 0) |
| 93 | +``` |
| 94 | + |
| 95 | +Here the device id is *226707*, which is almost similar to the *22670e* we had on the "On" event a few seconds ago. |
| 96 | + |
| 97 | +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. |
| 98 | + |
| 99 | +So here is the actual configuration section for the binary sensor: |
| 100 | + |
| 101 | +```yaml |
| 102 | +platform: rfxtrx |
| 103 | +automatic_add: True |
| 104 | +devices: |
| 105 | + 0913000022670e013b70: |
| 106 | + name: window_room2 |
| 107 | + device_class: opening |
| 108 | + data_bits: 4 |
| 109 | + command_on: 0xe |
| 110 | + command_off: 0x7 |
| 111 | +``` |
| 112 | + |
| 113 | +The *automatic_add* option makes the rfxtrx binary sensor component calculate and display the configuration options for you in the Home Assistant logs: |
| 114 | + |
| 115 | +``` |
| 116 | +INFO (Thread-6) [homeassistant.components.rfxtrx] rfxtrx: found possible device 226707 for 22670e with the following configuration: |
| 117 | +data_bits=4 |
| 118 | +command_on=0xe |
| 119 | +command_off=0x7 |
| 120 | +INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Found possible matching deviceid 22670e. |
| 121 | +``` |
| 122 | + |
| 123 | +This automatic guess should work most of the time but there is no guarantee on that. You should activate it only when you want |
| 124 | +to configure your new devices and leave it off otherwise. |
| 125 | + |
| 126 | +## Known working devices |
| 127 | + |
| 128 | +The following devices are known to work with the rfxtrx binary sensor component. There are too many other to list. |
| 129 | + |
| 130 | +- Motion detectors: |
| 131 | + - Kerui P817 and P829. |
| 132 | + - Chuango PIR-700. |
| 133 | + |
| 134 | +- Door / window sensors: |
| 135 | + - Kerui D026 door / window sensor: can trigger on "open" and "close". Has a temper switch. |
| 136 | + - Nexa LMST-606 Magnetic contact switch. |
0 commit comments