Handling keypress events

The Node.js keypress module allows you to easily listen to keyboard events from the stdin input stream. Nathan Rajlich (@TooTallNate) wrote the keypress module.

Source code for keypress can be found here on GitHub.

Let’s install the module using npm:

$ npm install keypress

Now create a new file named keypress-test.js.

The first step is to require the keypress module:

var keypress = require('keypress');

Then we can set up the keypress module on the stdin stream:

keypress(process.stdin);

We also need to enable raw mode on the stdin stream. Without raw mode, the keyboard input will be buffered so you would not get the keypress event immediately.

process.stdin.setRawMode(true);

The last step is to attach an event handler for the keypress event. First, we need to check if the key argument is provided; if it isn’t, we can stop processing the event and return. The key argument is not present for some keys, like number keys. Then we can check if Ctrl-C was entered. This is usually handled for you, but since we’ve set up the keypress module, we need to handle it ourselves. Otherwise, we will print the keypress event key to the console.

process.stdin.on('keypress', function (ch, key) {
  if (!key) {
    return;
  }

  if (key.ctrl && key.name === 'c') {
    process.exit();
  }

  console.log('got "keypress"', key);
});

Now we can run the application:

$ node keypress-test.js

When you press the up arrow key on your keyboard, the test application will output the following:

got "keypress" { name: 'up',
  ctrl: false,
  meta: false,
  shift: false,
  sequence: 'u001b[A',
  code: '[A' }

The name property of the key has the value of up; we can ignore the other properties.

You can try other key presses and see the key event output. Press the Ctrl-C at the same time to exit.

Let’s update the keypress event handler to only log the name of the key that was pressed:

process.stdin.on('keypress', function (ch, key) {
  // ...

  console.log('got "keypress"', key.name);
});

When we run the application again:

$ node keypress-test.js

You will see a simplified output of key events, like the following for the up arrow key:

got "keypress" up

If you hold a key down many events are received, this will cause issues when you map keypress events to Rolling Spider actions. Too many commands will be sent to the drone when a key is held down.

Let’s add a debouncing mechanism to the keypress event handler to throttle out event handling. We start by adding a global variable to track the state at the top of the file:

var active = false;

Then we check the value in the keypress event handler. If active is true, we abort processing the event. Otherwise, we can set active to true.

process.stdin.on('keypress', function (ch, key) {
  // ...

  if (active) {
    return;
  }
  active = true;

  // ...
});

Now we need to set the value of active to false after a delay. We can use the setTimeout function to accomplish this, with a delay of 100 milliseconds.

Create a new function named clearActive that sets the active variable value to false. At the end of the keypress event handler, use setTimeout to call clearActive after 100 ms.

function clearActive() {
  active = false;
}

process.stdin.on('keypress', function (ch, key) {
  // ...

  setTimeout(clearActive, 100);
});

Now when we run the test application again, and hold a key down, there will be a 100-ms delay between events when they are logged to the console.

$ node keypress-test.js

Putting it all together

Now that we have familarized ourselves with the node-rolling-spider and keypress modules, we can combine them.

The code from earlier can be reused with a few changes. We don’t want to automatically have the Rolling Spider take off and land.

Create a new file named keyboard.js with the following starter code:

var RollingSpider = require('rolling-spider');

var rs = new RollingSpider();

function connect() {
  console.log('connecting ...');
  rs.connect(connectCallback);
}

function connectCallback(error) {
  if (error) {
    console.log('error connecting: ' + error);
    process.exit(-1);
  }

  console.log('connected, setting up ...');
  rs.setup(setupCallback);
}

function setupCallback() {
  console.log('set up, flat trimming and starting ping ...');

  rs.flatTrim();
  rs.startPing();
  rs.flatTrim();

  setTimeout(ready, 1000);
}

function ready() {
  // ...
}

connect();

When the Rolling Spider is ready to receive commands, we’ll call a new function named ready. Previously, we had code to take off and land. Now let’s add the keypress functionality. At the start of the file, add the following:

