User Tools

  • (equal to forum credentials)

Site Tools


config

Configuration

Make sure the daemon is not running before editing the configuration

The config file allows users to create a predefined configuration for all their devices. This allows pilight to track the status of the devices and it facilitates the creation of dynamical GUIs.

The pilight configuration has to be put in an external file called config.json. It is located under /etc/pilight/config.json

For any questions regarding JSON, Wikipedia provides a brief introduction into JSON. In particular the section “Data types, Syntax and Examples” is helpful to understand where to use square and curly brackets, commas, double quotes and the colon.

Basic Syntax

The pilight configuration contains six basic levels:

  1. Devices
  2. Rules
  3. GUI
  4. Settings
  5. Hardware
  6. Registry

Devices

[...]
    "devices": {
        "television": {
            "protocol": [ "relay" ],
            "id": [{
                "gpio": 3
            }],
            "state": "off"
        },
        "bookShelfLight": {
            "protocol": [ "kaku_switch" ],
            "id": [{
                "id": 123456,
                "unit": 1
            }],
            "state": "off"
        }
    },
[...]

Each device you want to register in pilight has its own entry. In this example we have registered two devices. One GPIO connected Relay that turns the television on and off and bookShelfLight.

Whenever an action has been performed by pilight the registered device will update itself when necessary. Also, whenever a specific action has been received by pilight concerning one of the devices, pilight will update the device accordingly. 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 it's own specific syntax but its basic properties remain the same. That is:

  • name
  • protocol
  • id

To know what the syntax of the specific protocol you want to use you can refer to the protocols description.

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. When you run pilight-receive a KlikAanKlikUit code can show up like this:

{
    "origin": "receiver",
    "protocol": "arctech_switches",
    "code": {
        "id": 100,
        "unit": 15,
        "state": off
    },
    "repeat": 1
}
{
    "origin": "receiver",
    "protocol": "arctech_dimmers",
    "code": {
        "id": 100,
        "unit": 15,
        "state": off
    },
    "repeat": 1
}
{
    "origin": "receiver",
    "protocol": "arctech_screens",
    "code": {
        "id": 100,
        "unit": 15,
        "state": up
    },
    "repeat": 1
}

As you can see, a single KlikAanKlikUit code was interpreted as three different devices. You need to choose carefully from which device the code actually originated in order to properly define it in the device setup. The difference is that the GUI will have an on/off button and a slider option for the dimmer, for a switch the GUI will just show an on/off button, and for a screen the GUI will show momentary up/down buttons. Defining a screen as a dimmer just won't work as you might expect and as it seems logical.

Multiple ID's

Each protocol needs to have at least one id to be defined so pilight knows what device it is controlling. However, it is possible that you have multiple KlikAanKlikUit remotes controlling the same KlikAanKlikUit switch. If this is the case, you can define multiple ids to your devices. In case of a KlikAanKlikUit switch:

[...]
    "devices": {
        "bookShelfLight": {
            "protocol": ["kaku_switch"],
            "id": [{
                "id": 1234,
                "unit": 0
            },
            {
                "id": 2345,
                "unit": 1
            }],
            "state": "off"
        }
    }      
[...]

Whenever one of these ids has 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:

[...]
    "devices": {
        "bookShelfLight": {
            "protocol": [ "kaku_dimmer", "kaku_switch", "kaku_old" ],
            "id": [{
                "id": 123456,
                "unit": 1
            },
            {
                "id": 10,
                "unit": 5
            }],
            "state": "off",
            "dimlevel": 10
        }
    }
[...]

Please notice 3 important things:

  • 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 an unit < 33. The id set for the kaku_switch and kaku_dimmer is thereby not supported by the kaku_old protocol. Thereby an additional id must be set to match the requirements by kaku_old.
  • Because we have a dimmer and switch protocol combined we must have a dimlevel and state value present in the device.
  • 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.

Override Protocol Settings

Each protocol also has specific settings you can override in your device setup. What these settings are can be found in the protocols page on this wiki. These settings can change the internal functioning of a protocol, the values a protocol can take, or how the protocol should be translated into the GUI. These settings are device specific.

For example, we don't want to have our dimmer to go to a full dimlevel, because then it's too bright. But we also don't want it to go to its minimum dimlevel, because then it's too dim. In that case, you can override the min and max values of the dimmer:

{
    "devices": {
        "mainDimmer": {
                "protocol": ["kaku_dimmer"],
                "id": [{
                        "id": 1234,
                        "unit": 1
                }],
                "state": "on",
                "dimlevel": 3,
                "dimlevel-minimum": 3,
                "dimlevel-maximum": 10
        }
    }
}

Another example:

{
    "devices": {
        "OutsideTemp": {
            "protocol": [ "conrad_weather" ],
            "id": [{
                "id": 236,
                "channel": 1
            }],
            "humidity": 0,
            "temperature": 29.16,
            "battery": 0,
            "temperature-offset": -0.50
        }
    }
}

Of course, the maximum dimlevels can still be overriden by the KlikAanKlikUit remote, but pilight will make sure it cannot control the dimmers below or above these dimlevels within pilight.

Rules

Since pilight version 6, eventing has been introduced. To use events, you need to define rules inside the pilight configuration first.

The basic pilight rule structure for the configuration looks like this:

[...]
    "rules": {
        "rule_name": {
            "rule": "IF switch.state IS on THEN switch DEVICE switch.state TO off",
            "active": 1
        }
    },
[...]

As you can see, a rules object consists of various elements:

  • Each rule is placed in its own object with an unique identifier.
  • Each rule consists of the actual rule placed in the rule field.
  • Each rule consists of an active field that tells pilight if the rule is active or not.

You can of course define as many rules as you like. See the Eventing page for more information on how to write your own rules.

GUI

pilight has an extensive API that allows developers to create custom control GUIs. A pilight GUI is actually nothing more then presenting those devices a user wants to control easily. This means that a GUI doesn't have to show all devices added to the device setup and that not all GUIs have to show the same devices. You can create a more compact GUI for a small screen such as a mobile phone or a more extensive GUI for your computer screen.

Elements

Remember the device setup we created earlier:

[...]
    "devices": {
        "television": {
            "protocol": [ "relay" ],
            "id": [{
                "gpio": 3
            }],
            "state": "off"
        },
        "bookShelfLight": {
            "protocol": [ "kaku_switch" ],
            "id": [{
                "id": 123456,
                "unit": 1
            }],
            "state": "off"
        }
    },
[...]

To present these devices to our GUI, we have to add them to the GUI list like this:

[...]
    "gui": {
        "television": {
            "name": "Television",
            "group": [ "Living" ],
            "media": [ "web" ]
        },
        "bookShelfLight": {
            "name": "Bookshelf",
            "group": [ "Library" ],
            "media": [ "mobile" ],
            "readonly": 1
        }
    },
[...]

Each device you want to add to the GUI has its own entry. You can only add a device that is also registered in the device setup, but of course, you don't have to present all those devices to the GUIs.

There are some fixed fields that are common for all GUI elements:

  • name - The display name inside the GUI.
  • group - See Group section below.
  • media - Which GUIs should display this devices: mobile, web, desktop, all (default)
  • readonly - Should the GUI element be readonly? Default is 0.

To know what the additional options are for the specific protocols, check the protocol description on the wiki.

Group

The group attribute allows you to group GUI elements. pilight allows you to define multiple groups but it's dependent on the GUI how it will interpret these groups. Currently, the pilight webgui and the Android App Illumina only parses the first group and will create different tabs for each one of them. However, possible implementation could be:

  • Assign element to multiple groups.
  • Create a treeview of descending parent / children.
  • Create pages with grouped widgets.

Settings

The way pilight works can be altered by changing various settings. Some settings are more advanced then others, and some settings are required by others. The most important ones will be described here. For a full description of the pilight settings, check the appropriate wiki page.

  • port
  • receive-repeats
  • webserver-enable
  • webserver-port
  • webserver-cache
  • webgui-websockets
  • whitelist

port

By default, pilight will run at a random port. You can set the port setting to set the port to a fixed number.

