Backup & Restore

Import, export, and automatically backup your entity configurations

The Home Assistant Plasmoid includes import/export functionality to backup and restore your entity configurations. This allows you to easily migrate settings between systems, recover from configuration errors, or share configurations.

Accessing Backup Options

The backup menu is located in the Items configuration page:

1. Right-click the plasmoid widget
2. Select Configure Home Assistant…
3. Navigate to the Items tab
4. Click the menu button (≡) at the bottom right (ConfigItems.qml:38-41)

The backup menu expands to show import, export, and auto-backup options.

Exporting Configurations

1. Step 1: Open the Backup Menu
2. Click the menu button at the bottom of the Items configuration page.
3. Step 2: Click Export
4. Click the Export button (ConfigItems.qml:58-64).
5. Step 3: Choose Save Location
6. A file dialog opens:
8. Step 4: Save the File
9. Click Save to create the backup file.

The exported file contains all configured entities in JSON format, including:

• Entity IDs
• Custom names and icons
• Display attribute settings
• Click and scroll actions
• Notification preferences

The Export button is only enabled when you have at least one entity configured (ConfigItems.qml:62).

Importing Configurations

1. Step 1: Open the Backup Menu
2. Click the menu button at the bottom of the Items configuration page.
3. Step 2: Click Import
4. Click the Import button (ConfigItems.qml:49-56).
5. Step 3: Select Backup File
6. A file dialog opens:
8. Step 4: Confirm Import
9. Click Open to import the configuration.

Importing replaces all current entities. Your existing entity configuration will be completely replaced with the imported configuration. Export your current setup first if you want to keep it.

Import Process

When you import a configuration (ConfigItems.qml:52-54):

1. The backup file is read
2. Current entities are cleared
3. Entities from the backup are loaded
4. Configuration is automatically saved

The imported entities appear immediately in the entity list and the plasmoid widget.

The .hapi File Format

Backup files use the .hapi extension (Home Assistant Plasma Items) and contain JSON data.

File Structure

The file contains a JSON array of entity configurations:

[
  {
    "entity_id": "light.living_room",
    "name": "Living Room",
    "icon": "mdi:ceiling-light",
    "default_action": {
      "service": "light.toggle",
      "domain": "light",
      "target": { "entity_id": "light.living_room" }
    },
    "scroll_action": {
      "service": "light.turn_on",
      "domain": "light",
      "target": { "entity_id": "light.living_room" },
      "data_field": "brightness"
    }
  },
  {
    "entity_id": "sensor.temperature",
    "name": "Temp",
    "attribute": "temperature",
    "notify": true
  }
]

Data Format

The JSON format (ConfigItems.qml:207):

• Null and undefined values are omitted
• Only defined properties are included
• Entity order is preserved

.hapi files are human-readable JSON. You can manually edit them with a text editor if needed, but be careful to maintain valid JSON syntax.

Auto-Backup Configuration

The plasmoid can automatically backup your configuration to a file every time settings are saved.

1. Step 1: Open the Backup Menu
2. Click the menu button at the bottom of the Items configuration page.
3. Step 2: Configure Auto Backup File
4. In the Auto backup section (ConfigItems.qml:67-84):
6. Step 3: Apply Configuration
7. Click Apply in the configuration dialog.

How Auto-Backup Works

When auto-backup is configured (ConfigItems.qml:231-234):

• Every time you click Apply in the configuration dialog, the current entity configuration is written to the auto-backup file
• The backup file is automatically updated whenever you:
  • Add a new entity
  • Edit an entity
  • Remove an entity
  • Reorder entities

Auto-backup only triggers when you click Apply or OK in the configuration dialog. Changes are not backed up until explicitly saved.

Disabling Auto-Backup

To disable auto-backup:

1. Click the clear button (×) in the auto backup field (ConfigItems.qml:77-81)
2. The auto-backup file path is cleared
3. Click Apply

Auto-backup stops, but your existing backup file is not deleted.

Use Cases

Migrating to a New System

1. Export your configuration on the old system
2. Copy the .hapi file to the new system
3. Install the plasmoid on the new system
4. Configure the Home Assistant connection
5. Import the .hapi file

Configuration Backup Before Changes

1. Export your current configuration
2. Make experimental changes
3. If something goes wrong, Import the backup to restore

Sharing Configurations

1. Export your configuration
2. Share the .hapi file with other users
3. They can Import it to replicate your setup

When sharing configurations, remember that entity IDs must match between Home Assistant instances. Recipients may need to edit imported entity IDs to match their setup.

Regular Backups with Auto-Backup

1. Configure Auto backup to a file in your documents folder
2. Include that folder in your regular system backups
3. Your plasmoid configuration is automatically backed up with your system

Data Storage

Entity configurations are stored in two places:

1. Plasmoid configuration: The cfg_items property stores the current configuration (ConfigItems.qml:13)
2. Auto-backup file: Optional external file that mirrors the configuration

Configuration Persistence

• Entity configurations persist across Plasma restarts
• Configurations are stored in the plasmoid’s configuration file
• KDE Wallet stores access tokens separately (not included in backups)

Access tokens are not included in backups. When migrating to a new system, you need to reconfigure the Home Assistant URL and access token separately. See Connection Setup.

Troubleshooting

Import Fails

• Verify the file is a valid .hapi file
• Check that the file contains valid JSON
• Ensure the file is not corrupted

Auto-Backup Not Working

• Verify you clicked Apply after configuring the auto-backup file
• Check that you have write permission to the backup location
• Ensure the file path is valid and the directory exists

Missing Entities After Import

• Verify entity IDs exist in your Home Assistant instance
• Check the Home Assistant connection in General settings
• Entities with invalid IDs will not function but will remain in the configuration

Next Steps

Adding Entities

Add new entities to your plasmoid

Entity Settings

Customize entity display and behavior