Editing (ZHA) quirks in a (HA) container or local.

[MattWestb]

The guide on the main page it working very well but i always having problem then doing editing one file in the docker container.
For real beginners: The filesystem in one docker container can normally NOT being assessed from the host system then its isolated form the host system and must being done thru one terminal in the docker container and instructed above.
Then im no real unix person (the first Linux was around 0.95 with X-windows was optional to install with some extra floppy disks but i'm not being 110% hooked on it and moved on by skipping Windows 9X and landed in OS/2 but im not complete lost in that world) and the HA container is really stripped and no disent editor is installed (what i have finding at least) and VI is not my friend.
In Linux CLI i normally using nano that is not super but OK for my level.
I have trying installing different text editors with pip but was not finding any that i like until testing suplemon that is pretty easy to understand without much knowledge.
Install it from the docker container command prompt with pip install suplemon and then open one file with command like this:
suplemon /usr/local/lib/python3.10/site-packages/zhaquirks/tuya/valve.py

Installing with pip:

pip install suplemon
Collecting suplemon
  Downloading Suplemon-0.2.1.tar.gz (61 kB)
     |████████████████████████████████| 61 kB 4.4 kB/s
Requirement already satisfied: pygments in /usr/local/lib/python3.9/site-packages (from suplemon) (2.7.3)
Requirement already satisfied: wcwidth in /usr/local/lib/python3.9/site-packages (from suplemon) (0.2.5)
Building wheels for collected packages: suplemon
  Building wheel for suplemon (setup.py) ... done
  Created wheel for suplemon: filename=Suplemon-0.2.1-py3-none-any.whl size=79536 sha256=63b1197afe555b122dda80d508728ad869ad9bc1756056074c454c2dd45131da
  Stored in directory: /root/.cache/pip/wheels/5a/96/87/d217c2003335e2d1f0b3b3a4f361a00f82c830630715314542
Successfully built suplemon
Installing collected packages: suplemon
Successfully installed suplemon-0.2.1

Editing HAs configuration.yaml: suplemon /config/configuration.yam

 🍋 Suplemon Editor v0.2.1 - ⌚13:05 02.01. [configuration.yaml] ]
  1
  2 # Configure a default setup of Home Assistant (frontend, api, etc)
  3 default_config:h scripts.yaml
  4 #tts:: !include scenes.yaml
  5 # Uncomment this if you are using SSL/TLS, running in Docker container, etc.
  6 # http:n: mdi:chip
  7 #   base_url: example.duckdns.org:8123
 14 automation: !include automations.yaml
 21 #    title: 'MQTT433gateway'
 22 #    icon: mdi:alpha-p-box-outline
 31 #    url: 'http://192.168.2.121'
 32 #  port_tainer:
 33 #    title: 'Portainer'
 34 #    icon: mdi:docker
 27     url: 'http://192.168.2.13:6052''
 36
 37
 38 panel_custom:
 39   - name: custom-panel-zigzag
 40     sidebar_title: Zigzag
 41     sidebar_icon: mdi:zigbee
 42     url_path: zigzag
 43     module_url: /local/zigzag/zigzag-panel.js
 44     trust_external_script: true
 45     config:

^S Save F1 Save as F2 Reload F5 Undo F6 Redo ^O Open ^C Copy ^X Cut ^V Paste ^F Find ^D Find next ^A Find all ^K Duplicate line
ESC Single cursor ^G Go to ^E Run command F8 Mouse mode ^H Help ^Q Exit
                                                                                      host:home-assistant.local.hass.io  @0,0 cur:1 buf:0

Copy and paste with mouse is supported as scrolling with mouse and commands is showing in the underline for easy getting started for beginners / low end users like my.

Question: Do you knowing some other better or easier text editor for using in HA container for editing files and how to installing it in the container ?
Pleas writing your experience of it so other users can getting on the train and easy start editing there files (then needed and not too much).
Also if some editors have support for our friends black and company and python formatting for helping doing the coding working OK.

To edit other files in ZHA / zigpy suit is found under:

ls /usr/local/lib/python3.10/site-packages/

bellows-0.21.0.dist-info
bellows
zha_quirks-0.0.49.dist-info
zhaquirks
zigpy
zigpy-0.28.2.dist-info
zigpy_cc
zigpy_cc-0.5.2.dist-info
zigpy_deconz
zigpy_deconz-0.11.0.dist-info
zigpy_xbee
zigpy_xbee-0.13.0.dist-info
zigpy_zigate
zigpy_zigate-0.7.3.dist-info
zigpy_znp
zigpy_znp-0.3.0.dist-info
zipp-3.4.0.dist-info
zipp.py

One more good thing if trying one updated package before HA have released it is editing the ZHAs manifest.json with:
suplemon /usr/src/homeassistant/homeassistant/components/zha/manifest.json

