#:########################################################################################:#
# Flounder Kiosk Package                                                                   #
#:########################################################################################:#
#
# TITLE:
#   Flounder Kiosk
#
# FILE:
#   flounder_kiosk.yaml
#
# VERSION:
#   V2.0 - 2026-07-28
#
# PURPOSE:
#   Provides Home Assistant controls and status entities for the Flounder portrait
#   touchscreen kiosk.
#
# DISPLAY CONTROL MODEL:
#   A single MQTT select sets one persistent display mode:
#     - Screen Lock
#     - Screen Off
#     - Screensaver
#     - Screen On
#
#   The selected display mode is separate from the actual physical screen and
#   screensaver states. For example, Screen Off remains selected while a touch
#   temporarily wakes the physical display.
#
# MQTT DEVICE:
#   Name: Flounder Kiosk
#   Identifier: flounder_kiosk
#   Manufacturer: Dell
#   Model: Portrait Touchscreen Kiosk
#   Suggested Area: Lounge
#
# ENTITIES:
#   select.flounder_kiosk_display_mode
#   number.flounder_kiosk_brightness
#   number.flounder_kiosk_presence_brightness
#   sensor.flounder_kiosk_actual_brightness
#   number.flounder_kiosk_presence_timeout
#   binary_sensor.flounder_kiosk_presence_active
#   switch.flounder_kiosk_motion_wake
#   number.flounder_kiosk_volume
#   switch.flounder_kiosk_mute
#   binary_sensor.flounder_kiosk_screen_on
#   binary_sensor.flounder_kiosk_screensaver_active
#   binary_sensor.flounder_kiosk_motion
#
# REPLACED ENTITIES:
#   The following writable entities from V1.7 are removed:
#     - switch.flounder_kiosk_screen
#     - switch.flounder_kiosk_screensaver
#
#   They are replaced by:
#     - select.flounder_kiosk_display_mode
#     - binary_sensor.flounder_kiosk_screen_on
#     - binary_sensor.flounder_kiosk_screensaver_active
#
# MQTT COMMAND TOPICS:
#   viewroad-commands/flounder/display_mode/set
#   viewroad-commands/flounder/brightness/set
#   viewroad-commands/flounder/brightness/presence/set
#   viewroad-commands/flounder/presence/timeout/set
#   viewroad-commands/flounder/motion_wake/set
#   viewroad-commands/flounder/audio/volume/set
#   viewroad-commands/flounder/audio/mute/set
#
# MQTT STATE TOPICS:
#   viewroad-status/flounder/display_mode/state
#   viewroad-status/flounder/screen/state
#   viewroad-status/flounder/screensaver/state
#   viewroad-status/flounder/brightness/state
#   viewroad-status/flounder/brightness/actual/state
#   viewroad-status/flounder/brightness/presence/state
#   viewroad-status/flounder/presence/state
#   viewroad-status/flounder/presence/timeout/state
#   viewroad-status/flounder/motion_wake/state
#   viewroad-status/flounder/audio/volume/state
#   viewroad-status/flounder/audio/mute/state
#   viewroad-status/flounder/motion/state
#
# MQTT AVAILABILITY TOPIC:
#   viewroad-status/flounder/availability
#
# DISPLAY MODES:
#   Screen Lock:
#     - Stops XScreenSaver.
#     - Disables touchscreen input.
#     - Keeps the physical panel off.
#     - Ignores camera motion even when Motion Wake is enabled.
#     - Camera motion detection and reporting continue in the background.
#
#   Screen Off:
#     - Keeps the physical panel off while activity is inactive.
#     - Keeps the touchscreen enabled.
#     - Touch always wakes the panel temporarily.
#     - Camera motion wakes it when Motion Wake is enabled.
#     - Activity applies Presence Brightness.
#     - The panel returns to Screen Off after the shared Presence Timeout.
#
#   Screensaver:
#     - Turns the panel on at Current Brightness.
#     - Starts XScreenSaver immediately.
#     - Touch stops XScreenSaver and applies Presence Brightness.
#     - Camera motion does the same when Motion Wake is enabled.
#     - XScreenSaver restarts after the shared Presence Timeout.
#
#   Screen On:
#     - Keeps the panel on at Current Brightness while activity is inactive.
#     - Touch applies Presence Brightness.
#     - Camera motion does the same when Motion Wake is enabled.
#     - The panel returns to Current Brightness after the Presence Timeout.
#
# PRESENCE AND TOUCH OPERATION:
#   - Touch and camera motion use the same Presence Timeout.
#   - Touch is active in every mode except Screen Lock.
#   - Motion Wake controls camera motion only and does not disable touch wake.
#   - Qualifying activity immediately applies Presence Brightness.
#   - Camera motion holds presence active until the Motion entity returns to OFF.
#   - A touch starts or restarts the ten-step brightness ramp immediately unless
#     qualifying camera motion is currently holding presence active.
#   - Presence Timeout is the total duration of the ten-step brightness ramp.
#   - The final ramp step applies the latest Current Brightness.
#   - The selected display mode is then restored automatically.
#
# DIAGNOSTIC STATE MEANING:
#   - Screen On reports the real Linux DPMS panel state.
#   - Screensaver Active reports whether XScreenSaver is running.
#   - Presence Active reports whether temporary activity behaviour is active.
#   - Actual Brightness reports the physical backlight percentage.
#
# VERSION HISTORY:
#   V2.0 - 2026-07-28
#     - Replaced the separate Screen and Screensaver switches with one persistent
#       four-option Display Mode select.
#     - Added Screen Lock, Screen Off, Screensaver, and Screen On modes.
#     - Added shared touchscreen and camera-presence behaviour.
#     - Added automatic return to the selected mode after the presence ramp.
#     - Replaced writable Screen and Screensaver entities with diagnostics.
#
#   V1.7 - 2026-07-27
#     - Re-enabled DPMS after XScreenSaver activation.
#     - Corrected Screen state reporting while XScreenSaver was running.
#
#   V1.6 - 2026-07-27
#     - Grouped all MQTT entities under one Flounder Kiosk device.
#
#   V1.5 - 2026-07-27
#     - Added Motion Wake control.
#
#   V1.4 - 2026-07-27
#     - Added the ten-step presence-brightness fade.
#
#   V1.3 - 2026-07-27
#     - Added presence brightness, timeout, and diagnostic entities.
#
#   V1.2 - 2026-07-27
#     - Added XScreenSaver control.
#
#   V1.1 - 2026-07-27
#     - Added MQTT availability monitoring.
#
#   V1.0 - 2026-07-26
#     - Initial package.
#
#:########################################################################################:#
# MQTT Entities                                                                            #
#:########################################################################################:#

