Add short intro and to dictionary to zha.markdown

[Hedda]

Proposed change

Added a short ZHA introduction with Zigbee diction and ZHA limitations as a summary to zha.markdown meant for new end users.

I think this will help explain the most essential questions that many potential ZHA users (and also users new to Zigbee) commonly have and ask before they buy an adapter and install the ZHA integration or first asked directly after they have installed ZHA.

The purpose of this short introduction is to help new users quickly get up to speed on the hardware requirements for ZHA as well as mention the minimum essential Zigbee terminology that is really needed to get easily up and running with the ZHA integration.

Type of change

• Spelling, grammar or other readability improvements (current branch).
• Adjusted missing or incorrect information in the current documentation (current branch).
• Added documentation for a new integration I'm adding to Home Assistant (next branch).
  • I've opened up a PR to add logo's and icons in Brands repository.
• Added documentation for a new feature I'm adding to Home Assistant (next branch).
• Removed stale or deprecated documentation.

Additional information

• Link to parent pull request in the codebase:
• Link to parent pull request in the Brands repository:
• This PR fixes or closes issue: fixes #

Checklist

• This PR uses the correct branch, based on one of the following:
  • I made a change to the existing documentation and used the current branch.
  • I made a change that is related to an upcoming version of Home Assistant and used the next branch.
• The documentation follows the Home Assistant documentation standards.

[frenck]

Some initial comments.

Don't get me wrong @Hedda, but you already have PRs open for this page, with similar readability comments. We need to target end-users.

I would very much appreciate if you'd finish up those comments first before opening new PRs.

Thanks 👍

../Frenck

[Hedda]

Some initial comments.

Don't get me wrong @Hedda, but you already have PRs open for this page, with similar readability comments. We need to target end-users.

I would very much appreciate if you'd finish up those comments first before opening new PRs.

@frenck If you are referring to #18864 then I already rewrote that PR based on feedback and submitted update (see -> 970295a).

#18864 was initially submitted on 9 Aug 2021 and took 6-month before first review so think justity new PR for a separate section.

[frenck]

If you are referring to #18864 then I already rewrote that all based on feedback and submitted update

Yes I meant that one.

[Hedda]

@frenck by the way, watched this video https://www.youtube.com/watch?v=MfJ5OyNwuHc&ab_channel=FranckNijhof by yourself a year back or so and remember thinking that even you too had a hard time getting started with ZHA for the very first time.

Same reason why I like to help improve docs to assist both beginners as well as more advanced users coming with experiences from other Zigbee implementations or alternative protocols new to ZHA get a smooth and seamless start with a stable network.

Personally, I had a lot of previous experience with Z-Wave and my first impression was that Zigbee is an unstable mess with horrible interoperability, but I think that my first impression would have been way different if the ZHA docs contained some Zigbee basics so new would not want to go elseware to learn essentials on how Zigbee works, essentials which every Zigbee user should really know to not have a unfairly bad experience getting started.

[frenck]

by yourself a year back or so and remember thinking that even you too had a hard time getting started with ZHA for the very first time.

Its not a good reference, things changed a lot. Those were UI issues which have been actively addressed and resolved. It also has 0 to do with what you are writing here, nor does it justify anything.

Same reason why I like to help improve docs to assist both beginners

Lets make stuff less technical and readable for that reason instead of discussing it.

Thanks 👍

../Frenck

[Hedda]

OK. Please see my rewrite -> 3adb003

Introduction

ZHA integration uses one Zigbee Coordinator adapter to set up and control a Zigbee network, (please see the section below for compatible hardware). Once installed ZHA you will be able to directly join/pair Zigbee Router Device and Zigbee End Device products to that Zigbee network, regardless of the manufacturer and brand of that product.

Supported devices are Zigbee Router Devices, which are normally mains-powered that act repeaters within the Zigbee network mesh to extend its range and coherence. And Zigbee End Devices, which will not act as repeaters and are usually but not always battery-operated sensors. ZHA does not yet support "Zigbee Green Power" devices, (such as for example "Friends of Hue" battery-less switches). Any devices that are or have previously been connected to another Zigbee implementation will need to first be reset to factory default before they can be paired/joined to ZHA.

Before installing the integration you will need to buy and connect a Zigbee Coordinator adapter to the computer running the Home Assistant installation. The general recommendation is to buy a newer model of Zigbee Coordinator adapter hardware and to flash the latest firmware to it, the reason for that is that it will usually offer better interoperability with all functions of most Zigbee devices on the market. Note that ZHA only supports connecting one Zigbee Coordinator adapter with a single Zigbee network.

[github-actions]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
Thank you for your contributions.

[Hedda]

Updated end user diction introduction while waiting for a review of the rewrite.

[Hedda]

Not stale (beating the github-actions stale message to the punch).

[github-actions]

There hasn't been any activity on this pull request recently. This pull request has been automatically marked as stale because of that and will be closed if no further activity occurs within 7 days.
Thank you for your contributions.

[Hedda]

Not stale, the rewritten text has not been reviewed.

[Hedda]

Closing in favour of #24494

[frenck]

I'm not sure why you didn't update this PR instead.