Add struct-based NVS storage for ESPHome compatibility

[Copilot]

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.

[balloob]

Would it be preferred to write NVS storage over Improv? The downside is that we will not be able to scan for Wifi networks.

[jesserockz]

Would it be preferred to write NVS storage over Improv? The downside is that we will not be able to scan for Wifi networks.

In certain cases yes, this came up when discussing how to compile firmware on a different (cloud hosted) server without passing through your secrets to the builder. This would allow for the build to be clean, then utilize your own browser to embed the wifi and api encryption key into the nvs partition before flashing.

It was less for general purpose web tools flashing and more for personal usage.

Edit: Maybe this repo was not the best place to put something like this? maybe esptool.js could do with this feature directly?