Aria  2.8.0
ArJoyHandler Class Reference

Interfaces to a computer joystick. More...

#include <ArJoyHandler.h>

Public Member Functions

 ArJoyHandler (bool useOSCal=true, bool useOldJoystick=false)
 Constructor. More...
 
void endCal (void)
 Ends the calibration process. More...
 
void getAdjusted (int *x, int *y, int *z=NULL)
 Gets the adjusted reading, as integers, based on the setSpeed. More...
 
double getAxis (unsigned int axis)
 Gets the floating (-1 to 1) location of the given joystick axis. More...
 
bool getButton (unsigned int button)
 Gets the button. More...
 
void getDoubles (double *x, double *y, double *z=NULL)
 Gets the adjusted reading, as floats, between -1.0 and 1.0. More...
 
unsigned int getNumAxes (void)
 Gets the number of axes the joystick has. More...
 
unsigned int getNumButtons (void)
 Gets the number of buttons the joystick has. More...
 
void getSpeeds (int *x, int *y, int *z)
 Gets the maximums for each axis. More...
 
void getStats (int *maxX, int *minX, int *maxY, int *minY, int *cenX, int *cenY)
 Gets the stats for the joystick, useful after calibrating to save values.
 
void getUnfiltered (int *x, int *y, int *z=NULL)
 Gets the unfilitered reading, mostly for internal use, maybe useful for Calibration. More...
 
bool getUseOSCal (void)
 Gets whether to just use OS calibration or not. More...
 
bool haveJoystick (void)
 Returns if the joystick was successfully initialized or not.
 
