Backup
You can save your entire panel configuration as a file and restore it later. You'll find these options in the Settings tab on the Setup page, under the Backup section.
- Export - saves your entire setup (cards, subpages, colours, brightness, screen schedule, display settings, Home Assistant artwork settings, and firmware update preferences) as a file you can keep as a backup.
- Import - loads a previously saved file to restore your setup. If you're loading a backup from a different-sized panel, the cards are rearranged to fit automatically.
Restored presence and screen-schedule sensors reconnect automatically without restarting the display.
Backup files are versioned so newer Basalt releases can keep importing older backups safely. Older version 1 backups still import, and new exports use version 2 while keeping the same readable layout fields for compatibility.
Compatibility Notes
Basalt keeps old saved card strings readable during upgrades. That means cards created before newer card options or compact subpage storage were added should still load, display, and export correctly after an update.
New backup exports continue to use version: 2 with format: "espcontrol.backup". The readable JSON file also includes a native_config section. It records the panel profile, document version, and an encoded copy of the configuration so a firmware version with the native configuration service can restore it exactly. Older panels continue to import the same file through the compatible JSON fields.
When importing a backup from a different-sized panel, Basalt keeps the saved card order where it can and rearranges cards that no longer fit the target screen. Subpages are moved with their parent card when the parent card is kept.
Reset the Display
Open Settings > System > Factory Reset on the Setup page. Choose Save backup to keep a copy of your settings, then choose a reset option and confirm:
- Partial reset removes cards, layouts, subpages, actions, the custom device name and device preferences, while keeping the saved Wi-Fi connection and Home Assistant encryption key. The display restarts into card setup.
- Complete reset also removes saved Wi-Fi credentials and the Home Assistant encryption key. Confirm the reset in the web dialog, then follow the display's first-time setup instructions. Ethernet displays remain accessible through their wired network. Home Assistant may need to be configured again; its integration records and automations are not deleted.
Backups do not restore the display's Wi-Fi login or Home Assistant encryption key. They can still contain passwords saved in Wifi Sharing cards. Both options keep the installed firmware and its built-in defaults. Names, credentials and other settings compiled into a custom ESPHome YAML remain; install stock firmware to restore stock defaults.
The Factory Reset section appears only on firmware that supports it. After reset, reload any other open setup pages before editing. A reset interrupted by power loss resumes at startup. If storage cleanup fails, startup remains paused and the serial log reports Reset recovery; cleanup retries every ten seconds. Do not restore a backup until reset has completed.
Reset clears operational configuration; it is not a forensic secure-erasure feature.
Panel Names in Backups
Custom-named panels include their name and device suffix in backup filenames, for example espcontrol-4-inch-kitchen-b2c3-2026-09-11.json.
When importing a backup with panel naming metadata, Also restore panel name is off by default. Leave it off to keep the destination's name and address. Selecting it copies the name, generates an address using the destination panel's own suffix, and restarts after the configuration restores successfully. The source panel's hardware identity is never copied. Older backups keep the current panel name.
If panel naming is unavailable, export still saves your configuration and warns that the name was omitted. Import still restores the configuration and keeps the destination panel name.