Proximity documentation lacks information


#1

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?


#2

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:


#3

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:


#4

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.


#5

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.


#6

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.


#7

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