Initial commit: v1.9.1 production firmware

Complete reverse engineering of TJ-56-654 weather clock from AliExpress. Security fixes: - Eliminated WiFi password leak vulnerability - Removed dependency on Chinese cloud services (QWeather) - Secure WiFiManager captive portal setup - No hardcoded credentials Features: - Fully async architecture (zero blocking operations) - OTA firmware updates (web + ArduinoOTA) - NTP time sync with timezone + DST support - Open-Meteo weather API (free, no registration) - 3 display modes: time, weather, sunrise/sunset - REST API + web interface - EEPROM config persistence Performance: - Loop time: <1ms (was 10ms+) - Memory: 409KB flash (38%), 38KB RAM (46%), 62KB IRAM (94%) - Zero blocking delays Hardware: - ESP-01S (ESP8266EX, 1MB flash) - GM009605v4.3 OLED display (128x64, I2C) - Custom I2C mapping: SDA=GPIO0, SCL=GPIO2 Documentation: - Complete installation guide - Hardware specifications - API documentation - Troubleshooting guide - Version history v1.5 → v1.9.1 Built with Claude Code (Opus 4.5) Author: Andrey Petrochenko Date: 2026-01-03
2026-01-03 14:01:31 +00:00
commit 8f0df02e77
21 changed files with 5165 additions and 0 deletions
@@ -0,0 +1,206 @@
+# Hardware Documentation
+
+## Device Specifications
+
+### Original Product
+- **Name**: ESP8266 Mini Weather Clock Kit
+- **Model**: TJ-56-654
+- **Source**: [AliExpress Link](https://pt.aliexpress.com/item/1005008333782531.html)
+- **Price**: ~$12 USD
+- **Dimensions**: 40mm x 40mm x 43mm
+
+### Components
+
+#### ESP-01S WiFi Module
+- **Chip**: ESP8266EX
+- **Flash**: 1MB (8Mbit)
+- **RAM**: 80KB total (32KB instruction, 48KB data)
+- **CPU**: 80MHz (can be overclocked to 160MHz)
+- **WiFi**: 802.11 b/g/n (2.4GHz only)
+- **GPIO**: 2 usable pins (GPIO0, GPIO2)
+- **Voltage**: 3.3V (NOT 5V tolerant!)
+
+#### Display Module
+- **Model**: GM009605v4.3
+- **Type**: OLED (Organic LED)
+- **Resolution**: 128x64 pixels
+- **Size**: 0.96 inches diagonal
+- **Controller**: SSD1306 or SH1106 compatible
+- **Interface**: I2C
+- **I2C Address**: 0x3C (default), 0x3D (fallback)
+- **Colors**: Monochrome (white on black)
+
+#### Power Supply
+- **Input**: 5V via Micro-USB
+- **Regulator**: Onboard 3.3V LDO (on main PCB)
+- **Current**: ~80-120mA typical
+
+#### Case
+- **Material**: Transparent acrylic
+- **Pieces**: 6 (top, bottom, 4 sides)
+- **Assembly**: Brass standoffs and M2.5 screws
+
+## Pinout
+
+### ESP-01S Pin Configuration
+
+```
+┌─────────────────┐
+│  ESP-01S Module │
+├─────────────────┤
+│                 │
+│  [antenna]      │
+│                 │
+│  3V3 │ │ GND    │
+│   TX │ │ GPIO0  │  ← I2C SDA (custom mapping!)
+│   RX │ │ GPIO2  │  ← I2C SCL (custom mapping!)
+│   EN │ │ GND    │
+│                 │
+└─────────────────┘
+```
+
+### Pin Functions
+
+| Pin | Standard Use | This Project |
+|-----|--------------|--------------|
+| 3V3 | Power (3.3V) | Power |
+| GND | Ground | Ground |
+| TX | UART TX | Serial debug output |
+| RX | UART RX | Serial input (flashing) |
+| GPIO0 | General I/O | **I2C SDA** (data line) |
+| GPIO2 | General I/O | **I2C SCL** (clock line) |
+| EN | Chip Enable | Pulled high (always on) |
+
+**⚠️ Important**: This project uses **non-standard I2C pin mapping**!
+- Typical ESP8266: SDA=GPIO4, SCL=GPIO5
+- **This device**: SDA=GPIO0, SCL=GPIO2
+
+### I2C Connection
+
+```
+ESP-01S          OLED Display
+─────────────────────────────
+3V3      →       VCC
+GND      →       GND
+GPIO0    →       SDA
+GPIO2    →       SCL
+```
+
+### Programming Connection (FTDI)
+
+```
+FTDI Adapter     ESP-01S
+──────────────────────────
+3V3      →       3V3
+GND      →       GND
+TX       →       RX
+RX       →       TX
+GND      →       GPIO0  (boot mode - connect only during programming)
+```
+
+**Programming Mode:**
+1. Connect GPIO0 to GND
+2. Power on the ESP-01S
+3. Remove GPIO0-GND connection
+4. Upload firmware
+5. Power cycle to run new code
+
+## PCB Layout
+
+The main PCB (TJ-56-654) contains:
+- ESP-01S socket (8-pin header)
+- OLED display connector (4-pin header)
+- 3.3V voltage regulator (AMS1117-3.3)
+- Micro-USB connector for power
+- Bypass capacitors
+
+## Memory Map
+
+### Flash Memory (1MB)
+```
+0x00000000 - 0x00010000  : Bootloader (64KB)
+0x00010000 - 0x0007C000  : Firmware (~470KB max for OTA)
+0x0007C000 - 0x00080000  : EEPROM emulation (16KB)
+0x00080000 - 0x000FA000  : OTA partition (~470KB)
+0x000FA000 - 0x000FB000  : WiFi config (4KB)
+0x000FB000 - 0x00100000  : System reserved (20KB)
+```
+
+### RAM Layout
+```
+Total: 80KB
+├── IRAM (Instruction): 32KB
+│   ├── Used: ~62KB (94%)  ← Critical!
+│   └── Free: ~4KB
+└── DRAM (Data): 48KB
+    ├── Heap: ~40KB free
+    ├── Stack: ~4KB
+    └── Globals: ~4KB
+```
+
+## Power Consumption
+
+| Mode | Current | Power @3.3V |
+|------|---------|-------------|
+| Active (WiFi on) | 80-120mA | 264-396mW |
+| Display on | +15mA | +50mW |
+| Deep sleep | ~20µA | ~66µW |
+
+**Note**: This firmware does not use deep sleep (clock is always-on).
+
+## Hardware Modifications
+
+### Optional Improvements
+
+1. **External antenna**: Solder U.FL connector for better WiFi range
+2. **Temperature sensor**: Add DHT22 or BME280 to GPIO (requires software changes)
+3. **Buttons**: Add physical buttons for display control (requires free GPIO)
+4. **Battery backup**: Add 18650 cell + TP4056 charger for UPS functionality
+
+### Pin Availability
+
+ESP-01S has very limited GPIO:
+- **GPIO0**: Used for I2C SDA (can't use for other purposes)
+- **GPIO2**: Used for I2C SCL (can't use for other purposes)
+- **TX/RX**: Can be repurposed (breaks serial console)
+
+For additional peripherals, consider upgrading to ESP-12F or ESP32.
+
+## Troubleshooting
+
+### Display not working
+- Check I2C address: Try 0x3C and 0x3D
+- Verify pin mapping: SDA=GPIO0, SCL=GPIO2
+- Check power: Display needs 3.3V
+- Test with I2C scanner (`/api/i2c-scan`)
+
+### WiFi connection fails
+- ESP8266 only supports 2.4GHz (not 5GHz)
+- Check power supply: Weak USB port can cause brownouts
+- Some routers don't like ESP8266 - try different channel
+
+### Bootloop/crashes
+- Check IRAM usage: Must be <95%
+- Verify flash mode: Should be "DIO" not "QIO"
+- Bad power supply: Use quality USB cable
+
+### Can't flash firmware
+- GPIO0 must be LOW during boot for programming mode
+- Some FTDI adapters need DTR/RTS wiring for auto-reset
+- Baud rate: Try 115200 (default) or 57600 if errors
+
+## Datasheets
+
+- [ESP8266EX Datasheet](https://www.espressif.com/sites/default/files/documentation/0a-esp8266ex_datasheet_en.pdf)
+- [ESP-01S Pinout](https://components101.com/wireless/esp8266-pinout-configuration-features-datasheet)
+- [SSD1306 OLED Controller](https://cdn-shop.adafruit.com/datasheets/SSD1306.pdf)
+
+## Safety Warnings
+
+⚠️ **Do NOT connect 5V to ESP-01S GPIO pins** - they are NOT 5V tolerant!
+
+⚠️ **Use 3.3V FTDI adapter** - 5V will permanently damage the ESP8266
+
+⚠️ **Check polarity** - Reversing power can destroy the module
+
+⚠️ **ESD sensitive** - Touch grounded metal before handling board