Tutorial: Setting up WebStorm for Homebridge plugin development

Homebridge-WebStorm.md

Setting up WebStorm for Homebridge plugin development

This tutorial shows how to set up a new Homebridge plugin project using the WebStorm IDE and how to make it debuggable by creating a custom Run/Debug configuration.

Requirements

The following tools are used and expected to be installed:

• WebStorm IDE
• Git
• NodeJS
• Node package manager (NPM)

Setting up Homebridge

First of all we have to prepare a dedicated Homebridge installation that will later on serves as the host-process for our plugin. Download the latest version by cloning the repository:

git clone https://github.com/nfarina/homebridge.git

Now we have to download all dependencies for the new Homebridge installation. Switch to the newly created homebridge directory and execute:

npm install

NPM takes care of downloading all required packages and installs them in the node_modules subdirectory. After this step the new Homebridge is ready to run.

Let's go ahead and create a default configuration. In the homebridge directory create the new folder config and place a file named config.json with the following contents inside:

{
    "bridge": {
        "name": "Homebridge",
        "username": "CC:22:3D:E3:CE:30",
        "port": 51826,
        "pin": "031-45-154"
    }
}

Now adjust the name, username, port and pin settings and make sure they are different to the values of your original Homebridge installation (if there is one).

You will have to extend this configuration file later, in order to enable the platforms and accessories your plugin provides (take a look at the example config).

Setting up the plugin

In the same directory that contains the homebridge folder, create a second directory with the name of your plugin. I'm using homebridge-example-plugin for now.

Inside this directory place all files needed by your plugin. For this tutorial I'm just using the files of the example-plugin provided in the homebridge repository by copying them over:

cp ./homebridge/example-plugins/homebridge-samplePlatform/* ./homebridge-example-plugin

Your directory tree should now look like this:

root
 :.. homebridge
 :    :. config
 :    :   :. config.json
 :    :. ...
 :.. homebridge-example-plugin
      :. index.js
      :. package.json

Creating the WebStorm project

First of all create a new project using the Empty Project template and choose Yes if the IDE asks you to to create a project from existing sources.

Because WebStorm not providing a template for generic Node.js projects (without Express), we have to adjust some settings in order the make the IDE recognizing the inbuild NodeJS functions and types. Under File -> Settings -> Languages & Frameworks -> Node.js and NPM enable Coding assistance for Node.js.

Setting up the Run/Debug confguration

General setup

The last step is about setting up a new Run/Debug configuration in order to be able to debug our plugin. Click on Run -> Edit Configurations and add a new Node.js configuration by clicking on the + on the top left.

The Node interpreter and Working directory inputs should be filled automatically. We just have to rename the new configuration to Homebridge and set some additional Node paramters:

../homebridge/bin/homebridge -D -P ./ -U ../homebridge/config/

This way our dedicated Homebridge is executed everytime we run/debug the project.

The -P argument tells the homebridge instance to look for plugins in the specified directory (which is our plugin/working directory) while -U changes the config directory.

NPM Integration

As it can get quite irritating having to manually run npm install from inside your plugin directory everytime you modify the dependencies in package.json, we can tell WebStorm to do this for us (optional).

In the Before launch category on the bottom of the Run/Debug Configurations window, click on the + button and choose Run npm script, change the command to install, press OK and you are ready to go. The package.json input should automatically point to the correct file in your plugin directory.

From now on, npm install is automatically executed everytime you run/debug the project.

Debugging the plugin

Click Run -> Debug 'Homebridge' to start debugging your plugin. You can set breakpoints, inspect objects, step into, step over, and so on. Just like in other projects.

As we are using a dedicated Homebridge instance, you have to add it to your HomeKit App on the phone the first time you start the plugin project. This step is only required once, as the instance persists between different debug sessions (and even different plugins, if you re-use the same homebridge and homebridge/config directory).

Don't forget to extend the config.json to enable the custom platforms and accessories your plugin provides.