And editing the component version you like to using and restarting HA and its being installed.

 🍋 Suplemon Editor v0.2.1 - ⌚13:24 02.01. [manifest.json]
 1 {
 2   "domain": "zha",
 3   "name": "Zigbee Home Automation",
 4   "config_flow": true,
 5   "documentation": "https://www.home-assistant.io/integrations/zha",
 6   "requirements": [
 7     "bellows==0.21.0",
 8     "pyserial==3.4",
 9     "pyserial-asyncio==0.4",
10     "zha-quirks==0.0.49",
11     "zigpy-cc==0.5.2",
12     "zigpy-deconz==0.11.0",
13     "zigpy==0.28.2",
14     "zigpy-xbee==0.13.0",
15     "zigpy-zigate==0.7.3",
16     "zigpy-znp==0.3.0"
17   ],
18   "codeowners": ["@dmulcahey", "@adminiuga"]
19 }
20






^S Save F1 Save as F2 Reload F5 Undo F6 Redo ^O Open ^C Copy ^X Cut ^V Paste
^F Find ^D Find next ^A Find all ^K Duplicate line ESC Single cursor ^G Go to
                               host:home-assistant.local.hass.io  @0,0 cur:1 buf:0

Warning it can being that some components is not compatible with other versions then the devs have making changes that is needed in to being adopted in more than one package and is being broken if having the same patch levels of them (example API changes between radio and main zigpy packages both need having the same level of patches or ZHA is broken).

One good / bad thing its the installed editor is gone then updating the container so must reinstalling in if need doing new changes to files after HA / ZHA updates.

[MattWestb]

Problem with dependencies after installing custom libs.

If you is installing custom libs with pip and updating your ha installation, its not deleting your custom installed libs and can making problems with dependencies is being broken and you system is not working well.

If you is using docker and have pip installed packages they is stored locally in /config/deps/
Open one CLI to your HA container and execute rm -r /config/deps/ and the restarting HA and all old libs is away and HAs dependencies is being OK.

You can also deleting packages little more selective one by one and leaving that you dont like deleting.

This method is also working if you is having testing radio-libs and installing them with pip or copy them to the /config/deps for getting them overriding the libs that HA is having in its container.

If you have installing packages by modding zha/manifest.json method from the first posting its normally being over written then you is updating HA container and then you is back to standard installed HA with OK dependencies.
You can looking wot versions of your libs that is installed in the container with ls /usr/local/lib/python3.9/site-packages/ and comparing with the manifest and wot version you is expecting to being installed.

[MattWestb]

New method adding local quirks in HA

For getting the local quirk folder to working add this in HA config:

zha:
  custom_quirks_path: /config/custom_zha_quirks/

Making one folder with the name custom_zha_quirks in you HA config directory.
Putting the quirk file in the folder and restarting HA.

Warning: ZHA is not loading if not finding configured folder or the quirk is having fatal fault.

If its being loaded you see the local quirk have path the device property is short and is only the name and not the full path like Quirk: fourbtnremote.IkeaTradfriRemote and the normal quirk is shown like Quirk: zhaquirks.ikea.fivebtnremotezha.IkeaTradfriRemote.

Then you have making changes you need deleting the __pycache__ folder in your temporary quirk fold and restarting HA for the changes taking place, alternative restarting ZHA from integration card (only working if local quirks is enabled after last HA restart).
Some times ZHA is not loading the device information from the database OK and the quirks is not being loaded then reload ZHA and its normally working OK.

All local quirk is using the (in HA) installed quirk heritage so if you is doing one new quirk XXX.py and no __init__.py its working OK but if you is updating one quirk YYYYY.py and / or __init__.py for the quirk its not working then the YYYY.py is not getting the data from the local __init__.py but from the (HA) installed __init__.py so then you need doing one (or all) of the changes in the container for getting it working #693 (comment).
Some devs can doing temporary __init__.py and quirk files that is working in the local quirk directors but is not recommended doing it self then it need making changes for adding the working quirk in ZHA.

The priority for matching quirks is first local quirk and then ZHA builtin. In one quirk is the first (earlier device class in the code) is matched then the system is loading it and do not trying more device classes (its being used for TS004F for special devices in the beginning and general deceives without "extras" is at the end if the quirk).

For getting important information from the system and the device pleas adding little more debut logging then testing new quirks. Instruction for setting debug logging: #693 (comment).

Also then the quirk is merged in (Z)HA you shall deleting the "temporary quirk" for not getting problem in the future then the local quirks is not being deleted then updating the HA container and you is not getting updates for it and can getting broken in the future.

Pleas making one PR if you have making one working quirk for your device so other user can using there devices in ZHA.

Instruction for making PRs: #693 (comment)

[MattWestb]

Jeedom's zigpy-based zigbee plugin

