RE: [lcd4linux] Revisisted > Help > Using LCD4Linux on Toshiba Magnia SG-20

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Hi.  Here's some additional information about the LCD Display for the =
Toshiba Magnia SG-20.
=20
--- Simon.
=20
=20
=20
=20
LCD Panel Customization        =
<http://www.sos-spa.it/software/Immagine%20SG20/Magnia%20SG20%20General%2=
0Customization%20Guide.doc#B0000002> =20
=20

The Toshiba Magnia SG20 contains a built-in, easy to read and use LCD =
panel.  This display is normally used to present information to the user =
concerning the system status and operations.  Messages include items =
such as:=20

=09
*	Boot and shutdown progress=20
*	Backup / restore progress=20
*	Networking operations=20
*	Health alerts=20

The LCD panel and the items it displays are controlled by the internal =
operating system of the SG20.  Because the internal software controls =
the LCD panel, it is easy to add and modify what it displays.  No =
modifications to the system firmware are required.=20

This section covers a general description of the LCD panel operation, =
its interface, the software controlling message display, and how to =
display information on the panel directly without using the Magnia SG20 =
provided software.  There are two methods to interact with the Magnia =
SG20 LCD panel.  When using the Magnia SG20 preinstalled software, =
interaction with the LCD panel is direct, through the LCD daemon.  If =
using your own software preinstall image that does not include the =
Magnia SG20 software for LCD management, you can create your own =
programs and procedures to interact with the LCD panel and the system =
buttons.

LCD Interface Technical Overview

The Magnia SG20 contains two main boards.  The PC motherboard contains =
most of the controllers and interfaces normally associated with a PC, =
including the CPU, IDE controllers, serial and parallel port =
controllers, etc.  A second board, the mezzanine board, contains some =
additional components such as the internal built in Ethernet switch and =
the system LCD firmware.=20
=20
Communications to the LCD display are transmitted from the operating =
system software running on the main system board through the COM1 serial =
port.  The LCD controller firmware listens to the serial port and =
displays most characters sent through this serial port.=20

The LCD panel display is a two-line display.  Each line can display up =
to 16 characters.  =20

In addition to display and control of the LCD panel, the LCD firmware =
monitors and reports the button presses of the LCD select button and the =
soft power button, both located on the front of the Magnia SG20.

LCD Panel Direct Access=20

It is possible to interact directly with the Magnia SG20 LCD panel =
without using the supplied LCD control software.  This can be useful =
when a different operating system has been loaded on the SG20 (such as a =
generic Linux system, or DOS).=20

Please note that the techniques described in this section are for use on =
operating systems other than the one normally supplied with the Magnia =
SG20 by Toshiba.  The standard Magnia SG20 software contains a Linux =
daemon that controls and monitors the LCD and system buttons.  =
Therefore, attempts to control the LCD panel or receive button press =
information on the standard Magnia SG20 operating system installation =
will conflict with the LCD control daemon.

Direct LCD message display

Because characters sent to the LCD COM1 port are automatically displayed =
on the LCD screen, it is very easy to display your own messages.  For =
example, on DOS, the command:

	echo =93Hello World=94 > COM1=20
=09

Will cause the characters =93Hello World=94 to appear on the LCD panel.  =
The equivalen Linux command is:

	echo =93hello world=94 > /dev/ttyS0=20
=09

More complicated strings, controlling wrapping on the two LCD lines and =
spacing are available.  The following table shows the characters that =
are accepted for printing and formatting as part of the message text on =
the LCD panel.=20

	Received Character

	Name

	Operation

	 =09
	=91A=92-Z=92, =91a=92-=91z=92, =910-9=92

	ASCII printable code.

	Display character at the current cursor position and advance cursor to =
