User Tools

Site Tools


config

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
config [2013/10/09 10:57]
curlymo
config [2015/11/27 21:09] (current)
Line 1: Line 1:
-**Configuration**+====== ​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.+**//Make sure the daemon is not running before editing ​the configuration//​**
  
-The ''​pilight''​ configuration has to be put in an external file to which it's location is set in the [[settings|settings.json]] under ''​config-file''​. The syntax ​of the config file is just like the settings file in JSON.+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.
  
-Basic Syntax+The pilight configuration has to be put in an external file called config.json. It is located under /​etc/​pilight/​config.json
  
-The ''​pilight'' ​configuration contains ​two basic levels: +For any questions regarding JSON, [[http://​en.wikipedia.org/​wiki/​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. 
-  - Locations+ 
 +===== Basic Syntax ===== 
 +The pilight configuration contains ​six basic levels:
   - Devices   - Devices
 +  - Rules
 +  - GUI
 +  - Settings
 +  - Hardware
 +  - Registry
  
-So, you can define various locations and these locations can hold various devices. The locations are set like this: +===== Devices ===== 
-<​code ​js+<​code>​ 
-+[...] 
-    "​living":​ { +    "devices": { 
-        "​name":​ "​Living"​ +        "television": { 
-    },   +            "​protocol":​ [ "relay" ],
-    "​bedroom":​ { +
-        "​name":​ "​Bedroom"​ +
-    }         +
-+
-</​code>​ +
- +
-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 locationsThis can be done as follows: +
- +
-<code js> +
-{ +
-    "living": { +
-        "name": "​Living",​ +
-        "​order":​ 1, +
-        "​bookshelve": { +
-            "​name":​ "Book Shelve Light",​ +
-            "​protocol":​ ["kaku_switch"],+
             "​id":​ [{             "​id":​ [{
-                "id": ​1234, +                "gpio": ​3
-                "​unit":​ 0+
             }],             }],
             "​state":​ "​off"​             "​state":​ "​off"​
         },         },
-        "television": { +        "bookShelfLight": { 
-            "​name":​ "​Television",​ +            "​protocol":​ [ "kaku_switch" ],
-            "​protocol":​ ["relay"],+
             "​id":​ [{             "​id":​ [{
-                "gpio": ​3+                "id": ​123456, 
 +                "​unit":​ 1
             }],             }],
             "​state":​ "​off"​             "​state":​ "​off"​
         }         }
-    }         +    }, 
-}+[...]
 </​code>​ </​code>​
  
-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''​.+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 ​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 sameThat is:
  
-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   * name
   * protocol   * protocol
   * id   * id
  
-To know what the syntax of the specific protocol you want to use you can refer to the [[protocols|protocols]] description ​on this wiki.+To know what the syntax of the specific protocol you want to use you can refer to the [[protocols]] description.
  
-Multiple ID's+==== 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:
  
-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: +<​code>​
- +
-<​code ​js>+
 { {
-    "living": { +    "origin":​ "​receiver",​ 
-        "name": "Living", +    "​protocol":​ "​arctech_switches",​ 
-        "bookshelve": { +    "code": { 
-            "name": "Book Shelve Light",+        "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 
 +
 +</​code>​ 
 + 
 +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: 
 + 
 +<​code>​ 
 +[...] 
 +    "​devices":​ { 
 +        "​bookShelfLight":​ {
             "​protocol":​ ["​kaku_switch"​],​             "​protocol":​ ["​kaku_switch"​],​
             "​id":​ [{             "​id":​ [{
Line 83: Line 107:
             "​state":​ "​off"​             "​state":​ "​off"​
         }         }
-    }         +    }       
-}+[...]
 </​code>​ </​code>​
  
-Whenever one of these id's have been received, ​''​pilight'' ​will update the device accordingly. +Whenever one of these ids has been received, pilight will update the device accordingly.
- +
-Multiple Protocols per Device+
  
-pilight ​support ​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 now 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 one ID each protocol and all protocol values should be present. An example:+==== 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:
  
 <​code>​ <​code>​
-{ +[...] 
-    "living": { +    "devices": { 
-        "name": "​Living",​ +        "bookShelfLight": {
-        "​bookshelve": { +
-            "​name":​ "Book Shelve Light",​+
             "​protocol":​ [ "​kaku_dimmer",​ "​kaku_switch",​ "​kaku_old"​ ],             "​protocol":​ [ "​kaku_dimmer",​ "​kaku_switch",​ "​kaku_old"​ ],
             "​id":​ [{             "​id":​ [{
Line 111: Line 132:
             "​dimlevel":​ 10             "​dimlevel":​ 10
         }         }
-    }         +    } 
-}+[...]
 </​code>​ </​code>​
  
 Please notice 3 important things: 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 an dimlevel and state value present in the device. 
-  - 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+  * 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.
  
-Each protocol also has specific settings you can override in your config file. What these settings arecan be found in the [[protocols|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.+==== 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 ​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:+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:
  
 <​code>​ <​code>​
 { {
-    "living": { +    "devices": { 
-        "name": "Living", +        "mainDimmer": ​
-        "main": { +                ​"protocol":​ ["​kaku_dimmer"]
-            "name": "Main", +                "id": ​[
-            "​protocol":​ ["kaku_dimmer"],+                        "id": ​1234, 
 +                        ​"unit": 1 
 +                }], 
 +                "​state":​ "​on",​ 
 +                "​dimlevel":​ 3, 
 +                "​dimlevel-minimum":​ 3, 
 +                "​dimlevel-maximum":​ 10 
 +        } 
 +    } 
 +
 +</​code>​ 
 + 
 +Another example: 
 + 
 +<​code>​ 
 +
 +    "​devices":​ { 
 +        "​OutsideTemp":​ { 
 +            "​protocol":​ [ "conrad_weather" ],
             "​id":​ [{             "​id":​ [{
-                "​id": ​1234,+                "​id": ​236, 
 +                "​channel":​ 1 
 +            }], 
 +            "​humidity":​ 0, 
 +            "​temperature":​ 29.16, 
 +            "​battery":​ 0, 
 +            "​temperature-offset":​ -0.50 
 +        } 
 +    } 
 +
 +</​code>​ 
 + 
 +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: 
 + 
 +<​code>​ 
 +[...] 
 +    "​rules":​ { 
 +        "​rule_name":​ { 
 +            "​rule":​ "IF switch.state IS on THEN switch DEVICE switch.state TO off",​ 
 +            "​active":​ 1 
 +        } 
 +    }, 
 +[...] 
 +</​code>​ 
 + 
 +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 [[http://​www.pilight.org/​getting-started/​eventing/​|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: 
 + 
 +<​code>​ 
 +[...] 
 +    "​devices":​ { 
 +        "​television":​ { 
 +            "​protocol":​ [ "​relay"​ ], 
 +            "​id":​ [{ 
 +                "​gpio":​ 3 
 +            }], 
 +            "​state":​ "​off"​ 
 +        }, 
 +        "​bookShelfLight":​ { 
 +            "​protocol":​ [ "​kaku_switch"​ ], 
 +            "​id":​ [{ 
 +                "​id":​ 123456,
                 "​unit":​ 1                 "​unit":​ 1
             }],             }],
-            "​state":​ "on"+            "​state":​ "off"
-            "​dimlevel",​ 3, +
-            "​settings":​ [{ +
-                "​min":​ 3, +
-                "​max":​ 10 +
-            }], +
         }         }
 +    },
 +[...]
 +</​code>​
 +
 +To present these devices to our GUI, we have to add them to the GUI list like this:
 +
 +<​code>​
 +[...]
 +    "​gui":​ {
 +        "​television":​ {
 +            "​name":​ "​Television",​
 +            "​group":​ [ "​Living"​ ],
 +            "​media":​ [ "​web"​ ]
 +        },
 +        "​bookShelfLight":​ {
 +            "​name":​ "​Bookshelf",​
 +            "​group":​ [ "​Library"​ ],
 +            "​media":​ [ "​mobile"​ ],
 +            "​readonly":​ 1
 +        }
 +    },
 +[...]
 +</​code>​
 +
 +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 [[settings|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.
 +
 +<​code>​
 +"​port":​ 5000
 +</​code>​
 +
 +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.
 +
 +<​code>​
 +"​receive-repeats":​ 1
 +</​code>​
 +
 +=== 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.
 +
 +<​code>​
 +"​webserver-enable":​ 0
 +</​code>​
 +
 +=== 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.
 +
 +<​code>​
 +"​webserver-port":​ 80
 +</​code>​
 +
 +=== 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.
 +
 +<​code>​
 +"​webserver-cache":​ 0
 +</​code>​
 +
 +=== 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:
 +
 +<​code>​
 +"​webgui-websockets":​ 0
 +</​code>​
 +
 +=== 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.
 +
 +<​code>​
 +"​whitelist":​ "​192.168.2.100,​ 10.0.0.*"​
 +</​code>​
 +
 +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 ====
 +<​code>​
 +{
 +  "​none":​ { }
 +}
 +</​code>​
 +
 +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 ===
 +
 +<​code>​
 +{
 +    "​433lirc":​ {
 +      "​socket":​ "/​dev/​lirc0"​
     }     }
 } }
 </​code>​ </​code>​
  
-Of course, the maximum dimlevels can still be overriden by the KlikAanKlikUit remotebut ''​pilight''​ will make sure it can not control ​the dimmers below or above these dimlevels with the controller or GUIsThey can be overridden by the pilight-sender but that's not recommended.+=== Direct GPIO Access === 
 + 
 +<​code>​ 
 +
 +    "​433gpio":​ { 
 +        "​sender":​ 0, 
 +        "​receiver":​ 1 
 +    } 
 +
 +</​code>​ 
 + 
 +For pin numbering, please refer to the specification of the platform used on http://​www.wiringx.org. To disable either sending or receiving with 433gpiojust set the appropriate pin to -1. 
 + 
 +=== Arduino USB-Nano === 
 + 
 +<​code>​ 
 +
 +    "​433nano":​ { 
 +        "​comport":​ "/​dev/​ttyUSB0"​ 
 +    } 
 +
 +</​code>​ 
 + 
 +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. 
 + 
 +<​code>​ 
 +
 +    "​433nano":​ { 
 +        "​comport":​ "​COM5"​ 
 +    } 
 +
 +</​code>​ 
 + 
 +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.
  
-**These settings WILL NOT be validated when starting the daemon or when using pilight-send. They WILL be validated when trying to send / receive codes through the controller or GUIs. If these programs don't work, you probably have a conflicts in these settings or there is a bug in one of the GUIs created by third parties.** 
config.1381316238.txt.gz · Last modified: 2015/11/27 21:08 (external edit)