{"id":50178922,"url":"https://github.com/positionguard/positionguard-homeassistant","last_synced_at":"2026-06-13T02:09:04.110Z","repository":{"id":352531463,"uuid":"1215466870","full_name":"positionguard/positionguard-homeassistant","owner":"positionguard","description":"Privacy-first family location for Home Assistant — area-level presence, no exact coordinates.","archived":false,"fork":false,"pushed_at":"2026-05-25T04:55:41.000Z","size":1460,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T06:47:23.652Z","etag":null,"topics":["custom-component","device-tracker","family-location","hacs","home-assistant","home-assistant-integration","home-automation","location-sharing","positionguard","presence-detection","privacy"],"latest_commit_sha":null,"homepage":"https://positionguardai.com","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/positionguard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-20T00:09:42.000Z","updated_at":"2026-05-25T04:53:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/positionguard/positionguard-homeassistant","commit_stats":null,"previous_names":["positionguard/positionguard-homeassistant"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/positionguard/positionguard-homeassistant","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/positionguard%2Fpositionguard-homeassistant","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/positionguard%2Fpositionguard-homeassistant/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/positionguard%2Fpositionguard-homeassistant/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/positionguard%2Fpositionguard-homeassistant/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/positionguard","download_url":"https://codeload.github.com/positionguard/positionguard-homeassistant/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/positionguard%2Fpositionguard-homeassistant/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34269411,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["custom-component","device-tracker","family-location","hacs","home-assistant","home-assistant-integration","home-automation","location-sharing","positionguard","presence-detection","privacy"],"created_at":"2026-05-25T06:05:07.140Z","updated_at":"2026-06-13T02:09:04.093Z","avatar_url":"https://github.com/positionguard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PositionGuard — Home Assistant Integration\n\nPrivacy-first family location for Home Assistant. PositionGuard exposes\nyour family group's presence as native `device_tracker` and\n`binary_sensor` entities, with area-level granularity — home, school,\ngrandma's house — instead of exact coordinates.\n\nBuilt for Home Assistant users who want reliable family presence\ndetection without handing their family's location data to third-party\nservices.\n\n![PositionGuard family dashboard](docs/images/dashboard-hero.png)\n\n---\n\n## What's different about this\n\n- **Area-level, not coordinate-level.** PositionGuard reports presence\n  as \"in this area\" or \"not in this area\" — never exact GPS coordinates.\n  Your dashboard shows where family members are *grouped*, not where\n  they stand.\n- **One install per person.** Family members install the PositionGuard\n  app on their phone once. They don't need a Home Assistant account, the\n  HA Companion app, or any HA configuration on their device.\n- **Works around iOS Private Wi-Fi Address rotation.** Position is\n  reported by the phone, not detected by the router. Family members'\n  iPhones report reliably regardless of MAC randomization.\n- **Privacy-first by design.** No data sale, no ads, no third-party\n  trackers. Sharing can be paused per-person at any time.\n\n---\n\n## What this integration provides\n\nWhen configured, the integration exposes one device per group with the\nfollowing entities per family member:\n\n- **`device_tracker.\u003cmember\u003e_in_\u003cgroup\u003e`** — whole-group presence.\n  States: `home` (member is in any area belonging to this group),\n  `not_home` (member is outside all group areas), `unknown` (sharing\n  paused).\n- **`binary_sensor.\u003cmember\u003e_at_\u003carea\u003e`** — per-area presence, one per\n  (member, area) combination. State `on` (in this specific area), `off`\n  (not in this specific area), `unavailable` (sharing paused).\n  *Disabled by default* — enable only the ones you want to use.\n\nEach entity exposes useful attributes including `area` (the specific\narea within the group, if any) and `sharing_status` (`active` or\n`disabled`).\n\nThe integration creates one device per group with all member entities,\nvisible under Settings → Devices \u0026 Services → PositionGuard:\n\n![PositionGuard device page in Home Assistant](docs/images/device-page.png)\n\n---\n\n## Compatibility\n\n- **Home Assistant**: 2026.3 or later (required for proper icon\n  rendering)\n- **PositionGuard app**: latest version on iOS App Store\n  ([download](https://apps.apple.com/app/id6758687496)). Android\n  support is in beta — if you want to participate, mention it in\n  the\n  [Discussions](https://github.com/positionguard/positionguard-homeassistant/discussions)\n  tab.\n- **HACS**: recommended for installation, though manual install is\n  supported\n\n---\n\n## Installation\n\nYou'll go through three places: the PositionGuard app (to set up your\naccount and family), the developer portal (to mint an API key), and HACS\n(to install this integration).\n\n### 1. Install the PositionGuard app and set up your family\n\n1. Install [PositionGuard](https://apps.apple.com/app/id6758687496)\n   from the App Store.\n2. Sign in with your phone number (SMS verification).\n3. Create a family group. Default name is \"Family\"; rename if you like.\n4. Add areas to the group: at minimum a \"Home\" area centered on your\n   house. Add others as needed (work, school, grandma's house, etc.).\n   The integration will expose every member-area combination as a\n   binary sensor.\n5. Invite family members to the group. They install the app and accept\n   the invite. Sharing can be paused per-person at any time.\n6. Confirm your own and family members' positions update on the app's\n   map. **Wait at least 30 seconds after any change** for presence\n   state to propagate before checking in HA.\n\n### 2. Get your API key from the developer portal\n\n1. Visit [dev.positionguardai.com](https://dev.positionguardai.com).\n2. Sign in with the same phone number you used for the app.\n3. Click **Create API key**, give it a descriptive name (e.g.,\n   \"Home Assistant\").\n4. Copy the key — it's shown once only. Store it somewhere safe (a\n   password manager works well).\n\n### 3. Install the integration via HACS\n\n1. In Home Assistant, open HACS.\n2. Click the three-dot menu (top right) → **Custom repositories**.\n3. Add this repository:\n   - **Repository**: `https://github.com/positionguard/positionguard-homeassistant`\n   - **Type**: `Integration`\n4. Click **Add**.\n5. Find PositionGuard in HACS and click **Download**.\n6. Restart Home Assistant when prompted.\n\n### 4. Configure the integration\n\n1. Go to **Settings → Devices \u0026 Services → Add Integration**.\n2. Search for \"PositionGuard\" and select it.\n3. Paste your API key.\n\n![PositionGuard config flow API key entry](docs/images/config-flow.png)\n\n4. Select which group(s) you want to expose to Home Assistant. You can\n   select multiple groups (Family, Work, Activity groups, etc.). Each\n   becomes a separate device with its own member entities.\n5. Done. Your family members will appear as `device_tracker` entities\n   within ~30 seconds.\n   \n\n\n### Manual installation (without HACS)\n\nIf you don't use HACS:\n\n1. Clone or download this repo.\n2. Copy `custom_components/positionguard/` into your Home Assistant\n   `/config/custom_components/` directory.\n3. Restart Home Assistant.\n4. Configure as in step 4 above.\n\n### Updates\n\nIn-place version updates are supported. When a new version is released,\nHACS will offer the update; accept and restart HA. Entity IDs are\npreserved across updates — you won't see suffixes like `_2` appended\nto your existing entities.\n\n---\n\n## Privacy\n\nPositionGuard is built privacy-first. The integration shows presence at\n**area level only**, never exact coordinates. The map in Home Assistant\nwill display the area boundary, not a precise location point.\n\nWhat's shared:\n- Whether each member is at any area in the group (`home` / `not_home`)\n- Which specific area, if any, they're in\n- Whether sharing is active or paused\n\nWhat's never shared:\n- Exact GPS coordinates\n- Movement history outside of area transitions\n- Any data about non-family-members nearby\n\nWhen a family member pauses sharing in the app, the integration\nrespects this immediately. Their entities become `unavailable` rather\nthan reporting stale or fabricated data — automations correctly do not\nfire on paused users.\n\n---\n\n## Automation examples\n\nThe examples below use a sample LA family group with parents Fred and\nSarah, and kids Peter, John, and Sally. Areas defined: Home, School,\nGrandma's House, Beach House.\n\n### Welcome someone home\n\nThe simplest case — trigger on a member arriving home:\n\n```yaml\nautomation:\n  - alias: \"Welcome John home\"\n    trigger:\n      - platform: state\n        entity_id: device_tracker.john_in_family\n        to: \"home\"\n    action:\n      - service: light.turn_on\n        target:\n          entity_id: light.living_room\n```\n\nThis fires when John transitions from outside any group area to inside\nany group area. If you want to be specific about *which* area he\narrived at, see the next example.\n\n### Triggering on arrival at a specific area\n\nThe `device_tracker` entity exposes an `area` attribute identifying\nwhich specific area within the group the member is in. Use a template\ncondition to match a particular area:\n\n```yaml\nautomation:\n  - alias: \"Music when family arrives at Beach House\"\n    trigger:\n      - platform: state\n        entity_id: device_tracker.fred_in_family\n        to: \"home\"\n    condition:\n      - condition: template\n        value_template: \u003e\n          {{ state_attr('device_tracker.fred_in_family', 'area')\n             == 'Beach House' }}\n    action:\n      - service: media_player.play_media\n        target:\n          entity_id: media_player.beach_house_speaker\n        data:\n          media_content_id: \"spotify:playlist:...\"\n          media_content_type: \"playlist\"\n```\n\nThis pattern lets you keep one Family group with multiple areas\n(Home, School, Beach House, Grandma's House) and use templates to\ndistinguish *which* area triggered the automation. You don't need to\ncreate a separate group per area.\n\n### Triggering when a child arrives at school\n\nA reliable \"kid arrived at school safely\" notification is one of the\nkiller use cases for family presence. Two approaches — pick whichever\nfits your style.\n\n**Using the area attribute (no entity setup needed):**\n\n```yaml\nautomation:\n  - alias: \"Notify when Sally arrives at School\"\n    trigger:\n      - platform: state\n        entity_id: device_tracker.sally_in_family\n        to: \"home\"\n    condition:\n      - condition: template\n        value_template: \u003e\n          {{ state_attr('device_tracker.sally_in_family', 'area')\n             == 'School' }}\n    action:\n      - service: notify.parents\n        data:\n          message: \"Sally arrived at school\"\n```\n\n**Using the per-area binary sensor (cleaner, requires enabling the\nsensor first):**\n\n```yaml\nautomation:\n  - alias: \"Notify when Sally arrives at School\"\n    trigger:\n      - platform: state\n        entity_id: binary_sensor.sally_at_school\n        to: \"on\"\n    action:\n      - service: notify.parents\n        data:\n          message: \"Sally arrived at school\"\n```\n\nThe binary sensor approach is more readable in YAML but requires\nenabling the sensor first (see next section).\n\n### Per-area binary sensors (advanced)\n\nFor each (member, area) combination, a `binary_sensor` exists but is\n**disabled by default** to avoid cluttering Home Assistant with dozens\nof entities most users won't reference.\n\nTo enable a binary sensor:\n\n1. **Settings → Devices \u0026 Services → PositionGuard**\n2. Click your group device\n3. Click the binary sensor entity (e.g.,\n   `binary_sensor.sally_at_school`)\n4. Toggle \"Enabled\" on\n5. Restart HA or reload the integration\n\nOnce enabled, automations using these sensors are simpler than the\ntemplate-based approach — no `state_attr` calls, just direct state\nchecks.\n\n### Multiple-area scenarios\n\nThe integration shines when you have multiple meaningful areas in a\nsingle group. Define all your common destinations as areas in the\nPositionGuard app, then write automations using the `area` attribute:\n\n```yaml\nautomation:\n  - alias: \"Announce who arrived where\"\n    trigger:\n      - platform: state\n        entity_id:\n          - device_tracker.fred_in_family\n          - device_tracker.sarah_in_family\n          - device_tracker.john_in_family\n          - device_tracker.peter_in_family\n          - device_tracker.sally_in_family\n        to: \"home\"\n    action:\n      - service: notify.family\n        data:\n          message: \u003e\n            {{ trigger.to_state.attributes.friendly_name }}\n            arrived at\n            {{ trigger.to_state.attributes.area }}\n```\n\nThis single automation announces every family-member arrival at every\ndefined area, dynamically including the area name in the notification.\n\n### Respecting sharing status\n\nWhen a family member pauses sharing in the PositionGuard app, their\nentities become `unavailable` rather than `not_home`. Automations that\ntrigger on `home → not_home` transitions will correctly **not fire**\nwhen someone simply pauses sharing — only on actual departures.\n\nIf you want to track sharing status explicitly, each entity exposes a\n`sharing_status` attribute (`active` or `disabled`):\n\n```yaml\nautomation:\n  - alias: \"Note when sharing is paused\"\n    trigger:\n      - platform: state\n        entity_id: device_tracker.peter_in_family\n    condition:\n      - condition: template\n        value_template: \u003e\n          {{ state_attr('device_tracker.peter_in_family',\n                        'sharing_status') == 'disabled' }}\n    action:\n      - service: notify.parents\n        data:\n          message: \"Peter has paused location sharing\"\n```\n\n---\n\n## Companion widgets\n\n[**AlertTicker Card**](https://github.com/djdevil/AlertTicker-Card) by\ndjdevil pairs nicely with PositionGuard for moment-based presence\nnotifications on a dashboard. Use `auto_dismiss_after` for transient\narrival/departure alerts that don't clutter the dashboard:\n\n```yaml\ntype: custom:alertticker-card\nalerts:\n  - entity: binary_sensor.sally_at_school\n    state: \"on\"\n    message: \"🎒 Sally arrived at School\"\n    theme: success\n    auto_dismiss_after: 60\n  - entity: device_tracker.fred_in_family\n    on_change: true\n    message: \"👤 {{ state_attr('device_tracker.fred_in_family',\n                                'friendly_name') }}: {{ state }}\"\n    auto_dismiss_after: 60\n```\n\nThe first variant fires only on arrivals at a specific area. The second\nfires on any state transition (arrival or departure) and includes the\nstate in the message.\n\nIn practice, this looks like:\n\n![AlertTicker rendering a PositionGuard presence event](docs/images/alertticker-example.png)\n\n\n---\n\n## Limitations\n\nThis integration is **read-only**. From Home Assistant, you cannot:\n\n- Create, modify, or delete groups, areas, or members\n- Change sharing permissions\n- Send messages, invitations, or notifications\n\nThese actions remain in the PositionGuard app where group members can\nmanage their own privacy directly.\n\nThe integration polls the PositionGuard API every 30 seconds. Position\nchanges typically reflect in Home Assistant within 30–60 seconds of\nthe actual change.\n\n---\n\n## Questions, feedback, bug reports\n\nUse the\n[Discussions](https://github.com/positionguard/positionguard-homeassistant/discussions)\ntab for questions or feedback, and\n[Issues](https://github.com/positionguard/positionguard-homeassistant/issues)\nfor bug reports.\n\nFor information about PositionGuard the app or the developer portal,\nvisit [positionguardai.com](https://positionguardai.com).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpositionguard%2Fpositionguard-homeassistant","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpositionguard%2Fpositionguard-homeassistant","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpositionguard%2Fpositionguard-homeassistant/lists"}