Matrix Orbital LK202-24-USB

January 30, 2003

The new Matrix Orbital LK202-24-USB displays will work with a patched version of the Linux kernel. This will allow applications such LCDProc to work with it without modification.

The LK202-24-USB is a 2x20 LCD display that takes a single USB cable to connect to the PC. The details of the LCD display can be found at http://www.matrixorbital.com/pdfs/LK202-24-USB_01.pdf

It is my goal to have the support added to the kernel directly so that future versions will support the display directly, but that may take a little while. Until then, the kernel has to be patched. For someone who compiled a kernel before, this is an easy project. For someone that hasn’t, this is a very good first project. This article won’t explain too much about how to configure a kernel, but with a good book or the phone number of a guru, this should be a good learning experience.

Details of patching the kernel
Using LCDProc with the USB display
What has been tested
What has NOT been tested
To Do: Hot pluggable LCD displays
Acknowledgements
Useful Links
Questions?

Details of patching the kernel

I’ve compiled and used this with version 2.4.20 (the latest stable release) of the Linux kernel, which you can download at www.kernel.org. If you want to work with an earlier version, that’s fine; be aware that you’ll need a recent ftdi_sio.c & and ftdi_sio.h (mentioned below).

In linux-2.4.20/drivers/usb/serial/, there are two files that need to be changed to add the vendor and product IDs in use by the serial displays: ftdi_sio.c and ftdi_sio.h. The files are the serial drivers for FTDI’s 8U232AM chips, which are apparently pretty close to the FT232BM chips that Matrix Orbital is using on the USB chips.

I chose to have all the USB support be modular, but you may wish to compile it in so you don’t have to worry about inserting modules when you need it. You may which to include hotplug-ability, for it will load up the drivers for you if the drivers are modular. If you don’t know what I mean, now’s the time to pick up the Linux book to learn how to navigate the menu system for choosing options in the kernel.

The actual details of the patch are as follows:

--- ftdi_sio.h 2003-01-30 19:32:56.000000000 -0500

+++ /home/wayne/linux-2.4.20/drivers/usb/serial/ftdi_sio.h 2002-11-28 18:53:14.000000000 -0500

@@ -25,19 +25,6 @@

#define FTDI_NF_RIC_VID 0x0DCD /* Vendor Id */

#define FTDI_NF_RIC_PID 0x0001 /* Product Id */

-/*

- * The following are the values for the Matrix Orbital LCD displays,

- * which are the FT232BM ( similar to the 8U232AM )

- */

-#define FTDI_MTXORB_VID FTDI_VID /* Matrix Orbital Product Id */

-#define FTDI_MTXORB_0_PID 0xFA00 /* Matrix Orbital Product Id */

-#define FTDI_MTXORB_1_PID 0xFA01 /* Matrix Orbital Product Id */

-#define FTDI_MTXORB_2_PID 0xFA02 /* Matrix Orbital Product Id */

-#define FTDI_MTXORB_3_PID 0xFA03 /* Matrix Orbital Product Id */

-#define FTDI_MTXORB_4_PID 0xFA04 /* Matrix Orbital Product Id */

-#define FTDI_MTXORB_5_PID 0xFA05 /* Matrix Orbital Product Id */

-#define FTDI_MTXORB_6_PID 0xFA06 /* Matrix Orbital Product Id */

#define FTDI_SIO_RESET 0 /* Reset the port */

#define FTDI_SIO_MODEM_CTRL 1 /* Set the modem control register */

#define FTDI_SIO_SET_FLOW_CTRL 2 /* Set flow control register */

--- ftdi_sio.c 2003-01-30 19:33:36.000000000 -0500

+++ /home/wayne/linux-2.4.20/drivers/usb/serial/ftdi_sio.c 2002-11-28 18:53:14.000000000 -0500

@@ -154,13 +154,6 @@

static struct usb_device_id id_table_8U232AM [] = {

{ USB_DEVICE(FTDI_VID, FTDI_8U232AM_PID) },

{ USB_DEVICE(FTDI_NF_RIC_VID, FTDI_NF_RIC_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_0_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_1_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_2_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_3_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_4_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_5_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_6_PID) },

{ } /* Terminating entry */

};

@@ -169,13 +162,6 @@

{ USB_DEVICE(FTDI_VID, FTDI_SIO_PID) },

{ USB_DEVICE(FTDI_VID, FTDI_8U232AM_PID) },

{ USB_DEVICE(FTDI_NF_RIC_VID, FTDI_NF_RIC_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_0_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_1_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_2_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_3_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_4_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_5_PID) },

- { USB_DEVICE(FTDI_MTXORB_VID, FTDI_MTXORB_6_PID) },

{ } /* Terminating entry */

};

In short, the steps to build the kernel are:

make menuconfig (to select the parts of the kernel you want)
make dep bzImage modules
make modules_install
make install

I had to change /boot/grub/grub.conf so that I can explicitly pass /dev/hda2 as the root to the kernel.

After you successfully reboot, the drivers may not be loaded if chose them to be built as modules. Issue a

/sbin/modprobe ftd_sio

and check /var/log/messages to see if driver was indeed loaded. As I mentioned above, if you choose hotplug-ability, the modular drivers will be loaded for you.

If this is the FIRST USB serial device on your system, it will be installed as /dev/ttyUSB0; if it was the second, it would be /dev/ttyUSB1 and so on. Use minicom or MatrixOrbital’s ex2.pl script to test out communication with the USB.

Using LCDProc with the USB display

Getting LCDProc to use the USB display is easy. If the ftdi_sio module is loaded, then all you need to do is change LCDd.conf to refer to the specific serial port (i.e., /dev/ttyUSB0). Of course, there are other parameters that need to be set, such as the driver, the size of the display and the contrast, but the INSTALL document that comes with LCDProc should explain what you will need to do to configure LCDProc.

What has been tested

I have tested the use of lcdproc client program and found it work well with the new module with several days of continuous use.

What has NOT been tested

Anything having to do with the general purpose outputs, or the use of any keypad (yet; one is on its way).

To Do: Hot pluggable LCD displays

The latest version of the kernel can dynamically bring in and out device drivers when a new device is hooked up via USB. With the scripts from the Linux Hotplugging Project at SourceForge, even applications can be started when the device is plugged in. I’m going to try to get LCDproc to start-up automatically when the USB display is plugged in.

Acknowledgements

I needed help from the following gracious people:

The Matrix Orbital folks, especially Henry J has been kind enough to answer my questions and give me a sample to work with.
The LCDProc folk, especially David Glaude who helped me get set up with this project.
The people who wrote and supported the ftdi_sio driver within the Linux kernel.
My wife, who thinks I‘m crazy, but she benefits from all of my projects (well, almost all of my projects…)

I had fun. Now it’s your turn.

Useful Links

Here are some links to recourses that I found handy:

The Matrix Orbital display’s manual: http://www.matrixorbital.com/pdfs/LK202-24-USB_01.pdf
The FTD_SIO Driver Project http://ftdi-usb-sio.sourceforge.net/
Linux-USB resource center: http://www.linux-usb.org/
Linux HotPlug Project: http://linux-hotplug.sourceforge.net/
The Kernel itself (reading the source was fun!): http://www.kernel.org/
FTDI web site: http://www.ftdichip.com/
Usbview ( for Gnome; it was handy ); http://www.kroah.com/linux-usb/

Questions?

For questions, please send mail to projects@webBastards.com

Wayne Wylupski