USB Interface to USB joystick/game pad, such as Logitech 'Dual Action' game pad. More...

#include <USBJoystick.h>

Public Member Functions
	USBJoystick ()
void	init ()
void	run ()
uint8_t	stickValue (uint8_t stick)
boolean	buttonValue (uint8_t button)
uint8_t	hatValue (uint8_t hat)
void	setStickNewValueCallback (void(*cb)(uint8_t stick, uint8_t value))
void	setButtonNewValueCallback (void(*cb)(uint8_t button, uint8_t value))
void	setHatNewValueCallback (void(*cb)(uint8_t hat, uint8_t value))
void	setStickValueDidChangeCallback (void(*cb)(uint8_t stick, uint8_t value))
void	setButtonValueDidChangeCallback (void(*cb)(uint8_t button, uint8_t value))
void	setHatValueDidChangeCallback (void(*cb)(uint8_t hat, uint8_t value))

Protected Member Functions
boolean	device_init ()
void	poll ()
virtual void	stickNewValue (uint8_t stick, uint8_t value)
virtual void	buttonNewValue (uint8_t button, boolean value)
virtual void	hatNewValue (uint8_t hat, uint8_t value)
virtual void	stickValueDidChange (uint8_t stick, uint8_t value)
virtual void	buttonValueDidChange (uint8_t button, boolean value)
virtual void	hatValueDidChange (uint8_t hat, uint8_t value)

Detailed Description

USB Interface to USB joystick/game pad, such as Logitech 'Dual Action' game pad.

Overview

A class that interfaces with a USB Joystick or game pad. It can be subclassed to get control when new input values are read, or when they actually change. Alternatively, you can set up callback functions to be called when new input values are read, or when they actually change.

Input data such as stick positions, button presses and hat-switch directions are read from the device and delivered to the calling application.

USBJoystick uses the USB_Host_Shield library to initialise and interrogate a USB joystick or game pad. When the task() function is called, an attempt to read new values from the joystick is made every USBJOYSTICK_POLL_INTERVAL milliseconds. If successful the NewValue virtual functions are called. These in turn call the ValueDidChange virtual functions if the value changed since last poll. After the poll the new values can also be read with the data accessor functions.

The virtual functions will call their respective callbacks if callback functions have been set up.

Therefore developers have several choices for getting input data from a device:

subclass USBJoystick and override the *NewValue() and/or *ValueDidChange() functions.
set callback functions with set*NewValueCallback() and set*ValueDidChangeCallback() functions
Asynchronously read current values with the *Value() functions.

Input indexes

The joystick/game pad is considered to have a number of joysticks, buttons and hat switches. In order to identifiy which joysticks, buttons or hat switch is being referred to in callbacks etc, an index number is used. Macros can be used to refer to specific items by name, see the USBJOYSTICK_STICK_*, USBJOYSTICK_BUTTON_* and USBJOYSTICK_HAT_* macros. The Logitech Dula Action game pad has 4 sticks (really 2 physical sticks with vertical and horizontal movement), 13 buttons and 1 hat switch.

Input Device Values

Stick positions are represented as 8 bit unsigned integers:

0 is fully left or up
255 is fully right or down

Button positions are represented by booleans:

true - button is pressed (in the case of MODE button, mode is enabled and the red light is on)
false - otherwise

Hat switch positions are represented as 8 bit unsigned integers. The current hat position is one of USBJOYSTICK_HAT_POS_*.

Constructor & Destructor Documentation

USBJoystick::USBJoystick ( )

Constructor. Stick positions are initialised to 0x80, buttons to false and hat switches to idle

Member Function Documentation

void USBJoystick::buttonNewValue	(	uint8_t	button,
		boolean	value
	)

protectedvirtual

This virtual function is called when a new button value is read from the USB device Default implementation calls the apropriate callback (if set) then calls buttonValueDidChange() if the value changed since the last poll. Subclasses may override this to change get control for each value read and change the default behaviour

Parameters:

[in]	button	The button index, one of USBJOYSTICK_BUTTON_*
[in]	value	The new button value

References buttonValueDidChange().

Referenced by poll().

boolean USBJoystick::buttonValue ( uint8_t button )

Read the current value of a button param[in] button The button index. One of USBJOYSTICK_BUTTON_*

Returns:: the most recently read button position value

void USBJoystick::buttonValueDidChange	(	uint8_t	button,
		boolean	value
	)

protectedvirtual

This virtual function is called when a button value changes Default implementation calls the apropriate callback (if set)

Parameters:

[in]	button	The button index, one of USBJOYSTICK_BUTTON_*
[in]	value	The new button value

Referenced by buttonNewValue().

boolean USBJoystick::device_init ( )

protected

Initialises the USB hardware. Internal use: should not be called directly.

Returns:: true if initialisation was successful

Referenced by run().

void USBJoystick::hatNewValue	(	uint8_t	hat,
		uint8_t	value
	)

protectedvirtual

This virtual function is called when a new hat switch value is read from the USB device Default implementation calls the apropriate callback (if set) then calls hatValueDidChange() if the value changed since the last poll. Subclasses may override this to change get control for each value read and change the default behaviour

Parameters:

[in]	hat	The hat switch index, one of USBJOYSTICK_HAT_*
[in]	value	The new hat position value

References hatValueDidChange().

Referenced by poll().

uint8_t USBJoystick::hatValue ( uint8_t hat )

Read the current value of a joystick

Parameters:

[in] hat The stick index. One of USBJOYSTICK_HAT_*

Returns:: the most recently read hat position value, one of USBJOYSTICK_HAT_POS_*

void USBJoystick::hatValueDidChange	(	uint8_t	hat,
		uint8_t	value
	)

protectedvirtual

This virtual function is called when a hat switch value changes Default implementation calls the apropriate callback (if set)

Parameters:

[in]	hat	The hat index, one of USBJOYSTICK_HAT_*
[in]	value	The new hat switch value

Referenced by hatNewValue().

void USBJoystick::init ( )

Library initialisation. Must be called once during setup() Enables the USB hardware and delays 200msec

void USBJoystick::poll ( )

protected

Polls the USB device for a new reading. Internal use: should not be called directly.

References buttonNewValue(), hatNewValue(), and stickNewValue().

Referenced by run().

void USBJoystick::run ( )

USB Device regular poll function. Attempts to read current data from the USB device. If successful, calls the *NewValue() and/or *ValueDidChange() functions, and any calbacks if so configured. This must be called as often as possible in your main loop(). Calls the intenal poll() functi0on every USBJOYSTICK_POLL_INTERVAL milliseconds

References device_init(), and poll().

void USBJoystick::setButtonNewValueCallback ( void(*)(uint8_t button, uint8_t value) cb )

Set a callback to be called when a button value is read from the usb device. Overrides any previously set callback. May be called at any time to set or change the callback.

Parameters: