hue_control_api v0.1.1

Hue Control API

An API library for Node.js that interacts with the Philips Hue bridge to control lights, rooms/zones, scenes and various other features of the Hue bridge using the new V2 API (and some features from V1 quin' have not yet been put on the V2).

This library is currently in alpha, the majority of the essential features are already present and usable but the others such as the rule engine or the entertainment areas are not yet integrated. To see what features are available and which are coming soon, please see the Features section.

Contents

• Installation
• Concept
• Basic Usage Connect to Hue Bridge By discovering By IP By bridge ID By remote Using auth code * Using Hue auth portal
• Features Bridge Global Device (light/accessory) Light/Plug Accessory Group (room/zone) Scene Automation Entertainment Matter Homekit

Installation

Node.js using npm:

$ npm install hue_control_api

Concept

The whole library works on the principle of resource and event, all objects are based on the class Resource and the resources send events when a light, room, button, ... is updated on the bridge.

When connecting to through the local network, it is therefore not necessary to do light.getColor() for example, using instead light.on("color", color => console .log(color)), you would immediately have the up-to-date values.

This system makes it possible to work in real time and to be able to react quickly (like updating a graphic interface for example).

Basic usage

There are 4 possibilities of connection to a bridge, discovering all bridge available in local network, the direct connection to an IP, by its unique ID through the search for a bridge on the local network or thanks to the remote identifier.

Connect to Hue bridge

By discovering

import {Connector} from  "hue_control_api";

const  connector  =  new  Connector();

connector.on("hue_bridge_infos", async  bridge  =>
{
	let  bridgeData;

	console.log("Wait linking...");
	bridgeData  =  await  connector.registerHueBridgeApp(bridge, "<APPLICATION_NAME>");
	console.log(`Bridge linked ! (ip: ${bridgeData.ip}, id: ${bridgeData.id}, appKey: ${bridgeData.appKey})`);
	bridge  =  await  connector.loadHueBridge(bridgeData.id, bridgeData.appKey);

	// Print all rooms/zones with their devices and scenes in the console
	bridge.describe();
})

await  connector.discover();

By IP

import {Connector, Bridge} from  "hue_control_api";

async function main()
{
	const  connector  =  new  Connector();
	const  bridge  =  new  Bridge("<BRIDGE_IP>", "<APPLICATION_KEY>", null, connector);

	await  bridge.connect();

	// Print all rooms/zones with their devices and scenes in the console
	bridge.describe();
}

main();

By bridge ID

import {Connector} from  "hue_control_api";

async  function  main()
{
	const  connector  =  new  Connector();
	const  bridge  =  await  connector.loadHueBridge("<BRIDGE_ID>", "<APPLICATION_KEY>");

	// Print all rooms/zones with their devices and scenes in the console
	bridge.describe();
}

main();

By remote

Using auth code

import {Connector} from  "hue_control_api";

async  function  main()
{
	const  connector  =  new  Connector({clientID: "<HUE_CLIENT_ID>", clientSecret: "<HUE_CLIENT_SECRET>"});
	const  bridgeID  =  "<BRIDGE_ID>";
	const  remoteAccess  =  await  connector.getToken(bridgeID, "<APPLICATION_KEY>", {code: "<AUTH_CODE>", codeVerifier: "<AUTH_CODE_VERFIFIER>"});
	const  bridge  =  await  connector.loadHueBridge(bridgeID, , "<APPLICATION_KEY>", remoteAccess);

	// Print all rooms/zones with their devices and scenes in the console
	bridge.describe();
}

main();

Using Hue auth portal

import {Connector} from  "hue_control_api";

async  function  main()
{
	const  connector  =  new  Connector({clientID: "<HUE_CLIENT_ID>", clientSecret: "<HUE_CLIENT_SECRET>"});
	const  bridgeID  =  "<BRIDGE_ID>";
	let  remoteAccess;
	let  bridge;

	connector.registerAuthorizationCallback(async (endpoints, clientID, state) =>
	{
		/**
		 * Here, execute request to Hue auth portal
		 * The request should return code and code verifier to continue the authentication
		 */
		return ({code: "<AUTH_CODE>", codeVerifier: "<AUTH_CODE_VERFIFIER>"});
	});
	// The getToken method will execute the authorization callback
	remoteAccess  =  await  connector.getToken(bridgeID, "<APPLICATION_KEY>");
	bridge  =  await  connector.loadHueBridge(bridgeID, "<APPLICATION_KEY>", remoteAccess);

	// Print all rooms/zones with their devices and scenes in the console
	bridge.describe();
}

main();

Features

Below thte list of features currently supported by this library

Bridge

Global Device (light, accessory)

Light/Plug

* Compliant with Philips Hue API but not tested with physical device ** New feature documented by Philips but not released, so not testable (sunrise effect)

Accessory

Motion sensor

Global Switch

Dimmer switch :x:

No additional support currently

Hue button :x:

No additional support currently

Wall switch :x:

No additional support currently

Tap dial switch :x:

No additional support currently

Group (room/zone)

Room

Zone

Scene

Automation

Behavior :x:

Not supported currently

Rule :x:

Not supported currently

Schedule :x:

Not supported currently

Entertainment :x:

Not supported currently

Matter :x:

Not supported currently

Homekit :x:

Not supported currently