The Mini-Box.com USB LCD picoLCD Driver

This section covers the installation and use of the Mini-Box USB LCD displays.

Displays

Mini-Box.com offers two types of USB LCD displays:

PicoLCD 4x20-Sideshow

PicoLCD 4x20-Sideshow is the desktop variant targeted at end users. It an external USB 2.0 full speed device that comes in a stylish casing and sports a 4 line by 20 character display with white letters on a blue background, a built-in InfraRed receiver as well as an keypad with 8 keys labeled Escape, F1, F2, F3, Home, Up, Down and Enter.

picoLCD 20x2 (OEM)

picoLCD-20x2-OEM 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, I2C or USART (the latter two are not supported by this driver). It has connectors for an InfraRed receiver, keypad and LEDs.

When pre-installed in enclosures like the Mini-Box M300 LCD it comes equipped with an InfraRed receiver as well as key pad with 12 keys labeled Plus, Minus, F1, F2, F3, F4, F5, Up, Down, Left, Right, and Enter.

Finally, the picoLCD 20x2 (OEM) supports 8 general purpose outputs and 10 custom splash screens. Although these features are not supported by this driver, the splash screens can be changed using the usblcd tool, that can be built from the Linux SDK available on the picoLCD web page.

Requirements

The driver is based on the libusb USB library, which should make it work with Linux, the different BSB variants as well as Darwin/MacOS X.

Note

When using a libusb based driver like picolcd, LCDd needs to be started as root.

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

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

Configuration in LCDd.conf

[picolcd]

Backlight = { yes | no }

Turns the backlight on or off, default yes.

Brightness = BRIGHTNESS

Set the initial brightness. Legal values are: 0 - 1000. If not given, it defaults to 1000.

Contrast = CONTRAST

Contrast: 0-1000. 0 is visible, and 1000 is not on my M300. Default is 1000.

KeyLights = { yes | no }

Allow key LEDs to be turned on or off. Default is yes.

Key0Light = { yes | no }

If Keylights is set, you can disable the directional pad LED by setting this value to no. Default is yes.

Key1Light = { yes | no }

If Keylights is set, you can disable the F1 LED by setting this value to no. Default is yes.

Key2Light = { yes | no }

If Keylights is set, you can disable the F2 LED by setting this value to no. Default is yes.

Key3Light = { yes | no }

If Keylights is set, you can disable the F3 LED by setting this value to no. Default is yes.

Key4Light = { yes | no }

If Keylights is set, you can disable the F4 LED by setting this value to no. Default is yes.

Key5Light = { yes | no }

If Keylights is set, you can disable the F5 LED by setting this value to no. Default is yes.

KeyTimeout = DURATION

(Advanced) This value controls how long LCDd waits for a key press when get_key() is called. The value represents microseconds and the default is 500 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. Lparameterer values make key presses more reliable if somewhat slow to take effect.

LircHost = HOSTNAME_OR_IP-ADDRESS

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.

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 pulse and mark 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.

LircPort = PORTNUM

This value determines the UDP port to which the driver will send IR data from the sensor. It defaults to 8765, which is also the default port on which LIRC will listen.

LircSync = DURATION

This value determines the length in jiffies (1/16384 seconds) of the synthesized sync pulse added to the beginning of the UDP packet sent to LIRC. Values up to 255 are permitted. Setting a length of zero will suppress the synthesized pulse (I can't make it work without it, though). The default is 64 jiffies (3.9ms).

LircLength = DURATION

This value determines the length in jiffies (1/16384 seconds) of the entire LIRC code for a single remote property. It depends on the notion that all propertys are of the same duration, and are padded with a trailing gap (space) to make up the time. No such gap is emitted by the picolcd hardware. Values up to MAXINT are permitted. Setting a length of zero will suppress the synthesized gap. The default is 2048 jiffies (125ms).

picolcd driver status

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 combonation, 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 mutiple events if the user is more than a tenth of a second (maybe less?) off in motions.

Infrared sensor status

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 still had trouble getting irrecord to work; you need at least to feed it a template configuration containing sync and gap data.

This code could therefore use more testing, more research, and more work.

Copyright

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.