diff --git a/.github/workflows/build-firmware.yaml b/.github/workflows/build-firmware.yaml index 43468a74..5b660076 100644 --- a/.github/workflows/build-firmware.yaml +++ b/.github/workflows/build-firmware.yaml @@ -38,7 +38,7 @@ jobs: matrix: ${{ steps.prepare-matrix.outputs.matrix }} steps: - name: ⤵️ Check out code from GitHub - uses: actions/checkout@v4.2.1 + uses: actions/checkout@v4.2.2 - name: ⤵️ Get changed files if: github.event_name == 'pull_request' id: changes @@ -91,7 +91,7 @@ jobs: matrix: ${{fromJson(needs.prepare.outputs.matrix)}} steps: - name: ⤵️ Check out code from GitHub - uses: actions/checkout@v4.2.1 + uses: actions/checkout@v4.2.2 - name: 🔍 Determine ref - ESPHome packages if: ${{ !contains(fromJSON('["release", "workflow_call"]'), github.event_name) }} run: | diff --git a/.github/workflows/deploy-firmware.yaml b/.github/workflows/deploy-firmware.yaml index 96d37dd9..b5c30b99 100644 --- a/.github/workflows/deploy-firmware.yaml +++ b/.github/workflows/deploy-firmware.yaml @@ -57,7 +57,7 @@ jobs: needs: combined-manifests steps: - name: ⤵️ Check out code from GitHub - uses: actions/checkout@v4.2.1 + uses: actions/checkout@v4.2.2 - name: ⬇️ Download all artifacts uses: actions/download-artifact@v4.1.8 with: diff --git a/.github/workflows/labels.yaml b/.github/workflows/labels.yaml index 71f71376..63b8f35d 100644 --- a/.github/workflows/labels.yaml +++ b/.github/workflows/labels.yaml @@ -18,7 +18,7 @@ jobs: pull-requests: write steps: - name: ⤵️ Check out code from GitHub - uses: actions/checkout@v4.2.1 + uses: actions/checkout@v4.2.2 - name: 🚀 Run Label Syncer uses: micnncim/action-label-syncer@v1.3.0 env: diff --git a/docs/blog/2024-01-11-fresh-new-start.md b/docs/blog/2024-01-11-fresh-new-start.md index 1c05b9f9..f344238f 100644 --- a/docs/blog/2024-01-11-fresh-new-start.md +++ b/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 diff --git a/docs/blog/2024-09-06-release.md b/docs/blog/2024-09-06-release.md index b97dce93..2b5219dc 100644 --- a/docs/blog/2024-09-06-release.md +++ b/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) [esphome-changelog]: https://esphome.io/changelog/2024.8.0.html diff --git a/docs/docs/advanced/firmware_changes.mdx b/docs/docs/advanced/firmware_changes.mdx new file mode 100644 index 00000000..1005d73c --- /dev/null +++ b/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. + +

+ +

+ +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. + +

+ +

+ +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 \ No newline at end of file diff --git a/docs/docs/advanced/firmware_customization.mdx b/docs/docs/advanced/firmware_customization.mdx deleted file mode 100644 index e68a4eeb..00000000 --- a/docs/docs/advanced/firmware_customization.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -id: firmware_customization -title: Customizing the firmware -description: How to adopt and customize the firmware for your own needs. ---- - -The Home Assistant 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 Home Assistant Glow is connected to your -local network, you should see an option to adopt it. - -

- -

- -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. Embed your Wi-Fi credentials directly into the firmware, enabling automatic reconnections. -4. Upload the customized firmware onto the Home Assistant Glow. - -## Understanding the Configuration - -### Component Structure - -To make the firmware manageable and adaptable to different hardware setups, it is organized into -distinct "components." Each major function of the device is isolated in its own YAML file. The -base configuration includes several important components: - -- **`basis.yaml`**: Handles the basic, essential functionality of the device. -- **`pulse_meter.yaml`**: Manages pulse metering, useful for tracking energy usage. -- **`status_led.yaml`**: Controls the status LED, allowing you to customize its behavior or color based on the device's state. -- **`updates.yaml`**: Provides Over-the-Air ([OTA][ota]) update capabilities, making it easy to update firmware without physical access. - -These components can be found in the [GitHub repository](https://github.com/klaasnicolaas/home-assistant-glow/tree/main/components). - -### 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. - -