mqtt:
  #:########################################################################################:#
  # Flounder Kiosk Display Mode                                                              #
  #:########################################################################################:#
  #
  # Selects the persistent display operating mode.
  #
  # The selected mode remains unchanged while touch or camera activity temporarily
  # changes the real panel or screensaver state.
  #

  - select:
      name: "Display Mode"
      unique_id: flounder_kiosk_display_mode
      default_entity_id: select.flounder_kiosk_display_mode

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      command_topic: "viewroad-commands/flounder/display_mode/set"
      state_topic: "viewroad-status/flounder/display_mode/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      options:
        - "Screen Lock"
        - "Screen Off"
        - "Screensaver"
        - "Screen On"

      optimistic: false
      retain: false

      icon: mdi:monitor-dashboard

  #:########################################################################################:#
  # Flounder Kiosk Current Brightness                                                        #
  #:########################################################################################:#
  #
  # Stores the normal inactive brightness from 1 to 100 percent.
  #
  # In Screensaver and Screen On modes it is the normal visible brightness.
  # In Screen Off mode it is the final ramp target before the panel powers off.
  # In Screen Lock mode it is stored for the next unlocked mode.
  #

  - number:
      name: "Brightness"
      unique_id: flounder_kiosk_brightness
      default_entity_id: number.flounder_kiosk_brightness

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      command_topic: "viewroad-commands/flounder/brightness/set"
      state_topic: "viewroad-status/flounder/brightness/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      min: 1
      max: 100
      step: 1
      mode: slider

      unit_of_measurement: "%"

      optimistic: false
      retain: false

      icon: mdi:brightness-6

  #:########################################################################################:#
  # Flounder Kiosk Presence Brightness                                                       #
  #:########################################################################################:#
  #
  # Sets the temporary brightness used after touch or qualifying camera motion.
  #
  # Changing it while Presence Active is ON immediately updates the physical
  # backlight.
  #

  - number:
      name: "Presence Brightness"
      unique_id: flounder_kiosk_presence_brightness
      default_entity_id: number.flounder_kiosk_presence_brightness

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      entity_category: config

      command_topic: "viewroad-commands/flounder/brightness/presence/set"
      state_topic: "viewroad-status/flounder/brightness/presence/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      min: 1
      max: 100
      step: 1
      mode: slider

      unit_of_measurement: "%"

      optimistic: false
      retain: false

      icon: mdi:brightness-7

  #:########################################################################################:#
  # Flounder Kiosk Actual Brightness                                                         #
  #:########################################################################################:#
  #
  # Reports the physical display backlight percentage.
  #
  # This may differ from Current Brightness while temporary activity is active or
  # while the ten-step brightness ramp is running.
  #

  - sensor:
      name: "Actual Brightness"
      unique_id: flounder_kiosk_actual_brightness
      default_entity_id: sensor.flounder_kiosk_actual_brightness

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      entity_category: diagnostic

      state_topic: "viewroad-status/flounder/brightness/actual/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      unit_of_measurement: "%"
      state_class: measurement

      icon: mdi:brightness-percent

  #:########################################################################################:#
  # Flounder Kiosk Presence Timeout                                                          #
  #:########################################################################################:#
  #
  # Sets the shared touch and camera-presence timeout.
  #
  # The value is the total duration of the ten-step brightness ramp. Home Assistant
  # displays whole minutes while MQTT stores and transfers seconds.
  #

  - number:
      name: "Presence Timeout"
      unique_id: flounder_kiosk_presence_timeout
      default_entity_id: number.flounder_kiosk_presence_timeout

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      entity_category: config

      command_topic: "viewroad-commands/flounder/presence/timeout/set"
      state_topic: "viewroad-status/flounder/presence/timeout/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      command_template: >-
        {{ (value | float(1) * 60) | round(0) | int }}

      value_template: >-
        {{ (value | float(60) / 60) | round(0) | int }}

      min: 1
      max: 1440
      step: 1
      mode: box

      unit_of_measurement: "min"

      optimistic: false
      retain: false

      icon: mdi:timer-outline

  #:########################################################################################:#
  # Flounder Kiosk Presence Active                                                           #
  #:########################################################################################:#
  #
  # Reports whether temporary touch or camera-presence behaviour is active.
  #
  # It remains ON through the brightness ramp and returns to OFF when the selected
  # display mode has been restored.
  #

  - binary_sensor:
      name: "Presence Active"
      unique_id: flounder_kiosk_presence_active
      default_entity_id: binary_sensor.flounder_kiosk_presence_active

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      entity_category: diagnostic

      state_topic: "viewroad-status/flounder/presence/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      payload_on: "ON"
      payload_off: "OFF"

      icon: mdi:account-eye

  #:########################################################################################:#
  # Flounder Kiosk Motion Wake                                                               #
  #:########################################################################################:#
  #
  # Controls whether camera motion counts as display activity.
  #
  # Motion Wake does not affect touchscreen activity. Screen Lock ignores camera
  # motion regardless of this switch while motion detection continues reporting.
  #

  - switch:
      name: "Motion Wake"
      unique_id: flounder_kiosk_motion_wake
      default_entity_id: switch.flounder_kiosk_motion_wake

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      entity_category: config

      command_topic: "viewroad-commands/flounder/motion_wake/set"
      state_topic: "viewroad-status/flounder/motion_wake/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      payload_on: "ON"
      payload_off: "OFF"

      optimistic: false
      retain: false

      icon: mdi:motion-sensor

  #:########################################################################################:#
  # Flounder Kiosk Volume                                                                    #
  #:########################################################################################:#
  #
  # Controls the active PipeWire audio-sink volume from 0 to 100 percent.
  #

  - number:
      name: "Volume"
      unique_id: flounder_kiosk_volume
      default_entity_id: number.flounder_kiosk_volume

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      command_topic: "viewroad-commands/flounder/audio/volume/set"
      state_topic: "viewroad-status/flounder/audio/volume/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      min: 0
      max: 100
      step: 1
      mode: slider

      unit_of_measurement: "%"

      optimistic: false
      retain: false

      icon: mdi:volume-high

  #:########################################################################################:#
  # Flounder Kiosk Mute                                                                      #
  #:########################################################################################:#
  #
  # Controls the mute state of the active PipeWire audio sink.
  #

  - switch:
      name: "Mute"
      unique_id: flounder_kiosk_mute
      default_entity_id: switch.flounder_kiosk_mute

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      command_topic: "viewroad-commands/flounder/audio/mute/set"
      state_topic: "viewroad-status/flounder/audio/mute/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      payload_on: "ON"
      payload_off: "OFF"

      optimistic: false
      retain: false

      icon: mdi:volume-mute

  #:########################################################################################:#
  # Flounder Kiosk Screen On                                                                 #
  #:########################################################################################:#
  #
  # Reports the real physical panel state from Linux DPMS.
  #
  # This can report ON while Display Mode remains Screen Off because touch or
  # qualifying camera motion has temporarily woken the panel.
  #

  - binary_sensor:
      name: "Screen On"
      unique_id: flounder_kiosk_screen_on
      default_entity_id: binary_sensor.flounder_kiosk_screen_on

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      entity_category: diagnostic

      state_topic: "viewroad-status/flounder/screen/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      payload_on: "ON"
      payload_off: "OFF"

      device_class: power
      icon: mdi:monitor

  #:########################################################################################:#
  # Flounder Kiosk Screensaver Active                                                        #
  #:########################################################################################:#
  #
  # Reports whether XScreenSaver is currently running.
  #
  # In Screensaver mode it normally reports ON, but temporarily reports OFF while
  # touch or qualifying camera motion displays the Home Assistant kiosk.
  #

  - binary_sensor:
      name: "Screensaver Active"
      unique_id: flounder_kiosk_screensaver_active
      default_entity_id: binary_sensor.flounder_kiosk_screensaver_active

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      entity_category: diagnostic

      state_topic: "viewroad-status/flounder/screensaver/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      payload_on: "ON"
      payload_off: "OFF"

      icon: mdi:monitor-shimmer

  #:########################################################################################:#
  # Flounder Kiosk Motion                                                                    #
  #:########################################################################################:#
  #
  # Reports raw movement detected by the local Motion camera service.
  #
  # Motion continues reporting in Screen Lock and while Motion Wake is OFF. It only
  # affects display activity when Motion Wake is ON and Display Mode is not
  # Screen Lock.
  #

  - binary_sensor:
      name: "Motion"
      unique_id: flounder_kiosk_motion
      default_entity_id: binary_sensor.flounder_kiosk_motion

      device:
        identifiers:
          - flounder_kiosk
        name: "Flounder Kiosk"
        manufacturer: "Dell"
        model: "Portrait Touchscreen Kiosk"
        suggested_area: "Lounge"

      state_topic: "viewroad-status/flounder/motion/state"

      availability_topic: "viewroad-status/flounder/availability"
      payload_available: "ON"
      payload_not_available: "OFF"

      payload_on: "ON"
      payload_off: "OFF"

      device_class: motion