nodemacros

NodeMacros

Use extra keyboards to do anything!

Nodemacros hooks into the HID drivers to allow to take over any keyboard (don't use your main one) and rebind (pretty much) any key to do (pretty much) anything

Installation

just install the package globally using npm install -g nodemacros

Compiling

these instructions are for linux. this program has only been tested on linux at the current point in time, though, they might work on other platforms. if you've successfully ran the program on your platform, please feel free to add the documentation or modifications so others can too!

1. install the following dependencies:

• NodeJS (tested on 8.9.3)
• NPM
• gulp-cli (globally, using NPM)

1. clone the project and change directory into it: git clone http://gitlab.riksolo.com/riksolo/nodemacros.git && cd nodemacros
2. npm install to install the dependencies
3. compile the project by running: gulp
4. run the install script to add the required udev rules: ./install.sh, this uses sudo and will ask your password. this step is optional, but if you don't do this you'll probably have to run as root if the device you want to use is already plugged in, unplug it, then plug it back in, as the new rules will only be applied to the device when it gets plugged in.

you can now run the program by running npm start

Usage and Configuration

You can run the program, but will probably notice that it won't do much. To actually use it, you'll need to create 2 config files. A folder named nodemacros will be created in the default user config location for your operating system (on linux, there's a good chance that's ~/.config/). in this folder, you'll see 2 blank files. one is called "bindings.cson", the other will be "devices.cson".

devices.cson is where you'll want to define which devices will be used, like so:

[
	{
		name: "devicename" 	#	this can be whatever you want, as long as each device has a unique named
		vendorId: 0xC45 	#	the HID's vendor ID, can be found using lsusb on linux, this can be either decimal or hex
		productId: 30211 	#	the HID's product ID, can also be found using lsusb on linux, can be decimal or hex
		keymap: 'default' 	#	which keymap to use, the only one included in the program is 'default'
	}
]

bindings.cson is where you map your keys, like so:

"devicename":	#	the name of the device, as specified in bindings.cson
	"keyname": 	#	the name of the key to bind, as defined in the keymap
		module: "command"	#	which module to use, more info on modules further down in this document
		args: "wmctrl -a Firefox"	#	the argument to pass to the module
	"a": module: "media" args: "play"	#	you can even shorten the bindings to one line each!
	# this is how you do key combinations:
	"b":
		"a": module: "text" args: "Hello, world!"	# this runs when you press b+a (not a+b though!)
		"c": module: "media" args: "pause"	# ditto for a+c

(the default keymap can be found here)

adding additional keymaps

to add additional keymaps, you'll want to create a .cson file in the keymaps/ subfolder of the nodemacros config folder. in this file you can define the key mappings like so:

01: "Escape"
02: "Tab"
03: "q"

and so on and so forth.

The number is the keycode of the key, i have no idea where the hid-handler library makes these up, but you can figure them out by first adding your device to devices.cson, then restarting the program, and pressing keys on it. Whenever a key is pressed on a device in use by the software it'll log the keycode to the console. The string is the definition, which is used to bind functions to keys in bindings.cson

Modules

Modules are what allow the program to do anything, not to be confused with npm modules, these are all the functions that you can bind to a key. keys are bound to modules as shown above, where module: takes a string with the module's name, and args: is whatever the module takes as input, this can be any data type

there are a few modules included with nodemacros:

• cmd: runs command provided as string as if it were entered into the command line
• media: emulates a media key as if it were pressed on the keyboard, the argument is a string, and can be one of the following:
  • "play"
  • "pause"
  • "stop"
  • "next"
  • "previous"
• text: inserts any text as if it were typed on the keyboard

custom modules

You can also add your own modules to nodemacros to make it even more powerful! these modules go into the 'modules/' subfolder of the nodemacros config folder. Modules are either single nodejs files, or nodejs module folders (so folders with at least one js file and a valid package.json file) inside. these modules should have a single function as module.exports (module.exports = function(args){ ...your code here... }), where the (first and only) argument is whatever is passed along by the args field in bindings.cson.

to use one of these custom modules, just make sure theyre in the 'modules/' folder, and bind it to a key in bindings.cson where the module field is the filename (sans .cson) or the foldername (NOT the package name specified in package.json!) of the module and args is what gets passed to the first argument of the function.