# FreePocket NVS Diagnostics

Date: 2026-07-12

## Current conclusion

The LittleFS preconfiguration test did not change runtime behavior: the ESP32 still boots in AP mode and does not connect to Wi-Fi `Solax`.

Do not generate more LittleFS variants by trial and error. The next diagnostic target is the ESP-IDF NVS partition.

## Partition table source

FreePocket multipart packages currently use this partition-table artifact:

`/srv/esp-platform/artifacts/14/148b959cbff1c38aa8e1d5c0ba9d612c54997b945e56a63f41223eef650653a1.bin`

Decode command:

```bash
cd /opt/esp-platform/repo
scripts/freepocket-nvs-info.sh
```

Decoded partition table:

| Label | Type | Subtype | Offset | Size |
| --- | --- | --- | --- | --- |
| nvs | data | nvs | `0x9000` | `0x5000` / 20480 bytes |
| otadata | data | ota | `0xE000` | `0x2000` / 8192 bytes |
| app0 | app | ota_0 | `0x10000` | `0x140000` / 1310720 bytes |
| app1 | app | ota_1 | `0x150000` | `0x140000` / 1310720 bytes |
| spiffs | data | spiffs | `0x290000` | `0x160000` / 1441792 bytes |
| coredump | data | coredump | `0x3F0000` | `0x10000` / 65536 bytes |

## NVS read workflow through Flasher Web

Use `https://iot.aeizoon.com/flasher` from Chrome or Edge on the Mac. The Mac is only the physical USB/browser endpoint; the project tooling remains on the VM.

Use 115200 baud for this ESP32 board because previous validation showed it is stable while 921600 can lose the flash connection.

The ESP32 must be connected in bootloader/flashing mode before reading if auto-reset does not work with the USB-TTL wiring.

Steps for the first dump:

1. Open `https://iot.aeizoon.com/flasher`.
2. Set baudrate to `115200`.
3. Click `Connect ESP32` and authorize the USB-TTL serial port.
4. Open `Advanced`.
5. Click `FreePocket NVS`.
6. Confirm:
   - Offset: `0x9000`
   - Size: `0x5000`
   - Suggested filename: `freepocket-nvs-before.bin`
7. Click `Read and download .bin`.

After configuring the device manually with:

- Wi-Fi SSID: `Solax`
- Wi-Fi password value is not included
- Web user: `admin`
- Web password value is not included

repeat the read, using suggested filename:

`freepocket-nvs-after-solax-admin.bin`

The Flasher Web operation uses esptool-js `readFlash` through the current Web Serial connection and is read-only; it does not modify flash bytes.

## Move dumps to the VM

From the Mac, after downloading the two files:

```bash
scp ~/Downloads/freepocket-nvs-before.bin ~/Downloads/freepocket-nvs-after-solax-admin.bin codex@192.168.1.62:/opt/esp-platform/repo/diagnostics/nvs/
```

## Analyze with Espressif tools

Official parser installed in the VM:

`/opt/esp-platform/tools/esp-idf/components/nvs_flash/nvs_partition_tool/nvs_tool.py`

Repo links:

- `tools/nvs-diagnostics/nvs_partition_tool`
- `tools/nvs-diagnostics/nvs_partition_generator`

Espressif documentation states that `nvs_tool.py` parses NVS storage partitions, lists namespaces, entries, blobs/strings, and can run integrity checks. It does not decrypt encrypted NVS partitions.

Analyze one dump:

```bash
cd /opt/esp-platform/repo
scripts/analyze-nvs-dump.sh diagnostics/nvs/freepocket-nvs-before.bin
scripts/analyze-nvs-dump.sh diagnostics/nvs/freepocket-nvs-after-solax-admin.bin
```

Compare before/after:

```bash
cd /opt/esp-platform/repo
scripts/compare-nvs-dumps.sh \
  diagnostics/nvs/freepocket-nvs-before.bin \
  diagnostics/nvs/freepocket-nvs-after-solax-admin.bin
```

The comparison generates:

- `storage_info.txt`
- `namespaces.txt`
- `written.txt`
- `minimal.txt`
- `blobs.txt`
- `all.json`
- `hexdump.txt`
- `minimal.diff`
- `written.diff`
- `blobs.diff`
- `changed-ranges.txt`

## Static findings before NVS dump

LittleFS/static web content contains form fields and default JSON-like values for:

- `WIFI_SSID`
- `WIFI_PASSWORD`
- `WIFI_isValid`
- `WEB_USERNAME`
- `WEB_PASSWORD`
- `MAINTAIN_CONFIG`
- `MQTT_PASSWORD`
- `MQTT_SOLAX_ENABLED`
- `SOLAX_WIFI_SERIAL_NUMBER`

The application binary contains strings related to ESP-IDF NVS and Wi-Fi persistence, including:

- `WIFI_STA_DEF`
- `WIFI_AP_DEF`
- `ap.ssid`
- `ap.passwd`
- `bssid.set`
- `esp_phy_load_cal_data_from_nvs`
- NVS error symbols such as `ESP_ERR_NVS_NOT_FOUND`, `ESP_ERR_WIFI_NVS`, `ESP_ERR_NVS_NO_FREE_PAGES`

Interpretation:

- LittleFS likely provides UI defaults/static configuration material.
- Runtime effective Wi-Fi state may be persisted in NVS by ESP-IDF Wi-Fi and/or by FreePocket application namespaces.
- The exact source of truth must be determined from before/after NVS dumps, not inferred from strings alone.

## Open questions for the dump analysis

When both dumps are available, identify:

- NVS namespaces present before and after configuration.
- New or changed keys after setting Wi-Fi and web credentials.
- Whether Wi-Fi credentials are stored under ESP-IDF Wi-Fi namespaces or FreePocket application namespaces.
- Whether values are plain strings, blobs, integers, or structured serialized records.
- Whether flags such as Wi-Fi enabled/valid/configured change independently from SSID/password.
- Whether NVS integrity check reports valid pages and entries.
- Whether NVS encryption is absent or present.

## Do not implement yet

Do not modify firmware, generate NVS images, or add automatic NVS provisioning until the before/after NVS format is understood.