nhc2-hobby-api

As of October 29, 2019 Niko has published their Hobby API which allows end users to control their Niko Home Control 2 installation through the MQTT protocol.

This library is a wrapper library around the MQTT.js library exposing MQTT messages as a RxJS Observable stream. Events supported include:

• query available devices in a NHC2 installation
• listen on light status change
• listen on light brightness change
• listen on moving status change
• listen on position change

The library can also control your installation through commands. Commands supported include:

• toggle light status
• set light brightness level
• change position (e.g. of sun-blinds)
• set fan speed
• toggle generic switches (free start stop actions)

Changes

You can read the complete history of changes in the CHANGELOG.

Known Issues

1. Currently we need to set the rejectUnauthorized option to false because we are unable to verify the Niko root CA which is not ideal. Feel free to look into this.

Project Principles

This project has a few principles that have and will continue to guide its development.

1. Dependency lean. Try to keep the required dependencies to a minimum.
2. Simple. Using the library should be simple and straightforward following common conventions.
3. Completeness This library is a far way from being complete, but we aim to make this library feature complete based on the official Niko documentation.
4. Homebridge The intent of developing this library is to build a homebridge plugin on top of this library to support control of the installation through Apple HomeKit. This plugin still needs to be developed. When adding features feel free to include the feature in the homebridge plugin as well.

Contributing

Contributions are welcome, particularly bug fixes and enhancements! Refer to our Contribution Guidelines for details.

Please note that Project owners reserve the right to accept or reject any PR for any reason.

Code of Conduct

Before contributing or participating in the nhc2-hobby-api community please be sure to familiarize yourself with our project CODE OF CONDUCT. These guidelines are intended to govern interactions with and within the nhc2-hobby-api community.

Hobby API Documentation

The Hobby API encapsulated by this library is documented by Niko which can be found here

Warranty Disclaimer

You may use this library with the understanding that doing so is AT YOUR OWN RISK. No warranty, express or implied, is made with regards to the fitness or safety of this code for any purpose. If you use this library to query or change settings of your installation you understand that it is possible to break your installation and may require the replace of devices or intervention of professionals of which costs cannot be returned by the project team.

Please be careful not to use this library in a way that puts massive load on the Connected Controller of your NHC2 installation. Spamming the controller with a huge load of messages will stress the controller and may reduce it's lifespan. For example prefer to use a push system for listening on changes instead of polling an accessory every x milliseconds.

Installation

In order to use the library and/or samples you must first download and install NodeJS. An installable nhc2-hobby-api module for npm is available.

To download and install the library and all of its dependencies to a local project directory use the following:

npm install @openhomekit/nhc2-hobby-api

To install dependencies via npm, from the root level of the library directory type:

npm install

This library and its accompanying samples are still under development. New features, samples and bug fixes may be added regularly. To ensure that you have the very latest version of nhc2-hobby-api and it's dependencies be sure to update frequently.

To do so, from your project directory type:

npm update

Library Usage Examples

Connecting the Hobby API

Login in to mynikohomecontrol and add the Hobby API to your connected services. This will provide you with a password which in formatted as a JWT token and valid for 1 year. The following properties are set by Niko:

• The port is fixed to 8884
• The username is fixed to hobby

    var nhc2 = require('nhc2-hobby-api');
    
    var nhc2 = new nhc2.NHC2('mqtts://<IP_ADDRESS_OF_YOUR_CONNECTED_CONTROLLER>', {
        port: 8884,
        clientId: '<YOUR_UNIQUE_CLIENT_ID_NAME>',
        username: 'hobby',
        password: '<PASSWORD_PROVIDED_BY_MYNIKOHOMECONTROLL>',
        rejectUnauthorized: false,
    });

Note: The clientId should be unique to the MQTT service provided by the Connected Controller. If multiple connections with the same ClientId are running these will continuously disconnect/reconnect and may skip MQTT messages since messages are not retained and broadcasted with QoS set to 0.

We need to wait until subscriptions to MQTT topics are completed before we are able to control the installation. This can be done using the NHC2.prototype.subscribe method which returns a promise.

    nhc2.subscribe().then(function () {
        // Now you are ready to start querying NHC2
    });

Because of the async process we are dealing with when sending/receiving messages, and the possible callback hell, it is preferred to make use of the Javascript async/await syntax.

    (async () => {
        await nhc2.subscribe();
        // Now you are ready to start querying NHC2
    })();

Get a list of all connected accessories

    var accessories = await nhc2.getAccessories();

Note: currently only accessories of type action are returned since these are the only accessories which we can control.

Listen on incoming events

NHC2.prototype.getEvents will return an Observable stream containing incoming events.

    nhc2.getEvents().subscribe(event => console.log(event));

Note: currently only events controlling accessories of type light or dimmer are returned.

Change the status of an accessory

NHC2.prototype.sendStatusChangeCommand allows you to control the status of lights.

    var light = accessories[21];
    nhc2.sendStatusChangeCommand(light.Uuid, true);

Change the brightness of an accessory

NHC2.prototype.sendStatusChangeCommand allows you to control the status of lights.

    var dimmableLight = accessories[21];
    nhc2.sendBrightnessChangeCommand(dimmableLight.Uuid, 0);

Samples

A collection of samples is provided in the samples directory. These demonstrate some basic usage scenarios for the library. These samples are written in typescript, in order to run them you need to compile them first.

cd samples
tsc turn-on-all-lights.ts 
node turn-on-all-lights.js 

Releasing a new version

To release a new version it is sufficient to bump the version number and push the changes, then create a new version on github that will create a tag for you. Github CI will see the new version and publish to NPM.