- -

- -In the YAML editor, you'll see the default configuration for your Home Assistant Glow. You can -make changes here or add new functionality by extending existing components. For instance, to -modify the behavior of the [pulse_meter], you could use the [!extend] feature. - -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 -``` - -## Related links - -- [ESPHome - Pulse Counter][pulse_meter] -- [ESPHome - Extend][!extend] -- [ESPHome - OTA Updates][ota] - -[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/ \ No newline at end of file diff --git a/docs/docs/advanced/firmware_updates.mdx b/docs/docs/advanced/firmware_updates.mdx new file mode 100644 index 00000000..4cc213c3 --- /dev/null +++ b/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. + +

+ Update notification in Home Assistant +

+ +:::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. 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. + +

+ Update firmware through ESPHome Dashboard +

\ No newline at end of file diff --git a/docs/docs/configuration.mdx b/docs/docs/configuration.mdx deleted file mode 100644 index 50295411..00000000 --- a/docs/docs/configuration.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -id: configuration -title: Configuration ---- - -## Changing the Device Name - -When you first add your device to Home Assistant, it's assigned a default name like `home-assistant-glow-XXXXXX`, -where `XXXXXX` is a portion of the device's MAC address. While functional, this default name isn't very user-friendly -or descriptive, especially if you have multiple devices. Renaming it to something more meaningful helps with organization -and makes it easier to recognize within your smart home setup. - -### How to Rename Your Device - -To change the name of your device, follow these steps: - -1. Open the Home Assistant user interface. -2. Navigate to **Settings** > **Devices & Services**. -3. Under the **ESPHome** section, find and select your device. If you have multiple devices, you may need to identify it by its current name (the default format described earlier). - -Alternatively, you can click the badge below to be taken directly to the ESPHome devices overview page: - -[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)][esphome-devices] - -4. Once on the device's page, locate the pencil icon in the top-right corner. Clicking this icon will allow you to edit the device name. -5. Enter your preferred name, something that reflects the purpose or location of the device (e.g., “Home Assistant Glow” or “Glow Energy”). This will help you easily identify it later. -6. Click **Update** to apply the changes and save the new name. - -

- -

