Refactor the advanced section (#628)

* Refactor the advanced section

* Refactor firmware changes documentation for improved clarity and component linking

* Refactor firmware updates documentation for brevity in description

* Fix broken links

* Refactor firmware updates documentation for grammatical clarity

docs/blog/2024-01-11-fresh-new-start.md

@@ -25,7 +25,7 @@ TL;DR - A lot 😅 ... v4.0.0 has been released, the most important changes are
 1. The pulse meter pin for ESP32 boards has been changed from GPIO `13` to GPIO `26`.
 2. The `home_assistant_glow.yaml` file no longer exists.
 
-This would break the **package_import** for existing configs for people in the ESPHome dashboard. If you would like to use the latest version, I recommend re-flashing your ESP according to step 2 in [Getting Started](/docs/getting-started#step-2-install-firmware), and if desired, [re-adopting](/docs/advanced/firmware_customization#adopting-the-device) your device again in ESPHome dashboard (add-on).
+This would break the **package_import** for existing configs for people in the ESPHome dashboard. If you would like to use the latest version, I recommend re-flashing your ESP according to step 2 in [Getting Started](/docs/getting-started#step-2-install-firmware), and if desired, [re-adopting](/docs/advanced/firmware_changes#adopting-the-device) your device again in ESPHome dashboard (add-on).
 
 ### New config structure
 

docs/blog/2024-09-06-release.md

@@ -37,7 +37,7 @@ If you would like to support the project, you can do so through [GitHub sponsors
 
 - [ESPHome 2024.8.x - Changelog][esphome-changelog]
 - [ESPHome - Extend][!extend]
-- [Customizing the firmware](/docs/advanced/firmware_customization)
+- [Customizing the Firmware](/docs/advanced/firmware_changes)
 
 <!-- Links -->
 [esphome-changelog]: https://esphome.io/changelog/2024.8.0.html

docs/docs/advanced/firmware_changes.mdx

@@ -0,0 +1,75 @@
+---
+id: firmware_changes
+title: Customizing the Firmware
+description: Learn how to customize the firmware of the Glow using ESPHome.
+---
+
+# Customizing the Firmware
+
+The Glow's firmware is built on [ESPHome](https://esphome.io), a platform designed for customization through simple YAML configurations. Whether you need to tweak the device's functionality or adapt it for different use cases, the process is straightforward.
+
+This guide will walk you through how to adopt the device and customize its firmware using the [ESPHome Dashboard](https://esphome.io/guides/getting_started_hassio.html).
+
+## Adopting the Device
+
+Before making any changes to the firmware, you first need to adopt the device into the ESPHome. Once your ESPHome Dashboard is up and running, and the Glow is connected to your local network, you should see an option to adopt it.
+
+<p align="left">
+  <img src={require('@site/static/img/customization/adopt-esphome.png').default} />
+</p>
+
+Following the adoption steps will automatically:
+
+1. Create a unique ESPHome configuration file for your device.
+2. Set up a secure API encryption key, allowing communication between Home Assistant and your device.
+3. Configure the device's network settings, such as Wi-Fi credentials.
+4. Upload the customized firmware onto the Glow.
+
+## Component Structure
+
+The firmware is designed to be flexible for different ESP boards by breaking it into separate "components". Each main function of the device is kept in its own YAML file, making it easier to manage. The base configuration includes a few key components that handle the important functions of the device.
+
+| Component                                     | Description                                                                                           |
+| :-------------------------------------------- | :---------------------------------------------------------------------------------------------------- |
+| [**basis.yaml**][component-basis]             | Handles the basic, essential functionality of the device.                                             |
+| [**pulse_meter.yaml**][component-pulse_meter] | Manages pulse metering, useful for tracking energy usage.                                             |
+| [**status_led.yaml**][component-status_led]   | Controls the status LED, allowing customization of its behavior or color based on the device's state. |
+| [**updates.yaml**][component-updates]         | Provides Over-the-Air ([OTA][ota]) update capabilities for easy firmware updates.                     |
+
+### Making Your First Customization
+
+Once your device is adopted, you can start customizing its behavior by editing the configuration files. In the ESPHome dashboard, click on **EDIT** next to the device to open the YAML editor, where you can modify the configuration directly.
+
+<p align="left">
+  <img src={require('@site/static/img/customization/edit-device.png').default} />
+</p>
+
+The YAML configuration may seem short and incomplete because it relies on [remote packages][remote], which are loaded during the firmware build process. If you want to customize or modify anything, it's important to first find the used ESPHome component ID.
+
+When you open the YAML editor, you'll see the default configuration for your Glow device. You can adjust this configuration or add new functionality by extending the existing components. For example, to change the behavior of the [pulse_meter], you can use the [!extend] feature to easily make the necessary changes.
+
+Here's an example of adding an [internal_filter] to the pulse meter configuration:
+
+```yaml title="your_glow_config.yaml"
+sensor:
+  - id: !extend sensor_energy_pulse_meter
+    internal_filter: 100ms
+```
+
+## Helpful Resources
+
+- [ESPHome - Pulse Counter][pulse_meter]
+- [ESPHome - Extend][!extend]
+- [ESPHome - OTA Updates][ota]
+- [ESPHome - Remote Packages][remote]
+
+[internal_filter]: https://esphome.io/components/sensor/pulse_counter.html?highlight=internal_filter
+[pulse_meter]: https://esphome.io/components/sensor/pulse_counter.html
+[!extend]: https://esphome.io/components/packages.html#extend
+[ota]: https://esphome.io/components/ota/
+[remote]: https://esphome.io/components/packages.html#remote-git-packages
+
+[component-basis]: https://github.com/klaasnicolaas/home-assistant-glow/blob/main/components/basis.yaml
+[component-pulse_meter]: https://github.com/klaasnicolaas/home-assistant-glow/blob/main/components/pulse_meter.yaml
+[component-status_led]: https://github.com/klaasnicolaas/home-assistant-glow/blob/main/components/status_led.yaml
+[component-updates]: https://github.com/klaasnicolaas/home-assistant-glow/blob/main/components/updates.yaml

docs/docs/advanced/firmware_updates.mdx

@@ -0,0 +1,70 @@
+---
+id: firmware_updates
+title: Firmware Updates
+description: Learn how to update the firmware of the Glow.
+---
+
+# Firmware Updates
+
+Keeping your device's firmware up to date is essential to ensure it runs smoothly and benefits from the latest (ESPHome) features. This guide will walk you through how to update the firmware of the Home Assistant Glow.
+
+## Updating Firmware through Home Assistant
+
+_Level of Difficulty: **Easy**_
+
+The easiest way to update the firmware of the Glow is through Home Assistant. When a new firmware update is available, you will receive a notification directly within Home Assistant. To update your device, follow these simple steps:
+
+1. Look on the **Settings** page of Home Assistant for update notifications.
+2. Click on the notification for the Home Assistant Glow.
+3. A pop-up will appear with release notes / version number and the option to update the firmware.
+4. Click **Install** to start the process.
+
+<p align="left">
+  <img 
+    width="80%"
+    src={require('@site/static/img/advanced/glow_update-popup.png').default}
+    alt="Update notification in Home Assistant"
+  />
+</p>
+
+:::note
+Since ESPHome 2024.6.x, the update component can directly retrieve firmware updates from the glow energy manifest. Which has made updating even easier and eliminates the need to use ESPHome Dashboard add-on just for updates.
+:::
+
+## Glow Web Interface
+
+_Level of Difficulty: **Medium**_
+
+If you are unable to update the firmware through Home Assistant, you can also update the firmware directly within the Glow's web interface. This method is useful if you are using the Glow as a standalone device or if you prefer to update the firmware manually.
+
+1. Download the latest firmware binary file for your device:
+    - Download for ESP32: [home-assistant-glow-esp32.ota.bin](https://glow-energy.io/home-assistant-glow/esp32/home-assistant-glow-esp32.ota.bin)
+    - Download for ESP8266: [home-assistant-glow-esp8266.ota.bin](https://glow-energy.io/home-assistant-glow/esp8266/home-assistant-glow-esp8266.ota.bin)
+2. Navigate to the Glow's web interface, by entering the IP address of the device in your browser.
+3. At the bottom of the page, you will find the **OTA Update** section.
+4. Click on **Choose File** and select the firmware binary file you downloaded.
+5. Click **Upload** to start the update process.
+
+After the update is complete, the device will automatically reboot with the new firmware.
+
+## ESPHome Dashboard
+
+_Level of Difficulty: **Advanced**_
+
+If you are using the ESPHome Dashboard add-on in Home Assistant, you can also update the firmware through the dashboard. This method is useful if you have adopted the firmware to your ESPHome dashboard and know how to tweak the YAML configuration.
+
+1. Open the ESPHome Dashboard.
+2. If it is possible to update the firmware, you will see an update button at the device card (see image below).
+3. Click on the **UPDATE** button to start the process.
+4. Select **Wirelessly** to update the firmware over-the-air (OTA).
+5. After this, it will start the update process and you will see the update process in a pop-up window.
+
+Once the update is complete, the device will automatically reboot with the new firmware.
+
+<p align="left">
+  <img 
+    width="80%"
+    src={require('@site/static/img/advanced/glow_update-esphome.png').default}
+    alt="Update firmware through ESPHome Dashboard"
+  />
+</p>

docs/docs/faq/faq_nr2.md

@@ -22,14 +22,14 @@ sensor:
         - heartbeat: 300s
 ```
 
-After applying the filters, only 396 state changes will be produced per hour. You can read more about making YAML adjustments on the [customizing the firmware](/docs/advanced/firmware_customization.mdx) page.
+After applying the filters, only 396 state changes will be produced per hour. You can read more about making YAML adjustments on the [customizing the firmware](/docs/advanced/firmware_changes) page.
 
 ## Related topics
 
 - [ESPHome sensor filters][filters]
 - [ESPHome pulse meter](https://esphome.io/components/sensor/pulse_meter.html)
 - [ESPHome total daily energy sensor](https://esphome.io/components/sensor/total_daily_energy.html)
-- [Customizing the firmware](/docs/advanced/firmware_customization.mdx)
+- [Customizing the Firmware](/docs/advanced/firmware_changes)
 
 [filters]: https://esphome.io/components/sensor/index.html#sensor-filters
 [file]: https://github.com/klaasnicolaas/home-assistant-glow/blob/main/components/pulse_meter.yaml#L73

docs/docs/faq/faq_nr7.md

@@ -21,7 +21,7 @@ sensor:
 ## Related topics
 
 - [ESPHome total daily energy sensor][method]
-- [Customizing the firmware](/docs/advanced/firmware_customization.mdx)
+- [Customizing the Firmware](/docs/advanced/firmware_changes)
 
 [method]: https://esphome.io/components/sensor/total_daily_energy.html
 [issue_274]: https://github.com/klaasnicolaas/home-assistant-glow/issues/274

docs/docs/faq/faq_nr8.md

@@ -18,7 +18,7 @@ In the example above, replace `your_password` with the password you want to use
 
 - [ESPHome - OTA updates][esphome_ota]
 - [ESPHome - Extend][!extend]
-- [Customizing the firmware](/docs/advanced/firmware_customization.mdx)
+- [Customizing the Firmware](/docs/advanced/firmware_changes)
 
 [esphome_ota]: https://esphome.io/components/ota.html
 [!extend]: https://esphome.io/components/packages.html#extend

docs/sidebars.ts

@@ -29,7 +29,8 @@ const sidebars: SidebarsConfig = {
       type: 'category',
       label: 'Advanced',
       items: [
-        'advanced/firmware_customization',
+        'advanced/firmware_changes',
+        'advanced/firmware_updates',
       ],
     },
     {