160 lines
7.3 KiB
Groff
160 lines
7.3 KiB
Groff
.TH LCD "9" "2012-09-17" "LinuxCNC Documentation" "HAL Component"
|
|
|
|
.SH NAME
|
|
lcd \- Stream HAL data to an LCD screen
|
|
.SH SYNOPSIS
|
|
.HP
|
|
.B loadrt lcd fmt_strings=""Plain Text %4.4f\enAnd So on|Second Page, Next Inst""
|
|
.SH FUNCTIONS
|
|
.TP
|
|
\fBlcd\fR (requires a floating-point thread).
|
|
All LCD instances are updated by the same function.
|
|
|
|
.SH PINS
|
|
.TP
|
|
.B lcd.\fINN\fB.out\fR (u32) out
|
|
The output byte stream is sent via this pin. One character is sent every thread
|
|
invocation. There in no handshaking provided.
|
|
.TP
|
|
.B lcd.\fINN\fB.page.\fIPP.\fBarg.\fINN\fR (float/s32/u32/bit) in
|
|
The input pins have types matched to the format string specifiers.
|
|
.TP
|
|
.B lcd.\fINN\fB.page_num\fR (u32) in
|
|
Selects the page number. Multiple layouts may be defined, and this pin switches
|
|
between them.
|
|
.TP
|
|
.B lcd.\fINN\fB.contrast\fR (float) in
|
|
Attempts to set the contrast of the LCD screen using the byte sequence ESC C and
|
|
then a value from 0x20 to 0xBF (matching the Mesa 7I73).
|
|
The value should be between 0 and 1.
|
|
|
|
.SH PARAMETERS
|
|
.TP
|
|
.B lcd.\fINN\fB.decimal\-separator\fR (u32) rw
|
|
Sets the decimal separator used for floating point numbers. The default value is
|
|
46 (0x2E) which corresponds to ".". If a comma is required then set this
|
|
parameter to 44 (0x2C).
|
|
|
|
.SH DESCRIPTION
|
|
|
|
\fBlcd\fR takes format strings much like those used in C and many other languages
|
|
in the printf and scanf functions and their variants.
|
|
|
|
The component was written specifically to support the Mesa 7I73 pendant controller,
|
|
however, it may be of use streaming data to other character devices
|
|
and, as the output format mimics the ADM3 terminal format, it could be used
|
|
to stream data to a serial device. Perhaps even a genuine ADM3.
|
|
The strings contain a mixture of text values (which are displayed directly),
|
|
"escaped" formatting codes and numerical format descriptors.
|
|
For a detailed description of formatting codes see:
|
|
http://en.wikipedia.org/wiki/Printf
|
|
|
|
The component can be configured to display an unlimited number of
|
|
differently-formatted pages, which may be selected with a HAL pin.
|
|
.TP
|
|
\fBEscaped codes\fR
|
|
\en Inserts a clear-to-end, carriage return and line feed character. This will
|
|
still linefeed and clear even if an automatic wrap has occurred (lcd has no
|
|
knowledge of the width of the lcd display.) To print in the rightmost column it
|
|
is necessary to allow the format to wrap and omit the \en code.
|
|
|
|
\et Inserts a tab (actually 4 spaces in the current version rather than a true
|
|
tab.)
|
|
|
|
\eNN inserts the character defined by the hexadecimal code NN.
|
|
As the ',' character is used in the format string to separate LCD instances
|
|
it must be represented by \e2C in the format string. (the decimal
|
|
separator is handled differently)
|
|
|
|
\e\e Inserts a literal \e.
|
|
|
|
.TP
|
|
\fBNumerical formats\fR
|
|
|
|
\fBlcd\fR differs slightly from the standard printf conventions.
|
|
One significant difference is that width limits are strictly enforced to prevent the LCD display
|
|
wrapping and spoiling the layout. The field width includes the sign character
|
|
so that negative numbers will often have a smaller valid range than positive.
|
|
Numbers that do not fit in the specified width are displayed as a line of asterisks (\fB********\fR).
|
|
|
|
Each format begins with a "%" symbol. (For a literal % use "%%").
|
|
Immediately after the % the following modifiers may be used:
|
|
|
|
" " (space) Pad the number to the specified width with spaces.
|
|
This is the default and is not strictly necessary.
|
|
|
|
"0" Pad the number to the specified width with the numeral 0.
|
|
|
|
"+" Force display of a + symbol before positive numbers. This (like the \- sign)
|
|
will appear immediately to the left of the digits for a space-padded number
|
|
and in the extreme left position for a 0-padded number.
|
|
|
|
"1234567890" A numerical entry (other than the leading 0 above) defines the
|
|
total number of characters to display including the decimal separator and the sign.
|
|
Whilst this number can be as many digits as required, the maximum field width is 20 characters.
|
|
The inherent precision of the "double" data type means
|
|
that more than 14 digits will tend to show errors in the least significant digits.
|
|
The integer data types will never fill more than 10 decimal digits.
|
|
|
|
Following the width specifier should be the decimal specifier.
|
|
This can only be a full-stop character (.) as the comma (,) is used as the instance separator.
|
|
Currently lcd does not access the locale information to determine the correct separator
|
|
but the \fBdecimal\-separator\fR HAL parameter can be used to choose any desired separator.
|
|
|
|
Following the decimal separator should be a number that determines
|
|
how many places of decimals to display. This entry is ignored in the case of integer formats.
|
|
|
|
All the above modifiers are optional, but to specify a decimal precision the
|
|
decimal point must precede the precision, e.g., as in "%.3f".
|
|
The default decimal precision is 4.
|
|
|
|
The numerical formats supported are:
|
|
|
|
\fB%f %F\fR (for example, %+09.3f) These create a floating-point type HAL pin.
|
|
The example would be displayed in a 9-character field, with 3 places of decimals,
|
|
as a decimal separator, padded to the left with 0s and with a sign displayed for
|
|
both positive and negative. Conversely a plain %f would be 6 digits of decimal,
|
|
variable format width, with a sign only shown for negative numbers.
|
|
Both %f and %F create exactly the same format.
|
|
|
|
\fB%i %d\fR (For example %+ 4d) Creates a signed (s32) HAL pin.
|
|
The example would display the value at a fixed 4 characters, space padded,
|
|
width including the "+" giving a range of +999 to \-999. %i and %d create identical output.
|
|
|
|
\fB%u\fR (for example %08u) Creates an unsigned (u32) HAL pin.
|
|
The example would be a fixed 8 characters wide, padded with zeros.
|
|
|
|
\fB%x, %X\fR Creates an unsigned (u32) HAL pin and displays the value in Hexadecimal.
|
|
Both %x and %X display capital letters for digits ABCDEF.
|
|
A width may be specified, though the u32 HAL type is only 8 hex digits wide.
|
|
|
|
\fB%o\fR Creates an unsigned (u32) pin and displays the value in octal representation.
|
|
|
|
\fB%c\fR Creates a u32 HAL pin and displays the character corresponding to the value of the pin.
|
|
Values less than 32 (space) are suppressed. A width specifier may be used,
|
|
for example %20c might be used to create a complete line of one character.
|
|
|
|
\fB%b\fR This specifier has no equivalent in printf.
|
|
It creates a bit (boolean) type HAL pin. The b should be followed by two characters
|
|
and the display will show the first of these when the pin is true, and the second when false.
|
|
Note that the characters follow, not precede the "b", unlike the case with other formats.
|
|
The characters may be "escaped" Hex values.
|
|
For example "%b\eFF " will display a solid black block if true,
|
|
and a space if false and "%b\e7F\e7E" would display right-arrow for false and left-arrow for true.
|
|
An unexpected value of 'E' indicates a formatting error.
|
|
|
|
\fBPages\fR
|
|
The page separator is the "|" (pipe) character (if the actual character is needed then \e7C may be used).
|
|
A "Page" in this context refers to a separate format which may be displayed on the same display.
|
|
|
|
\fBInstances\fR
|
|
The instance separator is the comma. This creates a completely separate lcd instance,
|
|
for example to drive a second lcd display on the second 7I73.
|
|
The use of comma to separate instances is built in to the modparam reading code
|
|
so not even escaped commas "\e," can be used.
|
|
A comma may be displayed by using the \e2C sequence.
|
|
|
|
.SH AUTHOR
|
|
Andy Pugh
|
|
.SH LICENSE
|
|
GPL
|