the next location. Scroll line as needed.

	 =09
	SP =3D =91 =91

	Space char

	Advance the cursor to the next cursor position and scroll as needed.

	 =09
	NL :=3D =91\n=92

	Newline=20

	Advance the cursor to the next line, scrolling as needed.

	 =09
	CR :=3D =91\r=92

	Carriage return

	Return the cursor to the first column on the current row.

	 =09
	ESC

	Escape

	Prepare for the next received char as a command code.

	 =09

=20

LCD Control Codes

In addition to direct transmission of characters to the LCD, there are =
several special command sequences that can be sent to the LCD =
controller.  These sequences are designed to ease formatting and =
manipulation of the LCD display.  All command sequences begin with the =
escape character, and are following by a character indicating a specific =
action.=20

The table below shows the available escape command sequences and their =
use.=20

Received Character

Name

Operation

=91H=92

 	 Home the cursor.

=91X=92

 	 Clear the display.

=91B=92

 	 Turn on backlight

=91b=92

 	 Turn off backlight

<sec>=91q=92

 	 Power down the system in <sec> seconds. Should only be sent at end of =
shutdown sequence.

Examples of the use of these commands appear below:=20

To send the LCD cursor to the top row, far left character position:

	echo =96n =96e =93\033H=94 > /dev/ttyS0=20
=09

To clear the LCD display:

	echo =96n =96e =93\033X=94 > /dev/ttyS0=20
=09

To turn off the backlight of the LCD display:

	echo =96n =96e =93\033b=94 > /dev/ttyS0=20
=09

To shut the power of the system off in 10 seconds:

	echo =96n =96e =93\03310q=94 > /dev/ttyS0=20
=09

Please note that issuance of the power off command illustrated above =
should not be issued unless the operating system is being shut down in =
an orderly manner. Sufficient time should be given for the OS to =
complete its shutdown procedures.

Button Status Codes

The LCD controller also monitors and reports whenever one of the control =
buttons on the Magnia SG20 is pressed.  These buttons include the LCD =
scroll button located directly adjacent to the LCD panel and the power =
down button located on the front of the Magnia SG20 and to the right of =
the LCD panel.=20

Button status information is sent in on the internal COM1 port.=20

Status values sent across the COM1 port are listed below.  No preceding =
escape or other characters are sent from the LCD controller to the =
motherboard.=20

	Transmitted Character

	Name

	Operation

	=91P=92

	Power

	Power button pressed.

	=91S=92

	Select

	Select button pressed.

Because these characters are sent across the COM1 port without a CR/LF, =
it may be necessary to write specific code to monitor the incoming =
characters.  This code should place the device in a raw mode in order to =
receive characters as soon as they are sent, so that they are not =
buffered.  While this can be accomplished using command line level =
instructions, it is significantly better to write a program to monitor =
and process these commands.=20

While command / shell scripts can be used to send information to the LCD =
for display with ease, monitoring and responding to button commands is =
best handled in a program specifically written for the purpose.

Magnia SG20 Queued LCD Message Interface

If you wish to add custom LCD messages when using a Toshiba Magnia SG20 =
preinstall, you need to integrate your messaging in to the internal =
messaging management system.  The internal queuing system manages the =
display of LCD messages, their positioning, translation and cycling =
through the multiple messages available for display using the LCD scroll =
button.=20

There is an LCD/KBD Daemon (LCDKBD) used to coordinate client =
application access to the LCD/KB micro-controller sub-system. This is a =
Linux daemon that runs at system startup and is used by client =
applications to queue messages to display on the LCD panel. Client =
applications do not directly communicate to the device.=20

Direct Command Line Interface

The command line interface to the LCD/KB port is used for direct display =
of messages on the LCD panel. The following describes the command line =
interface for script access.=20

setlcd [=96<cmd> [<data>]] <text>=20

Where -<text> is an ASCII text string with NL (=91\n=92) & CR (=91\r=92) =
support.

Where -<cmd> is described by the following:=20

Cmd

Description

Comment

-clear

Clear the display

Clear display and homes the cursor.

-home

Home the cursor.

Move to the row=3D1, col=3D1 position.

-home2

Move cursor to second row.

Move to the row=3D2, col=3D1 position.

-col <col>

Move the cursor to the column position

Move the col to <col>.

-row <row>

Move the row to the row position

Move the row to < row >.

 	  	  =09
=20

Note that because this command bypasses the message queuing system, it =
is reserved for use by the LCDKBD and for debugging.

Queued LCD Messages

Under normal circumstances, all LCD messages are displayed and managed =
by the lcdkbd daemon. This daemon takes messages that should be =
displayed on the LCD panel and places them in a queue.  Because there =
are multiple messages available for display on the LCD panel, the LCD =
scroll button on the front of the machine is used to communicate with =
the lcdkbd daemon. =20

When the lcdkbd daemon detects a button press, it will cycle through the =
various messages in the message queue.  Some messages can be forced to =
the top of the queue, placing the message on the LCD without requiring =
the user press the LCD button.  This technique is used for urgent =
messages such as alerts.  Messages can also be displayed for one time =
only.  This type of message appears on the LCD until the user presses =
the LCD scroll button, and is then removed from the message queue so =
that it does not appear again.=20

Use the Perl object ShowMsg to tell the lcdkbd daemon to display =
specific messages on the LCD panel, as described below.

Adding LCD Messages

Because the contents of the LCD display are managed by the lcdkbd =
daemon, display of new messages involves creating a new message =
definition in an LCD message definition file.  Once defined properly, =
the LCD message can be displayed on the LCD panel by sending the lcdkbd =
daemon an instruction.  Use the following procedure to add your own LCD =
message to the display message queue.=20

=09
1.	Go to the directory /sa2/lang/en/lcdmsg.  This directory contains all =
LCD message definition files for the English language (which is the =
default).  When customizing messages to display in different languages, =
go to the corresponding language directory, such as /sa2/lang/es/lcdmsg =
for Spanish, or /sa2/lang/de/lcdmsg for German.=20

=20

=09
2.	Create a new definition file for your LCD message.  An example of a =
new message definition file called =93newmsg=94 appears below:=20

=20

	newmsg.desc=3DAcme Application Messages

	newmsg.name=3DACME

	newmsg.readonly=3D0

	newmsg.hidden=3D0

	newmsg.msgup=3D-center =93Acme App=94 =96center =93Running=94

	newmsg.msgdown=3D-center =93Acme App=94 =96center =93Not Running=94

	newmsg.msgalert=3D-ontop -center =93Acme App=94 =96center =93%s =
Error=94

	newmsg.msgmail=3D-ontop -onetime =96center =93Acme App=94 =96center =
=93Check Mail=94=20
=09

	See the section below for more information on these fields and their =
operation.=20
=09

=09
3.	Add a Perl script to your application that invokes the messages =
defined in your LCD message definition file.  This script should =
incorporate the appropriate ShowMsg call to display a message.  An =
example program is shown below:=20

=20

		use SA;

		use SA::LCD::Disp;=20
	=09

		my $objDisp =3D SA::LCD::Disp->new();

		$objDisp->ShowMsg(=93newmsg.msgmail=94);=20
	=09

		exit(0);=20
	=09

	This script would place the message =93Acme App=94, and =93Check =
Mail=94 on the first and second lines of the LCD panel.=20
=09

	Here is an example of how to display an LCD message that incorporates =
dynamic text, as in the =93newmsg.msgalert=94 LCD message above:=20
=09

		$objDisp->ShowMsg(=93newmsg.msgalert=94, =93Download=94);=20
	=09

=09
4.	To complete the configuration process for the new message, execute =
the mod_lcd trigger.  This trigger will regenerate the LCD configuration =
files and inform the lcdkbd daemon it should refresh its message list.  =
Note that execution of this trigger is only necessary when you have made =
a change to the LCD message list.=20

=20

		trigger mod_lcd

LCD Message Display Options