"port": 5000

Note that this is not the port for the webGUI, but for programs that communicate with the pilight daemon using the API.

send-repeats and receive-repeats

The send-repeats setting will define how many times pilight must repeatedly send a code. This can depend on your environment. If you have a clear view between your Raspberry Pi and the devices you want to switch, then this number can be lower. When your Raspberry Pi is in a environment with a lot of interference this number needs to be higher.

Support for send-repeats ends with pilight V6 and is replaced with individual protocol settings.

This numeric value for receive-repeats defines how many times a code must be received before pilight interprets it as a valid code. This number is also relevant for those who aren't using a low-pass filter. When noise is received, it often happens that by chance a pattern of noise is the same as the codes sent by one of the supported protocols. This means that pilight will receive false positives. The chance that this noise actually represents the same ID as your device is really low, but if you want to be sure, just increase this number.

"receive-repeats": 1

webserver-enable

pilight ships with a built-in websockets capable webserver. By default the webserver is enabled. If you want to disable it, set this setting to 0.

"webserver-enable": 0

webserver-port

By default, the pilight webserver will run at port 5001. This port is chosen so it doesn't conflict with common webservers like Apache or lighttpd. If you want to run the webserver on the default HTTP port 80, change this setting.

"webserver-port": 80

webserver-cache

By default, the pilight webserver loads all files needed for the webserver into the memory so it only has to be read from the disk once. Every subsequent call to the webserver will just serve all necessary files from within the memory reducing disk-I/O. To disable this caching, set this setting to 0.

"webserver-cache": 0

webgui-websockets

This settings tells the webgui to either use the AJAX communication protocol or the newer websockets. By default, pilight will use websockets. Set this settings to 0 if you want to use AJAX on older browsers:

"webgui-websockets": 0

whitelist

All pilight clients connect to pilight by using a TCP socket connection. If you want to restrict access to pilight to certain devices of IP ranges, and block others, you can add these to the whitelist. You can define specific IP addresses like 192.168.2.100 or IP ranges like 192.168.2.*. In the latter case all IP addresses from 192.168.2.1 to 192.168.2.255 will be allowed to connect to pilight. In the first case only the device with the IP address 192.168.2.100 will be allowed to connect to pilight. You can add several of these IP addresses to the whitelist by separating them by a comma. The localhost IP address (127.0.0.1) has to be enabled by default and can't be blocked.

"whitelist": "192.168.2.100, 10.0.0.*"

See the settings wiki page for a full list of settings and descriptions.

Hardware

Since pilight 3.0 the feature to send and receive from multiple hardware modules has been introduced. This means you can use control various different frequencies at the same time. However, only one definition per frequency is supported. Each hardware module has its own syntax as listed below. So choose one of your liking:

Disabled

{
  "none": { }
}

In case the computer that the pilight-daemon is running on does not have GPIO capabilities, choose this option.

433.92 MHz

lirc_rpi Kernel Module

{
    "433lirc": {
      "socket": "/dev/lirc0"
    }
}

Direct GPIO Access

{
    "433gpio": {
        "sender": 0,
        "receiver": 1
    }
}

For pin numbering, please refer to the specification of the platform used on http://www.wiringx.org. To disable either sending or receiving with 433gpio, just set the appropriate pin to -1.

Arduino USB-Nano

{
    "433nano": {
        "comport": "/dev/ttyUSB0"
    }
}

You can not configure the ports on the arduino, the receiver is connected to pin D2 and the transmitter is connected to pin D5 of the nano.

the only port you can configure currently is the USB port the Nano is connected to.

{
    "433nano": {
        "comport": "COM5"
    }
}

On Windows machines use the windows syntax for the com port.

Registry

Besides all the fixed configuration objects, pilight also allows developers to use the integrated registry. This registry allows developers to store information and to retrieve them later on. pilight itself will for example store its current version in the registry and the pilight webgui will store additional settings in there as well. You are therefore advised to leave the registry untouched so all additional information created by the different GUIs isn't lost.

config.txt · Last modified: 2015/11/27 22:09 (external edit)