- What is this?
- Local Express API Install
- PowerShell Module Installation
- PowerShell Module Usage
- PowerShell Aliases
A locally-run Node Express API
application with an accommodating PowerShell Module
that can be used to control Philips Hue
lights.
Why not? This is a random personal project that I worked on during part of my end-of-year holiday break in 2020.
I use the Windows Terminal
a whole lot throughout my regular workday and I thought it would be neat if I could change the color of a Philips Hue
light (I've got a bunch since I went all in in 2016) from a PowerShell prompt to basically give my family unobtrusive alerts when I'm in a meeting and unavailable. I wanted access to proper invoke PowerShell functions, but also be able to type onair
or offair
to toggle the light whenever I start a call.
This project was the result.
I also started looking into automating the onair/offair commands based on my presence in Teams - however, that would require me to request special permissions from my organization. If I were to gain those permissions, that would be completely doable with this setup.
I wanted to rock a Express
node API application because it's a break from .NET
and seemed like promising stack for what I wanted to achieve. Once I had a working API
and PowerShell Module
where I was operating my lights using my shiny new PowerShell functions.
Lots of experimentation π§ͺπ¨βπ¬
All of this was always meant to be ran locally in Docker
for portability. I definitely don't intend to deploy this anywhere publicly. In my case, I was able to set up a Raspberry Pi
to run the Docker container and 'remotely' access the API from other devices on my networking using the Pi's local IP address.
There are two parts:
-
Locally run
Express
-basedNodeJS
API wrapper application that interacts with thePhilips Hue Remote Hue Developer APIs
.- Preferably run on
Docker
(Windows and Linux* flavors available)
- Preferably run on
-
Windows PowerShell Module
which acts as a wrapper for theexpress
API endpoints.- Bonus: corresponding set of
PowerShell aliases
to go 'onair' and 'offair' from the terminal.
- Bonus: corresponding set of
These are the projects that helped build this project quickly. π
http://localhost:9000/authorize
- One time setup, except when tokens expire.
http://localhost:9000/lights
- List of all connected lights on the Hue bridge.
-
http://localhost:9000/lights/setlightstate
- Sets the light state of all inputted device ids.
Params
Name | Type | Required? | Description |
---|---|---|---|
lightids | Array of int |
β | Target light IDs to send updated light state to. List can be obtained via /lights endpoint |
colorstate | string |
β | Preset hue values. Accepts yellow , green , blue , pink , or red |
hue | int |
β | Hue int value (max value: 65535 ) |
saturation | int |
- | Saturation int value (max value: 100 ) |
brightness | int |
- | Brightness int value (max value: 100 ) |
alert | bool |
- | Short blink when transitioning light state. |
onstate | bool |
- | Flag to set the light ON state. (default onstate : true) Use /lights/setlightstate/on and /lights/setlightstate/off instead. |
The request requires
colorstate
ORhue
to be present, but not both. If both are present, the response will result in a400 Bad Request
status.
Request JSON Body Examples
-
Set light
20
to preset colorblue
.{"colorstate": "blue", "lightids" : [20]}
-
Set lights
16
and20
to preset colorgreen
.{"colorstate": "green", "lightids" : [16, 20], "brightness": 50}
-
Set lights
16
and20
to preset colorpink
with50%
brightness and100%
saturation.{"colorstate": "pink", "lightids" : [16, 20], "brightness": 50, "saturation": 100}
-
Set lights
16
to preset colorred
and blink during transition.{"colorstate": "red", "lightids" : [16], "alert": true}
-
http://localhost:9000/lights/setlightstate/on
- Sets the light state of all inputted device ids to on state.
-
http://localhost:9000/lights/setlightstate/off
- Sets the light state of all inputted device ids to off state.
The express API can run locally with npm installed or in Docker. I use Docker to keep it running in the background so I can interact with it whenever I'd like.
node -v
11 and above
Required
-
Run
npm install
-
Run
node index.js
-
Run
npm install apidoc -g
Optional
npm install forever -g
There two Dockerfiles
to support the Express API
running in either Windows Containers
or Linux Containers
.
Linux Containers
are preferred for this stack, but if you intend to have theDocker
container running while usingWindows Containers
, theDockerfile
forWindows
is also available.
Depends on Official Docker Images for node
docker pull node
-
Switch to Linux Containers in Docker
-
Build the image against
Dockerfile.Linux
docker build --pull --rm -f "local-hue-controls\hue-express-node-api\Dockerfile.Linux" -t hue-express-node-api "local-hue-controls\hue-express-node-api"
-
Run the image
docker run --rm -d -p 9000:9000/tcp hue-for-powershell:latest
The Dockerfile.Windows
is a modified version of stefanscherer/node-windows
-
Switch to
Windows Containers
-
Build the image
- In VS Code, right-click on
Dockerfile.Windows
and give the build a name/tag, and hit enter.
Or run
docker build --pull --rm -f "hue-for-powershell\Dockerfile" -t hue-for-powershell:latest "hue-for-powershell"` against `Dockerfile.Windows`
- In VS Code, right-click on
-
Run the image
docker run --rm -d -p 9000:9000/tcp windows-hue-node:latest`
Using
Windows Containers
for this project requiresnpm install
to have ran locally since thenode_modules
is copied to the container when the image is built.
-
Copy the
hue-for-powershell
folder into to a location to a validPSModulePath
path registered- Run
$Env:PSModulePath
to find one.
- Run
-
Run
Import-Module hue-for-powershell
-
Run
Get-HueLightsList
to see if everything is working.
Synopsis | Gets the list of registered lights from the Hue Bridge. |
Description | This function will call the /lights endpoint of the application. |
Examples | Get-HueLightsList |
Get-HueLightsList -OutGridView | |
Get-HueLightsList - ExcludeUnreachable |
Synopsis | Invokes an ON light state action against a series of lights based on of the device ID. |
Description | Calls the /lights/setlightstate/on API endpoint. |
Example | Invoke-HueLightsOn -LightIdArray @(1) |
Invoke-HueLightsOn -LightIdArray @(2, 6) | |
Invoke-HueLightsOn -LightIdArray @(2, 6. 12) |
Synopsis | Invokes an OFF light state action against a series of lights based on of the device ID. |
Description | Calls the /lights/setlightstate/off API endpoint. |
Example | Invoke-HueLightsOff -LightIdArray @(1) |
Invoke-HueLightsOff -LightIdArray @(2, 6) | |
Invoke-HueLightsOff -LightIdArray @(2, 6. 12) |
Synopsis | Invokes an updated light state action against a series of lights based on the device ID. |
Description | Calls the /lights/setlightstate API endpoint. |
Invoke-HueLightSwitch -LightIdArray @(int, int, int) `
-Color "default" `
-Hue 65535 `
-Saturation 100 `
-Brightness 50 `
-Alert
Color | Sample |
---|---|
Green | Invoke-HueLightSwitch -LightIdArray $array -Color "green" -Alert |
Blue | Invoke-HueLightSwitch -LightIdArray $array -Color "blue" -Alert |
Red | Invoke-HueLightSwitch -LightIdArray $array -Color "red" -Alert |
Pink | Invoke-HueLightSwitch -LightIdArray $array -Color "pink" -Alert |
Yellow | Invoke-HueLightSwitch -LightIdArray $array -Color "yellow" -Alert |
Run onair
or offair
to trigger 3 lights.
onair
turns the lights to redoffair
turns them to a neutral soft white
Edit your PowerShell profile (run > code $profile
)
Paste the following and modify the LightIdArray
.
Set-Alias onair Invoke-OnAirLights
function Invoke-OnAirLights {
[CmdletBinding()]
param([Parameter(Position=0)]
[string]$Query
)
Invoke-HueLightSwitch -LightIdArray @(7, 20) -Color "red" -Alert
}
Set-Alias offair Invoke-OffAirLights
function Invoke-OffAirLights {
[CmdletBinding()]
param([Parameter(Position=0)]
[string]$Query
)
Invoke-HueLightSwitch -LightIdArray @(7, 20) -Color "default" -Alert
}