added docs

README.md

@@ -1,2 +1,10 @@
 # Smart_Garden
 
+## Requirements
+VisualStudioCode with PlatformIO extension
+
+## Build
+Configuration is defined in `platformio.ini` file. If you have PlatformIO extension installed, just use built-in build-command.
+
+## Flash to µC
+Connect ESP32 to any desired USB-Port and use PlatformIOs upload-command.

platformio.ini

@@ -18,11 +18,8 @@ monitor_speed = 115200
 lib_deps =
   439 #ID of Lightsensor library BH1750 
   19 #DHT sensor library 
-  31 #Adafruit Unified Sensor
   AutoConnect@^1.1.7
-  AsyncMqttClient@^0.8.2
   ArduinoJson@^6.15.2
-  ; MQTT@^2.4.7
   PubSubClient@^2.8
   ArduinoNvs@^2.5
   ESPRandom@^1.3.3

src/capacitiveSoilMoistureSensor.cpp

@@ -5,23 +5,22 @@
 
 const int numReadings = 20;
 
-void setupCapacitiveSoilMoistureSensor() {
+// reads soil moisture multiple times and calculates average to eliminate noise
-  // pinMode(PIN_MS, INPUT);
-}
-
 int readCapacitiveSoilMoistureSensor() {
   int total = 0;  // the running total
-  // read from the sensor:
+  // read from the sensor
   for (int readIndex = 0; readIndex < numReadings; readIndex++) {
     total = total + analogRead(PIN_MS);
     delay(2);
   }
   int measurement = total / numReadings;
 
+  // map measurement to relative soil moisture value in %
   int finalRes = map(measurement, VALUE_AIR, VALUE_WATER, 0, 100);
   Serial.print("current soil moisture: ");
   Serial.println(finalRes);
 
+  // clamp mesurement to a value between 0 and 100
   if (finalRes < 0) {
     return 0;
   } else if (finalRes > 100) {

src/capacitiveSoilMoistureSensor.h

@@ -1,2 +1 @@
-void setupCapacitiveSoilMoistureSensor();
 int readCapacitiveSoilMoistureSensor();

src/common.h

@@ -1,4 +1,5 @@
 #include <Arduino.h>
+// this common Header file defines commonly used hardware and buildtime constants
 
 // PUBLISH FREQUENCY (MS)
 #define FREQUENCY 60000

src/connections.cpp

@@ -31,6 +31,7 @@ WiFiClient client;
 AutoConnectConfig Config;
 PubSubClient mqttClient(client);
 
+// spins wifi up and activates green status light when wifi is conencted
 void connectWiFi() {
   yield();
   Serial.println("Start WiFi...");
@@ -39,6 +40,7 @@ void connectWiFi() {
   }
 }
 
+// handles MQTT messages and keeps track of MQTT connection. starts reconnect timer if connection lost.
 void mqttLoop(void *parameter) {
   do {
     yield();
@@ -56,11 +58,12 @@ void mqttLoop(void *parameter) {
   vTaskDelete(NULL);
 }
 
+// setup MQTT connection and spins up task to handle connection and messages
 void connectMQTT() {
   yield();
   if (mqttClient.connected()) return;
   Serial.println("Connecting to MQTT...");
-  // mqttClient.begin(MQTT_HOST, MQTT_PORT, client);
+
   mqttClient.setServer(MQTT_HOST, MQTT_PORT);
   mqttClient.disconnect();
   mqttClient.connect(getDeviceIDcharArr());
@@ -82,6 +85,7 @@ void connectMQTT() {
       1);
 }
 
+// handles lost wifi connection
 void WiFiEvent(WiFiEvent_t event, WiFiEventInfo_t info) {
   Serial.printf("[WiFi-event] event: %d\n", event);
   switch (event) {
@@ -105,6 +109,7 @@ void WiFiEvent(WiFiEvent_t event, WiFiEventInfo_t info) {
   }
 }
 
+// mqtt callback handles incoming messages
 void onMqttMessage(char *topic, byte *payload, unsigned int payload_length) {
   Serial.print("Message arrived [");
   Serial.print(topic);
@@ -115,7 +120,7 @@ void onMqttMessage(char *topic, byte *payload, unsigned int payload_length) {
   Serial.println();
 
   if (strcmp(topic, MQTT_LIGHT_PROPERTIES) == 0) {
-    Serial.println("receiving light treshold...");
+    Serial.println("receiving light threshold...");
     Serial.println(topic);
     StaticJsonDocument<1024> doc;
     DeserializationError err = deserializeJson(doc, payload);
@@ -161,6 +166,7 @@ void onMqttMessage(char *topic, byte *payload, unsigned int payload_length) {
   }
 }
 
+// generates mqtt topics based on device-uuid
 void constructMQTTpaths() {
   strcpy(MQTT_VALVE_COMMAND, MQTT_TOPIC_BASE_SUB "/");
   strcat(MQTT_VALVE_COMMAND, getDeviceIDcharArr());
@@ -185,16 +191,17 @@ void constructMQTTpaths() {
   Serial.println(MQTT_AUTO_PROPERTIES);
 }
 
+// initializes Wifi and MQTT connections
 void setupConnections() {
   constructMQTTpaths();
   Serial.println();
   Serial.println();
+  // disable Watchdog Task. This task made ESP stopped working, probably caused by working with arduino framework combined with multicore-concurrent patterns
   disableCore0WDT();
-  // disableCore1WDT();
   Config.autoReconnect = true;
-  // Config.autoReset = true;
   Portal.config(Config);
 
+  // FreeRTOS Timer to handle loss of connections
   mqttReconnectTimer = xTimerCreate(
       "mqttTimer", pdMS_TO_TICKS(2000), pdFALSE, (void *)0, reinterpret_cast<TimerCallbackFunction_t>(connectMQTT));
   wifiReconnectTimer = xTimerCreate(
@@ -209,6 +216,7 @@ void setupConnections() {
   setupNTP();
 }
 
+// method to delegate publish from other modules to connecions module
 void publishMessage(const char *topic, const char *msg) {
   if(mqttClient.connected()) {
     mqttClient.publish(topic, msg);

src/lightSensor.cpp

@@ -1,4 +1,3 @@
-#include <Adafruit_Sensor.h>
 #include <BH1750.h>
 #include <Wire.h>
 #include <lightSensor.h>

src/sensors.cpp

@@ -17,8 +17,8 @@ void setupSensors() {
   setupLightSensor();
   setupPWM();
   setupTemperatureSensor();
-  setupCapacitiveSoilMoistureSensor();
 
+  // generates MQTT topics based on device ID
   strcpy(MQTT_SENSOR_DATA_TOPIC, MQTT_TOPIC_BASE_PUB "/");
   strcat(MQTT_SENSOR_DATA_TOPIC, getDeviceIDcharArr());
   strcat(MQTT_SENSOR_DATA_TOPIC, "/data");
@@ -26,6 +26,7 @@ void setupSensors() {
   Serial.println(MQTT_SENSOR_DATA_TOPIC);
 }
 
+// function to collect sensor data and delegate collected data as json to mqtt-task
 void readSensors() {
   Serial.println();
   StaticJsonDocument<128> doc;
@@ -34,7 +35,7 @@ void readSensors() {
   Serial.print(lxValue);
   Serial.println(" lx");
   doc["brightness"] = lxValue;
-  if ((lxValue < minimumLightValueLX) && checkForDay()) {
+  if (automaticLight && (lxValue < minimumLightValueLX && checkForDay())) {
     triggerLight();
   }
 

src/store.cpp

@@ -18,6 +18,7 @@ bool automaticIrrigation = false;
 // Make sure device irrigates until fieldcapacity is reached
 bool irrigateUntilFC = false;
 
+// stores properties to non-volatile-flash
 void persistSoilProps(int FC, int PWP, int SAT) {
   Serial.println("persistSoilProps");
   bool f = NVS.setInt("fieldCapacity", FC);
@@ -32,6 +33,7 @@ void persistSoilProps(int FC, int PWP, int SAT) {
   }
 }
 
+// restores properties from nvs on boot
 void restoreSoilProps() {
   Serial.println("restoreSoilProps");
   int fc = NVS.getInt("fieldCapacity");
@@ -54,6 +56,7 @@ void restoreSoilProps() {
   Serial.println(soilSaturation);
 }
 
+// will be executed in setup process when booting µC
 void setupStore() {
   NVS.begin("store");
   initDeviceID();
@@ -62,6 +65,7 @@ void setupStore() {
   restoreAutoProps();
 }
 
+// sets soil properties and calls funtion to persist them
 void setSoilProperties(int FC, int PWP, int SAT) {
   fieldCapacity = FC;
   permanentWiltingPoint = PWP;
@@ -125,6 +129,7 @@ void persistAutoProps(bool light, bool irrigation) {
   }
 }
 
+// restores properties from nvs on boot
 void restoreAutoProps() {
   Serial.println("restoreLightProps");
   int li = NVS.getInt("automaticLight");
@@ -145,6 +150,7 @@ void setAutoProperties(bool light, bool irrigation) {
 
 String DEVICE_ID = "";
 
+// generates device UUID on first boot and stores it to NVS. UUID will be restored from NVS after each subsequent boot
 void initDeviceID() {
   DEVICE_ID = NVS.getString("UUID");
   if (!DEVICE_ID.isEmpty()) {

src/valve.cpp

@@ -9,6 +9,7 @@ extern "C" {
 
 #include <valve.h>
 
+// open valve and set status led to blue while irrigating
 bool openValve() {
   digitalWrite(PIN_VALVE, HIGH);
   digitalWrite(PIN_LED_G, LOW);
@@ -16,6 +17,7 @@ bool openValve() {
   return true;
 }
 
+// close valve and set status back to green
 bool closeValve() {
   digitalWrite(PIN_VALVE, LOW);
   digitalWrite(PIN_LED_G, HIGH);
@@ -23,7 +25,9 @@ bool closeValve() {
   return false;
 }
 
+// function to handle valve control, see documentation for visual representation of control flow
 void valveTask(void *parameter) {
+  // this parameter is used to determine if task was triggered manually by mqtt or by the sensor loop
   bool isAutomatic = (bool)parameter;
   Serial.print(isAutomatic);
   Serial.println(" Valve task triggered.");
@@ -55,6 +59,7 @@ void valveTask(void *parameter) {
   vTaskDelete(NULL);
 }
 
+// Creates a new task which handles valve control concurrently
 void toggleValve(bool automatic) {
   xTaskCreate(
       valveTask,   /* Task function. */