Colota - Android GPS Location tracker
feat: add Home Assistant API template and update integration docs
Max Dietrich93050e2a8632
diff --git a/apps/docs/docs/integrations/home-assistant.md b/apps/docs/docs/integrations/home-assistant.mdindex 5cf718da..280169b3 100644--- a/apps/docs/docs/integrations/home-assistant.md+++ b/apps/docs/docs/integrations/home-assistant.md@@ -6,55 +6,79 @@ sidebar_position: 3[Home Assistant](https://www.home-assistant.io/) is an open-source home automation platform.-Colota integrates with Home Assistant via the built-in [OwnTracks integration](https://www.home-assistant.io/integrations/owntracks/), which accepts location updates over HTTP.+Colota has a dedicated Home Assistant integration that receives location updates via webhook and creates `device_tracker` entities. The integration source code is available on [GitHub](https://github.com/dietrichmax/colota-home-assistant).## Setup-1. **Add the OwnTracks integration** in Home Assistant:- - Go to **Settings > Devices & Services > Add Integration**- - Search for **OwnTracks** and add it- - Note the webhook URL shown after setup (e.g. `https://your-ha-instance/api/webhook/abc123`)-2. **Configure Colota**:- - Go to **Settings > API Settings**- - Select the **OwnTracks** template- - Set the endpoint to your Home Assistant webhook URL:- ```- https://your-ha-instance/api/webhook/abc123- ```- - No authentication is needed - the webhook ID acts as the secret- - Add the following **custom headers** - these are required for Home Assistant to create the `device_tracker` entity:+### 1. Install the Colota integration- | Header | Value | Description |- | ----------- | ------------ | ---------------------------------------------- |- | `X-Limit-U` | e.g. `john` | Your username - used as part of the entity ID |- | `X-Limit-D` | e.g. `phone` | Your device ID - used as part of the entity ID |+**Via HACS (recommended):**- Without these headers, Home Assistant will accept the webhook but will not create a device tracker entity. The entity will appear as `device_tracker.<username>_<device>`.+1. Open HACS in Home Assistant+2. Go to **Integrations**+3. Click the three dots menu and select **Custom repositories**+4. Add `https://github.com/dietrichmax/colota-home-assistant` as an **Integration**+5. Search for **Colota** and install it+6. Restart Home Assistant-Your device will appear as a `device_tracker` entity in Home Assistant that you can use for automations, zones, and the map.+**Manual:**-## Payload Format+1. Copy the `custom_components/colota` folder to your Home Assistant `config/custom_components/` directory+2. Restart Home Assistant-The OwnTracks template auto-configures the following payload:+### 2. Add the integration++1. Go to **Settings > Devices & Services > Add Integration**+2. Search for **Colota** and add it+3. Copy the webhook URL shown after setup++### 3. Configure the Colota app++1. Go to **Settings > API Settings**+2. Paste the webhook URL as the endpoint+3. No authentication is needed - the webhook URL acts as the secret++The integration works with the default/custom API template out of the box. For the best experience, select the **Home Assistant** template which adds a device identifier (`tid`) and enables the connection status check.++Your device will appear as a `device_tracker` entity in Home Assistant that you can use for automations, zones and the map.++## Payload++The Home Assistant template sends the following payload:```json{- "_type": "location",- "tid": "AA",- "lat": 51.495065,- "lon": -0.043945,- "acc": 12,- "alt": 519,- "vel": 0,+ "lat": 51.5074,+ "lon": -0.1278,+ "acc": 15,+ "alt": 20,+ "vel": 1.5,"batt": 85,"bs": 2,- "tst": 1704067200,- "cog": 180.5+ "bear": 180,+ "tid": "colota",+ "tst": 1704067200}```+The `tid` field is used as the device identifier in Home Assistant. You can customize it in the custom fields settings to distinguish multiple devices.+## Notes-- You can customize the tracker ID (`tid`) in the custom fields settings to distinguish multiple devices-- If you use Nabu Casa, use the `cloudhook_url` or `remote_ui_url` provided during setup for external access-- Home Assistant does not require a Bearer token or Basic Auth for webhook endpoints+- If you use Nabu Casa, the integration will automatically generate a cloud webhook URL for external access+- The integration supports multiple devices - each unique `tid` value creates a separate `device_tracker` entity++## Alternative: OwnTracks integration++If you prefer not to install a custom integration, you can use Home Assistant's built-in [OwnTracks integration](https://www.home-assistant.io/integrations/owntracks/) instead:++1. Add the **OwnTracks** integration in Home Assistant and note the webhook URL+2. In the Colota app, select the **OwnTracks** template and set the endpoint to the webhook URL+3. Add the following custom headers:++ | Header | Value | Description |+ | ----------- | ------------ | ---------------------------------------------- |+ | `X-Limit-U` | e.g. `john` | Your username - used as part of the entity ID |+ | `X-Limit-D` | e.g. `phone` | Your device ID - used as part of the entity ID |++ Without these headers, Home Assistant will not create a device tracker entity.diff --git a/apps/mobile/src/components/features/dashboard/ConnectionStatus.tsx b/apps/mobile/src/components/features/dashboard/ConnectionStatus.tsxindex 5f69efa3..cbc16a75 100644--- a/apps/mobile/src/components/features/dashboard/ConnectionStatus.tsx+++ b/apps/mobile/src/components/features/dashboard/ConnectionStatus.tsx@@ -66,7 +66,8 @@ export function ConnectionStatus({ endpoint, navigation }: ConnectionStatusPropsif (response.ok || (response.status !== 404 && response.status !== 405)) break}- setServerStatus(response.ok ? "connected" : "error")+ const reachable = response.ok || response.status === 405+ setServerStatus(reachable ? "connected" : "error")hasChecked.current = true} catch {setServerStatus("error")diff --git a/apps/mobile/src/types/__tests__/defaults.test.ts b/apps/mobile/src/types/__tests__/defaults.test.tsindex 990f5cc5..d48c1b88 100644--- a/apps/mobile/src/types/__tests__/defaults.test.ts+++ b/apps/mobile/src/types/__tests__/defaults.test.ts@@ -130,7 +130,15 @@ describe("TRACKING_PRESETS", () => {})describe("API_TEMPLATES", () => {- const templateNames = ["dawarich", "owntracks", "phonetrack", "reitti", "traccar"] as const+ const templateNames = [+ "dawarich",+ "geopulse",+ "homeassistant",+ "owntracks",+ "phonetrack",+ "reitti",+ "traccar"+ ] as constit.each(templateNames)("%s has valid fieldMap with required keys", (name) => {const template = API_TEMPLATES[name]@@ -139,7 +147,16 @@ describe("API_TEMPLATES", () => {expect(template.fieldMap).toHaveProperty("acc")})- it.each(templateNames)("%s has non-empty customFields", (name) => {+ const templatesWithCustomFields = [+ "dawarich",+ "homeassistant",+ "owntracks",+ "phonetrack",+ "reitti",+ "traccar"+ ] as const++ it.each(templatesWithCustomFields)("%s has non-empty customFields", (name) => {expect(API_TEMPLATES[name].customFields.length).toBeGreaterThan(0)})@@ -175,6 +192,12 @@ describe("API_TEMPLATES", () => {expect(API_TEMPLATES.traccar.httpMethod).toBe("GET")})+ it("homeassistant uses default field names and includes tid", () => {+ expect(API_TEMPLATES.homeassistant.fieldMap.lat).toBe("lat")+ expect(API_TEMPLATES.homeassistant.fieldMap.lon).toBe("lon")+ expect(API_TEMPLATES.homeassistant.customFields).toEqual([{ key: "tid", value: "colota" }])+ })+it("traccar maps fields for OsmAnd protocol", () => {expect(API_TEMPLATES.traccar.fieldMap.acc).toBe("accuracy")expect(API_TEMPLATES.traccar.fieldMap.alt).toBe("altitude")diff --git a/apps/mobile/src/types/global.ts b/apps/mobile/src/types/global.tsindex bb10eea2..0d266e2b 100644--- a/apps/mobile/src/types/global.ts+++ b/apps/mobile/src/types/global.ts@@ -99,7 +99,15 @@ export interface CustomField {export type HttpMethod = "POST" | "GET"-export type ApiTemplateName = "custom" | "dawarich" | "geopulse" | "owntracks" | "phonetrack" | "reitti" | "traccar"+export type ApiTemplateName =+ | "custom"+ | "dawarich"+ | "geopulse"+ | "homeassistant"+ | "owntracks"+ | "phonetrack"+ | "reitti"+ | "traccar"export interface ApiTemplate {name: ApiTemplateName@@ -128,6 +136,23 @@ export const API_TEMPLATES: Record<Exclude<ApiTemplateName, "custom">, ApiTempla},customFields: []},+ homeassistant: {+ name: "homeassistant",+ label: "Home Assistant",+ description: "Colota webhook for Home Assistant",+ fieldMap: {+ lat: "lat",+ lon: "lon",+ acc: "acc",+ alt: "alt",+ vel: "vel",+ batt: "batt",+ bs: "bs",+ tst: "tst",+ bear: "bear"+ },+ customFields: [{ key: "tid", value: "colota" }]+ },dawarich: {name: "dawarich",label: "Dawarich",diff --git a/apps/mobile/src/utils/__tests__/healthCheck.test.ts b/apps/mobile/src/utils/__tests__/healthCheck.test.tsindex 287bd112..1b8f716e 100644--- a/apps/mobile/src/utils/__tests__/healthCheck.test.ts+++ b/apps/mobile/src/utils/__tests__/healthCheck.test.ts@@ -43,6 +43,12 @@ describe("resolveHealthUrls", () => {])})+ it("homeassistant: uses webhook URL directly (server returns 405 which counts as reachable)", () => {+ expect(resolveHealthUrls("http://192.168.50.186:8123/api/webhook/abc123", "homeassistant")).toEqual([+ "http://192.168.50.186:8123/api/webhook/abc123"+ ])+ })+it("custom: tries /health then origin regardless of endpoint path", () => {expect(resolveHealthUrls("https://custom.example.com/track", "custom")).toEqual(["https://custom.example.com/health",diff --git a/apps/mobile/src/utils/healthCheck.ts b/apps/mobile/src/utils/healthCheck.tsindex 93672d68..6f00b753 100644--- a/apps/mobile/src/utils/healthCheck.ts+++ b/apps/mobile/src/utils/healthCheck.ts@@ -18,6 +18,9 @@ export function resolveHealthUrls(endpoint: string, apiTemplate: ApiTemplateName}case "dawarich":return [`${origin}/api/v1/health`, origin]+ case "homeassistant":+ // HEAD request to the webhook URL itself to confirm reachability+ return [endpoint]case "owntracks":// /api/0/version for OwnTracks Recorder; Home Assistant responds at root if that 404sreturn [`${origin}/api/0/version`, origin]