Getting Started

1. Usage
   1. Creating the controller
   2. Event Types
   3. Understanding the Frame Detection Loop
2. Examples
3. Development
4. Tests

Usage

Creating the Controller

To use LeapJS, start by creating a Leap.Controller:

var controller = new Leap.Controller();

There are a few options you can pass to this controller:

• host - The host used by the WebSocket connection. Default is "127.0.0.1"
• port - The port used by the WebSocket connection. Default is 6437
• enableGestures - Enables or disables gesture recognition for this controller. Default is true
• frameEventName - Lets you specify which frame detection loop to use for the frame event type. In the browser, it will default to the animation loop. In Node, it will use the device frame loop

Example:

var controller = new Leap.Controller({host: "24.6.0.1", port: 1337});

Event Types

The controller supports a number of event types. When LeapJS connects to the websocket server, it first firest the connect event. After that, once the protocol has been selected, it fires a ready event. Once a frame has been received, a deviceConnected event gets fired once. Then, a deviceFrame gets fired for each frame coming from the websocket server connection. (If you're using the animationFrame though, you won't get this information until the animation loop procs.)

• connect - The client is connected to the websocket server
• protocol - The protocal has been selected for the connection. The protocol object is passed as an argument to the event handler
• ready - The protocol has been selected
• disconnect - The client disconnects from the websocket server
• code>focus - The browser received focus
• blur - The browser loses focus
• deviceConnected - A Leap device has been connected
• deviceDisconnected - A Leap device has been disconnected
• frame - A frame is finishing being processed by the controller. This event is either driven by the animationFrame or the deviceFrame event, depending which is the controller was created with. The frame is passed as an argument to the event handler
• animationFrame - A frame being emitted in time with the animation loop. The frame is passed as an argument to the event handler
• deviceFrame - A frame being emitted by the connection to the Leap device. The frame is passed as an argument to the event handler

Example use of event type:

var controller = new Leap.Controller();
controller.on('connect', function() {
  console.log("Successfully connected.");
});
controller.on('deviceConnected', function() {
  console.log("A Leap device has been connected.");
};
controller.on('deviceDisconnected', function() {
  console.log("A Leap device has been disconnected.");
};
controller.connect();

Understanding the Frame Detection Loop

There are two types of frame detection loops. In general, in the browser, the animation loop will be the most useful. This will tick at 60fps and grab whatever the latest frame is at that point. The other type of loop is a device loop, where the device will ping you with every new frame as soon as it is available. Those working in Node will likely want this type of loop. Whichever frame event name the controller is declared for will be the default given by the event type frame, but you also have the flexibility to write functions for each type of frame specificially. Some apps may even want to use both types of frames; this is allowed.

To illustrate, this will use the animation loop since we're in a browser and didn't specify otherwise in the controller options:

var controller = new Leap.Controller();
controller.on('frame', function() {
  // your code here
});
controller.connect();

A more verbose version of above:

var controller = new Leap.Controller();
controller.on('animationFrame', function() {
  // your code here
});
controller.connect();

To use the deviceFrame instead you can do:

var controller = new Leap.Controller({frameEventName: "deviceFrame"});
controller.on('frame', function() {
  // your code here
});
controller.connect();

Or:

var controller = new Leap.Controller();
controller.on('deviceFrame', function() {
  // your code here
});
controller.connect();

Examples

Some examples have been included in the examples/ directory. To run them do the following:

1. Run npm install
2. Run make serve
3. Point your browser to http://localhost:8080/examples

Or in code:

1. Run node examples/node.js

Development

You can build your own leap.js file by using make build. If you're doing any amount of development, you'll find it convenient to run make watch. This takes care of building and testing leapjs for you on every edit.

Tests

There are currently rudamentary test. To get them running, do the following:

• Run npm install
• Run make test

Or use make watch-test as noted above.

---