An AppDaemon app for advanced lighting control via Home Assistant or MQTT
Set light data based on time of day, use Mode Change events or environmental conditions like lux levels, rain, and sensors like motion, presence and media players.

• Mode-based automation with MODE_CHANGE events
• Lux-based lighting with rain and time configurations
• Multiple sensor inputs for maximum flexibility

This app is designed to work with:

• AppDaemon
• Home Assistant

Home Assistant is a popular open-source home automation platform that offers a wide range of features and integrations with various smart home devices. If you're not already using Home Assistant, I recommend checking it out.

AppDaemon is a loosely coupled, multi-threaded, sandboxed Python execution environment for writing automation apps for various types of home automation software, including Home Assistant and MQTT.

1. Have Home Assistant and Appdaemon up and running

2. git clone into your AppDaemon apps directory.

3. Add configuration to a .yaml or .toml file to enable the ElectricalManagement module.

4. Add the configuration to your .yaml file:

Minimum Configuration

your_room_name:
  module: lightwand
  class: Room
  Lights:
    - lights:
      - light.yourLight

Define lights using Lights, MQTTLights, or ToggleLights.

Use Home Assistant switches/lights. Example:

Lights:
  - lights:
    - light.kitchen

Use MQTT for devices like Zigbee2MQTT.

MQTTLights:
  - lights:
    - zigbee2mqtt/YourLight

For bulbs that dim with toggle actions:

ToggleLights:
  - lights:
    - switch.toggle_bulb
    toggle: 2  # Number of toggles to reach desired brightness
    num_dim_steps: 3  # Steps in bulb dimming
    toggle_speed: 0.8 # Set time in seconds between each toggle

      light_modes:
        - mode: night
          toggle: 3

Toggle lights does not support motion or time based automations, only a mode with a toggle. If you need motion use Light with only on/off.

Use MODE_CHANGE events to activate predefined or custom modes.

self.fire_event("MODE_CHANGE", mode='your-mode-name')

day:
  alias: "your_mode_name"
  sequence:
    - event: MODE_CHANGE
      event_data:
        mode: 'your-mode-name'

Custom Mode Names

• With the exception of custom and reset, you can use any mode name in light_modes.
• You can overwrite default behavior by configuring the mode.
• In addition to night (or its translation, such as nacht) mode you can configure modes beginning with night, for instance night-kid-bedroom. All modes starting with night or off will by default disable motion detection.

• Normal: Safe for automations; does not override manual changes.
• Reset: Forces lights back to their original normal settings.

To change the mode for a single room, use the mode name + _appName.

• appName is the name you defined for your app in the configuration.

As an alternative to firing an event, you can use a Home Assistant selector with selector_input.

• The app will update the selector options dynamically based on MODE_CHANGE events.
• Version 2.0.0 and later auto populates the selector_input with valid modes for the room.
• Use selector_input_exclude_modes to exclude mode names from the selector. Note that if the active mode is not in the selector it will show the old name.

your_room_name:
  ...
  selector_input: input_select.livingroom_mode_light
  selector_input_exclude_modes:
    - away
    - wash

1. Save the File Persistently
   Store the supplied example translation.json in a location that persists across sessions and updates (e.g., /config/lightwand/translation.json).

2. Edit the Translation File
   Modify translation.json to update the mode names and event settings.

   Tip
   In translation.json, you can specify a custom event name (e.g., "LIGHT_MODE") instead of the default "MODE_CHANGE" to match your existing automations.

   Only translate the words that already exist in the default file. The json file only contains mode names with a predefined action.

3. Specify the Path and Language in Configuration
   Use the language_file parameter and lightwand_language to set your preferred language in one of your room‑app configurations:

   your_room_name:
     ...
     language_file: /config/lightwand/translation.json
     lightwand_language: "en"

   Lightwand creates a singleton that can be imported by other apps to listen to the same modes.

4. Consistency Across the System
   If you translate a word (for instance, "off" → "aus" and "night" → "nacht"), every app that uses the translation will recognize the new word. These mode names are pre defined and have some logic behind it and you can then do modes like "nachtKinderzimmer" (nightChildRoom) to treat the room as in night mode. To turn off only in the livingroom you would use "aus_Wohnzimmer". If you have translated "off" → "aus" a call like off_LivingRoom would be interpreted as a custom mode named "off" rather than the built‑in off‑logic, leading to unexpected behaviour.

   The translated names will need to be changed throughout your entire setup in everything from scripts to other automations.

