DigiLive/mushroom-strategy
1
0
Fork 1
mirror of https://github.com/DigiLive/mushroom-strategy.git synced 2025-08-02 19:14:27 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add wiki documents

Browse Source
This commit is contained in:
DigiLive
2025-05-26 15:03:23 +02:00
parent 2fd1be9fc3
commit 09d486359e
23 changed files with 1132 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.github/workflows/deploy-docs.yml vendored Normal file
View File

@@ -0,0 +1,32 @@
# .github/workflows/deploy.yml
name: Deploy Documentation
on:
push:
branches:
- main
paths:
- 'docs/**'
- 'mkdocs.yml'
permissions:
contents: write
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.x' # Use a specific version like '3.10', '3.11', or '3.12'
- name: Install MkDocs, Material for MkDocs, and PyMdown Extensions
run: pip install mkdocs mkdocs-material pymdown-extensions
- name: Deploy Docs to GitHub Pages
run: mkdocs gh-deploy --force --clean

8
README.md
View File

@@ -4,16 +4,16 @@
[![HACS][hacsBadge]][hacsUrl]
[![Codacy][codacyBadge]][codacyUrl]
![Preview GIF](./docs/preview.gif)
![Preview GIF](docs/images/preview.gif)
<details>
<summary>More images...</summary>
![Automatic](./docs/auto.png)
![Automatic](docs/images/auto.png)
![Views](./docs/views.png)
![Views](docs/images/views.png)
![customizable](./docs/customizable.png)
![customizable](docs/images/customizable.png)
</details>
## What is the Mushroom Dashboard Strategy?

167
docs/contributing.md Normal file
View File

