raspberry-pico-balcony-watering/README.md

# raspberry-pico-balcony-watering
The goal of this project was to build an automated watering system for the vegetables on my balcony with soil moisture sensors. In addition, I included it into my home automation system FHEM.  
You can manually turn on/off the watering pump, trigger a watering pulse (you can set the duration), turn on/off the automatic watering mode (this mode allows automatic watering, if soil moisture is below a threshold it triggers a watering pulse).  
You can fully customize the parameters, for example the interval the system should read new soil moisture, what is the threshold for the soil moisture to be considered dry or wet

## Setup  
1. Upload all *.py files to your Raspberry Pico W  
2. Set your wifi credentials in secrets.py file. Also set an api_key.  
3. Set values in configs.py file  
4. Be sure that you give your Pico W a static IP address on your router, so you know where the webservice is available and can configure it in FHEM

In the file configs.py set your configurations:  
country: your countrycode (AT=Austria, DE=Germany...) (2-digit string)  
ntp_host: set a ntp server (string url)  
gmt_offset: offset to gmt for your timezone in hours (int)  
auto_summertime: Enables changing to summertime (and back) automatically (True/False)  
disable_wifi_powersavingmode: Wifi powersavingmode is enabled per default. Set to true to disable powersavingmode for Wifi (True/False)  
api_port: Port on which the API is available (int)  
log_housekeeping_days: Logfiles older than this value in days get deleted by housekeeping (int)  
api_client_ip: Only this IP is allowed to use the API. Leave blank to allow all connections from all IPs (string)  
pulse_duration: Duration of watering pulse (time between pump on and off) in seconds (int)  
soil_moisture_measure_interval: Interval when to read new values from soil moisture sensors in minutes (int)  
check_for_update: Interval when to check for OTA updates in minutes (int)  
ota_host: Host for checking for OTA updates (http://ip-of-your-update-host) - leave empty to disable OTA updates

In the file secrets.py set your configurations:  
ssid: Wifi name (string)  
pw: Wifi password (string)  
api: API key (string)  

**Hint:** use `openssl rand -hex 20` to generate the api_key  

## Hardware  
You need the following parts:  
[Raspberry Pico W](https://mk0.at/pico-w)  
[Water pump](https://www.amazon.de/dp/B07L1FB18S?psc=1&ref=ppx_yo2ov_dt_b_product_details)  
[6mm water hose and mounting material](https://www.amazon.de/dp/B07RTHNSWK?psc=1&ref=ppx_yo2ov_dt_b_product_details)  
[3 Soil moisture sensors](https://www.amazon.de/dp/B08GCRZVSR?psc=1&ref=ppx_yo2ov_dt_b_product_details)  
[DC to DC converter](https://www.amazon.de/dp/B09B818N5F?psc=1&ref=ppx_yo2ov_dt_b_product_details)  
[12 V PWM solar charge controller](https://www.amazon.de/dp/B08Z84FT4Z?psc=1&ref=ppx_yo2ov_dt_b_product_details)  
[30 Watt Solar panel](https://www.amazon.de/Offgridtec-Solarmodul-Solarpanel-Photovoltaikmodul-3-01-001530/dp/B007HLNFES/ref=sxin_17_pa_sp_search_thematic_sspa?content-id=amzn1.sym.9a40cf28-51bb-4bea-92a6-a7215aacac74%3Aamzn1.sym.9a40cf28-51bb-4bea-92a6-a7215aacac74&cv_ct_cx=30+watt+solar&keywords=30+watt+solar&pd_rd_i=B007HLNFES&pd_rd_r=eaf2fb78-64fb-4763-b113-36d1fa0d9c91&pd_rd_w=gWBgZ&pd_rd_wg=eFzLl&pf_rd_p=9a40cf28-51bb-4bea-92a6-a7215aacac74&pf_rd_r=RG1JFKQVJPW7YD850G8W&qid=1688189898&sbo=RZvfv%2F%2FHxDF%2BO5021pAnSA%3D%3D&sr=1-2-6e6ea531-5af4-4866-af75-1ef299d1c279-spons&sp_csd=d2lkZ2V0TmFtZT1zcF9zZWFyY2hfdGhlbWF0aWM&psc=1)
[Waterlevel switch](https://www.amazon.de/dp/B09B1KQV7B?psc=1&ref=ppx_yo2ov_dt_b_product_details)
12 V Battery
3D-printed waterhose clamps (see folder 3d)  
3D-printed waterhose dripping tips (see folder 3d)  
3D-printed case (see folder 3d)  
Prototype PCB (see folder kicad)  

## Pico W API  
You can configure the port, on which the API runs in configs.py in the 'api_port'-value. You also have to set an API-Key in secrets.py in the 'api'-value. Then you can call the API as follows:  
http://servername/api_key/command[/json]  

You can use the following commands:  
wateron - Turns on the watering pump  
wateroff - Turns off the watering pump  
waterstate - Returns the state of the watering pump  
waterpulse - Triggers the watering pump for the duration of pulse_duration (set it in configs.py)  
autoon - Enables automatic watering mode  
autooff - Disables automatic watering mode  
autostate - Returns state of automatic watering mode  
forcesoilread - Forces new readings from soil moisture sensors  
waterlevel - Returns the level of the water tank  
ping - Check if the API is up and running  
stats - Returns some stats of the device  
reboot - Reboots the device  
logs - See logs of the device (you can add a number like .../stats/12 to see the latest 12 log lines)
soils - See soil moisture of the device (usage like logs)

## FHEM Integration  
This is the Watering-HTTPMOD Device for FHEM. It shows status symbols and all readings from stats. You can manually trigger a watering pulse and enable/disable the automatic watering mode.  
```
defmod Watering HTTPMOD 0
attr Watering devStateIcon full:zisterne_100 empty:zisterne_00 wet:water@green:wateringPulse dry:water@red:wateringPulse on:automatic@green:autoModeOff off:automatic@red:autoModeOn
attr Watering event-on-change-reading .*
attr Watering extractAllJSON 1
attr Watering fp_Wohnung 30,590,5,
attr Watering get05Name stats
attr Watering get05Poll 1
attr Watering get05URL http://watering-host/api_key/stats/json
attr Watering icon measure_water_meter
attr Watering room Start,Watering
attr Watering set01Name wateringOn
attr Watering set01NoArg 1
attr Watering set01URL http://watering-host/api_key/wateron
attr Watering set02Name wateringOff
attr Watering set02NoArg 1
attr Watering set02URL http://watering-host/api_key/wateroff
attr Watering set03Name wateringPulse
attr Watering set03NoArg 1
attr Watering set03URL http://watering-host/api_key/waterpulse
attr Watering set04FollowGet stats
attr Watering set04Name autoModeOn
attr Watering set04NoArg 1
attr Watering set04URL http://watering-host/api_key/autoon
attr Watering set05FollowGet stats
attr Watering set05Name autoModeOff
attr Watering set05NoArg 1
attr Watering set05URL http://watering-host/api_key/autooff
attr Watering stateFormat Watering_Soil_is \
Watering_Water_level_status \
Watering_Automatic_watering_Mode
```

Example of a notification to your Nextcloud Talk instance in case the water tank is empty.  
```
defmod n_WateringWaterEmpty notify Watering:Watering_Water_level_status:.empty {\
fhem("set Talk msg Kein Wasser im Tank der Bewässerungsanlage!");;
}
attr n_WateringWaterEmpty room Watering
```