examples, docs

Author: fabianoriccardi

examples/esp_logger/esp_logger.ino

@@ -1,67 +1,68 @@
+/**
+ * Log on flash memory an event every 1.5 seconds. Every 30 seconds,
+ * the log file is flushed over serial port.
+ *
+ * NOTE: the first time you run this sketch or when changing the file system
+ *       layout, explicit formatting is recommended.
+ */
 #include <Ticker.h>
 #include <logger_spiffs.h>
 
+// Specify the path where the log is placed
 LoggerSPIFFS myLog("/log/mylog.log");
 
-/** 
- * Event generation and management 
- */
-
 // Event generator, this could be implemented in the main loop
 Ticker somethingHappens;
 
-// in seconds
-float eventFrequency = 1.5;
+// Event generation period, in seconds
+float eventPeriod = 1.5;
 
-// This is the variable event to log
+// Variable to be logged
 int counter = 0;
 
 void somethingHappening(){
   counter++;
 
   // counter is a multiple of 3, log it!
   if(counter%3==0){
-    Serial.println(String("Oh, ->") + counter + "<- is just happened");
-    myLog.append(String("val:") + counter);
+    Serial.println(String("Hey, event ->") + counter + "<- is just happened");
+    String record = String("val:") + counter;
+    myLog.append(record.c_str());
   }
-  somethingHappens.attach(eventFrequency, somethingHappening);
 }
 
 void setup() {
   Serial.begin(115200);
   while(!Serial);
+  Serial.println();
+  Serial.println("ESP Logger - Log on internal flash memory");
 
-  Serial.println("Basic log example");
-
-  Serial.print("Initializing SD card... ");
-  if(!myLog.begin()){
-    Serial.println("Failed!");
-    while(1) delay(100);
-  }else{
-    Serial.println("Done!");
-  }
+  myLog.begin();
   myLog.setFlusherCallback(senderHelp);
-  somethingHappens.attach(eventFrequency, somethingHappening);
+
+  Serial.println("Starting to log...");
+  somethingHappens.attach(eventPeriod, somethingHappening);
 }
 
-// in millisecond
+// flush period, in millisecond
 int period = 30000;
 
 unsigned int nextTime = 0;
 
