Update README.md for improved clarity on AC control and sensor configuration

2025-11-05 15:37:29 -05:00 · 2025-11-05 15:37:29 -05:00 · 99afba25c4
commit 99afba25c4
parent 5618f07113
1 changed files with 158 additions and 20 deletions
--- 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.