stimewifi more documentation and new version

platformio/stima_v3/stimawifi/include/stimawifi_config.h

@@ -2,21 +2,28 @@
 #define STIMAWIFI_CONFIG_H_
 
 // increment on change
-#define SOFTWARE_VERSION "2024-10-17T00:00"    // date and time
-#define MAJOR_VERSION    "20241017"            // date  YYYYMMDD
+#define SOFTWARE_VERSION "2024-10-31T00:00"    // date and time
+#define MAJOR_VERSION    "20241031"            // date  YYYYMMDD
 #define MINOR_VERSION    "0"                   // time  HHMM without leading 0
 
+// SSID and password of WiFi for setup
 #define WIFI_SSED "STIMA-config"
 #define WIFI_PASSWORD  "bellastima"
+
+// defaul sample time to get measure from sensors
 #define DEFAULT_SAMPLETIME 30
+
+// udp port to use for communicate with androd gps_forwarder app
 #define UDP_PORT 8888
 
+// display I2C address
 #define OLEDI2CADDRESS 0X3C
 
 // logging level at compile time
 // Available levels are:
 // LOG_LEVEL_SILENT, LOG_LEVEL_FATAL, LOG_LEVEL_ERROR, LOG_LEVEL_WARNING, LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE
 #define LOG_LEVEL   LOG_LEVEL_NOTICE
+
 // Length of datetime string %04u-%02u-%02uT%02u:%02u:%02u
 #define DATE_TIME_STRING_LENGTH                       (25)
 
@@ -26,14 +33,19 @@
 // minimum thread stack size for warning
 #define STACK_MIN_WARNING 100
 
+// port for http server
 #define STIMAHTTP_PORT 80
 
 #define FIRMWARE_TYPE "LOLIN_C3_MINI"
+
+// set to 1 if we use PMS sensor
 #define PMS_RESET 0
 
+// define pins for I2C
 #define SCL_PIN SCL
 #define SDA_PIN SDA
 
+// define reset and LED pins
 #if defined(ARDUINO_LOLIN_C3_MINI)
 //C3 mini
 // https://www.wemos.cc/en/latest/_static/files/sch_c3_mini_v2.1.0.pdf
@@ -56,13 +68,15 @@
 #define LED_PIN 34       // not connected to neopixel
 #endif
 
-// for sensor_t
+// size for sensor_t
 #define SENSORDRIVER_DRIVER_LEN 5
 #define SENSORDRIVER_TYPE_LEN 5
 #define SENSORDRIVER_META_LEN 30
 
-#define CH 8            // character height px for display
+// character height px for display
+#define CH 8
 
+// define parameter for queues len and communication
 //#define DATA_BURST (SENSORS_MAX*VALUES_TO_READ_FROM_SENSOR_COUNT)
 #define DATA_BURST (15)
 #define DATA_BURST_RECOVERY (DATA_BURST)
@@ -75,8 +89,7 @@
 #define MQTT_QUEUE_SPACELEFT_RECOVERY (DATA_BURST*2)
 
 // SD card SPI PIN assignment
-
-//Micro SD Card Shield
+// Micro SD Card Shield
 #define C3SCK 1   
 #define C3MISO 0  
 #define C3MOSI 4  
@@ -91,18 +104,20 @@
 // SPI clock
 #define SPICLOCK 10000000
 
-// SD card max number of file
+// SD card max number of file opened
 #define SDMAXFILE 6
 
-
+// SD card file name for archive
+#define SDCARD_INFO_FILE_NAME    ("/info.dat")
 #define SDCARD_ARCHIVE_FILE_NAME ("/archive.dat")
 
-// littlefs max number of file
+// littlefs max number of file opened on EEPROM
 #define LFMAXFILE 4
 
-// time in seconds saved on SD card for archive and recovery
+// time in seconds saved on sqlite on SD card for tmp archive and recovery
 #define SDRECOVERYTIME (3600*24*1)
 
+// sqlite setup
 /*
   https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/memory-types.html
   There is 520 KB of available SRAM (320 KB of DRAM and 200 KB of
@@ -131,9 +146,9 @@
 */
 #define MQTT_PACKET_SIZE               (220)
 
+// MQTT broker port
 # define MQTT_SERVER_PORT (1883)
 
