infrapuzzle/projects/esphome_display_kitchen/AGENTS.md

AGENTS.md — Kitchen e-Paper Display (esphome_display_kitchen)

Note

Domain: ESP32 microcontroller driving the e-Paper display in the kitchen.
Source Location: projects/esphome_display_kitchen/
Integrations: Home Assistant Native API (https://hass.moritzgraf.de), Prometheus metrics client.
Hardware: Waveshare e-Paper display on ESP32 (nodemcu-32s).

---

🛠️ Build, Flash & Messaging Tooling

• Interactive Flashing Wizard:

  cd projects/esphome_display_kitchen
  uv run flash.py
  

  Provides an interactive CLI to Validate, Compile, Upload, and view Logs for esdisplay_kitchen.yaml.
• Direct Terminal Messaging:

  cd projects/esphome_display_kitchen
  ./send_message.sh "Your custom display message"
  

  Uses the Home Assistant long-lived token from k8s/home-assistant/ to set the input_text.epaper_message helper in Home Assistant, which instantly pushes updates to the screen.

---

🚨 Rules & Standards

1. Secret Management

• NEVER write plaintext Wi-Fi passwords, tokens, or API keys directly into YAML configurations.
• DO NOT modify .gitignore to allow committing .env files.
• Use ESPHome's !env_var VAR_NAME to inject environment variables at compile-time. Any new secrets must be declared in .env.template and configured locally in .env.

2. Configuration Standards

• Board architecture: ESP32 (nodemcu-32s with arduino framework).
• SNTP time synchronization configured via time component for clock rendering.
• Sensor values (outdoor temperature, indoor climate) are dynamically pulled from Home Assistant entities.