User Manual

GNU Octave Joystick Package

The Joystick toolkit is a set of Joystick file I/O routines for GNU
Octave

1 Installing and loading

The Joystick toolkit must be installed and then loaded to be used.

It can be installed in GNU Octave directly from octave-forge, or can be
installed in an off-line mode via a downloaded tarball.

The toolkit has a dependency on the SDL library
(http://www.libsdl.org/), so it must be installed in order to
successfully install the Joystick toolkit.

For Fedora: 'yum install sdl2-devel'

For Ubuntu: 'apt install libsdl2-dev'

The toolkit must be then be loaded once per each GNU Octave session in
order to use its functionality.

1.1 Online Direct install

With an internet connection available, the Joystick package can be
installed from the octave-joystick website using the following command
within GNU Octave:

 pkg install https://sourceforge.net/projects/octave-joystick/files/v0.0.3/joystick-0.0.3.tar.gz/download

The latest released version of the toolkit will be downloaded and
installed.

1.2 Off-line install

With the Joystick toolkit package already downloaded, and in the current
directory when running GNU Octave, the package can be installed using
the following command within GNU Octave:

 pkg install joystick-0.0.3.tar.gz

1.3 Loading

Regardless of the method of installing the Joystick toolkit, in order to
use its functions, the toolkit must be loaded using the pkg load
command:

 pkg load joystick

The toolkit must be loaded on each GNU Octave session.

2 Basic Usage Overview

A list of available joysticks available can be obtained using the
vrjoysticklist function.

 > vrjoysticklist
 id name                   forcefeedbacksupported
  1 logitech dual action   0

The ID value is then used to create a joystick object.
> joy = vrjoystick(1)
joy =

   Joystick object
       ID: 1
     Name: Logitech Dual Action

The capabilities of the joystick can be read to determine number of axis
and buttons are available.

 > caps(joy)
 ans =

   scalar structure containing the fields:

     Axes = 4
     Buttons = 12
     POVs = 1
     Forces = 0

The axis and button states can be read for any axis or button number.

 > a1 = axis(joy, 1)
 a1 = 0

 > b1 = button(joy, 1)
 b1 = 0

3 Function Reference

The functions currently available in the Joystick toolkit are described
below;

3.1 Utility Functions

3.1.1 isvrjoystick

-- : RETVAL = isvrjoystick (OBJ)
Check if input value is a vrjoystick object

Function is essentially just a call of ' retval = isa(obj,
"octave_joystick"); '

Inputs
......

OBJ - The object to check

Outputs
.......

RETVAL is true, if obj is an vrjoystick object, false otherwise.

See also: vrjoystick.

3.1.2 vrjoysticklist

-- : vrjoysticklist ()
-- : JOYLIST = vrjoysticklist ()
Get or print the available joystick devices.

Inputs
......

None

Outputs
.......

JOYLIST - a list of joystick ID, Name, ForceFeedbackSupported
structures.

Examples
........

Display available joysticks

vrjoysticklist;

Get a list available joysticks to a variable

   joylist = joysticklist;

The list will contain ID, Name and ForceFeedbackSupported entries
for each joystick.

See also: vrjoystick.

3.2 Joystick Functions

3.2.1 @octave_joystick/axis

-- : JOY = axis (JOY, ID)
Get the value of axis ID on joystick JOY.

Inputs
......

JOY - a previously opened joystick object
ID - a positive numeric id for the joystick axis to use

ID can be a vector of ids to allow getting multiple axis.

Outputs
.......

VALUE - value of the axis between -1 .. 1.

VALUE will be a vector of values when getting multiple axis.

Examples
........

Open device 1 and get value of axis 1

   joy = vrjoystick(1);
   val = axis(joy, 1)

See also: vrjoystick.

3.2.2 @octave_joystick/button

