Skip to content

Contributing

Jump to bottom
David edited this page Feb 10, 2024 · 5 revisions

Here is a complete guide from @GeoDerp to help setting the environments for developing. The original message was posted on PR#182

This is an optional pull request uses VS-Code Dev container or Dockerfile (as an sandboxed environment) for debugging and testing the application. Both of which where designed with focus on running with Add-on mode. And both need an additional HA environment to operate (no supervisor support for the moment)

Method 1: VS-Code Debug and Run

Recommended steps to run are:

  • Pull in the git repo (or Fork), open the root (emhass) foulder in VS-Code
  • VS-Code will asks if you want to run in a dev-container, say yes (Docker environment must be set up first). This give us a development environment we can test without messing with the host device. (I believe codespaces does this by default) To run and test: (via VS-Code Run and Debug)
  • Compile emhass by pressing control+shift+p > Tasks: Run Task > EMHASS Install. This has been set up in the tasks.json file. Re-run this every time a change has been made emhass before run & debug.
  • Launch and debug the application selecting the Run and Debug tab (Ctrl+Shift+D.) > EMHASS run Addon. This has been setup in the Launch.json. You will need to modify the EMHASS_URL (http://HAIPHERE:8123/) and EMHASS_KEY (PLACEKEYHERE) before running to match your HA environment in order to work. you can also choose to run EMHASS run. This acts more like standalone mode and uses the secrets file (however less tested)
  • If you want to change your parameters, I tend to do this in the options.json file before launch.
  • You can also run all the pytests by going to the Testing tab on the left hand side

Method 2: Dockerfile run

Alternatively: This PR also adds a dockerfile that tries to emulate the Add-on environment as best as possible. This method is slower, however does not need VS-code to run (just Docker environment) Run it on the emhass root dir with: (It is recommended to run this on the host device, rather than an dev container)

docker build -t emhass/testing -f Add-onEmulateDocker .
docker run -it -p 5000:5000 --name emhass-test docker.io/emhass/testing --url YOURHAURLHERE --key YOURHAKEYHERE

Delete docker container and image with:

docker rm  emhass-test
docker rmi emhass/testing

For Rapid testing try a command chain like this: Bash Example

docker rm -f emhass-test ; docker build -t emhass/testing -f Add-onEmulateDocker . && docker run -it -p 5001:5000 --name emhass-test docker.io/emhass/testing --url YOURHAURLHERE --key YOURHAKEYHERE

With example above use secrets_emhass.yaml or options.yaml file to set time_zone,Lat,Lon & Alt

Docker Alternative

We can also pass location, key and url parameters via environment variables

docker build -t emhass/testing -f Add-onEmulateDocker .
docker run -it -p 5000:5000 --name emhass-test -e URL="YOURHAURLHERE" -e KEY="YOURHAKEYHERE" -e LAT="45.83" -e LON="6.86" -e ALT="4807.8" docker.io/emhass/testing

This allows the user to set variables prior to build Linux Example: (in you host terminal)

export EMHASS_URL="YOURHAURLHERE"
export EMHASS_KEY="YOURHAKEYHERE"
export TIME_ZONE="Europe/Paris"
export LAT="45.83"
export LON="45.83"
export ALT="4807.8"

docker build -t emhass/testing -f Add-onEmulateDocker .
docker run -it -p 5001:5000 --name emhass-test  -e EMHASS_KEY -e EMHASS_URL -e TIME_ZONE  -e LAT -e LON -e ALT  docker.io/emhass/testing

Note:

  • both methods can use the secrets_emhass.yaml instead of passing secret parameters as environment variables/ arguments
  • I cant vouch for the security of passing in the secrets via Environment Variables and arguments. User discretion advised. This is designed for testing with an secure host

Old guide for development with basic virtual env creation and package build commands

Create a developer environment: virtualenv -p /usr/bin/python3 emhass-dev

To develop using Anaconda use (pick the correct Python and Pip versions): conda create --name emhass-dev python=3.8 pip=21.0.1

Then activate environment and install the required packages using: pip install -r requirements.txt

Add emhass to the Python path using the path to src, for example: /home/user/emhass/src

If working on linux we can add these lines to the ~/.bashrc file:

# Python modules
export PYTHONPATH="${PYTHONPATH}:/home/user/emhass/src"

Don't foget to source the ~/.bashrc file: source ~/.bashrc

Update the build package: python3 -m pip install --upgrade build

And generate distribution archives with: python3 -m build

Or with: python3 setup.py build bdist_wheel

Create a new tag version: git tag vX.X.X

And push the tag: git push origin --tags

Upload to pypi: twine upload dist/*

Clone this wiki locally