var keypress = require('keypress');
var RollingSpider = require('rolling-spider');

keypress(process.stdin);

var active = true;

This is similar to what we used earlier when trying out the keypress module. We’ll also set up a variable named active with an initial value of true to ignore keypress events until the Rolling Spider is ready to receive commands.

Now we can add the remaining keypress handling at the end of the file. Again, this is similiar to what we tried out before.

// ...

process.stdin.setRawMode(true);

function clearActive() {
  active = false;
}

process.stdin.on('keypress', function (ch, key) {
  if (!key) {
    return;
  }

  if (key.ctrl && key.name === 'c') {
    process.exit();
  }

  if (active) {
    return;
  }
  active = true;

  setTimeout(clearActive, 100);
});

connect();

Now we will fill in the ready function we created earlier. We’ll print a message to the console to let the user know things are ready. Then we will clear the active flag to enable keypress event handling.

function ready() {
  console.log('ready to receive commands!');
  console.log();

  clearActive();
}

Now let’s add some code to map keypress events to Rolling Spider commands. We’ll map the t key to takeOff and l to land.

process.stdin.on('keypress', function (ch, key) {
  // ...

  if (key.name === 't') {
    console.log('taking off');
    rs.takeOff();
  } else if (key.name === 'l') {
    console.log('landing');
    rs.land();
  }

  setTimeout(clearActive, 100);
});

Now we are ready to try taking off and landing using keyboard controls.

On OS X:

$ node keyboard.js

On Linux, sudo is needed:

$ sudo node keyboard.js

Wait for the following output:

connecting ...
connected, setting up ...
set up, flat trimming and starting ping ...
ready to receive commands!

Now press the t key to make the Rolling Spider take off. Once the Rolling Spider is in the air, wait a few seconds, and then press l to initiate landing. Then use Ctrl-C to exit the application.

Let’s map the keyboard arrow keys to Rolling Spider commands. The APIs we’ll use for this take an options parameter, which can contain the following properties:

speed

The speed to use for the drive or rotation; a number between 0 and 100 inclusively

steps

The step (time) to use for the drive or rotation; a number between 0 and 100 inclusively

We’ll use a step size of 2 and a default speed for the new commands so we need to create an options variable that will be passed into the action functions. The up and down keys will be mapped to up and down, respectively. The left and right keys will make the Rolling Spider turn left and right.

process.stdin.on('keypress', function (ch, key) {
  // ...

  var options = {
    steps: 2
  };

  if (key.name === 't') {
    console.log('taking off');
    rs.takeOff();
  } else if (key.name === 'l') {
    console.log('landing');
    rs.land();
  } else if (key.name === 'up') {
    console.log('up');
    rs.up(options);
  } else if (key.name ==='down') {
    console.log('down');
    rs.down(options);
  } else if (key.name === 'left') {
    console.log('turn left');
    rs.turnLeft(options);
  } else if (key.name ==='right') {
    console.log('turn right');
    rs.turnRight(options);
  }

  // ...
});

Now let’s add some commands for moving forward, backward, left, and right. The w key will be used for forward, s for backward, a for left, and d for right.

process.stdin.on('keypress', function (ch, key) {
  // ...

  // ...
  } else if (key.name === 'w') {
    console.log('forward');
    rs.forward(options);
  } else if (key.name ==='s') {
    console.log('backward');
    rs.backward(options);
  } else if (key.name === 'a') {
    console.log('left');
    rs.left(options);
  } else if (key.name ==='d') {
    console.log('right');
    rs.right(options);
  }

  // ...
});

See Table 11-1 for a summary of the key mappings we implemented.

Time to try out the commands!

Like before, wait for the “ready to receive commands!” message. Then press t to take off, and once you’re in the air, use the keys you mapped to actions to move the Rolling Spider around. Press l to land the drone.

Additional Rolling Spider commands, such as tilt left/right, can also be mapped to keypress events, but we will stop here.