<sect1 id="picolcd">
<title>The Mini-Box.com USB LCD picoLCD Driver</title>

<para>
	This section covers the use of the Mini-Box USB LCD displays.
</para>

<sect2 id="picolcd-displays">
<title>Displays</title>
<para>
	<ulink url="http://www.mini-box.com/">Mini-Box.com</ulink> offers two types of
	USB LCD displays:
</para>

<variablelist>
<varlistentry>
<term>PicoLCD 4x20-Sideshow</term>
<listitem>
<para>
	<ulink url="http://www.mini-box.com/PicoLCD-4X20-Sideshow">PicoLCD 4x20-Sideshow</ulink>
	is the desktop variant targeted at end users.
	It is an external USB 2.0 full speed device that comes in a stylish case and
	sports a 4 line by 20 character display with white letters
	on a blue background, a built-in InfraRed receiver as well as a
	keypad with 8 keys labeled <literal>Escape</literal>, <literal>F1</literal>,
	<literal>F2</literal>, <literal>F3</literal>, <literal>Home</literal>,
	<literal>Up</literal>, <literal>Down</literal> and <literal>Enter</literal>.
</para>
</listitem>
</varlistentry>

<varlistentry>
<term>picoLCD 20x2 (OEM)</term>
<listitem>
<para>
	<ulink url="http://www.mini-box.com/picoLCD-20x2-OEM">picoLCD-20x2-OEM</ulink> is
	the OEM version.
	It is a 2 line by 20 character display with black letters on a
	yellow-green background, that can be connected to the system via
	USB, I<superscript>2</superscript>C or USART (the latter two are
	not supported by this driver).
	It  has connectors for an InfraRed receiver, keypad and LEDs.
</para>

<para>
 	When pre-installed in enclosures like the
	<ulink url="http://www.mini-box.com/Mini-Box-M300-LCD">Mini-Box M300 LCD</ulink>
	it comes equipped with an InfraRed receiver as well as key pad with
	12 keys labeled <literal>Plus</literal>, <literal>Minus</literal>,
	<literal>F1</literal>, <literal>F2</literal>, <literal>F3</literal>,
	<literal>F4</literal>, <literal>F5</literal>, <literal>Up</literal>,
	<literal>Down</literal>, <literal>Left</literal>, <literal>Right</literal>,
	and <literal>Enter</literal>.
</para>

<para>
	Finally, the picoLCD 20x2 (OEM) supports 8 general purpose outputs
	and 10 custom splash screens.
	When the keypad is connected the outputs control the key LEDs. The
	output command and KeyLight settings below can be used to control the
	outputs.
	Although splash screens are not supported by this driver, the
	splash screens can be changed using the <command>usblcd</command>
	tool, that can be built from the Linux SDK available on the picoLCD web page.
</para>
</listitem>
</varlistentry>
</variablelist>

</sect2>


<sect2 id="picolcd-requirements">
<title>Requirements</title>

<para>
	The driver is based on the
	<ulink url="http://libusb.info/"><filename>libusb</filename></ulink>
	USB library, which should make it work with Linux, the different BSB variants
	as well as Darwin/MacOS X.

<note>
	<para>
		When using a <filename>libusb</filename> based driver like
		<code>picolcd</code>, <application>LCDd</application>
		needs to be started as root.
	</para>
</note>
</para>

<para>
	On Linux, the only kernel module required is the USB host controller
	driver 	(<filename>uhci_hcd</filename> on the M300) to fire up the USB bus
	to which the LCD is attached.
	For other operating systems, analogous requirements apply.
</para>

<para>
	Lastly, for <filename>libusb</filename> to work correctly,
	the <filename>usbfs</filename> file system must be mounted on
	<filename>/proc/bus/usb</filename>, e.g. using the command
	<code>mount -t usbfs usbfs /proc/bus/usb</code> or by your system's
	default configuration.
</para>
</sect2>



<sect2 id="picolcd-config">
<title>Configuration in LCDd.conf</title>

<sect3 id="picolcd-config-section">
<title>[picolcd]</title>

<variablelist>

<note>
  <para>
    The Brightness and OffBrightness settings only have an effect on the 20x4
    device. With the 20x2 device the backlight can only be set on (any value
    <literal>1</literal> or greater) or off (<literal>0</literal>).
  </para>
</note>

