313 lines
7.5 KiB
Markdown
313 lines
7.5 KiB
Markdown
# Bahmcloud Store - Full User Guide
|
|
|
|
This guide explains the current feature set of Bahmcloud Store (BCS) for Home Assistant.
|
|
|
|
BCS is a git-based store UI that can currently manage integrations and blueprints from multiple repository providers.
|
|
|
|
---
|
|
|
|
## Contents
|
|
|
|
- Concepts
|
|
- Sources
|
|
- Supported Content Types
|
|
- UI Overview
|
|
- Finding Repositories
|
|
- Installing
|
|
- Selecting Versions
|
|
- Updating
|
|
- Uninstalling
|
|
- Pinned Repositories
|
|
- Release Notes
|
|
- Backups and Restore
|
|
- Custom Repositories
|
|
- HACS Repositories
|
|
- Update Entities
|
|
- Performance and Caching
|
|
- Restart Behavior
|
|
- Troubleshooting
|
|
- FAQ
|
|
|
|
---
|
|
|
|
## Concepts
|
|
|
|
### Sources
|
|
|
|
- **BCS Official**: repositories from the official Bahmcloud index
|
|
- **HACS**: optional HACS integration source
|
|
- **Custom**: repositories you add manually by URL
|
|
|
|
### Installed Ref
|
|
|
|
BCS stores the installed ref separately from any version declared inside the repository itself.
|
|
That makes update checks more reliable when a repository uses tags or releases that do not exactly match its internal manifest version.
|
|
|
|
---
|
|
|
|
## Supported Content Types
|
|
|
|
### Integrations
|
|
|
|
- Source layout: `custom_components/<domain>/...`
|
|
- Install target: `/config/custom_components/<domain>`
|
|
- Supports install, update, downgrade, uninstall, backups, restore, and update entities
|
|
- Restart required after install, update, uninstall, or restore
|
|
|
|
### Blueprints
|
|
|
|
- Source layout: `blueprints/...`
|
|
- Install target: `/config/blueprints/...`
|
|
- Supports install and uninstall through the store
|
|
- Intended for blueprint repositories without integration-specific folder structures
|
|
|
|
---
|
|
|
|
## UI Overview
|
|
|
|
Store view:
|
|
|
|
- Search
|
|
- Source filter
|
|
- Category filter
|
|
- State filter
|
|
- Sorting
|
|
- HACS source toggle
|
|
- Pinned repository filtering and sorting
|
|
|
|
Repository detail view:
|
|
|
|
- README rendering
|
|
- Release notes for provider releases
|
|
- Version selector
|
|
- Install / Update / Uninstall actions
|
|
- Pin / Unpin action
|
|
- Backup restore action for integrations
|
|
- Category and install target information
|
|
|
|
---
|
|
|
|
## Finding Repositories
|
|
|
|
1. Use **Search** to filter by name, description, or URL.
|
|
2. Use **Source** to switch between BCS Official, HACS, and Custom repositories.
|
|
3. Use **Category** to focus on a specific content type.
|
|
4. Use **Pinned** filtering or sorting to surface repositories you watch often.
|
|
|
|
Descriptions, metadata, and latest versions may appear progressively because BCS enriches repository information in the background.
|
|
|
|
---
|
|
|
|
## Installing
|
|
|
|
### Integration Install
|
|
|
|
1. Open a repository.
|
|
2. Optionally select a version.
|
|
3. Click **Install**.
|
|
4. Restart Home Assistant when prompted.
|
|
|
|
Internally, BCS:
|
|
|
|
- downloads the selected repository archive
|
|
- extracts `custom_components/...`
|
|
- installs every valid integration found there
|
|
- stores the installed ref
|
|
- creates backups before overwriting existing integration folders
|
|
|
|
### Blueprint Install
|
|
|
|
1. Open a blueprint repository.
|
|
2. Optionally select a version.
|
|
3. Click **Install**.
|
|
|
|
Internally, BCS:
|
|
|
|
- downloads the selected repository archive
|
|
- extracts `blueprints/...`
|
|
- copies blueprint files into `/config/blueprints/...`
|
|
|
|
Blueprint installs normally do not require a Home Assistant restart.
|
|
|
|
---
|
|
|
|
## Selecting Versions
|
|
|
|
- Use the version selector in the detail view.
|
|
- `Latest` uses the newest provider release or tag BCS can determine.
|
|
- You can install an older release or tag when available.
|
|
- Release notes are shown when the selected version is a provider release with a body.
|
|
|
|
---
|
|
|
|
## Updating
|
|
|
|
### Integrations
|
|
|
|
- The **Update** button appears when the latest ref differs from the installed ref.
|
|
- Updates are also available through **Settings -> Updates** via native Home Assistant update entities.
|
|
- Integration updates create backups before overwriting files.
|
|
|
|
### Blueprints
|
|
|
|
- Blueprint repositories can also be reinstalled from another selected version.
|
|
- The current blueprint path handling is focused on direct deployment to the blueprints folder.
|
|
|
|
---
|
|
|
|
## Uninstalling
|
|
|
|
### Integrations
|
|
|
|
- Removes the installed integration directories from `/config/custom_components`
|
|
- Clears the installed state in BCS
|
|
- Usually requires a restart
|
|
|
|
### Blueprints
|
|
|
|
- Removes the installed blueprint files recorded by BCS
|
|
- Cleans up empty directories below `/config/blueprints` when possible
|
|
|
|
---
|
|
|
|
## Pinned Repositories
|
|
|
|
You can pin repositories to keep important items easy to find.
|
|
|
|
Current behavior:
|
|
|
|
- Pin or unpin from the detail view
|
|
- Filter the store by pinned repositories
|
|
- Sort the store with pinned repositories first
|
|
- Pinned repositories show a dedicated badge in the store overview
|
|
- Pinned state is persisted in settings
|
|
|
|
---
|
|
|
|
## Release Notes
|
|
|
|
When a provider release has a release body, BCS can show release notes in the detail view for the selected version.
|
|
|
|
Notes:
|
|
|
|
- Release notes are available for real releases, not every tag or branch
|
|
- If no provider release body exists, BCS shows a clear not-available state
|
|
|
|
---
|
|
|
|
## Backups and Restore
|
|
|
|
Integration installs and updates create backups before overwriting existing files.
|
|
|
|
Backup path:
|
|
|
|
`/config/.bcs_backups/<domain>/<timestamp>/`
|
|
|
|
Restore flow:
|
|
|
|
1. Open the repository detail
|
|
2. Click **Restore**
|
|
3. Select a backup
|
|
4. Confirm restore
|
|
5. Restart Home Assistant if prompted
|
|
|
|
Restore is currently intended for integrations.
|
|
|
|
---
|
|
|
|
## Custom Repositories
|
|
|
|
You can add any public repository URL that matches a supported provider style and contains supported content.
|
|
|
|
BCS attempts to detect:
|
|
|
|
- provider
|
|
- default branch
|
|
- latest version
|
|
- metadata from `bcs.yaml`, `hacs.yaml`, or `hacs.json`
|
|
- README content
|
|
|
|
Custom repositories get a **Custom** badge and can be filtered separately.
|
|
|
|
---
|
|
|
|
## HACS Repositories
|
|
|
|
Enable the HACS toggle to include official HACS integration repositories.
|
|
|
|
Current scope:
|
|
|
|
- HACS source support is currently focused on integrations
|
|
- HACS metadata is used to improve naming and descriptions
|
|
|
|
---
|
|
|
|
## Update Entities
|
|
|
|
BCS exposes Home Assistant update entities for installed integrations.
|
|
|
|
- Found under **Settings -> Updates**
|
|
- Shows installed ref and latest ref
|
|
- Lets Home Assistant trigger the BCS update pipeline
|
|
|
|
Blueprint repositories do not currently use the integration-style update entity flow.
|
|
|
|
---
|
|
|
|
## Performance and Caching
|
|
|
|
BCS is designed to keep startup responsive.
|
|
|
|
- Heavy work runs after Home Assistant startup
|
|
- Repo data is enriched in the background
|
|
- Repository details are cached
|
|
- Version lists are cached
|
|
- HACS metadata is cached
|
|
|
|
Opening a repository detail view can force immediate enrichment for that repository.
|
|
|
|
---
|
|
|
|
## Restart Behavior
|
|
|
|
Restart usually matters only for integration changes.
|
|
|
|
- Integration install/update/uninstall/restore: restart expected
|
|
- Blueprint install/uninstall: restart usually not needed
|
|
|
|
BCS uses a Home Assistant repair flow to surface restart requirements for integration changes.
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
- **Latest version missing**: open the repository detail once to force a recheck
|
|
- **Release notes missing**: the selected version may be a tag or branch without a provider release body
|
|
- **Blueprint install fails**: verify the repository really contains a `blueprints/` folder
|
|
- **Integration install fails**: verify the repository contains `custom_components/<domain>/manifest.json`
|
|
- **Repo appears but cannot install**: metadata can describe the category, but the repository layout still has to match that category
|
|
|
|
---
|
|
|
|
## FAQ
|
|
|
|
### Where are integrations installed?
|
|
|
|
`/config/custom_components/<domain>`
|
|
|
|
### Where are blueprints installed?
|
|
|
|
`/config/blueprints/...`
|
|
|
|
### Are pinned repositories persistent?
|
|
|
|
Yes.
|
|
|
|
### Do blueprints require a restart?
|
|
|
|
Usually no.
|
|
|
|
### Do integrations require a restart?
|
|
|
|
Yes, normally after install, update, uninstall, or restore.
|