diff --git a/README.md b/README.md index 499ac57b..79a0a3af 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ places Logo +[![Integration Usage][integration-usage-shield]][releases] + [![GitHub Downloads][downloads-shield]][releases] [![GitHub Latest Downloads][downloads-latest-shield]][releases] [![GitHub Release][releases-shield]][releases] @@ -11,56 +13,46 @@ [![Coverage][coverage-shield]][coverage] [![License][license-shield]](LICENSE) [![hacs][hacsbadge]][hacs] -[![Community Forum][community-forum-shield]](community-forum) _Component to integrate with OpenStreetMap Reverse Geocode and create a sensor with numerous address and place attributes from a device_tracker, person, or sensor_ -## Installation -### HACS *(recommended)* -1. Ensure that [HACS](https://hacs.xyz/) is installed -1. [Click Here](https://my.home-assistant.io/redirect/hacs_repository/?owner=custom-components&repository=places) to directly open `places` in HACS **or**
-  a. Navigate to HACS
-  b. Click `+ Explore & Download Repositories`
-  c. Find the `places` integration
-1. Click `Download` -1. Restart Home Assistant -1. See [Configuration](#configuration) below +## Breaking Change with v3: Entity model and migration notes -
-

Manual

 +The main places sensor keeps the Display Options state. It now only exposes location-context attributes. Most values that used to be attributes are child sensors under the same places device. For example: -You probably do not want to do this! Use the HACS method above unless you know what you are doing and have a good reason as to why you are installing manually +* `state_attr('sensor.alice', 'place_name')` becomes `states('sensor.alice_place_name')` +* `state_attr('sensor.alice', 'city')` becomes `states('sensor.alice_city')` +* `state_attr('sensor.alice', 'state')` becomes `states('sensor.alice_state')` +* `state_attr('sensor.alice', 'map_link')` becomes `states('sensor.alice_map_link')` -1. Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`) -1. If you do not have a `custom_components` directory there, you need to create it -1. In the `custom_components` directory create a new folder called `places` -1. Download _all_ the files from the `custom_components/places/` directory in this repository -1. Place the files you downloaded in the new directory you created -1. Restart Home Assistant -1. See [Configuration](#configuration) below +`country` and detailed address/diagnostic sensors are disabled by default. Enable them from the places device page if you use them in automations. -Using your HA configuration directory as a starting point you should now also have this: -```text -custom_components/places/__init__.py -custom_components/places/config_flow.py -custom_components/places/const.py -custom_components/places/manifest.json -custom_components/places/sensor.py -custom_components/places/strings.json -custom_components/places/translations -custom_components/places/translations/en.json -``` -
+When Extended Attributes is enabled, raw payloads move to `sensor._extended_data`: + +* `state_attr('sensor.alice_extended_data', 'osm_dict')` +* `state_attr('sensor.alice_extended_data', 'osm_details_dict')` +* `state_attr('sensor.alice_extended_data', 'wikidata_dict')` +* `state_attr('sensor.alice_extended_data', 'wikidata_id')` + +## Installation via HACS + +Ensure that [HACS](https://hacs.xyz/) is installed + +Open your Home Assistant instance to download the places integration. + +Download the `places` integration + +Restart Home Assistant ## Configuration -**Configuration is done in the Integrations section of Home Assistant.** -1. [Click Here](https://my.home-assistant.io/redirect/config_flow_start/?domain=places) to directly add a `places` sensor **or**
-  a. In Home Assistant, go to Settings -> [Integrations](https://my.home-assistant.io/redirect/integrations/)
-  b. Click `+ Add Integrations` and select `places`
-1. Add your configuration ([see Configuration Options below](#configuration-options)) -1. Click `Submit` -* Repeat as needed to create additional `places` sensors -* Options can be changed for existing `places` sensors in Home Assistant Integrations by selecting `Configure` under the desired `places` sensor. + +Open your Home Assistant instance to create a places entry. + +[See Configuration Options below](#configuration-options) + +Repeat as needed to create additional `places` entries + +Options for existing places entries can be changed by clicking the gear icon next to the desired entry under Settings > Devices & services > `places` integration. ## Configuration Options @@ -85,13 +77,16 @@ To use, simply enter your advanced options into the `display_options` text area. __Tip:__ _Build your advanced display options string in a text editor and copy/paste it into display_options field as it is pretty small._ ### __Brackets [ ]:__ Fields to show if initial field is blank or empty
+ These can be nested. + #### Examples * `name[type]` will show the name, but if name is blank, will show the type instead. If type is also blank, nothing will show for that field * `name[type[category]]` will show the name, but if name is blank, will show the type instead, but if type is blank, will show the category. If category is also blank, nothing will show for that field. ### __Parenthesis ( ):__ Inclusion/Exclusion Logic to filter the field
+ #### To include/exclude based on the main field * __Include:__ Set the first item inside the parenthesis to + to only show the field if it equals one of the states listed @@ -127,11 +122,14 @@ These can be nested. ### Brackets and Parenthesis can also be combined * To recreate `place`: -``` + +```text name_no_dupe, category(-, place), type(-, yes), neighborhood, house_number, street ``` + * To recreate `formatted_place`: -``` + +```text zone_name[driving, name_no_dupe[type(-, unclassified, category(-, highway))[category(-, highway)], house_number, route_number(type(+, motorway, trunk))[street[route_number]], neighborhood(type(house))], city_clean[county], state_abbr] ``` @@ -167,39 +165,11 @@ __Note:__ `place` and `formatted_place` are not valid fields in the advanced dis ------- -
-Entity model and migration notes - -The main Places sensor keeps the Display Options state. It only exposes location-context attributes: - -* `latitude` -* `longitude` -* `gps_accuracy` -* `entity_picture` -* `attribution` - -Most values that used to be attributes are now child sensors under the same Places device. For example: - -* `state_attr('sensor.alice', 'place_name')` becomes `states('sensor.alice_place_name')` -* `state_attr('sensor.alice', 'city')` becomes `states('sensor.alice_city')` -* `state_attr('sensor.alice', 'state')` becomes `states('sensor.alice_state')` -* `state_attr('sensor.alice', 'map_link')` becomes `states('sensor.alice_map_link')` - -The integration no longer creates a `formatted_address` child sensor. - -`country` and detailed address/diagnostic sensors are disabled by default. Enable them from the Places device page if you use them in automations. - -When Extended Attributes is enabled, raw payloads move to `sensor._extended_data`: - -* `state_attr('sensor.alice_extended_data', 'osm_dict')` -* `state_attr('sensor.alice_extended_data', 'osm_details_dict')` -* `state_attr('sensor.alice_extended_data', 'wikidata_dict')` -
-
Sample generic `automations.yaml` snippet to send an iOS notify on any device state change (the only difference is the second one uses a condition to only trigger for a specific user) + ```yaml - alias: ReverseLocateEveryone initial_state: 'on' @@ -242,16 +212,19 @@ When Extended Attributes is enabled, raw payloads move to `sensor._extende url: '{{ trigger.event.data.map_link }}' hide_thumbnail: false ``` +
## Notes + * This component is only useful to those who have device tracking enabled via a mechanism that provides latitude and longitude coordinates (such as the [Home Assistant Mobile App](https://www.home-assistant.io/integrations/mobile_app/), [OwnTracks](https://www.home-assistant.io/integrations/owntracks/), or [iCloud3](https://github.com/gcobb321/icloud3)). * The OpenStreetMap database is very flexible with regards to tag_names in their database schema. If you come across a set of coordinates that do not parse properly, you can enable debug logging (see below) to see the actual JSON that is returned from the query. * The OpenStreetMap API requests that you include your valid e-mail address in each API call if you are making a large numbers of requests. They say that this information will be kept confidential and only used to contact you in the event of a problem, see their Usage Policy for more details. * The map link that gets generated for Google, Apple or OpenStreetMaps has a push pin marking the users location. Note that when opening the Apple link on a non-Apple device, it will open in Google Maps. -* When no `language` value is given, default language will be in the location's local language. When a comma separated list of languages is provided - the component will attempt to fill each address field in desired languages by order. +* When no `language` value is given, default language will be in the location's local language. When a comma-separated list of languages is provided - the component will attempt to fill each address field in desired languages by order. * Translations are partial in OpenStreetMap database. For each field, if a translation is missing in first requested language it will be resolved with a language following in the provided list, defaulting to local language if no matching translations were found for the list. * To enable debug logging for this component, add the following to your `configuration.yaml` file + ```yaml logger:   default: warning @@ -269,13 +242,16 @@ python -m pip install --group dev -e . ``` ## Prior Contributions: + * Previous Authors: [Jim Thompson](https://github.com/tenly2000) & [Ian Richardson](https://github.com/iantrich) * Current Author: [Snuffy2](https://github.com/Snuffy2) ## Contributions are welcome! + If you want to contribute to this please read the [Contribution guidelines](CONTRIBUTING.md) *** +[integration-usage-shield]: https://img.shields.io/badge/dynamic/json?color=41BDF5&logo=home-assistant&label=integration%20usage&suffix=%20installs&cacheSeconds=15600&url=https%3A%2F%2Fanalytics.home-assistant.io%2Fcustom_integrations.json&query=%24.places.total&style=for-the-badge [downloads-shield]: https://img.shields.io/github/downloads/custom-components/places/total?style=for-the-badge&label=total%20downloads [downloads-latest-shield]: https://img.shields.io/github/downloads-pre/custom-components/places/latest/total?style=for-the-badge [releases]: https://github.com/custom-components/places/releases @@ -286,7 +262,5 @@ If you want to contribute to this please read the [Contribution guidelines](CONT [license-shield]: https://img.shields.io/github/license/custom-components/places?color=blue&style=for-the-badge [hacsbadge]: https://img.shields.io/badge/HACS-Default-blue.svg?style=for-the-badge [hacs]: https://hacs.xyz -[community-forum-shield]: https://img.shields.io/badge/community-forum-orange.svg?label=HA%20Community&style=for-the-badge -[community-forum]: https://community.home-assistant.io/t/reverse-geocode-sensor-places-using-openstreetmap-custom-component [coverage]: https://htmlpreview.github.io/?https://github.com/custom-components/places/blob/python-coverage-comment-action-data/htmlcov/index.html [coverage-shield]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fcustom-components%2Fplaces%2Fpython-coverage-comment-action-data%2Fendpoint.json&style=for-the-badge