npm package: @openhomekit/nhc2-hobby-api
Description: A wrapper library for the Niko Home Control 2 Hobby API
Latest version: 2.5.0

# nhc2-hobby-api 
[![Version](http://img.shields.io/npm/v/@openhomekit/nhc2-hobby-api.png)](https://www.npmjs.com/package/@openhomekit/nhc2-hobby-api)
[![License](https://img.shields.io/npm/l/@openhomekit/nhc2-hobby-api.svg)](https://github.com/homebridge-nhc2/nhc2-hobby-api/blob/master/LICENSE)
[![Downloads](https://img.shields.io/npm/dt/@openhomekit/nhc2-hobby-api.svg)](https://www.npmjs.com/package/@openhomekit/nhc2-hobby-api)
[![Node.js Package](https://github.com/openhomekit/nhc2-hobby-api/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/openhomekit/nhc2-hobby-api/actions/workflows/npm-publish.yml)

As of October 29, 2019 Niko has published their [Hobby API](https://www.niko.eu/en/campaign/niko-home-control/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](https://github.com/mqttjs/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)
* toggle an EV charger, or change its charging mode

## Changes

You can read the complete history of changes in the 
[CHANGELOG](https://github.com/homebridge-nhc2/nhc2-hobby-api/blob/master/CHANGELOG.md).

## 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](https://github.com/homebridge-nhc2/homebridge-nhc2) 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](https://github.com/homebridge-nhc2/nhc2-hobby-api/blob/master/CONTRIBUTING.md) 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](https://github.com/homebridge-nhc2/nhc2-hobby-api/blob/master/CODE_OF_CONDUCT.md). 
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](https://mynikohomecontrol.niko.eu/Content/hobbyapi/documentation.pdf)
	
# 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](http://nodejs.org). An installable [nhc2-hobby-api](https://www.npmjs.com/package/@openhomekit/nhc2-hobby-api) module for [npm](http://npmjs.org) 
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](https://mynikohomecontrol.niko.eu/) 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`

```javascript
    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.
```javascript
    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.
```javascript
    (async () => {
        await nhc2.subscribe();
        // Now you are ready to start querying NHC2
    })();

```
## Get a list of all connected accessories
```javascript
    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.

```javascript
    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.

```javascript
    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.

```javascript
    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.