Development of add-on - why are the docs so sparse and unhelpful?

Development
6

Sorry, was very cranky yesterday after that experience. I have some recommendations to make things easier for anyone else wanting to develop an add-on.

I use PyCharm, so the devcontainers set up wasn’t an option.

  • Develop your add-on locally, on the HASS machine by using studio code server and placing your add-on folder into the /addons directory.
    • make sure the image: key is commented out in your config.yaml file, to force supervisor to build the add-on docker image locally

In order to pull new changes into your LOCAL add-on:

  • Navigate to the add-on management page (where the start / stop / restart / rebuild/ open webui buttons are)
  • For README.md, DOCS.md and CHANGELOG.md: Do a CTRL + F5 refresh on the add-on management page
  • For logo.png and icon.png: Do a CTRL + F5 refresh on the add-on management page
  • For Dockerfile: Click the REBUILD button to delete the current image and rebuild a new one from scratch (no docker build caching, whenever you press REBUILD, the Dockerfile is re-read)
  • For config.yaml (Configuration tab) changes, it wont show until you REBUILD the image (also translations/, apparmor.txt, run.sh and build.yaml changes)

After rebuild, your new changes will be in the add-on image/container (config.yaml changes will be reflected; new options / schema / permissions/ mappings / etc.). You may need to CTRL + F5 refresh, though.

Example file structure

/addons
├── /cync-lan
    ├── /translations
      ├── en.yaml
    ├── apparmor.txt
    ├── build.yaml
    ├── config.yaml
    ├── Dockerfile
    ├── run.sh
    ├── icon.png
    ├── logo.png
    ├── README.md
    ├── DOCS.md
    ├── CHANGELOG.md
    ├── LICENSE

I added a log output with a string as a sanity check. So, when my code runs, I can be sure the latest code was pulled in after the rebuild (change the string before REBUILD):

SANITY_CHECK = "new_code_pulled_23"

# <rest of code>
logger.info(f"{SANITY_CHECK = }")

Edit: Also, it is a good idea to configure HASS to open SSH port 22222 to the host. There is an add-on that can do this for you, or you can follow the debugging docs and create a USB drive to load SSH keys into HASS to enable port 22222 host SSH.

When you are installing/building your add-on, all the good debug logs are in the hassio_supervisor container.

  • open a terminal and run ssh root@HASS_IP -p 22222
  • once logged into the hass host, follow the supervisor logs: docker logs -f hassio_supervisor
  • Now you’'ll see useful debug logs when installing, rebuilding and ‘checking for updates’

Edit 2: You can also use the HASS web UI to view the supervisor logs, but I find having terminal output is much better for debugging

2 Likes