{"id":13528388,"url":"https://github.com/peter-murray/node-hue-api","last_synced_at":"2025-05-14T23:07:35.148Z","repository":{"id":6213345,"uuid":"7444512","full_name":"peter-murray/node-hue-api","owner":"peter-murray","description":"Node.js Library for interacting with the Philips Hue Bridge and Lights","archived":false,"fork":false,"pushed_at":"2024-04-09T13:58:08.000Z","size":1567,"stargazers_count":1196,"open_issues_count":29,"forks_count":146,"subscribers_count":39,"default_branch":"typescript","last_synced_at":"2025-04-13T19:50:01.033Z","etag":null,"topics":["hue","hue-api","hue-bridge","hue-lights","javascript","lights","nodejs","scene","schedule","smart-home","smarthome"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peter-murray.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-01-04T17:45:57.000Z","updated_at":"2025-03-09T19:37:22.000Z","dependencies_parsed_at":"2024-06-18T12:30:23.345Z","dependency_job_id":"97a10d8e-5383-4a3c-b741-24b3edcb8e1c","html_url":"https://github.com/peter-murray/node-hue-api","commit_stats":{"total_commits":401,"total_committers":29,"mean_commits":"13.827586206896552","dds":0.6134663341645885,"last_synced_commit":"081da8354c761d3405ddf240ed53d83e01ee7a6c"},"previous_names":[],"tags_count":86,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-hue-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-hue-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-hue-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-murray%2Fnode-hue-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-murray","download_url":"https://codeload.github.com/peter-murray/node-hue-api/tar.gz/refs/heads/typescript","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254243362,"owners_count":22038046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hue","hue-api","hue-bridge","hue-lights","javascript","lights","nodejs","scene","schedule","smart-home","smarthome"],"created_at":"2024-08-01T06:02:30.256Z","updated_at":"2025-05-14T23:07:30.137Z","avatar_url":"https://github.com/peter-murray.png","language":"TypeScript","readme":"# node-hue-api\n\n[![npm](https://img.shields.io/npm/v/node-hue-api.svg)](http://npmjs.org/node-hue-api)\n\nAn API library for Node.js that interacts with the Philips Hue Bridge to control Lights, schedules, sensors and the \nvarious other features of the Hue Bridge.\n\nThis library abstracts away the actual Philips Hue Bridge REST API and provides all of the features of the Philips API \nand a number of useful functions to control/configure its various features.\n\nThe library fully supports `local network` and `remote internet` access to the Hue Bridge API and has 100% coverage of the \ndocumented Hue API.\n\n\n## Contents\n- [Change Log](#change-log) \n- [Installation](#installation)\n- [v3 API](#v3-api)\n    - [Connections to the Bridge](#connections-to-the-bridge)\n    - [Rate Limiting](#rate-limiting)\n    - [Debug Bridge Communications](#debug-bridge-communications)\n    - [v2 Compatibility](#v2-api-compatibility)\n    - [API Documentation](#api-documentation)\n        - [Discovering Local Hue Bridges](docs/discovery.md)\n        - [Remote API Support](docs/remoteApi.md)\n        - [Users](docs/users.md)\n        - [Lights](docs/lights.md)\n            - [Light Object](docs/light.md)\n            - [LightState Object](docs/lightState.md)\n        - [Sensors](docs/sensors.md)\n            - [Sensor Objects](docs/sensor.md)\n        - [Scenes](docs/scenes.md)\n            - [Scene Object](docs/scene.md)\n            - [SceneLightState Object](docs/lightState.md#scenelightstate)\n        - [Groups](docs/groups.md)\n            - [Group Objects](docs/group.md)\n            - [GroupLightState Object](docs/lightState.md#grouplightstate)\n        - [Rules](docs/rules.md)\n            - [Rule Object](docs/rule.md)\n            - [RuleCondition Object](docs/ruleCondition.md)\n            - [RuleAction Object](docs/ruleAction.md)\n        - [ResourceLinks](/docs/resourcelinks.md)\n            - [ResourceLink Object](docs/resourceLink.md)\n        - [Schedules](docs/schedules.md)\n            - [Schedule Object](docs/schedule.md)\n            - [Time Patterns](docs/timePatterns.md)\n        - [Configuration](docs/configuration.md)\n        - [Capabilities](docs/capabilities.md)\n        - [Remote](docs/remote.md)\n- [Examples](#examples)\n    - [Discover and connect to the Hue Bridge for the first time](#discover-and-connect-to-the-hue-bridge-for-the-first-time)\n    - [Set a LightState on a Light](#set-a-light-state-on-a-light)\n    - [Using Hue Remote API](#using-hue-remote-api)\n- [Philips Hue Resources](#philips-hue-resources)\n- [License](#license)\n\n\n\n## Change Log\nFor a list of changes, and details of the fixes/improvements, bugs resolved, please refer to the change log;\n[Change Log](Changelog.md)\n\n## Installation\n\nNode.js using npm:\n```\n$ npm install node-hue-api\n```\n\nNode.js using yarn:\n```\n$ yarn add node-hue-api\n```\n\n## v3 API\n\nThe V3 API is written to support JavaScript native Promises, as such you can use standard Promise chaining with `then()` \nand `catch()` or utilize synchronous `async` and `await` in your own code base.\n\nAs of release `4.0.0` in December 2019, the library now has complete coverage for the Hue REST API.\n\n\n### Connections to the Bridge\nBy default all connections to the Hue Bridge are done over TLS, after the negotiation of the Bridge certificate being \nverified to the expected format and subject contents.\n\nThe Bridge certificate is self-signed, so this will cause issues when validating it normally. The library will process \nthe certificate, validate the issuer and the subject and if happy will then allow the connection over TLS with the Hue \nBridge.\n\nWhen using the remote API functionality of the library, the certificate is validated normally as the https://api.meethue.com\nsite has an externally valid certificate and CA chain.\n\n_Note: There is an option to connect over `HTTP` using `createInsecureLocal()` as there are some instances of use of the \nlibrary against software the pretends to be a Hue Bridge. Using this method to connect will output warnings on the `console`\nthat you are connecting in an insecure way_.\n\n\n### Rate Limiting\nAs of version 4.0+ of the library there are Rate limiters being used in three places:\n\n* For the whole library, API calls are limited to 12 per second\n* For `lights.setLightState()`, API calls are limited to 10 per second\n* For `groups.setState()`, API calls are limited to 1 per second\n\nThese defaults are not currently configurable, but have been implemented to conform to the best practices defined in the \nHue API documentation. If you are facing issues with this, then raise a support ticket via an Issue.\n\n_Note: these do NOT (and cannot) take into account all access to the Hue Bridge, so if you have other softare that also \naccesses the bridge, it is still possible to overload it with requests._\n\n\n### Debug Bridge Communications\nYou can put the library in to debug mode which will print out the placeholder and request details that it is using to \ntalk to the Hue Bridge.\n\nTo do this, you need to define an environment variable of `NODE_DEBUG` and ensure that it is set to a string that \ncontains `node-hue-api` in it.\n\nOnce the debug mode is active you will see output like the following on the console:\n\n```\nBridge Certificate:\n  subject:       {\"C\":\"NL\",\"O\":\"Philips Hue\",\"CN\":\"xxxxxxxxx\"}\n  issuer:        {\"C\":\"NL\",\"O\":\"Philips Hue\",\"CN\":\"xxxxxxxxx\"}\n  valid from:    Jan  1 00:00:00 2017 GMT\n  valid to:      Jan  1 00:00:00 2038 GMT\n  serial number: xxxxxxx\n\nPerforming validation of bridgeId \"xxx\" against certifcate subject \"xxx\"; matched? true\nURL Placeholders:\n  username: { type:string, optional:false, defaultValue:null }\nHeaders: {\"Accept\":\"application/json\"}\n{\n  \"method\": \"get\",\n  \"baseURL\": \"https://192.xxx.xxx.xxx:443/api\",\n  \"url\": \"/xxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n}\nURL Placeholders:\n  username: { type:string, optional:false, defaultValue:null }\nHeaders: {\"Accept\":\"application/json\",\"Content-Type\":\"application/json\"}\n{\n  \"method\": \"post\",\n  \"baseURL\": \"https://192.xxx.xxx.xxx:443/api\",\n  \"url\": \"/xxxxxxxxxxxxxxxxxxxxxxxx/schedules\",\n  \"data\": {\n    \"name\": \"Test Schedule Recurring\",\n    \"description\": \"A node-hue-api test schedule that can be removed\",\n    \"command\": {\n      \"address\": \"/api/xxxxxxxxxxxxxxxxxxxxxxxxxx/lights/0/state\",\n      \"method\": \"PUT\",\n      \"body\": {\n        \"on\": true\n      }\n    },\n    \"localtime\": \"W124/T12:00:00\",\n    \"status\": \"enabled\",\n    \"recycle\": true\n  }\n}\n```\n\n_Note: You should be careful as to who can gain access to this output as it will contain sensative data including the \nMAC Address of the bridge, IP Address and username values._\n\nThe above warning applies here with respect to schedule when **not** in debug mode, as the schedule endpoints will contain the\nusername value (that can be used to authenticate against the bridge) in the payloads of the `command`.\n\n\n## v2 API Compatibility\nIn the version 4.x releases of this library all backwards compatibility to the much older Q promise and callback\nfunctionality was removed (as was indicated in the 3.x documentation). \n\nWhat was provided in the 3.x versions of this library to provide some backward comaptibility has now been moved into \nanother library [node-hue-api-v2-shim](https://github.com/peter-murray/node-hue-api-v2-shim).\n\n_The `node-hue-api-v2-shim` is only provided to allow you to continue to use the older v2 API functionality in code you \nmay have had previously written and there are downsides to using it. You are strongly encouraged to migrate to the v3 \nAPI provided in this library (which is where any new features and improvements will be made going forward)._\n\n\n## API Documentation\n- [Discovering Local Hue Bridges](docs/discovery.md)  \n- [Remote API Support](docs/remoteApi.md)\n- [Users](docs/users.md)\n- [Lights](docs/lights.md)\n    - [Light Object](docs/light.md)\n- [Sensors](docs/sensors.md)\n    - [Sensor Objects](docs/sensor.md)\n- [Scenes](docs/scenes.md)\n    - [Scene Object](docs/scene.md)\n    - [SceneLightState Object](docs/lightState.md#scenelightstate)\n- [Groups](docs/groups.md)\n    - [Group Objects](docs/group.md)\n    - [GroupLightState Object](docs/lightState.md#grouplightstate)\n- [Rules](docs/rules.md)\n    - [Rule Object](docs/rule.md)\n    - [RuleCondition Object](docs/ruleCondition.md)\n    - [RuleAction Object](docs/ruleAction.md)\n- [ResourceLinks](docs/resourcelinks.md)\n    - [ResourceLink Object](docs/resourceLink.md)\n- [Schedules](docs/schedules.md)\n    - [Schedule Object](docs/schedule.md)\n    - [Time Patterns](docs/timePatterns.md)\n- [Configuration](docs/configuration.md)\n- [Capabilities](docs/capabilities.md)\n- [Remote](docs/remote.md)\n\n\n## Examples\nThe v3 APIs are documented using example code and links to more complex/complete examples for each API calls, consult \nthe documentation links [above](#v3-api).\n\nAlternatively take a look at the [examples directory](examples/v3) in this repository for complete self contained \nrunnable example code.\n\n---\n\n### Discover and connect to the Hue Bridge for the first time\n\nFor getting started interacting with the Hue Bridge, you will need to discover and then connect to the Hue Bridge as an\nauthorized user. To do this you need to either know the IP Address of the Hue Bridge in advance, or use the discovery \nfeatures to locate it.\n\nOnce you know the IP Address of the Bridge, you need to create a user that is authorized to interact with the Hue Bridge,\nthis is typically done by pressing the `Link` button on the bridge and then attempting to register a new user via code.\n\nBelow is example code that can be used to achieve this (using async/await to avoid nested Promises):\n```js\nconst v3 = require('node-hue-api').v3\n  , discovery = v3.discovery\n  , hueApi = v3.api \n;\n\nconst appName = 'node-hue-api';\nconst deviceName = 'example-code';\n\nasync function discoverBridge() {\n  const discoveryResults = await discovery.nupnpSearch();\n\n  if (discoveryResults.length === 0) {\n    console.error('Failed to resolve any Hue Bridges');\n    return null;\n  } else {\n    // Ignoring that you could have more than one Hue Bridge on a network as this is unlikely in 99.9% of users situations\n    return discoveryResults[0].ipaddress;\n  }\n}\n\nasync function discoverAndCreateUser() {\n  const ipAddress = await discoverBridge();\n\n  // Create an unauthenticated instance of the Hue API so that we can create a new user\n  const unauthenticatedApi = await hueApi.createLocal(ipAddress).connect();\n  \n  let createdUser;\n  try {\n    createdUser = await unauthenticatedApi.users.createUser(appName, deviceName);\n    console.log('*******************************************************************************\\n');\n    console.log('User has been created on the Hue Bridge. The following username can be used to\\n' +\n                'authenticate with the Bridge and provide full local access to the Hue Bridge.\\n' +\n                'YOU SHOULD TREAT THIS LIKE A PASSWORD\\n');\n    console.log(`Hue Bridge User: ${createdUser.username}`);\n    console.log(`Hue Bridge User Client Key: ${createdUser.clientkey}`);\n    console.log('*******************************************************************************\\n');\n\n    // Create a new API instance that is authenticated with the new user we created\n    const authenticatedApi = await hueApi.createLocal(ipAddress).connect(createdUser.username);\n\n    // Do something with the authenticated user/api\n    const bridgeConfig = await authenticatedApi.configuration.getConfiguration();\n    console.log(`Connected to Hue Bridge: ${bridgeConfig.name} :: ${bridgeConfig.ipaddress}`);\n\n  } catch(err) {\n    if (err.getHueErrorType() === 101) {\n      console.error('The Link button on the bridge was not pressed. Please press the Link button and try again.');\n    } else {\n      console.error(`Unexpected Error: ${err.message}`);\n    }\n  }\n}\n\n// Invoke the discovery and create user code\ndiscoverAndCreateUser();\n```\n\nThe complete code sample above is available from [here](./examples/v3/discoverAndCreateUserScript.js).\n\nFor more details on discovery of Hue Bridges, check out the [discovery API](./docs/discovery.md) and referenced examples \nalong with the [users API](./docs/users.md). \n\n\n---\n\n### Set a Light State on a Light\nOnce you have created your user account and know the IP Address of the Hue Bridge you can interact with things on it. \nTo interact with light on the Hue Bridge you can use the following:\n\n```js\nconst v3 = require('node-hue-api').v3;\nconst LightState = v3.lightStates.LightState;\n\nconst USERNAME = 'your username to authenticating with the bridge'\n  // The name of the light we wish to retrieve by name\n  , LIGHT_ID = 1\n;\n\nv3.discovery.nupnpSearch()\n  .then(searchResults =\u003e {\n    const host = searchResults[0].ipaddress;\n    return v3.api.createLocal(host).connect(USERNAME);\n  })\n  .then(api =\u003e {\n    // Using a LightState object to build the desired state\n    const state = new LightState()\n      .on()\n      .ct(200)\n      .brightness(100)\n    ;\n    \n    return api.lights.setLightState(LIGHT_ID, state);\n  })\n  .then(result =\u003e {\n    console.log(`Light state change was successful? ${result}`);\n  })\n;\n```\n\nFor more details on interacting with lights, see the [lights API](./docs/lights.md) and [LightState](./docs/lightState.md) \ndocumentation and examples referenced within.\n\n\n### Using Hue Remote API\nThis library has support for interacting with the `Hue Remote API` as well as local network connections. There are some\nlimitations on the remote endpoints, but the majority of them will function as they would on a local network.\n\nIt can be rather involved to set up a remote connection, but not too onerous if you desire such a thing.\n\nThe complete documentation for doing this is detailed in the [Remote API](docs/remoteApi.md) and associated links.\n\n* [Example for connecting remotely for the first time](./examples/v3/remote/accessFromScratch.js)\n* [Example for connecting using existing OAuth tokens](./examples/v3/remote/accessWithTokens.js) \n\n\n## Philips Hue Resources\n\nThere are a number of resources where users have detailed documentation on the Philips Hue Bridge;\n - The Official Phillips Hue Documentation \u003chttp://www.developers.meethue.com\u003e\n - Hue Hackers Mailing List: \u003chttps://groups.google.com/forum/#!forum/hue-hackers\u003e\n - StackOverflow: \u003chttp://stackoverflow.com/questions/tagged/philips-hue\u003e\n\n\n## License\nCopyright 2013-2019. All Rights Reserved.\n\nLicensed under the Apache License, Version 2.0 (the \"License\"); you may not use this library except in compliance with the License.\n\nYou may obtain a copy of the License at \u003chttp://www.apache.org/licenses/LICENSE-2.0\u003e.\n\nUnless 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.\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-murray%2Fnode-hue-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-murray%2Fnode-hue-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-murray%2Fnode-hue-api/lists"}