Files

T

Alex Petrochenko 8f0df02e77 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

2.7 KiB

Raw Blame History

Contributing to ESP8266 Weather Clock

Thank you for your interest in contributing! This project welcomes improvements, bug fixes, and new features.

How to Contribute

Reporting Bugs

If you find a bug, please open an issue with:

Clear description of the problem
Steps to reproduce
Expected vs actual behavior
Serial console output (if applicable)
Firmware version

Suggesting Features

Feature requests are welcome! Please include:

Use case description
Why this would be useful
Any implementation ideas

Pull Requests

Fork the repository
Create a feature branch: git checkout -b feature/my-new-feature
Test your changes:
- Compile successfully
- Test on real hardware if possible
- Check memory usage (IRAM must stay < 95%)
Follow the code style:
- Use ICACHE_FLASH_ATTR for non-critical functions
- Avoid String concatenation in loops
- Document state machines with comments
Commit with clear messages: Explain what and why, not how
Submit PR with description of changes

Code Guidelines

Memory Safety:

Check IRAM usage after adding code
Use fixed-size buffers instead of dynamic allocation where possible
Prefer snprintf over String concatenation

Async Architecture:

Keep loop() non-blocking (no delay() calls)
Use state machines for multi-step operations
Add exponential backoff to network operations

Testing:

Test on ESP-01S hardware (1MB flash, 80KB RAM)
Verify OTA updates work
Check 24h stability

Development Setup

Requirements

Arduino IDE 1.8.x or 2.x
ESP8266 board support (v3.0.0+)
Libraries (see README)

Building

# Arduino IDE: Sketch → Verify/Compile
# Or use arduino-cli:
arduino-cli compile --fqbn esp8266:esp8266:generic src/clock_ntp_ota_v1.9.ino

Testing

# Upload via FTDI (first time)
arduino-cli upload -p /dev/cu.usbserial* --fqbn esp8266:esp8266:generic

# Upload via OTA (subsequent)
curl -u admin:admin -F "file=@build/*.bin" http://192.168.x.x/update

Project Structure

esp8266-weather-clock-opensource/
├── src/                    # Main firmware source
├── docs/                   # Documentation
├── images/                 # Photos and screenshots
├── README.md               # Main documentation
└── LICENSE                 # MIT License

Communication

Issues: Bug reports and feature requests
Discussions: General questions and ideas
Pull Requests: Code contributions

Code of Conduct

Be respectful, constructive, and helpful. We're all here to learn and build cool stuff.

Questions?

Open an issue or discussion - happy to help!

2.7 KiB Raw Blame History