libusblcd SDK developer guide ============================== Usblcd and libusblcd are (c) 2006 iTuner Networks and Mini-Box.Com and distributed under the terms of the GNU General Public License. See the file ./COPYING in the source distribution for more information. Please send bug reports to Introduction ------------- Libusblcd implements the basic communication with the USB LCD device. It relies on libusb for raw usb data and libhid as a framework for hid devices. Future version might remove libhid dependency. Requirements ------------ Libusblcd doesn't require any kernel drivers except basic USB drivers and can run on both 2.4.x and 2.6.x kernel versions. It relies on libusb (http://libusb.sourceforge.net) and libhid (libhid.alioth.debian.org). Also usbfs filesystem must be mounted (by default on all linux distributions). You can mount usbfs by executing the command: mount -t usbfs usbfs /proc/bus/usb To verify if usb is working corectly on your distribution execute: lsusb or lsusb -v which should list the usb devices that are connected to your computer like in the exemple below Bus 003 Device 001: ID 0000:0000 Bus 002 Device 003: ID 04d8:0002 Microchip Technology, Inc. Bus 002 Device 002: ID 046d:c01e Logitech, Inc. Bus 002 Device 001: ID 0000:0000 Bus 001 Device 001: ID 0000:0000 Using libusblcd --------------- A minimal program that inits the usb lcd and sets the backlight on looks like this: #include int main(void) { usblcd_operation *mylcd; /* init hid device and usblcd_operations structure */ mylcd = new_usblcd_operations(); /* init the USB LCD */ mylcd->init(mylcd); /* sets backlight to on */ mylcd->backlight(mylcd,1); /* close the USB LCD device */ mylcd->close(mylcd); return 0; } mylcd is a pointer of usblcd_operation type. This structure contains all the functions needed to work with the USB LCD device. The structure must be initialised by using: mylcd = new_usblcd_operations(); After this all operation are accessible by: mylcd->function(mylcd, params....) Initialising usblcd_operations also initialise the hid communication with the device. usblcd_operations structure also contains the function and variables that directly work with HID devices. These can be accessed by using mylcd->hid->hid_interrupt_read(mylcd, params...) Basic usb lcd functions ======================= mylcd->match(char *string) This function can alter the default detection of LCD device by providing a different matching string. mylcd->init(usblcd_operations *self) This function will send the functional parameters to USB LCD. Note that HID initialisation and USB LCD communication is already opened when usblcd_operation struct was initialised by using: mylcd = new_usblcd_operations(); mylcd->debug(int level) ------------------------- This allow to set the debug level of messages visible on console. mylcd->setled(usblcd_operations *self, unsigned int led, unsigned int status); -------------------------------------------------------------------------- This function will open/close the specified led. mylcd->backlight(usblcd_operations *self, unsigned int status) --------------------------------------------------------------- Sets backlight on or off. mylcd->contrast(usblcd_operations *self, unsigned int level); -------------------------------------------------------------- Sets contrast of the lcd screen with values between 0 and 40. mylcd->set_cursor(usblcd_operations *self, unsigned int status); ---------------------------------------------------------------- Shows or hides the cursor. mylcd->set_cursor_blink(usblcd_operations *self, unsigned int status); ----------------------------------------------------------------------- Sets or unsets cursor blink status. mylcd->set_switch(usblcd_operations *self, unsigned int status); ---------------------------------------------------------------- Allows LCD screen to be switched off or on. mylcd->read_events(usblcd_operations *self); -------------------------------------------- This function will read any event available and output it on stderr. mylcd->enter_flasher_mode(usblcd_operations *self); --------------------------------------------------- Puts the device in flasher mode of operation. mylcd->exit_flasher_mode(usblcd_operations *self); --------------------------------------------------- Returns the device to keyboard mode of operation. mylcd->clear(usblcd_operations *self); --------------------------------------- Clears the lcd screen. mylcd->settext(usblcd_operations *self, unsigned int row, unsigned int column, char *text); ------------------------------------------------------------------------------------------- Writes the specified text to LCD screen on specified row and column. mylcd->setfont(usblcd_operations *self, char *filename); -------------------------------------------------------- Write the characters defined in filename to CG-RAM of the LCD device. mylcd->setsplash(usblcd_operations *self, char *filename); ---------------------------------------------------------- Write the splash screen data from filename into the LCD device EEPROM. See usblcd documentation for splash file format. mylcd->flash(usblcd_operations *self, char *filename); ------------------------------------------------------ Write the firmware from filename into LCD EEPROM. mylcd->getversion(usblcd_operations *self); ------------------------------------------- This function should return USB LCD version and it's also used to clear the message queue of LCD device. mylcd->close(usblcd_operations *self); -------------------------------------- Shutsdown USB LCD and HID communication and frees the memory occupied. mylcd->powerstate(usblcd_operations *self); ------------------------------------------- Get the power button status from LCD device. Not implemented yet. mylcd->keystate(usblcd_operations *self); ----------------------------------------- Returns the last keypresses. Not implemeted yet use read_events function. mylcd->irdata(usblcd_operations *self); --------------------------------------- Returns the last IR data received. Not implemented yet use read_events function. Basic HID functions =================== These functions are presented here as a reference. They shouldn't be called directly since all operations are made thru usblcd functions presented above. As usblcd functions hid functions are initialised by calling new_hid_operations and the structure holding them is hid_operations. mylcd->hid->hid_id hid_id is the device id returned by calling hid->init. hid_id is allocated when new_usblcd_operations or new_hid_operations are called. mylcd->hid->debug(int level); Sets the level of HID messages on console. mylcd->hid->init(HIDInterface **hid_id); Initialises the HID communication with the lcd device. This is already done when calling new_usb_operations. mylcd->hid->interrupt_read(void *hid_id, hid_params *params); Attempts to execute a interrupt read from the device specified by hid_id. mylcd->hid->interrupt_write(void *hid_id, hid_params *params); Attempts to execute a interrupt write to the device specified by hid_id. mylcd->hid->close(void *hid_id); Closes the HID communications and frees the data structures used. For more examples see the source of libusblcd and usblcd application.