- -### Renaming Entity IDs (Optional) - -After renaming the device, Home Assistant may prompt you to rename the associated entity IDs as well. Entity IDs are used to reference your device in automations, dashboards, and other parts of Home Assistant. - -- **If you haven't created any automations or dashboards yet**: It's generally a good idea to rename the entity IDs to match the new device name. This makes them easier to recognize and use in future configurations. -- **If you already have automations or dashboards**: You may want to keep the existing entity IDs if they are already used in various setups. Renaming the entity IDs will require you to update those configurations to reference the new names. In this case, you can opt to change only the device name and leave the entity IDs as they are. - -## Related links - -- [Home Assistant - Terminology](https://home-assistant.io/getting-started/concepts-terminology) - -[esphome-devices]: https://my.home-assistant.io/redirect/integration/?domain=esphome \ No newline at end of file diff --git a/docs/docs/configuration/energy_dashboard.md b/docs/docs/configuration/energy_dashboard.md new file mode 100644 index 00000000..0de10316 --- /dev/null +++ b/docs/docs/configuration/energy_dashboard.md @@ -0,0 +1,37 @@ +--- +id: energy_dashboard +title: Energy Dashboard +description: Learn how to set up an energy dashboard in Home Assistant to monitor your energy usage. +--- + +# Add to Energy Dashboard + +To monitor your energy usage, you can add the Home Assistant Glow to the [Energy Dashboard][energy]. This dashboard provides an overview of your energy consumption, costs, and trends over time. + +## Which entities to add? + +You can choose between the following entities to add to the Energy Dashboard: + +- **sensor.home_assistant_glow_daily_energy** +- **sensor.home_assistant_glow_total_energy** + +It doesn't matter if the entity resets during the day for example due to an update/or hard reset after reboot. The long-term statistics in Home Assistant can handle that. + +## Step-by-step guide to add entities + +1. Open your Home Assistant dashboard/interface. +2. From the sidebar, click on **Energy**. +3. Click on the 3 dots in the top right corner and select **Energy Configuration**. +4. Click on **Add Consumption** and select the entity you want to add. +5. Optionally, you can setup the cost of your energy provider to get an overview of your energy costs. +6. Click **Save** to apply the changes. + +:::note +If your Glow has just been added to Home Assistant, you may need to wait up to 2 hours before enough long-term statistics are stored to show in the Energy Dashboard. +::: + +## Helpful resources + +- [Home Assistant - Energy Management][energy] + +[energy]: https://www.home-assistant.io/docs/energy \ No newline at end of file diff --git a/docs/docs/configuration/pulse_rate.mdx b/docs/docs/configuration/pulse_rate.mdx new file mode 100644 index 00000000..3739383f --- /dev/null +++ b/docs/docs/configuration/pulse_rate.mdx @@ -0,0 +1,34 @@ +--- +id: pulse_rate +title: Pulse Rate +description: Learn how to adjust the pulse rate of your Home Assistant Glow device to match your energy meter. +--- + +# Adjust the Pulse Rate + +The Glow uses a pulse meter to track energy usage, which requires setting the correct pulse rate to match your energy meter. This ensures accurate energy monitoring and tracking in Home Assistant. + +In most cases, the correct pulse rate is set during the [getting started](/docs/getting-started#step-4-configure-the-pulse-rate) guide, but you can easily adjust it later if needed. If the pulse rate hasn't been changed yet, the Glow defaults to `1000` **imp/kWh**, which is commonly used in the Netherlands. However, you may need to modify this value based on your energy meter's specifications. + +You can adjust the value in 2 ways: + +### Option 1: Via the web interface + +You open the web server by going to the IP address of your Home Assistant Glow, where you will find the line **Pulse rate - imp/kWh** in the table, and you can then adjust it on the right. + +

+ Adjusting the pulse rate via the web interface +

+ +### Option 2: In Home Assistant + +1. Go to the device overview page of the Home Assistant Glow, via [**Settings** > **Devices & Services** > **ESPHome**](https://my.home-assistant.io/redirect/integration/?domain=esphome). +2. Adjust the value for the entity **Pulse rate - imp/kWh**. + +## Useful resources + +- [Glow Energy - FAQ page](/docs/faq) diff --git a/docs/docs/configuration/rename.mdx b/docs/docs/configuration/rename.mdx new file mode 100644 index 00000000..346a3278 --- /dev/null +++ b/docs/docs/configuration/rename.mdx @@ -0,0 +1,53 @@ +--- +id: rename +title: Rename the Glow +description: Learn how to rename your Home Assistant Glow device to something more descriptive and user-friendly. +--- + +# Rename your Glow in Home Assistant + +When you add the Glow to Home Assistant, it is automatically given a default name like `home-assistant-glow-XXXXXX`, where `XXXXXX` is a portion of the device's MAC address. This name shows up in the device list, but it isn't very descriptive. Renaming the device makes it much easier to manage, and if you want, you can also update the **entity IDs** to match the new device name for consistency. + +## Why rename the device? + +Even though the entity IDs don't include the MAC address and are functional as they are, having a device name that includes part of the MAC address isn't ideal. Changing the device name to something more descriptive can help you: + +- Quickly identify the device in Home Assistant. +- Make it easier to work with the device when adding in automations or dashboards. +- Keep your Home Assistant setup organized and clear 🧹 + +## Step-by-step guide to rename your Glow + +Here's how to change the name of your Glow in Home Assistant: + +1. Open your Home Assistant dashboard/interface. +2. **Go to settings**: From the sidebar, click on **Settings** and then select **Devices & Services**. +3. In the **ESPHome** section, find your glow. If you have multiple devices, look for the one with the default format. + + **Pro Tip**: Want to get there faster? Click the badge below to jump directly to your device page: + +[![Open your Home Assistant instance and show an integration.](https://my.home-assistant.io/badges/integration.svg)][esphome-devices] + +4. On the device details page, click the pencil icon in the top-right corner to rename it (see image below). +5. **Choose a descriptive name** that's easy to remember, like "Home Assistant Glow" or "Glow Energy". +6. Click **Update** to save the new name. + +