bool haveZAxis (void)
 Returns true if we definitely have a Z axis (we don't know in windows unless it moves)
 
bool init (void)
 Intializes the joystick, returns true if successful.
 
void setSpeeds (int x, int y, int z=0)
 Sets the maximums for the x, y and optionally, z axes.
 
void setStats (int maxX, int minX, int maxY, int minY, int cenX, int cenY)
 Sets the stats for the joystick, useful for restoring calibrated settings.
 
void setUseOSCal (bool useOSCal)
 Sets whether to just use OS calibration or not. More...
 
void startCal (void)
 Starts the calibration process. More...
 
 ~ArJoyHandler ()
 Destructor.
 

Protected Member Functions

void getData (void)
 
void getNewData (void)
 Handles the reading of the data into the bins.
 
void getOldData (void)
 

Protected Attributes

std::map< unsigned int, int > myAxes
 
std::map< unsigned int, bool > myButtons
 
int myCenX
 
int myCenY
 
bool myFirstData
 
bool myHaveZ
 
bool myInitialized
 
int myJoyData
 
int myJoyDesc
 
char myJoyNameTemp [512]
 
int myJoyNumber
 
ArTime myLastDataGathered
 
ArTime myLastOpenTry
 
int myMaxX
 
int myMaxY
 
int myMinX
 
int myMinY
 
FILE * myOldJoyDesc
 
int myPhysMax
 
int myTopX
 
int myTopY
 
int myTopZ
 
bool myUseOld
 
bool myUseOSCal
 

Detailed Description

Interfaces to a computer joystick.

This class is used to read data from a joystick device attached to the computer (usually via USB). The joystick handler keeps track of the minimum and maximums for both axes, updating them to constantly be better calibrated. The speeds set with setSpeed() influence what is returned by getAdjusted() or getDoubles().

The joystick device is not opened until init() is called. If there was an error connecting to the joystick device, it will return false, and haveJoystick() will return false. After calling init(), use getAdjusted() or getDoubles() to get values, and getButton() to check whether a button is pressed. setSpeed() may be called at any time to configure or reconfigure the range of the values returned by getAdjusted() and getDoubles().

To get the raw data instead, use getUnfiltered() or getAxis().

For example, if you want the X axis output to range from -1000 to 1000, and the Y axis output to range from -100 to 100, call setSpeed(1000, 100);.

The X joystick axis is usually the left-right axis, and Y is forward-back. If a joystick has a Z axis, it is usually a "throttle" slider or dial on the joystick. The usual way to drive a robot with a joystick is to use the X joystick axis for rotational velocity, and Y for translational velocity (note the robot coordinate system, this is its local X axis), and use the Z axis to adjust the robot's maximum driving speed.

Examples:
gpsRobotTaskExample.cpp, and joydriveActionExample.cpp.

Constructor & Destructor Documentation

◆ ArJoyHandler()

ArJoyHandler::ArJoyHandler ( bool  useOSCal = true,
bool  useOld = false 
)

Constructor.

Parameters
useOSCalif this is set then the joystick will just rely on the OS to calibrate, otherwise it will keep track of center min and max and use those values for calibration
useOlduse the old linux interface to the joystick

Member Function Documentation

◆ endCal()

void ArJoyHandler::endCal ( void  )

Ends the calibration process.

Ends the calibration, which also sets the center to where the joystick is when the function is called...

the center is never reset except in this function, whereas the min and maxes are constantly checked

See also
startCal

◆ getAdjusted()

void ArJoyHandler::getAdjusted ( int *  x,
int *  y,
int *  z = NULL 
)

Gets the adjusted reading, as integers, based on the setSpeed.

if useOSCal is true then this returns the readings as calibrated from the OS.

If useOSCal is false this finds the percentage of the distance between center and max (or min) then takes this percentage and multiplies it by the speeds given the class, and returns the values computed from this.

Parameters
xpointer to an integer in which to store the x value, which will be within the range [-1 * x given in setSpeeds(), x given in setSpeeds()]
ypointer to an integer in which to store the y value, which will be within the range [-1 * y given in setSpeeds(), y given in setSpeeds()]
zpointer to an integer in which to store the z value, which will be within the range [-1 * z given in setSpeeds(), z given in setSpeeds()]

Java Wrapper Library: Use the version of this method returning ArJoyVec3i

Python Wrapper Library: returns a tuple of (x, y, z) instead

◆ getAxis()

double ArJoyHandler::getAxis ( unsigned int  axis)

Gets the floating (-1 to 1) location of the given joystick axis.

Parameters
axisaxis to get, should range from 1 through getNumAxes()

now make sure its in there if (myAxes.find(axis) == myAxes.end()) return 0; return myAxes[axis]/128.0;

◆ getButton()

bool ArJoyHandler::getButton ( unsigned int  button)

Gets the button.

Parameters
buttonbutton to test for pressed, within the range 1 through getNumButtons()
Returns
true if the button is pressed, false otherwise

◆ getDoubles()

void ArJoyHandler::getDoubles ( double *  x,
double *  y,
double *  z = NULL 
)

Gets the adjusted reading, as floats, between -1.0 and 1.0.

If useOSCal is true then this gets normalized values (between -1.0 and 1.0) as calibrated by the OS.

In other words, the range [-1.0,1.0] is scaled to the calibrated range determined by the set maximum. If useOSCal is false this finds the percentage of the distance between center and max (or min) then takes this percentage and multiplies it by the speeds given the class, and returns the values computed from this.

Parameters
xpointer to an integer in which to store the x value. Will be within the range [-1.0, 1.0]
ypointer to an integer in which to store the y value. Will be within the range [-1.0, 1.0]
zpointer to an integer in which to store the z value. Will be within the range [-1.0, 1.0]

Python Wrapper Library: Returns a tuple of (x, y, z) instead

Java Wrapper Library: Use the version of this method returning ArJoyVec3f

Python Wrapper Library: Returns a tuple of (x, y, z) instead

◆ getNumAxes()

unsigned int ArJoyHandler::getNumAxes ( void  )

Gets the number of axes the joystick has.

Returns
the number of axes (axes are indexed as 1 through this number)

◆ getNumButtons()

unsigned int ArJoyHandler::getNumButtons ( void  )

Gets the number of buttons the joystick has.

Returns
the number of buttons (buttons are indexed as 1 through this number)

◆ getSpeeds()

void ArJoyHandler::getSpeeds ( int *  x,
int *  y,
int *  z 
)

Gets the maximums for each axis.

Java and Python Wrappers: Use the version of this method returning ArJoyVec3i

◆ getUnfiltered()

void ArJoyHandler::getUnfiltered ( int *  x,
int *  y,
int *  z = NULL 
)

Gets the unfilitered reading, mostly for internal use, maybe useful for Calibration.

This returns the raw value from the joystick...

with X and Y varying between -128 and 128. This data normally shouldn't be used except in calibration since it can give very uncentered or inconsistent readings. For example its not uncommon for a joystick to move 10 to the right but 50 or 100 to the left, so if you aren't adjusting for this you get a robot (or whatever) that goes left really fast, but will hardly go right. Instead you should use getAdjusted() exclusively except for calibration, or informational purposes.

Parameters
xpointer to an integer in which to store x value
ypointer to an integer in which to store y value
zpointer to an integer in which to store z value

Java Wrapper Library: Use the version of this method returning ArJoyVec3i

Python Wrapper Library: Returns a tuple of (x, y, z) instead

◆ getUseOSCal()

bool ArJoyHandler::getUseOSCal ( void  )

Gets whether to just use OS calibration or not.

Returns
if useOSCal is set then the joystick will just rely on the OS to calibrate, otherwise it will keep track of center min and max and use those values for calibration

◆ setUseOSCal()

void ArJoyHandler::setUseOSCal ( bool  useOSCal)

Sets whether to just use OS calibration or not.

Parameters
useOSCalif this is set then the joystick will just rely on the OS to calibrate, otherwise it will keep track of center min and max and use those values for calibration

◆ startCal()

void ArJoyHandler::startCal ( void  )

Starts the calibration process.

Starts the calibration, which resets all the min and max variables as well as the center variables.

See also
endCal

The documentation for this class was generated from the following files: