jgauchia · jgauchia · Jun 1, 2025 · Jun 1, 2025 · Jun 1, 2025 · Jun 1, 2025
diff --git a/.gitignore b/.gitignore
@@ -7,3 +7,6 @@
 assets
 tools/*.raw
 tools/*.png
+features.json
+tile_generator.py
+tile_viewer.py
diff --git a/README.md b/README.md
@@ -22,7 +22,7 @@ ESP32 Based GPS Navigator (LVGL - LovyanGFX).
 
 ## Screenshots
 
-|<img src="images/dev/splash.png">|<img src="images/dev/compass.jpg">|<img src="images/dev/rendermap.jpg">|<img src="images/dev/satelliteinfo.jpg">|
+|<img src="images/dev/splash.png">|<img src="images/dev/compass.jpg">|<img src="images/dev/mapnav.jpg">|<img src="images/dev/satelliteinfo.jpg">|
 |:-:|:-:|:-:|:-:|
 
 <details><summary>See more...</summary>
@@ -148,43 +148,29 @@ On SD Card map tiles (256x256 PNG Format) should be stored, in these folders str
                               |__________________ [ 📁 tile X folder (number) ]
                                                              |_______________________ 🗺️ tile Y file.png
 
-## SD Vectorized Map File structure          
+## SD Vectorized Map File structure 
 
-Using [OSM_Extract](https://github.com/aresta/OSM_Extract) you can generate binary map files to later create vector maps. Once generated, these files should be saved in the `mymap` folder on the SD card.
+Vectorized maps for IceNav can be generated using the Tile-Generator utility, which is available on GitHub at [jgauchia/Tile-Generator](https://github.com/jgauchia/Tile-Generator). This script allows you to convert map data into the required vector tile format compatible with IceNav. Please refer to the Tile-Generator repository for detailed instructions and usage examples on generating and preparing your own vector map files.
 
-The PBF files can be downloaded from the [geofabrik](https://download.geofabrik.de/) website.
+      [ 📁 VECTMAP ]
+            |________ [ 📁 zoom folder (number) ]
+                                 |__________________ [ 📁 tile X folder (number) ]
+                                                                |_______________________ 🗺️ tile Y file.bin
 
-The PBF files should be saved in the `pbf` directory. Once saved, you should select the region or boundaries for which the GeoJSON files will be generated.
+## Mass Copy Script for Map Tiles
 
-To obtain the boundaries use `osmconvert file.pbf --out-statistics`:
-```
-lon min: -5.5203154
-lon max: 11.7825360
-lat min: 35.2703341
-lat max: 44.4078541
-```
-
-or use [Bboxfinder](http://bboxfinder.com/) website drawing a box on desired area.
-
-
-For generate GeoJSON files run inside `scripts` directory:
+For efficient transfer of millions of map tiles to SD cards or external storage devices, IceNav includes a high-performance mass copy script. This script is optimized for copying large numbers of small files (such as map tiles) and can reduce transfer time from hours to minutes.
 
-```bash
-min_lon=123
-min_lat=123
-max_lon=123
-max_lat=123
-
-./pbf_to_geojson.sh $min_lon $min_lat $max_lon $max_lat /pbf/clipped.pbf /maps/test
-```
+**Key features:**
+- ✅ **Optimized for millions of small files** - Much faster than traditional copy methods
+- ✅ **Real-time progress monitoring** - See exactly what's being copied
+- ✅ **Resumable transfers** - Continue interrupted copies
+- ✅ **Built-in integrity verification** - Sample file verification
+- ✅ **Performance metrics** - Speed and time statistics
 
-For generate binary map files run inside `scripts` directory.
-```bash
-./extract_features.py $min_lon $min_lat $max_lon $max_lat /maps/test
-```
-Once the process is completed, the maps will be inside the `maps/mymap` directory. Copy all folders to the SD card except the `test_imgs` directory into `VECTMAP` folder of the SD Card.
+For detailed instructions on how to use the mass copy script, please refer to the [Mass Copy Tools Documentation](tools/mass_copy/README.md).
 
-Please follow the instructions provided by [OSM_Extract](https://github.com/aresta/OSM_Extract) for any further questions.
+Download link: [tools/mass_copy/rsync_copy.sh](tools/mass_copy/rsync_copy.sh)
 
 ## Firmware install
 
@@ -244,7 +230,7 @@ Please follow the instructions provided by [OSM_Extract](https://github.com/ares
 
 ## CLI
 
-IceNav has a basic CLI accessible via Serial and optionally via Telnet if enabled. When you access the CLI and type `help`, you should see the following commands:
+IceNav has a basic CLI accessible via Serial and optionally via Telnet if enabled (port 11000). When you access the CLI and type `help`, you should see the following commands:
 
 ```bash
 clear:          clear shell
@@ -268,12 +254,13 @@ Some extra details:
     KEYNAME     DEFINED         VALUE          
     =======     =======         ===== 
     defZoom     custom          17             Default zoom
- fullScrMap     custom          true           Fullscreen map
     vectMap     custom          false          Vectorized map
    mapSpeed     custom          true           Show speed meter in map
    mapScale     custom          true           Show scale meter in map
     mapComp     custom          true           Show compass in map
  mapCompRot     custom          true           Rotate map with the compass
+     simNav     custom          false          Indicates whether navigation simulation mode is enabled or disabled
+   fillPoly     custom          true           Fill polygons in vectorized map
       gpsTX     custom          43             GPS Tx gpio
       gpsRX     custom          44             GPS Rx gpio
      defLAT     custom          52.5200        Default latitude
@@ -338,8 +325,8 @@ To access the Web File Server, simply use any browser and go to the following ad
 - [ ] Multiple IMU's and Compass module implementation
 - [X] Power saving
 - [X] Vector maps
-- [ ] Google Maps navigation style (turn by turn)
-- [x] Optimize code
+- [X] Google Maps navigation style (turn by turn)
+- [X] Optimize code
 - [X] Fix bugs!
 - [X] Web file server
 
@@ -360,8 +347,6 @@ To access the Web File Server, simply use any browser and go to the following ad
 * Improved auto mainScreen selection from env variable preset thanks to [@hpsaturn](https://github.com/hpsaturn)
 * Improved getLat getLon from environment variables thanks to [@hpsaturn](https://github.com/hpsaturn)
 * 3DPrint case for an ESP32S3 Makerfabs Parallel board thanks to [@hpsaturn](https://github.com/hpsaturn)
-* Vectorial Maps routines [ESP32_GPS](https://github.com/aresta/ESP32_GPS) thanks to [@aresta](https://github.com/aresta)
-* OSM to binary vectorial maps [OSM_Extract](https://github.com/aresta/OSM_Extract) thanks to [@aresta](https://github.com/aresta)
 * Preferences Library [Easy Preferences](https://github.com/hpsaturn/easy-preferences) thanks to [@hpsaturn](https://github.com/hpsaturn)
 * Wifi CLI manager [esp32-wifi-cli](https://github.com/hpsaturn/esp32-wifi-cli) thanks to [@hpsaturn](https://github.com/hpsaturn)
 * Web file server based in [@smford](https://github.com/smford) [esp32-asyncwebserver-fileupload-example](https://github.com/smford/esp32-asyncwebserver-fileupload-example)

diff --git a/data/TODO.png b/data/TODO.png
diff --git a/data/mapspeed.bin b/data/mapspeed.bin
diff --git a/data/navarrow.bin b/data/navarrow.bin
diff --git a/data/zoom.bin b/data/zoom.bin
diff --git a/data/zoomin.bin b/data/zoomin.bin
diff --git a/data/zoomout.bin b/data/zoomout.bin
diff --git a/images/dev/mapnav.jpg b/images/dev/mapnav.jpg
diff --git a/images/dev/mapsettings.jpg b/images/dev/mapsettings.jpg
diff --git a/images/dev/rendermap.jpg b/images/dev/rendermap.jpg
diff --git a/images/dev/vectormap.jpg b/images/dev/vectormap.jpg
diff --git a/include/hal.hpp b/include/hal.hpp
@@ -2,8 +2,8 @@
  * @file hal.hpp
  * @author Jordi Gauchía ([email protected])
  * @brief  Boards Pin definitions
- * @version 0.2.2
- * @date 2025-05
+ * @version 0.2.3
+ * @date 2025-06
  */
 
 #pragma once