+ Renaming a device in Home Assistant +

+ +### Renaming Entity IDs (Optional) + +After you rename the device, Home Assistant may ask if you want to also rename the associated entity IDs. The entity IDs are already usable as is, but if you prefer consistency, you can rename them to match the new device name: + +- **If you want the entity IDs to stay the same**: Simply keep the existing entity IDs and only update the device name. +- **Want everything to be consistent?** You can rename the entity IDs too, but be aware that this is a breaking change. You will need to update all automations, scripts, dashboards, and any other configurations that reference the old entity IDs to prevent disruptions in your Home Assistant setup. + +## Helpful resources + +- [Home Assistant - Terminology](https://home-assistant.io/getting-started/concepts-terminology) + +[esphome-devices]: https://my.home-assistant.io/redirect/integration/?domain=esphome \ No newline at end of file diff --git a/docs/docs/faq/faq_nr2.md b/docs/docs/faq/faq_nr2.md index 62287c81..8a6f685b 100644 --- a/docs/docs/faq/faq_nr2.md +++ b/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 \ No newline at end of file diff --git a/docs/docs/faq/faq_nr7.md b/docs/docs/faq/faq_nr7.md index c3f48872..1ba5ffe7 100644 --- a/docs/docs/faq/faq_nr7.md +++ b/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 diff --git a/docs/docs/faq/faq_nr8.md b/docs/docs/faq/faq_nr8.md index a4b82d03..c87d8fca 100644 --- a/docs/docs/faq/faq_nr8.md +++ b/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 diff --git a/docs/docs/getting-started.mdx b/docs/docs/getting-started.mdx index 47716a54..4a4b5e9c 100644 --- a/docs/docs/getting-started.mdx +++ b/docs/docs/getting-started.mdx @@ -13,9 +13,9 @@ import { faUsb } from '@fortawesome/free-brands-svg-icons'; This guide will walk you through the steps needed to set up your new Home Assistant Glow. You'll go through connecting the hardware, installing the necessary software, and configuring the settings to get everything up and running smoothly. -## Step 1: Hardware +## Step 1 - Hardware -To get started, you need the right hardware first, fill your 🛒 or see if you already have the components in house. Choose between an **ESP32** (recommended) or **ESP8266**. +To get started, you need the right hardware first, fill your 🛒 or see if you already have the items in house. Choose between an **ESP32** (recommended) or **ESP8266**. | Nr. | Item | Shops | | | |:-----|:---------|:------|:-|:-| @@ -35,9 +35,9 @@ If you would like to prototype, I can also recommend the following items: Keep in mind that besides the photodiode board there are also boards in circulation with an LDR. The expansion board is optional, but makes it easier to connect and prototype with the components. ::: -How everything should be connected can be found on the [wiring diagram](/docs/reference/diagram). Once this is done, you can proceed to step 2. +How everything should be connected can be found on the [wiring diagram](/docs/resources/schematics). Once this is done, you can proceed to step 2. -## Step 2: Install firmware +## Step 2 - Install firmware Use the method below to provide your ESP with the correct firmware. @@ -46,31 +46,29 @@ Use the method below to provide your ESP with the correct firmware. _Make sure this page is opened in a Chromium-based browser on a desktop. The software installation does not work with a tablet or phone._ -:::note -If your device does not appear in the list, make sure you are using a USB data cable (i.e., not power-only), and try installing the [driver](https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers?tab=downloads) for the serial chip. -::: - -1. Click the blue **connect** button below, a pop-up window will appear with a list of available USB devices. -2. Plug the USB cable into the ESP and connect it to your computer. -3. In the pop-up window, there should now appear a new entry. Select this USB serial port and click **Connect**. -4. Choose **Install Home Assistant Glow**, then click **Install**. +1. Click the blue **connect** button below to display a list of available USB devices. +2. To connect your ESP to your computer, follow these steps: + - In the pop-up window, view the list of available USB devices. + - Connect your ESP to your computer using a USB cable. + - In the pop-up window, there should now appear a new entry. Select this USB serial port and select **Connect**. +3. Select **Install Home Assistant Glow**, then **Install**. - If the installation does not go well, you may need to first hold down the `boot` button and then click **Install**. -5. Once the installation is completed, click **Next**. +4. Once the installation is completed, click **Next**. - Add the Home Assistant Glow to your Wi-Fi network: - When prompted, select your network from the list and enter the credentials to your 2.4 GHz Wi-Fi network. - Click **Connect**. - The Home Assistant Glow is now connected to your network. -6. Congratulations 🎉 You have successfully installed the firmware on your Home Assistant Glow. +5. Congratulations 🎉 You have successfully installed the firmware on your Home Assistant Glow. -## Step 3: Connect to Home Assistant +## Step 3 - Connect to Home Assistant -You have two options to add the Home Assistant Glow to Home Assistant. +There are two ways to connect the Glow to Home Assistant. You can do this during the firmware installation or later via auto discovery. -### Option 1: During firmware installation +### Option 1 - During firmware installation 1. Immediately after setting up your Wi-Fi network (from step 2), you will see a screen with the option **Add to Home Assistant**. - This opens the **My** link to Home Assistant (see image below). @@ -80,10 +78,14 @@ You have two options to add the Home Assistant Glow to Home Assistant. 4. Congratulations 🎉 You have successfully added the Home Assistant Glow to your Home Assistant instance.

- + My link to Home Assistant

-### Option 2: Auto discovery +### Option 2 - Auto discovery When the Home Assistant Glow is added to a network to which your Home Assistant instance is also connected, your device will automatically be recognized in Home Assistant. @@ -93,35 +95,45 @@ When the Home Assistant Glow is added to a network to which your Home Assistant 4. Congratulations 🎉 You have successfully added the Home Assistant Glow to your Home Assistant instance.

- + Auto discovery in Home Assistant

-## Step 4: Configure +## Step 4 - Configure the Pulse Rate + +To ensure that the Home Assistant Glow accurately measures energy consumption, you must set the correct pulse rate. The pulse rate refers to the number of pulses the energy meter sends per kilowatt-hour (kWh). Energy meters with a pulse LED will have an imp/kWh value indicated, such as 1000, 2000, etc. -In order for the measurements to run smoothly, it is important to set the correct pulse rate. Each meter with a pulse LED has a marking with an **imp/kWh** value, for example 1000, 2000, etc. The Home Assistant Glow will use the value `1000` by default, because this is a commonly used value in the Netherlands. +By default, the Home Assistant Glow is configured to use a pulse rate of `1000`. -You can adjust the value in 2 ways: +There are two ways to adjust the pulse rate: -### Option 1: Via the web interface +### Option 1 - Via the web interface -You open the web server by going to the IP address of your Home Assistant Glow, where you will find the line **Pulse rate - imp/kWh** in the table and you can then adjust it on the right. +Access the web interface by navigating to the IP address of your Home Assistant Glow. Once there, you'll find a table with a row labeled **Pulse rate - imp/kWh**, where you can easily adjust the value in the column on the right.

