How Plugins work with HOOBS (Advanced)

You are here:
  • Main
  • FAQs
  • How Plugins work with HOOBS (Advanced)
← All Topics


This document describes how we use plugins. It is very advanced. You need to fully understand Homebridge and you need to know how to write a JSON file.

If you are uncomfortable running shell commands. Or you are uncomfortable writing JSON. Or just simply want a better way to install plugins go here

HOOBS handles plugins differently than Homebridge. There are many reasons why we do this, two big ones are security, and instance separation.

Notes about this documentation. Commands you need to run in the terminal are prefixed with ~]$. You don’t enter the prefix in to the terminal. If you don’t see the prefix, this means the content is either example output or content you need to enter into a file.

Managing Plugins

The best way to install plugins is via the user interface.

Installing via the user interface insures that the plugin is installed in the correct directory. It also automates things for you like adding the plugin to the “white list”, and starting the configuration for you.

It also detects the type of plugin it is, and configures it accordingly.

Uninstalling a plugin is also best done via the user interface. This also automates removing the plugin from the “white list” and un-configuring it for you.

The user interface also handles upgrading for you as well.

Installing Plugins With the API

HOOBS manages plugins via the API. There are other things the user interface does, however the API is the next best way to manage your plugins.

The plugins API documentation can be found here.

The API is not user friendly and since the user interface is bundled and started with the API, the user interface should be available at the same ip address.

How Plugins Work

Installing plugins manually is not recommended. However, we are documenting the process, just-in-case.

Before installing plugins in HOOBS, we must first understand how vanillia Homebridge loads plugins. Typically a plugin is installed with a command like this.

~]$ sudo npm install -g homebridge-plugin

This installs the plugin in the system’s Node modules, and can be accessed globally, by all applications. This is done using the -g flag.

HOOBS will NOT load global plugins.

Another way to install plugins with vanillia Homebridge is to install the plugin into the executing users home directory. To install a plugin into the executing user’s home directory.

~]$ su homebridge-user
~]$ cd ~/
~]$ npm install homebridge-plugin

This method typically is not mentioned. And HOOBS will NOT load these plugins either.

Plugins installed this way are available to any Node application ran by the current user.

Another method is to pass in the plugin path into Homebridge using the -P flag. This is helpfull for plugin development. It is used when you download the code to any directory on the system.

If you are developing a plugin, you need to use vanilla Homebridge. Head to our developer docs. HOOBS ignores the -P flag.

The final method is to install the plugin under the Homebridge directory. This directory is typically found in /usr/local/lib/node_modules/homebridge/ This isolates the plugin along with the Homebridge code. This will even add the plugin to the packages.json file along with all of the other dependencies.

To install a plugin along with the Homebridge code.

~]$ cd /usr/local/lib/node_modules/homebridge/
~]$ sudo install homebridge-plugin

You must use sudo because Homebridge is a global package

This method is great for people who are concerned with security. The down side is when you upgrade Homebridge, you must re-install your plugins, because the Homebridge NPM package will overwrite the dependencies.

HOOBS uses this method. However HOOBS has logic around this that keeps your plugins with the executing user.

HOOBS User Mode

HOOBS is installed globally using the same NPM command as Homebridge.

~]$ sudo npm install -g --unsafe-perm @hoobs/hoobs

However this is where the similarities end.

When HOOBS starts, it sets up a user mode enviornment, and then executes from that enviornment. All of your configurations and plugins live in this enviornment. This ensures that the executing user has access to the configuration and its plugins.

So when installing plugins manually, you must know the executing user. If you downloaded one of our images or have one of our boxes, the good news is the only user on the system hoobs is the executing user. So for the purposes of this documentation, we will be using the hoobs user.

Installing Plugins Manually

Again for purposes of this documentation we are assuming that the executing user is the hoobsuser.

First navigate to the HOOBS user mode directory.

~]$ cd ~/.hoobs/

All commands will be executed from this directory. It is important that the current working directory be ~/.hoobs/.

Next install the plugin.

~]$ npm install homebridge-plugin

Notice that we are NOT using sudo. HOOBS runs in user mode, using sudo will cause files and directories in the users home that are not accessable by that user. It will not load either. In other words do NOT use sudo.

Also note that we are not using the -g flag. This flag will not install the plugin in the proper directory. It may or may not load, but you will have no control over the plugin. Even if the plugin’s documents tell you to use the -g flag, do not. That documentation is for Homebridge not HOOBS. Do NOT use the -g or –global flags.

Once the plugin installs you will need to stop HOOBS.

~]$ sudo systemctrl stop hoobs

Note. If you installed the plugin via the user interface, the interface can restart just the internal Homebridge service. If using the API you can restart the internal service via POST /api/service/restart. Since the terminal doesn’t have access to the internal service, you must restart the entire HOOBS service.

Next you need to edit the configuration.

~]$ nano ~/.hoobs/etc/config.json

Now find the plugins array and add the plugin to that array.

    "plugins": [

Note. This is the name of the package not the name of the platform or accessory. It is the same name as you used to install.

Also since you have the config.json file open, lets add the platform or accessory configuration.

    "platforms": [
            "platform": "Plugin",
            "plugin_map": {
                "plugin_name": "homebridge-plugin"

Notice that we added a plugin_map variable. This is used by the interface and the API to link a configuration entry to a plugin. Without this there is no definitive link between the two.

Again the plugin_name is the name of the package, not the platform or accessory.

A little note about plugin names. As stated, the package name is used by NPM and the configuration file. However, HOOBS allows scoped plugins. Scoped plugins are plugins that are released under an orgization on NPM. For example @hoobs/shelly is a certified plugin, and it has a scope of hoobs. When using a scoped plugin, the plugin name becomes the name after the /. So @hoobs/shelly has a plugin_name equal to shelly.

The down side to this is, you can only have one scoped shelly plugin installed. You can’t have @hoobs/shelly and @bobs-burgers/shelly installed on the same system.

Finally once you have the configuration done, save the changes.

In nano ctrl+x then y and enter saves the file.

Now you are ready to start HOOBS back up.

~]$ sudo systemctrl start hoobs

You can check for any errors by running.

~]$ sudo systemctrl status hoobs

Or you can review the log in the user interface.

Skip to content