Table Of Content¶
Plugin rfxcom¶
Purpose¶
The rfxcom plugin handle the following Rfxcom hardware devices:
RFXtrx433 USB 433.92MHz Transceiver
RFXLAN Transceiver 433.92 MHz with xPL interface
You will get more informations on these devices on the official RFXCOM website
Dependencies¶
There is no dependency.
Install the RFXCOM usb device¶
Create an udev rule¶
You may create a udev rule for this device. You can find sample udev rules in the udev/ folder of this plugin.
You just need to copy the choosen sample file in the folder /etc/udev/rules.d/ and unplug/plug the device.
Install the RFXCOM xPL LAN device¶
Set up your RFXCOM lan with the xPL firmware (check the RFXCOM LAN module documentation). Plug your RFXCOM lan on the same network as your Domogik server.
Plugin configuration¶
Here is the global configuration:
Key | Type | Description |
---|---|---|
device | string | For the usb model, the path to the RFXCOM serial device. Example : /dev/rfxcom |
Create the devices¶
If your device is already listed in the products list, select it. Some fields will be automatically prefilled.
How to get a device address ?¶
All the devices detected by the plugin are listed in Domogik administration. To see them, make sure that the plugin is started, wait a few minutes to let the plugin see all sensors, activate manually the open/close sensors, switch on or off the lights, ... Then, you can look for detected devices in the Domogik devices part.
How to set a device to an address ?¶
Depending of the device (brand, model), there are various way to set up the hardware device address. The device documentation may help you to find how to do.
Here are the steps to set an address to a device, for example a Switch plug :
- create the related device in Domogik and set it some address, for example : address = 0x0038abfc, unit = 11.
- put the hardware device in learning mode (thanks to the device documentation)
- in Domogik administration, on the device details, click on the “On” button
- the device light should blink to tell it is ok
Start the plugin¶
You can now start the plugin (start button) and use the created devices.
Set up your widgets on the user interface¶
You can now place the widgets of your devices features on the user interface.
Temperature and humidity devices¶
Overview¶
These devices are able to send the temperature and the humidity. There are many models of them. You can find the list of all the compliant models in the products list of the user interface.
Features¶
These devices have several features:
- temperature
- humidity
- battery level
- RSSI (signal strength)
Configuration¶
When you create such a device, you will have to set this parameter:
Key | Type | Description |
---|---|---|
address | string | The device address. Example: th9 0xFFFF |
You can find the value of address for your device in the list of the detected devices in Domogik administration.
Temperature devices¶
Overview¶
These devices are able to send the temperature. There are many models of them. You can find the list of all the compliant models in the products list of the user interface.
Configuration¶
When you create such a device, you will have to set this parameter:
Key | Type | Description |
---|---|---|
address | string | The device address. Example: temp1 0xFFFF |
You can find the value of address for your device in the list of the detected devices in Domogik administration.
Switch devices : AC, HomeEasy EU, ANSLUT¶
Overview¶
These devices are able to switch on and off some appliances. There are many models in various brands.
These devices can have several addresses set.
Configuration¶
When you create such a device, you will have to set the parameters for both the command and the sensor part. For a common usage, you will set the same values for the xPL command parameters and the xPL stat parameters.
xPL command parameters¶
Key | Type | Description |
---|---|---|
address | string | The device address (0x00000000 to 0x03ffffff). Example: 0x0038abfe |
unit | integer | The device unit (1..16). Example: 3 |
xPL stat parameters¶
Key | Type | Description |
---|---|---|
address | string | The device address (0x00000000 to 0x03ffffff). Example: 0x0038abfe |
unit | integer | The device unit (1..16). Example: 3 |
For both address and unit, you can use multiple values. This can be needed if you are controlling the light with several commands :
- a switch
- a remote control
- an open/close sensor
If you don’t set all the possible addreses, the device sensor status may not be updated on Domogik side!
Here is an example for the 0x0011223344 : 10 and 0x0044332211 : 8 :
- address = 0x0011223344|0x0044332211
- unit = 10|8
Configure the hardware device¶
You can set up the address and unit values for this kind of hardware devices. Here are the instructions for several models. Before doing this, you will have to create a Domogik device with the values you can freely choose for both address and unit parameters.
DI.O PDR-2300¶
Delete the learned addresses¶
Be careful, this will delete all the addresses learned by the hardware device!
Plug the module.
Call this command before the led stop blinking (there is currently no way to do this from Domogik administration):
dmg_send xpl-cmnd ac.basic "address=0x1,unit=1,command=group_off"
The plugged light should blink twice for acknowlegment.
Learn a new address¶
- Plug the module.
- Do this action before the led stop blinking : in Domogik administration, on your device details, for the command part, click on the On button of the switch command.
- The plugged light should blink twice for acknowlegment.
Chacon 54561, 54565, 54566, 54567, 54581, 54582, 54585, 54585¶
Delete the learned addresses¶
- Plug the module. Press the button until the led blinks (about 6 seconds).
- Press the button one more time.
- The plugged light should blink twice for acknowlegment.
Learn a new address¶
- Plug the module.
- Press the button.
- Do this action before the led stop blinking : in Domogik administration, on your device details, for the command part, click on the On button of the switch command.
- The plugged light should blink twice for acknowlegment.
Doors and windows open/close sensors : Chacon, ...¶
Overview¶
These devices are open sensors and are able to detect when a door or a window (or whatever else) is opened and closed.
Features¶
These devices acts as switch commands. If they are open they send an on event. If they are closed, they send an off event. They have the following features :
- Open/close sensor
- RSSI (signal strength)
Sadly there is no way to get the battery level information.
Configuration¶
When you create such a device, you will have to set these parameters:
Key | Type | Description |
---|---|---|
address | string | The device address (0x00000000 to 0x03ffffff). Example: 0x0038abfe |
unit | integer | The device unit (1..16). Example: 3 |
Smoke sensor devices¶
Overview¶
These devices will raise an alarm when some smoke is detected or when the test button is pressed.
Configuration¶
When you create such a device, you will have to set this parameter:
Key | Type | Description |
---|---|---|
device | string | The device address. Example: temp1 0xFFFFFF |
You can find the value of device for your device in the list of the detected devices in Domogik administration after having pushed the Test button on the smoke sensor.
Development informations¶
Developments are based on 2 documents:
- RFXtrx SDK.pdf: the SDF for the usb model. It describes all handled hardware and how to use them with the rfxcom device. This file can be ask to RFXCOM support.
- RFXCOM implementation xPL.pdf: the specification of the used xPL messages for the lan model. To be compliant, we used these messages also for the usb model. This file is available on the official website.
Timeout on sensors¶
type 50 - temperature sensors¶
The timeout is set to 10 minutes. Most of the sensors send data each minute, but it may happen that some data are lost from time to time, so we choose to set the timeout to 10 minutes to allow several errors.
type 52 - temperature and humidity sensors¶
The timeout is set to 10 minutes. Most of the sensors send data each minute, but it may happen that some data are lost from time to time, so we choose to set the timeout to 10 minutes to allow several errors.
How to disable processing on some messages during development ?¶
In the file lib/rfxcom.py, you can edit the following list :
RESTRICT_TO_TYPE = [11]
This will for example, restrict all messages processed to type 11 (and also system types) and will avoid too much spam in the logs due to other sensors.
Don’t forget to empty it after your upgrades!
Tests summary¶
Some automated tests are used to validate this plugin. They use some fake serial devices.
Here is a summary of the implemented tests and also of the features which have been tested with the RFXCOM device and some real devices.
Feature | Automated tests | Tests with real devices |
---|---|---|
type 11 - switch plug | yes | yes (fritz, Chacon, DIO) |
type 11 - open close sensor | yes | yes (fritz, Chacon open/close sensor) |
type 50 - temperature | yes | yes (fritz, Lacrosse) |
type 52 - temperature and humidity | yes | yes (fritz, Oregon device) |
Changelog¶
1.68.4¶
- New datatype : DT_Battery. It is used for all Battery sensors now (previously : DT_Scaling).
1.68.3¶
- Add support for KD-101 smoke sensors (Chacon, ...). No battery support :(
- Add ‘nbz-rfxcomrx’ as compliant xPL client (this is the xpl-perl library)
- Doc upgrade for open close sensors
1.68.2¶
- New feature : lighting 2 (type 11) : AC, HomeEasy EU, ANSLUT. AC is the protocol used by different brands with units having a learning mode button: KlikAanKlikUit, NEXA, CHACON, HomeEasy UK.
- Switches
- Open/close windows and doors sensors
- Upgrade devices detection to be Domogik 0.4.1 compliant.
1.68.1¶
- New feature : temperature sensors (type 50)
1.68.0¶
- Plugin reboot for Domogik 0.4
- The second number of the plugin release will now be the compliant firmware
- Only one feature in the plugin currently : temperature and hygro sensors (type 52)
0.1¶
- Plugin creation