299 lines
12 KiB
C
299 lines
12 KiB
C
/****************************************************************************
|
|
* include/nuttx/input/ajoystick.h
|
|
*
|
|
* Copyright (C) 2014 Gregory Nutt. All rights reserved.
|
|
* Author: Gregory Nutt <gnutt@nuttx.org>
|
|
*
|
|
* Redistribution and use in source and binary forms, with or without
|
|
* modification, are permitted provided that the following conditions
|
|
* are met:
|
|
*
|
|
* 1. Redistributions of source code must retain the above copyright
|
|
* notice, this list of conditions and the following disclaimer.
|
|
* 2. Redistributions in binary form must reproduce the above copyright
|
|
* notice, this list of conditions and the following disclaimer in
|
|
* the documentation and/or other materials provided with the
|
|
* distribution.
|
|
* 3. Neither the name NuttX nor the names of its contributors may be
|
|
* used to endorse or promote products derived from this software
|
|
* without specific prior written permission.
|
|
*
|
|
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
|
|
* FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
|
|
* COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
|
|
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
|
|
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
|
|
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
|
|
* ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
* POSSIBILITY OF SUCH DAMAGE.
|
|
*
|
|
****************************************************************************/
|
|
|
|
/* This header file provides definition for a standard analog joystick
|
|
* interface. An analog joystick refers to a joystick that provides X/Y
|
|
* positional data as integer values such as might be provides by Analog-
|
|
* to-Digital Conversion (ADC). The analog positional data may also be
|
|
* accompanied by discrete button data.
|
|
*
|
|
* The analog joystick driver exports a standard character driver
|
|
* interface. By convention, the analog joystick is registered as an input
|
|
* device at /dev/ajoyN where N uniquely identifies the driver instance.
|
|
*
|
|
* This header file documents the generic interface that all NuttX analog
|
|
* joystick devices must conform. It adds standards and conventions on top
|
|
* of the standard character driver interface.
|
|
*/
|
|
|
|
#ifndef __INCLUDE_NUTTX_INPUT_AJOYSTICK_H
|
|
#define __INCLUDE_NUTTX_INPUT_AJOYSTICK_H
|
|
|
|
/****************************************************************************
|
|
* Included Files
|
|
****************************************************************************/
|
|
|
|
#include <nuttx/config.h>
|
|
#include <nuttx/fs/ioctl.h>
|
|
|
|
/****************************************************************************
|
|
* Pre-processor Definitions
|
|
****************************************************************************/
|
|
/* Configuration ************************************************************/
|
|
|
|
#ifndef CONFIG_AJOYSTICK_NPOLLWAITERS
|
|
# define CONFIG_AJOYSTICK_NPOLLWAITERS 2
|
|
#endif
|
|
|
|
/* Joystick Interface *******************************************************/
|
|
/* These definitions provide the meaning of all of the bits that may be
|
|
* reported in the ajoy_buttonset_t bitset.
|
|
*/
|
|
|
|
#define AJOY_BUTTON(n) ((n)-1) /* Bit n-1: Button n, n=1..8 */
|
|
#define AJOY_BUTTON_1 (0) /* Bit 0: Button 1 */
|
|
#define AJOY_BUTTON_2 (1) /* Bit 1: Button 2 */
|
|
#define AJOY_BUTTON_3 (2) /* Bit 2: Button 3 */
|
|
#define AJOY_BUTTON_4 (3) /* Bit 3: Button 4 */
|
|
#define AJOY_BUTTON_5 (4) /* Bit 4: Button 5 */
|
|
#define AJOY_BUTTON_6 (5) /* Bit 5: Button 6 */
|
|
#define AJOY_BUTTON_7 (6) /* Bit 6: Button 7 */
|
|
#define AJOY_BUTTON_8 (7) /* Bit 7: Button 8 */
|
|
#define AJOY_NBUTTONS (8) /* Total number of buttons */
|
|
|
|
#define AJOY_BUTTON_1_BIT (1 << AJOY_BUTTON_1) /* 1:Button 1 pressed */
|
|
#define AJOY_BUTTON_2_BIT (1 << AJOY_BUTTON_2) /* 1:Button 2 pressed */
|
|
#define AJOY_BUTTON_3_BIT (1 << AJOY_BUTTON_3) /* 1:Button 3 pressed */
|
|
#define AJOY_BUTTON_4_BIT (1 << AJOY_BUTTON_4) /* 1:Button 4 pressed */
|
|
#define AJOY_BUTTON_5_BIT (1 << AJOY_BUTTON_5) /* 1:Button 5 pressed */
|
|
#define AJOY_BUTTON_6_BIT (1 << AJOY_BUTTON_6) /* 1:Button 6 pressed */
|
|
#define AJOY_BUTTON_7_BIT (1 << AJOY_BUTTON_7) /* 1:Button 7 pressed */
|
|
#define AJOY_BUTTON_8_BIT (1 << AJOY_BUTTON_8) /* 1:Button 8 pressed */
|
|
#define AJOY_BUTTONS_ALL 0xff /* Set of all buttons */
|
|
|
|
/* Typical usage */
|
|
|
|
#define AJOY_BUTTON_SELECT AJOY_BUTTON_1
|
|
#define AJOY_BUTTON_FIRE AJOY_BUTTON_2
|
|
#define AJOY_BUTTON_JUMP AJOY_BUTTON_3
|
|
|
|
#define AJOY_BUTTON_SELECT_BIT AJOY_BUTTON_1_BIT
|
|
#define AJOY_BUTTON_FIRE_BIT AJOY_BUTTON_2_BIT
|
|
#define AJOY_BUTTON_JUMP_BIT AJOY_BUTTON_3_BIT
|
|
|
|
/* IOCTL commands
|
|
*
|
|
* Discrete joystick drivers do not support the character driver write() or
|
|
* seek() methods. The remaining driver methods behave as follows:
|
|
*
|
|
* 1) The read() method will always return a single value of size
|
|
* struct ajoy_sample_s represent the current joystick positional and the
|
|
* state of all joystick buttons. read() never blocks. X an Y position
|
|
* data is raw converted data. Zeroing and scaling must be performed by
|
|
* the application.
|
|
* 2) The poll() method can be used to notify a client if there is a change
|
|
* in any of the joystick button inputs. This feature, of course,
|
|
* depends upon interrupt GPIO support from the platform. NOTE: that
|
|
* semantics of poll() for POLLIN are atypical: The successful poll
|
|
* means that the button data has changed and has nothing to with the
|
|
* availability of data to be read; data is always available to be
|
|
* read.
|
|
* 3) The ioctl() method supports the commands documented below:
|
|
*/
|
|
|
|
/* Command: AJOYIOC_SUPPORTED
|
|
* Description: Report the set of button events supported by the hardware;
|
|
* Argument: A pointer to writeable integer value in which to return the
|
|
* set of supported buttons.
|
|
* Return: Zero (OK) on success. Minus one will be returned on failure
|
|
* with the errno value set appropriately.
|
|
*/
|
|
|
|
#define AJOYIOC_SUPPORTED _AJOYIOC(0x0001)
|
|
|
|
/* Command: AJOYIOC_POLLEVENTS
|
|
* Description: Specify the set of button events that can cause a poll()
|
|
* to awaken. The default is all button depressions and all
|
|
* button releases (all supported buttons);
|
|
* Argument: A read-only pointer to an instance of struct ajoy_pollevents_s
|
|
* Return: Zero (OK) on success. Minus one will be returned on failure
|
|
* with the errno value set appropriately.
|
|
*/
|
|
|
|
#define AJOYIOC_POLLEVENTS _AJOYIOC(0x0002)
|
|
|
|
/* Command: AJOYIOC_REGISTER
|
|
* Description: Register to receive a signal whenever there is a change in
|
|
* any of the joystick analog inputs. This feature, of
|
|
* course, depends upon interrupt GPIO support from the
|
|
* platform.
|
|
* Argument: A read-only pointer to an instance of struct ajoy_notify_s
|
|
* Return: Zero (OK) on success. Minus one will be returned on failure
|
|
* with the errno value set appropriately.
|
|
*/
|
|
|
|
#define AJOYIOC_REGISTER _AJOYIOC(0x0003)
|
|
|
|
/****************************************************************************
|
|
* Public Types
|
|
****************************************************************************/
|
|
/* This type is a bit set that contains the state of all analog joystick
|
|
* buttons.
|
|
*/
|
|
|
|
typedef uint8_t ajoy_buttonset_t;
|
|
|
|
/* A reference to this structure is provided with the AJOYIOC_POLLEVENTS IOCTL
|
|
* command and describes the conditions under which the client would like
|
|
* to receive notification.
|
|
*/
|
|
|
|
struct ajoy_pollevents_s
|
|
{
|
|
ajoy_buttonset_t ap_press; /* Set of button depressions to wake up the poll */
|
|
ajoy_buttonset_t ap_release; /* Set of button releases to wake up the poll */
|
|
};
|
|
|
|
/* A reference to this structure is provided with the AJOYIOC_REGISTER IOCTL
|
|
* command and describes the conditions under which the client would like
|
|
* to receive notification.
|
|
*/
|
|
|
|
struct ajoy_notify_s
|
|
{
|
|
ajoy_buttonset_t an_press; /* Set of button depressions to be notified */
|
|
ajoy_buttonset_t an_release; /* Set of button releases to be notified */
|
|
uint8_t an_signo; /* Signal number to use in the notification */
|
|
};
|
|
|
|
/* This structure is returned by read() and provides the sample state of the
|
|
* analog joystick.
|
|
*
|
|
* NOTE: that this structure is equivalent to the struct mouse_report_s
|
|
* structure (with no wheel) defined in include/nuttx/input/mouse.h and can
|
|
* be used interchangeably in certain contexts.
|
|
*/
|
|
|
|
struct ajoy_sample_s
|
|
{
|
|
ajoy_buttonset_t as_buttons; /* State of all buttons */
|
|
/* Possibly padded with 1 byte here */
|
|
int16_t as_x; /* X/horizontal position */
|
|
int16_t as_y; /* Y/vertical position */
|
|
};
|
|
|
|
/* This is the type of the analog joystick interrupt handler used with
|
|
* the struct ajoy_lowerhalf_s enable() method.
|
|
*/
|
|
|
|
struct ajoy_lowerhalf_s;
|
|
typedef CODE void (*ajoy_handler_t)
|
|
(FAR const struct ajoy_lowerhalf_s *lower, FAR void *arg);
|
|
|
|
/* The analog joystick driver is a two-part driver:
|
|
*
|
|
* 1) A common upper half driver that provides the common user interface to
|
|
* the joystick,
|
|
* 2) Platform-specific lower half drivers that provide the interface
|
|
* between the common upper half and the platform analog and discrete
|
|
* inputs.
|
|
*
|
|
* This structure defines the interface between an instance of the lower
|
|
* half driver and the common upper half driver. Such an instance is
|
|
* passed to the upper half driver when the driver is initialized, binding
|
|
* the upper and lower halves into one driver.
|
|
*/
|
|
|
|
struct ajoy_lowerhalf_s
|
|
{
|
|
/* Return the set of buttons supported on the analog joystick device */
|
|
|
|
CODE ajoy_buttonset_t (*al_supported)(FAR const struct ajoy_lowerhalf_s *lower);
|
|
|
|
/* Return the current state of all analog joystick position and button data */
|
|
|
|
CODE int (*al_sample)(FAR const struct ajoy_lowerhalf_s *lower,
|
|
FAR struct ajoy_sample_s *sample);
|
|
|
|
/* Return the current state of button data (only) */
|
|
|
|
CODE ajoy_buttonset_t (*al_buttons)(FAR const struct ajoy_lowerhalf_s *lower);
|
|
|
|
/* Enable interrupts on the selected set of joystick buttons. An empty
|
|
* set will disable all interrupts.
|
|
*/
|
|
|
|
CODE void (*al_enable)(FAR const struct ajoy_lowerhalf_s *lower,
|
|
ajoy_buttonset_t press, ajoy_buttonset_t release,
|
|
ajoy_handler_t handler, FAR void *arg);
|
|
};
|
|
|
|
/****************************************************************************
|
|
* Public Data
|
|
****************************************************************************/
|
|
|
|
#ifdef __cplusplus
|
|
#define EXTERN extern "C"
|
|
extern "C"
|
|
{
|
|
#else
|
|
#define EXTERN extern
|
|
#endif
|
|
|
|
/****************************************************************************
|
|
* Public Function Prototypes
|
|
****************************************************************************/
|
|
|
|
/****************************************************************************
|
|
* Name: ajoy_register
|
|
*
|
|
* Description:
|
|
* Bind the lower half analog joystick driver to an instance of the upper
|
|
* half analog joystick driver and register the composite character
|
|
* driver as the specified device.
|
|
*
|
|
* Input Parameters:
|
|
* devname - The name of the analog joystick device to be registered.
|
|
* This should be a string of the form "/dev/ajoyN" where N is the the
|
|
* minor device number.
|
|
* lower - An instance of the platform-specific analog joystick lower
|
|
* half driver.
|
|
*
|
|
* Returned Values:
|
|
* Zero (OK) is returned on success. Otherwise a negated errno value is
|
|
* returned to indicate the nature of the failure.
|
|
*
|
|
****************************************************************************/
|
|
|
|
int ajoy_register(FAR const char *devname,
|
|
FAR const struct ajoy_lowerhalf_s *lower);
|
|
|
|
#undef EXTERN
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif /* __INCLUDE_NUTTX_INPUT_AJOYSTICK_H */
|