- + Pulse rate in the web interface

-### Option 2: In Home Assistant +### Option 2 - In Home Assistant 1. Go to the device overview page of the Home Assistant Glow, via [**Settings** > **Devices & Services** > **ESPHome**](https://my.home-assistant.io/redirect/integration/?domain=esphome). 2. Adjust the value for the entity **Pulse rate - imp/kWh**. For problems with the measurements, see the [FAQ page](/docs/faq). -## Step 5: Print Enclosure +## Step 5 - Print the case -The last step is to print a housing, the files for this can be found on the [cases page](/docs/reference/cases). If you do not have a 3D printer, there are platforms where you could place a print job or mount the Home Assistant Glow in a creative way 🙃 (my first concept was with cardboard). +The final step is to wrap everything up in a casing that you can print. The files for this can be found on the [case resources page](/docs/resources/cases). If you do not have a 3D printer, there are platforms where you could place a print job or mount the Home Assistant Glow in a creative way 🙃 -## Step 6: Sit back and relax +## Step 6 - Sit back and relax Congratulations 🎉 You have gone successfully through everything to get started with the Home Assistant Glow 🌟 If you have any questions, please check the [FAQ page](/docs/faq) first and if you can't find the answer there, you can always ask your question on the [Github](https://github.com/klaasnicolaas/home-assistant-glow). @@ -129,10 +141,6 @@ Congratulations 🎉 You have gone successfully through everything to get starte Affiliate links are used on this website to support the Home Assistant Glow 🌟 project. Some Ad-blockers might block these links, and thus they seem to appear broken. You will have to temporarily disable ad-blocker to open these links. -:::note -This page contains content derived from the [Upsy Desky documentation](https://upsy-desky.tjhorner.dev/) by [TJ Horner](https://github.com/tjhorner). The derived content is licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/deed.en). -::: - {/* Hardware */} [esp32-bg-shop]: https://www.banggood.com/bang/?tt=16956_12_417111_&r=https%3A%2F%2Fnl.banggood.com%2FGeekcreit-ESP32-WiFi%2Bbluetooth-Development-Board-Ultra-Low-Power-Consumption-Dual-Cores-Pins-Unsoldered-p-1214159.html [esp32-ali-shop]: https://tc.tradetracker.net/?c=15640&m=12&a=417111&r=&u=https%3A%2F%2Faliexpress.com%2Fitem%2F1005005970816555.html diff --git a/docs/docs/introduction.mdx b/docs/docs/introduction.mdx index c0849482..79bea4cf 100644 --- a/docs/docs/introduction.mdx +++ b/docs/docs/introduction.mdx @@ -8,7 +8,7 @@ description: What is the Home Assistant Glow?s During my internship at [Nabu Casa](https://www.nabucasa.com) in the first half of 2021, I focused on energy management for your house, how to collect all energy data and display it on a dashboard. Since Home Assistant release **2021.8** it's possible to use the [Home Assistant Energy](https://www.home-assistant.io/home-energy-management) dashboard to display your energy usage. Unfortunately, not everyone has a smart meter and/or is equipped with a P1 port. This is where the Home Assistant Glow comes in! -## What is this thing? +## What does it do? Home Assistant Glow makes a (not so) smart meter without a P1 port easily readable, using the pulse LED that is always present in most cases and it works with [ESPHome](https://esphome.io)! To neatly hide it all in your meter cupboard, a case has been designed that you can 3D print yourself. diff --git a/docs/docs/reference/diagram.mdx b/docs/docs/reference/diagram.mdx deleted file mode 100644 index 4da9135f..00000000 --- a/docs/docs/reference/diagram.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -id: diagram -title: Diagram -description: How to connect the Photodiode and Status LED based on diagrams ---- - -# Diagrams - -On this page you will find GPIO pin tables for the Photodiode and Status LED, as well as a wiring diagram of how everything is connected. - -## Wiring diagram - -Below you will find a wiring diagram of how everything is connected, depending on the type of board you use, the [GPIO pins](#gpio-pins) may be in a different place. You could also omit the status LED if desired. - -

