GS32Config

GS32Config — библиотека для хранения настроек на ESP32 с помощью Preferences.h. Она связывает переменные приложения с ключами в NVS, загружает сохранённые значения, сохраняет изменения и позволяет восстановить значения по умолчанию.

Возможности

• Хранение настроек в NVS через Preferences.
• Регистрация параметров типов bool, int, int8_t, uint8_t и строк в char[].
• Загрузка значений при запуске.
• Сохранение текущих значений переменных.
• Сброс настроек к значениям по умолчанию.
• Работа напрямую с переменными приложения: изменение зарегистрированной переменной меняет значение, которое будет записано при следующем save().

Требования

• Плата на базе ESP32.
• Arduino-ESP32 с поддержкой Preferences.h.
• Файлы GS32Config.h и GS32Config.cpp в папке библиотеки.

📦 Установка

1. Скачайте репозиторий в виде .zip архива.
2. В Arduino IDE перейдите в меню: Скетч ➡️ Подключить библиотеку ➡️ Добавить .ZIP библиотеку...
3. Выберите скачанный архив.

После этого перезапустите Arduino IDE и подключите библиотеку:

#include <GS32Config.h>

Быстрый старт

#include <Arduino.h>
#include <GS32Config.h>

GS32Config config;

char ssid[32];
int channel = 1;
bool dhcpEnabled = true;
int8_t retryCount = 3;
uint8_t authMode = 0;

void setup() {
  Serial.begin(115200);

  // Открыть пространство имён в NVS.
  if (!config.begin("mydevice_cfg")) {
    Serial.println("Не удалось открыть NVS");
    return;
  }

  // Зарегистрировать настройки и их значения по умолчанию.
  config.addText("ssid", ssid, sizeof(ssid), "MyHomeWiFi");
  config.addInt("channel", &channel, 1);
  config.addBool("dhcp", &dhcpEnabled, true);
  config.addInt8("retries", &retryCount, 3);
  config.addUInt8("auth", &authMode, 0);

  // Загрузить сохранённые настройки.
  config.load();

  Serial.printf("SSID: %s\n", ssid);
  Serial.printf("Channel: %d\n", channel);
}

void loop() {
}

Порядок важен: сначала вызовите begin(), затем зарегистрируйте параметры через add...(), после этого вызовите load().

Поддерживаемые типы

Метод	Тип переменной	Значение по умолчанию
addBool(key, pointer, defaultValue)	bool	false
addInt(key, pointer, defaultValue)	int	0
addInt8(key, pointer, defaultValue)	int8_t	0
addUInt8(key, pointer, defaultValue)	uint8_t	0
addText(key, buffer, bufferSize, defaultValue)	char[]	пустая строка

Пример регистрации:

bool enabled;
int interval;
int8_t offset;
uint8_t mode;
char hostname[24];

config.addBool("enabled", &enabled, true);
config.addInt("interval", &interval, 30);
config.addInt8("offset", &offset, -2);
config.addUInt8("mode", &mode, 1);
config.addText("hostname", hostname, sizeof(hostname), "esp32-device");

У ключей Preferences есть ограничения по длине. Используйте короткие уникальные имена ключей, например "ssid", "channel" и "dhcp".

Загрузка и значения по умолчанию

При вызове load() библиотека проверяет каждый зарегистрированный ключ:

• если ключ есть в NVS, сохранённое значение копируется в переменную;
• если ключа нет, используется значение по умолчанию, а значение записывается в NVS.

Значение по умолчанию применяется при первом запуске с этим ключом или после сброса настроек. Изменение значения по умолчанию в исходном коде само по себе не заменит уже сохранённое значение.

Сохранение изменений

Библиотека хранит указатели на зарегистрированные переменные. Поэтому после регистрации можно изменить переменную напрямую, а затем вызвать save():

channel = 12;
config.save();

При следующем запуске load() прочитает 12 из NVS, даже если в коде значение по умолчанию равно 1.

Изменение переменной не сохраняется автоматически. Для записи в NVS необходимо явно вызвать config.save().

Сброс к заводским настройкам

