User Tools

Site Tools


config

This is an old revision of the document!


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 to which it's location is set in the settings.json under config-file. The syntax of the config file is just like the settings file in JSON.

Basic Syntax

The pilight configuration contains two basic levels:

  1. Locations
  2. Devices

So, you can define various locations and these locations can hold various devices. The locations are set like this:

{
    "living": {
        "name": "Living"
    },  
    "bedroom": {
        "name": "Bedroom"
    }        
}

The first JSON key living is the id used by pilight to identify a specific location, the value of the name (in this case Living with a capital L) setting is the name communicated by pilight.

Of course, after we have defined various locations, we also want to assign devices to these locations. This can be done as follows:

{
    "living": {
        "name": "Living",
        "order": 1,
        "bookshelve": {
            "name": "Book Shelve Light",
            "protocol": ["kaku_switch"],
            "id": [{
                "id": 1234,
                "unit": 0
            }],
            "state": "off"
        },
        "television": {
            "name": "Television",
            "protocol": ["relay"],
            "id": [{
                "gpio": 3
            }],
            "state": "off"
        }
    }        
}

In this example, the location Living has two devices. One KlikAanKlikUit switch that controls the Book Shelve Light, and a relay that is meant to turn the Television on and off.

Whenever an action has been performed by pilight the config file will update itself when necessary. Also, whenever a specific action has been received by pilight concerning one of the devices, pilight will update the config file accordingly. So, would you in this example, turn the Book Shelve Light on with a KlikAanKlikUit remote, pilight will also record this, and change the status of the Book Shelve Light to on. Of course, a receiver needs to be connected for this to work. Each device has it's own specific syntax but it's settings 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 on this wiki.

Multiple ID's

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:

{
    "living": {
        "name": "Living",
        "bookshelve": {
            "name": "Book Shelve Light",
            "protocol": ["kaku_switch"],
            "id": [{
                "id": 1234,
                "unit": 0
            },
            {
                "id": 2345,
                "unit": 1
            }],
            "state": "off"
        }
    }        
}

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 KaKu switches can be controlled by either the KaKu old remotes and the KaKu new remotes. This means that pilight needs to check both protocols to know whether a device state was changed. In case of a KaKu 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:

{
    "living": {
        "name": "Living",
        "bookshelve": {
            "name": "Book Shelve Light",
            "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:

  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 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.
  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 the GUIs 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 have shown as a switch in the GUIs.

Override Protocol Settings

Each protocol also has specific settings you can override in your config file. What these settings are, can be found in the protocols section 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 to bright. But we also don't want it to go to it's minimum dimlevel, because then it's to dim. In that case, you can override the min and max values of the dimmer:

{
    "living": {
        "name": "Living",
        "main": {
            "name": "Main",
            "protocol": ["kaku_dimmer"],
            "id": [{
                "id": 1234,
                "unit": 1
            }],
            "state": "on",
            "dimlevel", 3,
            "settings": {
                "min": 3,
                "max": 10
            }, 
        }
    }
}

Of course, the maximum dimlevels can still be overriden by the KlikAanKlikUit remote, but pilight will make sure it can not control the dimmers below or above these dimlevels with the controller or GUIs. They can be overridden by the pilight-sender but that's not recommended.

These settings WILL NOT be validated when using pilight-send. They WILL be validated when pilight wants to update the config file. This means you can override these settings by pilight-send but if you do, the config file will not reflect the real world states of a device. The config will always keep its consistancy.

config.1381502245.txt.gz · Last modified: 2015/11/27 21:08 (external edit)