@@ -0,0 +1,167 @@
# 🤝 Contributing to Mushroom Strategy
We love contributions from the community! Whether you're reporting a bug, suggesting a new feature, or submitting code
changes, your help makes the Mushroom Strategy better for everyone.
Please take a moment to review this guide before making a contribution.
## 📜 Code of Conduct
To ensure a welcoming and inclusive environment, all contributors are expected to adhere to
our [Code of Conduct](https://github.com/DigiLive/mushroom-strategy/blob/main/CODE_OF_CONDUCT.md). Please read it
carefully.
---
## 🐞 Reporting Bugs
Found a bug? That's not ideal, but your report helps us squash it!
1. **Check existing issues:** Before opening a new issue, please search
our GitHub [Issues](https://github.com/DigiLive/mushroom-strategy/issues)
or [Discussions](https://github.com/DigiLive/mushroom-strategy/discussions) to see if the bug has already been
reported.
2. **Open a new issue:** If it's a new bug, please open
a [new issue](https://github.com/DigiLive/mushroom-strategy/issues/new?template=bug_report.yml).
3. **Provide details:** In your report, please include:
* A clear and concise description of the bug.
* Steps to reproduce the behavior.
* Expected behavior.
* Screenshots or animated GIFs (if applicable).
* Your Home Assistant version and Mushroom Strategy version.
---
## ✨ Suggesting Features
Have a great idea for a new feature or enhancement? We'd love to hear it!
1. **Check existing suggestions:** Search our GitHub [Issues](https://github.com/DigiLive/mushroom-strategy/issues)
or [Discussions](https://github.com/DigiLive/mushroom-strategy/discussions) to see if the feature has already been
requested.
2. **Open a new issue:** If it's a new idea, open
a [new issue](https://github.com/DigiLive/mushroom-strategy/issues/new?template=feature_request.yml).
3. **Describe your idea:** Clearly explain the feature, why you think it's useful, and any potential use cases.
---
## 💻 Contributing Code
Want to get your hands dirty with the code? Awesome! We appreciate all code contributions.
1. **Fork the Repository:** Start by forking
the [DigiLive/mushroom-strategy](https://github.com/DigiLive/mushroom-strategy) repository to your own GitHub
account.
2. **Clone Your Fork:** Clone your forked repository to your local machine.
```bash
git clone https://github.com/YOUR_USERNAME/mushroom-strategy.git
cd mushroom-strategy
```
3. **Create a New Branch:** Create a new branch for your feature or bug fix. Use a descriptive name (e.g.,
`feature/my-awesome-feature`, `bugfix/fix-admonition-rendering`).
```bash
git checkout -b feature/my-new-feature
```
4. **Set up Development Environment:**
* Ensure you have Node.js and npm installed.
* Install project dependencies: `npm install`
* You can build the strategy with `npm run build` (for production) or `npm run build-dev` (for development/testing).
* Copy the built files to your Home Assistant's `www/community/mushroom-strategy` folder for testing.
5. **Make Your Changes:** Implement your bug fix or new feature.
6. **Test Your Changes:** Thoroughly test your changes to ensure they work as expected and don't introduce new issues.
7. **Commit Your Changes:**
* We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) for clear commit history.
* Example: `feat: add new card option` or `fix: correct card rendering issue`
```bash
git add .
git commit -m "feat: add super cool new feature"
```
8. **Push to Your Fork:**
```bash
git push origin feature/my-new-feature
```
9. **Create a Pull Request (PR):**
* Go to your forked repository on GitHub.
* You should see a prompt to create a pull request from your new branch to the `main` branch of
`DigiLive/mushroom-strategy`.
* Provide a clear title and description for your PR, referencing any related issues.
* Be prepared to discuss your changes and address any feedback during the review process.
---
## 📄 Improving Documentation
Good documentation is vital! If you find typos, unclear sections, or want to add more examples, please open a pull
request. The documentation is located in the `docs/` folder of this repository.
---
## 🌐 Translations
Help us make Mushroom Strategy accessible to more users around the world by contributing and improving translations!
Language tags have to follow [BCP 47](https://tools.ietf.org/html/bcp47).
A list of most language tags can be found
here: [IANA subtag registry](http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry).
Examples: fr, fr-CA, zh-Hans.
1. **Check for Existing Translations:** See if your language is already being worked on or exists.
2. **Locate Translation Files:** Language files are found within the `src/translations` directory.
Each language has its own `locale.json` file (e.g., `en.json`, `nl.json`, `pt-BR.json`).
3. **Create or Update:**
* **To create a new language:** Copy an existing `.json` file (e.g., `en.json`), rename it to your language
code (e.g., `de.json` for German), and translate the property values.
* **To update an existing language:** Open the `.json` file for your language and update any missing or
outdated translations.
4. **Submit a Pull Request:** Once your translations are complete, submit a pull request with your changes. Clearly
state which language you are contributing to or updating.
!!! info
**Integrating a new Translation:**
* For your new language file to be picked up, it needs to be imported and registered at file
`src/utilities/localize.ts`.
* You will need to add an `import` statement for your new `.json` file at the top, following the existing pattern.
* Then, you'll need to add it to the `languages` map, associating the language code with the imported module.
**Special Handling for `language-country` Locales:**
If you are adding a country-specific locale (e.g., `es-ES` for Spanish (Spain) or `en-GB` for English
(United Kingdom)), you should create a file like `en-GB.json` in the `translations` folder. In
`src/utilities/localize.ts`, you'll import it similarly and add it to the `languages` map using the full locale
code.
Please ensure you follow existing patterns for `language-country` codes, which typically use a hyphen (`-`) + a
UPPER-cased country code in the file name and an underscore (`_`) + a lower-cased country code in the import key.
!!! example
```typescript
import * as en from '../translations/en.json';
import * as pt_br from '../translations/pt-BR.json';
/** Registry of currently supported languages */
const languages: Record<string, unknown> = {
en,
'pt-BR': pt_br,
};
```
---
## 🙏 Get Support
If you have questions about contributing or need help with your setup, please open
a [discussion](https://github.com/DigiLive/mushroom-strategy/discussions) on our GitHub repository.

56
docs/faq.md Normal file
View File

@@ -0,0 +1,56 @@
??? question "How do I add a device or entity to an area?"
You can add devices to an area by going to `Settings` found at the bottom of the sidebar.
1. Select `Devices & services`.
2. Select `Devices` or `Entities`at the top.
3. Choose the device or entity you wish to add to an area.
4. Select :material-pencil: or :material-cog: in the top right corner.
5. Choose an area in the area field.
!!! warning
If you created an entity manually (in your `configuration.yaml`), you may need to create a `unique_id` before
you can set an area to it.
See Home Assistant's [documentation][uniqueIdUrl] for more info about unique ids.
??? question "How do I hide entities from the Strategy?"
When creating this dashboard for the first time, you might be overwhelmed by the number of entities.
To reduce the number of entities shown, you can hide these entities by following the steps below:
1. Click and hold the entity.
2. Click :material-cog: in the top right corner of the popup.
3. Set `Visible` to `off`.
!!! note
If you don't want to hide the entity from all dashboards, you can use [Card Options][cardOptionsUrl] to hide
specific entities and devices.
??? question "How do I get the id of entities, devices and areas?"
* Entity Id
1. Select `Settings` at the bottom of the sidebar.
2. Select `Devices & services`.
3. Select `Entities` at the top.
4. Choose the entity you want to get the id of.
5. Click :material-cog: in the top right corner of the popup.
* Device Id
1. Select `Settings` at the bottom of the sidebar.
2. Select `Devices & services`.
3. Select `Devices` at the top.
4. Select the device you want to get the id of.
5. The device id is shown as the **last** part of the url in the address bar.
E.g.: `https://.../config/devices/device/h55b6k54j76g56`
* Area Id
1. Select `Settings` at the bottom of the sidebar.
2. Select `Areas`.
3. Select :material-pencil: of the area you want to get the id of.
<!-- references -->
[uniqueIdUrl]: https://www.home-assistant.io/faq/unique_id
[cardOptionsUrl]: options/card-options.md

119
docs/full-example.md Normal file
View File

@@ -0,0 +1,119 @@
Here is a full example using all the options provided with the strategy.
```yaml
strategy:
type: custom:mushroom-strategy
options:
views:
light:
order: 1
title: illumination
switches:
hidden: true
icon: mdi:toggle-switch
home_view:
hidden:
- areasTitle
- greeting
stack_count:
areas: [2, 1]
persons: 3
domains:
_:
hide_config_entities: true
stack_count: 1
light:
order: 1
stack_count: 2
title: "My cool lights"
chips:
weather_entity: weather.forecast_home
climate_count: false
cover_count: false
extra_chips:
- type: conditional
conditions:
- entity: lock.front_door
state: unlocked
chip:
type: entity
entity: lock.front_door
icon_color: red
content_info: none
icon: ''
use_entity_picture: false
tap_action:
action: toggle
- type: conditional
conditions:
- entity: cover.garage_door
state_not: closed
chip:
type: entity
entity: cover.garage_door
icon_color: red
content_info: none
tap_action:
action: toggle
areas:
_:
type: default
family_room_id:
name: Family Room
icon: mdi:television
icon_color: green
extra_cards:
- type: custom:mushroom-chips-card
chips:
- type: entity
entity: sensor.family_room_temperature
icon: mdi:thermometer
icon_color: pink
alignment: center
kitchen_id:
name: Kitchen
icon: mdi:silverware-fork-knife
icon_color: red
order: 1
master_bedroom_id:
name: Master Bedroom
icon: mdi:bed-king
icon_color: blue
kids_bedroom_id:
name: Kids Bedroom
icon: mdi:flower-tulip
icon_color: green
card_options:
fan.master_bedroom_fan:
type: custom:mushroom-fan-card
remote.harmony_hub_wk:
hidden: true
quick_access_cards:
- type: custom:mushroom-cover-card
entity: cover.garage_door
show_buttons_control: true
- type: horizontal-stack
cards:
- type: custom:mushroom-lock-card
entity: lock.front_door
- type: custom:mushroom-entity-card
entity: sensor.front_door_lock_battery
name: Battery
extra_cards:
- type: custom:xiaomi-vacuum-map-card
map_source:
camera: camera.xiaomi_cloud_map_extractor
calibration_source:
camera: true
entity: vacuum.robot_vacuum
vacuum_platform: default
extra_views:
- theme: Backend-selected
title: Cool view
path: cool-view
icon: mdi:emoticon-cool
badges: []
cards:
- type: markdown
content: I am cool
```

30
docs/getting-started/basic-setup.md Normal file
View File

@@ -0,0 +1,30 @@
# Basic Setup
To apply the Mushroom Strategy to a dashboard:
1. In the UI of the dashboard, select :material-pencil: in the top right corner.
2. If not taken to a Raw Configuration editor, click the three-dot menu in the top right corner.
3. Select `Raw configuration editor`.
4. Empty the configuration and add the following lines:
```yaml
strategy:
type: custom:mushroom-strategy
views: []
```
> [!NOTE]
> You may see the following error:
```
Error loading the dashboard strategy:
Error: Timeout waiting for strategy
element ||-strategy-mushroom-strategy to
be registered
```
This is mainly because of cache issues or HACS didn't create a reference.
Try clearing the cache of your client and/or re-downloading the strategy from HACS.
If it still doesn't work, please consult guide
[How to solve: Error loading the dashboard strategy](https://github.com/DigiLive/mushroom-strategy/discussions/90).

71
docs/getting-started/installation.md Normal file
View File

@@ -0,0 +1,71 @@
# Installation
## Prerequisites
Mushroom dashboard strategy and dependencies are available in [HACS][hacsUrl] (Home Assistant Community Store).
Install HACS if you don't have it already.
For assistance, you can follow the [installation guide][hacsInstallationGuideUrl].
Once you have HACS installed, you can install custom integration and plug-ins.
This guide offers you badges to open your Home Assistant on the correct page.
If the badges don't work, try installing from HACS manually:
1. Open HACS in Home Assistant (Usually in the menu on the left side).
2. At the top, search for the component you want to install.
3. Select the `three-dot` menu on the right side of the component and select `Download`.
4. Choose the desired version and select `Download` again.
You need to install the following HACS integrations before you can use this strategy.
Click the badges below and follow the installation instructions.
They will open the HACS repository at your Home Assistant instance directly.
[![Open in HACS at your Home Assistant instance.][hacsBadge]][hacsMushroomUrl] to install [Mushroom][mushroomUrl].
[![Open in HACS at your Home Assistant instance.][hacsBadge]][hacsMiniGraphUrl] to
install [Mini graph card][miniGraphUrl].
## Dashboard Installation
If you meet all the prerequisites, click the badge below to install the strategy.
[![Open in HACS at your Home Assistant instance.][hacsBadge]][hacsStrategyUrl]
## Local Installation
Please install the strategy with HACS as described above.
If you require testing a custom build for debug purposes, follow these steps:
1. Build the strategy with `npm build` or `npm build-dev`.
2. Copy the build file(s) to folder `<your-hass-directory>/www/community/mushroom-strategy`.
3. If file `mushroom-strategy.js.gz` exists in that folder, rename or delete it.
!!! note
Refresh the cache of the client you use to access Home Assistant.
## Updating
By default, Home Assistant will notify you when an update of the strategy is available.
You can update the strategy by going to `Settings` found at the bottom of the sidebar.
!!! tip
You can enable notifications of pre-releases.
* Go to `Settings` > `Devices & services` > `Entities`.
* Search for `Mushroom Dashboard` and switch on the `Pre-release` entity.
<!-- References -->
[hacsUrl]: https://hacs.xyz
[hacsInstallationGuideUrl]: https://hacs.xyz/docs/setup/prerequisites
[hacsBadge]: https://img.shields.io/badge/Open%20my%20HACS%20Repository-%2318BCF2?logo=homeassistant&logoColor=%23FFFFFF&labelColor=%2318BCF2
[mushroomUrl]: https://github.com/piitaya/lovelace-mushroom
[hacsMushroomUrl]: https://my.home-assistant.io/redirect/hacs_repository/?owner=piitaya&repository=lovelace-mushroom&category=frontend
[miniGraphUrl]: https://github.com/kalkih/mini-graph-card
[hacsMiniGraphUrl]: https://my.home-assistant.io/redirect/hacs_repository/?owner=kalkih&repository=mini-graph-card&category=frontend
[hacsStrategyUrl]: https://my.home-assistant.io/redirect/hacs_repository/?owner=DigiLive&repository=mushroom-strategy&category=frontend

0
docs/Hidden.png → docs/images/Hidden.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 117 KiB

After

Width:  |  Height:  |  Size: 117 KiB

0
docs/additonal_cards.png → docs/images/additonal_cards.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 144 KiB

After

Width:  |  Height:  |  Size: 144 KiB

0
docs/auto.png → docs/images/auto.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 505 KiB

After

Width:  |  Height:  |  Size: 505 KiB

0
docs/chips.png → docs/images/chips.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 10 KiB

After

Width:  |  Height:  |  Size: 10 KiB

0
docs/customizable.png → docs/images/customizable.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 524 KiB

After

Width:  |  Height:  |  Size: 524 KiB

0
docs/light_view.png → docs/images/light_view.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 133 KiB

After

Width:  |  Height:  |  Size: 133 KiB

0
docs/preview.gif → docs/images/preview.gif
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 8.7 MiB

After

Width:  |  Height:  |  Size: 8.7 MiB

0
docs/views.png → docs/images/views.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 595 KiB

After

Width:  |  Height:  |  Size: 595 KiB

49
docs/index.md Normal file
View File

@@ -0,0 +1,49 @@
# Welcome to the Mushroom Strategy Documentation 🍄
The **Mushroom Strategy** is an innovative solution for Home Assistant that empowers you to effortlessly create
beautiful, intuitive, and automatically generated dashboards using the
popular [Mushroom cards](https://github.com/piitaya/lovelace-mushroom).
Say goodbye to tedious manual YAML configuration for every card! With the Mushroom Strategy, you can define your
entities, areas, and devices and let the strategy intelligently build a dynamic and responsive dashboard tailored to
your smart home.
## ✨ Key Features & Benefits
* **Automated Dashboard Generation:** Create a comprehensive dashboard with minimal YAML, saving you countless hours.
* **Leverages Mushroom Cards:** Enjoy the stunning aesthetics and rich functionality of Mushroom cards, renowned for
their clean design and user-friendliness.
* **Entity, Device, and Area-Aware:** Automatically organizes your Home Assistant components into logical, navigable
views.
* **Built-in Views:** Access pre-built views for specific domains like lights, fans, climate, and more, ensuring quick
control.
* **Highly Customizable:** While automated, the strategy provides ample options to fine-tune the appearance and behavior
to match your preferences.
* **Responsive Design:** Your generated dashboard will look great and function seamlessly across all devices – mobile,
tablet, and desktop.
## 🚀 Get Started in Minutes
Ready to transform your Home Assistant interface? Follow these guides to get your Mushroom Strategy dashboard up and
running:
* [**Installation Guide**](getting-started/installation.md): Step-by-step instructions to install the strategy via HACS
or manually.
* [**Basic Setup**](getting-started/basic-setup.md): Learn the fundamental configuration to generate your first
dashboard.
* [**Configuration Options**](options/index.md): Dive deeper into all available settings to customize your dashboard to
perfection.
* [**Usage Example**](full-example.md): An example to show most of the configuration options.
---
We're excited for you to experience the simplicity and power of the Mushroom Strategy. If you have questions, encounter
issues, or want to contribute, please visit our [GitHub repository](https://github.com/DigiLive/mushroom-strategy) and
engage with the community!
**Enjoying the Mushroom Strategy?** Consider giving our project a
⭐ [star on GitHub](https://github.com/DigiLive/mushroom-strategy) and exploring ways
to ❤️ [sponsor the project](https://github.com/sponsors/DigiLive) to support its continued development! Your support
helps us grow and improve.
// TODO: add contribution and pre-release

99
docs/options/area-options.md Normal file
View File

@@ -0,0 +1,99 @@
# Area Options
The `areas` group enables you to specify the configuration of specific areas.
Each configuration is identified by an area id and can have the following options:
| Name | Type | Default | Description |
|:--------------|:---------------|:----------------|:---------------------------------------------------------------------------|
| `extra_cards` | array of cards | `[]` | A list of cards to show on the top of the area sub-view. |
| `hidden` | boolean | `false` | Set to `true` to exclude the area from the dashboard and views. |
| `name` | string | `Area specific` | The name of the area. |
| `order` | number | `unset` | Ordering position of the area in the list of available areas. |
| `type` | string | `default` | Set to a type of area card. (Currently supported: `default` & `HaAreaCard` |
Also, all options from the Template mushroom card and/or Home Assistant Area card are supported.
Please follow the links below to see the additional options per card type.
* [Mushroom Template Card][templateDocUrl].
* [Home Assistant Area Card][areaDocUrl].
## Extra Cards
The `extra_cards` group enables you to specify the configuration of additional cards an Area view.
These cards will be shown last in the view.
See Home View Options → [Extra Cards](#extra-cards) for more information.
## Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
areas:
family_room_id:
name: Family Room
icon: mdi:television
icon_color: green
order: 1
extra_cards:
- type: custom:mushroom-chips-card
chips:
- type: entity
entity: sensor.family_room_temperature
icon: mdi:thermometer
icon_color: pink
alignment: center
kitchen_id:
name: Kitchen
icon: mdi:silverware-fork-knife
icon_color: red
order: 2
garage_id:
hidden: true
hallway_id:
type: HaAreaCard
extra_cards:
- type: custom:xiaomi-vacuum-map-card
map_source:
camera: camera.xiaomi_cloud_map_extractor
calibration_source:
camera: true
entity: vacuum.robot_vacuum
vacuum_platform: default
views: []
```
## Undisclosed Area
The strategy has a special area, named `undisclosed`.
This area is enabled by default and includes the entities that aren't linked to any Home Assistant area.
The area can be configured like any other area as described above.
To exclude this area from the dashboard and views, set its property `hidden` to `true`.
## Setting options for all areas
Use `_` as an identifier to set the options for all areas.
The following example sets the type of all area-cards to the one of Home Assistant:
### Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
areas:
_:
type: HaAreaCard
views: []
```
!!! note
Area specific options take precedence over options set for all areas.!
<!-- References -->
[templateDocUrl]: https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/template.md
[areaDocUrl]: https://www.home-assistant.io/dashboards/area/#configuration-variables

35
docs/options/card-options.md Normal file
View File

@@ -0,0 +1,35 @@
# Card Options
The `card_options` group enables you to specify the configuration of entity cards.
Each configuration is identified by an entity id and can have the following options:
| name | type | default | description |
|:-------|:--------|:------------------|:------------------------------------------------------|
| hidden | boolean | `false` | Set to `true` to exclude the card from the dashboard. |
| type | string | `domain specific` | The type for card to apply. |
| ... | ... | `type specific` | An option belonging to the given card type. |
Depending on the type of card, you can also specify options belonging to that type.
Providing a device id will enable you to hide all the entities associated with that device.
## Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
card_options:
fan.master_bedroom_fan:
type: custom:mushroom-fan-card
icon: mdi:fan
remote.harmony_hub_wk:
hidden: true
077ba0492c9bb3b3134f1f3a626a: # this is a device id
hidden: true
```
!!! tip
You can build your card at another dashboard and copy the `cards` group from the YAML of that dashboard into group
`card_options` of the strategy configuration.
The YAML can be found in the Raw configuration editor.

72
docs/options/domain-options.md Normal file
View File

@@ -0,0 +1,72 @@
# Domain Options
The `domains` group enables you to specify the configuration of a domain in a view.
Each configuration is identified by a domain name and can have the following options:
| Option | type | Default | Description |
|:-------------------------|:--------|:------------------|:--------------------------------------------------------------------------|
| hidden | boolean | `false` | Set to `true` to exclude the domain from the dashboard. |
| hide_config_entities | boolean | `true` | Set to `false` to include config-entities to the dashboard. |
| hide_diagnostic_entities | boolean | `true` | Set to `false` to include diagnostic-entities to the dashboard. |
| order | number | `unset` | Ordering position of the domain entities in a view. |
| showControls | boolean | `true` | Weather to show controls in a view, to switch all entities of the domain. |
| stack_count | object | `{_: 1}` | Cards per row.[^1] |
| title | string | `domain specific` | Title of the domain in a view. |
[^1]:
In the different views, the cards belonging to a specific domain will be horizontally stacked into a row.
The number of cards per row can be configured with this option.
!!! note
* Domain `default` represents any other domain than supported by this strategy.
* The `showControls` option will default to false for domain which can't be controlled.
* The `hide_config_entities` and `hide_diagnostic_entities` options are only available as an "All domains" option.
---
## Setting options for all domains
Use `_` as the identifier to set options for all domains.
## Example
```YAML
strategy:
type: custom:mushroom-strategy
options:
domains:
_:
stack_count: 2
hide_config_entities: false
light:
title: "My cool lights"
order: 1
switch:
stack_count: 3
showControls: false
default: # All other domains
hidden: true
```
??? info "Click to expand the full list of supported domains"
- _ (All domains)
- area
- binary_sensor
- camera
- climate
- cover
- default (Miscellaneous)
- fan
- input_select
- light
- lock
- media_player
- number
- person
- scene
- select
- sensor
- switch
- vacuum
- valve

197
docs/options/home-view-options.md Normal file
View File

@@ -0,0 +1,197 @@
# Home View Options
The `home_view` group enables you to specify the configuration of the Home view.
| Option | type | default | Description |
|:--------------|:-------|:---------|:----------------------------------------------|
| `hidden` | array | `[]` | Array of sections to hide from the home view. |
| `stack_count` | object | `{_: 2}` | Cards per row. |
---
## Hiding sections
The following sections can be hidden from the Home view:
* areas
* areasTitle
* chips
* greeting
* persons
### Example
```YAML
strategy:
type: custom:mushroom-strategy
options:
home_view:
hidden:
- greeting
- areasTitle
```
---
## Stack Count
The `stack_count` option is a map of sections to define the number of cards per row.
The key of the map is the section, while the value is the number of cards per row.
The `areas` section is a special case, where the value is an array of two numbers.
The first number is the number of default cards per row, while the second number is the number of
[Home Assistant cards](https://www.home-assistant.io/dashboards/area/) per row.
### example
```yaml
home_view:
stack_count:
_: 2 # Two cards per row for all sections.
persons: 3 # Three person cards per row.
areas: [2,1] # [Two Strategy Card per row, 1 HASS card per row]
```
!!! note
Section specific options take precedence over options set for all sections.!
---
## Chip Options
The mushroom strategy has chips that indicate the number of entities for a specific domain which are in an "active"
state. Hidden/Disabled entities are excluded from this count.
* Tapping a chip will set corresponding entities to an "inactive" state.[^1]
* Tap and hold a chip, will navigate to the corresponding view.
[^1]: For some chips, the tap action is disabled.
The `chips` group enables you to specify the configuration of chips.
| Name | type | default | Description |
|:-----------------|:--------|:--------|:--------------------------------------------|
| `light_count` | boolean | `false` | Number of lights on. |
| `fan_count` | boolean | `false` | Number of fans on. |
| `cover_count` | boolean | `false` | Number of covers not closed. No tap action. |
| `switch_count` | boolean | `false` | Number of switches on. |
| `climate_count` | boolean | `false` | Number of climate not off. No tap action. |
| `weather_entity` | string | `auto` | Entity id for the weather chip to use. |
| `extra_chips` | array | `[]` | List of extra chips to show. |
If `weather_entity` is set to `auto`, the weather chip uses the first entity of the weather domain it finds.
You can define a custom entity to use by setting an entity id.
!!! note
To hide the weather chip, you should hide or disable the entity itself.
```yaml
strategy:
type: custom:mushroom-strategy
options:
chips:
climate_count: false
cover_count: false
weather_entity: weather.forecast_home
```
---
## Extra Chips
To add custom chips, you can configure them in `extra_chips`.
See [Mushroom Chips][chipDocUrl] for all available chips.
!!! tip
You can build your chips in a temporary card in another dashboard and copy the `chips` group from the YAML of that
card into group `extra_chips` of the strategy configuration. The YAML can be found in the Raw configuration editor.
### Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
chips:
extra_chips:
- type: conditional
conditions:
- entity: lock.front_door
state: unlocked
chip:
type: entity
entity: lock.front_door
icon_color: red
content_info: none
tap_action:
action: toggle
```
---
## Quick Access Cards
The `quick_access_cards` group enables you to specify the configuration of additional cards in the view.
These cards will be shown between the greeting card and area cards.
Each card can have the options as described at [Card Options](card-options.md).
!!! tip
You can build your view in a temporary dashboard and copy the `views` group from the YAML of that dashboard into
group `extra_views` of the strategy configuration.
The YAML can be found in the Raw configuration editor.
### Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
quick_access_cards:
- type: custom:mushroom-title-card
title: Security
- type: custom:mushroom-cover-card
entity: cover.garage_door
show_buttons_control: true
- type: horizontal-stack
cards:
- type: custom:mushroom-lock-card
entity: lock.front_door
- type: custom:mushroom-entity-card
entity: sensor.front_door_lock_battery
name: Battery
```
---
### Extra Cards
The `extra_cards` group enables you to specify the configuration of additional cards in the view.
These cards will be shown below the areas.
Each card can have the options as described at [Card Options](card-options.md).
!!! tip
You can build your view in a temporary dashboard and copy the `views` group from the YAML of that dashboard into
group `extra_cards` of the strategy configuration.
The YAML can be found in the Raw configuration editor.
#### Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
extra_cards:
- type: custom:xiaomi-vacuum-map-card
map_source:
camera: camera.xiaomi_cloud_map_extractor
calibration_source:
camera: true
entity: vacuum.robot_vacuum
vacuum_platform: default
```
<!-- references -->
[chipDocUrl]: https://github.com/piitaya/lovelace-mushroom/blob/main/docs/cards/chips.md

47
docs/options/index.md Normal file
View File

@@ -0,0 +1,47 @@
# Overview
The dashboard can be highly customized using the `options` parameter in the yaml configuration of your dashboard.
```yaml
strategy:
type: custom:mushroom-strategy
options:
# Custom Configuration
```
By default,
- All views and domains are enabled.
- All chips are enabled and count the number of "active" entities.
- For the weather chip, the entity is selected automatically unless you specify one.
- All entities without an area are added to the `undisclosed` area.
- All configuration- and diagnostic entities are hidden.
The options are divided into groups as described below.
| Name | Type | Default | Description |
|:-------------------|:---------------|:----------------------|:------------------------------------------------------------------------------------------------------------------------------------------|
| areas | object | undisclosed | See [Area Options](area-options.md). |
| card_options | object | empty | See [Card Options](card-options.md). |
| domains | object | All supported domains | See [Domain Options](domain-options.md). |
| home_view | object | unset | See [Home View Options](home-view-options.md). |
| chips | object | All supported chips | See [Chip Options](home-view-options.md#chip-options). |
| quick_access_cards | array of cards | empty | List of cards to show between the greeting card and the area cards.<br>See [Quick Access Cards](home-view-options.md#quick-access-cards). |
| extra_cards | array of cards | empty | List of cards to show below the area cards.<br>See [extra Cards](home-view-options.md#extra-cards). |
| views | object | All supported views | See [View Options](view-options.md). |
| extra_views | array of views | empty | List of user defined views to add to the dashboard.<br>See [Extra Views](view-options.md#extra-views). |
## Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
areas:
family_room_id:
name: Family Room
icon: mdi:sofa
icon_color: green
```

80
docs/options/view-options.md Normal file
View File

@@ -0,0 +1,80 @@
# View Options
Mushroom strategy includes several views to control/view entities of a specific domain.
Hidden/Disabled entities or linked to a hidden area are excluded from the view.
The following views are supported and enabled by default:
| View | Type | Description |
|:--------|:-------|:-------------------------------------------|
| camera | object | View to control cameras. |
| climate | object | View to control climates. |
| cover | object | View to control covers. |
| fan | object | View to control fans. |
| home | object | An overview of several entities and areas. |
| light | object | View to control lights. |
| lock | object | View to control locks. |
| scene | object | View to control scenes. |
| switch | object | View to control switches. |
| vacuum | object | View to control vacuums. |
| valve | object | View to control valves. |
The `views` group enables you to specify the configuration of a view.
Each configuration is identified by a view name and can have the following options:
| name | type | Default | description |
|:-------|:--------|:-----------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------|
| hidden | boolean | `false` | Set to `true` to exclude the view from the dashboard |
| icon | string | `domain specific` | Icon of the view in the navigation bar. |
| order | string | home, light, fan, cover, switch, climate, camera, vacuum, scene, lock, valve | Ordering position of the view in the navigation bar. |
| title | string | `domain specific` | Title of the view in the navigation bar. (Shown when no icon is defined or hovering above it.) |
## Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
views:
light:
order: 0
title: illumination
switch:
order: 1
hidden: true
icon: mdi:toggle-switch
views: []
```
---
## Extra Views
The `extra_views` group enables you to specify the configuration of additional views.
Each view can have the options as described in the [Home Assistant documentation][viewDocUrl].
!!! tip
You can build your view in a temporary dashboard and copy the `views` group from the YAML of that dashboard into
group `extra_views` of the strategy configuration. The YAML can be found in the Raw configuration editor.
### Example
```yaml
strategy:
type: custom:mushroom-strategy
options:
extra_views:
- theme: Backend-selected
title: cool view
path: cool-view
icon: mdi:emoticon-cool
badges: []
cards:
- type: markdown
content: I am cool
```
<!-- references -->
[viewDocUrl]: https://www.home-assistant.io/dashboards/views/#views

74
mkdocs.yml Normal file
View File

@@ -0,0 +1,74 @@
site_name: Mushroom Strategy Documentation
site_url: https://digilive.github.io/mushroom-strategy/
site_description: The official documentation for Home Assistant's Mushroom Dashboard Strategy.
repo_url: https://github.com/DigiLive/mushroom-strategy/
edit_uri: edit/main/docs/
site_author: Ferry Cools
copyright: Copyright &copy; 2024 - <script>document.write(new Date().getFullYear())</script> DigiLive. All Rights Reserved.
theme:
name: material
icon:
logo: material/mushroom
palette:
- scheme: default
primary: blue
accent: light blue
toggle:
icon: material/brightness-7
name: Switch to dark mode
- scheme: slate
primary: blue
accent: light blue
toggle:
icon: material/brightness-4
name: Switch to light mode
features:
- navigation.tabs
- navigation.sections
- toc.integrate
- toc.follow
- search.suggest
- search.highlight
- content.code.copy
- content.tabs
- content.action.edit
- content.footnote.tooltips
nav:
- Home: index.md
- Getting Started:
- Installation: getting-started/installation.md
- Basic Setup: getting-started/basic-setup.md
- Strategy Options:
- Overview: options/index.md
- Area Options: options/area-options.md
- Card Options: options/card-options.md
- Domain Options: options/domain-options.md
- Home View Options: options/home-view-options.md
- View Options: options/view-options.md
- Full Example: full-example.md
- FAQ: faq.md
- Contributing: contributing.md
markdown_extensions:
- toc:
permalink: "#"
- admonition
- pymdownx.superfences
- pymdownx.details
- footnotes
- attr_list
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
validation:
nav:
not_found: warn
links:
not_found: warn
anchors: warn
unrecognized_links: warn