# ============================================================================
# M5Stack ATOM S3 Lite - ESPHome Configuration
# ============================================================================
# This is a complete configuration for the M5Stack ATOM S3 Lite board.
# The ATOM S3 Lite is a tiny ESP32-S3 board with RGB LEDs, a button, and IR.

# Substitutions: Variables that can be reused throughout this configuration
# Think of these as "find and replace" - everywhere you see ${devicename},
# it will be replaced with the value defined here
substitutions:
  # The internal name used by ESPHome (use lowercase, no spaces, hyphens OK)
  devicename: "m5stack-atoms3-lite"

  # The friendly name shown in Home Assistant (can have spaces and capitals)
  friendly_name: "M5Stack ATOM S3 Lite"

  # Description of what this device does
  device_comment: "M5Stack ATOM S3 Lite - Multi-purpose ESPHome Device"

  # Tip: Change these to match your use case, for example:
  #   devicename: "living-room-sensor"
  #   friendly_name: "Living Room Sensor"
  #   device_comment: "Temperature and humidity sensor for living room"

# ============================================================================
# Core ESPHome Configuration
# ============================================================================
esphome:
  # Uses the devicename variable defined above (m5stack-atoms3-lite)
  name: ${devicename}

  # Uses the friendly_name variable defined above
  friendly_name: ${friendly_name}

  # Uses the device_comment variable defined above
  comment: ${device_comment}

  # Don't add MAC address to the device name (set to true if you have multiple identical devices)
  name_add_mac_suffix: false

# ============================================================================
# ESP32 Hardware Configuration
# ============================================================================
esp32:
  # Tells ESPHome which board you're using (ATOM S3 Lite uses ESP32-S3)
  board: esp32-s3-devkitc-1

  # Which framework to use for compiling (Arduino is easier for beginners)
  framework:
    type: arduino

# ============================================================================
# Logger - Serial Output for Debugging
# ============================================================================
# The logger lets you see what's happening on your device in real-time
logger:
  # baud_rate: 0 is REQUIRED for ESP32-S3 (it uses USB-CDC, not traditional UART)
  baud_rate: 0

  # How much detail to show in logs (DEBUG shows everything, INFO shows less)
  level: DEBUG

# ============================================================================
# WiFi Configuration
# ============================================================================
# Configure WiFi connection to your home network
wifi:
  # Your WiFi network name (SSID) - stored in secrets.yaml
  ssid: !secret wifi_ssid

  # Your WiFi password - stored in secrets.yaml
  password: !secret wifi_password

# ============================================================================
# RGB LED Strip - The 4 Colorful LEDs
# ============================================================================
# The ATOM S3 Lite has 4 RGB LEDs built-in on GPIO35
# Documentation: https://esphome.io/components/light/fastled
light:
  # Use FastLED library for addressable LED control
  - platform: fastled_clockless

    # WS2812B is the type of LED chip used
    chipset: WS2812B

    # The LEDs are connected to GPIO35 on the board
    pin: GPIO35

    # There are 4 LEDs in the strip
    num_leds: 4

    # GRB is the color order for these specific LEDs (Green-Red-Blue)
    rgb_order: GRB

    # Internal ID to reference these LEDs in automations
    id: led

    # The name that appears in Home Assistant
    name: "${friendly_name} LED"

    # When device restarts, LEDs start OFF
    restore_mode: RESTORE_DEFAULT_OFF

    # Built-in light effects you can activate from Home Assistant
    effects:
      # Pulse effect: LEDs fade in and out smoothly
      - pulse:
          name: "Pulse"
          # How long each fade in/out takes (1 second)
          transition_length: 1s
          # How often to update the effect (1 second)
          update_interval: 1s

      # Strobe effect: LEDs flash on and off rapidly
      - strobe:
          name: "Strobe"

      # Random effect: LEDs change to random colors
      - random:
          name: "Random"
          # How long to transition between colors (5 seconds)
          transition_length: 5s
          # How often to pick a new random color (3 seconds)
          update_interval: 3s

# ============================================================================
# IR Remote Transmitter - Infrared LED for Remote Control
# ============================================================================
# The ATOM S3 Lite has a built-in IR LED on GPIO4 for controlling TVs, etc.
# Documentation: https://esphome.io/components/remote_transmitter/
remote_transmitter:
  # The IR LED is connected to GPIO4
  pin: GPIO4

  # Carrier duty cycle controls IR signal strength (50% is standard)
  carrier_duty_percent: 50%

  # Internal ID to reference the IR transmitter in automations
  id: ir_transmitter

  # Non-blocking allows other code to run while IR signal is being sent
  non_blocking: true

# ============================================================================
# Binary Sensors - On/Off Sensors
# ============================================================================
binary_sensor:
  # Status Sensor - Shows if device is online or offline in Home Assistant
  - platform: status
    # The name that appears in Home Assistant
    name: "${friendly_name} Status"

  # Physical Button - The built-in button on GPIO41
  - platform: gpio
    # The name that appears in Home Assistant
    name: "${friendly_name} Button"

    # Button configuration
    pin:
      # The button is connected to GPIO41
      number: GPIO41

      # Inverted means pressed=LOW, released=HIGH (common for buttons with pullup)
      inverted: true

      # Pin mode configuration
      mode:
        # Configure as input (reads signal)
        input: true

        # Enable internal pullup resistor (keeps pin HIGH when button not pressed)
        pullup: true

    # Filters clean up the button signal
    filters:
      # Debouncing: Ignore button bouncing for 10 milliseconds
      - delayed_off: 10ms

    # Action to perform when button is pressed
    on_press:
      then:
        # Send Samsung TV power signal via IR LED
        - remote_transmitter.transmit_samsung:
            # Samsung TV power code (change this for other devices)
            data: 0xE0E040BF

        # Write a message to the logs for debugging
        - logger.log: "Samsung TV Power Signal sent"
