tob1no/shelly-hue-helper repository overview

⁠Control Philips Hue lights using Shelly URL actions!

This repo contains a custom implementation of a node.js server that listens for HTTP requests from a shelly light switch (URL action) in order to transform them into a HTTP PUT to control a light connected to a Philips Hue bridge.

Why bother? The default URL action from the shelly just trigger a simple HTTP GET to a specific URL. The Philips Hue bridge API requires HTTP PUT with a data body in order to control the lights.

Supported and tested OSs Although it has only been tested on amd64 Linux, this should also run on aarch64 (RPi 3/4/5).

⁠Prerequisites

I don't really know why, but you need to enable MQTT on the shelly in order to get URL actions to work correctly. I just found this out on my shelly1 running the firmware 20230913-112003/v1.14.0-gcb84623.

⁠Philips API user

You need to create an authenticated user on your Philips Hue bridge⁠. Then, take notes of your bridge IP and the user ID.

⁠Get the light(s) ID

Visit http://<your-bridge-ip>/api/<your-user>/lights, if you're using Google Chrome, select pretty print and take notes of the light's ID you want to control (you can search for your light's name and then find the ID above).

⁠Run the image

NOTE: Make sure to set <your-bridge-ip> to the IP address of your Philips Hue bridge and <your-api-key> to the user created above. You can then run the docker container using docker run:

docker run --name shelly-hue-helper -h shelly-hue-helper --restart unless-stopped -e BRIDGE_IP=<your-bridge-ip> -e API_KEY=<your-api-key> -p 3000:3000 tob1no/shelly-hue-helper:v1.2

Or if you prefer docker compose:

shelly-hue-helper:
    container_name: shelly-hue-helper
    hostname: shelly-hue-helper
    image: tob1no/shelly-hue-helper:v1.2
    restart: unless-stopped
    environment:
      - "BRIDGE_IP=<your-bridge-ip>"
      - "API_KEY=<your-api-key>"
    ports:
      - 3000:3000

⁠Configure the shelly

From the main menu, go to URL actions and expand Button switched On URL. Enable it, and insert the following string: http://<docker-ip>:3000/light/<light-id>/1 For Button switched Off URL, do the same, just make sure that the final value is 0.

NOTE: Make sure to replace <docker-ip> with the IP address of the host you're running shelly-hue-helper on and <light-id> with the actual ID of the light you want to control.