Alex PetrochenkoandClaude Sonnet 4.6
29d7c7f8ad
src/clock_ntp_ota_v1.9.ino was a duplicate of firmware/clock_ntp_ota_v1.9/ that had already drifted out of sync. Removing it eliminates the need to patch both copies on every PR. Updated CONTRIBUTING.md build path to point to firmware/clock_ntp_ota_v1.9. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
110 lines
2.7 KiB
Markdown
110 lines
2.7 KiB
Markdown
# 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
|
|
|
|
1. **Fork the repository**
|
|
2. **Create a feature branch**: `git checkout -b feature/my-new-feature`
|
|
3. **Test your changes**:
|
|
- Compile successfully
|
|
- Test on real hardware if possible
|
|
- Check memory usage (IRAM must stay < 95%)
|
|
4. **Follow the code style**:
|
|
- Use `ICACHE_FLASH_ATTR` for non-critical functions
|
|
- Avoid String concatenation in loops
|
|
- Document state machines with comments
|
|
5. **Commit with clear messages**: Explain what and why, not how
|
|
6. **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
|
|
|
|
```bash
|
|
# Arduino IDE: Sketch → Verify/Compile
|
|
# Or use arduino-cli:
|
|
arduino-cli compile --fqbn esp8266:esp8266:generic firmware/clock_ntp_ota_v1.9
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# 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/
|
|
├── firmware/ # Main firmware source (clock_ntp_ota_v1.9/)
|
|
├── 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!
|