-- : JOY = button (JOY, ID)
Get the value of button ID on joystick JOY.

 Inputs
 ......

 JOY - a previously opened joystick object
 ID - a positive numeric id for the joystick button to use

 ID can be a vector of ids to allow getting multiple buttons.

 Outputs
 .......

 VALUE - value of the button (0 or 1).

 VALUE will be a vector of values when getting multiple buttons.

 Examples
 ........

 Open device 1 and get value of button 1

       joy = vrjoystick(1);
       val = button(joy, 1)


 See also: vrjoystick.

3.2.3 @octave_joystick/caps

-- : INFO = caps (JOY)
Get the capabilities joystick JOY.

 Inputs
 ......

 JOY - a previously opened joystick object

 Outputs
 .......

 INFO - A struct with fields Axis, Buttons, Force, POVs to hold the
 numeric count of each in joystick.

 Examples
 ........

 Open device 1 and capabilities

       joy = vrjoystick(1);
       c = caps(joy)


 See also: vrjoystick.

3.2.4 @octave_joystick/close

-- : close (JOY)
Close opened joystick JOY.

 After closing the joystick querying the device will no longer work.

 Inputs
 ......

 JOY - a previously opened joystick object

 Outputs
 .......

 None

 See also: vrjoystick.

3.2.5 @octave_joystick/force

-- : JOY = force (JOY, ID, FORCEVALUE)
Apply forcefeedback on axis ID on joystick JOY.

 Inputs
 ......

 JOY - a previously opened joystick object
 ID - a positive numeric id for the joystick forcefeed axis to use
 FORCEVALUE - force value to use, values should be between -1 ..  1

 If ID is a vector of axis ids, FORCEVALUE is expected to be a
 single value applied to all of the specified axis or a vector of
 the same size as ID, with a value for each axis.

 Outputs
 .......

 None

 See also: vrjoystick.

3.2.6 @octave_joystick/pov

-- : JOY = pov (JOY, ID)
Get the value of pov ID on joystick JOY.

 Inputs
 ......

 JOY - a previously opened joystick object
 ID - a positive numeric id for the joystick pov to use

 ID can be a vector of ids to allow getting multiple povs.

 Outputs
 .......

 VALUE - value of the pov as an angle in degrees, or -1 if not
 pressed.

 VALUE will be a vector of values when getting multiple buttons.

 Examples
 ........

 Open device 1 and get value of pov 1

       joy = vrjoystick(1);
       val = pov(joy, 1)


 See also: vrjoystick.

3.2.7 @octave_joystick/read

-- : [AXES, BUTTONS, POVS] = read (JOY)
Get the value of all axes, buttons and povs joystick JOY.

 Inputs
 ......

 JOY - a previously opened joystick object

 Outputs
 .......

 AXES - vector of the axis values.
 BUTTONS - vector of the button values.
 POVS - vector of the pov values.

 See also: vrjoystick, axis, pov, buttons.

3.2.8 vrjoystick

-- : JOY = vrjoystick (ID)
-- : JOY = vrjoystick (ID, "FORCEFEEDBACK")
Attempt to open a joystick.

 Inputs
 ......

 ID - a positive numeric id for the joystick device to use.
 "FORCEFEEDBACK" - String constant to enable forcefeedback.

 Outputs
 .......

 JOY - a octave_joystick object.

 Joystick Properties
 ...................

 A joystick object has the following properties:
 ID
      The ID of the joystick as used to create the joystick
 Name
      The name of the joystick device
 Status
      Status of the joystick ("Open" or "Closed")
 ForceFeedbackSupported
      Boolean for if the joystick was opened with forcefeedback
      enabled and supports forcefeedback.

 Joystick Functions
 ..................

 A joystick object provides the following functions:
 axis
      Get the value of a joystick axis
 buttons
      Get the state of a joystick button
 caps
      Get the capabilities of the joystick
 close
      Close a joystick
 force
      Set the forcefeedback forces on a joystick
 pov
      Get the pov values from a joystick
 read
      Read all state values from a joystick

 Examples
 ........

 Open device 1

       joy = vrjoystick(1);


 See also: vrjoysticklist.