OpenHue API
OpenHue is an open-source project that provides a comprehensive OpenAPI specification for the Philips Hue REST API, known as CLIP (Connected Lighting Interface Protocol) API.
This specification serves as a bridge between developers and Philips Hue smart lighting systems, enabling seamless integration
and control of Hue lighting within various applications and platforms.
📣 Follow the project roadmap and join the discussion in our GitHub Discussions!
Table of Contents
Introduction
The Philips Hue lighting system is renowned for its versatility and convenience in home and commercial lighting solutions.
However, developers often face challenges when attempting to interact with Hue devices programmatically due to the complexity
of the underlying REST API. OpenHue aims to simplify this process by offering a well-structured and fully-documented OpenAPI specification.
With OpenHue, developers can:
- Effortlessly Integrate Philips Hue: OpenHue provides a clear and standardized way to connect your applications and services with Philips Hue smart lighting, allowing for easy automation, customization, and remote control of lighting scenes and individual bulbs.
- Enhance User Experiences: By integrating OpenHue into your projects, you can create innovative lighting experiences that respond to user interactions, environmental conditions, or specific events, enhancing user comfort and ambiance.
- Save Development Time: Avoid the complexities of reverse-engineering the Philips Hue API. OpenHue eliminates the need for developers to decipher the API’s intricacies and reduces development time, enabling faster implementation of Hue-related features.
Supported Resources
The OpenHue specification covers the following Hue API resources:
- Lighting: light, grouped_light
- Rooms & Zones: room, zone, bridge_home
- Scenes: scene, smart_scene
- Sensors: motion, temperature, light_level, button, bell_button, relative_rotary, contact, tamper, camera_motion
- Grouped Sensors: grouped_motion, grouped_light_level
- Motion Areas: convenience_area_motion, security_area_motion, motion_area_candidate, motion_area_configuration
- Devices: device, device_power, device_software_update, bridge, service_group
- Connectivity: zigbee_connectivity, zgp_connectivity, wifi_connectivity, zigbee_device_discovery
- Entertainment: entertainment, entertainment_configuration, speaker
- Automation: behavior_script, behavior_instance, geofence_client, geolocation
- Smart Home: homekit, matter, matter_fabric
Quick Start
# Get the OpenAPI spec
curl -O https://api.redocly.com/registry/bundle/openhue/openhue/v2/openapi.yaml
# Or generate a client (e.g., Python)
npx @openapitools/openapi-generator-cli generate -g python -i https://api.redocly.com/registry/bundle/openhue/openhue/v2/openapi.yaml -o my-openhue-client
Usage
To use the OpenHue OpenAPI specification in your projects, you can obtain it from our GitHub releases. Here’s how:
Obtain the OpenAPI Specification
The OpenHue OpenAPI Specification is hosted on Redocly,
you can directly obtain it via this link.
Click here
to view the specification via the Swagger Editor.
From GitHub
- Visit our GitHub releases page.
- Select the desired release version that suits your needs. Each release contains the complete OpenAPI specification for OpenHue.
- Download the
openhue.yaml file from the selected release. This YAML file represents the OpenAPI specification, which defines the structure and behavior of the OpenHue API.
Integration with Postman
You can easily import the OpenAPI specification into Postman, a popular API development and testing tool. Here’s how:
- Open Postman and click on the “Import” button in the top-left corner of the application.
- Select “API schema” as the import type.
- Upload the
openhue.yaml file that you downloaded from the OpenHue release.
- Postman will automatically generate a collection based on the OpenAPI specification, allowing you to make requests to the OpenHue API with ease.
Generate Client Code
The OpenAPI specification openhue.yaml can be used to generate client code in virtually any programming language.
There are various tools and libraries available that can take the specification,
and generate client code tailored to your language of choice.
Here’s a basic example using the openapi-generator-cli to generate a Python client:
npx @openapitools/openapi-generator-cli generate -g python -i https://api.redocly.com/registry/bundle/openhue/openhue/v2/openapi.yaml -o my-openhue-project
ℹ️ openapi-generator-cli requires Java 17 to be installed
Getting Started
To begin developing with OpenHue’s OpenAPI specification, follow these steps:
Prerequisites
Before you start, ensure that you have the following prerequisites installed:
- Git: For cloning and version control.
- Node.js and NPM: OpenHue relies on Node.js and NPM for certain tasks. Make sure you have them installed. You can download them from the official website: Node.js.
- Make: For running build commands (pre-installed on macOS/Linux).
Fork the Repository
Before contributing to OpenHue, it’s a good practice to fork the repository to your own GitHub account.
This will create a copy of the project that you can work on independently. See CONTRIBUTING.md for detailed contribution guidelines.
Setup
- Clone the OpenHue repository to your local machine:
git clone https://github.com/your-username/openhue-api.git
cd openhue-api
- Run the following command to set up the development environment. This will install the Redocly CLI, which is used for documentation management:
make setup
Validate the Specification
Before proceeding, it’s essential to ensure that the OpenAPI specification is valid and error-free. You can do this by running the following command:
make verify
This command will validate the specification file and provide feedback if there are any issues.
Build the Specification
To bundle the OpenAPI specification into a single file, run the following command:
make build
The bundled specification file can be found at build/openhue.yaml. This consolidated file makes it easier to work with the API definition and can be used for various purposes, including generating client libraries and documentation.
Build the Documentation
To build the static HTML documentation, run the following command:
make docs
The bundled documentation can be found at build/index.html.
The build/ folder will also contain all the files required to display the HTML page, including images, fonts, etc.
With these initial setup steps completed, you’re ready to start developing and utilizing the OpenHue OpenAPI specification for your projects.
License
OpenHue is distributed under the Apache License 2.0,
making it open and free for anyone to use and contribute to.
See the license file for detailed terms.
Acknowledgments
We want to extend our heartfelt gratitude to GitBook for their generous support of the OpenHue Project. GitBook’s commitment to helping open-source initiatives like ours thrive is truly appreciated. They have graciously provided the OSS plan for OpenHue, which will be instrumental in our documentation efforts, making it easier for developers and users to get started with OpenHue.
评论