kylepaulsen / kbm-robot

A module to help you emulate system wide keyboard and mouse actions.

kbm-robot (Keyboard-Mouse-Robot)

kbm-robot is a module to help you emulate system wide keyboard and mouse actions. It uses java's robot class (a child process with stdio pipe communication) to help accomplish this.

Example:

var robot = require("kbm-robot");

robot.startJar();

robot.press("alt")
    .press("tab")
    .sleep(100)
    .release("tab")
    .release("alt")
    .sleep(100)
    .typeString("Hello World!")
    .go()
    .then(robot.stopJar);

Install

npm install --save kbm-robot

Documentation

API functions

var robot = require("kbm-robot");

All functions except for startJar and stopJar are chainable. You must chain them and then call .go() to have things happen.

• robot**.startJar(version)**
  • version - (String, optional, default is "6") - argument to specify which jar you want to run. Currently there is a Java 6 and Java 7 jar. Valid values are "6" or "7". If you are having trouble getting something to work, try using .startJar("7"); (You will need java >= 1.7 to run the 7 jar. Type java -version in a console to see your version).
  • This function must be called before any other api functions are used.
• robot**.stopJar()**
  • Stops the child process that is running the jar.
• robot**.press(key)**
  • key - (String, required)
  • Tells the robot to press (and hold) the specified key.
• robot**.release(key)**
  • key - (String, required)
  • Tells the robot to release the specified key.
• robot**.typeString(str, downDelay, upDelay)**
  • str - (String, required) - The string to type.
  • downDelay (int, optional, default is 0) - How long to wait after a key is pressed.
  • upDelay (int, optional, default is 0) - How long to wait after a key is released.
  • Tells the robot to type a series of keys. NOTE: it will only be able to type keys that have a one character long string code (it splits the string into 1 character parts). This is basically 0-9, a-z, punctuation, and any characters that you hold shift to type on your keyboard. \n will press Enter.
• robot**.type(key, delay)**
  • key - (String, required)
  • delay (int, optional, default is 0) - How long to wait after the key is pressed.
  • Tells the robot to press and release the specified key.
• robot**.sleep(delay)**
  • delay (int, required) - How long to sleep for in ms (1000 is 1 second).
  • Tells the robot to wait.
• robot**.mouseMove(x, y)**
  • x - (int, required) - The X coordinate on your screen.
  • Y - (int, required) - The Y coordinate on your screen.
  • Tells the robot to move your mouse to the specified location.
• robot**.mousePress(buttons)**
  • buttons (String, required) - A string containing 1, 2, or 3 or any combination of those. 1 is the left mouse button, 2 is the right mouse button and 3 is the middle mouse button. (Ex. "13" press mouse 1 and mouse 3).
  • Tells the robot to press (and hold) the specified mouse buttons.
• robot**.mouseRelease(buttons)**
  • buttons (String, required) - A string containing 1, 2, or 3 or any combination of those. 1 is the left mouse button, 2 is the right mouse button and 3 is the middle mouse button. (Ex. "13" press mouse 1 and mouse 3).
  • Tells the robot to release the specified mouse buttons.
• robot**.mouseClick(buttons, delay)**
  • buttons (String, required) - A string containing 1, 2, or 3 or any combination of those. 1 is the left mouse button, 2 is the right mouse button and 3 is the middle mouse button. (Ex. "13" press mouse 1 and mouse 3).
  • delay (int, optional, default is 0) - How long to wait after the mouse buttons are pressed.
  • Tells the robot to click the specified mouse buttons.
• robot**.mouseWheel(amount)**
  • amount (int, required) - How many "notches" to move your mouse wheel. Negative values are "up" or "away" from you.
  • Tells the robot to scroll using the mouse wheel.
• robot**.go(callback)**
  • callback (Function, optional) - The function to call after all actions are complete. If this argument is not given, then go() will return a promise.
  • Tells the robot to start the chained actions.

Keys

All key strings are the same as you would find in Java's KeyEvent class: http://docs.oracle.com/javase/7/docs/api/java/awt/event/KeyEvent.html For example the string "VK_UP" would represent the up arrow key.

However this library also supplies many "shortcut" strings to get your robot typing faster. (Also add on A-Z and 0-9 as shortcuts). When using a shortcut string of A-Z, case doesn't matter.