<varlistentry>
  <term>
    <property>Backlight</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    Turns the backlight on or off on start-up, default <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Brightness</property> =
    <parameter><replaceable>BRIGHTNESS</replaceable></parameter>
  </term>
  <listitem>
  <para>
    Set the initial brightness if the backlight is on. Legal values are:
    <literal>0</literal> - <literal>1000</literal>. If not given, it defaults
    to <literal>1000</literal>.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>OffBrightness</property> =
    <parameter><replaceable>OFFBRIGHTNESS</replaceable></parameter>
  </term>
  <listitem>
  <para>
    Set the initial value for the backlight if it is off. Legal values are:
    <literal>0</literal> - <literal>1000</literal>. If not given, it defaults
    to <literal>0</literal>.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Contrast</property> =
    <parameter><replaceable>CONTRAST</replaceable></parameter>
  </term>
  <listitem><para>
    Contrast: <literal>0</literal>-<literal>1000</literal>, default to
    <literal>1000</literal> (full contrast).
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>LinkLights</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    Allow key LEDs to be turned on or off with the backlight. Default is <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>KeyLights</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    Allow key LEDs to be turned on or off. Default is <literal>yes</literal>.
    This setting affects all keys. If set to <literal>on</literal> each key
    can be disabled independently by setting <literal>KeyXLight</literal> below.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Key0Light</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    If <property>Keylights</property> is set, you can disable the directional pad LED by
    setting this value to <literal>no</literal>.  Default is <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Key1Light</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    If <property>Keylights</property> is set, you can disable the F1 LED by setting this value
    to <literal>no</literal>.  Default is <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Key2Light</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    If <property>Keylights</property> is set, you can disable the F2 LED by setting this value
    to <literal>no</literal>.  Default is <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Key3Light</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    If <property>Keylights</property> is set, you can disable the F3 LED by setting this value
    to <literal>no</literal>.  Default is <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Key4Light</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    If <property>Keylights</property> is set, you can disable the F4 LED by setting this value
    to <literal>no</literal>.  Default is <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>Key5Light</property> = &parameters.yesdefno;
  </term>
  <listitem><para>
    If <property>Keylights</property> is set, you can disable the F5 LED by setting this value
    to <literal>no</literal>.  Default is <literal>yes</literal>.
  </para></listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>KeyTimeout</property> =
    <parameter><replaceable>DURATION</replaceable></parameter>
  </term>
  <listitem>
  <para>
    KeyTimeout is only used if the picoLCD driver is built with libusb-0.1, when
    built with libusb-1.0 key and IR data is input asynchronously so there is no
    need to wait for the USB data thus allowing LCDd to process other inputs at
    the correct rate.
  </para>
  <para>
    This value controls how long <application>LCDd</application> waits for a key press when
    get_key() is called.  The value represents milliseconds and the default is <literal>500</literal>
    or .5 seconds.  Lowering this value will make LCDd more responsive but also causes LCDd to use
    more CPU time and, as the timeout grows shorter, key presses become harder to detect.
    Large values make key presses more reliable but may slow down LCDd. Values
    in the range <literal>0</literal>-<literal>1000</literal> (1s) are allowed.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>KeyRepeatDelay</property> =
    <parameter><replaceable>DURATION</replaceable></parameter>
  </term>
  <listitem>
  <para>
    KeyRepeatDelay is only used if the picoLCD driver is built with libusb-1.0, when
    built with libusb-0.1 key input blocks all other processing until the key is released.
  </para>
  <para>
    This value controls how long <application>LCDd</application> waits from when a key is
	pressed and reported before generating the first repeat.  The value represents milliseconds
	and the default is <literal>300</literal> (0.3 second).  Use zero to disable auto repeat.
	Values in the range <literal>0</literal>-<literal>3000</literal> (3s) are allowed.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>KeyRepeatInterval</property> =
    <parameter><replaceable>DURATION</replaceable></parameter>
  </term>
  <listitem>
  <para>
    KeyRepeatInterval is only used if the picoLCD driver is built with libusb-1.0, when
    built with libusb-0.1 key input blocks all other processing until the key is released.
  </para>
  <para>
    This value controls how long <application>LCDd</application> waits between key reports
	after generating the first repeat.  The value represents milliseconds and the default
	is <literal>200</literal> (0.2 second). Use zero to disable auto repeat.
	Values in the range <literal>0</literal>-<literal>3000</literal> (3s) are allowed.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>LircHost</property> =
    <parameter><replaceable>HOSTNAME_OR_IP-ADDRESS</replaceable></parameter>
  </term>
  <listitem>
  <para>
    Set the hostname or IP address to which the driver will send IR data from the sensor.
    If not set or set to an empty value, IR support for LIRC will be disabled.
  </para>
  <para>
    LIRC should be configured to use the driver "udp", which will cause it to listen on some
    UDP port for packets containing a series of integers, representing mark and space
    intervals from the sensor. It doesn't matter whether LCDd or LIRC is started first; if LIRC
    isn't listening, the packets from LCDd will be discarded. When LIRC comes back, it will
    start picking up the packets. Similarly, LCDd can be stopped and restarted without affecting
    anything, because UDP is a connectionless protocol.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>LircPort</property> =
    <parameter><replaceable>PORTNUM</replaceable></parameter>
  </term>
  <listitem>
  <para>
    This value determines the UDP port to which the driver will send IR data from the sensor. It
    defaults to <literal>8765</literal>, which is also the default port on which LIRC will listen.
  </para>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>LircTime_us</property> = &parameters.yesnodef;
  </term>
  <listitem>
  <para>
	If <property>LircTime_us</property> is set to on mark and space times
	are sent to LIRC in microseconds (requires a LIRC UDP driver that
	accepts this (LIRC 0.9.3 onwards)).
  </para>
  <para>
	If <property>LircTime_us</property> is set to off mark and space times
	are sent to LIRC in 'jiffies' (1/16384s) (supported by the standard LIRC
	UDP driver).
  </para>
  <para>
	Default is <literal>off</literal>.
  </para>
  <note>
  <para>
	One 'jiffy' is approximately 61 microseconds about a tenth of typical IR
	mark and space times. LIRC configuration program <code>irrecord</code>
	cannot reliably detect the IR data timing when measured in 'jiffies' it
	works better with microseconds.
  </para>
  <para>
	I have submitted a patch that modifies the LIRC udp driver to support
	timing data in microseconds. This was included in LIRC 0.9.3.
	The default (61&micro;s) UDP driver settings will work but I recommend
	using 1 microsecond.
	The LIRC upd plugin timing resolution can be set using the
	<code>--driver-option=clocktick:value</code>
	or <code>-A clocktick:value</code> command line switch.
  </para>
  </note>
  </listitem>
