From 99afba25c42bec7ffd2bdac27291f2c3179894c5 Mon Sep 17 00:00:00 2001 From: sickprodigy Date: Wed, 5 Nov 2025 15:37:29 -0500 Subject: [PATCH] Update README.md for improved clarity on AC control and sensor configuration --- README.md | 178 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 158 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 08665a9..049e766 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ ## Overview -This project automates garden monitoring using a Raspberry Pi Pico W with temperature sensors, Discord notifications, and planned expansion for humidity, soil moisture, and environmental controls. +This project automates garden monitoring using a Raspberry Pi Pico W with temperature sensors, Discord notifications, and AC control for climate management. ## Features @@ -14,9 +14,11 @@ This project automates garden monitoring using a Raspberry Pi Pico W with temper - ✅ Separate alert channel for critical temperatures - ✅ Temperature logging to CSV file - ✅ Configurable alert thresholds +- ✅ Automated AC control with temperature swing logic +- ✅ Relay control via opto-coupler for 110V AC - 🚧 Humidity monitoring (planned) - 🚧 Soil moisture monitoring (planned) -- 🚧 Relay control for fans, AC, heaters (planned) +- 🚧 Additional relay control for fans, heaters (planned) ## Quick Start @@ -27,6 +29,7 @@ This project automates garden monitoring using a Raspberry Pi Pico W with temper - Raspberry Pi Pico W - DS18B20 temperature sensors (waterproof recommended) - 4.7kΩ resistor (pull-up for 1-Wire bus) +- Opto-coupler relay module (3.3V logic, 110V AC rated) - Momentary button (optional, for easy reset) See the [Items Needed Wiki](https://gitea.rcs1.top/sickprodigy/Auto-Garden/wiki/Items-Needed-for-the-Project) for full parts list. @@ -46,6 +49,28 @@ Yellow (Data) → GP10 (Inside) - Pin 14 Add 4.7kΩ resistor between Data line and 3.3V ``` +**⚠️ Important:** The 4.7kΩ pull-up resistor is **required** for reliable 1-Wire communication. While it may work without it occasionally, you'll experience intermittent failures, communication errors, and unreliable readings. + +**Opto-Coupler Relay Module:** + +```text +Low Voltage Side (Pico): +GP15 (Pin 20) → IN (Signal) +3.3V (Pin 36) → VCC +GND → GND + +High Voltage Side (AC Unit): +NO (Normally Open) → AC Control Wire 1 +COM (Common) → AC Control Wire 2 +``` + +**Note:** Most opto-coupler modules work with standard logic: + +- `relay.on()` = relay energized (NO closes) = AC ON +- `relay.off()` = relay de-energized (NC closes) = AC OFF + +If your AC behavior is inverted (turns on when it should be off), your module may be active LOW—see troubleshooting section. + **Optional Reset Button:** ```text @@ -80,23 +105,33 @@ secrets = { } ``` -**Configure sensors in `scripts/temperature_sensor.py`:** +**Configure sensors and AC in `main.py`:** ```python +# Sensor configuration SENSOR_CONFIG = { 'inside': { 'pin': 10, 'label': 'Inside', - 'alert_high': 85.0, - 'alert_low': 32.0 + 'alert_high': 80.0, + 'alert_low': 70.0 }, 'outside': { 'pin': 11, 'label': 'Outside', - 'alert_high': 100.0, - 'alert_low': 20.0 + 'alert_high': 85.0, + 'alert_low': 68.0 } } + +# AC Controller options +relay_pin = 15 +min_run_time = 300 # Minimum 5 minutes run time +min_off_time = 180 # Minimum 3 minutes off time + +# AC Monitor options +target_temp = 75.0 # Target temperature in °F +temp_swing = 2.0 # ±2°F swing (AC on at 77°F, off at 73°F) ``` ### 5. Upload & Run @@ -108,6 +143,7 @@ Upload all files to your Pico: ├── main.py ├── secrets.py └── scripts/ + ├── air_conditioning.py ├── discord_webhook.py ├── monitors.py ├── networking.py @@ -120,27 +156,51 @@ The Pico will auto-start `main.py` on boot. ```text Auto-Garden/ -├── main.py # Entry point, sets up monitors +├── main.py # Entry point, configuration, monitor setup ├── secrets.py # WiFi & Discord credentials (gitignored) ├── secrets.example.py # Template for secrets.py └── scripts/ + ├── air_conditioning.py # AC controller with short-cycle protection ├── discord_webhook.py # Discord notification handling ├── monitors.py # Monitor base class & implementations ├── networking.py # WiFi connection management - └── temperature_sensor.py # DS18B20 sensor interface & config + └── temperature_sensor.py # DS18B20 sensor interface ``` -## Monitoring Behavior +## How It Works + +### Temperature Monitoring - **Every 10 seconds:** Check temperatures, send alerts if out of range - **Every 30 seconds:** Regular temperature reports to Discord + log to file -- **Every 5 seconds:** WiFi connection check with auto-reconnect **Discord Channels:** - `discord_webhook_url`: Regular temperature updates, connection status - `discord_alert_webhook_url`: Critical temperature alerts (Inside sensor only) +### AC Control Logic + +- **Every 30 seconds:** Check inside temperature and decide AC state +- **Temperature swing:** Creates a "dead band" to prevent rapid cycling + - Example: Target 75°F with 2°F swing + - AC turns **ON** when temp > 77°F + - AC turns **OFF** when temp < 73°F + - Between 73-77°F: maintains current state + +**Short-Cycle Protection:** + +- Minimum run time (default 5 min) prevents AC from turning off too quickly +- Minimum off time (default 3 min) protects compressor from rapid restarts + +### WiFi Monitoring + +- **Every 5 seconds:** Check WiFi connection status +- **LED Indicator:** + - Slow blink (1 sec on/off): Connected + - Fast blink (0.2 sec): Disconnected +- **Auto-reconnect:** Attempts reconnection every 60 seconds if disconnected + ## Temperature Logs Logs are saved to `/temp_logs.csv` on the Pico: @@ -152,43 +212,120 @@ Logs are saved to `/temp_logs.csv` on the Pico: Format: `timestamp,location,sensor_id,temperature_f` +## Customization + +All configuration is centralized in `main.py`: + +**Sensor Settings:** + +- Pin assignments +- Alert thresholds (high/low) +- Labels + +**AC Settings:** + +- Relay pin +- Target temperature +- Temperature swing (dead band) +- Minimum run/off times + +**Monitor Intervals:** + +- Temperature check/report intervals +- WiFi check interval +- AC control interval + +## Safety Notes + +⚠️ **High Voltage Warning:** + +- Opto-couplers isolate the Pico from AC voltage +- Never connect GPIO pins directly to 110V AC +- Ensure your opto-coupler module is rated for your voltage +- Test relay switching with a multimeter before connecting AC +- Consider hiring a licensed electrician if uncomfortable with AC wiring + +**Compressor Protection:** + +- Always use minimum run/off times (defaults are safe) +- Minimum 3 minutes off time protects compressor bearings +- Minimum 5 minutes run time prevents short cycling + ## Future Expansion ### Planned Features - **Humidity Sensors:** DHT22 or SHT31 for air humidity monitoring - **Soil Moisture:** Capacitive sensors for plant watering automation -- **Relay Control:** 3V-32VDC SSR relays for switching AC, fans, heaters +- **Additional Relays:** Control for fans, heaters, grow lights - **Smart Ventilation:** Auto-open windows when outside air is optimal -- **Light Monitoring:** LDR or BH1750 for grow light automation +- **Light Monitoring:** LDR or BH1750 for day/night cycles -### Relay Wiring (Future) +### Adding More Sensors -```text -Pico 3.3V output → SSR relay input → High voltage device (120V/240V) +To add a new temperature sensor: + +First Add to `SENSOR_CONFIG` in `main.py`: + +```python +'greenhouse': { + 'pin': 12, + 'label': 'Greenhouse', + 'alert_high': 90.0, + 'alert_low': 50.0 +} ``` -Use solid-state relays (SSR) rated for your voltage/current needs. +Second Add a `TemperatureMonitor` to the monitors list: + +```python +TemperatureMonitor( + sensor=sensors['greenhouse'], + label=SENSOR_CONFIG['greenhouse']['label'], + check_interval=10, + report_interval=30, + alert_high=SENSOR_CONFIG['greenhouse']['alert_high'], + alert_low=SENSOR_CONFIG['greenhouse']['alert_low'], + log_file="/temp_logs.csv", + send_alerts_to_separate_channel=False +) +``` ## Troubleshooting **No temperature readings:** -- Check 4.7kΩ pull-up resistor is connected +- Check 4.7kΩ pull-up resistor is connected between data line and 3.3V - Verify sensor wiring (VDD to 3.3V, not 5V) - Check GPIO pin numbers in `SENSOR_CONFIG` +- Run `sensor.scan_sensors()` to detect connected sensors **WiFi not connecting:** - Verify SSID/password in `secrets.py` - Check 2.4GHz WiFi (Pico W doesn't support 5GHz) - Look for connection messages in serial console +- LED should blink slowly when connected **Discord messages not sending:** - Verify webhook URLs are correct - Test webhooks with curl/Postman first -- Check Pico has internet access (ping test) +- Check Pico has internet access + +**AC not switching:** + +- Verify relay pin number (default GP15) +- Test relay manually: `Pin(15, Pin.OUT).off()` should activate it +- Check if module is active LOW or active HIGH +- Ensure opto-coupler has 3.3V power +- Look for LED on relay module (should light when active) +- Verify minimum run/off times haven't locked out switching + +**AC behavior inverted:** + +- Your opto-coupler is likely active LOW +- In `air_conditioning.py`, swap `relay.on()` and `relay.off()` calls ## Contributing @@ -204,7 +341,8 @@ MIT License - See LICENSE file for details - [MicroPython Documentation](https://docs.micropython.org/) - [DS18B20 Datasheet](https://www.analog.com/media/en/technical-documentation/data-sheets/DS18B20.pdf) - [Discord Webhooks Guide](https://discord.com/developers/docs/resources/webhook) +- [1-Wire Protocol Guide](https://www.analog.com/en/technical-articles/guide-to-1wire-communication.html) --- -**Note:** Always ensure proper electrical safety when working with high-voltage relays and AC power. Consult a licensed electrician if unsure. +**Note:** Always ensure proper electrical safety when working with high-voltage relays and AC power. Test thoroughly before leaving unattended.