Skip to content

Add struct-based NVS storage for ESPHome compatibility#684

Draft
Copilot wants to merge 8 commits intomainfrom
copilot/add-form-structure-for-nvs
Draft

Add struct-based NVS storage for ESPHome compatibility#684
Copilot wants to merge 8 commits intomainfrom
copilot/add-form-structure-for-nvs

Conversation

Copy link

Copilot AI commented Feb 19, 2026

ESPHome stores preferences using numeric hash keys with binary structs, not individual string-keyed entries. The initial implementation stored WiFi credentials as separate "ssid" and "password" keys, which doesn't match ESPHome's global_preferences->make_preference<T>(hash) API.

Changes

NVS Builder (src/nvs-partition-builder.ts)

  • Added BLOB type support for binary data storage
  • Implemented packStruct() to pack multiple fields into C struct layout
  • Support numeric keys (converted to strings for NVS storage)
  • Export packStruct() for reuse

Manifest Schema (src/const.ts)
Extended NVSPartitionConfig with two storage modes:

struct?: {
  key: number;          // ESPHome preference hash (e.g., 88491487)
  fields: Array<{
    name: string;       // Form field to pack
    type: "u8" | "u16" | "u32" | "string";
    maxLength?: number; // Fixed buffer size for strings
  }>;
};

fields?: Array<{       // Legacy mode for individual entries
  name: string;
  key: string;
  type: "u8" | "u16" | "u32" | "string";
}>;

Install Flow (src/install-dialog.ts)

  • Pack form values into binary struct when nvsPartition.struct is defined
  • Convert boolean form values to numbers for numeric struct fields
  • Support both struct and individual field modes

Usage

ESPHome WiFi credentials (correct format):

{
  "customFields": [
    { "name": "wifi_ssid", "label": "WiFi SSID", "type": "text", "required": true },
    { "name": "wifi_password", "label": "WiFi Password", "type": "password", "required": true }
  ],
  "nvsPartition": {
    "offset": 36864,
    "namespace": "esphome",
    "struct": {
      "key": 88491487,
      "fields": [
        { "name": "wifi_ssid", "type": "string", "maxLength": 33 },
        { "name": "wifi_password", "type": "string", "maxLength": 65 }
      ]
    }
  }
}

Matches ESPHome's SavedWifiSettings struct:

struct SavedWifiSettings {
  char ssid[33];
  char password[65];
} PACKED;

The fields mode remains available for non-ESPHome use cases requiring individual NVS entries.


✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Copilot AI and others added 4 commits February 19, 2026 03:21
- Created NVS partition builder module with ESP32 NVS format support
- Extended Manifest interface with customFields and nvsPartition properties
- Added CONFIGURATION state to install dialog
- Implemented configuration form rendering with text, password, number, and checkbox fields
- Integrated NVS partition generation into flash process
- Configuration values are collected from form and used to build NVS partition
- NVS partition is flashed alongside firmware at specified offset

Co-authored-by: jesserockz <3060199+jesserockz@users.noreply.github.com>
- Created comprehensive NVS_CONFIGURATION.md documentation
- Added example manifest with configuration fields
- Updated README with feature overview

Co-authored-by: jesserockz <3060199+jesserockz@users.noreply.github.com>
- Fix NVS key length handling to support full 15-character keys
- Remove unnecessary blank line in install-dialog.ts
- Update test file to use relative path for manifest
- Improve test documentation

Co-authored-by: jesserockz <3060199+jesserockz@users.noreply.github.com>
Co-authored-by: jesserockz <3060199+jesserockz@users.noreply.github.com>
Copilot AI changed the title [WIP] Add a way to define form structure for NVS configuration Add browser-based NVS partition builder with configuration forms Feb 19, 2026
Copilot AI requested a review from jesserockz February 19, 2026 03:32
Copilot AI and others added 3 commits February 19, 2026 03:51
- Add blob type support to NVS partition builder
- Implement packStruct() function for binary struct packing
- Update manifest schema to support struct-based storage with numeric keys
- Add struct configuration option alongside individual fields
- Update buildESPHomeWiFiNVS() to use correct struct format
- Add example-esphome-wifi.json with proper ESPHome configuration
- Update documentation to explain struct vs individual field storage
- Handle boolean to number conversion for struct fields

Co-authored-by: jesserockz <3060199+jesserockz@users.noreply.github.com>
- Fix incomplete JSON in documentation
- Improve boolean-to-number conversion to explicitly check numeric types
- Add test functions for struct packing
- Add ESPHome WiFi struct test
- Add packStruct() export to test page

Co-authored-by: jesserockz <3060199+jesserockz@users.noreply.github.com>
- Document blob type and struct packing features
- Update manifest schema examples with both modes
- Add ESPHome WiFi struct example with firmware integration
- Document version changes and ESPHome compatibility fix
- Update testing section with struct tests

Co-authored-by: jesserockz <3060199+jesserockz@users.noreply.github.com>
Copilot AI changed the title Add browser-based NVS partition builder with configuration forms Add struct-based NVS storage for ESPHome compatibility Feb 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants

Comments