search

rmoesbergen / openwrt-ha-device-tracker

OpenWRT device tracker for Home Assistant that actually works
107 stars 18 forks source link

Documentation Improvements (Differentiation + Example Automations?), 802.11r Roaming #31

Closed bai-yi-bai closed 1 year ago

bai-yi-bai commented 1 year ago

Hi, this is an excellent project!

It took me about two hours to get this software up-and-running, and another hour to write this, so I wanted to offer some improvements to the documentation. I use a Docker Container version of Home Assistant and in general I struggle a lot with configuring Home Assistant, so I hope these suggested improvements are well received. If you'd like me to open a PR, I could also do that.

Without further adieu, here are my improvements.

  1. Make it clear that this project has no association with either of the "built-in" OpenWRT HA integrations: "This project replaces the built-in OpenWRT (luci) and OpenWRT (ubus) integrations." Initially, when I couldn't get this working, I started searching the internet and thought maybe I needed to set up these integrations. Note: I'm not sure if "replaces" is the correct word.

  2. Add an instruction to enable the "device_tracker:" add-on to Home Assistance's configuration.yaml. This instruction is missing... and not to get on a soapbox, but HA's half-webGUI and half-yaml configuration pattern is a mess. It'd be so much better if there were toggle buttons in the webGUI, see my introduction where I mention struggling with HA configuration. Here is where I added it, but I'm not sure this is correct for all installation types:

    # Loads default set of integrations. Do not remove.
default_config:
device_tracker:

  3. Re-title the headings to make it clearer where the user must perform actions; either in OpenWRT or in Home Assistant.

    • "Installation" > "OpenWRT Device Installation"
    • "Configuration" > "OpenWRT Device Configuration"
    • "Home Assistant" > "Modifying Home Assistant Configuration"
    • "Logging" > "Troubleshooting"

  4. Modify the "Modifying Home Assistant Configuration" content: I misunderstood that I had to manually create an entry in known_devices.yaml since I hadn't added the "device_tracker:" line. This led to a ghost device which was showing away, when in reality my problem was that the OpenWRT <> HA connection had not been established. It was only after I fixed my connection issues and saw two entries that I understood this. Maybe explicitly state, "Do not manually add devices to this file, only modify the entries automatically added by the presence-detect script running on the OpenWRT device."

  5. Consider adding a "Verifying Connectivity" section. It would have helped me to have a series of steps which has the user verify that the connection between OpenWRT and HA has been established. This would mean needing to change the debug default value from false to true. The majority of this section would be reading the OpenWRT log files. Here are something things I would suggest including to help the user:

    • A screenshot showing the entity card of the device added by OpenWRT to HA's with activity (blue, grey, and green states).
    • An example of a successful message being sent to Home Assistant.
