475 lines
17 KiB
Plaintext
475 lines
17 KiB
Plaintext
<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.sourceforge.net/"><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> = ¶meters.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> = ¶meters.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> = ¶meters.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> = ¶meters.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> = ¶meters.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> = ¶meters.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> = ¶meters.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> = ¶meters.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> = ¶meters.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> = ¶meters.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).
|
|
</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 but it has been ignored. The LIRC team
|
|
currently seems only to be interested in adding IR support to the kernel.
|
|
You can obtain my modified files from
|
|
<ulink url="https://github.com/emteejay/Patched-LIRC.git">GitHub</ulink>.
|
|
The standard UDP driver is satisfactory for most uses but I recommend
|
|
using the modified driver if you intend to use <code>irrecord</code>
|
|
</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>
|