How to enable Emulated Hue in Home Assistant on Umbrel OS

Support and Troubleshooting
1

How to enable Emulated Hue in Home Assistant on Umbrelos

I’m documenting the steps I took to get Alexa to recognize Home Assistant’s Emulated Hue running on Umbrel OS:

1. Configure macvlan network for the Home Assistant container

I configured the Home Assistant container to use a macvlan network, assigning it its own IP on the local network.

This configuration was necessary to avoid conflicts with the ports used by Umbrel, especially port 80, which is required by Emulated Hue but was already in use.

2. Collect network information

Before configuring the macvlan network, it is important to know:

  • Network gateway
  • Subnet (netmask)
  • Network interface (e.g. eth0, enx0, etc.)

You can obtain this information by running the command:

ifconfig

And to find out the default gateway, use:

ip route

Ex:

version: '3.7'
services:
  homeassistant:
    image: homeassistant/home-assistant:2025.4.1
    container_name: homeassistant
    networks:
      home_net:
        ipv4_address: 10.0.0.50 # put a free IP on your network here
    privileged: true
    ports:
      - "8123:8123"
    volumes:
      - ${APP_DATA_DIR}/data:/config
      - ${UMBREL_ROOT}/home/Downloads:/media
      - /dev:/dev
      - /run/dbus:/run/dbus:ro
    restart: unless-stopped
networks:
  home_net:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 10.0.0.0/24
          gateway: 10.0.0.1

3. Configure Home Assistant via configuration.yaml

In this step, I kept the basic, default Home Assistant configuration, only adding the necessary parameters to enable Emulated Hue.

No significant changes were made beyond that.

# Loads default set of integrations. Do not remove.
default_config:

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

emulated_hue:
  advertise_ip: 10.0.0.50
  upnp_bind_multicast: true
  host_ip: 10.0.0.50
  advertise_port: 80
  listen_port: 80
  expose_by_default: false
  entities:
    input_boolean.botao_virtual:
      hidden: false

Testing

After configuring the files, you need to restart the Home Assistant container for the changes to take effect.

Note: In some cases, you may need to restart the Umbrel server completely for everything to work properly.

Checking if it’s working

Access the IP you defined for Home Assistant. In my case, I used:

You can also test with the following URLs:

  • http://<HOME_ASSISTANT_IP>:80/description.xml

It should return an XML file with the Emulated Hue information.

  • http://<HOME_ASSISTANT_IP>:80/api/v2/lights

Should return the list of devices (lights, scenes, groups, etc.) that are being exposed to Alexa via Emulated Hue.