- -

- -:::important -Please note that there are different boards in circulation and that the GPIO -pins may be on a different location than in the example above. So always double -check and, if necessary, consult the pin layout of your specific board. -::: - -## GPIO pins - -In the tables below you will find more information, about how to connect the Photodiode PCB and the status LED. - -### Photodiode - -How the Photodiode is connected to the ESP board of your choice. - -| PHOTODIODE | ESP32 | ESP8266 | -|------------|--------------|-------------| -| A0 | NOT USING | NOT USING | -| DO | D26 (GPIO26) | D7 (GPIO13) | -| VCC | 3V3 | 3V3 | -| GND | GND | GND | - -### Status LED - -How the status LED is connected to the ESP board of your choice. For each measured pulse, the LED will briefly flash *red* and in case of no WiFi connection, the LED will continue to flash *blue*. - -| LED | ESP32 | ESP8266 | -|--------|------------|------------| -| RED | D2 (GPIO2) | D4 (GPIO2) | -| GREEN | D4 (GPIO4) | D2 (GPIO4) | -| BLUE | D5 (GPIO5) | D1 (GPIO5) | -| GND | GND | GND | \ No newline at end of file diff --git a/docs/docs/reference/cases.mdx b/docs/docs/resources/cases.mdx similarity index 98% rename from docs/docs/reference/cases.mdx rename to docs/docs/resources/cases.mdx index e547275c..7783bb4a 100644 --- a/docs/docs/reference/cases.mdx +++ b/docs/docs/resources/cases.mdx @@ -1,10 +1,10 @@ --- id: cases -title: Cases +title: 3D Printed Cases description: Collection of all cases that you can 3D print --- -# Cases +# 3D Printed Cases On this page you will find all the cases that you can 3D print for the Home Assistant Glow. If you've made some changes on the cases, I'd appreciate it if you add the new case design to the repository for everyone to benefit 😉 diff --git a/docs/docs/resources/gpio.mdx b/docs/docs/resources/gpio.mdx new file mode 100644 index 00000000..9ffa2ae8 --- /dev/null +++ b/docs/docs/resources/gpio.mdx @@ -0,0 +1,31 @@ +--- +id: gpio +title: GPIO Pinout +description: GPIO pinout of the ESP32 and ESP8266 boards +--- + +# GPIO Pinout + +In this section, you will find the GPIO pinout of the ESP32 and ESP8266 boards. The GPIO pins are used to connect the Photodiode and Status LED to the ESP board of your choice. + +## Photodiode + +How the Photodiode is connected to the ESP board of your choice. + +| PHOTODIODE | ESP32 | ESP8266 | +|------------|--------------|-------------| +| A0 | NOT USING | NOT USING | +| DO | D26 (GPIO26) | D7 (GPIO13) | +| VCC | 3V3 | 3V3 | +| GND | GND | GND | + +## Status LED + +How the status LED is connected to the ESP board of your choice. For each measured pulse, the LED will briefly flash *red* and in case of no WiFi connection, the LED will continue to flash *blue*. + +| LED | ESP32 | ESP8266 | +|--------|------------|------------| +| RED | D2 (GPIO2) | D4 (GPIO2) | +| GREEN | D4 (GPIO4) | D2 (GPIO4) | +| BLUE | D5 (GPIO5) | D1 (GPIO5) | +| GND | GND | GND | \ No newline at end of file diff --git a/docs/docs/resources/schematics.mdx b/docs/docs/resources/schematics.mdx new file mode 100644 index 00000000..cc25cf93 --- /dev/null +++ b/docs/docs/resources/schematics.mdx @@ -0,0 +1,27 @@ +--- +id: schematics +title: Schematics +description: How to connect the Photodiode and Status LED based on wiring diagram +--- + +# Schematics + +In this section, you will find the wiring diagram of how to connect the Photodiode and Status LED to the ESP board of your choice. + +## Wiring diagram + +Below you will find a wiring diagram of how everything is connected, depending on the type of board you use, the [GPIO pins](/docs/resources/gpio) may be in a different place. You could also omit the status LED if desired. + +