You juste have to past it in this folder: /var/www/html/plugins/zigbee/resources/zigbeed/quirks than restart deamon.

(For the moment untested !!)

[MattWestb]

Editing files in Home Assistant OS

OS and supervised is blocking installing portainer as addon so the user cant connecting to the HA container.
One user have using SSH access to the host docker container and its working OK.
HA SSH access to the host

[aog2000a]

In Home Assistant Core 2022.5.4 i see there is vi in the container, out of the box.

[Hedda]

Btw, I wrote this initial troubleshooting guide for the official ZHA integration on how to add custom ZHA quirks locally that was rejected:

home-assistant/home-assistant.io#23884

That initial guide did however not cover how to map/define storage volumes with Docker-Compose f using Home Assistant core in a Docker container but there it should be noted that the existing ZHA integration documentation does mention Docker Compose under troubleshooting:

https://www.home-assistant.io/integrations/zha#cant-connect-to-usb-device-and-using-docker

https://www.home-assistant.io/integrations/zha#docker-compose

Anyway, here is a copy of my guide for beginners:

home-assistant/home-assistant.io#23884

Manually add and use a not yet merged custom ZHA quirk

If you have bought a non-standard Zigbee device that is not yet supported by ZHA but someone have written a ZHA "quirk" module (ZHA Device Handler/Zigbee Converter) that not get been merged into a "ZHA Device Handlers"" library release then you can add that manually as a custom ZHA quirk to your Home Assistant instance, (using something like File Editor or Samba share add-ons in Home Assistant).

1. Get a copy of an existing custom ZHA quirk or code your own quirks. Tip is to search using Zigbee device signature https://github.com/zigpy/zha-device-handlers/issues?q=is%3Aissue+is%3Aopen
2. Create a directory/folder for your custom quirks (for example /config/zha_quirks/)
3. Copy or create a quirk file in this directory (called it for example “devicemodelzyz_devicetypexyz.py”). This file should contain the Python script for the quirk and its specific Zigbee device signature unique to it.
4. Add configuration with the full path to the directory that now containing custom quirk module(s) that will override and take precedence over any built-in quirks matching any device that has the same Zigbee device signature. to Home Assistant's config.yaml

zha:
  custom_quirks_path: /config/zha_quirks/

5. Restart Home Assistant to make the quirk take effect.

[MattWestb]

HA is too large for ditaled instructions and and sk´hall being in the integrations documents so for ZHA is its the Zigpy family and the main place is the Wiki pages.

Make one good "fast guide" in the Wiki and also if you like one more dilated one and we can linking to it then supporting users.

[MattWestb]

Adding new / updating quirks in Zigpy / ZHA GitHub.

Then you have getting one local quirk working OK in your system is best making one PR for adding it in the main ZHA so other user can getting there device working well in there system and if ZHA is doing changes the maintainers is fixing the quirk so its working in the future.
If ZHA is making changes and you is using local quirks you is on your own fixing the problem and it can being braking changes for your system that is coming in the future.
Also dont forgetting deleting the local quirk then its included in HA for not getting problem in the future (local quirk have higher priority then being loaded then ZHA internals).

Making changes in GitHub repos:

Go to the file you like changing and click on the edit symbol and GitHub is making one local copy of the repro in your Git.
First formatting your new / updated code with Black Playground by putting your code in the left window and you is getting nice formatted code in the right one (use copy and pace) and then putting it in the file you like updating.
You can doing more changes also of multiple files if you like.

Then all is done make one the pull request for getting it uploaded to the main repor so it can being merged after reviue of the maintainers. Look on the ESPHome guide for editing ESPHome docks that is good illustrated instruction.

GitHub is making many test of the code syntax and if getting problems read the errors its normally is giving clues what is not OK and also other users and devs can helping getting it OK.

Large thanks for contributing and making our system better and better and getting more functionality in the future !!

[MattWestb]

Debug logging for getting information from the system and devices.

Setting up instruction for ZHA components https://www.home-assistant.io/integrations/zha/#debug-logging.
Normally is the radio libs not needed and is only spamming the log.

One good start is putting in:

logger:
  default: info
  logs:
    homeassistant.core: info
    homeassistant.components.zha: debug
    bellows.zigbee.application: debug
    bellows.ezsp: info
    zigpy: info
    zigpy_deconz.zigbee.application: info
    zigpy_deconz.api: info
    zigpy_xbee.zigbee.application: info
    zigpy_xbee.api: info
    zigpy_zigate: info
    zigpy_znp: info
    zhaquirks: debug
    custom_zha_quirks: debug

If need more debug setting is the devs saying what is need being sett for getting it working OK.

After have finished the debug is best practice putting the standard setting back for not spamming the log more then needed for normal operation.

[martin3000]

With HA core, I had to use

custom_quirks_path: .homeassistant/custom_zha_quirks/