mirror of https://github.com/nirenjan/libx52.git
Clarify Doxygen comments for libx52
parent
533a472b10
commit
6b89a9d7f9
|
|
@ -121,21 +121,28 @@ typedef enum {
|
|||
*/
|
||||
LIBX52_LED_STATE_ON,
|
||||
|
||||
/** LED displays red color. This is not supported by single state LEDs */
|
||||
/** LED displays red color. This is not supported by single color LEDs */
|
||||
LIBX52_LED_STATE_RED,
|
||||
|
||||
/** LED displays amber color. This is not supported by single state LEDs */
|
||||
/** LED displays amber color. This is not supported by single color LEDs */
|
||||
LIBX52_LED_STATE_AMBER,
|
||||
|
||||
/** LED displays green color. This is not supported by single state LEDs */
|
||||
/** LED displays green color. This is not supported by single color LEDs */
|
||||
LIBX52_LED_STATE_GREEN,
|
||||
} libx52_led_state;
|
||||
|
||||
/**
|
||||
* @brief Initialize the X52 library
|
||||
*
|
||||
* Sets up any internal data structures to access the joystick, all
|
||||
* calls to libx52 use the returned pointer to control the device.
|
||||
* This function initializes the libx52 library, sets up any internal data
|
||||
* structures to access the joystick, and returns a \ref libx52_device pointer.
|
||||
* All calls to libx52 use the returned pointer to control the device.
|
||||
*
|
||||
* If no joystick is found `libx52_init()` returns _NULL_.
|
||||
*
|
||||
* @par Limitations
|
||||
* This function does not support hotplugging. The joystick must be plugged in
|
||||
* before calling this function.
|
||||
*
|
||||
* @returns a pointer to the detected \ref libx52_device
|
||||
*/
|
||||
|
|
@ -144,6 +151,10 @@ libx52_device * libx52_init(void);
|
|||
/**
|
||||
* @brief Exit the library and free up any resources used
|
||||
*
|
||||
* This function releases any resources allocated by \ref libx52_init and
|
||||
* terminates the library. Using the freed device now is invalid and can
|
||||
* cause errors.
|
||||
*
|
||||
* @param[in] dev Pointer to the device
|
||||
* @returns None
|
||||
*/
|
||||
|
|
@ -155,13 +166,25 @@ void libx52_exit(libx52_device *dev);
|
|||
* The Multifunction display (MFD) supports 3 lines of up to 16 characters.
|
||||
* This function will set the text into the internal data structures.
|
||||
*
|
||||
* \p text must be a pointer to an array of bytes, each byte represents a code
|
||||
* point on the MFD's internal character map. \p length is the length of this
|
||||
* array.
|
||||
*
|
||||
* \p line must be \b 0, \b 1, or \b 2 and refers to the first, second or third
|
||||
* line of the MFD respectively.
|
||||
*
|
||||
* @par Limitations
|
||||
* This function can only store a maximum of 16 characters per line. Any
|
||||
* additional characters are silently discarded.
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] line Line to be updated (0, 1 or 2)
|
||||
* @param[in] text Pointer to the text string. The text must be mapped to
|
||||
* the code page of the X52 display.
|
||||
* @param[in] length Length of the text to display
|
||||
*
|
||||
* @returns 0 on success, -errno on failure.
|
||||
* @returns 0 on success, \c -EINVAL if either \p x52 is invalid, or \p line is
|
||||
* outside the accepted range.
|
||||
*/
|
||||
int libx52_set_text(libx52_device *x52, uint8_t line, const char *text, uint8_t length);
|
||||
|
||||
|
|
@ -169,13 +192,22 @@ int libx52_set_text(libx52_device *x52, uint8_t line, const char *text, uint8_t
|
|||
* @brief Set the LED state
|
||||
*
|
||||
* The X52 pro has several LEDs that can be individually controlled. This
|
||||
* function will allow you to control them.
|
||||
* function allows you to set the state of each LED in the internal data
|
||||
* structures.
|
||||
*
|
||||
* Note that the LEDs referred to by \ref LIBX52_LED_FIRE and \ref
|
||||
* LIBX52_LED_THROTTLE support only the states \ref LIBX52_LED_STATE_OFF and
|
||||
* \ref LIBX52_LED_STATE_ON. The remaining LEDs support all the states with
|
||||
* the exception of \ref LIBX52_LED_STATE_ON.
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] led LED identifier (refer \ref libx52_led_id)
|
||||
* @param[in] state State of the LED (refer \ref libx52_led_state)
|
||||
*
|
||||
* @returns 0 on success, -errno on failure.
|
||||
* @returns 0 on success, \c -EINVAL if the \p x52 parameter is not valid, and
|
||||
* \c -ENOTSUP if the \p led and \p state combination is not a supported one.
|
||||
* The API also returns \c -ENOTSUP if the probed joystick is not an X52 Pro,
|
||||
* but the non-Pro X52 variant.
|
||||
*/
|
||||
int libx52_set_led_state(libx52_device *x52,
|
||||
libx52_led_id led,
|
||||
|
|
@ -185,15 +217,25 @@ int libx52_set_led_state(libx52_device *x52,
|
|||
* @brief Set the clock
|
||||
*
|
||||
* This function sets the primary clock's date and time with the specified Unix
|
||||
* time value. An additional argument specifies whether this uses local time or
|
||||
* GM time.
|
||||
* time value. \p time can be obtained from \c time(2). \p local controls
|
||||
* whether the primary clock displays local time or GMT.
|
||||
*
|
||||
* If this function is called again within the same minute as calculated by
|
||||
* \c localtime(3) or \c gmtime(3), it will return \c -EAGAIN, as it does not
|
||||
* require any updates to be written to the joystick. However, if the call
|
||||
* changes the timezone from local time to GMT or vice-versa, then the function
|
||||
* will return 0, since it requires 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
|
||||
* using \ref libx52_set_clock_timezone.
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] time Time value from \ref time(3)
|
||||
* @param[in] time Time value from \c time(3)
|
||||
* @param[in] local 0 for GM time, non-zero for localtime
|
||||
*
|
||||
* @returns 0 on success, -EAGAIN if no change from previous time,
|
||||
* -errno on failure
|
||||
* @returns 0 on success, \c -EAGAIN if no change from previous time,
|
||||
* \c -EINVAL if \p x52 is not valid.
|
||||
*/
|
||||
int libx52_set_clock(libx52_device *x52, time_t time, int local);
|
||||
|
||||
|
|
@ -204,8 +246,8 @@ int libx52_set_clock(libx52_device *x52, time_t time, int local);
|
|||
* clocks are controlled as an offset from the primary clock in minutes.
|
||||
* However, for convenience, the X52 library calculates this offset internally
|
||||
* and only requires you to set the timezone as the number of minutes offset
|
||||
* from GMT. Offset is limited to +/- 1440 minutes, and any offset outside
|
||||
* this range will result in a return value of -EDOM
|
||||
* from GMT. \p offset is limited to +/- 1440 minutes, and any offset outside
|
||||
* this range will result in a return value of \c -EDOM
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] clock \ref libx52_clock_id, cannot be \ref
|
||||
|
|
@ -213,7 +255,9 @@ int libx52_set_clock(libx52_device *x52, time_t time, int local);
|
|||
* @param[in] offset Offset in minutes from GMT (east is positive, west
|
||||
* is negative)
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, \c -EINVAL if \p x52 is invalid, \c -ENOTSUP if
|
||||
* \p clock is \ref LIBX52_CLOCK_1, \c -EDOM if \p offset is more than +/-
|
||||
* 24 hours.
|
||||
*/
|
||||
int libx52_set_clock_timezone(libx52_device *x52,
|
||||
libx52_clock_id clock,
|
||||
|
|
@ -226,11 +270,16 @@ int libx52_set_clock_timezone(libx52_device *x52,
|
|||
* display it in 12-hour (AM/PM) or 24-hour format. The default format if not
|
||||
* specified is 12-hour.
|
||||
*
|
||||
* @par Limitations
|
||||
* The hardware has a limitation that it cannot display 12:00 am in 12 hour
|
||||
* mode - instead it will display as 00:00 am
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] clock \ref libx52_clock_id
|
||||
* @param[in] format \ref libx52_clock_format
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, \c -EINVAL if \p x52 is not valid, or if either of
|
||||
* \p clock or \p format are outside their respective ranges.
|
||||
*/
|
||||
int libx52_set_clock_format(libx52_device *x52,
|
||||
libx52_clock_id clock,
|
||||
|
|
@ -244,7 +293,7 @@ int libx52_set_clock_format(libx52_device *x52,
|
|||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] format \ref libx52_date_format
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, \c -EINVAL if \p x52 is not valid
|
||||
*/
|
||||
int libx52_set_date_format(libx52_device *x52, libx52_date_format format);
|
||||
|
||||
|
|
@ -252,13 +301,15 @@ int libx52_set_date_format(libx52_device *x52, libx52_date_format format);
|
|||
* @brief Set the MFD or LED brightness
|
||||
*
|
||||
* The brightness of the MFD display and the button LEDs can be controlled
|
||||
* individually.
|
||||
* individually. \p brightness should be a value between 0 and 128. While
|
||||
* the library does not fail on values higher than 128, the effect may not
|
||||
* be what is intended.
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] mfd 0 for LED brightness, 1 for MFD brightness
|
||||
* @param[in] brightness Brightness level to set
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, \c -EINVAL if \p x52 is not valid.
|
||||
*/
|
||||
int libx52_set_brightness(libx52_device *x52, uint8_t mfd, uint16_t brightness);
|
||||
|
||||
|
|
@ -271,7 +322,7 @@ int libx52_set_brightness(libx52_device *x52, uint8_t mfd, uint16_t brightness);
|
|||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] state 0 for off, 1 for on
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, \c -EINVAL if \p x52 is not valid
|
||||
*/
|
||||
int libx52_set_shift(libx52_device *x52, uint8_t state);
|
||||
|
||||
|
|
@ -283,7 +334,7 @@ int libx52_set_shift(libx52_device *x52, uint8_t state);
|
|||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] state 0 for off, 1 for on
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, \c -EINVAL if \p x52 is not valid
|
||||
*/
|
||||
int libx52_set_blink(libx52_device *x52, uint8_t state);
|
||||
|
||||
|
|
@ -292,25 +343,28 @@ int libx52_set_blink(libx52_device *x52, uint8_t state);
|
|||
*
|
||||
* All the 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.
|
||||
* data to the joystick and updates the internal data structures as necessary.
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, non-zero error number on failure
|
||||
*/
|
||||
int libx52_update(libx52_device *x52);
|
||||
|
||||
/**
|
||||
* @brief Write a raw vendor control packet
|
||||
*
|
||||
* This can be used to debug issues seen on the hardware, however, it is not
|
||||
* This function sends the control packet immediately to the hardware, without
|
||||
* having to wait for a call to \ref libx52_update.
|
||||
*
|
||||
* This can be used to debug issues seen on the hardware, however, it is \b NOT
|
||||
* recommended for use by end users, as it can potentially damage the hardware.
|
||||
*
|
||||
* @param[in] x52 Pointer to the device
|
||||
* @param[in] index wIndex in the USB packet
|
||||
* @param[in] value wValue in the USB packet
|
||||
*
|
||||
* @returns 0 on success, -errno on failure
|
||||
* @returns 0 on success, non-zero error number on failure
|
||||
*/
|
||||
int libx52_vendor_command(libx52_device *x52, uint16_t index, uint16_t value);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue