From e9b4374f3acc1f29a13e9c59dee5a98697729ba8 Mon Sep 17 00:00:00 2001 From: Amir Date: Sun, 16 Aug 2026 13:41:52 +0200 Subject: [PATCH] Upload files to "/" --- README.md | 553 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 553 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ee63b9e --- /dev/null +++ b/README.md @@ -0,0 +1,553 @@ +# ESPHome E-Paper Climate Display + +A wall-mounted climate monitoring station powered by ESPHome, displaying real-time temperature and humidity data from 6 rooms, along with atmospheric pressure, battery status, household energy consumption, and solar power generation data. + +![License](https://img.shields.io/badge/license-MIT-blue.svg) +![ESPHome](https://img.shields.io/badge/ESPHome-Compatible-green.svg) +![Home Assistant](https://img.shields.io/badge/Home%20Assistant-Supported-yellow.svg) + +--- + +## Table of Contents + +- [Features](#features) +- [Hardware Requirements](#hardware-requirements) +- [Pinout Diagram](#pinout-diagram) +- [Wiring Configuration](#wiring-configuration) +- [Home Assistant Integration](#home-assistant-integration) +- [Installation](#installation) +- [Configuration](#configuration) +- [Usage](#usage) +- [Customization](#customization) +- [Troubleshooting](#troubleshooting) + +--- + +## Features + +### Display Features + +- **400x300 pixel e-paper display** (WeAct 4.2" E-Paper Module, GDEY042T81) +- **6-room climate grid** showing temperature and humidity: + - Balkon (Balcony) + - Dnevna soba (Living Room) + - Kopalnica (Bathroom) + - Spalnica (Bedroom) + - Soba (Room) + - Kuhinja (Kitchen) +- **Footer with system information**: + - Atmospheric pressure (mbar) + - Device battery level (%) + - Daily household energy consumption (kWh) + - Daily solar power generation (Wh) + - Remote solar panel forecast (kWh) + - Last update timestamp +- **Low-power design** - E-paper only updates when necessary +- **Slovenian language interface** for labels and status messages + +### Smart Features + +- **Boot screen** with loading animation while gathering data +- **Quiet hours scheduling** - Automatic refresh pause (default: 23:59 - 04:59) +- **Manual refresh button** - Force screen update anytime via TTP223 touch sensor +- **Backlight control** - Temporary LED backlight via TTP223 touch sensor +- **Data caching** - Remembers last values for quick display after restart +- **Home Assistant integration** via native API with encryption + +### WeAct E-Paper Module Features + +- **Built-in backlight** - Front-lit display for low-light conditions +- **SPI interface** - Fast and efficient communication +- **Wide viewing angle** - E-paper technology for excellent readability +- **Low power consumption** - Only draws power during screen updates +- **Compact design** - All-in-one module with convenient header pins + +### Power Management + +- **Deep sleep ready** architecture +- **WiFi power save mode disabled** for reliable connectivity +- **Captive portal** for initial WiFi configuration + +--- + +## Hardware Requirements + +### Main Components + +| Component | Model/Specification | Quantity | +|-----------|---------------------|----------| +| Microcontroller | Wemos D1 Mini (ESP8266) | 1 | +| E-Paper Display | WeAct 4.2" E-Paper Module (GDEY042T81, 400x300) | 1 | + +### User Input Components + +| Component | Model/Specification | Quantity | +|-----------|---------------------|----------| +| Touch Button (Refresh) | TTP223 Capacitive Touch Module | 1 | +| Touch Button (Light) | TTP223 Capacitive Touch Module | 1 | +| LED Backlight | Built-in on WeAct E-Paper Module | 1 | + +### Power Requirements + +- **Voltage**: 3.3V - 5V DC (USB or external) +- **Typical Current**: ~80mA during refresh, <20mA standby +- **Recommended**: USB power adapter (5V/1A) or USB power bank + +--- + +## Pinout Diagram + +``` +┌─────────────────────────────────────────────────────────────┐ +│ WEMOS D1 MINI │ +│ (ESP8266 Top View) │ +│ │ +│ ┌──────────────────────────────────────────┐ │ +│ │ [ANT] [USB] │ │ +│ │ │ │ │ +│ └────────────────────────────────────┼──────┘ │ +│ │ │ +│ 3V3 ────────●──── 3.3V Power │ │ +│ GND ────────●──── Ground │ │ +│ D0 ────────●──── (Wake/GPIO16) │ │ +│ D1 ────────●──── GPIO5 (SCL) │ │ +│ D2 ────────●──── GPIO4 (SDA/DC) │ │ +│ D3 ────────●──── GPIO0 │ │ +│ D4 ────────●──── GPIO2 │ │ +│ D5 ────────●──── GPIO14 (SCK) │ │ +│ D6 ●───────────── GPIO12 ──●── TTP223 Touch (Refresh) │ +│ D7 ────────●──── GPIO13 (MISO) │ │ +│ D8 ────────●──── GPIO15 (CS) │ │ +│ RX ●───────────── GPIO3 ──●── TTP223 Touch (Light) │ +│ TX ●───────────── GPIO1 ──●── Backlight LED (PWM) │ +│ │ +│ A0 ────────●──── ADC (Optional) │ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### WeAct E-Paper Module Pinout + +The WeAct 4.2" E-Paper Module has a convenient 8-pin header for easy connection: + +``` +┌────────────────────────────────────┐ +│ WEACT 4.2" E-PAPER MODULE │ +│ (8-Pin Header on module) │ +├────────────────────────────────────┤ +│ │ +│ VCC ──── 3.3V Power │ +│ GND ──── GND Ground │ +│ CS ──── GPIO15 Chip Select │ +│ DC ──── GPIO4 Data/Cmd │ +│ RST ──── GPIO5 Reset │ +│ BUSY ──── GPIO16 Busy Status │ +│ CLK ──── GPIO14 Clock (SCK) │ +│ DIN ──── GPIO13 Data (MOSI) │ +│ │ +└────────────────────────────────────┘ +``` + +**Note**: The WeAct module includes a built-in backlight circuit. The backlight control (GPIO1/TX) can be connected directly to the module's backlight header if supported. + +--- + +## Wiring Configuration + +### Primary Connections (Required) + +Connect the WeAct 4.2" E-Paper Module to the Wemos D1 Mini using the 8-pin SPI interface: + +| Wemos D1 Mini | WeAct E-Paper Module | Wire Color (Suggested) | +|---------------|---------------------|------------------------| +| 3.3V | VCC | Red | +| GND | GND | Black | +| GPIO15 (D8) | CS | Yellow | +| GPIO4 (D2) | DC | Orange | +| GPIO5 (D1) | RST | White | +| GPIO16 (D0) | BUSY | Purple | +| GPIO14 (D5) | CLK | Blue | +| GPIO13 (D7) | DIN | Green | + +### TTP223 Touch Button Wiring + +The TTP223 is a capacitive touch sensor module that outputs a HIGH signal when touched. Each module requires: + +| Wemos D1 Mini | TTP223 Module | Notes | +|---------------|---------------|-------| +| 3.3V | VCC | Power | +| GND | GND | Ground | +| GPIO12 (D6) | OUT | Touch Refresh button | +| GPIO3 (RX) | OUT | Touch Light button | + +#### TTP223 Module Pinout + +``` +┌─────────────────────┐ +│ TTP223 MODULE │ +│ (Top View) │ +├─────────────────────┤ +│ │ +│ VCC ──── 3.3V │ +│ OUT ──── GPIO │ +│ GND ──── GND │ +│ │ +│ [Touch Pad Area] │ +│ │ +│ Jumper: A (LOW) │ +│ B (HIGH) │ +└─────────────────────┘ +``` + +**Note**: Set the TTP223 mode jumper to position **A** (default) for self-latching output, or **B** for momentary output. The YAML configuration uses `pullup: true` expecting a HIGH output on touch. + +--- + +## Home Assistant Integration + +### Required Entities + +The display fetches data from the following Home Assistant entities. Ensure these exist in your Home Assistant installation: + +### Room Temperature & Humidity Sensors + +| Room | Temperature Entity | Humidity Entity | +|------|-------------------|-----------------| +| Balkon | `sensor.indoor_outdoor_meter_f7c8_temperatura` | `sensor.indoor_outdoor_meter_f7c8_vlaznost` | +| Dnevna soba | `sensor.indoor_outdoor_meter_f965_temperatura` | `sensor.indoor_outdoor_meter_f965_vlaznost` | +| Kopalnica | `sensor.meter_plus_3550_temperatura` | `sensor.meter_plus_3550_vlaznost` | +| Spalnica | `sensor.meter_plus_080d_temperatura` | `sensor.meter_plus_080d_vlaznost` | +| Soba | `sensor.meter_plus_f010_temperatura` | `sensor.meter_plus_f010_vlaznost` | +| Kuhinja | `sensor.meter_plus_86aa_temperatura` | `sensor.meter_plus_86aa_vlaznost` | + +### System Sensors + +| Data | Entity ID | +|------|-----------| +| Atmospheric Pressure | `sensor.arso_weather_brezice_zracni_tlak` | +| Device Battery | `sensor.delta_2_max_0110_battery_level` | +| Daily Energy | `sensor.daily_household_power_usage` | +| Daily Solar | `sensor.ecoflow_daily_solar_power` | +| Remote Solar Forecast | `sensor.solcast_sc_daily_measurment_no_negative_eprices` | + +### API Configuration + +The device uses ESPHome native API with encryption: +- **API Key**: Configured via `api.encryption.key` +- **OTA Password**: `88fcca1cd8e29c78697cfcee032c8e1e` + +--- + +## Installation + +### Prerequisites + +1. **ESPHome** installed (via Home Assistant Add-on or standalone) +2. **Home Assistant** running with API enabled +3. **Secrets configured** in ESPHome: + - `wifi_ssid`: Your WiFi network name + - `wifi_password`: Your WiFi password + +### Step 1: Prepare Font Files + +Copy the required font files to your ESPHome configuration directory: + +``` +/config/esphome/fonts/roboto/ +├── Roboto_Condensed-Regular.ttf +└── Roboto_Condensed-Bold.ttf + +/config/esphome/fonts/ +└── materialdesignicons-webfont.ttf +``` + +### Step 2: Update Entity IDs + +Edit the YAML file and update all `entity_id` values to match your Home Assistant entities: + +```yaml +sensor: + - platform: homeassistant + entity_id: sensor.your_balcony_temp # Replace with your entity +``` + +### Step 3: Generate Encryption Key + +Generate a new API encryption key: + +```bash +openssl rand -hex 32 +``` + +Update the `api.encryption.key` in your YAML file. + +### Step 4: Update OTA Password + +Change the OTA password from the default: + +```yaml +ota: + - platform: esphome + password: "your_secure_password_here" +``` + +### Step 5: Compile and Flash + +Using ESPHome CLI: + +```bash +# Compile the firmware +esphome compile epaper-climate-display.yaml + +# Flash via USB +esphome upload epaper-climate-display.yaml --device /dev/ttyUSB0 + +# Or flash wirelessly (device must be on same network) +esphome upload epaper-climate-display.yaml --host 192.168.x.x +``` + +### Step 6: Add to Home Assistant + +Once flashed, the device should auto-discover in Home Assistant via the ESPHome integration. + +--- + +## Configuration + +### WiFi Configuration + +```yaml +wifi: + ssid: !secret wifi_ssid + password: !secret wifi_password + min_auth_mode: WPA2 + fast_connect: true + power_save_mode: none +``` + +### Quiet Hours (Refresh Schedule) + +Default quiet hours: **23:59 - 04:59** (11:59 PM - 4:59 AM) + +To modify, edit the `interval` section: + +```yaml +const int start_h = 23; // Start hour (24-hour format) +const int start_m = 59; // Start minute +const int end_h = 4; // End hour +const int end_m = 59; // End minute +``` + +### Automatic Refresh Interval + +Screen refreshes every **10 minutes** (outside quiet hours): + +```yaml +interval: + - interval: 10min +``` + +### Backlight Behavior + +| Trigger | Duration | Brightness | +|---------|----------|------------| +| Initial data received | 10 seconds | 100% | +| Manual refresh | 5 seconds | 35% | +| Touch light button | 10 seconds | 100% | + +--- + +## Usage + +### Normal Operation + +1. Power on the device +2. Wait for "Pridobivam podatke" (Getting data) screen +3. Main grid displays when data is received (or after 60 seconds timeout) +4. Screen auto-refreshes every 10 minutes outside quiet hours + +### Manual Refresh + +Press the **Touch Refresh button** (GPIO12/D6) to force an immediate screen update. + +### Temporary Backlight + +Press the **Touch Light button** (GPIO3/RX) to activate the backlight for 10 seconds. + +### WiFi Fallback + +If WiFi connection fails, the device creates an access point: +- **SSID**: `Epaper-Climate-Display` +- **Password**: `QCaF9KQtPXUn` + +Connect to this network to reconfigure WiFi settings via the captive portal. + +--- + +## Customization + +### Changing Room Names + +Edit the `draw_cell` calls in the display lambda: + +```cpp +draw_cell(0, 0, "Your Room", id(your_temp_cache), id(your_hum_cache)); +``` + +### Adding New Rooms + +1. Add new global cache variables: + +```yaml +globals: + - id: newroom_temp_cache + type: float + restore_value: no + initial_value: 'NAN' + - id: newroom_hum_cache + type: float + restore_value: no + initial_value: 'NAN' +``` + +2. Add sensor entity: + +```yaml +sensor: + - platform: homeassistant + id: newroom_temp + entity_id: sensor.your_new_temp + on_value: { then: [ lambda: 'id(newroom_temp_cache) = x;' ] } +``` + +3. Update grid layout in display lambda + +### Changing Language + +All display text is in Slovenian. To change to English, update: + +| Slovenian | English | +|-----------|---------| +| Pridobivam podatke | Getting data | +| To bo trajalo nekaj sekund | This will take a few seconds | +| Osveženo | Updated | +| Balkon | Balcony | +| Dnevna soba | Living Room | +| Kopalnica | Bathroom | +| Spalnica | Bedroom | +| Soba | Room | +| Kuhinja | Kitchen | + +--- + +## Troubleshooting + +### Common Issues + +#### Display shows "Pridobivam podatke" indefinitely + +**Cause**: Home Assistant entities not available or network issues. + +**Solution**: +1. Verify all entity IDs exist in Home Assistant +2. Check network connectivity +3. Device will timeout after 60 seconds and display cached/placeholder data + +#### E-Paper not updating + +**Cause**: Quiet hours active or refresh interval not triggered. + +**Solution**: +1. Press the Touch Refresh button (GPIO12) +2. Check if current time falls within quiet hours +3. Verify ESPHome API connection in Home Assistant + +#### WiFi connection failures + +**Cause**: Incorrect credentials or weak signal. + +**Solution**: +1. Move device closer to router +2. Check WiFi credentials in secrets +3. Use the fallback AP to reconfigure + +#### Compilation memory errors + +**Cause**: Font files too large for ESP8266. + +**Solution**: +1. Ensure using local font files (not remote URLs) +2. Optimize glyphs in font configuration +3. Use Roboto Condensed as it has smaller file size + +### Debug Logging + +Enable debug output in ESPHome logs: + +```bash +esphome logs epaper-climate-display.yaml --level DEBUG +``` + +### Factory Reset + +To reset the device and re-enter WiFi setup: + +1. Erase flash: `esphome run --erase` or use esptool +2. Reflash the firmware +3. Device will create fallback AP on first boot + +--- + +## File Structure + +``` +/config/esphome/ +├── epaper-climate-display.yaml # Main configuration +├── fonts/ +│ ├── roboto/ +│ │ ├── Roboto_Condensed-Regular.ttf +│ │ └── Roboto_Condensed-Bold.ttf +│ └── materialdesignicons-webfont.ttf +└── secrets.yaml # WiFi credentials +``` + +--- + +## License + +This project is open source and available under the MIT License. + +--- + +## Credits + +- **ESPHome** - Firmware framework +- **Home Assistant** - Home automation platform +- **WeActStudio** - E-paper module manufacturer +- **TTP223** - Capacitive touch sensor IC + +--- + +## Changelog + +### v1.0.0 +- Initial release with 6-room climate monitoring +- Support for WeAct 4.2" E-Paper Module (GDEY042T81, 400x300) +- Capacitive touch control via TTP223 modules +- Slovenian language interface +- Quiet hours scheduling +- Manual refresh and backlight controls +- Home Assistant API integration + +--- + +## Support + +For issues or questions: +1. Check the [ESPHome documentation](https://esphome.io/) +2. Review [Home Assistant community](https://community.home-assistant.io/) +3. Check GitHub issues for this project + +--- + +*Documentation generated for ESPHome E-Paper Climate Display project.*