mangavalk/lcdproc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update developer documentaton

Browse Source
This commit is contained in:
marschap
2006-04-05 06:04:20 +00:00
parent 1c1ade5f56
commit f1d36b0179
3 changed files with 239 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/lcdproc-dev/add-your-driver.docbook
+150 -4
View File
@@ -15,7 +15,7 @@ This chapter will explain you the major steps and few gotchas of adding your own
</sect1>
<sect1 id="autoconfautomake">
<title>Autoconf, automake, b&ouml;rk b&ouml;rk b&ouml;rk!</title>
<title>Autoconf, automake, and Everything!</title>
<para>How I Learned to Stop Worrying and Love the Configure Script</para>
@@ -148,7 +148,11 @@ myDriver_LDADD = @SOMESTRANGELIB@
<sect3 id="automake-step3">
<title>Step 3</title>
<para>Last but not least, you need to specify which source files should be associated with your driver. You put your driver name followed by _SOURCES and egal this to a space separated list of the source and header files. See below for an example.</para>
<para>
Last but not least, you need to specify which source files should be
associated with your driver. You put your driver name followed by
<literal>_SOURCES</literal> and egal this to a space separated list
of the source and header files. See below for an example.</para>
<screen>
myDriver_SOURCES = lcd.h myDriver.c myDriver.h report.h
@@ -161,9 +165,151 @@ myDriver_SOURCES = lcd.h myDriver.c myDriver.h report.h
<sect2 id="autoconfautomake-test">
<title>Test your setup</title>
<para>You're almost done! You only need to check out if you didn't made any mistake. Just run sh autogen.sh to regenerate the configure script and Makefiles, then run ./configure --enable-drivers=myDriver and type make. If your driver compiles without error, then congratulations, you've just added your driver to LCDproc! Remember to submit a patch to the mailing list so that we can add it to the standard distribution.</para>
<para>
You're almost done! You only need to check out if you didn't made any mistake.
Just run sh autogen.sh to regenerate the configure script and Makefiles,
then run ./configure --enable-drivers=myDriver and type make.
If your driver compiles without error, then congratulations, you've just added
your driver to LCDproc! Remember to submit a patch to the mailing list so that
we can add it to the standard distribution, but do not forget the documentation.
</para>
<para>If you had an error, just send us an email describing it to the mailing list and we'll try to help you.</para>
<para>
If you had an error, just send us an email describing it to the mailing list and we'll try to help you.
</para>
</sect2>
</sect1>
<sect1 id="documentation">
<title>It's all about documentation</title>
<para>
Please do not forget to also add the required documentation,
so that your driver can be used from others as well.
</para>
<sect2 id="documentation-LCDd.conf">
<title>The configuration file, LCDd.conf</title>
<para>
Extend the LCDproc server's configuration file with a section that holds
a standard configuration for your driver together with short descriptions
of the options used.
</para>
<screen>
&hellip;
<emphasis>
## MyDriver for MyDevice ##
[MyDriver]
# Select the output device to use [default: /dev/lcd]
Device=/dev/ttyS0
# Set the display size [default: 20x4]
Size=20x4
</emphasis>
&hellip;
</screen>
</sect2>
<sect2 id="documentation-manpage">
<title>The daemon's manual page, LCDd.8</title>
<para>
Append your driver to the list of drivers in <filename>docs/LCDd.conf</filename>,
the manual page of LCD, so that users can find your driver when doing <userinput>man LCDd</userinput>.
</para>
<screen>
&hellip;
.TP
.B ms6931
MSI-6931 displays in 1U rack servers by MSI
.TP
.B mtc_s16209x
MTC_S16209x LCD displays by Microtips Technology Inc
.TP
.B MtxOrb
Matrix Orbital displays (except Matrix Orbital GLK displays)
<emphasis>.TP</emphasis>
<emphasis>.B MyDriver</emphasis>
<emphasis>displays connected using MyDevice</emphasis>
.TP
.B NoritakeVFD
Noritake VFD Device CU20045SCPB-T28A
.TP
.B pylcd
LCD displays from Pyramid (http://www.pyramid.de)
.TP
.B sed1330
SED1330/SED1335 (aka S1D13300/S1D13305) based graphical displays
&hellip;
</screen>
</sect2>
<sect2 id="documentation-userdocbook">
<title>The user guide</title>
<sect3 id="userdocbook-file">
<title>Step 1</title>
<para>
Please add a file <filename><emphasis>myDriver</emphasis>.docbook</filename>,
that describes the configuration of your driver and the hard/software needed,
to the directory <filename>docs/lcdproc-user/drivers/</filename>.
</para>
</sect3>
<sect3 id="userdocbook-defentity">
<title>Step 2</title>
<para>
Define a Docbook entity for your driverfile in <filename>lcdproc-user.docbook</filename>.
</para>
<screen>
&hellip;
&lt;!ENTITY ms6931 SYSTEM "drivers/ms6931.docbook"&gt;
&lt;!ENTITY mtc_s16209x SYSTEM "drivers/mtc_s16209x.docbook"&gt;
&lt;!ENTITY MtxOrb SYSTEM "drivers/mtxorb.docbook"&gt;
<emphasis>&lt;!ENTITY MyDriver SYSTEM "drivers/MyDriver.docbook"&gt;</emphasis>
&lt;!ENTITY NoritakeVFD SYSTEM "drivers/NoritakeVFD.docbook"&gt;
&lt;!ENTITY pylcd SYSTEM "drivers/pylcd.docbook"&gt;
&lt;!ENTITY sed1330 SYSTEM "drivers/sed1330.docbook"&gt;
&hellip;
</screen>
</sect3>
<sect3 id="userdocbook-useentity">
<title>Step 3</title>
<para>
Add the freshly defined entity to <filename>drivers.docbook</filename>
to include the documentation of your driver into the
<emphasis>LCDproc User's Guide</emphasis>.
</para>
<screen>
&hellip;
&amp;ms6931;
&amp;mtc_s16209x;
&amp;MtxOrb;
<emphasis>&amp;MyDriver;</emphasis>
&amp;NoritakeVFD;
&amp;pylcd;
&amp;sed1330;
&hellip;
</screen>
</sect3>
</sect2>
docs/lcdproc-dev/driver-api.docbook
+83 -71
View File
@@ -256,70 +256,72 @@ typedef struct my_driver_private {
<sect1 id="function-details">
<title>FUNCTIONS IN DETAIL</title>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*init)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
The init function
Starts up the LCD, initializes all vars. Allocates private data space
The init() function.
It starts up the LCD, initializes all variables, allocates private data space
and stores the pointer by calling store_private_ptr();
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*close)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Shuts down the connection with the LCD.
Shut down the connection with the LCD.
Called just before unloading the driver.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*width)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Get the screen width.
Get the screen width in characters.
The result is 1-based.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*height)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Get the screen height.
Get the screen height in lines.
The result is 1-based.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*clear)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Clears the framebuffer
Clear the framebuffer.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*flush)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Flushes the framebuffer to the LCD.
Flush the framebuffer to the LCD.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*string)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -327,14 +329,17 @@ typedef struct my_driver_private {
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>char *<parameter>str</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Places a string in the framebuffer
All coordinates are 1-based, (1,1) is top left.
Driver should check for overflows
Place string <replaceable>str</replaceable> into position
(<replaceable>x</replaceable>,<replaceable>y</replaceable>) in the framebuffer.
All coordinates are 1-based, i.e. (1,1) is top left.
The driver should check for overflows, i.e. that the positional parameters
are within the screen's boundaries and cut off the part of the string
that is out of bounds.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*chr)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -342,13 +347,16 @@ typedef struct my_driver_private {
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>char <parameter>c</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Places a char in the framebuffer
Driver should check for overflows
Place a single character <replaceable>c</replaceable> into position
(<replaceable>x</replaceable>,<replaceable>y</replaceable>) in the framebuffer.
The driver should check for overflows, i.e. that the positional parameters
are within the screen's boundaries and ignore the request if
the character is out of bounds.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*vbar)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -358,12 +366,14 @@ typedef struct my_driver_private {
<paramdef>int <parameter>promille</parameter></paramdef>
<paramdef>int <parameter>options</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Draws a vertical bar at horizontal position x and with length len.
Draw a vertical bar at position (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
that has maximal length <replaceable>len</replaceable>, where a fraction of
(<replaceable>promille</replaceable> / 1000) is filled.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*hbar)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -373,30 +383,32 @@ typedef struct my_driver_private {
<paramdef>int <parameter>promille</parameter></paramdef>
<paramdef>int <parameter>options</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Draws a horizontal bar at position x,y and with length len.
Draw a horizontal bar at position (<replaceable>x</replaceable>,<replaceable>y</replaceable>)
that has maximal length <replaceable>len</replaceable>, where a fraction of
(<replaceable>promille</replaceable> / 1000) is filled.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*num)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>int <parameter>x</parameter></paramdef>
<paramdef>int <parameter>num</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Displays a big number at position x.
Display big number <replaceable>num</replaceable> at horizontal position <replaceable>x</replaceable>.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*heartbeat)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>int <parameter>state</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Sets the heartbeat to the indicated state.
0=off 1=graph1 2=graph2
@@ -406,7 +418,7 @@ typedef struct my_driver_private {
The driver choose how to do it. See MtxOrb.c"
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*icon)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
@@ -414,110 +426,110 @@ typedef struct my_driver_private {
<paramdef>int <parameter>y</parameter></paramdef>
<paramdef>int <parameter>icon</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*set_char)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>char <parameter>ch</parameter></paramdef>
<paramdef>char *<parameter>dat</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*get_free_chars)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*cellwidth)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*cellheight)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*contrast)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>int <parameter>contrast</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Sets the contrast to the given value. Values should be 0 to 255.
Many displays do not support software setting of contrast.
Use -1 to get the current value returned.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*backlight)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>int <parameter>brightness</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Sets the backlight to brightness 'on'.
Often hardware can only support on and off, in that case any value
of on>0 will switch the backlight on.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>void <function>(*output)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
<paramdef>int <parameter>state</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Sets the output value. Some displays/wirings have a general purpose
output, which can be controlled by calling this function. See the
'output' command in the 'widget language'.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>(*get_key)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Checks if a key has been pressed on the device.
Returns NULL for "no key pressed", or a string describing the pressd key.
These characters should match the keypad-layout.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>(*get_info)</function></funcdef>
<paramdef>Driver *<parameter>drvthis</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Returns a string describing the driver and its features.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>char <function>(*config_get_bool)</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -525,7 +537,7 @@ typedef struct my_driver_private {
<paramdef>int <parameter>skip</parameter></paramdef>
<paramdef>char <parameter>default_value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Call to server. Retrieve a bool from the config file.
Sectionname should be the name of the driver (as in the struct).
@@ -534,7 +546,7 @@ typedef struct my_driver_private {
identical keys, then increase skip to get every next value.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>(*config_get_int)</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -542,12 +554,12 @@ typedef struct my_driver_private {
<paramdef>int <parameter>skip</parameter></paramdef>
<paramdef>int <parameter>default_value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Call to server. Retrieve an integer from the config file.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>double <function>(*config_get_float)</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -555,12 +567,12 @@ typedef struct my_driver_private {
<paramdef>int <parameter>skip</parameter></paramdef>
<paramdef>double <parameter>default_value</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Call to server. Retrieve a float from the config file.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>char *<function>(*config_get_string)</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
@@ -568,7 +580,7 @@ typedef struct my_driver_private {
<paramdef>int <parameter>skip</parameter></paramdef>
<paramdef>char *<parameter>default</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Call to server. Retrieve a string from the config file.
Fill result with a pointer to some available space. You can fill it
@@ -579,24 +591,24 @@ typedef struct my_driver_private {
next call.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>config_has_section</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Returns wether a section exists. Does not need to be called prior
to a call to a config_get_* function.
</para>
<funcsynopsis>
<funcsynopsis>
<funcprototype>
<funcdef>int <function>config_has_key</function></funcdef>
<paramdef>char *<parameter>sectionname</parameter></paramdef>
<paramdef>char *<parameter>keyname</parameter></paramdef>
</funcprototype>
</funcsynopsis>
</funcsynopsis>
<para>
Returns the number of times a key exists. Does not need to be called
prior to a call to a config_get_* function.
docs/lcdproc-dev/language.docbook
+6 -6
View File
@@ -301,13 +301,13 @@
<varlistentry>
<term><literal>hidden</literal></term>
<listitem><para>
screen will never be visible
The screen will never be visible
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>background</literal></term>
<listitem><para>
only visible when no normal info screens exist
The screen is only visible when no normal info screens exists
</para></listitem>
</varlistentry>
<varlistentry>
@@ -325,13 +325,13 @@
<varlistentry>
<term><literal>alert</literal></term>
<listitem><para>
screen has an important message for the user
The screen has an important message for the user.
</para></listitem>
</varlistentry>
<varlistentry>
<term><literal>input</literal></term>
<listitem><para>
the client is doing interactive input
The client is doing interactive input.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -388,7 +388,7 @@
</term>
<listitem><para>
Changes the heartbeat setting for this screen.
If the to <literal>open</literal>, the default,r
If set to <literal>open</literal>, the default,
the client's heartbeat setting will be used.
</para></listitem>
</varlistentry>
@@ -480,7 +480,7 @@
<arg choice="plain"><replaceable>screen_id</replaceable></arg>
<arg choice="plain"><replaceable>new_widget_id</replaceable></arg>
<arg choice="plain"><replaceable>widgettype</replaceable></arg>
<arg>-in <replaceable>frame_id</replaceable></arg>]
<arg>-in <replaceable>frame_id</replaceable></arg>
</cmdsynopsis>
</term>
<listitem>