+ Wiring diagram showing connections between Photodiode, Status LED, and ESP board +

+ +:::important +Please note that there are different boards in circulation and that the GPIO +pins may be on a different location than in the example above. So always double +check and, if necessary, consult the pin layout of your specific board. +::: \ No newline at end of file diff --git a/docs/sidebars.ts b/docs/sidebars.ts index 37750b10..55276e98 100644 --- a/docs/sidebars.ts +++ b/docs/sidebars.ts @@ -15,23 +15,34 @@ const sidebars: SidebarsConfig = { docSidebar: [ 'introduction', 'getting-started', - 'configuration', { type: 'category', collapsed: false, - label: 'Reference', + label: 'Configuration', items: [ - 'reference/diagram', - 'reference/cases', + 'configuration/pulse_rate', + 'configuration/rename', + 'configuration/energy_dashboard', ], }, { type: 'category', label: 'Advanced', items: [ - 'advanced/firmware_customization', + 'advanced/firmware_changes', + 'advanced/firmware_updates', ], - } + }, + { + type: 'category', + collapsed: false, + label: 'Resources', + items: [ + 'resources/schematics', + 'resources/gpio', + 'resources/cases', + ], + }, ], // But you can create a sidebar manually diff --git a/docs/static/img/advanced/glow_update-esphome.png b/docs/static/img/advanced/glow_update-esphome.png new file mode 100644 index 00000000..0dd4cb19 Binary files /dev/null and b/docs/static/img/advanced/glow_update-esphome.png differ diff --git a/docs/static/img/advanced/glow_update-popup.png b/docs/static/img/advanced/glow_update-popup.png new file mode 100644 index 00000000..e8498c2b Binary files /dev/null and b/docs/static/img/advanced/glow_update-popup.png differ diff --git a/home-assistant-glow/esp32.yaml b/home-assistant-glow/esp32.yaml index 916abbd3..27cf6d1f 100644 --- a/home-assistant-glow/esp32.yaml +++ b/home-assistant-glow/esp32.yaml @@ -8,7 +8,7 @@ substitutions: device_name: home-assistant-glow friendly_name: Home Assistant Glow - project_version: "4.2.2" + project_version: "4.2.3" device_description: "Measure your energy consumption with the pulse LED on your smart meter - ESP32 Generic" # Define the GPIO pins @@ -37,7 +37,7 @@ esp32: packages: remote_package: url: https://github.com/klaasnicolaas/home-assistant-glow/ - ref: "4.2.2" + ref: "4.2.3" files: - components/basis.yaml - components/updates.yaml diff --git a/home-assistant-glow/esp8266.yaml b/home-assistant-glow/esp8266.yaml index f53f18bd..6ffe7b86 100644 --- a/home-assistant-glow/esp8266.yaml +++ b/home-assistant-glow/esp8266.yaml @@ -8,7 +8,7 @@ substitutions: device_name: home-assistant-glow friendly_name: Home Assistant Glow - project_version: "4.2.2" + project_version: "4.2.3" device_description: "Measure your energy consumption with the pulse LED on your smart meter - ESP8266 Generic" # Define the GPIO pins @@ -35,7 +35,7 @@ esp8266: packages: remote_package: url: https://github.com/klaasnicolaas/home-assistant-glow/ - ref: "4.2.2" + ref: "4.2.3" files: - components/basis.yaml - components/updates.yaml