diff --git a/Doxyfile.in b/Doxyfile.in index 29b0b48..a6006e8 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -524,7 +524,7 @@ EXTRACT_ANON_NSPACES = NO # section is generated. This option has no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_MEMBERS = NO +HIDE_UNDOC_MEMBERS = YES # If the HIDE_UNDOC_CLASSES tag is set to YES, doxygen will hide all # undocumented classes that are normally visible in the class hierarchy. If set @@ -532,14 +532,14 @@ HIDE_UNDOC_MEMBERS = NO # has no effect if EXTRACT_ALL is enabled. # The default value is: NO. -HIDE_UNDOC_CLASSES = NO +HIDE_UNDOC_CLASSES = YES # If the HIDE_FRIEND_COMPOUNDS tag is set to YES, doxygen will hide all friend # declarations. If set to NO, these declarations will be included in the # documentation. # The default value is: NO. -HIDE_FRIEND_COMPOUNDS = NO +HIDE_FRIEND_COMPOUNDS = YES # If the HIDE_IN_BODY_DOCS tag is set to YES, doxygen will hide any # documentation blocks found inside the body of a function. If set to NO, these @@ -859,6 +859,7 @@ INPUT_ENCODING = UTF-8 FILE_PATTERNS = \ libx52.h \ libx52util.h \ + x52_cli.c \ *.dox # The RECURSIVE tag can be used to specify whether or not subdirectories should @@ -1952,7 +1953,7 @@ RTF_SOURCE_CODE = NO # classes and files. # The default value is: NO. -GENERATE_MAN = NO +GENERATE_MAN = YES # The MAN_OUTPUT tag is used to specify where the man pages will be put. If a # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of @@ -1970,7 +1971,7 @@ MAN_OUTPUT = man # The default value is: .3. # This tag requires that the tag GENERATE_MAN is set to YES. -MAN_EXTENSION = .3 +MAN_EXTENSION = .1 # The MAN_SUBDIR tag determines the name of the directory created within # MAN_OUTPUT in which the man pages are placed. If defaults to man followed by diff --git a/Makefile.am b/Makefile.am index 2e0646f..b78bbfe 100644 --- a/Makefile.am +++ b/Makefile.am @@ -26,19 +26,23 @@ EXTRA_DIST = \ # Doxygen support if HAVE_DOXYGEN -DXGEN = $(DXGEN_$(V)) -DXGEN_ = $(DXGEN_$(AM_DEFAULT_VERBOSITY)) +DXGEN = $(DXGEN_@AM_V@) +DXGEN_ = $(DXGEN_@AM_DEFAULT_V@) DXGEN_0 = @printf " DXGEN $<\n"; docs/.stamp: Doxyfile $(DXGEN)$(DOXYGEN) $< $(AM_V_at)touch $@ -CLEANFILES = docs - all-local: docs/.stamp clean-local: rm -rf $(top_builddir)/docs + +# Install Doxygen generated HTML documentation and manpages install-data-local: $(INSTALL) -d $(DESTDIR)$(docdir) rsync -a $(top_builddir)/docs/html $(DESTDIR)$(docdir) + + $(INSTALL) -d $(DESTDIR)$(mandir)/man1 + $(INSTALL) -D docs/man/man1/x52cli.1 $(DESTDIR)$(mandir)/man1 + endif diff --git a/utils/cli/Makefile.am b/utils/cli/Makefile.am index 68adb65..607d10b 100644 --- a/utils/cli/Makefile.am +++ b/utils/cli/Makefile.am @@ -12,6 +12,3 @@ bin_PROGRAMS = x52cli x52cli_SOURCES = x52_cli.c x52cli_CFLAGS = @X52_INCLUDE@ x52cli_LDADD = ../../lib/libx52/libx52.la - -# Man pages for CLI utility -dist_man1_MANS = x52cli.man diff --git a/utils/cli/x52_cli.c b/utils/cli/x52_cli.c index bfed4a9..04cfd3c 100644 --- a/utils/cli/x52_cli.c +++ b/utils/cli/x52_cli.c @@ -6,6 +6,142 @@ * SPDX-License-Identifier: GPL-2.0-only WITH Classpath-exception-2.0 */ +/** +@page x52cli Command Line Interface to libx52 + +\htmlonly +x52cli - Command line interface to libx52 +\endhtmlonly + +# SYNOPSIS +\b x52cli \a commands [\a command-options] + +# DESCRIPTION + +\b x52cli is a command line interface to the X52 library that allows you to set +the LEDs and different parameters on the multifunction display (MFD). + +Running \b x52cli without any arguments will display a brief help message. + +# COMMANDS + +Commands are not case sensitive. + +- \b bri { \b mfd | \b led } < \a brightness > + \n \manonly \fR \endmanonly + Set the brightness of the \b MFD or LEDs. \a brightness can be any + numeric value between 0 and 128. Higher values are accepted, but may not have + the desired effect. + +- \b mfd < \a line > < \a text > \n \manonly \fR \endmanonly + Set the text on the MFD \a line. \a line can be \c 0, \c 1 or \c 2, and refers + to the first, second or third line of the multifunction display respectively. + \a text cannot have embedded NUL characters (0x00) and must correspond with + the character map fo the MFD. \a text should be quoted in order to preserve + embedded whitespace. To pass raw hex values, use \b printf(1) as shown in the + \ref x52cli_examples section. Note that \a text is limited to a length of 16 + characters. While you can pass in longer strings, they will be silenty + truncated. + +- \b led < \a led-id > < \a state > \n \manonly \fR \endmanonly + Set the LED \a led-id to \a state. See \ref x52cli_leds for a list of + supported values. + +- \b blink { \b on | \b off } \n \manonly \fR \endmanonly + Turn the \b blink state \b on or \b off. + +- \b shift { \b on | \b off } \n \manonly \fR \endmanonly + Turn the \b shift indicator in the MFD \b on or \b off. + +- \b clock { \b local | \b gmt } { \b 12hr | \b 24hr } + { \b ddmmyy | \b mmddyy | \b yymmdd }\n \manonly \fR \endmanonly + Set the clock 1 display to the current \b local or \b GMT time and date. + Clock can be configured to display in either \b 12hr or \b 24hr mode. Date + can be displayed in one of the following formats: \b DD-MM-YY, \b MM-DD-YY, + or \b YY-MM-DD. + +- \b offset { \b 2 | \b 3 } < \a offset-val > + { \b 12hr | \b 24hr }\n \manonly \fR \endmanonly + Set the offset for clock \b 2 or \b 3 and configure them to display in either + \b 12hr or \b 24hr mode. \a offset-val is in minutes east of \b UTC and can + range from \a -1440 to \a +1440. + +- \b time < \a hour > < \a minute > + { \b 12hr | \b 24hr }\n \manonly \fR \endmanonly + Set the time for clock 1 to hour:minute and configure it to display + in \b 12hr or \b 24hr mode. + +- \b date <\a dd > <\a mm > <\a yy> + { \b ddmmyy | \b mmddyy | \b yymmdd }\n \manonly \fR \endmanonly + Set the date on the MFD to the values represented by \a dd, \a mm and \a yy in + the requested format. + +- \b raw < \a wIndex > < \a wValue >\n \manonly \fR \endmanonly + Send a raw vendor control request to the connected joystick.\n + \warning You should only use this if you know what you are doing. Sending + an invalid control sequence can potentially destroy your device. + +@section x52cli_leds LEDs +This is the list of LED IDs and corresponding states supported by the X52 Pro. +Note that the \b on state is only allowed for the \b fire and \b throttle LEDs, +and they do not support the \b red, \b amber and \b green states. The remaining +LEDs do not support the \b on state, but support all the other states. + +\note The \b led command is only supported on the X52 Pro, not on the X52. + +## LED IDs + +- \b fire +- \b a +- \b b +- \b d +- \b e +- \b t1 +- \b t2 +- \b t3 +- \b pov +- \b clutch +- \b throttle + +## States + +- \b off +- \b on +- \b red +- \b amber +- \b green + +# LIMITATIONS + +\b x52cli does not maintain any state between invocations. As a result the +\b clock command will reset the relative offsets for clocks 2 and 3 back to 0 +and configure them to be in 12 hour mode. To work around this, use the \b date +and \b time commands instead to manually configure the date and time. + +# PERMISSIONS + +You must have write permissions to the USB device in order to use the \b libx52 +library, and by extension, \b x52cli. + +The simplest method to obtain such permissions is to run \b x52cli as root, +possibly through \b sudo(8) + +@section x52cli_examples EXAMPLES + +- Turn off the T1 LED. + > \b x52cli led t1 off + +- Turn the B LED to Amber. + > \b x52cli led B amber + +- Set line 1 of the MFD to display "Hello World" + > \b x52cli mfd 0 "Hello World" + +- Set line 2 of the MFD to display "¿Cómo Estás?" + > \b x52cli mfd 1 "$(printf '\\x9FC\\xE2mo Est\\xE0s?')" + +*/ + #include #include #include diff --git a/utils/cli/x52cli.man b/utils/cli/x52cli.man deleted file mode 100644 index 1ae730a..0000000 --- a/utils/cli/x52cli.man +++ /dev/null @@ -1,147 +0,0 @@ -.TH X52CLI 1 2015-12-09 X52Pro-Linux "User Commands" -.SH NAME -x52cli \- Command line frontend to libx52 - -.SH SYNOPSIS -.B x52cli -<\fIcommands\fR> [\fIcommand-options\fR] - -.SH DESCRIPTION -.BR x52cli -is a command line frontend to the X52 library that allows you to set the LEDs -and different parameters on the multi-function display. - -Running -.BR x52cli -without any arguments will display a brief help message. - -.SH COMMANDS -Commands are not case sensitive. - -.IP "\fBbri\fR {\fBmfd\fR | \fBled\fR} <\fIbrightness\fR>" -Set the brightness of the \fBmfd\fR or \fBled\fRs. \fIbrightness\fR can be any -numeric value between 0 and 128. Higher values are accepted, but may not have -the desired effect. - -.IP "\fBmfd\fR <\fIline\fR> <\fItext\fR>" -Set the text on the MFD \fIline\fR. \fIline\fR can be 0, 1 or 2, and refers to -the first, second or third line of the multi-function display respectively. -\fItext\fR cannot have embedded NUL characters (0x00) and must correspond -with the character map of the MFD. \fItext\fR should be quoted in order to -preserve embedded whitespace. To pass raw hex values, use -.BR printf (1) -as shown in the examples section. Note that \fItext\fR is limited to a length -of 16 characters. While you can pass longer strings, they will be truncated. - -.IP "\fBled\fR <\fIled-id\fR> <\fIstate\fR>" -Set the LED \fIled-id\fR to \fIstate\fR. - -.IP "\fBblink\fR {\fBon\fR | \fBoff\fR}" -Turn the \fBblink\fR state \fBon\fR or \fBoff\fR. - -.IP "\fBshift\fR {\fBon\fR | \fBoff\fR}" -Turn the \fBshift\fR indicator in the multi-function display \fBon\fR or -\fBoff\fR. - -.IP "\fBclock\fR {\fBlocal\fR | \fBgmt\fR} {\fB12hr\fR | \fB24hr\fR} {\fBddmmyy\fR | \fBmmddyy\fR | \fByymmdd\fR}" -Set the clock 1 display to the current time and date in either the \fBlocal\fR -timezone, or in \fBgmt\fR timezone. Clock can be configured to display in either -\fB12hr\fB or \fB24hr\fR mode. Date can be displayed in one of the following -formats: \fBddmmyy\fR, \fBmmddyy\fR, or \fByymmdd\fR. - -.IP "\fBoffset\fR" {\fB2\fR | \fB3\fR} <\fIoffset-val\fR> {\fB12hr\fR | \fB24hr\fB}" -Set the offsets for clocks \fB2\fR or \fB3\fR and configure them in \fB12hr\fR -or \fB24hr\fR modes. \fIoffset-val\fR is in minutes from clock 1 and can range -from -1440 to +1440. - -.IP "\fBraw\fR <\fIwIndex\fR> <\fIwValue\fR>" -Send a raw vendor control request to the X52 Pro. - -\fBWARNING:\fR You should only use this if you know what you are doing. Sending -an invalid control sequence can potentially destroy your device. - -.SH LEDs - -.SS "LED IDs" -This is the list of LEDs supported by the X52 Pro. - -.IP \[bu] -fire -.IP \[bu] -a -.IP \[bu] -b -.IP \[bu] -d -.IP \[bu] -e -.IP \[bu] -t1 -.IP \[bu] -t2 -.IP \[bu] -t3 -.IP \[bu] -pov -.IP \[bu] -clutch -.IP \[bu] -throttle - -.SS "LED States" -This is the list of LED states supported by the X52 Pro. - -.IP \[bu] -off -.IP \[bu] -on -.IP \[bu] -red -.IP \[bu] -amber -.IP \[bu] -green - -.P -Note that the \fBon\fR state is only supported by the \fBfire\fR and -\fBthrottle\fR LEDs, and they do not support the \fBred\fR, \fBamber\fR -and \fBgreen\fR states. The remaining LEDs do not support the \fBon\fR -state, but support all the other states. - -.SH KNOWN ISSUES - -.BR x52cli -does not maintain any state between invocations. As a result, the -\fBclock\fR command will reset the offsets for clocks 2 and 3 back to 0 -in 12hr mode. - -.SH PERMISSIONS - -You must have write permissions to the USB device in order to use the -\fBlibx52\fR library, and by extension -.BR x52cli - -The simplest method is to run -.BR x52cli -as root, preferably through -.BR sudo (8) - -.SH EXAMPLES - -.PD 0 -\fBx52cli\fR led t1 off -.P -Turn off the T1 LED. - -\fBx52cli\fR led B amber -.P -Turn the B LED to Amber - -\fBx52cli\fR mfd 0 "Hello World" -.P -Set line 1 of the MFD to display "Hello World" - -\fBx52cli\fR mfd 1 "$(printf '\\x9FC\\xE2mo Est\\xE0s?')" -.P -Set line 2 of the MFD to display "¿Cómo Estás?" -