@@ -122,7 +122,7 @@
   extern const uint8_t TCH_I2C_PORT = 0;  
   extern const uint8_t TCH_I2C_SDA  = GPIO_NUM_38;
   extern const uint8_t TCH_I2C_SCL  = GPIO_NUM_39;
-  extern const uint8_t TCH_I2C_INT  = GPIO_NUM_40;
+  extern const uint8_t TCH_I2C_INT  = -1;
 
   extern const uint8_t SD_CS = GPIO_NUM_4;
   extern const uint8_t SD_MISO = GPIO_NUM_19;

diff --git a/lib/battery/battery.cpp b/lib/battery/battery.cpp
@@ -2,82 +2,88 @@
  * @file battery.cpp
  * @author Jordi Gauchía ([email protected])
  * @brief  Battery monitor definition and functions
- * @version 0.2.2
- * @date 2025-05
+ * @version 0.2.3
+ * @date 2025-06
  */
 
-
 #include "battery.hpp"
 
 /**
- * @brief Battery Class constructor
- *
+ * @brief Constructs a Battery monitoring object for voltage measurement and percentage calculation.
  */
 Battery::Battery() {}
 
 /**
- * @brief Configure ADC Channel for battery reading
+ * @brief Initializes the ADC channel(s) required for battery voltage measurement.
  *
+ * @details Configures the hardware ADC based on the ESP32 chip (ADC1 or ADC2).
  */
 void Battery::initADC()
 {
 #ifdef ADC1
-  adc1_config_width(ADC_WIDTH_BIT_12);
-  adc1_config_channel_atten(BATT_PIN, ADC_ATTEN_DB_12);
+    adc1_config_width(ADC_WIDTH_BIT_12);
+    adc1_config_channel_atten(BATT_PIN, ADC_ATTEN_DB_12);
 #endif
 
 #ifdef ADC2
-  adc2_config_channel_atten(BATT_PIN, ADC_ATTEN_DB_12);
+    adc2_config_channel_atten(BATT_PIN, ADC_ATTEN_DB_12);
 #endif
 }
 
 /**
- * @brief Set battery voltage levels
+ * @brief Sets the maximum and minimum voltage levels for battery charge calculation.
  *
- * @param maxVoltage -> Full Charge voltage
- * @param minVoltage -> Min Charge voltage
+ * @param maxVoltage Voltage considered as fully charged.
+ * @param minVoltage Voltage considered as minimum safe level.
  */
 void Battery::setBatteryLevels(float maxVoltage, float minVoltage)
 {
-  batteryMax = maxVoltage;
-  batteryMin = minVoltage;
+    batteryMax = maxVoltage;
+    batteryMin = minVoltage;
 }
 
 /**
- * @brief Read battery charge and return %.
+ * @brief Reads and computes the current battery charge as a percentage.
+ *
+ * @details Takes 100 ADC samples, averages them, compensates for the voltage divider, and calculates the charge percentage.
+ *          Returns a value between 0 and 100 (values above 160 are treated as 0).
  *
- * @return float -> % Charge
+ * @return float Percentage of battery charge (0–100% typically).
  */
 float Battery::readBattery() 
 {
-  long sum = 0;        // Sum of samples taken
-  float voltage = 0.0; // Calculated voltage
-  float output = 0.0;  // Output value
+    int32_t sum = 0;              /**< Accumulator for ADC samples. */
+    constexpr int samples = 100;  /**< Number of ADC samples. */
+    constexpr float invSamples = 1.0f / samples; /**< Precomputed inverse for averaging. */
+
+    /**< Collect ADC samples */
+    for (int i = 0; i < samples; ++i)
+    {
+        #ifdef ADC1
+            sum += static_cast<int32_t>(adc1_get_raw(BATT_PIN));
+        #endif
+
+        #ifdef ADC2
+            int readRaw;
+            if (adc2_get_raw(BATT_PIN, ADC_WIDTH_BIT_12, &readRaw) == ESP_OK)
+                sum += static_cast<int32_t>(readRaw);
+        #endif
+
+        ets_delay_us(100); /**< Slightly reduced delay for better responsiveness. */
+    }
 
-  for (int i = 0; i < 100; i++)
-  {
-    #ifdef ADC1
-      sum += static_cast<long>(adc1_get_raw(BATT_PIN));
-    #endif
+    /**< Convert ADC value to voltage */
+    float voltage = (sum * invSamples) * (V_REF / 4096.0f); /**< Averaged and scaled ADC voltage. */
 
-    #ifdef ADC2
-      int readRaw;
-      esp_err_t r = adc2_get_raw(BATT_PIN, ADC_WIDTH_BIT_12, &readRaw);
-      if (r == ESP_OK)
-        sum += static_cast<long>(readRaw);
-    #endif
+    /**< Compensate for voltage divider (R1 = R2 = 100kΩ) */
+    voltage *= 2.0f;
 
-    delayMicroseconds(150);
-  }
+    /**< Round to 2 decimal places */
+    voltage = roundf(voltage * 100.0f) * 0.01f;
 
-  voltage = sum / 100.0;
-  // Custom board has a divider circuit
-  constexpr float R1 = 100000.0; // Resistance of R1 (100K)
-  constexpr float R2 = 100000.0; // Resistance of R2 (100K)
-  voltage = (voltage * V_REF) / 4096.0;
-  voltage = voltage / (R2 / (R1 + R2));
-  voltage = roundf(voltage * 100) / 100;
+    /**< Calculate battery percentage */
+    float output = ((voltage - batteryMin) / (batteryMax - batteryMin)) * 100.0f;
 
-  output = ((voltage - batteryMin) / (batteryMax - batteryMin)) * 100;
-  return (output <= 160) ? output : 0.0f;
+    /**< Clamp out-of-range values */
+    return (output <= 160.0f) ? output : 0.0f;
 }
