====== CONFIGURATION ======

The config file (default: /etc/lcd4linux.conf) contains the configuration and layout of LCD4Linux. Starting with 0.10, the format changed a lot, and is now much more flexible.

Any text on a line after a hash character ('#') (and empty lines) will be ignored (If you want to use '#' in a value (think of X11-colors), you have to quote it with a backslash). Empty lines and lines containing only whitespace characters will be ignored, too.

The file consists of sections, subsections and parameters. Section and parameter names are not case sensitive. A key must not contain whitespace. 

A parameter looks like this:
<code>
name value
</code>


**BIG FAT WARNING**: Every //value// from the config file is treated as an //expression//, and therefore will be //[[:Evaluator|evaluated]]//. This means that normally you have to enclose a value in single quotes so that it evaluates to a string!

Some examples:
<code>
name1 value1
name2 'value2'
name3 '2+3'
name4 2+3
name5 '42'
name6 42
</code>


//name1// will be evaluated from the expression 'value1', which will return 0 (or an empty string), which is normally not what you want (except when value1 is the name of a variable).\\\

//name2// will return the string 'value2', which is what you want.\\\

//name3// will return the string '2+3'\\\

//name4// will evaluate the expression '2+3', and will return 5\\\

//name5// will evaluate to the string '42' (or the number 42 in numeric context)\\\

//name6// gives exactly the same result as name5\\\


//Sections// looks like this:
<code>
section_a {
   name1 value1
}
section_b name_b {
   name2 value2
}
section_c name_c {
   name3 value3
   section_d {
      name4 value4
   }
}
</code>


So a section may or may not have a name!

Sections can be written in a //compact// form, so the following is fully equivalent to the example above:
<code>
section_a.name1 value1
section_b:name_b.name2 value2
section_c:name_c.name3 value3
section_c:name_c.section_d.name4 value4
</code>


Sections and section names are concatenated with a colon (':'); sections, subsections and keys are concatenated with a dot ('.')

Here's a more real-world example: the following two entries (from a wiring configuration) are equivalent:
<code>
Wire.EX   'STROBE'
Wire.IOC1 'SELECT'
Wire.IOC2 'AUTOFD'
Wire.GPO  'INIT'
</code>

<code>
Wire {
   EX   'STROBE'
   IOC1 'SELECT'
   IOC2 'AUTOFD'
   GPO  'INIT'
}
</code>


----

===== Section selection =====

Note that there's a difference between //name value { }// and //name value//: The first defines a section, the second a parameter, but both have the same name! This is used to //select// a specific section.

Take a look at this:
<code>
Display My_20x4 {
   ...
}

Display My_16x2 {
   ...
}

Display My_16x2
</code>


You define two display sections with different names, and afterwards select one of the sections.

----

===== Special sections =====

some sections have a special meaning:

**[[:Displays|Display]]**: Display-specific configuration, depends on the display and driver used.\\\

**[[:Plugins|Plugin]]**: Configuration for specific plugins (rarely used)\\\

**[[:Layout|Widget]]**: Definition of Widgets \\\

**[[:Layout|Layout]]**: How and where widgets are placed on the display\\\

**Variables**: Definition of variables\\\


----

===== Minimalistic example configuration =====

<code>
Display HD44780-20x2 {
    Driver  'HD44780'
    Model   'generic'
    UseBusy  1
    Port    '/dev/parport0'	
    Size    '20x2'
    Wire {
	RW      'AUTOFD'
	RS      'INIT'
	ENABLE  'STROBE'
	ENABLE2 'GND'
	GPO     'GND'
    }
}


Widget CPU {
    class  'Text'
    expression  uname('machine')
    prefix 'CPU '
    width  9
    align  'L'
    update tick
}

Layout Default {
    Row1 {
        Col1 'CPU'
    }
}

Variables {
   tick 500
}

Display 'HD44780-20x2'
Layout  'Default'
</code>


There is at least one //[[:Displays|Display]]// section, which describes and configures your display.\\\

You have some //[[:Layout|Widget]]// sections, which define what and how data is displayed.\\\

Widgets are placed on the display in the //[[:Layout|Layout]]// section.\\\


----

===== Security =====

Because of security reasons (the configuration may contain usernames/passwords for mail accounts) the config file is assured to be:

  * file is a normal file (or /dev/null)
  * file owner is owner of program
  * file is not accessible by group
  * file is not accessible by other

So if you run lcd4linux as root, /etc/lcd4linux.conf has to be:
<code>
chmod 600
chown root.root
</code>


----