Library for getting keyboard and joystick input into MATLAB
Java Matlab
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

MatlabInput

MatlabInput allows MATLAB users to get input from keyboards and joysticks in a non-blocking manner.

Installation

Warning: Problems when used with other Java libraries

Typically the underlying Java libraries are loaded automatically at the first call. However, there is a limitation in MATLAB that prevents Java libraries to be loaded once any Java object is instantiated. Thus, if you are using other Java libraries, e.g., HebiCam or the Hebi API, you will need to pre-load the libraries manually before using them.

HebiKeyboard.loadLibs();

HebiKeyboard

HebiKeyboard provides a way to get keyboard input in a non-blocking manner. The default driver is based on Java-AWT and requires focus on a MATLAB window, i.e., the console, an editor window, or a figure. Note that inputs from all keyboards are combined.

Usage

The 'read' method returns a snapshot of the current state of various standard and meta keys. Numbers and letters can be queried by indexing into a key vector. Meta keys are exposed directly as fields in the returned struct.

Display a message whenever letter 'x' and the number '0' are pressed at the same time.

kb = HebiKeyboard();
while true
    state = read(kb);
    if all(state.keys('x0'))
        disp('x and 0 are both pressed!')
    end
    pause(0.01);
end

Display all pressed letters whenever shift is up

kb = HebiKeyboard();
while true
    state = read(kb);
    down = find(state.keys('a':'z')) + 'a';
    if ~state.SHIFT
        disp(char(down));
    end
    pause(0.01);
end

Driver Selection

Alternatively, users can choose to use a 'native' driver (based on JInput binaries) that may support the selection of individual keyboards and may allow reading input when MATLAB is running in the background.

OS Requires Focus Selectable Keyboard
Windows No No
OSX No Yes
Linux N/A (needs sudo) N/A (needs sudo)

Note that this is not the default behavior because of security concerns, e.g., displaying pressed keys while entering passwords into a browser window.

deviceId = 1;
kb = HebiKeyboard('native', deviceId);
state = read(kb);

HebiJoystick

HebiJoystick is intended for people who don't have access to the 3D Animation Toolbox and serves as a drop-in replacement for vrjoystick.

Usage

Create a joystick and react to button presses.

joy = HebiJoystick(1);
while true
  [axes, buttons, povs] = read(joy);
  if any(buttons)
    disp(['Pressed buttons: ' num2str(find(buttons))]);
  end
  pause(0.1);
end

See vrjoystick documentation for more information.

comparison

Notes

  • There is a maximum number of events that can occur between reads. If reads don't happen frequently enough, the returned state may not match the real physical state.
  • On some operating systems going into sleep mode while executing a script that reads from the joystick may make MATLAB seem unresponsive. Ctrl-C works eventually, but it may take on the order of minutes to recover.
  • The number and behavior of joystick axes / buttons / povs may differ between operating systems

Building from source

Install Apache Maven

Build the default snapshot

git clone https://github.com/HebiRobotics/MatlabInput.git
mvn package

Create a release

mvn package -DreleaseName="matlab-input-x.y"