From 3d3b3eab289f943ecbcf47f4568e9093e09a54aa Mon Sep 17 00:00:00 2001 From: Yannick POLLART Date: Sun, 2 Jul 2017 02:23:45 +0200 Subject: [PATCH] rfxtrx binary sensor component documentation (#2336) * First draft of RFXtrx binary sensor doc page. * Updated rfxtrx binary sensor doc. * binary_sensors.rfxtrx: updated doc according to latest PR changes. * Updated rfxtrx binary sensor documentation * Update binary_sensor.rfxtrx.markdown Tried to clarify the data_bits description. * Updated device_class property. --- .../_components/binary_sensor.rfxtrx.markdown | 136 ++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 source/_components/binary_sensor.rfxtrx.markdown diff --git a/source/_components/binary_sensor.rfxtrx.markdown b/source/_components/binary_sensor.rfxtrx.markdown new file mode 100644 index 00000000000..d2c2df56c8d --- /dev/null +++ b/source/_components/binary_sensor.rfxtrx.markdown @@ -0,0 +1,136 @@ +--- +layout: page +title: "RFXtrx Binary Sensor" +description: "Instructions 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 entites* 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'. + + +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 sur 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 temper switch. + - Nexa LMST-606 Magnetic contact switch.