diff --git a/lib/battery/battery.hpp b/lib/battery/battery.hpp
@@ -2,8 +2,8 @@
  * @file battery.hpp
  * @author Jordi Gauchía ([email protected])
  * @brief  Battery monitor definition and functions
- * @version 0.2.2
- * @date 2025-05
+ * @version 0.2.3
+ * @date 2025-06
  */
 
 #pragma once
@@ -12,17 +12,24 @@
 #include <driver/adc.h>
 #include <esp_adc_cal.h>
 
+
+/**
+ * @class Battery
+ * @brief Provides battery voltage monitoring and charge estimation.
+ *
+ * @details Handles ADC initialization, voltage range configuration, and computes battery charge percentage.
+ */
 class Battery
 {
 private:
-  float batteryMax;
-  float batteryMin;
-  static constexpr float V_REF = 3.9; // ADC reference voltage
+	float batteryMax; 					/**< Maximum (full charge) voltage. */
+	float batteryMin;					/**< Minimum (empty) voltage. */
+	static constexpr float V_REF = 3.9; /**< ADC reference voltage. */
 
 public:
-  Battery();
+  	Battery();
 
-  void initADC();
-  void setBatteryLevels(float maxVoltage, float minVoltage);
-  float readBattery();
+	void initADC();
+	void setBatteryLevels(float maxVoltage, float minVoltage);
+	float readBattery();
 };
