# MatlabInput

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

## Installation

* Download the [latest release](https://github.com/HebiRobotics/MatlabInput/releases)
* Extract the .zip file into a folder of your choice
* Add the unzipped files to the [MATLAB path](http://www.mathworks.com/help/matlab/ref/path.html)

## 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](https://github.com/HebiRobotics/HebiCam) or the [Hebi API](http://hebirobotics.com/matlab), you will need to pre-load the libraries manually before using them.

```matlab
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.

```matlab
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

```matlab
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](https://github.com/jinput/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.

```matlab
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](https://www.mathworks.com/products/3d-animation.html) and serves as a drop-in replacement for [vrjoystick](https://www.mathworks.com/help/sl3d/vrjoystick.html).

### Usage

Create a joystick and react to button presses.

```matlab
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](https://www.mathworks.com/help/sl3d/vrjoystick.html) documentation for more information.

![comparison](https://github.com/HebiRobotics/MatlabInput/raw/resources/comparison.png)

## 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](http://maven.apache.org/install.html)

Build the default snapshot

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

Create a release

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