Sun May 28 18:58:46 2023 daemon.debug presence-detector[4949]: Posting to HA: {'mac': 'theMAC', 'location_name': 'home', 'source_type': 'router', 'host_name': 'host_name', 'dev_id': 'dev_id'}
Sun May 28 18:58:46 2023 daemon.debug presence-detector[4949]: API Response: b'[]'

  1. Add how to troubleshoot error messages to "Troubleshooting". This, along with the heading changes will help the user conceptually understand where to begin troubleshooting "from the bottom up" to determine where things are going wrong.

    • First, I'm not sure where to put it, but I think a table mapping the home assistant variables to the presence-detector.settings.json parameters would help the user understand how data is transferred from OpenWRT to HA. This table might fit better in a "Terminology Mapping" section. For example: "Name" = "host_name" with spaces "Entity ID" = "device_tracker.host_name" with underscores I noticed in another ticket, "zone" != "location".
    • Next, provide a basic set of steps for troubleshooting. If you don't see successful logread message in the "Verifying Connectivity" section, begin troubleshooting:
      • Ensure that the device is in the OpenWRT webGUI connected devices list.
      • Double check that the MAC address in webGUI matches the .json file.
    • Here are some examples of errors I received and how I fixed them:
      • Sun May 28 18:58:17 2023 daemon.debug presence-detector[4645] <urlopen error unknown url type: 192.168.x.x> In this case, I neglected to include the "http://" in the "hass_url" attribute of the presence-detector.settings.json file.
      • Sun May 28 19:03:24 2023 daemon.debug presence-detector[4949]: <urlopen error [Errno 111] Connection refused> In this case, I hadn't added the " device_tracker:" line to the configuration.yaml file, so Home Assistant wasn't getting the state updates.

  2. Add a section on "Home Assistant - Create an Example Automation" Maybe this is asking too much, but maybe there's a simple automation which could be set up to test. For example (These should be numbered 1-13, but I'm using that for my main points).

    1. Navigate to "Settings" > "Automations & Scenes" and click "Create Automation"
    2. Choose "Create new automation".
    3. Click "ADD TRIGGER".
    4. Choose "State"
    5. From "Entity" select the Wi-Fi tracked device, it should be prefixed with 'device_tracker.home_name'
    6. From "From" choose the settings.json "away" - note, I don't think this is correct.
    7. From "To" choose the settings.json "location" - note, I don't think this is correct.
    8. From the "Actions"... I'm not sure what example option could be added that is universal 'turn on'... maybe something like this: https://community.home-assistant.io/t/traffic-light-card/465865/8
    9. Click "Save", name it " Arrives Home".
    10. Duplicate the automation
    11. Swap the "From" and "To" options.
    12. Change "Actions" to 'turn off'.
    13. Click "Save", name it " Leaves Home". Then test the automation by turning the device's Wi-Fi radio on/off or clicking "disconnect" in the OpenWRT webGUI.

  3. Add a section "[Advanced] Multiple OpenWRT Devices with 802.11r Roaming Best Practices" This topic is a bit more involved. I have multiple OpenWRT devices with 802.11r fast roaming involved.This was what attracted me to this application in the first place. I live in modestly-sized apartment with thick walls which attenuates 5 GHz wireless signals very quickly, so I have four routers set up as access points. If I reduce the output power of each router, I can trigger handoffs quite consistently. My intention is to carry my Wi-Fi device from room to room and have my smart home devices turn on/off automatically; for example right now I'm using Snapcast for whole-home audio, I would like speakers to turn on and off as I move from room to room. I suppose in the future I'll set up some microwave or IR presence detection sensors, too. It might be better to put this in an entirely separate file. This would be some excellent content for a tech-focused YouTuber, or someone writing a blog. "Taking 802.11r Roaming to the Next Level". I'll try to document my own experiments, but this is enough for today.

Thank you, again!

rmoesbergen commented 1 year ago

Hi @bai-yi-bai , Thanks for using this and taking the time to enhance the documentation. I've done my best to incorporate all your changes, see commit 468cc84 Regarding your 'fast roaming' section: it sounds really cool, but I don't have experience with this myself so wouldn't be comfortable adding to the docs (I won't be able to answer questions about it, etc.). I totally agree this would be great for a blog or youtube video and I'd be happy to link to it from here if you have some more experience with it.

Let me know if the docs are now more to your liking, and thanks again for your efforts.

bai-yi-bai commented 1 year ago

I'm honored! You're welcome. You've done a fine job of interpreting my suggestions. I really like the distinction you make about the difference you make about "push" verses "poll" between the existing integrations. This is brilliant and truly summarizes how wonderful your idea, and this program is.

I experimented a bit with fast-roaming to detect when a device is in a particular room and it might be unworkable. The trouble is tuning the output power levels between multiple access points is really difficult. Clients tend to want to stay connected to a station, and unless I set up an access point in every room and hallway, with very low output power, clients won't immediately disconnect.

So, it might simply help to write to "repeat these steps" on all OpenWrt devices.

Somewhat off-topic, but these sensors might be what I'm looking for to get super accurate presence detection: https://shop.everythingsmart.io/en-us/products/everything-presence-one-kit https://www.youtube.com/watch?v=JISNDJQNSXo