-// This loop is the logger controller, it decides when it's time to flush
-// You can see a more elegant management in other examples. 
+
 void loop() {
+  // This loop is the logger controller, it decides
+  // when it's time to flush. In other examples I will use Ticker library. 
   if (millis()>nextTime){
     nextTime += period;
     myLog.flush();
   }
 }
 
 /**
- * Callback to support the flushing.
- * In this case the flushing is performed on the Serial interface,
- * but you can easily replace this to send data over wireless network 
+ * Flush a chuck of logged records. To exemplify, the records are
+ * flushed on Serial, but you are free to modify it to send data
+ * over the network.
  */
 bool senderHelp(char* buffer, int n){
   int index=0;

examples/esp_logger_runtime/esp_logger_runtime.ino

@@ -1,62 +1,60 @@
 #include <logger_spiffs.h>
 #include <logger_routine.h>
 
-// in second
+// flush period, in second
 const int period = 30;
 // Path where the log is placed
 const String filepath = "/log/mylog.log";
 
 LoggerSPIFFS myLog(filepath);
 
-// This class takes care of flushing the log file every period 
+// This class takes care of flushing the log file every "period"
 LoggerRoutine logRun(myLog, period);
 
-
-/** 
- * Event generation and management 
- */
-
 // Event generator, this could be implemented in the main loop
 Ticker somethingHappens;
 
-// in seconds
-float eventFrequency = 1.5;
+// Event generation period, in seconds
+float eventPeriod = 1.5;
 
-// This is the variable event to log
+// Variable to be logged
 int counter = 0;
 
 void somethingHappening(){
   counter++;
 
-  // counter is a multiple of 4, log it!
+  // counter is a multiple of 3, log it!
   if(counter%3==0){
-    Serial.println(String("Oh, ->") + counter + "<- is just happened");
+    Serial.println(String("Hey, event ->") + counter + "<- is just happened");
     myLog.append(String("val:") + counter);
     Serial.println(String("Now the log takes ") + myLog.getActualSize() + "/" + myLog.getSizeLimit());
   }
-  somethingHappens.attach(eventFrequency, somethingHappening);
 }
 
 void setup() {
   Serial.begin(115200);
   while(!Serial);
-  Serial.println("Log on SPIFFS example");
+  Serial.println();
+  Serial.println("ESP Logger - Log on internal flash memory (with logger routine)");
 
   myLog.begin();
-  myLog.setSizeLimit(1000, false);
+  myLog.setSizeLimit(1000);
   myLog.setSizeLimitPerChunk(60);
   myLog.setFlusherCallback(senderHelp);
-  somethingHappens.attach(eventFrequency, somethingHappening);
-
+  
+  Serial.println("Starting to log...");
+  somethingHappens.attach(eventPeriod, somethingHappening);
   logRun.begin(true);
 }
 
 void loop() {}
 
 /**
- * Callback to support the flushing.
- * In this case the flushing is performed on the Serial interface, but you can easily 
- * replace this behaviour with a wireless connection or whatever function. 
+ * Flush a chuck of logged records. To exemplify, the records are
+ * flushed on Serial, but you are free to modify it to send data
+ * over the network.
+ *
+ * NOTE: This example simulates a channel that sometimes may fail.
  */
 bool senderHelp(char* buffer, int n){
   static int failPacketCounter = 0;

examples/esp_logger_runtime_sd/esp_logger_runtime_sd.ino

@@ -5,54 +5,46 @@
 // othewise you can call the method begin(..) (only for ESP32)
 #include <SD.h>
 
-#ifdef ESP8266 
-const int csPin = D4;
-#else
-const int csPin = 16;
-#endif
+// Specify CS (chip select) pin
+const int csPin = 5;
 
-// in seconds
+// flush period, in seconds
 const int period = 30;
-
+// Path where the log is placed
 const String filepath = "/myLog.log";
 
 LoggerSD myLog(filepath);
 
-// This class takes care to flush "myLog" object every period 
+// This class takes care to flush "myLog" object every "period" 
 LoggerRoutine myLogRun(myLog, period);
 
-
-/** 
- * Event generation and management 
- */
-
 // Event generator, this could be implemented in the main loop
 Ticker somethingHappens;
 
-// in seconds
-float eventFrequency = 1.5;
+// Event generation period, in seconds
+float eventPeriod = 1.5;
 
-// This is the variable event to myLog
+// Variable to be logged
 int counter = 0;
 
 void somethingHappening(){
   counter++;
 
-  // counter is a multiple of 4, myLog it!
+  // counter is a multiple of 3, myLog it!
   if(counter%3==0){
-    Serial.println(String("Oh, ->") + counter + "<- is just happened");
+    Serial.println(String("Hey, event ->") + counter + "<- is just happened");
     myLog.append(String("val:") + counter);
     Serial.println(String("Now the log takes ") + myLog.getActualSize() + "/" + myLog.getSizeLimit());
   }
-  somethingHappens.attach(eventFrequency, somethingHappening);
 }
 
 void setup() {
   Serial.begin(115200);
   while(!Serial);
   Serial.println();
-  Serial.println("Log on SD Example");
+  Serial.println("ESP Logger - Log on SD  (with logger routine)");
 
+  // Check if the microSD is connected
   Serial.print("Initializing SD card... ");
   if (!SD.begin(csPin)) {
     Serial.println("Failed!");
@@ -62,23 +54,23 @@ void setup() {
 
   // Effectively working only on ESP32
   myLog.begin(csPin);
-  
-  myLog.setSizeLimit(1000, false);
+  myLog.setSizeLimit(1000);
   myLog.setSizeLimitPerChunk(60);
   myLog.setFlusherCallback(senderHelp);
-  somethingHappens.attach(eventFrequency, somethingHappening);
-
+  
+  Serial.println("Starting to log...");
+  somethingHappens.attach(eventPeriod, somethingHappening);
   myLogRun.begin(true);
 }
 
 void loop() {}
 
 /**
- * Callback implementing the log flushing.
- * In this case log flushing is performed on the Serial interface, but you can easily 
- * write your own implementation for Wifi connection. 
- * 
- * NOTE: This example simulates a channel failure.
+ * Flush a chuck of logged records. To exemplify, the records are
+ * flushed on Serial, but you are free to modify it to send data
+ * over the network.
+ *
+ * NOTE: This example simulates a channel that sometimes may fail.
  */
 bool senderHelp(char* buffer, int n){
   static int failPacketCounter = 0;

readme.md

@@ -29,21 +29,21 @@ There are 2 main functions to be aware of: *append* and *flush*.
 
 #### Append
 
-    bool append(String data)
+    bool append(const char* record)
 
-it creates and stores a *Record* containing the input data. You cannot log data containing non-printable characters, nor new line or carriage return. Return true if the data is saved, false otherwise.
+it creates and stores a *Record*. You cannot log data containing non-printable characters, nor new line or carriage return. Return true if the data is saved, false otherwise.
 
 #### Flush
 
     bool flush()
 
 it calls your callback function which has the following prototype:
 
-    bool flusher(char* buffer, int n);
+    bool flusher(char* chunk, int n);
 
-where char* is a buffer that contains one or more records, *n* tells how many bytes is long this buffer. This function should return true is the buffer flush has succeeded, false otherwise (e.g. the server wasn't reachable). If true, the library deletes the flushed data and, if other data are available, it calls flusher() again, otherwise it stops. If false, the library stops the flushing process and preserves the unflushed data for the next flush(). 
+where *chunk* is a buffer that contains one or more records separated by '\0' char; *n* tells how many bytes is long the chunk, including '\0'. This function must return true is the buffer flush has succeeded, false otherwise (e.g. the server wasn't reachable). If true, the library deletes the flushed data and, if other data are available, it calls flusher() again, otherwise it stops. If false, the library stops the flushing process and preserves the unflushed data for the next flush().
 
-This kind of packetization can be useful in various scenarios, especially when the log is very large and you cannot send everything in one shot. The max buffer size can be arbitrarily set at run-time, though a dedicated method.
+This kind of packetization can be useful in various scenarios, especially when the log is very large and you cannot send everything in one shot. The maximum size of a chunk can be set at run-time through *setSizeLimitPerChunk()*.
 
 Please note that the flush() method guarantees that: