Merge branch 'current' into rc

_config.yml

@@ -211,6 +211,8 @@ installation:
           key: "odroid-c4"
         - name: "ODROID-M1"
           key: "odroid-m1"
+        - name: "ODROID-M1S"
+          key: "odroid-m1s"
 
     raspberrypi:
       board: Raspberry Pi

source/_dashboards/calendar.markdown

@@ -17,19 +17,6 @@ The calendar card displays your [calendar](/integrations/#calendar) entities in
 
 All options for this card can be configured via the user interface.
 
-## Card settings
-
-{% configuration_basic %}
-Title:
-  description: The title displayed at the top of the card.
-Initial View:
-  description: "The view that will show first when the card is loaded onto the page. Options are `Month View`, `Day View`, or `List (7 days)`."
-Entities:
-  description: The calendar entities that will be displayed in the card.
-Theme:
-  description: Name of any loaded theme to be used for this card. For more information about themes, see the [frontend documentation](/integrations/frontend/).
-{% endconfiguration_basic %}
-
 ## YAML configuration
 
 The following YAML options are available when you use YAML mode or just prefer to use YAML in the code editor in the UI.

source/_dashboards/masonry.markdown

@@ -2,7 +2,7 @@
 type: view
 title: Masonry view
 sidebar_label: Masonry (default)
-description: "The default panel layout uses a masonry algorithme."
+description: "The default panel layout uses a masonry algorithm."
 ---
 
 The masonry view is the default view type.
@@ -12,7 +12,14 @@ The masonry view is the default view type.
 Screenshot of the masonry view.
 </p>
 
-It sorts cards in columns based on their `card size`. If you want to group some cards you have to use [horizontal stack](/dashboards/horizontal-stack/), [vertical stack](/dashboards/vertical-stack/), or [grid](/dashboards/grid/) cards.
+Masonry sorts cards in columns based on their card size. The next card is placed below the smallest card on the dashboard.
+
+<p class='img'>
+<img src='/images/dashboards/masonry.png' alt='Image showing how masonry arranges cards based on size.'>
+Masonry arranges cards based on size.
+</p>
+
+To group cards, you have to use [horizontal stack](/dashboards/horizontal-stack/), [vertical stack](/dashboards/vertical-stack/), or [grid](/dashboards/grid/) cards.
 
 {% configuration %}
 type:

source/_docs/configuration/splitting_configuration.markdown

@@ -3,15 +3,23 @@ title: "Splitting up the configuration"
 description: "Splitting the configuration.yaml into several files."
 ---
 
-So you've been using Home Assistant for a while now and your `configuration.yaml` file brings people to tears or you simply want to start off with the distributed approach, here's how to split the `configuration.yaml` into more manageable (read: humanly readable) pieces.
+So you've been using Home Assistant for a while now and your `configuration.yaml` file brings people to tears because it has become so large. Or, you simply want to start off with the distributed approach. Here's how to split the `configuration.yaml` into more manageable (read: human-readable) pieces.
 
-First off, several community members have sanitized (read: without API keys/passwords etc) versions of their configurations available for viewing, you can see a list of them [here](/examples/#example-configurationyaml).
+## Example configuration files for inspiration
 
-As commenting code doesn't always happen, please read on for the details.
+First off, several community members have sanitized (read: without API keys/passwords) versions of their configurations available for viewing. You can see a [list of example files here](/examples/#example-configurationyaml).
 
-Now despite the logical assumption that the `configuration.yaml` will be replaced by this process it will in fact remain, albeit in a much less cluttered form.
+As commenting code doesn't always happen, please read on to learn in detail how configuration files can be structured.
 
-In this lighter version we will still need what could be called the core snippet:
+## Analyzing the configuration files
+
+In this section, we are going use some example configuration files and look at their structure and format in more detail.
+
+Now you might think that the `configuration.yaml` will be replaced during the splitting process. However, it will in fact remain, albeit in a much less cluttered form.
+
+### The core configuration file
+
+In this lighter version, we will still need what could be called the core snippet:
 
 ```yaml
 homeassistant:
@@ -27,9 +35,11 @@ homeassistant:
   customize: !include customize.yaml
 ```
 
+### Indentation, includes, comments, and modularization
+
 Note that each line after `homeassistant:` is indented two (2) spaces. Since the configuration files in Home Assistant are based on the YAML language, indentation and spacing are important. Also note that seemingly strange entry under `customize:`.
 
-`!include customize.yaml` is the statement that tells Home Assistant to insert the contents of `customize.yaml` at that point. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks.
+`!include customize.yaml` is the statement that tells Home Assistant to insert the parsed contents of `customize.yaml` at that point. The contents of the included file must be yaml data that is valid at the location it is included. This is how we are going to break a monolithic and hard to read file (when it gets big) into more manageable chunks.
 
 Now before we start splitting out the different components, let's look at the other integrations (in our example) that will stay in the base file:
 
@@ -51,9 +61,20 @@ mqtt:
       state_topic: "test/some_topic2"
 ```
 
-As with the core snippet, indentation makes a difference. The integration headers (`mqtt:`) should be fully left aligned (aka no indent), and the key (`sensor:`) should be indented two (2) spaces. The list `-` under the key `sensor` should be indented another two (2) spaces followed by a single space. The `mqtt` sensor list contains two (2) configurations containing two (2) keys each.
+As with the core snippet, indentation makes a difference:
 
-While some of these integrations can technically be moved to a separate file they are so small or "one off's" where splitting them off is superfluous. Also, you'll notice the # symbol (hash/pound). This represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored. This makes breaking up files for human readability really convenient, not to mention turning off features while leaving the entry intact.
+- The integration headers (`mqtt:`) should be fully left aligned (aka no indent).
+- The key (`sensor:`) should be indented two (2) spaces.
+- The list `-` under the key `sensor` should be indented another two (2) spaces followed by a single space.
+- The `mqtt` sensor list contains two (2) configurations, with two (2) keys each.
+
+#### Comments
+
+The # symbol (hash/pound) represents a "comment" as far as the commands are interpreted. Put another way, any line prefixed with a `#` will be ignored by the software. It is for humans only. Comments allow breaking up files for readability, as well as turning off features while leaving the entry intact.
+
+#### Modularization and granularity
+
+While some of these integrations could technically be moved to a separate file, they are so small or "one off's" where splitting them off is superfluous.
 
 Now, lets assume that a blank file has been created in the Home Assistant configuration directory for each of the following:
 
@@ -68,7 +89,7 @@ customize.yaml
 
 `automation.yaml` will hold all the automation integration details. `zone.yaml` will hold the zone integration details and so forth. These files can be called anything but giving them names that match their function will make things easier to keep track of.
 
-Inside the base configuration file add the following entries:
+Inside the base configuration file, add the following entries:
 
 ```yaml
 automation: !include automation.yaml
@@ -78,9 +99,15 @@ switch: !include switch.yaml
 device_tracker: !include device_tracker.yaml
 ```
 
-Nesting `!include`s (having an `!include` within a file that is itself `!include`d) will also work.
+#### Include statements and packages to split files
 
-Some integrations support multiple top-level `!include`s, this includes integrations defining an IoT domain, e.g. `light`, `switch`, `sensor` as well as the `automation`, `script` and `template` integrations, if you give a different label to each one. Configuration for other integrations can instead be split up by using packages. To learn more about packages, see the [Packages](/docs/configuration/packages) page.
+Nesting `!include` statements (having an `!include` within a file that is itself `!include`d) will also work.
+
+Some integrations support multiple top-level `!include` statements. This includes integrations defining an IoT domain. For example, `light`, `switch`, or `sensor`; as well as the `automation`, `script`, and `template` integrations, if you give a different label to each one. 
+
+Configuration for other integrations can instead be split up by using packages. To learn more about packages, see the [Packages](/docs/configuration/packages) page.
+
+#### Top level keys
 
 Example of multiple top-level keys for the `light` platform.
 
@@ -189,11 +216,11 @@ learn more about packages, see the [Packages](/docs/configuration/packages) page
 
 That about wraps it up.
 
-If you have issues checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to our [Discord chat server][discord] and ask away.
+If you have issues, checkout `home-assistant.log` in the configuration directory as well as your indentations. If all else fails, head over to our [Discord chat server][discord] and ask away.
 
 ## Debugging configuration files
 
-If you have many configuration files, Home Assistant provides a CLI that allows you to see how it interprets them, each installation type has its own section in the common-tasks about this:
+If you have many configuration files, Home Assistant provides a CLI that allows you to see how it interprets them. Each installation type has its own section in the common-tasks about this:
 
 - [Operating System](/common-tasks/os/#configuration-check)
 - [Container](/common-tasks/container/#configuration-check)
@@ -509,3 +536,8 @@ automation ui: !include automations.yaml
 ```
 
 [discord]: https://discord.gg/c5DvZ4e
+
+## Related topics
+
+- [Example configuration files by the community](/examples/#example-configurationyaml)
+- [Using packages to organize configuration files](/docs/configuration/packages)

source/_docs/energy/faq.markdown

@@ -15,7 +15,7 @@ Think of this in a parallel to speed and distance: Power is the speed you are go
 
 Therefore Energy (kiloWatt-hour) is not an average of the Power you are consuming over a given period of time (the unit of the average power would be Watt or kiloWatt again). Energy is the integral (mathematical operation) of the Power function.
 
-This difference is very important as you need to use the proper entities in our Energy Panel.
+This difference is very important as you need to use the proper entities in our Energy dashboard.
 
 ## Creating an Energy Sensor out of a Power Sensor
 
@@ -29,9 +29,9 @@ If you are using a 3rd party device (e.g. not reading directly from your utility
 
 To accomplish such, you can use the [utility_meter integration](/integrations/utility_meter/). With this integration, you define as many tariffs as required (in accordance with your utility provider contract) and HA will be able to differentiate energy consumptions in each of the tariffs. Please note that each utility provider has its own time schedules for peak and off-peak and you are required to create an automation that switches the utility_meter entity from one tariff to the other.
 
-## The energy panel is not visible
+## The energy dashboard is not visible
 
-If you do not see the Energy panel in the sidebar, make sure you have not removed [`default_config:`](/integrations/default_config/) from your `configuration.yaml`. If you have, you will need to add the `energy:` integration manually.
+If you do not see the Energy dashboard in the sidebar, make sure you have not removed [`default_config:`](/integrations/default_config/) from your `configuration.yaml`. If you have, you will need to add the `energy:` integration manually.
 
 ## Troubleshooting missing entities
 

source/_includes/asides/dashboards_navigation.html

@@ -6,7 +6,7 @@
     <ul class="divided sidebar-menu">
       <li>{% active_link /dashboards/ Introduction %}</li>
       <li>
-        {% active_link /dashboards/dashboards/ Multiple Dashboards %}
+        {% active_link /dashboards/dashboards/ Multiple dashboards %}
       </li>
       <li>
         {% active_link /dashboards/views/ Views %}
@@ -21,7 +21,7 @@
   </div>
 
   <div class="section">
-    <h1 class="title delta">Views</h1>
+    <h1 class="title delta">View types</h1>
     <ul class="divided sidebar-menu">
       {% for element in elements %}
         {% if element.type == "view" %}
@@ -32,7 +32,7 @@
   </div>
 
   <div class="section">
-    <h1 class="title delta">Cards</h1>
+    <h1 class="title delta">Card types</h1>
     <ul class="divided sidebar-menu">
       {% for element in elements %}
         {% if element.type == "card" %}

source/_includes/common-tasks/flashing_m1s_otg.md

@@ -0,0 +1,47 @@
+## Flashing an ODROID-M1S
+
+Home Assistant can be flashed to an ODROID-M1S by connecting the device directly to your computer via the USB-OTG connection on the front of the board. 
+Unlike other ODROID boards, the M1S does not have a socket for an optional  <abbr title="embedded MultiMediaCard">eMMC</abbr> module. It also does not have a separate flash chip that holds a dedicated bootloader.
+Instead, the M1S has a build-in 64GB <abbr title="embedded MultiMediaCard">eMMC</abbr> soldered directly on the board that holds a bootloader by default. This guide will show you how to install the Home Assistant Operating System to the built-in <abbr title="embedded MultiMediaCard">eMMC</abbr>.
+
+<ins>**Warning:</ins> Installing Home Assistant OS replaces the firmware and <abbr title="secondary program loader">SPL</abbr> on the <abbr title="embedded MultiMediaCard">eMMC</abbr> with the mainline version provided by the Home Assistant OS. As a result, it is not possible to use the SD card with the EMMC2UMS image anymore, because the mainline <abbr title="secondary program loader">SPL</abbr> is not compatible with U-Boot in the EMMC2UMS image at this time (February 2024). This does not pose any problem for standard use, just makes it more complicated in case you want to return to the Hardkernel-provided OS (see [HK Recovery](#hk-recovery)).**
+
+### What you will need
+
+To flash your <abbr title="embedded MultiMediaCard">eMMC</abbr> using <abbr title="USB-On-The-Go">USB-OTG</abbr>, you will need the following items:
+
+- A small SD card
+- Another computer
+- USB 2.0 to micro-USB cable
+- the special Hardkernel eMMC-to-USB-mass-storage image
+
+### Boot into mass-storage mode
+
+(These steps are identical to the official [Hardkernel wiki](https://wiki.odroid.com/odroid-m1s/getting_started/os_installation_guide?redirect=1#install_over_usb_from_pc) page.)
+
+1. Download [ODROID-M1S_EMMC2UMS.img](https://dn.odroid.com/RK3566/ODROID-M1S/Installer/ODROID-M1S_EMMC2UMS.img).
+2. Use [balena Etcher](https://www.balena.io/etcher/) or another tool to flash the UMS utility onto an SD card.
+   - Use **Flash from file**. **Flash from URL** does not work on all systems.
+      (balena Etcher will complain that something went wrong during flashing. You can ignore this message)
+3. Plug-in that SD card to your ODROID-M1S and boot it.
+
+### Flashing Home Assistant M1S
+
+1. Download the latest stable version of Home Assistant OS for the [ODROID-M1S](https://github.com/home-assistant/operating-system/releases/download/{{site.data.version_data.hassos['odroid-m1s']}}/haos_odroid-m1s-{{site.data.version_data.hassos['odroid-m1s']}}.img.xz).
+2. Apart from the HAOS image to flash (M1S instead of N2+ version), you can follow the N2+ step-by-step flashing guide [HERE](/common-tasks/os/#flashing-home-assistant).
+
+
+#### _HK Recovery_
+
+If you want to restore your M1S back into Hardkernel's initial state, you will have to restore the HK's bootloader.
+A reliable way of reflashing the eMMC with an operating system of your choice is to use Home Assistant OS to flash the EMMC2UMS image which turns the ODROID-M1S into USB Mass Storage device. Once you have flashed the EMMC2UMS image, you can flash any OS again. You will need a micro USB cable to connect ODROID-M1S to PC.
+
+Note: This commands will render your current Home Assistant OS installation unbootable!
+
+Use the local terminal (HDMI/keyboard) to access the system console. On the Home Assistant CLI (command line), enter `login` to enter the root shell and use `curl` to download an image and `dd` it to the eMMC block device:
+
+```sh
+curl https://dn.odroid.com/RK3566/ODROID-M1S/Installer/ODROID-M1S_EMMC2UMS.img | dd of=/dev/mmcblk0
+```
+
+This way, the device will start in the UMS mode on the next boot with the SD card removed. Follow the [Install over USB from PC](https://wiki.odroid.com/odroid-m1s/getting_started/os_installation_guide#install_over_usb_from_pc) to install a different operating system.

source/_includes/installation/operating_system.md

@@ -12,26 +12,26 @@ Follow this guide if you want to get started with Home Assistant easily or if yo
 
 You will need a few things to get started with installing Home Assistant. The links below lead to Ameridroid. If you’re not in the US, you should be able to find these items in web stores in your country.
 
-To get started, we suggest the ODROID N2+, the board that powers our [Home Assistant Blue](/blue/), or the ODROID M1.
+To get started, we suggest the ODROID-N2+, the board that powers our [Home Assistant Blue](/blue/), or the ODROID-M1.
 
-If unavailable, we also recommend the [ODROID C4](https://ameridroid.com/products/odroid-c4?ref=eeb6nfw07e).
+If unavailable, we also recommend the [ODROID-C4](https://ameridroid.com/products/odroid-c4?ref=eeb6nfw07e).
 
 Home Assistant bundles (US market):
 
 The bundles come with Home Assistant pre-installed.
 
-- [ODROID N2+: 2 GB RAM / 16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44748729286935?ref=eeb6nfw07e)
+- [ODROID-N2+: 2 GB RAM / 16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44748729286935?ref=eeb6nfw07e)
-- [ODROID N2+: 4 GB RAM / 64 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44748729221399?ref=eeb6nfw07e)
+- [ODROID-N2+: 4 GB RAM / 64 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44748729221399?ref=eeb6nfw07e)
-- ODROID M1: 4 GB RAM / 256 GB NVMe / [16 GB µSD](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44929573028119?ref=eeb6nfw07e) or [16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940567831?ref=eeb6nfw07e)
+- ODROID-M1: 4 GB RAM / 256 GB NVMe / [16 GB µSD](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44929573028119?ref=eeb6nfw07e) or [16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940567831?ref=eeb6nfw07e)
-- ODROID M1: 8 GB RAM / 256 GB NVMe / [16 GB µSD](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44929573093655?ref=eeb6nfw07e) or [16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940633367?ref=eeb6nfw07e)
+- ODROID-M1: 8 GB RAM / 256 GB NVMe / [16 GB µSD](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44929573093655?ref=eeb6nfw07e) or [16 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940633367?ref=eeb6nfw07e)
-- [ODROID M1: 8 GB RAM / 1 TB NVMe / 64 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940698903?ref=eeb6nfw07e)
+- [ODROID-M1: 8 GB RAM / 1 TB NVMe / 64 GB eMMC](https://ameridroid.com/products/odroid-n2-home-assistant-blue-bundle-limited-edition?variant=44994940698903?ref=eeb6nfw07e)
 
 Variants without pre-installed Home Assistant:
 
-- ODROID N2+, [2 GB RAM](https://ameridroid.com/products/odroid-n2-plus?variant=40371828719650?ref=eeb6nfw07e) or [4 GB RAM](https://ameridroid.com/products/odroid-n2-plus?variant=40371828752418?ref=eeb6nfw07e)
+- ODROID-N2+, [2 GB RAM](https://ameridroid.com/products/odroid-n2-plus?variant=40371828719650?ref=eeb6nfw07e) or [4 GB RAM](https://ameridroid.com/products/odroid-n2-plus?variant=40371828752418?ref=eeb6nfw07e)
-- [ODROID C4](https://ameridroid.com/products/odroid-c4?ref=eeb6nfw07e)
+- [ODROID-C4](https://ameridroid.com/products/odroid-c4?ref=eeb6nfw07e)
-- [ODROID M1](https://ameridroid.com/products/odroid-M1?ref=eeb6nfw07e)
+- [ODROID-M1](https://ameridroid.com/products/odroid-M1?ref=eeb6nfw07e)
-
+- ODROID-M1S, [4 GB RAM](https://ameridroid.com/products/odroid-m1s?variant=47425396474135?ref=eeb6nfw07e) or [8 GB RAM](https://ameridroid.com/products/odroid-m1s?variant=47425396506903?ref=eeb6nfw07e)
 - [Power Supply](https://ameridroid.com/products/12v-2a-power-supply-plug?ref=eeb6nfw07e)
 - [CR2032 Coin Cell](https://ameridroid.com/products/rtc-bios-battery?ref=eeb6nfw07e)
 - [eMMC Module](https://ameridroid.com/products/emmc-module-n2-linux-red-dot?ref=eeb6nfw07e)
@@ -162,9 +162,11 @@ Use this method only if Method 1 does not work for you.
    - Back up your data before continuing with the next step.
 2. Attach the Home Assistant boot medium ({{site.installation.types[page.installation_type].installation_media}}) to your computer.
     {% if page.installation_type == 'odroid' %}
-      If you are using ODROID M1, note that booting from NVMe is not supported. If you want to boot from eMMC, [update the firmware](https://github.com/home-assistant/operating-system/blob/dev/Documentation/boards/hardkernel/odroid-m1.md) before installing the image.
+      If you are using ODROID-M1, note that booting from NVMe is not supported. If you want to boot from eMMC, [update the firmware](https://github.com/home-assistant/operating-system/blob/dev/Documentation/boards/hardkernel/odroid-m1.md) before installing the image.
 
-      If you are using a [Home Assistant Blue](/blue) or ODROID N2+, you can [attach your device directly](/common-tasks/os/#flashing-an-odroid-n2).
+      If you are using a [Home Assistant Blue](/blue) or ODROID-N2+, you can [attach your device directly](/common-tasks/os/#flashing-an-odroid-n2).
+
+      If you are using an ODROID-M1S, you need to follow this guide to [boot your device into UMS mode](/common-tasks/os/#flashing-an-odroid-m1s).
     {% endif %}
 3. Download and start <a href="https://www.balena.io/etcher" target="_blank">Balena Etcher</a>. You may need to run it with administrator privileges on Windows.
 4. Download the image to your computer.
@@ -182,7 +184,9 @@ Use this method only if Method 1 does not work for you.
     ```
 
     {% if variant.key == "odroid-n2" %}
-    [Guide: Flashing Odroid-N2 using OTG-USB](/hassio/flashing_n2_otg/)
+    [Guide: Flashing ODROID-N2 using OTG-USB](/hassio/flashing_n2_otg/)
+    {% elsif variant.key == "odroid-m1s" %}
+    [Guide: Flashing ODROID-M1S using OTG-USB](/hassio/flashing_m1s_otg/)
     {% elsif variant.key == "rpi4" or variant.key == "rpi3" %}
       *(64-bit is recommended)*
     {% endif %}
@@ -212,7 +216,7 @@ Use this method only if Method 1 does not work for you.
 9. Select **Flash!** to start writing the image.
    - If the operation fails, decompress the .xz file and try again.
 ![Screenshot of the Etcher software showing the Flash button highlighted.](/images/installation/etcher5.png)
-1.  When Balena Etcher has finished writing the image, you will see a confirmation.
+   - When Balena Etcher has finished writing the image, you will see a confirmation.
 ![Screenshot of the Etcher software showing that the installation has completed.](/images/installation/etcher6.png)
 
 ### Start up your {{site.installation.types[page.installation_type].board}}

source/_integrations/backup.markdown

@@ -21,7 +21,7 @@ If you use Home Assistant Operating System or Home Assistant Supervised, [back u
 </div>
 
 
-### Manual configuration
+## Manual configuration
 
 The backup integration is by default enabled. If you've disabled or removed the [`default_config:`](/integrations/default_config/) line from your configuration the following example shows you how to enable this integration manually:
 
@@ -53,7 +53,7 @@ Example service call:
 service: backup.create
 ```
 
-## Example: Backing up every night at 3:00 AM
+### Example: Backing up every night at 3:00 AM
 
 
 This is a YAML example for an automation that initiate a backup every night
@@ -69,3 +69,18 @@ automation:
       alias: "Create backup now"
       service: backup.create
 ```
+
+## Restoring a backup
+
+<div class="note">
+
+If you use Home Assistant Operating System or Home Assistant Supervised, [the restore functionality is already built-in](/common-tasks/os/#restoring-a-backup).
+
+</div>
+
+Backups created via the **Backup** integration are located in your `/config/backups` directory. The Home Assistant Container installation will typically mount this directory via `docker-compose.yml` or `docker run` to a directory of your choice.  
+For Container and Core installations, there is currently no built-in way to restore a backup. However, a Home Assistant backup is just a tar file of the `/config` directory, plus some metadata. To manually restore a backup, you can use the following:
+
+```shell
+tar -xOf <backup_tar_file> "./homeassistant.tar.gz" | tar --strip-components=1 -zxf - -C <restore_directory>
+```

source/_integrations/calendar.markdown

@@ -4,7 +4,8 @@ description: Instructions on how to integrate calendars within Home Assistant.
 ha_release: 0.33
 ha_domain: calendar
 ha_quality_scale: internal
-ha_category: []
+ha_category:
+  - Calendar
 ha_codeowners:
   - '@home-assistant/core'
 ha_integration_type: entity
@@ -16,13 +17,10 @@ dashboard and can be used with automations.
 
 This page does not provide instructions on how to create calendar
 entities. Please see the ["Calendar" category](/integrations/#calendar) on the
-integrations page to find integration offering calendar entities.
+integrations page to find integrations offering calendar entities. For example, [Local Calendar](/integrations/local_calendar/) is a fully local integration to create calendars and events within your Home Assistant instance or other integrations work with other services providing calendar data.
 
 {% include integrations/building_block_integration.md %}
 
-A calendar {% term entity %} has a {% term state %} and attributes representing the next event (only).
-A calendar {% term trigger %} is much more flexible, has fewer limitations, and is
-recommended for automations instead of using the entity state.
 
 ## Viewing and managing calendars
 
@@ -43,6 +41,9 @@ event's start or end. Review the [Automating Home Assistant](/getting-started/au
 getting started guide on automations or the [Automation](/docs/automation/)
 documentation for full details.
 
+Calendar {% term triggers %} are the best way to automate based on calendar events.
+A calendar {% term entity %} can also be used to automate based on its state, but these are limited and attributes only represent the next event.
+
 {% my automations badge %}
 
 ![Screenshot Trigger](/images/integrations/calendar/trigger.png)

source/_integrations/daikin.markdown

@@ -21,9 +21,11 @@ ha_platforms:
 ha_integration_type: integration
 ---
 
-<p class='note warning'>
+<div class='note warning'>
-  Daikin has removed their local API in newer products. They offer a cloud API accessible only under NDA, which is incompatible with open source. This affects units fitted with the BRP069C4x wifi adapter. Units listed under Supported Hardware below continue to have access to local control. Additionally the older but commonly available BRP072A42 adapter can be fitted to most if not all newer units for access to local control.
+
-</p>
+Daikin has removed their local API in newer products. They offer a Onecta cloud API for controlling Daikin devices through the cloud, see the [Daikin Europe Developer Portal](https://developer.cloud.daikineurope.com) for more details. This affects units fitted with the BRP069C4x wifi adapter. Units listed under Supported Hardware below continue to have access to local control. Additionally the older but commonly available BRP072A42 adapter can be fitted to most if not all newer units for access to local control.
+
+</div>
 
 The **Daikin** {% term integration %} integrates Daikin air conditioning systems into Home Assistant.
 

source/_integrations/fan.markdown

@@ -126,7 +126,7 @@ automation:
 
 ### Service `fan.turn_on`
 
-Turn fan device on. This is only supported if the fan device supports being turned off.
+Turn fan device on. This is only supported if the fan device supports being turned off. See a similar example under `fan.turn_off`.
 
 | Service data attribute | Optional | Description |
 | ---------------------- | -------- | ----------- |
@@ -151,7 +151,7 @@ automation:
     platform: time
     at: "07:15:00"
   action:
-    - service: fan.set_speed
+    - service: fan.turn_off
       target:
         entity_id: fan.kitchen
       data:

source/_integrations/file_upload.markdown

@@ -11,3 +11,5 @@ ha_category: []
 ---
 
 The file upload integration allows various features in the frontend to upload files.
+
+{% include integrations/building_block_integration.md %}

source/_integrations/google_translate.markdown

@@ -40,7 +40,24 @@ You can also use supported BCP 47 tags like the below or the 2-2 digit format fo
 | es-es   | es       | es     |
 | es-us   | es       | com    |
 
-## Service say
+
+## Service speak
+
+The `tts.speak` service is the modern way to use Google translate TTS action. Add the `speak` action, select the entity for your Google translate TTS (it's named for the language you created it with), select the media player entity or group to send the TTS audio to, and enter the message to speak.
+
+For more options about `speak`, see the Speak section on the main [TTS](/integrations/tts/#service-speak) building block page.
+
+In YAML, your action will look like this:
+```yaml
+service: tts.speak
+target:
+  entity_id: tts.google_en_com
+data:
+  media_player_entity_id: media_player.giant_tv
+  message: Hello, can you hear me now?
+```
+
+## Service say (legacy)
 
 <div class='note'>
 

source/_integrations/matter.markdown

@@ -80,7 +80,6 @@ One of the great features of Matter is the so-called _Multi Fabric_ feature: you
 
 For devices where Home Assistant provides a native integration (with local API), Matter may not be the best option. Matter, being a universal standard, might not have the nitty-gritty features that come with a product-specific protocol. A good example is Philips Hue: the communication over Matter only provides the basic controls over lights, while the official [Hue integration](/integrations/hue) brings all Hue unique features like (dynamic) scenes, entertainment mode, etc.
 
-
 ## Supported installation types
 
 It is recommended to run the Matter add-on on Home Assistant OS. This is currently the only supported option. Other installation types are without support and at your own risk.
@@ -180,6 +179,23 @@ This guide describes how to add a new device. This will use the Bluetooth connec
 
 <lite-youtube videoid="Fk0n0r0eKcE" videotitle="Add Matter device via Android app in Home Assistant"></lite-youtube>
 
+### Troubleshooting the installation
+
+Check these steps if you are experiencing issues when trying to add a Matter device using the Home Assistant Companion app on your Android phone.
+
+#### Symptom
+
+While trying to add the Matter device, I get an error stating that *Matter is currently unavailable*. 
+
+#### Remedy
+
+This could mean that not all required Matter modules that are needed by the Home Assistant Companion App have been downloaded yet. Try the following steps:
+
+1. Wait up to 24 hours for the Google Play services to download the necessary Matter modules.
+2. If this did not work, try reinstalling the Home Assistant Companion app.
+3. If this did not work, try installing the Google Home app. Technically this is not required, but it might trigger another installation attempt of the Matter modules.
+4. Refer to this [Troubleshooting Guide from Google](https://developers.home.google.com/matter/verify-services).
+
 ## Sharing a device from another platform with Home Assistant
 
 Use one of these methods if your Matter device was added to Apple Home or Google Home and you want to control it from both Apple or Google Home and Home Assistant.

source/_integrations/proximity.markdown

@@ -24,6 +24,10 @@ Some examples of its use include:
 
 {% include integrations/config_flow.md %}
 
+<div class="note">
+When adding the **Proximity** integration, you are prompted to define the **Tolerance distance**. The tolerance distance is used to calculate the direction of travel in meters (m) to filter out small GPS coordinate changes.
+</div>
+
 ## Sensors
 
 The following sensor entities will be created.

source/_integrations/reolink.markdown

@@ -35,7 +35,7 @@ On the Reolink device, a user account with admin privileges is needed for the pr
 {% include integrations/option_flow.md %}
 {% configuration_basic %}
 Protocol:
-  description: Switch between RTSP, RTMP or FLV streaming protocol.
+  description: Switch between <abbr title="real-time streaming protocol">RTSP</abbr>, <abbr title="real-time messaging protocol">RTMP</abbr>, or <abbr title="flash video">FLV</abbr> streaming protocol. <abbr title="real-time streaming protocol">RTSP</abbr> supports 4K streams (h265 encoding) while <abbr title="real-time messaging protocol">RTMP</abbr> and <abbr title="flash video">FLV</abbr> do not. <abbr title="flash video">FLV</abbr> is the least demanding on the camera.
 {% endconfiguration_basic %}
 
 ## Asterisk (*) next to entities listed in this documentation
@@ -332,11 +332,13 @@ Then power up the camera while pointing it at the QR code. It takes about a minu
 - Setting a static IP address for Reolink cameras/NVRs in your router is advisable to prevent (temporal) connectivity issues when the IP address changes.
 - Do not set a static IP in the Reolink device itself, but leave the **Connection Type** on **DHCP** under **Settings** > **Network** > **Network Information** > **Set Up**. If you set it to **static** on the Reolink device itself, this is known to cause incorrect DHCP requests on the network. The incorrect DHCP request causes Home Assistant to use the wrong IP address for the camera, resulting in connection issues. The issue originates from the Reolink firmware, which keeps sending DCHP requests even when you set a static IP address in the Reolink device.
 - Reolink cameras can support a limited amount of simultaneous connections. Therefore using third-party software like Frigate, Blue Iris, or Scrypted, or using the ONVIF integration at the same time can cause the camera to drop connections. This results in short unavailabilities of the Reolink entities in Home Assistant. Especially when the connections are coming from the same device (IP) where Home Assistant is running, the Reolink cameras can get confused, dropping one connection in favor of the other originating from the same host IP. If you experience disconnections/unavailabilities of the entities, please first temporarily shut down the other connections (like Frigate) to diagnose if that is the problem. If that is indeed the problem, you could try moving the third-party software to a different host (IP address) since that is known to solve the problem most of the time. You could also try switching the protocol to FLV on Home Assistant and/or the third-party software, as that is known to be less resource-intensive on the camera.
+- If the Reolink entities go to unavailable for short periods, the camera may be overloaded with requests resulting in short connection drops. To resolve this, first, check if the integration is using `ONVIF push` instead of `ONVIF long polling` (resource intensive) or `Fast polling` (very resource intensive), see the [Reducing latency of motion events](#reducing-latency-of-motion-events) section. Moreover, try switching to the <abbr title="flash video">FLV</abbr> streaming protocol which is the least resource-intensive for the camera, see the [options](#options) section.
 - If the integration and the browser can't connect to the camera even after you enable the HTTP/HTTPS ports, try to create a new user on the camera; that fixes the problem in some cases.
 
 ### Reducing latency of motion events
 
 ONVIF push will result in slightly faster state changes of the binary motion/AI event sensors than ONVIF long polling.
+Moreover, ONVIF push is less demanding for the camera than ONVIF long polling or fast polling, resulting in potentially less connection issues.
 However, ONVIF push has some additional network configuration requirements:
 
 - Reolink products can not push motion events to an HTTPS address (SSL).

source/_integrations/script.markdown

@@ -122,11 +122,6 @@ sequence:
   type: list
 {% endconfiguration %}
 
-### Video tutorial
-This video tutorial explains how scripts work, how to use fields in scripts, and how to use response variables in scripts.
-
-<lite-youtube videoid="vD_xckjQxRk" videotitle="Mastering Scripts in Home Assistant: A Comprehensive Guide" posterquality="maxresdefault"></lite-youtube>
-
 ### Script modes
 
 Mode | Description
@@ -140,10 +135,133 @@ Mode | Description
   <img src='/images/integrations/script/script_modes.jpg'>
 </p>
 
-### Full configuration
+### Passing variables to scripts
+
+As part of the service, variables can be passed along to a script so they become available within templates in that script.
+
+To configure a script to accept variables using the UI, the variables can be added as fields in the script editor.
+1. In the script editor, in the 3-dots menu, select **Add fields**.
+2. A new section called **Fields** is added between the basic information and **Sequence** sections.
+3. Enter a name and choose type and options of each desired field.
+4. Fields set up here will be shown in other UI editors, such as in an automation that calls the script as inputs depending on the type of field.
+5. To use the field data, use them as templates using the **Field key name** when they were added, as shown in the example below.
+
+Using the variables in the script requires the use of templates:
+
+{% raw %}
+```yaml
+# Example configuration.yaml entry
+script:
+  notify_pushover:
+    description: "Send a pushover notification"
+    fields:
+      title:
+        description: "The title of the notification"
+        example: "State change"
+      message:
+        description: "The message content"
+        example: "The light is on!"
+    sequence:
+      - condition: state
+        entity_id: switch.pushover_notifications
+        state: "on"
+      - service: notify.pushover
+        data:
+          title: "{{ title }}"
+          message: "{{ message }}"
+```
+{% endraw %}
+
+Aside from the automation editor UI, variables can be passed to scripts within the service data. This can be used either by calling the script directly or the generic `script.turn_on` service. The difference is described in [Waiting for Script to Complete](#waiting-for-script-to-complete). All service data will be made available as variables in templates, even if not specified as fields in the script. This example shows how to call the script directly:
+
+{% raw %}
+```yaml
+# Example configuration.yaml entry
+automation:
+  trigger:
+    platform: state
+    entity_id: light.bedroom
+    from: "off"
+    to: "on"
+  action:
+    service: script.notify_pushover
+    data:
+      title: "State change"
+      message: "The light is on!"
+```
+{% endraw %}
+
+This example shows using `script.turn_on` service:
+
+{% raw %}
+```yaml
+# Example configuration.yaml entry
+automation:
+  trigger:
+    platform: state
+    entity_id: light.bedroom
+    from: "off"
+    to: "on"
+  action:
+    service: script.turn_on
+    target:
+      entity_id: script.notify_pushover
+    data:
+      variables:
+        title: "State change"
+        message: "The light is on!"
+```
+{% endraw %}
+
+
+
+<div class='note'>
+
+Script variables that may be used by templates include the following: 
+- those provided from the configuration as fields
+- those that are passed as data when started from a service, 
+- the `this` variable the value of which is a dictionary of the current script's state.
+
+</div>
+
+### Waiting for Script to Complete
+
+When calling a script "directly" (e.g., `script.NAME`) the calling script will wait for the called script to finish.
+If any errors occur that cause the called script to abort, the calling script will be aborted as well.
+
+When calling a script (or multiple scripts) via the `script.turn_on` service the calling script does _not_ wait. It starts the scripts, in the order listed, and continues as soon as the last script is started.
+Any errors that occur in the called scripts that cause them to abort will _not_ affect the calling script.
+
+<p class='img'>
+  <img src='/images/integrations/script/script_wait.jpg'>
+</p>
+
+Following is an example of the calling script not waiting. It performs some other operations while the called script runs "in the background." Then it later waits for the called script to complete via a `wait_template`.
+This technique can also be used for the calling script to wait for the called script, but _not_ be aborted if the called script aborts due to errors.
 
 {% raw %}
 
+```yaml
+script:
+  script_1:
+    sequence:
+      - service: script.turn_on
+        target:
+          entity_id: script.script_2
+      # Perform some other steps here while second script runs...
+      # Now wait for called script to complete.
+      - wait_template: "{{ is_state('script.script_2', 'off') }}"
+      # Now do some other things...
+  script_2:
+    sequence:
+      # Do some things at the same time as the first script...
+```
+
+{% endraw %}
+
+### Full configuration
+
+{% raw %}
 ```yaml
 script: 
   wakeup:
@@ -187,115 +305,11 @@ script:
         target:
           entity_id: "{{ turn_on_entity }}"
 ```
-
 {% endraw %}
 
-### Passing variables to scripts
 
-As part of the service, variables can be passed along to a script so they become available within templates in that script.
+## Video tutorial
 
-There are two ways to achieve this. One way is using the generic `script.turn_on` service. To pass variables to the script with this service, call it with the desired variables:
+This video tutorial explains how scripts work, how to use fields in scripts, and how to use response variables in scripts.
 
-```yaml
+<lite-youtube videoid="vD_xckjQxRk" videotitle="Mastering Scripts in Home Assistant: A Comprehensive Guide" posterquality="maxresdefault"></lite-youtube>
-# Example configuration.yaml entry
-automation:
-  trigger:
-    platform: state
-    entity_id: light.bedroom
-    from: "off"
-    to: "on"
-  action:
-    service: script.turn_on
-    target:
-      entity_id: script.notify_pushover
-    data:
-      variables:
-        title: "State change"
-        message: "The light is on!"
-```
-
-The other way is calling the script as a service directly. In this case, all service data will be made available as variables. If we apply this approach on the script above, it would look like this:
-
-```yaml
-# Example configuration.yaml entry
-automation:
-  trigger:
-    platform: state
-    entity_id: light.bedroom
-    from: "off"
-    to: "on"
-  action:
-    service: script.notify_pushover
-    data:
-      title: "State change"
-      message: "The light is on!"
-```
-
-Using the variables in the script requires the use of templates:
-
-{% raw %}
-
-```yaml
-# Example configuration.yaml entry
-script:
-  notify_pushover:
-    description: "Send a pushover notification"
-    fields:
-      title:
-        description: "The title of the notification"
-        example: "State change"
-      message:
-        description: "The message content"
-        example: "The light is on!"
-    sequence:
-      - condition: state
-        entity_id: switch.pushover_notifications
-        state: "on"
-      - service: notify.pushover
-        data:
-          title: "{{ title }}"
-          message: "{{ message }}"
-```
-
-<div class='note'>
-
-Script variables that may be used by templates include those provided from the configuration, those that are passed when started from a service and the `this` variable whose value is a dictionary of the current script's state.
-
-</div>
-
-{% endraw %}
-
-### Waiting for Script to Complete
-
-When calling a script "directly" (e.g., `script.NAME`) the calling script will wait for the called script to finish.
-If any errors occur that cause the called script to abort, the calling script will be aborted as well.
-
-When calling a script (or multiple scripts) via the `script.turn_on` service the calling script does _not_ wait. It starts the scripts, in the order listed, and continues as soon as the last script is started.
-Any errors that occur in the called scripts that cause them to abort will _not_ affect the calling script.
-
-<p class='img'>
-  <img src='/images/integrations/script/script_wait.jpg'>
-</p>
-
-Following is an example of the calling script not waiting. It performs some other operations while the called script runs "in the background." Then it later waits for the called script to complete via a `wait_template`.
-This technique can also be used for the calling script to wait for the called script, but _not_ be aborted if the called script aborts due to errors.
-
-{% raw %}
-
-```yaml
-script:
-  script_1:
-    sequence:
-      - service: script.turn_on
-        target:
-          entity_id: script.script_2
-      # Perform some other steps here while second script runs...
-      # Now wait for called script to complete.
-      - wait_template: "{{ is_state('script.script_2', 'off') }}"
-      # Now do some other things...
-  script_2:
-    sequence:
-      # Do some things at the same time as the first script...
-```
-
-{% endraw %}

source/_integrations/telegram.markdown

@@ -119,6 +119,10 @@ $ python3
 If you want to add new chat IDs then you will need to disable the active configuration to actually see the result with the IDs, otherwise you may only get empty results array.
 </div>
 
+
+**Method 4:** You can also get the chat ID from the Home Assistant logs. If you have set up the bot already, you can send a message to your bot from an unauthorized ID and you will see an error entry in the log containing the ID.  
+[![Open your Home Assistant instance and show your Home Assistant logs.](https://my.home-assistant.io/badges/logs.svg)](https://my.home-assistant.io/redirect/logs/?)
+
 ## Configuration
 
 To enable Telegram notifications in your installation, add the following to your `configuration.yaml` file:

source/_integrations/todo.markdown

@@ -17,6 +17,8 @@ dashboard for tracking items and whether or not they have been completed.
 
 {% include integrations/building_block_integration.md %}
 
+For example, [Local To-do](/integrations/local_todo/) is a fully local integration to create to-do lists and tasks within your Home Assistant instance, [Shopping list](/integrations/shopping_list) specifically for shopping that can be added to with Assist, or other integrations work with online services providing to-do list data.
+
 ## Viewing and managing to-do lists
 
 Each to-do list is represented as its own entity in Home Assistant and can be

source/_integrations/tts.markdown

@@ -18,6 +18,8 @@ Text-to-speech (TTS) enables Home Assistant to speak to you.
 
 {% include integrations/building_block_integration.md %}
 
+See all [TTS integrations](https://www.home-assistant.io/integrations/#text-to-speech) using this building block for ways to use it in your automations. If you are using the Home Assistant voice assistant, [Assist](https://www.home-assistant.io/voice_control/), Assist is using TTS when replying to you. Another way to use TTS is by using [TTS with Home Assistant Cloud](https://www.nabucasa.com/config/tts/). 
+
 ## Services
 
 ### Service speak
@@ -141,3 +143,11 @@ The Google cast devices (Google Home, Chromecast, etc.) present the following pr
 - They do not work with URLs that contain hostnames established by local naming means. Let's say your Home Assistant instance is running on a machine made known locally as `ha`. All your machines on your local network are able to access it as `ha`. However, try as you may, your cast device won't download the media files from your `ha` machine. That's because your cast device ignores your local naming setup. In this example, the `say` service creates a URL like `http://ha/path/to/media.mp3` (or `https://...` if you are using SSL). If you are _not_ using SSL then setting an internal URL that contains the IP address of your server works around this issue. By using an IP address, the cast device does not have to resolve the hostname.
 
 - If you are using SSL (e.g., `https://yourhost.example.org/...`) then you _must_ use the hostname in the certificate (e.g., `external_url: https://yourhost.example.org`). You cannot use an IP address since the certificate won't be valid for the IP address, and the cast device will refuse the connection.
+
+### Related topics
+
+- [List of integrations using the TTS integration](https://www.home-assistant.io/integrations/#text-to-speech)
+- [TTS with Home Assistant Cloud](https://www.nabucasa.com/config/tts/)
+- [Google Translate TTS](https://www.home-assistant.io/integrations/google_translate/)
+- [Microsoft TTS](https://www.home-assistant.io/integrations/microsoft/)
+- [Home Assistant Assist](https://www.home-assistant.io/voice_control/)

source/_posts/2024-03-04-dashboard-chapter-1.markdown

@@ -0,0 +1,266 @@
+---
+layout: post
+title: "A Home-Approved Dashboard chapter 1: Drag-and-drop, Sections view, and a new grid system design!"
+description: "Wow! At long last!! The stars have aligned, and our experimental drag-and-drop feature for dashboards is finally here!"
+date: 2024-03-04 00:00:01
+date_formatted: "March 4, 2024"
+author: Madelena Mak
+comments: true
+categories: Dashboard
+og_image: /images/blog/2024-03-dashboard-chapter-1/banner.png
+---
+
+Wow! At long last!! The stars have aligned, and our experimental drag-and-drop feature for dashboards is finally here! 🥲
+
+Home Assistant strives to be the best smart home platform, and a smart home allows its residents to automate, control, observe, and anticipate the comfort, security, and various conveniences of their home. Besides voice assistants, dashboards are also a great way to help users do just that!
+
+Therefore, we have been working hard to make customization and organization of dashboards as easy and intuitive as possible, and to create a default dashboard that will be more useful, user-friendly, and relevant right out of the box. [Matthias](https://github.com/matthiasdebaat) and [I](https://github.com/madelena) teamed up in April last year to tackle this problem together, and we called this series of improvements over our current dashboard “Project Grace”, named after the influential and brilliant late [Admiral Grace Hopper](https://www.nationalww2museum.org/war/articles/grace-hopper-woman-computer).
+
+After months of user research and ideation to ensure that our design is [“home-approved”](https://building.open-home.io/open-home-approval-factor/#home-approval-factor) - to be easy and intuitive to use for you, your family, your guests, your roommates, and more - we are happy to share the first fruit of our success in the upcoming release 2024.3, with the help of [Paul](https://github.com/piitaya) and of course the wonderful frontend team. We hope that these features will help you take the dream dashboard for you and your home from idea to reality much faster and much more easily.
+
+For those of you who are curious about the features and the design thinking behind them, read on and check out our [special livestream](https://www.youtube.com/watch?v=XyBy0ckkiDU) last week. You can also try out our updated [demo](https://demo.home-assistant.io/#/lovelace/home) and get involved by [joining the Home Assistant User Testing Group](http://home-assistant.io/join-research)! And last of all, thank you for supporting our efforts by [subscribing to Home Assistant Cloud](https://www.nabucasa.com)!
+
+<p class='img'>
+    <lite-youtube videoid="XyBy0ckkiDU" videotitle="A Home-Approved Dashboard - Chapter 1: What about Grace?"></lite-youtube>
+</p>
+
+Enjoy!
+
+~ Madelena 🥳
+
+<!--more-->
+
+## What is Project Grace?
+
+Grace was the codename we used for the series of improvements to be built on top of [Lovelace], the framework for our dashboards. We aim to preserve the strengths of Lovelace, such as its flexibility and extensibility, and to mitigate its weaknesses, such as its steep learning curve, its lack of scalability, as well as the poor responsiveness of its layouts.
+
+## The three-layout problem
+
+<p class='img'>
+    <img src='/images/blog/2024-03-dashboard-chapter-1/layout-types.png' alt='The three basic view layouts: Panel, Sidebar, and Masonry'>
+    The three basic view layouts: Panel, Sidebar, and Masonry
+</p>
+
+Our dashboard came with 3 default [view layout types](https://www.home-assistant.io/dashboards/views/#type) by default: Panel, which is simply one card covering the entire view; Sidebar, which is a two-column layout for cards; and [Masonry], which is the most robust of them all.
+
+While it is excellent at creating a tightly-packed screen space-saving dashboard, Masonry lays out cards in a logic that may not be immediately clear and predictable to many users, which leads to a frustrating user experience to create and customize the layout of the cards. And as the layout logic depends on the height of each card, the varying heights of the cards available for our dashboards become a blessing and a curse: Even a difference in height of 1 pixel would mean a card one would guess to be displayed on the leftmost column getting shifted all the way to the right.
+
+<p class='img'>
+    <img src='/images/dashboards/masonry.png' alt='Image showing how masonry arranges cards based on size.'>
+    Masonry arranges cards based on size.
+</p>
+
+What’s more, unlike most other smart home apps, Home Assistant prides itself on Choice. In terms of dashboard view layouts, Choice means that dashboards should be able to be displayed on any screens that are the most convenient to our users - whether it’s a phone, a tablet, a large monitor, or other display devices. While the Masonry layout is great at making neat walls of cards, as its name also implies, it is a wall of cards which does not care whether the bricks are laid, thus the muscle memory of where users remember the cards will be lost every time the dashboard is displayed on another screen.
+
+<p class='img'>
+    <img src='/images/blog/2024-03-dashboard-chapter-1/layout-masonry-problem.png' alt='Masonry does not care about where exactly cards are placed when the screen size changes.'>
+    Masonry does not care about where exactly cards are placed when the screen size changes.
+</p>
+
+For the past few years, we tried to create a more intuitive solution to rearrange the cards laid out by Masonry but ultimately the solutions did not work well for multiple screen sizes. Meanwhile, our users come up with solutions of their own, with many avoiding our default view layouts so that they can create a more predictable and memorable dashboard. As it turns out, “drag and drop” is not just an engineering problem; it is also a design problem.
+
+To solve these problems with our layout, we realized that the Masonry layout, compatibility with multiple screen sizes, and easy “drag and drop” rearrangement of cards cannot co-exist. Over the past year, we ideated and identified a few solutions, namely:
+
+1. [a new Sections view layout](#the-new-sections-view)
+2. [a design grid system](#the-grid-system), and
+3. [a “Z-Grid” auto-rearranging pattern](#drag-and-drop-rearrangement-of-cards-and-sections).
+
+Let's dive in each solution and learn how they work together to make your dashboards easier to customize and use!
+
+## The new Sections view
+
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/sections-case-studies.png" alt="Case studies of our users' dashboards"/>
+    Case studies of our users' dashboards
+</p>
+
+Throughout this project, we have looked at dozens of different dashboards created by you and posted on our discussion boards. One thing we notice is that our more advanced users are all naturally drawn to creating “sections”, groups of different cards delineated by a group title, manually with [grids](https://www.home-assistant.io/dashboards/grid/) and [markdown](https://www.home-assistant.io/dashboards/markdown/) cards.
+
+Home Assistant dashboards are robust and packed with information, and our users often place dozens of cards for all sorts of buttons, switches, graphs, indicators, and more. By grouping cards into “sections”, our users can reduce the number of items they need to scan through when they are looking for a certain card, as they will be able to look for the relevant group title first and then reduce the scope to scan that particular group for the information. And by packing cards in a section into a grid card, the relative positions of the cards within a section are affected by changes in screen sizes, and so the spatial memory of the cards are retained, leading to a faster and less cumbersome experience.
+
+<p class='img'>
+    <img width="66%" src="/images/blog/2024-03-dashboard-chapter-1/sections-section-example.png" alt="Example of a dashboard section"/>
+    Example of a dashboard section
+</p>
+
+For our new Sections view, we are making these sections as the base unit of the view and we are streamlining its creation and editing procedures. Users will not need to fiddle around with grid cards and markdown cards to assemble a section manually, and instead a section now comes with all those amenities and much more.
+
+### Getting started with Sections
+
+<div class='note warning'>
+    The new Sections view is experimental! Please do not build your daily dashboard on top of it yet!
+</div>
+
+<p class='img'>
+    <img width="66%" src="/images/blog/2024-03-dashboard-chapter-1/sections-create-new-view.png" alt="The Create New View configuration screen"/>
+    The Create New View configuration screen
+</p>
+
+To get started with the new Sections view, create a new view on your dashboard and choose **Sections (experimental)** as the view type. We currently do not have the option to migrate your current dashboard over yet.
+
+<div class='note info'>
+    If you are using the default dashboard, please read about how to <a href="/dashboards/#get-started-with-your-own-dashboard">create a new dashboard</a>.
+</div>
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/sections-blank-sections-view.png" alt="A new dashboard view laid out in Sections"/>
+    A new dashboard view laid out in Sections
+</p>
+
+You will be greeted by a clean new dashboard view, with one section already created for you.
+
+* To add a new section, select the **Create Section** button.
+  <img height="56px" src="/images/blog/2024-03-dashboard-chapter-1/sections-add-section-button.png" alt="Add Section button"/>
+
+* To edit the name of a section, select the <img height="28px" src="/images/blog/2024-03-dashboard-chapter-1/mdi-edit.png" alt="Edit icon"/> **Edit** button on the top right of the section. (Tip: You can add any descriptive text for your section, including emojis!) When the section does not have a name, the section header will be hidden.
+
+* To delete a section, select the <img height="28px" src="/images/blog/2024-03-dashboard-chapter-1/mdi-trash.png" alt="Delete icon"/> **Delete** button  on the top right of the section. You will be asked to confirm the deletion.
+
+### Filling it up
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/sections-example-dashboard.png" alt="A fully populated dashboard in Sections view layout"/>
+    A fully populated dashboard in Sections view layout
+</p>
+
+There are multiple ways to add cards into a section and populate your dashboard:
+
+{% details "Using the Add Card button" %}
+
+1. The easiest way to add cards is to select **Add Card** [Button icon] button inside the section.
+
+2. The Add Card dialog will appear, and there are two options:
+
+    * **By Card**
+        <p class='img'>
+            <img src="/images/blog/2024-03-dashboard-chapter-1/sections-add-card-by-card.png" alt="Add Card by Card type dialog"/>Add Card by Card type dialog
+        </p>
+
+        If you have a good idea of what card you want to use for an entity, browse the list of available cards on this screen. For the Sections view, we recommend the Tile card, which is now pinned to the top in a Suggested Cards section.
+
+    * **By Entity**
+        <p class='img'>
+            <img src="/images/blog/2024-03-dashboard-chapter-1/sections-add-card-by-card.png" alt="Add Card by Entity dialog"/>Add Card by Entity dialog
+        </p>
+
+        If you want to add a bunch of entities in one go, select one or multiple entities on this list.
+
+        <p class='img'>
+            <img src="/images/blog/2024-03-dashboard-chapter-1/sections-add-card-suggestions.png" alt="Card suggestions"/>Card suggestions
+        </p>
+        Home Assistant will show a preview of the cards to be added, which will be displayed in Tile cards as the default of the Sections view. Tap the “Add to Dashboard” button to complete the process.
+
+{% enddetails %}
+
+{% details "Using the Add to Dashboard button on device pages" %}
+
+<p class='img'>
+    <img width="66%" src="/images/blog/2024-03-dashboard-chapter-1/sections-add-from-device-page.jpg" alt="Add to Dashboard feature on the device page"/>Add to Dashboard feature on the device page
+</p>
+
+Another handy method for adding a bunch of sensors or controls belonging to the same device is to add them from the device’s page.
+
+1. Navigate to the page of the device through Settings.
+
+2. Tap the **Add to Dashboard** button on the screen.
+
+3. You will be prompted to choose which dashboard view you want to add them to. If you choose a view using the Sections view layout, the sensors or controls will be added as tile cards placed inside a new section.
+
+{% enddetails %}
+
+### Responsive design
+
+One major benefit of the new Sections view is that it is now much easier to build dashboards that work with multiple screen sizes.
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/sections-responsive-design.png" alt="Sections view adapt nicely to different screen sizes."/>
+    Sections view adapt nicely to different screen sizes.
+</p>
+
+The view will rearrange the sections according to the amount of space available horizontally, while the number of columns of cards within each section stays the same, thus preserving your muscle memory of where the cards are located.
+
+## The grid system
+
+Our current dashboard views are organized in columns with cards of varying heights, and with masonry layout by default. As cards can vary in height in small amounts, it becomes hard to predict where cards will "land" when one moves a card to another column, or when screen size changes and moves all the cards, such as when viewing a dashboard on tablet vs on mobile. This creates friction in the customization experience of the dashboards.
+
+Enter the grid system, a bastion of graphic design principles.
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/grid-system-examples.png" alt="Examples of grid systems in use"/>
+    Examples of grid systems in use
+</p>
+
+Typographic grid systems have a long history in modern graphic design and print publishing, starting from its rise in the early 20th Century during the Constructivist and Geometrical art movements in Europe, which concerns the hidden rhythm behind a visual image. They are easily repeatable and, therefore, practical for generating an infinite amount of pages, yet also ensure aesthetic proportions and consistency for printable matter. They also bring order to a page. It helps users understand the relationship between each element on the page and whether one element belongs to another.
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/grid-system.gif" alt="The Home Assistant dashboard grid system"/>
+    The Home Assistant dashboard grid system
+</p>
+
+When a UI is designed with a structured layout, that feeling of structure and organization comes through to the user in their first impression.
+
+By introducing a grid system with cards of regular row height and column width multiples, we can help users rearrange cards more easily in a predictable manner, make Home Assistant adapt the dashboards to different screen sizes more easily, and, of course, make dashboards look tidier and more aesthetically pleasing.
+
+<p class='img'>
+    <img width="66%" src="/images/blog/2024-03-dashboard-chapter-1/grid-system-available-cards.png" alt="Cards currently optimized for the grid system: Sensor card, Tile card, and Button card"/>
+    Cards currently optimized for the grid system: Sensor card, Tile card, and Button card
+</p>
+
+To implement the grid system, we are now in the process of standardizing the widths and heights of our cards, starting with the Tile card, Button card, and Sensor card. These cards will occupy the right amount of space in the grid, while other cards will occupy the full width of a section by default at the moment.
+
+For card developers, we will have more information on how to adapt your custom cards to the grid system soon.
+
+## Drag-and-drop rearrangement of cards and sections
+
+With sections and a grid system in place, we can finally implement a way to arrange cards and sections that is intuitive with drag-and-drop, predictable with how the cards will rearrange, while creating a dashboard that is easy to navigate and remember by visualizing the information hierarchy and not disturbing the spatial relationship between cards. Users will not need to pray and guess where the cards will land when they change their orders anymore!
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/drag-and-drop-arrangement-methods-comparison.png" alt="Comparison of four card arrangement methods"/>
+    Comparison of four card arrangement methods
+</p>
+
+Throughout the design process, we looked at a few different ways of how cards should be arranged. Ultimately, we chose the “Z-Grid” due to its simplicity, predictability, and memorability as the default, despite it may take up more space than other solutions. The Z-Grid works simply by laying out sections from left to right, and starting a new row when the row is full. The heights of the rows are determined by the tallest section on the row, while the width of the columns remain constant for responsive design.
+
+### How to drag and drop
+
+While your dashboard is in Edit Mode:
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/drag-and-drop-sections.gif" alt="Rearranging sections with drag-and-drop"/>
+    Rearranging sections with drag-and-drop
+</p>
+
+* To rearrange sections, simply tap and hold the <img height="28px" src="/images/blog/2024-03-dashboard-chapter-1/mdi-edit.png" alt="Edit icon"/> **Move** handle and then move your cursor or finger towards your desired location. Other sections will move out of the way for where the selected section will drop.
+
+<p class='img'>
+    <img src="/images/blog/2024-03-dashboard-chapter-1/drag-and-drop-cards.gif" alt="Rearranging cards with drag-and-drop"/>
+    Rearranging sections with drag-and-drop
+</p>
+
+* To rearrange cards, tap and hold anywhere on the card and then move your cursor or finger towards your desired location.
+
+(Don’t you love when instructions are so short? Yay to simplicity! 🦄)
+
+## What’s next? Get involved!
+
+The new Sections view with drag-and-drop is just the first step of Project Grace, a Home-Approved Dashboard. We have a good idea of where we want to head next in our design and development process, but we want to hear from you first before we proceed so that we can prioritize and build a product that will help you the most.
+
+To get feedback from all of you and your household members, we decided to release this early in its incomplete form as an *experiment* for you to try out the new Sections view. For those who are curious, feel free to check out [our updated demo](https://demo.home-assistant.io/#/lovelace/home) to play around and have fun!
+
+We want to make sure that the new default dashboard will not only work for you, but also everyone who lives in your home. We would love to hear what they think as well. Please do not hesitate to leave your comments below!
+
+### Join the Home Assistant User Testing Group!
+
+From time to time, we will send out user tests to help us make the harder product and design decisions we identify. By joining our user testing group, you will help steer the direction of our product and will also get a sneak peak of potential designs that are work in progress.
+
+Please [fill out this form](http://home-assistant.io/join-research) to join the Home Assistant User Testing Group!
+
+Big thanks to all the folks who joined us for user interviews, [Lewis from Everything Smart Home](https://www.youtube.com/c/EverythingSmartHome) for sharing his treasure trove of dashboards for our case studies, and of course, the fabulous [Nabu Casa](https://nabucasa.com) team. 💖
+
+That’s all for now! Thank you for reading. Can’t wait to show you what’s next!
+
+~ Madelena
+
+[Lovelace]: https://www.home-assistant.io/blog/2019/01/23/lovelace-released/
+[Masonry]: https://www.home-assistant.io/dashboards/masonry/

source/_redirects

@@ -34,6 +34,9 @@ layout: null
 /yellow https://yellow.home-assistant.io
 /blog/2021/09/13/home-assistant-amber/ /blog/2021/09/13/home-assistant-yellow/
 
+# User research
+/join-research https://forms.clickup.com/2533032/f/2d9n8-12931/52N1KK00E9BXEW71TN
+
 # Older development pages
 /developers https://developers.home-assistant.io
 /developers/add_new_platform https://developers.home-assistant.io/docs/creating_platform_index/

source/common-tasks/os.markdown

@@ -19,5 +19,6 @@ This section will provide guides to some common tasks and information which you
 {% include common-tasks/third-party-addons.md %}
 {% include common-tasks/data_disk.md %}
 {% include common-tasks/flashing_n2_otg.md %}
+{% include common-tasks/flashing_m1s_otg.md %}
 {% include common-tasks/enable_i2c.md %}
 

source/dashboards/cards.markdown

@@ -3,6 +3,16 @@ title: "Cards"
 description: "Cards."
 ---
 
-Your dashboard is made up of Cards.
+Each dashboard is made up of cards.
 
-There are several built-in card types, each with their own configuration options. Select a card from the menu to view additional details and the options for that card.
+<p class='img'>
+<img src='/images/getting-started/lovelace.png' alt='Screenshot of the masonry view with different types of cards'>
+Screenshot of the masonry view with different types of cards.
+</p>
+
+There are several built-in card types, each with their own configuration options. Select a card from the menu to view additional details and the options for that card.
+
+<p class='img'>
+<img src='/images/dashboards/card_menu.png' alt='Screenshot of the card menu'>
+Screenshot of the card menu.
+</p>

source/dashboards/dashboards.markdown

@@ -1,15 +1,44 @@
 ---
-title: "Multiple Dashboards"
+title: "Multiple dashboards"
 description: "Multiple powerful and configurable dashboards in Home Assistant."
 ---
 
 You can define multiple dashboards in Home Assistant. Each dashboard can be added to the sidebar. This makes it possible to create separate control dashboards for each individual part of your house.
 
-You can manage your dashboards via the user interface. Go to **Settings** -> **Dashboards**. Here you can see all defined dashboards and create new ones.
+You can manage your dashboards via the user interface. Go to {% my lovelace_dashboards title="**Settings** > **Dashboards**" %}. Here you can see some of the defined dashboards and create new ones.
 
-## Using YAML for the default dashboard
+<p class='img'>
+<img src='/images/dashboards/dashboard-manage-01.png' alt='Screenshot of the dashboard list'>
+Screenshot of the Dashboard list.
+</p>
 
-To change the default dashboard, create a new file `ui-lovelace.yaml` in your configuration directory and add the following section to your `configuration.yaml` and restart Home Assistant:
+## Home Assistant default dashboards
+
+Home Assistant ships with 5 predefined dashboards:
+
+- Overview
+- Energy
+- Map
+- Logbook
+- History
+
+Not all of predefined dashboards are listed under {% my lovelace_dashboards title="**Settings** > **Dashboards**" %}. **Map**, **Logbook**, and **History**, are powered by their respective integrations.
+
+### Map dashboard
+
+The predefined **Map** dashboard is powered by the [Map integration](/integrations/map/). If you see a [person](/integrations/person/) on the map, it means you have connected a device that allows [presence detection](/integrations/#presence-detection). This is the case for example if you have the [Home Assistant Companion App](https://companion.home-assistant.io/) on your phone and allowed location tracking.
+
+### Logbook dashboard
+
+The predefined **Logbook** dashboard is powered by the [Logbook integration](/integrations/logbook/). To control which events to show or filter out, refer to the documentation of the Logbook integration.
+
+### History dashboard
+
+The predefined **History** dashboard is powered by the [History integration](/integrations/logbook/). To learn about the data sources used and how to export data, refer to the documentation of the History integration.
+
+## Using YAML for the Overview dashboard
+
+To change the **Overview** dashboard, create a new file `ui-lovelace.yaml` in your configuration directory and add the following section to your `configuration.yaml` and restart Home Assistant:
 
 ```yaml
 lovelace:
@@ -18,9 +47,9 @@ lovelace:
 
 A good way to start this file is to copy and paste the "Raw configuration" from the UI so your manual configuration starts the same as your existing UI.
 
-- Click `Overview` in your sidebar.
+- In your sidebar, select **Overview**.
-- Click the three dots menu (top-right) and click on `Edit Dashboard`.
+- In the top-right corner, select the pencil icon.
-- Click the three dots menu again and click on `Raw configuration editor`.
+- Select the three dots menu and select **Raw configuration editor**.
 - There you see the configuration for your current dashboard. Copy that into the `<config>/ui-lovelace.yaml` file.
 
 Once you take control of your UI via YAML, the Home Assistant interface for modifying it won't be available anymore and new entities will not automatically be added to your UI.
@@ -192,3 +221,9 @@ views:
         content: >
           Welcome to your **dashboard**.
 ```
+
+## Related topics
+
+- [Logbook integration](/integrations/logbook/)
+- [Map integration](/integrations/map/)
+- [History integration](/integrations/history/)

source/dashboards/index.markdown

@@ -3,30 +3,40 @@ title: "Dashboards"
 description: "Powerful and configurable dashboards for Home Assistant."
 ---
 
-Home Assistant dashboards are a fast, customizable and powerful way for users to manage their home using their mobiles and desktops.
+Home Assistant dashboards allow you to display information about your smart home. Dashboards are customizable and provide a powerful way to manage your home from your mobile or desktop.
 
-- 29 different cards to place and configure as you like.
+You can customize your dashboard using various options:
-- Dashboard Editor: Allows you to manage your dashboard by including a live preview when editing cards.
-- Fast: Using a static configuration allows us to build up the dashboard once.
-- Customizable:
-  - Cards have a number of options which help to configure your data as required.
-  - Themes (even at a per card basis).
-  - Ability to override names and icons of entities.
-  - Custom Cards from our amazing community are fully supported.
 
-To start, go to the Home Assistant Overview page, click on the three dots at the top right of the screen and select 'Edit Dashboard'. Then click on the blue '+ Add Card' icon at the bottom right and select a card to add.
+- Different card types to visualize your data and control your smart home devices.
+- [Themes](/integrations/frontend/#defining-themes) (even at a per card basis).
+- Override names and icons of entities.
+- Use custom cards from our amazing community.
 
-<lite-youtube videoid="XY3R0xI45wA" videotitle="Editing the user interface" posterquality="maxresdefault"></lite-youtube>
+<p class='img'>
+<img src='/images/dashboards/edit-dashboard.webp' alt='Screencast showing how to edit a dashboard customize a vertical stack card'>
+Screencast showing how to edit a dashboard and customize a vertical stack card.
+</p>
 
-To try it yourself, check out [the demo](https://demo.home-assistant.io).
+## Explore the interactive demo dashboard
+
+Try it yourself with [the interactive demo](https://demo.home-assistant.io).
+
+## Get started with your own dashboard
+
+{% include dashboard/edit_dashboard.md %}
+
+For more detailed instructions, follow the step-by-step tutorial on [editing the **Overview** dashboard](/getting-started/onboarding_dashboard/).
 
 ## Discuss dashboard
 
 - Suggestions are welcome in the [frontend repository](https://github.com/home-assistant/frontend/)
 - For help with dashboards, join the `#frontend` channel on [our chat](/join-chat/) or [our forums](https://community.home-assistant.io/c/projects/frontend)
 
-## Additional Resources
+## Related topics
 
-- [Community Custom Cards](https://github.com/custom-cards)
+- [Community custom cards](https://github.com/custom-cards)
-- [Home Assistant Cards](https://home-assistant-cards.bessarabov.com/)
+- [Home Assistant cards](https://home-assistant-cards.bessarabov.com/)
 - [Material Design Icons](https://pictogrammers.com/library/mdi/)
+- [Dashboard themes](/integrations/frontend/#defining-themes)
+- [Interactive dashboard demo](https://demo.home-assistant.io)
+- [Editing the **Overview** dashboard](/getting-started/onboarding_dashboard/)

source/getting-started/concepts-terminology.markdown

@@ -37,7 +37,7 @@ Devices and entities are used throughout Home Assistant. To name a few examples:
 A set of repeatable {% term actions %} that can be set up to run automatically. Automations are made of three key components:
 
 1. Triggers - events that start an {% term automation %}. For example, when the sun sets or a motion sensor is activated.
-2. Conditions - optional tests that must be met an {% term action %} can be run. For example, if someone is home.
+2. Conditions - optional tests that must be met before an {% term action %} can be run. For example, if someone is home.
 3. Actions - interact with {% term devices %} such as turn on a light.
 
 To learn the basics about {% term automations %}, refer to the [automation basics](/docs/automation/basics/) page or try [creating an automation](/getting-started/automation) yourself.