diff --git a/man/.gitignore b/man/.gitignore new file mode 100644 index 0000000..70c9a85 --- /dev/null +++ b/man/.gitignore @@ -0,0 +1,7 @@ +# Ignore generated man pages +*.1 +*.3 + +# Ignore generated html pages +*.html + diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 0000000..9b242fc --- /dev/null +++ b/man/Makefile @@ -0,0 +1,14 @@ +# Makefile to generate man & html pages from ronn input +# This is deliberately kept as a manual makefile and not as a part of +# the autotools framework for the time being. + +PROJECT := x52pro-linux + +MAN3_PAGES := $(wildcard *.3.ronn) +all: $(MAN3_PAGES) + ronn --manual "Programmer's Guide" --organization="$(PROJECT)" $(MAN3_PAGES) + +.PHONY: clean +clean: + rm -f *.3 + rm -f *.html diff --git a/man/README.md b/man/README.md new file mode 100644 index 0000000..4ea904c --- /dev/null +++ b/man/README.md @@ -0,0 +1,9 @@ +Man Pages for x52pro-linux +========================== + +This folder contains the man pages for the components of libx52 in a Markdown +format called ronn. To convert them into man pages requires the ronn executable, +which may be found in the ruby-ronn package on Ubuntu. Other distributions may +have a similar package name. + +ronn may also be found at http://github.com/rtomayko/ronn diff --git a/man/index.txt b/man/index.txt new file mode 100644 index 0000000..2f23ae2 --- /dev/null +++ b/man/index.txt @@ -0,0 +1,5 @@ +# Standard POSIX manuals +time(2) http://man.cx/time%282%29 +localtime(3) http://man.cx/localtime +gmtime(3) http://man.cx/gmtime +timezone(3) http://man.cx/tzset diff --git a/man/libx52_exit.3.ronn b/man/libx52_exit.3.ronn new file mode 100644 index 0000000..89d1327 --- /dev/null +++ b/man/libx52_exit.3.ronn @@ -0,0 +1,18 @@ +libx52_exit(3) -- exit the library and free up any resources used +================================================================= + +## SYNOPSIS + +`#include ` + +**void libx52_exit(libx52_device * _dev_)** + +## DESCRIPTION + +`libx52_exit()` releases any resources allocated by libx52_init(3) and +terminates the library. Using the freed device now is invalid and can cause +errors. + +## SEE ALSO + +libx52_init(3) diff --git a/man/libx52_init.3.ronn b/man/libx52_init.3.ronn new file mode 100644 index 0000000..7d6be5f --- /dev/null +++ b/man/libx52_init.3.ronn @@ -0,0 +1,27 @@ +libx52_init(3) -- Initialize libx52 +=================================== + +## SYNOPSIS + +`#include ` + +`libx52_device * libx52_init(void)` + +## DESCRIPTION + +`libx52_init()` initializes the libx52 library, sets up any internal data +structures to access the X52 Pro joystick and returns a *libx52_device* pointer. + +If no joystick is found `libx52_init()` returns _NULL_. + +## LIMITATIONS + +`libx52_init()` currently only recognizes the Saitek X52 Pro, not the original +Saitek X52. + +`libx52_init()` does not support hotplugging. The joystick must be plugged in +before calling this function. + +## SEE ALSO + +libx52_exit(3) diff --git a/man/libx52_set_blink.3.ronn b/man/libx52_set_blink.3.ronn new file mode 100644 index 0000000..108f39d --- /dev/null +++ b/man/libx52_set_blink.3.ronn @@ -0,0 +1,21 @@ +libx52_set_blink(3) -- turn the blink module on or off +====================================================== + +## SYNOPSIS + +`#include ` + +`int libx52_set_blink(libx52_device *` _x52_`, uint8_t ` _state_`)` + +## DESCRIPTION + +`libx52_set_blink()` can be used to set the state of the blink module to `on` +(_state_ is non-zero) or `off` (_state_ is 0). + +## RETURN VALUE + +`libx52_set_blink()` returns 0 on success, and `-EINVAL` if _x52_ is not valid. + +## SEE ALSO + +libx52_update(3) diff --git a/man/libx52_set_brightness.3.ronn b/man/libx52_set_brightness.3.ronn new file mode 100644 index 0000000..da19c59 --- /dev/null +++ b/man/libx52_set_brightness.3.ronn @@ -0,0 +1,25 @@ +libx52_set_brightness(3) -- set the brightness of the MFD or LEDs +================================================================= + +## SYNOPSIS + +`#include ` + +`int libx52_set_brightness(libx52_device *` _x52_`, uint8_t ` _mfd_ +`, uint16_t ` _brightness_`)` + +## DESCRIPTION + +`libx52_set_brightness()` can be used to set the brightness of the MFD (if _mfd_ +is non-zero) or the LEDs (if _mfd_ is *0*). Brightness should be a value +between 0 and 128. While higher values are accepted, they do not have the +intended effect. + +## RETURN VALUE + +`libx52_set_brightness()` returns 0 on success, and `-EINVAL` if _x52_ is not +valid. + +## SEE ALSO + +libx52_set_text(3), libx52_set_led_state(3), libx52_update(3) diff --git a/man/libx52_set_clock.3.ronn b/man/libx52_set_clock.3.ronn new file mode 100644 index 0000000..204d80b --- /dev/null +++ b/man/libx52_set_clock.3.ronn @@ -0,0 +1,37 @@ +libx52_set_clock(3) -- set the primary clock +============================================ + +## SYNOPSIS + +`#include ` + +`int libx52_set_clock(libx52_device *` _x52_`, time_t ` _time_ `, int ` _local_`)` + +## DESCRIPTION + +`libx52_set_clock()` can be used to set the primary clock and date display of +the MFD. The _time_ can be obtained from time(2). _local_ controls whether +the primary clock displays local time or GMT. + +If this function is called again within the same minute as calculated by +localtime(3) or gmtime(3), it will return `-EAGAIN`, as it does not require +any updates to be written to the X52 Pro. However, if the call changes the +timezone from local time to GMT or vice-versa, then this function will return +0, since it necessitates a write to the device to update the clock with the +new timezone. + +The secondary and tertiary clocks are driven off the primary clock and set as +offsets in minutes east of GMT. + +## RETURN VALUE + +`libx52_set_clock()` returns the following values: + +* 0 on success +* `-EINVAL` if _x52_ is not valid +* `-EAGAIN` if the time did not require an update to the clock. + +## SEE ALSO + +libx52_set_clock_timezone(3), libx52_set_clock_format(3), +libx52_set_date_format(3), libx52_update(3) diff --git a/man/libx52_set_clock_format.3.ronn b/man/libx52_set_clock_format.3.ronn new file mode 100644 index 0000000..538fdd6 --- /dev/null +++ b/man/libx52_set_clock_format.3.ronn @@ -0,0 +1,42 @@ +libx52_set_clock_format(3) -- set the clock display format +========================================================== + +## SYNOPSIS + +`#include ` + +`int libx52_set_clock_format(libx52_device *` _x52_`, libx52_clock_id ` +_clock_ `, libx52_clock_format ` _format_`)` + +## DESCRIPTION + +`libx52_set_clock_format()` can be used to set the clocks to display in 12hr +or 24hr format. + +### CLOCK IDS + +The following are the clocks supported by the X52 Pro MFD: + +* `LIBX52_CLOCK_1` - refers to the primary clock +* `LIBX52_CLOCK_2` - refers to the secondary clock +* `LIBX52_CLOCK_3` - refers to the tertiary clock + +### CLOCK FORMATS + +The following formats are supported by the X52 Pro MFD: + +* `LIBX52_CLOCK_FORMAT_12HR` +* `LIBX52_CLOCK_FORMAT_24HR` + +## RETURN VALUE + +`libx52_set_clock_format()` returns the following values: + +* 0 on success +* `-EINVAL` if _x52_ is not valid, or _clock_ or _format_ values are not in +the accepted range + +## SEE ALSO + +libx52_set_clock(3), libx52_set_clock_timezone(3), +libx52_set_date_format(3), libx52_update(3) diff --git a/man/libx52_set_clock_timezone.3.ronn b/man/libx52_set_clock_timezone.3.ronn new file mode 100644 index 0000000..1de24eb --- /dev/null +++ b/man/libx52_set_clock_timezone.3.ronn @@ -0,0 +1,34 @@ +libx52_set_clock_timezone(3) -- set the timezone for the secondary and tertiary clocks +====================================================================================== + +## SYNOPSIS + +`#include ` + +`int libx52_set_clock_timezone(libx52_device *` _x52_`, libx52_clock_id ` +_clock_ `, int ` _offset_`)` + +## DESCRIPTION + +`libx52_set_clock_timezone()` can be used to set the timezone for the secondary +and tertiary clocks on the MFD. The timezone is set as an _offset_ in minutes +east of GMT. Note that this is different from the timezone(3) attribute in the +standard C library which specifies the offset in seconds west of GMT. + +_offset_ is limited to +/- 24 hours (1440 minutes). + +See libx52_set_clock_format(3) for an explanation of `libx52_clock_id`. + +## RETURN VALUE + +`libx52_set_clock()` returns the following values: + +* 0 on success +* `-EINVAL` if _x52_ is not valid +* `-EDOM` if the offset is more than +/- 24 hours +* `-ENOTSUP` if the _clock_ is `LIBX52_CLOCK_1` + +## SEE ALSO + +libx52_set_clock(3), libx52_set_clock_format(3), +libx52_set_date_format(3), libx52_update(3) diff --git a/man/libx52_set_date_format.3.ronn b/man/libx52_set_date_format.3.ronn new file mode 100644 index 0000000..1a95481 --- /dev/null +++ b/man/libx52_set_date_format.3.ronn @@ -0,0 +1,32 @@ +libx52_set_date_format(3) -- set the date display format +========================================================== + +## SYNOPSIS + +`#include ` + +`int libx52_set_date_format(libx52_device *` _x52_`, libx52_date_format ` _format_`)` + +## DESCRIPTION + +`libx52_set_date_format()` can be used to set the date display format. + +### DATE FORMATS + +The following formats are supported by the X52 Pro MFD: + +* `LIBX52_DATE_FORMAT_DDMMYY` +* `LIBX52_DATE_FORMAT_MMDDYY` +* `LIBX52_DATE_FORMAT_YYMMDD` + +## RETURN VALUE + +`libx52_set_date_format()` returns the following values: + +* 0 on success +* `-EINVAL` if _x52_ is not valid + +## SEE ALSO + +libx52_set_clock(3), libx52_set_clock_timezone(3), libx52_set_clock_format(3), +libx52_update(3) diff --git a/man/libx52_set_led_state.3.ronn b/man/libx52_set_led_state.3.ronn new file mode 100644 index 0000000..79ffb55 --- /dev/null +++ b/man/libx52_set_led_state.3.ronn @@ -0,0 +1,58 @@ +libx52_set_led_state(3) -- set the LED state +============================================ + +## SYNOPSIS + +`#include ` + +`int libx52_set_led_state(libx52_device *`_x52_`, libx52_led_id ` _led_ +`, libx52_led_state ` _state_`)` + +## DESCRIPTION + +The Saitek X52 Pro has several LEDs that can be individually controlled. This +function allows you to set the state of each LED in the internal data +structures. + +### LED STATES + +The following are the supported LED states that are accepted by the _state_ +parameter. Note that all values are not supported by all LEDs. + +* `LIBX52_LED_STATE_OFF` +* `LIBX52_LED_STATE_ON` +* `LIBX52_LED_STATE_RED` +* `LIBX52_LED_STATE_AMBER` +* `LIBX52_LED_STATE_GREEN` + +### LED IDS + +The following are the supported LED identifiers that are accepted by the _led_ +parameter: + +* `LIBX52_LED_FIRE` +* `LIBX52_LED_A` +* `LIBX52_LED_B` +* `LIBX52_LED_D` +* `LIBX52_LED_E` +* `LIBX52_LED_T1` +* `LIBX52_LED_T2` +* `LIBX52_LED_T3` +* `LIBX52_LED_POV` +* `LIBX52_LED_CLUTCH` +* `LIBX52_LED_THROTTLE` + +Note that the LEDs referred to by `LIBX52_LED_FIRE` and `LIBX52_LED_THROTTLE` +support only the states `LIBX52_LED_STATE_OFF` and `LIBX52_LED_STATE_ON`. The +remaining LEDs support all the states with the exception of +`LIBX52_LED_STATE_ON`. + +## RETURN VALUES + +`libx52_led_state()` returns 0 on success, `-EINVAL` if the _x52_ parameter is +not valid, and `-ENOTSUP` if the _led_ and _state_ combination is not a +supported one. + +## SEE ALSO + +libx52_update(3) diff --git a/man/libx52_set_shift.3.ronn b/man/libx52_set_shift.3.ronn new file mode 100644 index 0000000..fc1bf80 --- /dev/null +++ b/man/libx52_set_shift.3.ronn @@ -0,0 +1,21 @@ +libx52_set_shift(3) -- turn the shift indicator on or off +========================================================= + +## SYNOPSIS + +`#include ` + +`int libx52_set_shift(libx52_device *` _x52_`, uint8_t ` _state_`)` + +## DESCRIPTION + +`libx52_set_shift()` can be used to set the state of the shift indicator on the +MFD to `on` (_state_ is non-zero) or `off` (_state_ is 0). + +## RETURN VALUE + +`libx52_set_shift()` returns 0 on success, and `-EINVAL` if _x52_ is not valid. + +## SEE ALSO + +libx52_update(3) diff --git a/man/libx52_set_text.3.ronn b/man/libx52_set_text.3.ronn new file mode 100644 index 0000000..15c73ad --- /dev/null +++ b/man/libx52_set_text.3.ronn @@ -0,0 +1,35 @@ +libx52_set_text(3) -- set the text on an MFD line +================================================= + +## SYNOPSIS + +`#include ` + +`int libx52_set_text(libx52_device *` _x52_`, uint8_t` _line_`, const char *` +_text_`, uint8_t` _length_`)` + +## DESCRIPTION + +The Multifunction display (MFD) on the Saitek X52 Pro supports 3 lines of up to +16 characters. This function will set the text into the internal data +structures. + +_text_ must be a pointer to an array of bytes, each byte represents a code point +on the MFD's internal character map. _length_ is the length of this array. + +_line_ must be **0**, **1** or **2** and refers to the first, second or third +line of the MFD respectively. _x52_ is a pointer returned by libx52_init(3). + +## RETURN VALUE + +`libx52_set_text()` returns 0 on success, and `-EINVAL` if either _x52_ is +invalid, or _line_ is outside of the accepted range. + +## LIMITATIONS + +`libx52_set_text()` can only store a maximum of 16 characters. Any additional +characters are discarded. + +## SEE ALSO + +libx52_update(3) diff --git a/man/libx52_update.3.ronn b/man/libx52_update.3.ronn new file mode 100644 index 0000000..e8692a5 --- /dev/null +++ b/man/libx52_update.3.ronn @@ -0,0 +1,19 @@ +libx52_update(3) -- update the X52 Pro +====================================== + +## SYNOPSIS + +`#include ` + +`int libx52_update(libx52_device *` _x52_`)` + +## DESCRIPTION + +All the standard `libx52_set_*` functions only set the internal data structures, +but do not actually write anything to the joystick. This function writes the +saved data to the joystick and resets the internal data structures. + +## RETURN VALUE + +`libx52_update()` returns 0 on success, and a non-zero error number on failure. + diff --git a/man/libx52_vendor_command.3.ronn b/man/libx52_vendor_command.3.ronn new file mode 100644 index 0000000..47dda02 --- /dev/null +++ b/man/libx52_vendor_command.3.ronn @@ -0,0 +1,27 @@ +libx52_vendor_command(3) -- write a raw vendor control packet +============================================================= + +## SYNOPSIS + +`#include ` + +`int libx52_vendor_command(libx52_device *` _x52_`, uint16_t ` _wIndex_ +`, uint16_t ` _wValue_ `)` + +## DESCRIPTION + +`libx52_vendor_command()` can be used to debug issues seen on the hardware, +however, it is not recommended for use by end users, as it can potentially +damage the hardware. + +## RETURN VALUE + +`libx52_vendor_command()` returns 0 on success, and a non-zero error number on +failure. + +## SEE ALSO + +libx52_set_text(3), libx52_set_led_state(3), libx52_set_clock(3), +libx52_set_clock_timezone(3), libx52_set_clock_format(3), +libx52_set_date_format(3), libx52_set_brightness(3), libx52_set_shift(3), +libx52_set_blink(3), libx52_update(3)