Вызов factoryReset() устанавливает зарегистрированным переменным значения по умолчанию и записывает их в NVS:

config.factoryReset();

После сброса переменные сразу содержат значения по умолчанию, а после перезагрузки эти значения будут загружены из NVS.

Использование с GS32BIOS

Если BIOS вызывает обработчики при сохранении и сбросе, их можно связать с GS32Config:

bios.onSave([]() {
  config.save();
});

bios.onFactoryReset([]() {
  config.factoryReset();
});

Важно, чтобы переменные, зарегистрированные в GS32Config, были теми же переменными, указатели на которые передаются в элементы BIOS:

int channel = 1;

config.addInt("channel", &channel, 1);
bios.addInt("Settings", "Channel", &channel, 1, 60);

Тогда изменение channel через BIOS будет видно библиотеке конфигурации, и вызов config.save() сохранит актуальное значение.

Строковые буферы

Для addText() передавайте размер буфера, а не максимальное число символов без терминатора:

char ssid[32];
config.addText("ssid", ssid, sizeof(ssid), "MyHomeWiFi");

В буфере должно оставаться место для завершающего нулевого символа \\0. Значение, которое длиннее буфера, будет обрезано. После копирования строка должна завершаться нулём.

Если переменная объявлена так:

char ssid[32];

сама декларация без начального значения не гарантирует заполнение массива нулями. При регистрации addText() библиотека устанавливает строковое значение по умолчанию. Если требуется обнулить буфер до регистрации, можно сделать это явно:

char ssid[32] = {};

Не передавайте в addText() нулевой размер буфера.

Целочисленные типы и преобразования

Тип указателя должен соответствовать методу регистрации. Например:

int8_t value;
config.addInt8("value", &value, 0);

Метод addInt() предназначен для int; передавать ему указатель на int8_t нельзя. Это не автоматическое преобразование: тип указателя определяет, сколько байтов библиотека читает из памяти и записывает в неё.

Если требуется сохранить int8_t или uint8_t, используйте соответственно addInt8() или addUInt8(). Не полагайтесь на неявное преобразование между типами при работе с указателями.

При преобразовании значения в более узкий тип возможна потеря данных. Например, значение 300 не помещается в uint8_t. Проверяйте допустимый диапазон перед присваиванием.

Обработка ошибок и ограничения

Проверяйте результат begin() до загрузки или сохранения:

if (!config.begin("mydevice_cfg")) {
  Serial.println("Ошибка инициализации конфигурации");
  return;
}

Preferences использует NVS, поэтому данные сохраняются между перезагрузками и обновлениями прошивки, пока пространство NVS не очищено и ключи продолжают использоваться совместимым образом.

Имена ключей и пространство имён следует считать частью формата конфигурации. Если изменить ключ, библиотека увидит его как новый и применит для него значение по умолчанию.

API

begin()

bool begin(const char* nameSpace = "gs32_cfg");

Открывает указанное пространство имён NVS в режиме чтения и записи. Возвращает результат открытия.

Регистрация параметров

void addBool(const char* key, bool* ptr, bool defaultValue = false);
void addInt(const char* key, int* ptr, int defaultValue = 0);
void addInt8(const char* key, int8_t* ptr, int8_t defaultValue = 0);
void addUInt8(const char* key, uint8_t* ptr, uint8_t defaultValue = 0);
void addText(const char* key, char* ptr, size_t maxLen,
             const char* defaultValue = "");

Добавляет переменную в список настроек и связывает её с ключом NVS.

load()

void load();

Загружает значения из NVS. Для отсутствующих ключей использует значения по умолчанию.

save()

void save();

Записывает текущие значения зарегистрированных переменных в NVS.

factoryReset()

void factoryReset();

Возвращает зарегистрированные переменные к значениям по умолчанию и сохраняет их.

getEntries()

const std::vector<ConfigEntry>& getEntries() const;

Возвращает список зарегистрированных параметров. Предназначен для диагностики и отладки.

Лицензия

Этот проект является частью экосистемы GS32Bios и распространяется под лицензией MIT. Вы можете свободно использовать, модифицировать и распространять данный код в своих некоммерческих и коммерческих проектах.