</varlistentry>

<varlistentry>
  <term>
    <property>LircFlushThreshold</property> =
    <parameter><replaceable>DURATION</replaceable></parameter>
  </term>
  <listitem>
  <para>
	This value is the length in microseconds of the gap that will trigger
	sending the queued IR data to LIRC. Values greater than 1000 (1ms) are
	permitted, lower values will set the default value 8000 (8ms). The
	maximum depends on the setting of LircTime_us; if LircTime_us is on
	values greater than 32.767ms will disable the flush, if LircTime_us is
	off values greater than 1.999938s will disable the flush. The value
	should be less than the gap times specified in <code>lircd.conf</code>
	and greater than any space time specified in any header, one, zero, etc.
	field.
  </para>
  </listitem>
</varlistentry>
</variablelist>

</sect3>
</sect2>


<sect2 id="picolcd-status">
<title>picolcd driver status</title>

<para>
	The hardware also reports key-up events.  Normally this would be of no issue (they are
	usually a 0 or 'no key') except that when keys are used in combination, the key-up
	event may actually come back as multiple events depending on how the user released the
	keys.  If the key-up event for a multiple key press comes back as two events, the first
	up event will actually look like a new key press.  The algorithm in get_key tries to
	deal with this in a sane way and toss out all key-up events for now.  The hardware is
	touchy and both combo key-down and key-up actions may be reported as multiple events if
	the user is more than a tenth of a second (maybe less?) off in motions.
	The hardware is <emphasis>not</emphasis> "touchy" it reports what it receives. Two key
	presses or releases may appear simultaneous to a human but they are always some time apart.
	The hardware probably samples the keys for every USB transfer cycle; that is every 10ms,
	significantly faster than the typical human response time of a few hundred milliseconds!
</para>

<sect3 id="picolcd-ir-status">
<title>Infrared sensor status</title>

<para>
	LIRC expects sensor data that starts with a longish 'sync' space, denoting the start of
	a command; followed by the code data, a sequence of mark/space pairs; sometimes followed by
	a 'gap', which should be a space long enough to make the entire command up to a preset
	duration in milliseconds. The 'sync' and the 'gap' are absent from the data
	emitted by the picolcd hardware. I found that LIRC configuration files for remotes similar to the
	ones I tested all used such a fixed-duration encoding, and as that was the only way I could get it
	working, this driver by default adds the gap as well as the sync. However I have
	<emphasis>still</emphasis> had trouble getting <code>irrecord</code> to work; you need at least
	to feed it a template configuration containing sync and gap data.
	The LIRC configuration program <code>irrecord</code> cannot reliably
	detect the IR data timing when measured in 'jiffies' it works better
	with microseconds, see <code>LircTime_us</code> above.
</para>
<note>
  <para>
	The current libusb-1.0 implementation polls at 32Hz to see if any USB
	processing is required, this is  needed when a key has been pressed or
	some IR data has been received. 32Hz has a period of 31.25ms this is not
	really fast enough the picoLCD USB transfers can occur every 10ms. This
	may cause buffer overrun problems for long bursts of IR data. The best
	solution would be to include USB processing in the main loop <code>select</code>
	statement this has not been done to avoid major changes to the core
	code, to work-round this extra USB transfer buffers are allocated. It
	may also be worth building with <code>PROCESS_FREQ</code> set to 100Hz
	(in <code>server/main.h</code>).
  </para>
</note>
</sect3>
</sect2>

<sect2 id="picolcd-copy">
<title>Copyright</title>

<para>
	The lcdproc picolcd driver originally was written by Gatewood Green (woody@nitrosecurity.com)
	or (woody@linif.org) and paid for by NitroSecurity, Inc (nitrosecurity.com),
	but has been extended with code from various contributors since then.
</para>

</sect2>

</sect1>