Note
Custom Modes Are Your Choice Any mode that you create outside the predefined set is a light mode where you must specify either state or light_data.

• These do not need to be added to translation.json.

Note
Translating night and off also results in the app checking if a mode name starts with the translated mode name equivalent, to turn off and prevent motion.

• light_data contains attributes like brightness, color, and transition. It defines the specific light settings for each scenario (e.g., automations, modes, or motion events).

Example:

      automations:
        light_data:
          brightness: 80
          transition: 3
          color:
            x: 0.5075
            y: 0.4102

Lightwand can be used together with the Adaptive Lighting custom component for Home Assistant to automatically adjust the minimum and maximum brightness in modes, in addition to turning lights on and off. However, Lightwand does not know what brightness level Adaptive Lighting will set, so when combined with motion the light may dim instead of brighten when motion is detected.

• To use Adaptive Lighting in automations, motionlights, or modes, define state: adaptive. Check out the wiki for Adaptive Lighting setup.

• state: Controls on/off behavior for lights.

  • Default behavior depends on the mode being used:
    • In normal and user defined modes, the default is turn_on.
    • In away, night, or off modes, the default is turn_off (as described in the "Mode Change Events" section).
  • If no state is explicitly defined, the mode's default behavior applies.

• turn_off: Turns the light off at the given time or in the specified mode.

• adjust: Does not turn the light on or off, but adjusts it to the light_data defined for the current state.

• pass: Lightwand will apply the light_data as a "turn on" command, but will not send a new command if the light is already on. Lights running a program (e.g., "sunrise" effect in Philips Hue) will restart the program every time a new command is sent.

• manual: Lightwand will not interact with the light in this mode.

• lux_controlled: The light will be on if lux levels are below the defined lux_constraint.

Example:

      light_modes:
        - mode: decor
          state: lux_controlled
      lux_constraint: 5000

Automations are configured by defining an array of time-based rules. These can be clock-based, solar-based (using sunrise/sunset times), or a combination of both.

Key Rules for Automations:

• When lightmode is set to normal, Lightwand checks for defined light_data and state in automations.
• Automations can also be configured under motionlights and light_modes.
• For a light to turn on when the selected lightmode is an automation, both lux_constraint and conditions must pass.

• Automations use time to define when changes occur.
• Use orLater to combine solar and clock-based times for seasonal accuracy.
• If orLater is used, all subsequent times are shifted by the same timedelta unless fixed: True is defined.
• fixed: True locks the time from being moved or deleted.

Example:

      automations:
        - time: '08:00:00'
          orLater: 'sunrise + 00:15:00'
        - time: '20:00:00'
          fixed: True
          state: turn_off

Configure motionlights to define how lights react to motion detection.

Minimum Configuration:

  motion_sensors:
    - sensor: binary_sensor.yourMotionSensor
  Lights:
    - lights:
      - light.kitchen
      motionlights:

Key Rules for Motion Behavior:

• For the light to turn on, both lux_constraint and conditions must pass if the lightmode is normal.
• If another mode is active, behavior depends on how that mode is configured.

Example with motionlights and light_data:

      motionlights:
      - time: '00:00:00'
        light_data:
          brightness: 3
      - time: '03:00:00'
        state: turn_off
      - time: '06:50:00'
        light_data:
          brightness: 160
      - time: '08:30:00'
        orLater: 'sunrise + 00:15:00'
        light_data:
          brightness: 180
      - time: 'sunrise + 01:30:00'
        light_data:
          brightness: 120
      - time: '20:00:00'
        orLater: 'sunset + 00:30:00'
        dimrate: 2
        light_data:
          brightness: 3

Light modes are defined under light_modes as an array. They can include:

• automations for time-based settings
• light_data for specific attributes
• state (e.g., lux_controlled, turn_off, or manual)

Example with Multiple Configurations:

      light_modes:
        - mode: morning
          light_data:
            brightness: 220
            transition: 3
            color_temp: 427
        - mode: decor
          offset: -20 # Optional offset from brightness defined in normal mode
        - mode: tv
          state: turn_off
        - mode: away
          state: lux_controlled
        - mode: nightKid
          state: manual
        - mode: night
          automations:
            - time: '00:00:00'
            - time: '03:00:00'
              state: turn_off
            - time: '23:00:00'
        - mode: low_with_Automation
          automations:
            - light_data:
                brightness: 20

There are several options to fine-tune how lights behave:

Use dimrate in automations to control how quickly brightness changes (e.g., dimrate: 2 = 1 brightness unit per 2 minutes). The light will dim from the last timed brightness until the target brightness is met.

Use offset to dynamically increase or decrease brightness for dimmable lights when motionlights or light_modes are active. The offset is applied to the brightness defined in light_data.

Example:

  motionlights:
    offset: 35

• exclude_from_custom: Excludes the room from custom and wash modes (useful for outdoor or kid’s rooms).
• prevent_off_to_normal: Keeps lights off if a new mode is normal.
• prevent_night_to_morning: Keeps lights in night mode if a new mode is morning or normal.
• dim_while_motion: Enables dimming of lights when motion is detected.

• night_motion: Enables motion detection during night mode.

Set an input_boolean (or similar) as enable_light_control for switches/lights you only use for special occations like christmas or during winter time.
The app will control the light/switch only if this switch is ON.
If the switch is OFF, the app will leave the light untouched, allowing other tasks to use it.

NOTE
The setting is read only at startup, so you must restart AppDaemon (or the app) to enable/disable control.

Example:

  # Configure in room
  options:
    - exclude_from_custom
    - dim_while_motion
    - prevent_off_to_normal
    - prevent_night_to_morning
  MQTTLights:
    - lights:
      - zigbee2mqtt/ENTRE_Switch
      # Configure in light
      options:
        - night_motion
      enable_light_control: input_boolean.xmas_light_control

• Weather Data: Use the ad-Weather app for optimal integration. It consolidates all your weather sensors into a single app and publishes events for other apps to consume.

  ⚠️ Important: If you configure weather sensors directly in Lightwand, they will take precedence over the ad-Weather app.

You can define two outdoor lux sensors. The second sensor can be defined with a suffix of _2. The app will use the higher lux value or the last updated value if the other sensor hasn't updated in the last 15 minutes. Use OutLux_sensor for Home Assistant sensors and OutLuxMQTT for MQTT sensors.

• Only one room lux sensor can be defined, and it can be either an MQTT or Home Assistant entity.
• Rain sensors currently only support Home Assistant entities.

Example:

  OutLux_sensor: sensor.lux_sensor
  OutLuxMQTT_2: zigbee2mqtt/OutdoorHueLux
  RoomLux_sensor: sensor.lux_sensor
  RoomLuxMQTT: zwave/KITCHEN_sensor/sensor_multilevel/endpoint_0/Illuminance
  rain_sensor: sensor.netatmo_rain

You can define the time delay (in seconds) after motion detection before the lights return to normal. You can also define constraints for each sensor using an python if statement checked againts the ast_evaluator.py. These constraints must be true for motion to activate.

Example:

  motion_sensors:
    - sensor: binary_sensor.yourMotionSensor
  MQTT_motion_sensors:
    - sensor: zigbee2mqtt/KITCHEN_sensor
      delay: 60
      constraints: "self.now_is_between('06:50:00', '23:00:00') and self.get_tracker_state('person.wife') == 'home' or self.get_state('switch.kitch_espresso') == 'on' "

For presence tracking, define the trackers in the presence section. When a tracker is home, the app will switch to presence mode. If presence is not defined in light_modes or constraints are not met then the room will switch to normal mode. If all defined trackers are not home, the room will switch to away mode.

Example:

  presence:
    - sensor: person.wife
      constraints: "self.now_is_between('06:30:00', '23:00:00') "

• The bed_sensors feature keeps the light in night mode until the bed is exited.
  You can now define a constraint for the bed sensor that, when it is not true, will prevent the bed from being considered occupied.

Example:

  bed_sensors: 
    - sensor: binary_sensor.bed_occupied
      delay: 5

Sorted by priority if more than one media player is defined in a room. You can use any entity with an on/off state (e.g., sensors, switches).

