Parallel Text-based LCM
Implementation Manual
March 16, 2015
Version: 1.0.1
Revision History
Version
1.0.0
1.0.1
Date
11/27/2014
03/16/2015
Changes
Initial release
Apply the new template
This document contains proprietary information of Lanner Electronics Inc. –and is not to be
disclosed or used except in accordance with applicable agreements.
Copyright © 2015. All Rights Reserved.
Copyright© 2015 Lanner Electronics Inc. All rights reserved. The information in this document is
proprietary and confidential to Lanner Electronics Inc. No part of this document may be reproduced in
any form or by any means or used to make any derivative work (such as translation, transformation, or
adaptation) without the express written consent of Lanner Electronics Inc. Lanner Electronics Inc.
reserves the right to revise this document and to make changes in content from time to time without
obligation on the part of Lanner Electronics Inc. to provide notification of such revision or change.
The information in this document is furnished for informational use only, is subject to change without
notice, and should not be construed as a commitment by Lanner Electronics Inc. Lanner Electronics
Inc. assumes no responsibility or liability for any errors or inaccuracies that may appear in this
document or any software that may be provided in association with this document.
ii
Table of Contents
Revision History .......................................................................................ii
TABLE OF CONTENTS .............................................................................. III
ABOUT THIS DOCUMENT...........................................................................IV
PURPOSE ............................................................................................. IV
INTENDED AUDIENCE ................................................................................. IV
CONVENTIONS USED ................................................................................. IV
CHAPTER 1. INTRODUCTION ...................................................................... 2
1.1 OVERVIEW OF LANNER LCM .................................................................... 2
CHAPTER 2. BUILDING AND INSTALLING THE PROGRAM .................................... 3
2.1 BUILD PARALLEL TEXT-BASED LCM............................................................ 3
2.2 INSTALL THE DRIVER FOR PARALLEL TEXT-BASED LCM ........................................ 5
CHAPTER 3. EXECUTING THE SAMPLE PROGRAM ............................................ 6
3.1 PLCM_TEST ...................................................................................... 6
3.1.1 Corresponding Commands for plcm_test functions............................... 9
3.2 PLCM_CURSOR_CHAR .......................................................................... 11
3.3 TEST............................................................................................ 13
CHAPTER 4. LCM CONTROL FUNCTIONS ...................................................... 14
4.1 REQUEST CODES FOR PARALLEL TEXT-BASED LCM .......................................... 14
CHAPTER 5. VIRTUALIZATION IMPLEMENTED BY PARALLEL PORT PASS THROUGH .. 16
5.1 USING VIRTUALIZATION ON LINUX .............................................................. 16
5.2 EXECUTING THE SAMPLE PROGRAM ............................................................ 20
5.2.1 ppdev_test .............................................................................. 20
5.2.2 Corresponding Commands for ppdev_test functions ............................ 23
APPENDIX A - - - FILES FUNCTION DESCRIPTION OF THE PROGRAM PACKAGE ..... 25
iii
About this Document
Purpose
The purpose of this document is to provide implementation information for Lanner Parallel
Text-based LCM functionalities.
Intended Audience
This document is for individuals who install and configure networking appliances with the
above mentioned functionality.
Conventions Used
Followings are all the special characters and typographical conventions used in this manual:
Convention
Press Enter
Meaning
Means press the Enter or Return key or its
equivalent on your computer.
Note: introduces important additional information.
Caution: warns that a failure to follow the
recommended procedure could result in loss of
data or damage to equipment.
iv
v
About this user’s manual
In this user’s manual, it will not only tell you how to correctly build the Parallel Text-based LCM
step-by-step but many explanation of sample program tests as well as the related illustrations are
also shown in both virtualization and non-virtualization environment.
Overview of this user’s manual
Chapter 1 “Introduction” describes the features of Parallel Text-based LCM
Chapter 2 “Building and Installing the Program”
Chapter 3 “Executing the Sample Program”
Chapter 4 “LCM Control Functions”
Chapter 5 “Virtualization Implemented by Parallel Port Pass Through”
Publication date: March 16, 2015
Revision 1.0.1
1
Introduction
1
Introduction
1.1 Overview of Lanner LCM
Lanner 's LCM (LCD Message Display Module) is a general purpose message display which can be
programmed to display certain messages. For different connector interfaces, our LCM supports 4
different types, including Parallel Text-based LCM, Parallel Graphic-based LCM, Serial Text-based
LCM as well as USB and Serial Text or Graphic-based LCM. A software development kit contained
in each LCM helps system designers efficiently design the system to support LCM functionality.
Among all of the LCMs we had mentioned above, the Parallel Text-based LCM connects to the
parallel port of the motherboard. The LCD screen can display 2 lines, 16 (or 20) characters per line.
In the environment of virtualization, furthermore, the Parallel Text-based LCM also can be
implemented. For more details on other LCMs, please refer to the related manual.
Publication date: March 16, 2015
Revision 1.0.1
2
Building and Installing the Program
2
Building and Installing
the Program
2.1 Build Parallel Text-based LCM
To build program source code on Linux platform, please use the following steps as a guideline:
1.
Extract the source file:
# tar -xzvf plcm_drv_v0XX.tgz
(0XX is the version of the program.)
2.
Change directory to the extracted folder:
# cd plcm_drv_v0XX
(0XX is the version of the program.)
Note: Apply our Parallel Text-based LCM to the environment of virtualization, please
use the version 013 or above of the program. To realize the implementation
methods of virtualization by parallel port pass through, you can see Chapter 5.
3.
Type make to build source code:
# make
After compiling, the executable programs (plcm_test, plcm_cursor_char,
ppdev_test, Test) and the driver (plcm_drv.ko) will appear in the program’s folder.
For further information of these files, please read Appendix A “Files Function
Description of the Program Package”.
Publication date: March 16, 2015
Revision 1.0.1
3
Building and Installing the Program
Note: The OS supported by Parallel Text-based LCM function includes platforms
based on Linux Kernel series 2.4.x, Linux Kernel series 2.6.x and Linux Kernel
series 3.0.x or above.
Publication date: March 16, 2015
Revision 1.0.1
4
Building and Installing the Program
2.2 Install the Driver for Parallel Text-based LCM
Install the driver and create a node in the /dev directory by:
1.
# insmod plcm_drv.ko (refer to *)
2.
# mknod /dev/plcm_drv c 248 0 (refer to **)
Note:
*:
**:
Once the message of “insmod: error inserting 'plcm_drv.ko': -1 Input/output
error” appears, please check that whether the major number is repeated or
not.
The major number needed with the mknod command varies with different
software versions; please look up the Readme file for this value.
Publication date: March 16, 2015
Revision 1.0.1
5
Executing the Sample Program
3
Executing the Sample
Program
This chapter contains sample executable programs that you could test on your platform.
It demonstrates some useful functionality that the LCM provides. Note that the installation needs to
be completed before proceeding with these executions.
3.1 plcm_test
Run the command below for testing the Parallel Text-based LCM functions.
#./plcm_test
Then, this program will run through the following functions in sequence:
—
Backlight Off/On (turning off/on the backlight of the LCM display, see the figures
below)
Backlight Off
Backlight On
Publication date: March 16, 2015
Revision 1.0.1
6
Executing the Sample Program
—
Display Off (turning off the LCM display, see the figure below)
Display Off
—
Cursor Off/On (NOT showing/showing the cursor on the LCM display, see the figures
below)
Cursor Off
—
Cursor On
Blinking off/On (turning off/on the cursor blinking, see the figures below)
Blinking Off
—
Blinking On
Writing “Lanner@Taiwan” (displaying the specific sentences, see the figure below)
Writing
Publication date: March 16, 2015
Revision 1.0.1
7
Executing the Sample Program
—
Reading Lanner@Taiwan (reading the specific sentence, see the figure below)
Reading
—
CGram Test (displaying the user-stored characters, see the figure below)
CGram Test
—
Keypad Testing (Get the keypad input: the 1st button is read in as Left, the 2nd button
is read in as Up, the 3rd button is read in as Right, and the 4th button is read in as
Down)
Left
Up
Right
Down
Publication date: March 16, 2015
Revision 1.0.1
8
Executing the Sample Program
3.1.1 Corresponding Commands for plcm_test functions
Instead of using this plcm_test executable program to test the LCM with a series of functions, you
can directly input the specific command to have its corresponding function worked on your LCM.
This will be much more convenient once you would like to merely execute the Keypad Testing, for
example, among all functions as we had mentioned in Section 3.1. All of these corresponding
commands provided by our LCM for plcm_test are shown as Table 3-1.
Description of
Command
Options
—
-On
Figure of
LCM Display
Turn on the backlight of the LCM
display.
—
To execute, please type:
#./plcm_test -On
—
-Off
Turn off the backlight of the LCM
display.
—
To execute, please type:
#./plcm_test -Off
—
Writing “Lanner@Taiwan” in line1.
-LCM1
—
-LCM2
—
—
To execute, please type:
#./plcm_test -LCM1
Writing “2013-11-05” in line 2.
To execute, please type:
#./plcm_test -LCM2
Publication date: March 16, 2015
Revision 1.0.1
9
Executing the Sample Program
Left
—
Get the keypad input: the 1st button
is read in as Left, the 2nd button is
read in as Up, the 3rd button is read
-Keypad
in as Right, and the 4th button is
Up
read in as Down.
—
To execute, please type:
#./plcm_test -Keypad
Right
Down
Table 3-1
Publication date: March 16, 2015
Revision 1.0.1
10
Executing the Sample Program
3.2 plcm_cursor_char
Run the command below for cursor shift & single text update.
# ./plcm_cursor_char
Then, this program will provide the following menu to interact with you. Input 1~6 to choose the
desired item from available options.
Each option of this menu is described below:
—
Insert line (select Item 1 to set the starting line as either line 1 or line 2, see the
figures below)
Line 1
—
Line 2
Move cursor right (select Item 2 to move the cursor to the right, see the figure below)
The cursor is moved to the
right side
Publication date: March 16, 2015
Revision 1.0.1
11
Executing the Sample Program
—
Move cursor left (select Item 3 to move the cursor to the left, see the figure below)
The cursor is moved to the left
side
—
Add a char (select Item 4 to display a character on the LCM screen, see the figure
below)
Display the inputted chars
—
Clean display (select Item 5 to clear up the LCM display, see the figure below)
Clear up the display
—
Leave (select Item 6 to exit the program, see the figure below)
Publication date: March 16, 2015
Revision 1.0.1
12
Executing the Sample Program
3.3 Test
This program is a testing script and runs through the following procedures in sequence:
—
rmmod plcm_drv (remove the kernel mode driver module)
—
insmod plcm_drv.ko(install the kernel mode driver module)
—
./plcm_test(execute the driver testing program)
—
./plcm_test -stop(stop executing the driver testing program)
—
rmmod plcm_drv(remove the kernel mode driver module)
To execute, please type:
#./Test
Publication date: March 16, 2015
Revision 1.0.1
13
LCM Control Functions
4
LCM Control Functions
4.1 Request Codes for Parallel Text-based LCM
Lanner provides device-dependent request codes in PLCM driver that you can use within your
program to control the LCM. To use these request codes, simply include the “plcm_ioctl.h” file in
your program. And use the function ioctl to call these codes.
For example,
ioctl (user_defined driver pointer, PLCM_IOCTL_BACKLIGHT, 1)
For more details on these request codes, please refer to Table 4-1.
Request codes
Description
Description of Value
PLCM_IOCTL_
BACKLIGHT
Turn on/off the backlight
“1” stands for “Backlight On”
“0” stands for “Backlight Off”
PLCM_IOCTL_SET_
LINE
Set the cursor on the destined
line
“1” stands for “Line 1”
“2” stands for “ Line 2”
PLCM_IOCTL_
CLEARDISPLAY
Clear all display on the LCM
screen
PLCM_IOCTL_
RETURNHOME
Set cursor to the position of line
one and character one (Home
position)
Publication date: March 16, 2015
Revision 1.0.1
14
LCM Control Functions
PLCM_IOCTL_
ENTRYMODE_ID
“1” stands that LCM cursor will be
shifted right when writing
Set cursor to move to either left
or right when entering a character “0” stands that LCM cursor will be
shifted left when writing
PLCM_IOCTL_
ENTRYMODE_SH
Shift the LCM screen for more
display
PLCM_IOCTL_
DISPLAY_D
LCM display on/off
PLCM_IOCTL_
DISPLAY_C
LCM cursor on/off
PLCM_IOCTL_
DISPLAY_B
LCM cursor blinking on/off
PLCM_IOCTL_
SHIFT_SC
Make the LCM screen shift or
cursor shift
PLCM_IOCTL_
SHIFT_RL
Control LCM cursor to shift right
or left
PLCM_IOCTL_
GET_KEYPAD
Get the keypad input
PLCM_IOCTL_
INPUT_CHAR
Display a character on the LCM
screen
“1”stands that the current LCM screen
is shifted.
“0” stands that LCM screen is stayed
on.
“1” stands for “Display On”
“0” stands for “Display Off”
“1” stands for “Cursor On”
“0” stands for “Cursor Off”
“1” stands for “Blinking On”
Table 4-1
Publication date: March 16, 2015
Revision 1.0.1
15
“0” stands for “Blinking Off”
“1” stands for “Screen Shift”
“0” stands for “Cursor Shift”
“1” stands for “Cursor Shift Right”
“0” stands for “Cursor Shift Left”
Virtualization Implemented by Parallel Port Pass Through
5
Virtualization
Implemented by Parallel Port
Pass Through
5.1 Using Virtualization on Linux
By the utilization of the parallel port pass through, the Parallel Text-based LCM implements the
following three kinds of virtualization in the Guest OS.
QEMU/KVM
Xen
VMWare Player
Here, we take the Fedora 20 x86_64 operation system for instance to explain 3 virtualization
respectively for parallel port pass through. Use the procedures listed below for step-by-step
instructions separately based on your case.
Publication date: March 16, 2015
Revision 1.0.1
16
Virtualization Implemented by Parallel Port Pass Through
In case of QEMU/KVM or Xen, please use the following steps as a guideline to implement
the virtualization :
(1) Make sure that the Guest OS has been installed.
(2) Add the following 4 lines into the xml file (for example, add to
/etc/libvirt/qemu/<yourvirtualmachine>.xml in linux KVM) :
<parallel type='dev'>
<source path='/dev/parport0'/>
<target port='0'/>
</parallel>
(3) Open a terminal in the Guest OS and then issue the following commands to install linux
kernel drivers.
# modprobe parport
# modprobe parport_pc
# modprobe ppdev
(4) Check that whether the /dev/parport0 exists or not. You may not find proper /dev/parport0
in the device list, please reconfirm the setup of xml file in the Guest OS.
(5) Reboot the Guest OS.
Note: It is necessary for you to insmod parport.ko, parport_pc.ko and ppdev.ko
linux kernel drivers in virtualization environment before executing the
ppdev_test testing program.
Publication date: March 16, 2015
Revision 1.0.1
17
Virtualization Implemented by Parallel Port Pass Through
In case of VMWare Player, please use the following steps as a guideline to implement the
virtualization:
(1) Make sure that the Guest OS has been installed.
(2) To set up the parallel port pass through, please enter VMWare Player→Virtual Machine
Setting→VMWare Player's setting page to select /dev/parport0 as parallel port device.(See
the figure below)
(3) Open a terminal in the Guest OS and then issue the following commands to install linux
kernel drivers.
# modprobe parport
# modprobe parport_pc
# modprobe ppdev
Publication date: March 16, 2015
Revision 1.0.1
18
Virtualization Implemented by Parallel Port Pass Through
(4) Check that whether the /dev/parport0 exists or not. You may not find proper /dev/parport0
in the device list, please reconfirm the setup of VMWare Player's setting page described in
Step 2.
(5) Reboot the Guest OS.
Note: It is still necessary for you to insmod parport.ko, parport_pc.ko and
ppdev.ko linux kernel drivers in virtualization environment before
executing the ppdev_test testing program.
Publication date: March 16, 2015
Revision 1.0.1
19
Virtualization Implemented by Parallel Port Pass Through
5.2 Executing the Sample Program
This section contains sample executable program that you could test on your Guest OS in
virtualization environment. It demonstrates some useful functionality that the LCM provides. Note
that the installation needs to be completed before proceeding with these executions.
5.2.1 ppdev_test
Copy the file of “plcm_drv_v0XX.tgz” to the Guest OS, and issue the following commands to
compile. Make sure that the program you use is version 013 or above.
# tar -xzvf plcm_drv_v0XX.tgz
(0XX is the version of the program.)
# cd plcm_drv_v0XX
(0XX is the version of the program.)
# make
After compiling, run the command below in the Guest OS for testing the Parallel Text-based LCM
functions.
# ./ppdev_test
Then, this program will run through the following functions in sequence.
—
Backlight Off/On (turning off/on the backlight of the LCM display, see the figures
below)
Backlight Off
—
Backlight On
Display Off (turning off the LCM display, see the figure below)
Display Off
Publication date: March 16, 2015
Revision 1.0.1
20
Virtualization Implemented by Parallel Port Pass Through
—
Cursor Off/On (NOT showing/showing the cursor on the LCM display, see the figures
below)
Cursor Off
—
Cursor On
Blinking off/On (turning off/on the cursor blinking, see the figures below)
Blinking Off
—
Blinking On
Writing Lanner@Taiwan (displaying the specific sentences, see the figure below)
Writing
—
Reading Lanner@Taiwan (reading the specific sentence, see the figure below)
Reading
Publication date: March 16, 2015
Revision 1.0.1
21
Virtualization Implemented by Parallel Port Pass Through
—
CGram Test (displaying the user-stored characters, see the figure below)
CGram Test
—
Keypad Testing (Get the keypad input: the 1st button is read in as Left, the 2nd button
is read in as Up, the 3rd button is read in as Right, and the 4th button is read in as
Down)
Left
Up
Right
Down
Publication date: March 16, 2015
Revision 1.0.1
22
Virtualization Implemented by Parallel Port Pass Through
5.2.2 Corresponding Commands for ppdev_test functions
Like the plcm_test executable program, you can directly input the specific command to have the
corresponding function of ppdev_test worked on your LCM. This will be much more convenient once
you would like to merely execute the Keypad Testing, for example, among all functions as we had
mentioned in Section 5.2. All of these corresponding commands provided by our LCM for
ppdev_test are shown as Table 5-1.
Description of
Command
Options
—
-On
Figure of
LCM Display
Turn on the backlight of the LCM
display.
—
To execute, please type:
#./ppdev_test -On
—
-Off
Turn off the backlight of the LCM
display.
—
To execute, please type:
#./ppdev_test -Off
-LCM1
-LCM2
—
Writing “Lanner@Taiwan” in line1.
—
To execute, please type:
#./ppdev_test -LCM1
—
Writing “2013-11-05” in line 2.
—
To execute, please type:
#./ppdev_test -LCM2
Publication date: March 16, 2015
Revision 1.0.1
23
Virtualization Implemented by Parallel Port Pass Through
Left
—
-Keypad
—
Get the keypad input: the 1st button
is read in as Left, the 2nd button is
read in as Up, the 3rd button is read
in as Right, and the 4th button is
read in as Down.
Up
To execute, please type:
#./ppdev_test -Keypad
Right
Down
Table 5-1
Publication date: March 16, 2015
Revision 1.0.1
24
Appendix A
Appendix A - - - Files Function
Description of the Program Package
To get the correct usage of Parallel Text-based LCM, we suggest that you can read this section in
order to have a clear understanding of the executable programs (plcm_test, plcm_cursor_char,
ppdev_test, Test) and the driver (plcm_drv.ko) before operating it. Also refer to Chapter 3 and
Chapter 5 to know how the former files work in our Parallel Text-based LCM.
plcm_drv.ko
— The driver module of Kernel mode.
plcm_test
— User mode driver testing program developed by Lanner.
— Able to be used to test LCM in the non-virtualization environment.
Note: Between testing programs of plcm_test and ppdev_test that will be described
below, it is highly recommended that you can use the former to do the test in the
non-virtualization environment.
plcm_cursor_char
— Driver testing program for cursor shift & single text update of User mode.
ppdev_test
— Linux kernel standard driver testing program of User mode.
— parport.ko, parport_pc.ko and ppdev.ko these three linux kernel drivers need to be loaded
before running this ppdev_test file.
— Able to be used to test LCM in both virtualization and non-virtualization environment.
Test
— The testing script of User mode.
Publication date: March 16, 2015
Revision 1.0.1
25
Lanner Electronics Inc.
7F, No.173, Sec.2, Datong Rd.
XiZhi District, New Taipei City 221, Taiwan
Tel: +886-2-86926060
Fax: +886-2-86926103
www.lannerinc.com