"ESC"
"F1"
"F2"
"F3"
"F4"
"F5"
"F6"
"F7"
"F8"
"F9"
"F10"
"F11"
"F12"
"CTRL"
"META"
"SUPER"
"ALT"
" "
"SPACE"
"LEFT"
"DOWN"
"RIGHT"
"UP"
"TAB"
"SHIFT"
"ENTER"
"\n"
"CAPS_LOCK"
"PRINT_SCREEN"
"SCROLL_LOCK"
"PAUSE_BREAK"
"BACKSPACE"
"DELETE"
"HOME"
"END"
"INSERT"
"PAGE_UP"
"PAGE_DOWN"
"NUM_LOCK"
"`"
"-"
"="
"["
"]"
"\\"
";"
"'"
","
"."
"/"
"KP_ADD"
"KP_-"
"KP_*"
"KP_/"
"KP_0"
"KP_."
"KP_1"
"KP_2"
"KP_3"
"KP_4"
"KP_5"
"KP_6"
"KP_7"
"KP_8"
"KP_9"

License

MIT

P.S. If anyone knows how to ditch the java dependency while still having platform independent code, please let me know. I have a feeling it will be very hard to do.

kbm-robot's Issues

event.data includes a newline

(tested on Kubuntu 15)
Awesome module, but unfortunately every event includes a newline in the data field.

index.js

var gkm = require('gkm');

gkm.events.on('key.pressed', function (data) {
    console.log('\'' + data + '\'')
    console.log(this.event + ' ' + data);
});

output

'D
'
key.pressed D

Guess that's not intended, makes it much harder to work with at least.

Error: ERR: kbm-robot robot6.jar already started. appears if stopJar() and then run it again

events.js:72 throw er; // Unhandled 'error' event

Ok, so considering that I am just 13 I have probably made some major mistake on my end... But I cannot find why this is not working...

Here's my code:
var robot = require('kbm-robot');

function right() {

robot.startJar();

robot.press("right")
.sleep(100)
.release("right")
.go()
.then(robot.stopJar);

}

function left() {

robot.startJar();

robot.press("left")
.sleep(100)
.release("left")
.go()
.then(robot.stopJar);

}

function up() {

robot.startJar();

robot.press("up")
.sleep(100)
.release("up")
.go()
.then(robot.stopJar);

}

function down() {

robot.startJar();

robot.press("down")
.sleep(100)
.release("down")
.go()
.then(robot.stopJar);

}

up();

when ever I try and execute my code I run in to this error:

events.js:72
throw er; // Unhandled 'error' event
^
Error: read ECONNRESET
at errnoException (net.js:904:11)
at Pipe.onread (net.js:558:19)

But here's the weird part... yesterday it worked 1/8 of the time that I executed it, and I have not changed a thing... I recorded the video from yesterday:
Screencast_08-14-2016_09:38:33 PM.webm.zip

Command key

Is there any support to trigger the command key on Mac?
I can't find anything about that in the documentation.

Thanks!

Error: read ECONNRESET

Hi, I'm having this error after ~790 chars have been typed (both java 6 and java 7):

$ node test.js 
events.js:141
      throw er; // Unhandled 'error' event
      ^

Error: read ECONNRESET
    at exports._errnoException (util.js:870:11)
    at Pipe.onread (net.js:544:26)
jake@levix:/tmp$ node test.js 
events.js:141
      throw er; // Unhandled 'error' event
      ^

Error: read ECONNRESET
    at exports._errnoException (util.js:870:11)
    at Pipe.onread (net.js:544:26)

The code is:

var robot = require("kbm-robot");

robot.startJar('7');

msg = 'Aesop was one of the great Greek writers. He is best known for his fables, stories that have a moral. They teach us something about how we should live our lives. Aesop wrote thousands of these stories. Here are a few.\nThe Wolf in Sheep\'s Clothing\nOnce upon a time, a Wolf decided to disguise the way he looked. He thought it would help him get food more easily. He put on the skin of a sheep, then he went out with the flock into the pasture. Even the shepherd was fooled by his clever costume. In the evening, the shepherd put him in with the rest of the sheep. He closed the gate and made sure it was secure before he went to bed. In the middle of the night, he came back to the fold to get some meat for the next day. Instead of a sheep, though, he grabbed the Wolf, killing him instantly.\nThose who look to harm others will be harmed themselves.\nThe Bat and the Weasel\nA Bat fell on the ground and was caught by a Weasel. It begged the Weasel to spare its life, but the Weasel refused. It told the Bat that birds, by nature, were its enemy. The Bat assured him that it was not a bird, it was a mouse. The Weasel thought a moment, then set it free. A while later, the Bat fell again to the ground, and it was caught by another Weasel. It begged this Weasel not to eat him, either. The Weasel, though, said it did not like mice at all and would eat it. The Bat told the Weasel that it was not a mouse, but a bat. The second Weasel had no good answer, so he let it go.\nThe Bat knew it is always wise to turn events to your advantage.\nThe Lion and the Mouse\nA sleeping Lion was woken up by a Mouse running over his face. He got up angrily and caught the scared little Mouse. He was about to kill the Mouse, but it said in its squeaky little voice, "If you would only spare my life, I would be sure to repay your kindness." The Lion laughed at such nonsense, but he let him go. A short time later, though, the Lion was caught by some hunters. They bound him by ropes to the ground. The Mouse recognized his roar, and he rushed over and gnawed the rope with his teeth, setting the Lion free. The Mouse said "You laughed at the idea of my ever being able to help you. Now you know that it is possible for even a small little Mouse to help a great big Lion."'

