node-hue-api
An API library for Node.js that interacts with the Philips Hue Bridge to control Lights, schedules, sensors and the
various other features of the Hue Bridge.
This library abstracts away the actual Philips Hue Bridge REST API and provides all of the features of the Philips API
and a number of useful functions to control/configure its various features.
The library fully supports local network and remote internet access to the Hue Bridge API and has 100% coverage of the
documented Hue API.
Contents
Change Log
For a list of changes, and details of the fixes/improvements, bugs resolved, please refer to the change log;
Change Log
Installation
Node.js using npm:
$ npm install node-hue-api
Node.js using yarn:
$ yarn add node-hue-api
v3 API
The V3 API is written to support JavaScript native Promises, as such you can use standard Promise chaining with then()
and catch() or utilize synchronous async and await in your own code base.
As of release 4.0.0 in December 2019, the library now has complete coverage for the Hue REST API.
Connections to the Bridge
By default all connections to the Hue Bridge are done over TLS, after the negotiation of the Bridge certificate being
verified to the expected format and subject contents.
The Bridge certificate is self-signed, so this will cause issues when validating it normally. The library will process
the certificate, validate the issuer and the subject and if happy will then allow the connection over TLS with the Hue
Bridge.
When using the remote API functionality of the library, the certificate is validated normally as the https://api.meethue.com
site has an externally valid certificate and CA chain.
Note: There is an option to connect over HTTP using createInsecureLocal() as there are some instances of use of the
library against software the pretends to be a Hue Bridge. Using this method to connect will output warnings on the console
that you are connecting in an insecure way.
Rate Limiting
As of version 4.0+ of the library there are Rate limiters being used in three places:
- For the whole library, API calls are limited to 12 per second
- For
lights.setLightState(), API calls are limited to 10 per second
- For
groups.setState(), API calls are limited to 1 per second
These defaults are not currently configurable, but have been implemented to conform to the best practices defined in the
Hue API documentation. If you are facing issues with this, then raise a support ticket via an Issue.
Note: these do NOT (and cannot) take into account all access to the Hue Bridge, so if you have other software that also
accesses the bridge, it is still possible to overload it with requests.
Debug Bridge Communications
You can put the library in to debug mode which will print out the placeholder and request details that it is using to
talk to the Hue Bridge.
To do this, you need to define an environment variable of NODE_DEBUG and ensure that it is set to a string that
contains node-hue-api in it.
Once the debug mode is active you will see output like the following on the console:
Bridge Certificate:
subject: {"C":"NL","O":"Philips Hue","CN":"xxxxxxxxx"}
issuer: {"C":"NL","O":"Philips Hue","CN":"xxxxxxxxx"}
valid from: Jan 1 00:00:00 2017 GMT
valid to: Jan 1 00:00:00 2038 GMT
serial number: xxxxxxx
Performing validation of bridgeId "xxx" against certificate subject "xxx"; matched? true
URL Placeholders:
username: { type:string, optional:false, defaultValue:null }
Headers: {"Accept":"application/json"}
{
"method": "get",
"baseURL": "https://192.xxx.xxx.xxx:443/api",
"url": "/xxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
URL Placeholders:
username: { type:string, optional:false, defaultValue:null }
Headers: {"Accept":"application/json","Content-Type":"application/json"}
{
"method": "post",
"baseURL": "https://192.xxx.xxx.xxx:443/api",
"url": "/xxxxxxxxxxxxxxxxxxxxxxxx/schedules",
"data": {
"name": "Test Schedule Recurring",
"description": "A node-hue-api test schedule that can be removed",
"command": {
"address": "/api/xxxxxxxxxxxxxxxxxxxxxxxxxx/lights/0/state",
"method": "PUT",
"body": {
"on": true
}
},
"localtime": "W124/T12:00:00",
"status": "enabled",
"recycle": true
}
}
Note: You should be careful as to who can gain access to this output as it will contain sensitive data including the
MAC Address of the bridge, IP Address and username values.
The above warning applies here with respect to schedule when not in debug mode, as the schedule endpoints will contain the
username value (that can be used to authenticate against the bridge) in the payloads of the command.
v2 API Compatibility
In the version 4.x releases of this library all backwards compatibility to the much older Q promise and callback
functionality was removed (as was indicated in the 3.x documentation).
What was provided in the 3.x versions of this library to provide some backward compatibility has now been moved into
another library node-hue-api-v2-shim.
The node-hue-api-v2-shim is only provided to allow you to continue to use the older v2 API functionality in code you
may have had previously written and there are downsides to using it. You are strongly encouraged to migrate to the v3
API provided in this library (which is where any new features and improvements will be made going forward).
API Documentation
Examples
The v3 APIs are documented using example code and links to more complex/complete examples for each API calls, consult
the documentation links above.
Alternatively take a look at the examples directory in this repository for complete self-contained
runnable example code.
Discover and connect to the Hue Bridge for the first time
For getting started interacting with the Hue Bridge, you will need to discover and then connect to the Hue Bridge as an
authorized user. To do this you need to either know the IP Address of the Hue Bridge in advance, or use the discovery
features to locate it.
Once you know the IP Address of the Bridge, you need to create a user that is authorized to interact with the Hue Bridge,
this is typically done by pressing the Link button on the bridge and then attempting to register a new user via code.
Below is example code that can be used to achieve this (using async/await to avoid nested Promises):
const v3 = require('node-hue-api').v3
, discovery = v3.discovery
, hueApi = v3.api
;
const appName = 'node-hue-api';
const deviceName = 'example-code';
async function discoverBridge() {
const discoveryResults = await discovery.nupnpSearch();
if (discoveryResults.length === 0) {
console.error('Failed to resolve any Hue Bridges');
return null;
} else {
return discoveryResults[0].ipaddress;
}
}
async function discoverAndCreateUser() {
const ipAddress = await discoverBridge();
const unauthenticatedApi = await hueApi.createLocal(ipAddress).connect();
let createdUser;
try {
createdUser = await unauthenticatedApi.users.createUser(appName, deviceName);
console.log('*******************************************************************************\n');
console.log('User has been created on the Hue Bridge. The following username can be used to\n' +
'authenticate with the Bridge and provide full local access to the Hue Bridge.\n' +
'YOU SHOULD TREAT THIS LIKE A PASSWORD\n');
console.log(`Hue Bridge User: ${createdUser.username}`);
console.log(`Hue Bridge User Client Key: ${createdUser.clientkey}`);
console.log('*******************************************************************************\n');
const authenticatedApi = await hueApi.createLocal(ipAddress).connect(createdUser.username);
const bridgeConfig = await authenticatedApi.configuration.getConfiguration();
console.log(`Connected to Hue Bridge: ${bridgeConfig.name} :: ${bridgeConfig.ipaddress}`);
} catch(err) {
if (err.getHueErrorType() === 101) {
console.error('The Link button on the bridge was not pressed. Please press the Link button and try again.');
} else {
console.error(`Unexpected Error: ${err.message}`);
}
}
}
discoverAndCreateUser();
The complete code sample above is available from here.
For more details on discovery of Hue Bridges, check out the discovery API and referenced examples
along with the users API.
Set a Light State on a Light
Once you have created your user account and know the IP Address of the Hue Bridge you can interact with things on it.
To interact with light on the Hue Bridge you can use the following:
const v3 = require('node-hue-api').v3;
const LightState = v3.lightStates.LightState;
const USERNAME = 'your username to authenticating with the bridge'
, LIGHT_ID = 1
;
v3.discovery.nupnpSearch()
.then(searchResults => {
const host = searchResults[0].ipaddress;
return v3.api.createLocal(host).connect(USERNAME);
})
.then(api => {
const state = new LightState()
.on()
.ct(200)
.brightness(100)
;
return api.lights.setLightState(LIGHT_ID, state);
})
.then(result => {
console.log(`Light state change was successful? ${result}`);
})
;
For more details on interacting with lights, see the lights API and LightState
documentation and examples referenced within.
Using Hue Remote API
This library has support for interacting with the Hue Remote API as well as local network connections. There are some
limitations on the remote endpoints, but the majority of them will function as they would on a local network.
It can be rather involved to set up a remote connection, but not too onerous if you desire such a thing.
The complete documentation for doing this is detailed in the Remote API and associated links.
Philips Hue Resources
There are a number of resources where users have detailed documentation on the Philips Hue Bridge;
License
Copyright 2013-2019. All Rights Reserved.
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this library except in compliance with the License.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
评论