• Define the mode name for each media player.
• Define light_data in light_modes for the corresponding mode.

Behavior:

• The "media mode" will override normal lighting behavior when motion is detected, during morning, normal, or night* modes.

Example:

  mediaplayers:
    - mediaplayer: binary_sensor.yourXboxGamerTag
      mode: pc
    - mediaplayer: media_player.tv
      mode: tv
      delay: 30

You can use lux sensors to control or constrain lights. Optionally, you can define IF statements that must be met for the light to turn on during normal, morning, or motion modes, or when automations are triggered. The app inherits the AppDaemon API as self.ADapi.

Example Use Case:
I use this on some lights in my living room and kitchen to detect if my wife is not home, without setting the room to away mode.

To define custom conditions, create a listen_sensors list for the sensors you use in your statements. The app will update the light when any condition changes.

Example:

  listen_sensors:
    - person.wife
  # Some light data...
  conditions:
    - "self.ADapi.get_tracker_state('person.wife') == 'home'"
  keep_on_conditions:
    - "self.ADapi.get_tracker_state('person.wife') == 'home'"
  lux_constraint: 12000
  room_lux_constraint: 100

If you've configured all your lights to your liking, the normal automation should suffice for day-to-day use. However, there are times when you may need to make manual adjustments, such as for special events or when the automation doesn't match your needs.

  - lights:
    - light.spot1
    - light.spot2

Each lightwand app will write the current light mode on termination to a json file and read it on initialization. Default location for json files is pyton {self.AD.config_dir}/persistent/lightwand/ . You can overrule this by defining json_path.

Define MQTT/HASS namespaces if not using defaults:

MQTT_namespace: mqtt
HASS_namespace: default

Add delays to avoid network congestion:

  mode_turn_off_delay: 2
  mode_turn_on_delay: 2

You can also add a random delay random_turn_on_delay defined with an number, and the lights in the room, will be turned on/off randomly between zero and the given number in seconds. This applies to every change, including motion.

  random_turn_on_delay: 2

• Use MQTT Explorer to find device topics.
• Group Zigbee devices in your controller to reduce network load.
• Adaptive Lighting can be used with adaptive_switch and adaptive_sleep_mode.

Easisest to start off with is to copy this example and update with your sensors and lights and build from that. There is a lot of list/dictionaries that needs to be correctly indented. And remember: All sections and configurations are optional, so you use only what is applicable.

