Node-hue
A minimalist approch to wrap the hue clip v2 api using pure javascript. There are no model objects and helper methods. The result of the calls are provided as they are returned by the hue bridge. The API methods return promises and can be used together with await.
Getting started
A hue user key is needed to access the bridge. This key can be obtained by following the advice here. Automatic discovery using mDNS is not supported. You need to know your hue bridge IP or have a valid host dns entry.
Example: List all lights
This example lists all lights with their ID and ui name.
const hueApi = require('node-hue');
run = async () => {
const hue = hueApi.connect();
let lights = await hue.getLights();
lights.forEach(light => {
console.log(light.id+"\t"+light.metadata.name);
});
}
run();
Executing this example may produce a result like this one:
227cf111-a326-4d27-8d9f-c3e2e464b1a9 Kitchen lamp
c81f9556-b504-417d-8aee-2275b71a761d Bedroom lamp
17c0bd7e-d7c3-43d6-9c85-a440ffa50930 Garden lamp
Using events
The library hue-push-client is used to retrieve the hue bridge notifications (server side events).
Example: React on events
This example lists endlessly for events emitted by the hue bridge.
const hueApi = require('node-hue');
run = async () => {
const listener = (event) => {
console.log(JSON.stringify(event,1,1));
}
const hue=hueApi.connect( {
eventListener : listener // The eventlistener is given as option
});
}
run();
More examples can be found in the examples folder.
API connect options
The connect method accepts these options.
| Property | Description |
|---|---|
| host | Hostname or address of you hue bridge. Can also be set by the enviroment variable HUE_HOST and defaults to hue. |
| key | API access key. Can also be set by the enviroment variable HUE_KEY. |
| eventListener | The event listener callback. A method with one parameter for the data. |
| log | A custom log implementation, that provides the functions trace, debug, info, warn and error. |
Environment variables
| Environment variable | Description | Default |
|---|---|---|
| HUE_HOST | Hostname or address of you hue bridge. | hue |
| HUE_KEY | API access key. | |
| LOG_LEVEL | Log level : TRACE,DEBUG,INFO,WARN,ERROR | INFO |
API reference
This API reference is generated from the list of supported resources provided by the hue api. It should cover all methods that are provided by the clip V2 api. If you want to access the hue api description, you need a developer login at the meethue side.
| Method | Description | HTTP method | Hue api link |
|---|---|---|---|
| getLights() | Get all light(s). | GET | API Link |
| getLight(id) | Get single light. | GET | API Link |
| createLight(data) | Create light. | POST | API Link |
| setLight(id,data) | Update light. | PUT | API Link |
| getScenes() | Get all scene(s). | GET | API Link |
| getScene(id) | Get single scene. | GET | API Link |
| createScene(data) | Create scene. | POST | API Link |
| setScene(id,data) | Update scene. | PUT | API Link |
| deleteScene(id) | Delete scene. | DELETE | API Link |
| getRooms() | Get all room(s). | GET | API Link |
| getRoom(id) | Get single room. | GET | API Link |
| createRoom(data) | Create room. | POST | API Link |
| setRoom(id,data) | Update room. | PUT | API Link |
| deleteRoom(id) | Delete room. | DELETE | API Link |
| getZones() | Get all zone(s). | GET | API Link |
| getZone(id) | Get single zone. | GET | API Link |
| createZone(data) | Create zone. | POST | API Link |
| setZone(id,data) | Update zone. | PUT | API Link |
| deleteZone(id) | Delete zone. | DELETE | API Link |
| getBridgeHomes() | Get all bridge_home(s). | GET | API Link |
| getBridgeHome(id) | Get single bridge_home. | GET | API Link |
| getGroupedLights() | Get all grouped_light(s). | GET | API Link |
| getGroupedLight(id) | Get single grouped_light. | GET | API Link |
| setGroupedLight(id,data) | Update grouped_light. | PUT | API Link |
| getDevices() | Get all device(s). | GET | API Link |
| getDevice(id) | Get single device. | GET | API Link |
| setDevice(id,data) | Update device. | PUT | API Link |
| deleteDevice(id) | Delete device. | DELETE | API Link |
| getBridges() | Get all bridge(s). | GET | API Link |
| getBridge(id) | Get single bridge. | GET | API Link |
| setBridge(id,data) | Update bridge. | PUT | API Link |
| deleteBridge(id) | Delete bridge. | DELETE | API Link |
| getDevicePowers() | Get all device_power(s). | GET | API Link |
| getDevicePower(id) | Get single device_power. | GET | API Link |
| setDevicePower(id,data) | Update device_power. | PUT | API Link |
| getZigbeeConnectivitiys() | Get all zigbee_connectivitiy(s). | GET | API Link |
| getZigbeeConnectivitiy(id) | Get single zigbee_connectivitiy. | GET | API Link |
| setZigbeeConnectivitiy(id,data) | Update zigbee_connectivitiy. | PUT | API Link |
| getZgpConnectivitys() | Get all zgp_connectivity(s). | GET | API Link |
| getZgpConnectivity(id) | Get single zgp_connectivity. | GET | API Link |
| setZgpConnectivity(id,data) | Update zgp_connectivity. | PUT | API Link |
| getZigbeeDeviceDiscoverys() | Get all zigbee_device_discovery(s). | GET | API Link |
| getZigbeeDeviceDiscovery(id) | Get single zigbee_device_discovery. | GET | API Link |
| setZigbeeDeviceDiscovery(id,data) | Update zigbee_device_discovery. | PUT | API Link |
| getMotions() | Get all motion(s). | GET | API Link |
| getMotion(id) | Get single motion. | GET | API Link |
| setMotion(id,data) | Update motion. | PUT | API Link |
| getTemperatures() | Get all temperature(s). | GET | API Link |
| getTemperature(id) | Get single temperature. | GET | API Link |
| setTemperature(id,data) | Update temperature. | PUT | API Link |
| getLightLevels() | Get all light_level(s). | GET | API Link |
| getLightLevel(id) | Get single light_level. | GET | API Link |
| setLightLevel(id,data) | Update light_level. | PUT | API Link |
| getButtons() | Get all button(s). | GET | API Link |
| getButton(id) | Get single button. | GET | API Link |
| setButton(id,data) | Update button. | PUT | API Link |
| getRelativeRotarys() | Get all relative_rotary(s). | GET | API Link |
| getRelativeRotary(id) | Get single relative_rotary. | GET | API Link |
| setRelativeRotary(id,data) | Update relative_rotary. | PUT | API Link |
| getBehaviorScripts() | Get all behavior_script(s). | GET | API Link |
| getBehaviorScript(id) | Get single behavior_script. | GET | API Link |
| getBehaviorInstances() | Get all behavior_instance(s). | GET | API Link |
| getBehaviorInstance(id) | Get single behavior_instance. | GET | API Link |
| createBehaviorInstance(data) | Create behavior_instance. | POST | API Link |
| setBehaviorInstance(id,data) | Update behavior_instance. | PUT | API Link |
| deleteBehaviorInstance(id) | Delete behavior_instance. | DELETE | API Link |
| getGeofenceClients() | Get all geofence_client(s). | GET | API Link |
| getGeofenceClient(id) | Get single geofence_client. | GET | API Link |
| createGeofenceClient(data) | Create geofence_client. | POST | API Link |
| setGeofenceClient(id,data) | Update geofence_client. | PUT | API Link |
| deleteGeofenceClient(id) | Delete geofence_client. | DELETE | API Link |
| getGeolocations() | Get all geolocation(s). | GET | API Link |
| getGeolocation(id) | Get single geolocation. | GET | API Link |
| setGeolocation(id,data) | Update geolocation. | PUT | API Link |
| getEntertainmentConfigurations() | Get all entertainment_configuration(s). | GET | API Link |
| getEntertainmentConfiguration(id) | Get single entertainment_configuration. | GET | API Link |
| createEntertainmentConfiguration(data) | Create entertainment_configuration. | POST | API Link |
| setEntertainmentConfiguration(id,data) | Update entertainment_configuration. | PUT | API Link |
| deleteEntertainmentConfiguration(id) | Delete entertainment_configuration. | DELETE | API Link |
| getEntertainments() | Get all entertainment(s). | GET | API Link |
| getEntertainment(id) | Get single entertainment. | GET | API Link |
| setEntertainment(id,data) | Update entertainment. | PUT | API Link |
| getHomekits() | Get all homekit(s). | GET | API Link |
| getHomekit(id) | Get single homekit. | GET | API Link |
| setHomekit(id,data) | Update homekit. | PUT | API Link |
| getMatters() | Get all matter(s). | GET | API Link |
| getMatter(id) | Get single matter. | GET | API Link |
| setMatter(id,data) | Update matter. | PUT | API Link |
| getMatterFabrics() | Get all matter_fabric(s). | GET | API Link |
| getMatterFabric(id) | Get single matter_fabric. | GET | API Link |
| deleteMatterFabric(id) | Delete matter_fabric. | DELETE | API Link |
| getSmartScenes() | Get all smart_scene(s). | GET | API Link |
| getSmartScene(id) | Get single smart_scene. | GET | API Link |
| deleteSmartScene(id) | Delete smart_scene. | DELETE | API Link |
| getResources() | Get all resources. | GET | API Link |
| close() | Closes the hue connection. Removes a eventually registered event listener. | ||
| getDocumentation() | Returns this API documentation as markdown. |
Motivation
There are tons of hue api libraries around for the usage with node.js. But most provide just a subset of the available features or are based on the v1 api. They are often written in typescript and using data models. May be convenient in the usage, but missing flexibility. This library is handling the http request/response while keeping the original response value and without wrapping or changing the json data expected by the hue bridge. The dependency list should be short. For a home automation service I need fast access to buttons, temperature sensors, motion sensors, lights together with the possibility to get push events from the bridge. I didn't found it in the existing libraries - so this one was born.