Alex Petrochenko
8f0df02e77
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
250 lines
7.1 KiB
Markdown
250 lines
7.1 KiB
Markdown
# Project Structure
|
|
|
|
This document describes the organization of the ESP8266 Weather Clock firmware repository.
|
|
|
|
## Directory Layout
|
|
|
|
```
|
|
esp8266-weather-clock-opensource/
|
|
│
|
|
├── README.md # Main documentation (start here!)
|
|
├── LICENSE # MIT License
|
|
├── CHANGELOG.md # Version history
|
|
├── CONTRIBUTING.md # Contribution guidelines
|
|
├── PROJECT_STRUCTURE.md # This file
|
|
├── .gitignore # Git exclusions
|
|
│
|
|
├── src/ # Source code
|
|
│ └── clock_ntp_ota_v1.9.ino # Main firmware (2,096 lines)
|
|
│
|
|
├── docs/ # Documentation
|
|
│ ├── INSTALLATION.md # Complete installation guide
|
|
│ ├── HARDWARE.md # Hardware specs and pinout
|
|
│ ├── v1.9_RELEASE_NOTES.md # v1.9.0 release notes
|
|
│ └── v1.9.1_HYBRID_FIX.md # v1.9.1 WiFi startup fix
|
|
│
|
|
├── images/ # Photos and screenshots
|
|
│ ├── product/ # AliExpress product photos
|
|
│ │ ├── 01-main-product.webp # Main product shot
|
|
│ │ ├── 02-components.webp # Kit components
|
|
│ │ ├── 03-weather-forecast.webp
|
|
│ │ ├── 04-temperature-display.webp
|
|
│ │ ├── 05-details.webp # Transparent case details
|
|
│ │ └── 06-size.webp # Dimensions (40x40x43mm)
|
|
│ │
|
|
│ └── build/ # Custom firmware screenshots
|
|
│ ├── display-time.png # Time display mode
|
|
│ ├── display-temperature.png # Weather display mode
|
|
│ └── display-sunrise-sunset.png # Solar display mode
|
|
│
|
|
└── .github/ # GitHub-specific files
|
|
├── workflows/
|
|
│ └── build.yml # CI: Auto-build on push
|
|
│
|
|
└── ISSUE_TEMPLATE/
|
|
├── bug_report.md # Bug report template
|
|
└── feature_request.md # Feature request template
|
|
```
|
|
|
|
## Key Files
|
|
|
|
### Root Level
|
|
|
|
**README.md** (11KB)
|
|
- Main project documentation
|
|
- Blog-style narrative about reverse engineering
|
|
- Security issues discovered
|
|
- Complete feature list
|
|
- Installation quickstart
|
|
- API documentation
|
|
|
|
**LICENSE** (MIT)
|
|
- Permissive open source license
|
|
- Use freely, modify, distribute
|
|
|
|
**CHANGELOG.md**
|
|
- Version history: v1.5 → v1.9.1
|
|
- Features, fixes, breaking changes
|
|
- Migration notes
|
|
|
|
**CONTRIBUTING.md**
|
|
- How to contribute
|
|
- Code style guidelines
|
|
- Testing requirements
|
|
|
|
### Source Code (`/src`)
|
|
|
|
**clock_ntp_ota_v1.9.ino**
|
|
- Main firmware file (2,096 lines)
|
|
- ESP8266 Arduino sketch
|
|
- Requires libraries:
|
|
- Adafruit GFX & SSD1306
|
|
- NTPClient
|
|
- WiFiManager
|
|
- AsyncHTTPRequest_Generic
|
|
- ESPAsyncTCP
|
|
|
|
**Architecture:**
|
|
- Fully async (zero blocking in loop)
|
|
- State machines: WiFi, NTP, Weather
|
|
- Hybrid model: sync WiFi in setup(), async in loop()
|
|
- Memory-optimized: ICACHE_FLASH_ATTR on 26 functions
|
|
|
|
**Configuration:**
|
|
- 26-field struct stored in EEPROM
|
|
- Magic number validation
|
|
- Web-based config UI
|
|
|
|
### Documentation (`/docs`)
|
|
|
|
**INSTALLATION.md** (18KB)
|
|
- Complete step-by-step installation guide
|
|
- Arduino IDE setup
|
|
- FTDI wiring diagrams
|
|
- OTA update instructions
|
|
- Comprehensive troubleshooting
|
|
|
|
**HARDWARE.md** (8KB)
|
|
- ESP-01S specifications
|
|
- Pin mapping (SDA=GPIO0, SCL=GPIO2)
|
|
- Display module details (GM009605v4.3)
|
|
- Power requirements
|
|
- Memory layout
|
|
- Safety warnings
|
|
|
|
**v1.9_RELEASE_NOTES.md** (7KB)
|
|
- Detailed v1.9.0 changelog
|
|
- Performance improvements
|
|
- Async architecture explanation
|
|
- Memory usage comparison
|
|
- Testing checklist
|
|
|
|
**v1.9.1_HYBRID_FIX.md** (Russian, 6KB)
|
|
- Critical startup fix documentation
|
|
- WiFi synchronous vs async tradeoffs
|
|
- Timeline diagrams
|
|
- Before/after comparison
|
|
|
|
### Images (`/images`)
|
|
|
|
**Product Photos** (`/product`)
|
|
- Original AliExpress product images
|
|
- DIY kit components
|
|
- Transparent acrylic case
|
|
- Size reference (40mm cube)
|
|
|
|
**Build Photos** (`/build`)
|
|
- Custom firmware screenshots
|
|
- Three display modes:
|
|
1. Time mode (10:34 + date)
|
|
2. Weather mode (15.4°c + city)
|
|
3. Sunrise/sunset mode (times + daylight duration)
|
|
|
|
### GitHub Config (`/.github`)
|
|
|
|
**Workflows**
|
|
- `build.yml`: CI pipeline
|
|
- Auto-compile on push
|
|
- Check firmware size < 470KB
|
|
- Upload build artifacts
|
|
- Attach binaries to releases
|
|
|
|
**Issue Templates**
|
|
- `bug_report.md`: Structured bug reports
|
|
- `feature_request.md`: Feature suggestions
|
|
|
|
## Build Artifacts (ignored by git)
|
|
|
|
When you compile locally, these are created:
|
|
|
|
```
|
|
build/
|
|
├── clock_ntp_ota_v1.9.ino.bin # Flash this via OTA
|
|
├── clock_ntp_ota_v1.9.ino.elf # Debug symbols
|
|
└── clock_ntp_ota_v1.9.ino.map # Memory map
|
|
```
|
|
|
|
**Note**: `build/` is in `.gitignore` - artifacts not committed to repo.
|
|
|
|
## File Sizes
|
|
|
|
| File | Size | Description |
|
|
|------|------|-------------|
|
|
| `src/*.ino` | 65KB | Main source code |
|
|
| `build/*.bin` | 409KB | Compiled firmware |
|
|
| `README.md` | 45KB | Main docs |
|
|
| `docs/INSTALLATION.md` | 18KB | Install guide |
|
|
| `docs/HARDWARE.md` | 8KB | Hardware specs |
|
|
|
|
## Memory Usage
|
|
|
|
**Compiled firmware (v1.9.1):**
|
|
- Flash: 408,844 / 1,048,576 bytes (38%)
|
|
- RAM: 37,644 / 80,192 bytes (46%)
|
|
- IRAM: 61,987 / 65,536 bytes (94%) ⚠️
|
|
|
|
**Why 94% IRAM is acceptable:**
|
|
- ICACHE_FLASH_ATTR applied to all web handlers
|
|
- Stable across versions v1.8-v1.9.1
|
|
- No IRAM growth observed in testing
|
|
|
|
## Version Control
|
|
|
|
**Branches:**
|
|
- `main`: Stable releases (v1.9.1)
|
|
- `develop`: Work-in-progress features
|
|
- `feature/*`: New feature branches
|
|
|
|
**Tags:**
|
|
- `v1.9.1`: Current production release
|
|
- `v1.9.0`: Async refactoring
|
|
- `v1.8.0`: Security + stability fixes
|
|
- `v1.7.0`: Initial working firmware
|
|
|
|
## Not Included (Why)
|
|
|
|
**What's NOT in this repo:**
|
|
- Build artifacts (`.bin`, `.elf`, `.map`) - generated locally
|
|
- Backup files (`.bak`, `.bak2`) - development artifacts
|
|
- IDE configs (`.vscode/`, `.idea/`) - personal preferences
|
|
- macOS metadata (`.DS_Store`) - system files
|
|
- Secrets (`config_local.h`) - would leak credentials
|
|
|
|
These are excluded via `.gitignore`.
|
|
|
|
## How to Navigate
|
|
|
|
**For users:**
|
|
1. Start with `README.md` (overview + quickstart)
|
|
2. Follow `docs/INSTALLATION.md` (step-by-step setup)
|
|
3. Check `CHANGELOG.md` (version history)
|
|
|
|
**For developers:**
|
|
1. Read `CONTRIBUTING.md` (guidelines)
|
|
2. Study `src/clock_ntp_ota_v1.9.ino` (source code)
|
|
3. Review `docs/HARDWARE.md` (hardware constraints)
|
|
4. Check `.github/workflows/build.yml` (CI setup)
|
|
|
|
**For hardware hackers:**
|
|
1. Check `docs/HARDWARE.md` (pinout, specs)
|
|
2. View `images/product/` (original device photos)
|
|
3. Read `README.md` section "Hardware Discovery"
|
|
|
|
**For troubleshooters:**
|
|
1. Open `docs/INSTALLATION.md`
|
|
2. Jump to "Troubleshooting" section
|
|
3. Check `images/build/` for reference screenshots
|
|
|
|
## Quick Links
|
|
|
|
- **Main docs**: [README.md](README.md)
|
|
- **Install guide**: [docs/INSTALLATION.md](docs/INSTALLATION.md)
|
|
- **Hardware specs**: [docs/HARDWARE.md](docs/HARDWARE.md)
|
|
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
|
|
- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)
|
|
|
|
---
|
|
|
|
**Last updated**: 2026-01-03
|
|
**Repository**: https://github.com/your-username/esp8266-weather-clock-opensource
|