robot.sleep(1000)
    .typeString(msg)
    .go()
    .then(robot.stopJar);

I'm on Debian unstable:

$ node -v
v4.2.4

A possible workaround is to split the sentence in chunks and rebooting the robot, calling both robot.stopJar() followed by a robot.startJar():

var robot = require("kbm-robot");


msg = 'Aesop was one of the great Greek writers. He is best known for his fables, stories that have a moral. They teach us something about how we should live our lives. Aesop wrote thousands of these stories. Here are a few.\nThe Wolf in Sheep\'s Clothing\nOnce upon a time, a Wolf decided to disguise the way he looked. He thought it would help him get food more easily. He put on the skin of a sheep, then he went out with the flock into the pasture. Even the shepherd was fooled by his clever costume. In the evening, the shepherd put him in with the rest of the sheep. He closed the gate and made sure it was secure before he went to bed. In the middle of the night, he came back to the fold to get some meat for the next day. Instead of a sheep, though, he grabbed the Wolf, killing him instantly.\nThose who look to harm others will be harmed themselves.\nThe Bat and the Weasel\nA Bat fell on the ground and was caught by a Weasel. It begged the Weasel to spare its life, but the Weasel refused. It told the Bat that birds, by nature, were its enemy. The Bat assured him that it was not a bird, it was a mouse. The Weasel thought a moment, then set it free. A while later, the Bat fell again to the ground, and it was caught by another Weasel. It begged this Weasel not to eat him, either. The Weasel, though, said it did not like mice at all and would eat it. The Bat told the Weasel that it was not a mouse, but a bat. The second Weasel had no good answer, so he let it go.\nThe Bat knew it is always wise to turn events to your advantage.\nThe Lion and the Mouse\nA sleeping Lion was woken up by a Mouse running over his face. He got up angrily and caught the scared little Mouse. He was about to kill the Mouse, but it said in its squeaky little voice, "If you would only spare my life, I would be sure to repay your kindness." The Lion laughed at such nonsense, but he let him go. A short time later, though, the Lion was caught by some hunters. They bound him by ropes to the ground. The Mouse recognized his roar, and he rushed over and gnawed the rope with his teeth, setting the Lion free. The Mouse said "You laughed at the idea of my ever being able to help you. Now you know that it is possible for even a small little Mouse to help a great big Lion."'



function type() {
    robot.stopJar();

    if (i == chunks.length)
        return;

    robot.startJar();
    robot
        .sleep(i == 0 ? 1000 : 1)
        .typeString(chunks[i]+'\n', 0, 0)
        .go()
        .then(type);
    i++;
}

var i = 0;
chunks = msg.split('\n')
robot.startJar();
type();

Not able to run sample code

I have installed npm package and trying to run basic demo code given in readme file. However, while executing this project with Node V12.18.0 getting error as per below.

events.js:292
throw er; // Unhandled 'error' event
^

Error: spawn java ENOENT
at Process.ChildProcess._handle.onexit (internal/child_process.js:267:19)
at onErrorNT (internal/child_process.js:469:16)
at processTicksAndRejections (internal/process/task_queues.js:84:21)
Emitted 'error' event on ChildProcess instance at:
at Process.ChildProcess._handle.onexit (internal/child_process.js:273:12)
at onErrorNT (internal/child_process.js:469:16)
at processTicksAndRejections (internal/process/task_queues.js:84:21) {
errno: 'ENOENT',
code: 'ENOENT',
syscall: 'spawn java',
path: 'java',
spawnargs: [
'-jar',
'C:\Users\admin\Desktop\key\node_modules\kbm-robot\java\robot7.jar'
]
}

And when try running code with Node V10.23.0 getting error as per below.

events.js:174
throw er; // Unhandled 'error' event
^

Error: spawn java ENOENT
at Process.ChildProcess._handle.onexit (internal/child_process.js:240:19)
at onErrorNT (internal/child_process.js:415:16)
at process._tickCallback (internal/process/next_tick.js:63:19)
at Function.Module.runMain (internal/modules/cjs/loader.js:834:11)
at startup (internal/bootstrap/node.js:283:19)
at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)
Emitted 'error' event at:
at Process.ChildProcess._handle.onexit (internal/child_process.js:246:12)
at onErrorNT (internal/child_process.js:415:16)
[... lines matching original stack trace ...]
at bootstrapNodeJSCore (internal/bootstrap/node.js:623:3)