NVSFS.h

Go to the documentation of this file.

/*
 * This is a part of the Uniot project.
 * Copyright (C) 2016-2025 Uniot <contact@uniot.io>
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */

 
#pragma once
 
#ifdef ESP32
 
#include <Bytes.h>
#include <Logger.h>
#include <Preferences.h>
 
namespace uniot {

class NVSFile {
 public:
  NVSFile(const String& path, const String& mode, Preferences& prefs)
      : mKey(path), mMode(mode), mPrefs(prefs), mValid(true) {
    mKey = normalizePath(mKey);
    if (mMode == "r") {
      _loadData();
    } else if (mMode == "w") {
      mBuffer = Bytes();
    } else {
      mValid = false;
    }
  }

  operator bool() const { return mValid; }

  size_t write(const uint8_t* data, size_t size) {
    if (!mValid || mMode != "w") {
      return 0;
    }
 
    mBuffer = Bytes(data, size);
    return size;
  }

  Bytes getBytes() {
    if (!mValid || mMode != "r") {
      return Bytes();
    }
 
    return mBuffer;
  }

  void close() {
    if (!mValid) {
      return;
    }
 
    if (mMode == "w") {
      if (mBuffer.size() == 0) {
        mPrefs.remove(mKey.c_str());
      } else {
        mPrefs.putBytes(mKey.c_str(), mBuffer.raw(), mBuffer.size());
      }
    }
 
    mValid = false;
  }

  static String normalizePath(const String& path) {
    String normalized = path;
    if (normalized.startsWith("/")) {
      normalized = normalized.substring(1);
    }
    if (normalized.length() > 15) {
      normalized = normalized.substring(0, 15);
      UNIOT_LOG_WARN("NVS key truncated to 15 chars: %s", normalized.c_str());
    }
    return normalized;
  }
 
 private:
  String mKey;          
  String mMode;         
  Bytes mBuffer;        
  Preferences& mPrefs;  
  bool mValid;          

  void _loadData() {
    if (!mPrefs.isKey(mKey.c_str())) {
      mBuffer = Bytes();
      return;
    }
 
    size_t dataSize = mPrefs.getBytesLength(mKey.c_str());
    if (dataSize == 0) {
      mBuffer = Bytes();
      return;
    }
 
    mBuffer = Bytes(nullptr, dataSize);
    if (mBuffer.size() != dataSize) {
      UNIOT_LOG_ERROR("NVS read failed, no memory for %u bytes: %s", dataSize, mKey.c_str());
      mBuffer = Bytes();
      return;
    }
 
    // Sized by the buffer, not dataSize, so a buffer that does not match can never be
    // overrun. A short read keeps only what was read: the zero padding left behind would
    // otherwise decode as data.
    auto read = mBuffer.fill([this](uint8_t* buf, size_t size) {
      return mPrefs.getBytes(mKey.c_str(), buf, size);
    });
    mBuffer.prune(read);
  }
};


class NVSFileSystem {
 public:
  NVSFileSystem() : mInitialized(false) {}

  bool begin(bool formatOnFail = false) {
    if (mInitialized) return true;
 
    mInitialized = mPrefs.begin("uniot_files", false);
    if (!mInitialized) {
      UNIOT_LOG_ERROR("failed to open NVS namespace 'uniot_files'");
    }
 
    return mInitialized;
  }

  void end() {
    if (mInitialized) {
      mPrefs.end();
      mInitialized = false;
    }
  }

  NVSFile open(const String& path, const String& mode) {
    if (!mInitialized) {
      UNIOT_LOG_WARN("NVS not initialized");
      return NVSFile("", "", mPrefs);
    }
    return NVSFile(path, mode, mPrefs);
  }

  bool remove(const String& path) {
    if (!mInitialized) {
      return false;
    }
 
    String key = NVSFile::normalizePath(path);
    return mPrefs.remove(key.c_str());
  }
 
 private:
  Preferences mPrefs;  
  bool mInitialized;   
};


extern NVSFileSystem NVSFS;
 
}  // namespace uniot
 
#else
#error "NVSFS is only supported on ESP32. Please define UNIOT_USE_NVSFS=1 for ESP32 projects."
#endif