-
 /*!
 \def CONSTANTDATA_BTABLE_LENGTH
 \brief Maximum lenght of btable code plus terminator that describe one constant data.

platformio/stima_v3/stimawifi/src/db_thread.cpp

@@ -163,11 +163,7 @@ bool dbThread::data_purge(const bool flush=false, int nmessages=100){
   data->logger->notice(F("db Start purge"));       
 
   //The values emitted by the RETURNING clause are the values as seen
-  //by the top-level DELETE, INSERT, or UPDATE statement and do not
-  //reflect any subsequent value changes made by triggers. Thus, if
-  //the database includes AFTER triggers that modifies some of the
-  //values of each row inserted or updated, the RETURNING clause emits
-  //the original values that are computed before those triggers run
+  //by the top-level DELETE, INSERT, or UPDATE statement
 
   char sql[100];
   //char sql[] = "DELETE FROM messages WHERE datetime < strftime('%s',?)";
@@ -264,7 +260,7 @@ bool dbThread::data_purge(const bool flush=false, int nmessages=100){
 }
 
 
-// set data in specific datetime range as unset for recovery
+// set data in specific datetime range as unsent for recovery
 // of messages for retrasmission
 bool dbThread::data_set_recovery(void){
   int rc;
@@ -610,7 +606,7 @@ void dbThread::Run() {
   }
 
   // open and write info.dat file
-  File infoFile = SD.open("/info.dat", FILE_WRITE);
+  File infoFile = SD.open(SDCARD_INFO_FILE_NAME, FILE_WRITE);
   if (!infoFile){
     data->logger->error(F("db failed to open info file for writing"));
   }

platformio/stima_v3/stimawifi/src/measure_thread.cpp

@@ -83,6 +83,7 @@ void measureThread::get_summary_data_in_progress(uint8_t i) {
 
 }
 
+// encode and enqueue in a proper queue one message
 void measureThread::enqueueMqttMessage(uint8_t i ) {
 
   mqttMessage_t mqtt_message;
@@ -179,7 +180,7 @@ void measureThread::enqueueMqttMessage(uint8_t i ) {
   }
 }
 
-// execute all measure required
+// execute all required measure 
 void measureThread::doMeasure() {
 
   //LockGuard guard(data->i2cmutex);
@@ -308,15 +309,15 @@ void measureThread::Cleanup()
 void measureThread::Run() {
   data->logger->notice("Starting Thread %s %d", GetName().c_str(), data->id);
   for(;;){
-    // wait for notification from the main task when we have to do measurements
+    // wait for notification from the main task; start when we have to do measurements
     WaitForNotification();
-    if (timeStatus() == timeSet) doMeasure();
+    if (timeStatus() == timeSet) doMeasure();  // measure il we can use a timestamp
 
     // check heap and stack
     //data->logger->notice(F("HEAP: %l"),esp_get_minimum_free_heap_size());
     if( esp_get_minimum_free_heap_size() < HEAP_MIN_WARNING)data->logger->error(F("HEAP: %l"),esp_get_minimum_free_heap_size());
     //data->logger->notice("measure stack: %d",uxTaskGetStackHighWaterMark(NULL));
-    if (uxTaskGetStackHighWaterMark(NULL) < STACK_MIN_WARNING ) data->logger->error("measure stack");
+    if (uxTaskGetStackHighWaterMark(NULL) < STACK_MIN_WARNING ) data->logger->error("measure stack"); //check memory collision
   }
 };
 

platformio/stima_v3/stimawifi/src/measure_thread.h

@@ -3,7 +3,7 @@
 #ifndef MEASURE_THREAD_H_
 #define MEASURE_THREAD_H_
 
-struct measure_data_t {
+struct measure_data_t {    // thread communication data
   int id;
   frtosLogging* logger;
   Queue* mqttqueue;

platformio/stima_v3/stimawifi/src/publish_thread.cpp

@@ -266,7 +266,7 @@ void publishThread::archive() {
   }else{
     data->logger->error(F("publish dequeue mqtt message"));
   }
- }
+}
 
 // if required connect to the broker, publish maint message, publish constant data messages
 // try to send message to the broker
@@ -401,7 +401,7 @@ void publishThread::Run() {
     //data->logger->notice(F("HEAP: %l"),esp_get_minimum_free_heap_size());
     if( esp_get_minimum_free_heap_size() < HEAP_MIN_WARNING)data->logger->error(F("HEAP: %l"),esp_get_minimum_free_heap_size());
     //data->logger->notice("stack publish: %d",uxTaskGetStackHighWaterMark(NULL));
-    if( uxTaskGetStackHighWaterMark(NULL) < STACK_MIN_WARNING )data->logger->error(F("publish stack"));
+    if( uxTaskGetStackHighWaterMark(NULL) < STACK_MIN_WARNING )data->logger->error(F("publish stack"));  // check for memory collision
   }
 };
 

platformio/stima_v3/stimawifi/src/publish_thread.h

@@ -6,7 +6,7 @@
 #ifndef PUBLISH_THREAD_H_
 #define PUBLISH_THREAD_H_
 
-
+// thread exchange data struct
 struct publish_data_t {
   int id;
   frtosLogging* logger;