diff --git a/lib/bme/bme.cpp b/lib/bme/bme.cpp
@@ -2,8 +2,8 @@
  * @file bme.cpp
  * @author Jordi Gauchía ([email protected])
  * @brief  BME280 Sensor functions
- * @version 0.2.2
- * @date 2025-05
+ * @version 0.2.3
+ * @date 2025-06
  */
 
 #include "bme.hpp"
@@ -12,16 +12,13 @@
 
 Adafruit_BME280 bme = Adafruit_BME280();
 
-/**
- * @brief Temperature reading values
- *
- */
-uint8_t tempValue = 0;
-uint8_t tempOld = 0;
+uint8_t tempValue = 0; /**< Stores the current temperature value from the BME280 sensor. */
+uint8_t tempOld = 0; /**< Stores the previous temperature value for comparison. */
 
 /**
- * @brief Init BME sensor
+ * @brief Initializes the BME280 sensor and sets up I2C communication.
  *
+ * @details Optionally allows advanced configuration for oversampling and filtering.
  */
 void initBME()
 {

diff --git a/lib/bme/bme.hpp b/lib/bme/bme.hpp
@@ -2,8 +2,8 @@
  * @file bme.hpp
  * @author Jordi Gauchía ([email protected])
  * @brief  BME280 Sensor functions
- * @version 0.2.2
- * @date 2025-05
+ * @version 0.2.3
+ * @date 2025-06
  */
 
 #pragma once
@@ -15,15 +15,10 @@
 #include <Adafruit_Sensor.h>
 #include <Adafruit_BME280.h>
 
-/**
- * @brief BME280 Address
- *
- */
-#define BME_ADDRESS 0x76
-
-extern Adafruit_BME280 bme;
-extern uint8_t tempValue;
-extern uint8_t tempOld;
+#define BME_ADDRESS 0x76          /**< I2C address for the BME280 sensor (default: 0x76). */
+extern Adafruit_BME280 bme;       /**< Global instance of the BME280 sensor driver. */
+extern uint8_t tempValue;         /**< Stores the latest temperature reading from the BME280 sensor. */
+extern uint8_t tempOld;           /**< Stores the previous temperature value to detect changes. */
 
 void initBME();