Download source PDF Page last generated on 22:11, 27 November 2015 Github 
Devices
Devices..........................................................................................................................................................1
Introduction...............................................................................................................................................1
Structure....................................................................................................................................................2
Device Types.............................................................................................................................................3
Multiple IDs...............................................................................................................................................4
Multiple Protocols Per Device...................................................................................................................4
Overriding Protocol Settings.....................................................................................................................5
Introduction
This page will only explain the device set-up basics with some protocols as an example. To see the full
list of supported protocols and their respective syntax read the protocol pages of this manual.
pilight can be ran with or without a fixed devices set-up. The advantage of a fixed device set-up is that
pilight can use them in events and for external clients such as the built-in webGUI. Status updates will
automatically be updated just like information from weather information.
The protocol names outputted by pilight-receive are not (always) the same as the protocols used in the
device setup. The reason for this, is that various brands use the same underlying protocol. The
arctech_switch protocol is used by at least five different brands. So there is the same underlying protocol
for each of these brands.
1. Check the brand of the device you want to define in the device set-up.
2. Check if your device is recognize in pilight-receive.
3. Check the protocol pages to see if your device is listed and what the device syntax is.
If your specific brand / device is not listed, but pilight-receive does show output, then contact us so we can
add the device to the specific protocol supported brand list.
Structure
1 "devices": {
2 "television": {
3 "protocol": [ "relay" ],
4 "id": [{
5 "gpio": 3
6 }],
7 "state": "off"
8 },
9 "bookShelfLight": {
10 "protocol": [ "kaku_switch" ],
11 "id": [{
12 "id": 123456,
13 "unit": 1
14 }],
15 "state": "off"
16 }
17 }
Each device you want to set-up in pilight has its own entry. In this example we have set-up two devices.
One GPIO connected Relay that turns the television on and off and KlikAanKlikUit controlled
bookShelfLight.
Whenever an action has been performed or received by pilight the registered device will update itself when
necessary. So, would you in this example, turn the bookShelfLight to on with a KlikAanKlikUit remote, pilight
will also record this, and change the status of the bookShelfLight to on. Of course, a receiver needs to be
connected for this to work. Each device has its own specific syntax but its basic properties remain the
same. That is:
1. name
2. protocol
3. id
To know the syntax of the specific protocol you want to use you can refer to the protocols description found
in the protocol section of this manual.
Device Types
pilight can work with various device types. Each device type has different functionality and requirements,
however, they sometimes use the same code characteristics. One example are the KlikAanKlikUit switches,
dimmers, doorbells, and screens. In pilight a KlikAanKlikUit code can show up like this:
As you can see, a single KlikAanKlikUit command was interpreted as three different devices. You need to
choose carefully which device actually sent the code to make sure how to define it in the device set-up. The
difference is that a dimmer will have a slider and an on/off button, a switch will just show an on/off button,
and a screen will have momentary up/down buttons. Defining a screen as a dimmer is possible but does
not give you the ability to control the dimmer as a dimmer from the different GUIs.
{
"origin": "sender",
"protocol": "arctech_switches",
"code": {
"id": 100,
"unit": 15,
"state": off
},
"repeat": 1,
}
{
"origin": "sender",
"protocol": "arctech_dimmers",
"code": {
"id": 100,
"unit": 15,
"state": off
},
"repeat": 1,
}
{
"origin": "sender",
"protocol": "arctech_screens",
"code": {
"id": 100,
"unit": 15,
"state": up
},
"repeat": 1,
}
Multiple IDs
Each protocol needs to have at least one id defined so pilight knows what device has been controlled.
However, it is possible that you have multiple KlikAanKlikUit remotes that control the same KlikAanKlikUit
switch. In that case, you can define multiple id's to your devices. In case of a KlikAanKlikUit switch:
1 "devices": {
2 "bookShelfLight": {
3 "protocol": [ "kaku_switch" ],
4 "id": [{
5 "id": 1234,
6 "unit": 0
7 },
8 {
9 "id": 2345,
10 "unit": 1
11 }],
12 "state": "off"
13 }
14 }
Whenever one of these id's have been received, pilight will update the device accordingly.
Multiple Protocols Per Device
pilight supports multiple protocols per device. The new KlikAanKlikUit switches are backwards compatible
with the old KlikAanKlikUit remotes. This means that pilight needs to check both protocols to know whether
a device state was changed. In case of a KlikAanKlikUit dimmer, pilight needs to check three protocols. To
add multiple protocols per device, the device must contain at least one ID for each protocol and all protocol
values should be present. An example:
1 "devices": {
2 "bookShelfLight": {
3 "protocol": [ "kaku_dimmer", "kaku_switch", "kaku_old" ],
4 "id": [{
5 "id": 123456,
6 "unit": 1
7 },
8 {
9 "id": 10,
10 "unit": 5
11 }],
12 "state": "off",
13 "dimlevel": 10
14 }
15 }
There are a few important steps when you use multiple protocols in a single device setup.
1. The kaku_dimmer and kaku_switch protocols both share the same id specifications, but the
kaku_old protocol can only have an id < 16 and a unit < 33. The id set for the kaku_switch and
kaku_dimmer is thereby not supported by the kaku_old protocol. Therefore an additional id must be
added to match the requirements by kaku_old.
2. Because we have a dimmer and switch protocol combined we must have a dimlevel and state value
present in the device.
3. The kaku_dimmer is the first protocol defined. This is important, because pilight will now interpret
this device as a dimmer instead of a switch. Would the kaku_dimmer protocol be defined as second
or third protocol, then the device would be interpreted as a switch.
Overriding Protocol Settings
Each protocol has some specific settings you can override in your device set-up. What these settings are,
can be found in the protocols section of this manual. These settings can change the internal functioning of
a protocol or the values a protocol can take. These settings are device specific.
For example, we do not want to have our dimmer to go to a full dimlevel, because then it is to bright. But we
also do not want it to go to its minimum dimlevel, because then it is to dim. In that case, you can override
the minimum and maximum values of the dimmer:
1 "devices": {
2 "bookShelfLight": {
3 "protocol": [ "kaku_dimmer" ],
4 "id": [{
5 "id": 1234,
6 "unit": 1
7 }],
8 "state": "on",
9 "dimlevel": 3,
10 "dimlevel-minimum": 3,
11 "dimlevel-maximum": 10
12 }
13 }
Of course, the maximum dimlevels can still be overridden by the KlikAanKlikUit remote, but pilight will make
sure it cannot control the dimmers below or above these dimlevels within pilight.
Top