Proximity documentation lacks information

The documenation of the proximity component show several problems: https://www.home-assistant.io/components/proximity/

Values “state” and “dist_to_zone” have the same explanation. No description of the following parameters: ignored_zones, tolerance, unit_of_measurement…

Can somebody with knowledge of this component update the doc?

ignored_zones seems self explanatory.

unit_of_measurement are described in line 39 of the component source.

tolerance is fairly self explanatory from the source - a change in position of less than tolerance is ignored from what I can see.

state is the same as dist_to_zone.

Now you can edit the page yourself :slight_smile:

If it were “self explanatory” I wouldn’t be asking the question. I might guess about the function but still might not be 100% sure. And I’m not a coder so digging into the code really isn’t an option. it’s one of those things open-source really is bad at: you’ve got the code so why bother with documentation?

ignored_zones: ok, you ignore a zone while defining another zone. still not sure what it’s purpose is so… doesn’t explain itself to me.
units of measurement: found the code so I will update the doc
tolerance: so this compares to the radius of a standard zone

I’ll go edit the page with the info I’ve got :wink:

1 Like

Had a look at the documentation. When I checked it on github it appears it’s already there, it’s just not shown. Not an expert in markdown so no clue why it’s not parsed correctly.

I agree, but this component’s code is pretty short and simple.

Neither do I, I’ll take a look, but not this morning - work calls.

Without a good documentation it is hard to figure out whether there is a error, bug or this is by design.

I do not see dist_to_zone attribute. There are: unit_of_measurement, friendly_name, nearest and dir_of_travel.

dir_of_travel is confusing. I have a large zone, and when I’m in the zone, I am expecting “arrived” value. But it could be unknown or towards. The Map shows the correct location.

How ignored_zones affects dir_of_travel “arrived”, when zones intersect? Can I use ignored_zones to subtract one area from another? I want to have an ability to detect that I am in a zone, but not in overlapping zones. Can ignored_zones help?
ignored_zones: “proximity is not calculated for a device” - what does that mean? I see all the updated proximity attributes, when I am in the ignored zone. If proximity is not calculated, then what are the defaults?

If GPS Logger sends updates only when location is changed, or the update interval is long, then after which amount of time dir_of_travel becomes “stationary” without new updates? I saw “stationary” when I was at work with such GPS Logger settings.

Stationary seems quite clear from the source. If the device hasn’t moved more than tolerance then it is stationary. See around line 240.

Sorry to bump this topic again, but it’s still not clear to me - what does ignored_zones actually do?

I understand I can specify a Zone (default is home) to measure proximity to, and a number of devices to check the proximity of, but still don’t get ignored_zones.

So, I found a comment in an example for proximity that clarified what ignored_zones does.
When the person/device being monitored is in one of the ignored zones, then proximity won’t be calculated for that device - e.g. if I were measuring proximity to home but I was at work at work was defined as an ignored zone, then while I’m in that zone it won’t calculate my proximity to home.
Wish the documentation was a bit clearer about that - it does kind of say that, but it’s not very clear.

So I don’t get it. Where are the attributes have to be set?
When I try to set dir_of_travel and dist_to_zone it gives me an invalid config error. Are this parameters exclusively for automations? Why is the home zone then working and in dev tools info displayed with set parameters, but the work zone not?
How can I use all those values?

A full example in the documentation would be extremely helpful.