[SD] Refactor diagram, doxygen sd class

brentru · brentru · commit 5b5463cd3317 · 2024-11-18T15:04:03.000-05:00
diff --git a/src/Wippersnapper_V2.h b/src/Wippersnapper_V2.h
@@ -254,13 +254,8 @@ class Wippersnapper_V2 {
 #endif
   bool got_checkin_response; ///< True if a checkin response was received, False
                              ///< otherwise.
-
-  wippersnapper_signal_BrokerToDevice _signalB2dV2;
-  pb_ostream_t _signalStream;
-  size_t _szMessageBuf; // TODO: Delete
-  uint8_t _msgBuf[512]; // TODO: Delete
-  std::vector<std::vector<uint8_t>> _sharedConfigBuffers;
-
+  std::vector<std::vector<uint8_t>>
+      _sharedConfigBuffers; ///< Shared JSON config buffers for offline mode
 private:
   void _initV2();
 
diff --git a/src/components/ds18x20/model.cpp b/src/components/ds18x20/model.cpp
@@ -135,12 +135,6 @@ wippersnapper_ds18x20_Ds18x20Event *DS18X20Model::GetDS18x20EventMsg() {
 /*************************************************************************/
 /*!
     @brief  Encodes a Ds18x20Event message.
-    @param  onewire_pin
-            The OneWire bus' pin where the sensor is located.
-    @param  sensor_events_count
-            The number of sensorevent messages to encode.
-    @param  sensor_events
-            The sensorevent messages to encode.
     @return True if the message was successfully encoded, False otherwise.
 */
 /*************************************************************************/
diff --git a/src/provisioning/sdcard/ws_sdcard.cpp b/src/provisioning/sdcard/ws_sdcard.cpp
@@ -39,9 +39,18 @@ ws_sdcard::ws_sdcard() {
 ws_sdcard::~ws_sdcard() {
   // TODO: Close any open files
   // Then, end the SD card (ends SPI transaction)
-  _sd.end();
+  if (mode_offline) {
+    _sd.end();
+    mode_offline = false;
+  }
 }
 
+/**************************************************************************/
+/*!
+    @brief  Enables logging via a physical RTC to a SD-card, if available.
+            Otherwise, enables logging using millis() timestamps.
+*/
+/**************************************************************************/
 void ws_sdcard::EnableLogging() {
   // Attempt to search for a DS3231 RTC
   WS_DEBUG_PRINTLN("Searching for DS1307 RTC...");
@@ -99,6 +108,14 @@ void ws_sdcard::EnableLogging() {
   }
 }
 
+/**************************************************************************/
+/*!
+    @brief  Searches for and parses the JSON configuration file and sets up
+            the hardware accordingly.
+    @returns True if the JSON file was successfully parsed and the hardware
+             was successfully configured. False otherwise.
+*/
+/**************************************************************************/
 bool ws_sdcard::parseConfigFile() {
   File32 file_config; // TODO: MAke this global?
 #ifndef OFFLINE_MODE_DEBUG
@@ -385,7 +402,14 @@ bool ws_sdcard::parseConfigFile() {
   return true;
 }
 
-// Returns true if input points to a valid JSON string
+/**************************************************************************/
+/*!
+    @brief  Validates a JSON string.
+    @param  input
+            A JSON string to validate.
+    @returns True if the provided JSON string is valid, False otherwise.
+*/
+/**************************************************************************/
 bool ws_sdcard::validateJson(const char *input) {
   JsonDocument doc, filter;
 
@@ -394,8 +418,13 @@ bool ws_sdcard::validateJson(const char *input) {
   return error == DeserializationError::Ok;
 }
 
-// Waits for incoming config file and parses it
-// TODO: Split out parsing into parseConfigFile() and just read here
+/**************************************************************************/
+/*!
+    @brief  Waits for a valid JSON string to be received via the hardware's
+            serial input or from a hardcoded test JSON string.
+    @returns True if a valid JSON string was received, False otherwise.
+*/
+/**************************************************************************/
 bool ws_sdcard::waitForSerialConfig() {
 
   // We provide three ways to use this function:
@@ -525,6 +554,12 @@ bool ws_sdcard::waitForSerialConfig() {
   return true;
 }
 
+/**************************************************************************/
+/*!
+    @brief  Obtains a timestamp from the hardware (or software) RTC.
+    @returns The current timestamp, in unixtime format.
+*/
+/**************************************************************************/
 uint32_t ws_sdcard::GetTimestamp() {
   // Obtain RTC timestamp (TODO - refactor this out)
   DateTime now;
@@ -540,6 +575,14 @@ uint32_t ws_sdcard::GetTimestamp() {
   return now.unixtime();
 }
 
+/**************************************************************************/
+/*!
+    @brief  Converts a SensorType enum to a string.
+    @param  sensorType
+            The SensorType enum to convert.
+    @returns A string representation of the SensorType enum.
+*/
+/**************************************************************************/
 const char *SensorTypeToString(wippersnapper_sensor_SensorType sensorType) {
   switch (sensorType) {
   case wippersnapper_sensor_SensorType_SENSOR_TYPE_UNSPECIFIED:
@@ -621,6 +664,18 @@ const char *SensorTypeToString(wippersnapper_sensor_SensorType sensorType) {
   }
 }
 
+/**************************************************************************/
+/*!
+    @brief  Logs a GPIO sensor event to the SD card.
+    @param  pin
+            The GPIO pin number.
+    @param  value
+            The sensor value.
+    @param  read_type
+            The sensor type.
+    @returns True if the event was successfully logged, False otherwise.
+*/
+/**************************************************************************/
 bool ws_sdcard::LogGPIOSensorEventToSD(
     uint8_t pin, float value, wippersnapper_sensor_SensorType read_type) {
   // Get the pin name in the correct format ("A0", "A1", etc.)
@@ -641,6 +696,18 @@ bool ws_sdcard::LogGPIOSensorEventToSD(
   return true;
 }
 
+/**************************************************************************/
+/*!
+    @brief  Logs a GPIO sensor event to the SD card.
+    @param  pin
+            The GPIO pin number.
+    @param  value
+            The sensor value.
+    @param  read_type
+            The sensor type.
+    @returns True if the event was successfully logged, False otherwise.
+*/
+/**************************************************************************/
 bool ws_sdcard::LogGPIOSensorEventToSD(
     uint8_t pin, uint16_t value, wippersnapper_sensor_SensorType read_type) {
   // Get the pin name in the correct format ("A0", "A1", etc.)
@@ -661,6 +728,18 @@ bool ws_sdcard::LogGPIOSensorEventToSD(
   return true;
 }
 
+/**************************************************************************/
+/*!
+    @brief  Logs a GPIO sensor event to the SD card.
+    @param  pin
+            The GPIO pin number.
+    @param  value
+            The sensor value.
+    @param  read_type
+            The sensor type.
+    @returns True if the event was successfully logged, False otherwise.
+*/
+/**************************************************************************/
 bool ws_sdcard::LogGPIOSensorEventToSD(
     uint8_t pin, bool value, wippersnapper_sensor_SensorType read_type) {
   // Get the pin name in the correct format ("A0", "A1", etc.)
@@ -681,6 +760,18 @@ bool ws_sdcard::LogGPIOSensorEventToSD(
   return true;
 }
 
+/**************************************************************************/
+/*!
+    @brief  Logs a GPIO sensor event to the SD card.
+    @param  pin
+            The GPIO pin number.
+    @param  value
+            The sensor value.
+    @param  read_type
+            The sensor type.
+    @returns True if the event was successfully logged, False otherwise.
+*/
+/**************************************************************************/
 bool ws_sdcard::LogDS18xSensorEventToSD(
     wippersnapper_ds18x20_Ds18x20Event *event_msg) {
   // Get the RTC's timestamp
diff --git a/tests/diagram.json b/tests/diagram.json
@@ -28,31 +28,31 @@
       "rotate": 270,
       "attrs": {}
     },
-    { "type": "wokwi-potentiometer", "id": "pot1", "top": -1.3, "left": 182.2, "attrs": {} },
-    { "type": "wokwi-potentiometer", "id": "pot2", "top": -1.3, "left": 95.8, "attrs": {} },
+    { "type": "wokwi-potentiometer", "id": "pot1", "top": -87.7, "left": 143.8, "attrs": {} },
+    { "type": "wokwi-potentiometer", "id": "pot2", "top": -1.3, "left": 143.8, "attrs": {} },
     {
       "type": "wokwi-pushbutton",
       "id": "btn1",
-      "top": -0.4,
-      "left": 256.4,
+      "top": 9.2,
+      "left": 74,
       "rotate": 270,
       "attrs": { "color": "green" }
     },
-    { "type": "board-ds18b20", "id": "temp1", "top": -145.13, "left": 311.28, "attrs": {} },
+    { "type": "board-ds18b20", "id": "temp1", "top": -87.53, "left": 272.88, "attrs": {} },
     {
       "type": "wokwi-resistor",
       "id": "r1",
-      "top": -52.8,
-      "left": 345.05,
+      "top": 4.8,
+      "left": 277.85,
       "rotate": 90,
       "attrs": { "value": "7400" }
     },
-    { "type": "board-ds18b20", "id": "temp2", "top": -145.13, "left": 167.28, "attrs": {} },
+    { "type": "board-ds18b20", "id": "temp2", "top": -87.53, "left": 234.48, "attrs": {} },
     {
       "type": "wokwi-resistor",
       "id": "r2",
-      "top": -63.8,
-      "left": 191.15,
+      "top": -6.2,
+      "left": 239.15,
       "rotate": 270,
       "attrs": { "value": "7400" }
     }
@@ -66,26 +66,31 @@
     [ "sd1:DO", "esp:D19", "orange", [ "v124.8", "h-125.01" ] ],
     [ "rtc1:SDA", "esp:D21", "blue", [ "v115.2", "h-183.1" ] ],
     [ "rtc1:SCL", "esp:D22", "green", [ "v105.6", "h-163.7" ] ],
-    [ "pot2:SIG", "esp:D27", "green", [ "v19.2", "h143.6" ] ],
+    [ "pot2:SIG", "esp:D27", "green", [ "h-0.4", "v76.8", "h-345.9" ] ],
     [ "esp:3V3", "bb1:bp.1", "red", [ "h-9.6", "v39" ] ],
     [ "sd1:VCC", "bb1:bp.18", "red", [ "v0" ] ],
     [ "rtc1:GND", "bb1:bn.25", "black", [ "v0" ] ],
-    [ "sd1:GND", "bb1:bn.20", "black", [ "v0" ] ],
     [ "esp:GND.1", "bb1:bn.3", "black", [ "v0" ] ],
     [ "bb1:33b.h", "bb1:33b.g", "green", [ "v0" ] ],
     [ "rtc1:5V", "esp:VIN", "red", [ "v-19.2", "h-269.2" ] ],
-    [ "pot1:SIG", "esp:D14", "blue", [ "v67.2", "h-365.2", "v-163.2" ] ],
-    [ "pot2:GND", "bb1:bn.31", "black", [ "v0" ] ],
-    [ "pot2:VCC", "bb1:bn.33", "red", [ "v0" ] ],
-    [ "pot1:GND", "bb1:bn.39", "black", [ "v0" ] ],
-    [ "pot1:VCC", "bb1:bp.41", "red", [ "v0" ] ],
-    [ "btn1:1.l", "esp:D4", "violet", [ "v67.2", "h-451.1" ] ],
-    [ "btn1:2.r", "bb1:bn.46", "black", [ "v-9.8", "h-38.2", "v126.1" ] ],
+    [ "pot1:SIG", "esp:D14", "blue", [ "v9.6", "h-48.4", "v144", "h-316.8", "v-172.8" ] ],
+    [ "btn1:1.l", "esp:D4", "orange", [ "v57.6", "h-268.7" ] ],
     [ "temp1:GND", "bb1:bn.48", "black", [ "v0" ] ],
     [ "temp1:DQ", "r1:1", "green", [ "v0" ] ],
     [ "temp1:VCC", "r1:2", "red", [ "v0" ] ],
-    [ "r1:2", "bb1:bp.50", "red", [ "v56.4", "h-37.6" ] ],
-    [ "r1:1", "esp:D12", "green", [ "v-76.8", "h-557.5" ] ],
+    [ "r1:1", "esp:D12", "green", [ "v-124.8", "h-490.3" ] ],
+    [ "temp2:GND", "bb1:bn.36", "black", [ "v0" ] ],
+    [ "temp2:DQ", "r2:2", "violet", [ "v0" ] ],
+    [ "temp2:VCC", "r2:1", "red", [ "v0" ] ],
+    [ "esp:D25", "r2:2", "violet", [ "v-96", "h412.8" ] ],
+    [ "sd1:GND", "bb1:bn.21", "black", [ "v0" ] ],
+    [ "btn1:2.r", "bb1:tn.31", "black", [ "h9.8", "v-67.3" ] ],
+    [ "pot1:GND", "bb1:tn.32", "black", [ "h-38.4", "v-47.9" ] ],
+    [ "pot1:VCC", "bb1:bp.39", "red", [ "h18.4", "v116.1" ] ],
+    [ "pot2:GND", "bb1:bn.35", "black", [ "v0" ] ],
+    [ "pot2:VCC", "bb1:bp.37", "red", [ "v0" ] ],
+    [ "r2:1", "bb1:bp.44", "red", [ "h0" ] ],
+    [ "r1:2", "bb1:bp.47", "red", [ "h0" ] ],
     [ "esp:VIN", "bb1:4t.a", "", [ "$bb" ] ],
     [ "esp:GND.2", "bb1:5t.a", "", [ "$bb" ] ],
     [ "esp:D13", "bb1:6t.a", "", [ "$bb" ] ],
@@ -128,22 +133,27 @@
     [ "rtc1:SDA", "bb1:33t.a", "", [ "$bb" ] ],
     [ "rtc1:SCL", "bb1:34t.a", "", [ "$bb" ] ],
     [ "rtc1:SQW", "bb1:35t.a", "", [ "$bb" ] ],
-    [ "pot1:GND", "bb1:48b.j", "", [ "$bb" ] ],
-    [ "pot1:SIG", "bb1:49b.j", "", [ "$bb" ] ],
-    [ "pot1:VCC", "bb1:50b.j", "", [ "$bb" ] ],
-    [ "pot2:GND", "bb1:39b.j", "", [ "$bb" ] ],
-    [ "pot2:SIG", "bb1:40b.j", "", [ "$bb" ] ],
-    [ "pot2:VCC", "bb1:41b.j", "", [ "$bb" ] ],
-    [ "btn1:1.l", "bb1:55b.i", "", [ "$bb" ] ],
-    [ "btn1:2.l", "bb1:57b.i", "", [ "$bb" ] ],
-    [ "btn1:1.r", "bb1:55t.d", "", [ "$bb" ] ],
-    [ "btn1:2.r", "bb1:57t.d", "", [ "$bb" ] ],
-    [ "temp2:GND", "bb1:bn.36", "black", [ "v0" ] ],
-    [ "temp2:DQ", "r2:2", "violet", [ "v0" ] ],
-    [ "r2:1", "bb1:49t.b", "", [ "$bb" ] ],
-    [ "temp2:VCC", "r2:1", "red", [ "v0" ] ],
-    [ "r2:1", "bb1:bp.36", "red", [ "v19.2", "h-38.4", "v106.5" ] ],
-    [ "esp:D25", "r2:2", "violet", [ "v-124.8", "h364.8" ] ]
+    [ "pot1:GND", "bb1:44t.c", "", [ "$bb" ] ],
+    [ "pot1:SIG", "bb1:45t.c", "", [ "$bb" ] ],
+    [ "pot1:VCC", "bb1:46t.c", "", [ "$bb" ] ],
+    [ "pot2:GND", "bb1:44b.j", "", [ "$bb" ] ],
+    [ "pot2:SIG", "bb1:45b.j", "", [ "$bb" ] ],
+    [ "pot2:VCC", "bb1:46b.j", "", [ "$bb" ] ],
+    [ "btn1:1.l", "bb1:36b.j", "", [ "$bb" ] ],
+    [ "btn1:2.l", "bb1:38b.j", "", [ "$bb" ] ],
+    [ "btn1:1.r", "bb1:36t.e", "", [ "$bb" ] ],
+    [ "btn1:2.r", "bb1:38t.e", "", [ "$bb" ] ],
+    [ "r1:1", "bb1:58t.c", "", [ "$bb" ] ],
+    [ "r1:2", "bb1:58b.g", "", [ "$bb" ] ],
+    [ "r2:1", "bb1:54b.f", "", [ "$bb" ] ],
+    [ "r2:2", "bb1:54t.b", "", [ "$bb" ] ],
+    [ "temp1:GND", "bb1:55t.a", "", [ "$bb" ] ],
+    [ "temp1:DQ", "bb1:56t.a", "", [ "$bb" ] ],
+    [ "temp1:VCC", "bb1:57t.a", "", [ "$bb" ] ],
+    [ "temp2:GND", "bb1:51t.a", "", [ "$bb" ] ],
+    [ "temp2:DQ", "bb1:52t.a", "", [ "$bb" ] ],
+    [ "temp2:VCC", "bb1:53t.a", "", [ "$bb" ] ],
+    [ "esp:GND.2", "bb1:tn.3", "black", [ "v0" ] ]
   ],
   "serialMonitor": { "display": "terminal", "newline": "lf" },
   "dependencies": {}
