24dc2a2306
If no format length was specified then the formatting would break for any value with a zero in its representation. Signed-off-by: Andy Pugh <andy@bodgesoc.org> Fix some bugs in the lcd component Signed-off-by: Andy Pugh <andy@bodgesoc.org>
167 lines
7.1 KiB
Groff
167 lines
7.1 KiB
Groff
.TH LCD "9" "2012-09-17" "LinuxCNC Documentation" "HAL Component"
|
|
.de TQ
|
|
.br
|
|
.ns
|
|
.TP \\$1
|
|
..
|
|
|
|
.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.
|
|
|
|
\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 precison 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 and the \fBdecimal-separator\fR parameter should be used.
|
|
|
|
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. For example %.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.
|
|
|
|
\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 preceed 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
|