The LCD message definition files contained in the /sa2/lang/en/lcdmsg =
directory contain a variety of options for the messages displayed.  The =
message definition file example given above outlines these options.  The =
fields and options contained in this file are described here by using =
this example.  Fields are defined by the name of the message with a =
specific configuration parameter suffix.  In the example above, the =
message name is =93newmsg=94, so the description field in this file is =
=93newmsg.desc=94.=20

	newmsg.desc=3DAcme Application Messages=20
=09

The =93desc=94 portion is the configuration field parameter indicating =
the text description of the LCD message.  This text description will =
appear on the LCD configuration page in the web administration user =
interface that allows the user to select which LCD messages they wish to =
appear.=20
=20
=20

LCD Configuration Screen=20

The name suffix provides and internal name used by the Magnia SG20 =
middleware to help identify the message being displayed or configured.=20

	newmsg.name=3DACME=20
=09

In this case, the name given to the message is =93ACME=94.=20

	newmsg.readonly=3D0=20
=09

The readonly field specifies whether the user will be allowed to change =
the LCD setting.  In the default LCD configuration screen, the IP =
address display, and time of day are always checked and cannot be =
unchecked by the user.  To allow the user to deselect this LCD message =
from displaying on the LCD panel, set the readonly field to 0.  To =
prevent the user from deselecting this message and force the message to =
always display, set the readonly field to 0.=20

	newmsg.hidden=3D0=20
=09

The hidden field specifies whether the LCD message appears on the =
configuration screen.  Some messages, such as health monitoring, do not =
even appear on the user LCD configuration screen, and are always =
displayed.  To prevent a message from appearing on the configuration =
screen, set the hidden field to 1.  To present the message on the user =
configuration screen, set the hidden field to 0.=20

	newmsg.msgup=3D-center =93Acme App=94 =96center =93Running=94

	newmsg.msgdown=3D-center =93Acme App=94 =96center =93Not Running=94

	newmsg.msgalert=3D-ontop -center =93Acme App=94 =96center =93%s =
Error=94

	newmsg.msgmail=3D-ontop -onetime =96center =93Acme App=94 =96center =
=93Check Mail=94=20
=09

A single LCD message can have several states, or sub-messages.  For =
example, the =93backup=94 message may present the backup status as =
=93Not Performed=94, =93Started=94 or =93Completed=94.  Only one of =
these messages can be displayed on the LCD panel at a time.  If the =
=93Started=94 message is displayed, and then later the =93Completed=94 =
message is displayed, the =93Completed=94 message will replace the =
=93Started=94 message.=20

In this example, the Acme App message will display =93Acme App=94 on the =
first LCD line.  The second line will be =93Running=94, =93Not =
Running=94, =93 Error=94 or =93Check Mail=94. =20

The following formatting options are available:=20

=09
*	-center: center the text in the middle of the LCD line=20
*	-ontop: immediately display this message by placing it on the top of =
the message queue=20
*	-onetime: clear this message from the LCD message queue after it has =
been viewed by the user once=20

=20

________________________________

From: lcd...@li... =
[mailto:lcd...@li...] On Behalf Of Simon =
Kok
Sent: Monday, July 05, 2004 8:45 AM
To: lcd...@li...
Subject: [lcd4linux] Revisisted > Help > Using LCD4Linux on Toshiba =
Magnia SG-20

Hi there.
=20
I had posted a message a while back in regards to which driver to use =
for the Toshiba Magnia SG-20.
=20
Basically, it's a 2-line by 16- character backlit LCD along with a =
scroll button.  Toshiba refuses to release the source code / rpm to =
allow users to use a more current version of RedHat or distribution of =
Linux.
=20
Here's some pictures of what it looks like:
=20
http://www.groovesister.com/toshiba-sg20-lcd-front.JPG
=20
http://www.groovesister.com/toshiba-sg20-lcd-back.JPG
=20
http://www.linuxdevices.com/articles/AT7915816249.html
=20
-- Simon.