tobi/esp8266-weather-clock-opensource
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: v1.9.1 production firmware

Browse Source 
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
This commit is contained in:
Alex Petrochenko
2026-01-03 14:01:31 +00:00
commit 8f0df02e77
21 changed files with 5165 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
PUBLISH_TO_GITHUB.md
+440
View File
@@ -0,0 +1,440 @@
# Publishing to GitHub - Step by Step Guide
This file contains instructions for publishing this project to GitHub.
## Prerequisites
1. **GitHub account** - Sign up at https://github.com if you don't have one
2. **Git installed** - Check with `git --version` in terminal
3. **GitHub CLI (optional)** - Makes repository creation easier: https://cli.github.com/
---
## Option 1: Using GitHub Web Interface (Easiest)
### Step 1: Create Repository on GitHub
1. Go to https://github.com/new
2. Fill in:
- **Repository name**: `esp8266-weather-clock-opensource`
- **Description**: `Secure open-source firmware for ESP8266 weather clock - reverse engineered from AliExpress DIY kit`
- **Visibility**: Public ✅
- **Initialize**: ❌ Do NOT check "Add README" (we have one)
3. Click: **Create repository**
### Step 2: Initialize Local Git Repository
Open terminal and navigate to project directory:
```bash
cd "/Users/apetrochenko/Library/Mobile Documents/com~apple~CloudDocs/src/arduino/clock/esp8266-weather-clock-opensource"
```
Initialize git and add files:
```bash
# Initialize git
git init
# Add all files
git add .
# Create first commit
git commit -m "Initial commit: v1.9.1 production firmware
- Complete reverse engineering of TJ-56-654 weather clock
- Fixes security issues (WiFi password leak)
- Fully async architecture (zero blocking)
- OTA updates, web interface, REST API
- Open-Meteo weather (free, no API key)
- Comprehensive documentation"
```
### Step 3: Connect to GitHub
Replace `YOUR_USERNAME` with your actual GitHub username:
```bash
# Add remote
git remote add origin https://github.com/YOUR_USERNAME/esp8266-weather-clock-opensource.git
# Set main branch
git branch -M main
# Push to GitHub
git push -u origin main
```
**If prompted for credentials:**
- Username: Your GitHub username
- Password: Use **Personal Access Token** (not your password!)
- Create token at: https://github.com/settings/tokens
- Select scopes: `repo` (full control of private repositories)
### Step 4: Verify Upload
1. Browse to: `https://github.com/YOUR_USERNAME/esp8266-weather-clock-opensource`
2. You should see:
- README.md rendered nicely
- All directories and files
- First commit visible
---
## Option 2: Using GitHub CLI (Faster)
If you have GitHub CLI installed:
```bash
# Navigate to project
cd "/Users/apetrochenko/Library/Mobile Documents/com~apple~CloudDocs/src/arduino/clock/esp8266-weather-clock-opensource"
# Authenticate (one-time)
gh auth login
# Create repo and push in one command
gh repo create esp8266-weather-clock-opensource \
--public \
--source=. \
--description="Secure open-source firmware for ESP8266 weather clock" \
--push
```
Done! Repository is created and pushed.
---
## Step 5: Configure Repository Settings
### Add Topics (Tags)
1. Go to your repo on GitHub
2. Click: **⚙️ Settings** (top right near About)
3. Under "Topics", add:
- `esp8266`
- `arduino`
- `iot`
- `weather-station`
- `reverse-engineering`
- `security`
- `oled-display`
- `ntp`
- `ota-updates`
- `open-meteo`
### Update About Section
1. Go to repo main page
2. Click: **⚙️** (gear icon) next to "About"
3. Set:
- **Description**: `Secure open-source firmware for ESP8266 weather clock - reverse engineered from AliExpress DIY kit to fix security flaws`
- **Website**: `https://open-meteo.com` (or your personal site if you blog about it)
- **Topics**: Should already be set from above
### Enable Features
In **Settings → General**:
**Features**:
- ✅ Issues (for bug reports)
- ✅ Discussions (for questions)
- ❌ Wiki (not needed, we have docs/)
- ❌ Projects (not needed yet)
**Pull Requests**:
- ✅ Allow squash merging
- ✅ Automatically delete head branches
### Set Up GitHub Actions
The CI workflow should activate automatically on first push. Check:
1. Go to: **Actions** tab
2. You should see: "Build Firmware" workflow
3. It should run and ✅ pass (compiles firmware)
If it fails:
- Check library names in `.github/workflows/build.yml`
- Some libraries may need exact version pinning
---
## Step 6: Create First Release
### Tag the Release Locally
```bash
# Create annotated tag
git tag -a v1.9.1 -m "Release v1.9.1: Production-ready firmware
Features:
- Hybrid WiFi model (sync on boot, async in loop)
- Daylight duration display
- Fully async NTP, weather, WiFi reconnect
- OTA updates, web interface, REST API
- Open-Meteo weather (free API)
- Security fixes (no WiFi password leak)
Fixes:
- Startup display blank for 10+ seconds
- DNS resolution failed errors
- Sunrise/sunset label cutoff"
# Push tag to GitHub
git push origin v1.9.1
```
### Create Release on GitHub
1. Go to: **Releases** (right sidebar)
2. Click: **Draft a new release**
3. Fill in:
- **Tag**: `v1.9.1` (should appear in dropdown)
- **Release title**: `v1.9.1 - Production Ready`
- **Description**:
```markdown
## 🎉 First Public Release
Secure, open-source replacement firmware for ESP8266 weather clocks.
### ✨ Highlights
- **Security**: Fixes WiFi password leak in original firmware
- **Performance**: Fully async architecture, <1ms loop time
- **Features**: OTA updates, web UI, REST API, NTP time, weather
- **Free API**: Uses Open-Meteo (no registration required)
### 📦 Downloads
- `esp8266-weather-clock-v1.9.1.bin` - Flash this via OTA or FTDI
### 📖 Documentation
- [Installation Guide](docs/INSTALLATION.md)
- [Hardware Specs](docs/HARDWARE.md)
- [Full Changelog](CHANGELOG.md)
### 🚀 Quick Start
1. Download `.bin` file
2. Flash via FTDI (first time) or OTA (updates)
3. Connect to `TJ56654-Setup` WiFi
4. Configure your network
5. Access web UI at `http://tj56654-clock.local`
See [README](README.md) for complete instructions.
### 🐛 Known Issues
None! This release is production-ready and tested 24/7.
```
4. **Attach binary** (if you have it locally):
- Compile firmware first: Arduino IDE → Sketch → Export Compiled Binary
- Or use GitHub Actions artifact
- Drag `build/clock_ntp_ota_v1.9.ino.bin` to release assets
- Rename to: `esp8266-weather-clock-v1.9.1.bin`
5. Click: **Publish release**
---
## Step 7: Add Shields/Badges to README
Edit `README.md` and add at the top (after title):
```markdown
<p align="center">
<a href="https://github.com/YOUR_USERNAME/esp8266-weather-clock-opensource/releases">
<img src="https://img.shields.io/github/v/release/YOUR_USERNAME/esp8266-weather-clock-opensource?style=flat-square" alt="Release">
</a>
<a href="https://github.com/YOUR_USERNAME/esp8266-weather-clock-opensource/blob/main/LICENSE">
<img src="https://img.shields.io/github/license/YOUR_USERNAME/esp8266-weather-clock-opensource?style=flat-square" alt="License">
</a>
<a href="https://github.com/YOUR_USERNAME/esp8266-weather-clock-opensource/actions">
<img src="https://img.shields.io/github/actions/workflow/status/YOUR_USERNAME/esp8266-weather-clock-opensource/build.yml?style=flat-square" alt="Build">
</a>
<a href="https://github.com/YOUR_USERNAME/esp8266-weather-clock-opensource/issues">
<img src="https://img.shields.io/github/issues/YOUR_USERNAME/esp8266-weather-clock-opensource?style=flat-square" alt="Issues">
</a>
</p>
```
Replace `YOUR_USERNAME` with actual username.
Commit and push:
```bash
git add README.md
git commit -m "Add badges to README"
git push
```
---
## Step 8: Share Your Project
### Post on Social Media
**Reddit:**
- r/esp8266
- r/arduino
- r/selfhosted
- r/homeassistant (when you add HA integration)
**Hackaday:**
- Submit project tip: https://hackaday.com/submit-a-tip/
**Hackster.io:**
- Create project page: https://www.hackster.io/
**Twitter/X:**
```
Just reverse-engineered a $12 AliExpress weather clock and found it was leaking WiFi passwords!
Replaced the firmware with secure open-source version:
- ✅ No password leak
- ✅ OTA updates
- ✅ Free weather API
- ✅ Full async arch
Check it out: [your-repo-link]
#ESP8266 #IoTSecurity #Arduino
```
### Add to Awesome Lists
Search for "awesome ESP8266" and submit PR to add your project.
---
## Maintenance Tips
### Keep README Updated
When you add features:
1. Update README.md
2. Update CHANGELOG.md
3. Create new git tag
4. Create GitHub release
### Respond to Issues
Enable email notifications:
1. Go to: repo → **Watch** → **Custom**
2. Check: ✅ Issues, ✅ Pull requests, ✅ Discussions
### Version Numbering
Use semantic versioning (semver.org):
- `v2.0.0`: Breaking changes (incompatible config)
- `v1.10.0`: New features (backward-compatible)
- `v1.9.2`: Bug fixes only
### Automated Releases
GitHub Actions can auto-build on new tags. Check `.github/workflows/build.yml`.
---
## Troubleshooting
### "Permission denied" when pushing
**Solution**: Use Personal Access Token instead of password
1. Generate: https://github.com/settings/tokens
2. Scopes: `repo` (full control)
3. Use token as password when prompted
Or configure SSH keys:
```bash
# Generate SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"
# Add to GitHub: Settings → SSH Keys → New SSH key
# Paste contents of ~/.ssh/id_ed25519.pub
# Change remote to SSH
git remote set-url origin git@github.com:YOUR_USERNAME/esp8266-weather-clock-opensource.git
```
### "This repository is empty"
You forgot to push:
```bash
git push -u origin main
```
### Files too large
GitHub has 100MB file size limit. If you accidentally added build artifacts:
```bash
# Remove from staging
git reset HEAD build/
# Add to .gitignore
echo "build/" >> .gitignore
# Commit
git commit -m "Ignore build artifacts"
```
### CI build fails
Check:
- Library names are correct in `build.yml`
- All libraries are available via Arduino Library Manager
- Firmware compiles locally first
---
## Next Steps After Publishing
1. **Star your own repo** (to make it discoverable)
2. **Watch releases** (be notified of activity)
3. **Enable Discussions** (for community Q&A)
4. **Create SECURITY.md** (if you want responsible disclosure process)
5. **Add funding links** (GitHub Sponsors, Buy Me a Coffee, etc.)
---
## GitHub Repository Best Practices
### Essential Files (✅ You have these!)
- ✅ README.md
- ✅ LICENSE
- ✅ CONTRIBUTING.md
- ✅ CHANGELOG.md
- ✅ .gitignore
- ✅ Issue templates
### Nice-to-Have
- CODE_OF_CONDUCT.md (for community standards)
- SECURITY.md (vulnerability disclosure policy)
- FUNDING.yml (donation links)
### Pin Important Files
On your repo page, pin:
1. README.md (auto-pinned)
2. INSTALLATION.md (pin in About section)
3. Latest release (pin in sidebar)
---
## Success Checklist
After publishing, verify:
- [ ] Repository is public and accessible
- [ ] README renders correctly (images, links work)
- [ ] All documentation files are present
- [ ] CI/CD pipeline passes (green checkmark)
- [ ] First release is tagged and published
- [ ] Binary is attached to release
- [ ] Topics/tags are set
- [ ] License is visible
- [ ] Issues and Discussions are enabled
---
**Congratulations!** Your project is now public and ready to help the world build secure IoT devices. 🚀
---
**Repository URL**: https://github.com/YOUR_USERNAME/esp8266-weather-clock-opensource
Don't forget to replace `YOUR_USERNAME` with your actual GitHub username!