your_room_name:
  module: lightwand
  class: Room
  # Configure path to store Json for mode and lux data. This will give you some persistency when restarted. Adds 'your_room_name' + '.json' to the json_path
  json_path: /path/to/your/storage/
  language_file: /conf/apps/Lightwand/translations.json
  lightwand_language: no

  # Namespaces for MQTT and HASS if other than default.
  MQTT_namespace: mqtt
  HASS_namespace: hass
  # Lux sensors for lux control and constraint
  OutLux_sensor: sensor.lux_sensor
  OutLux_sensor_2: sensor.lux_sensor2
  OutLuxMQTT: zigbee2mqtt/OutdoorLux
  OutLuxMQTT_2: zigbee2mqtt/OutdoorLux2
  RoomLux_sensor: sensor.room_lux_sensor
  RoomLuxMQTT: zwave/KITCHEN_sensor/sensor_multilevel/endpoint_0/Illuminance
  # HA sensor for detection of rain. If rain is detected, it will raise lux constraint by * 1.5
  rain_sensor: sensor.netatmo_rain
  # Listen to sensors to update Lights when there is a change
  listen_sensors:
    - person.wife
  # Exclude the room from custom mode or allow motion detection during night
  options:
    - exclude_from_custom
    - night_motion
    - dim_while_motion
  # Motion sensors.
  # Input delay in seconds before light turns back from motion to 'mode' light
  # motion_constraints takes an if statement that must be true for motion to activate. Inherits Appdaemon API to self
    # Example from my kitchen:
    # "self.now_is_between('06:50:00', '23:00:00') and self.get_tracker_state('person.yourwife') == 'home' or self.get_state('switch.espresso') == 'on' "
  motion_sensors:
    - motion_sensor: binary_sensor.motion_sensor_home_security_motion_detection
      delay: 60
      motion_constraints: "self.now_is_between('06:30:00', '21:00:00')"
  MQTT_motion_sensors:
    - motion_sensor: zigbee2mqtt/
      delay: 60
      motion_constraints: "self.now_is_between('06:30:00', '21:00:00')"
  # Presence tracker detection. Configuration is same as motion sensors
  # Sets mode as away for room if all trackers are not equal to 'home'.
  # Sets mode to presence if defined in light_modes or normal if not defined when returning home
  presence:
    - tracker: person.yourwife
      delay: 60
      tracker_constraints: "self.now_is_between('06:30:00', '22:00:00') "
    - tracker: person.yourself
      delay: 60
      tracker_constraints: "self.now_is_between('06:30:00', '22:00:00') "
  # Media players. Sorted by priority if more than one mediaplayer is defined in room. Can be any sensor or switch with on/off state
  # Define name of mode here and define light attributes in 'light_modes'
  mediaplayers:
    - mediaplayer: binary_sensor.yourXboxGamerTag
      mode: pc
    - mediaplayer: media_player.tv
      mode: tv
  # Add delay to turn on/off lights.
  mode_turn_off_delay: 2
  mode_turn_on_delay: 2
  # Configure lights and switches as Lights. Lights that dim with toggle is configured with 'ToggleLights' insted of 'Lights'
  MQTTLights:
    # Configure as many light with different settings you wish in a room and each lights configuration can have many lights/switches
    - lights:
      - zigbee2mqtt/hue
      automations:
      - time: '06:30:00'
        light_data:
          brightness: 255
          effect: sunrise
      - time: '09:15:00'
        orLater: 'sunrise + 00:20:00'
        light_data:
          brightness: 255
          effect: colorloop
      - time: 'sunrise + 01:30:00'
        light_data:
          brightness: 120
          transition: 3
          color:
            x: 0.5075
            y: 0.4102
      - time: '22:00:00'
        light_data:
          brightness: 80
          effect: fireplace
      - time: '22:01:00'
        dimrate: 2 # Will start to dim from previous brightness (80) - 1 per x minutes. In this case every 2 minutes.
        light_data:
          brightness: 10
          effect: fireplace
      - time: '23:00:00'
        state: turn_off
      # Configure motion lights
      motionlights:
      - time: '06:30:00'
        light_data:
          brightness: 160
      - time: '08:30:00'
        orLater: 'sunrise + 00:30:00'
        light_data:
          brightness: 120
      - time: 'sunset - 00:30:00'
        orLater: '19:00:00'
        light_data:
          brightness: 140
      - time: 'sunset + 00:30:00'
        light_data:
          brightness: 110
      - time: '23:00:00'
        state: turn_off # Turn off at given time even when motion.
        fixed: True
      light_modes:
        - mode: night_kid
          light_data:
            brightness: 10
        - mode: presence
          automations:
          - time: '00:00:00'
            light_data:
              brightness: 100
          - time: '04:00:00'
            light_data:
              brightness: 110
          - time: sunrise - 00:10:00
            light_data:
              brightness: 160
          - time: sunset + 00:30:00
            light_data:
              brightness: 60
        - mode: pc
          state: turn_off
        - mode: tv
          state: lux_controlled
          offset: -50
  ToggleLights:
    - lights:
      - switch.toggle_bulb
      toggle: 2 # On toggles to get desired dim
      num_dim_steps: 3 # Number of dim steps in bulb
      toggle_speed: 0.8 # Set time in seconds between each toggle
      light_modes:
        - mode: night
          toggle: 3
        - mode: gaming
          state: turn_off
      # Lux constraints will only check when a new update to light is sent, like motion/presence, media player on/off or normal mode
      lux_constraint: 12000
      room_lux_constraint: 100
      # Conditions as if statement to be meet for light to turn on at normal/morning/motion mode or with automations defined
      # Inherits Appdaemon Api as ADapi.
      conditions:
        - "self.ADapi.get_tracker_state('person.kid') == 'home'"
        - "self.ADapi.now_is_between('06:50:00', '23:30:00')"

• Report issues on GitHub
• Suggest features via pull requests on the dev branch

MIT License. See LICENSE file for details.

Lightwand by Pythm
Automate your lights with precision and flexibility.