init emhass test image

emhass-test/DOCS.md

@@ -0,0 +1,97 @@
+<!-- markdown file presented on the documentation tab -->
+
+# EMHASS Add-on
+
+<div>
+ <a style="text-decoration:none" href="https://emhass.readthedocs.io/en/latest/">
+      <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Documentation_button.svg" alt="EMHASS Documentation">
+  </a>
+   <a style="text-decoration:none" href="https://community.home-assistant.io/t/emhass-an-energy-management-for-home-assistant/338126">
+      <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Community_button.svg" alt="Community">
+  </a>
+  <a style="text-decoration:none" href="https://github.com/davidusb-geek/emhass/issues">
+      <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Issues_button.svg" alt="Issues">
+  </a>
+  <a style="text-decoration:none" href="https://github.com/davidusb-geek/emhass-add-on">
+     <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/EMHASS_Add_on_button.svg" alt="EMHASS Add-on">
+  </a>
+  <a style="text-decoration:none" href="https://github.com/davidusb-geek/emhass">
+     <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/EMHASS_button.svg" alt="EMHASS">
+  </a>
+</div>
+
+---
+
+### A Home Assistant Add-on for the EMHASS (Energy Management for Home Assistant) module
+
+</br>
+
+<div style="display: flex;">
+This add-on uses the EMHASS core module from the following GitHub repository:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://github.com/davidusb-geek/emhass">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/EMHASS_button.svg" alt="EMHASS">
+</a>
+</div>
+
+</br>
+
+<div style="display: flex;">
+The complete documentation for this module can be found here:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://emhass.readthedocs.io/en/latest/">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Documentation_button.svg" alt="Documentation">
+</a>
+</div>
+
+</br>
+
+<div style="display: flex;">
+For any questions on EMHASS or EMHASS-Add-on:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://community.home-assistant.io/t/emhass-an-energy-management-for-home-assistant/338126">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Community_button.svg" alt="Community">
+</a>
+</div>
+
+</br>
+
+<div style="display: flex;">
+For any Issues/Feature Requests for the EMHASS core module, create a new issue here:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://github.com/davidusb-geek/emhass/issues">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Issues_button.svg" alt="Issues">
+</a>
+</div>
+
+## Developing EMHASS/EMHASS-Add-on
+
+#### **EMHASS**
+For those who want to develop the EMHASS package itself. Have a look at the [Develop page](https://emhass.readthedocs.io/en/latest/develop.html). _(EMHASS docs)_ 
+
+#### **EMHASS-Add-on**
+For those who want to test the EMHASS addon _(EMHASS inside of a virtual Home Assistant Environment)_. Have a look at [Test Markdown](./emhass/Test.md).
+
+## License
+
+MIT License
+
+Copyright (c) 2021-2023 David HERNANDEZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emhass-test/README.md

@@ -0,0 +1,133 @@
+<!-- markdown file presented on the main addon info tab -->
+
+# EMHASS Add-on
+
+### A Home Assistant Add-on for the EMHASS module: Energy Management for Home Assistant
+
+</br>
+
+<div style="display: flex;">
+This add-on uses the EMHASS core module from the following GitHub repository:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://github.com/davidusb-geek/emhass">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/EMHASS_button.svg" alt="EMHASS">
+</a>
+</div>
+
+</br>
+
+<div style="display: flex;">
+The complete documentation for this module can be found here:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://emhass.readthedocs.io/en/latest/">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Documentation_button.svg" alt="Documentation">
+</a>
+</div>
+
+</br>
+
+<div style="display: flex;">
+For any questions on EMHASS or EMHASS-Add-on:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://community.home-assistant.io/t/emhass-an-energy-management-for-home-assistant/338126">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Community_button.svg" alt="Community">
+</a>
+</div>
+
+</br>
+
+<div style="display: flex;">
+For any Issues/Feature Requests for the EMHASS core module, create a new issue here:
+&nbsp; &nbsp;
+<a style="text-decoration:none" href="https://github.com/davidusb-geek/emhass/issues">
+    <img src="https://raw.githubusercontent.com/davidusb-geek/emhass/master/docs/images/Issues_button.svg" alt="Issues">
+</a>
+</div>
+
+## Installation
+
+The steps to install EMHASS as an Home Assistant addon:
+
+1) Add the EMHASS-Add-on repository to the HAOS add-on store
+
+    - To install add the EMHASS Add-on repository in the Home Assistant store, follow [these steps](https://www.home-assistant.io/common-tasks/os/#installing-third-party-add-ons)
+
+    - This will be: Configuration > Add-ons & Backups open the add-on store > Add the URL of the repository (e.g https://github.com/davidusb-geek/emhass-add-on) and then press "Add".
+
+2) Install the EMHASS Add-on 
+    - Look for the EMHASS Add-on tab and when inside the Add-on click on `install`.
+      - The installation may take some time depending on your hardware.
+
+3) Start the EMHASS addon
+    - Once installed, head into the EMHASS addon
+    - click `start` to start the EMHASS web server
+      -  For consistent use, it is recommended that you enable: `Show in sidebar`,`Watchdog` and `Start on boot `
+
+4) Open the EMHASS web interface, and configure parameters
+    - Click `OPEN WEB UI` to enter the EMHASS web server
+    - Click the cog icon ⚙️  to to enter the emhass configuration page
+    - Insert your user specific parameters
+      - For users who wish to use `Solcast` or `Forecast.Solar` insert your secrets in the Home Assistant EMHASS configuration page, under `Show unused optional configuration options`. (E.g: `localhost:8123/hassio/addon/emhass/config`)
+
+## Installation Method 2 - Manually changing EMHASS version
+This method allows the user to select which EMHASS version to run _(via adjusting the Docker version tag)_. This second method of installation may be more preferable for users who wish to test EMHASS or rollback to a older stable version.   
+_Warning: This method will override the Docker image tag, and therefore will require the user to manually adjust the tag to update. The user will also need to regularly check to see if the EMHASS-Add-on repository is up to date with the Github `main` branch_
+
+1) Have a method of inserting commands
+    - Two Addon options are [Terminal & SSH](https://github.com/home-assistant/addons/tree/master/ssh) and Community Add-on: [Studio Code Server](https://github.com/hassio-addons/addon-vscode)
+
+2) Clone the `EMHASS-Add-on` repository into your `/addons` directory 
+    ```bash
+    cd ~/addons/
+    git clone https://github.com/davidusb-geek/emhass-add-on.git
+    ```
+
+3) Specify what EMHASS version image to use
+    - in the `emhass-add-on/emhass/config.yml` adjust the `version:` line to match the version of choice:
+      ```bash
+      # set version here 
+      emhassVersion=v0.20.0
+      # sed command to replace version line in config.yml 
+      sed -i.bak "s/version:.*/version: $emhassVersion/g"  ~/addons/emhass-add-on/emhass/config.yml
+      ```
+4) Head to the Home Assistant add-on store and refresh addon cache
+    - Settings > Add-ons > Add-on Store
+    - Refresh Addon cache with: hamburger icon ☰ > Check for updates
+    - Wait half a minute and refresh the page 
+
+5) Install local version of EMHASS 
+    - From here a new Addon Source under the name `Local add-ons` should appear _(if not repeat step 4)_
+    - Install the EMHASS addon, Note: after clicking the EMHASS addon, the `Current version: ` Tag on the top left of the EMHASS card.
+
+
+## Developing EMHASS/EMHASS-Add-on
+
+#### **EMHASS**
+For those who want to develop the EMHASS package itself. Have a look at the [Develop page](https://emhass.readthedocs.io/en/latest/develop.html). _(EMHASS docs)_ 
+
+#### **EMHASS-Add-on**
+For those who want to test the EMHASS addon _(EMHASS inside of a virtual Home Assistant Environment)_. Have a look at [Test Markdown](./Test.md).
+
+## License
+
+MIT License
+
+Copyright (c) 2021-2025 David HERNANDEZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emhass-test/Test.md

@@ -0,0 +1,140 @@
+# Testing EMHASS-Add-on
+
+To fully test EMHASS and its EMHASS-Add-on integration, you will likely want to test the EMHASS addon in a Home Assistant Operating System environment (HAOS/Supervisor).
+
+The common Home Assistant options are:
+
+- Adding EMHASS-Add-on into a pre-existing Home Assistant environment.
+- Testing EMHASS-Add-on on a Home Assistant with virtual test environment with VS-Code Dev Containers.
+
+See the following steps for both options.
+
+_Note: The following examples are for testing the EMHASS-Add-on integration with Home Assistant. To develop/test the EMHASS Package and its Docker container itself, check the EMHASS [Develop page](https://emhass.readthedocs.io/en/latest/develop.html)_.
+
+## Develop on VS-Code Dev Container with Home Assistant test environment
+
+Using VS-Code Dev Containers, you can generate a Home Assistant test environment for the EMHASS Add-on before release. The steps to achieve this are as follows:  
+</br>
+_Note: These following steps require VS-Code and the Dev Container Extension to be installed and operational. See ['Developing inside a Container'](https://code.visualstudio.com/docs/DevContainers/containers) for more information._
+
+
+1) Git clone `EMHASS-Add-on` repository and open VS-code 
+    ```bash
+    git clone https://github.com/davidusb-geek/emhass-add-on.git
+    cd emhass-add-on
+    code .
+    ```
+
+2) Adjust the EMHASS image to the version you would like to test. To adjust the image, you may select one of three options:
+    - Change the EMHASS Docker image version tag
+    - Change the EMHASS Docker image repository
+    - Build a custom image of EMHASS locally  
+
+    See [Customizing EMHASS](##Customizing-EMHASS) for more information.
+
+3) Run Home Assistant Environment
+    - Run _(if not already)_  the VS-Code Dev Container
+      - Shortcut: `F1` > `Dev Containers: Rebuild and Reopen in Container`
+    - Start VS-Code Task to start Home Assistant 
+      - `ctrl+shift+p`>`Tasks: Run Task`> `Start Home Assistant`
+      - Login to the generated HA Portal: `localhost:7123`
+      - Navigate to Home Assistant: 
+        - `Add-ons` > `ADD-ON STORE`
+      - Install/Run and Test Add-on
+        - For more information see Home Assistant's [Local add-on testing](https://developers.home-assistant.io/docs/add-ons/testing).
+
+_Note: If, on run, the emhass version looks off. Try: uninstalling Add-on, `check for updates` on Add-on Store page, and re-installing._
+
+## Adding EMHASS-Add-on into pre-existing Home Assistant environment
+
+If you would like to test a version of EMHASS-Add-on inside a pre-existing Home Assistant (with Supervisor) environment, see the following steps:
+
+1) With your preferred method of choice, clone the emhass-add-on repository to the addons folder
+    - One method is to use the [`Home Assistant Add-on: SSH server`](https://github.com/home-assistant/addons/blob/master/ssh/DOCS.md) addon to add:
+      - Install addon and click `OPEN WEB UI`
+        - See [SSH Addon README](https://github.com/home-assistant/addons/blob/master/ssh/DOCS.md#installation) for install steps
+      - Type commands to clone repository:
+        ```bash
+        cd ~/addons
+        git clone https://github.com/davidusb-geek/emhass-add-on
+        cd ./emhass-add-on
+        ```
+2) Adjust the EMHASS image to the version you would like to test. To adjust the image, you may select one of three options:
+    - Change the EMHASS Docker image version tag
+    - Change the EMHASS Docker image repository
+    - Build a custom image of EMHASS locally  
+
+    See [Customizing EMHASS](##Customizing-EMHASS) for more information.
+
+3) Run EMHASS addon:
+    - head to Home Assistant: `Add-ons` > `ADD-ON STORE`
+      - you should see an `EMHASS` Add-on under `Local add-ons`
+        - If you do not, try hamburger icon ☰ on top right > `check updates` > refresh page
+    - Install and test Add-on
+    - Use the Supervisor logs _(on the config/logs page)_ to see any logs with the Add-on.
+
+</br>
+
+_Note: If, on run, the emhass version looks off. Try: uninstalling Add-on, check for updates on the Add-on Store page, and re-install._
+
+## Customizing EMHASS 
+If you are testing EMHASS-Add-on, it is likely that you would want to select a particular version of EMHASS to run and test.
+There are different methods of achieving this, depending on where the source of the desired EMHASS package resigns. See examples bellow: 
+
+### Change the EMHASS Docker image version tag
+If you would like to solely change the EMHASS version _(i.e. Image tag)_ of the EMHASS package. (keeping the Docker repository to [ghcr.io/davidusb-geek/emhass](https://github.com/davidusb-geek/emhass/pkgs/container/emhass)). Follow the steps bellow:
+
+1) Change the `version:` line in the emhass-add-on `config.yml`:
+    ```bash
+    emhassVersion=v0.20.0
+    sed -i.bak "s/version:.*/version: $emhassVersion/g"  ~/addons/emhass-add-on/emhass/config.yml
+    ```
+*Make sure the version you select matches one of the tagged images in https://github.com/davidusb-geek/emhass/pkgs/container/emhass*
+
+### Change the EMHASS Docker image repository
+If you would like to test your own forked version of EMHASS, the container repository can be changed to match your forked repository. The steps to accomplish this include:  
+ _(building your own EMHASS image)_
+
+1) If not already, enable the Github Actions in your EMHASS fork 
+    - Head to the actions tag on your github fork (E.g. https://github.com/YOURUSERNAME/emhass/actions)
+    - Read the warnings and observe the workflow files on the repo (https://github.com/YOURUSERNAME/emhass/tree/master/.github/workflows)
+    - If you understand the workflows and accept the warnings, press `I understand my workflows, go ahead and enable them`
+
+2) Create a github release of your EMHASS fork
+    - In your EMHASS fork, draft a new release to trigger the github action to build the docker image 
+      - Head the releases page of your fork and draft a new release (https://github.com/YOURUSERNAME/emhass/releases/new)
+    - In `choose a new tag` create a new suitable tag name (E.g. `v2.0.0`)
+    - Change `Target` if you wish to select a branch that is not the default `master`
+    - When happy, click `publish release`
+    - Head to the Actions page of your fork again to observe the `publish_docker` workflow running. Once its finished, if successful, a new Docker image should be available in the packages page of your Github repo (https://github.com/YOURUSERNAME/emhass/pkgs/container/emhass) 
+
+3) In your home assistant environment change the `version:` and `image:` lines in the addons config.yml
+    - In the package page on Github copy the repository url and tag name provided (E.g. Repo:`ghcr.io/YOURUSERNAME/emhass` Tag:`v2.0.0`)
+    - Edit the version/tag and image/repo sections of the config.yaml
+      ```bash
+      emhassVersion=v2.0.0
+      emhassRepo="ghcr.io/YOURUSERNAME/emhass"
+      sed -i.bak "s%version:.*%version: $emhassVersion%g"  ~/addons/emhass-add-on/emhass/config.yml
+      sed -i.bak "s%image:.*%image: $emhassRepo%g"  ~/addons/emhass-add-on/emhass/config.yml
+      ```
+
+ ### Build a custom image of EMHASS locally
+ The last option requires merging the EMHASS-Add-on and EMHASS repository together, allowing the user to build EMHASS, and the Docker container locally. The best use case for this method if for rapid testing. Since you can adjust the emhass source files and rebuild the addon. This is the most complicated approach and the example bellow is not guaranteed to work.
+
+```bash
+cd ~/addons/emhass-add-on/
+# git clone EMHASS repo (or forked emhass repo)
+git clone https://github.com/davidusb-geek/emhass.git ./emhass-git
+# copy required EMHASS files to the emhass-add-on root
+cp ./emhass-git/Dockerfile ./emhass/
+cp ./emhass-git/requirements.txt ./emhass/
+cp ./emhass-git/README.md ./emhass/README.md
+cp -R ./emhass-git/src ./emhass/
+cp -R ./emhass-git/setup.py ./emhass/
+cp -R ./emhass-git/data ./emhass/
+# comment out the `image:` line of the emhass-add-on config.yml file. To tell Home Assistant to build the Dockerfile locally
+sed -i.bak '/image:/ s/./#&/' ~/addons/emhass-add-on/emhass/config.yml
+# Replace TARGETARCH with BUILD_ARCH (Home Assistant Build ARG) in Dockerfile 
+sed -i.bak "s/TARGETARCH/BUILD_ARCH/g"  ~/addons/emhass-add-on/emhass/Dockerfile
+```
+*Note: It is recommended to regularly adjust the `version:` tag_(in `config.yml`)_ after a change and before a test. This helps the user to check if Home Assistant has received the update.*