# Demeter Third-Party Integration Guide

Demeter integrates with commercial smart-garden, irrigation, and home-automation
platforms through
[`@demeter/sensors` integrations](../../../../libs/demeter/sensors/src/integrations.ts).
This guide covers the supported platforms, the integration lifecycle, and the
two home-automation bridges (Home Assistant entities + MQTT discovery).

## Supported platforms

`SUPPORTED_INTEGRATIONS` describes each platform's capabilities and auth method:

| Platform                     | Type               | Auth          | Capabilities                                                               |
| ---------------------------- | ------------------ | ------------- | -------------------------------------------------------------------------- |
| **GARDENA smart system**     | Irrigation/sensing | OAuth2        | soil moisture, temperature, irrigation control, mowing                     |
| **Rachio Smart Sprinkler**   | Irrigation         | API key       | irrigation control, flow monitoring, weather intelligence, scheduling      |
| **Orbit B-hyve**             | Irrigation         | (token)       | irrigation control, soil moisture, scheduling                              |
| **Ecowitt Weather Stations** | Weather/soil       | API key       | temperature, humidity, wind, rain, UV, soil moisture/temp, light, pressure |
| **Ambient Weather**          | Weather            | API key       | weather metrics                                                            |
| **Davis Instruments**        | Weather            | API key       | professional weather metrics                                               |
| **Home Assistant**           | Hub                | token         | full device bridge (sensors + actuators)                                   |
| **openHAB**                  | Hub                | (basic/token) | device bridge                                                              |
| **Hubitat**                  | Hub                | (local/token) | device bridge                                                              |
| **SmartThings**              | Hub                | OAuth2        | device bridge                                                              |

Auth methods are typed (`api_key | oauth2 | basic | token | local`); each
platform declares the one it uses so the setup UI requests the right
credentials.

## Integration lifecycle

1. **Create** — `createIntegration(config)` registers a platform connection
   (platform, credentials, options) and assigns it an id.
2. **Test** — `testConnection(config)` returns an `IntegrationStatus`
   (reachable? authenticated? last error) before you rely on it.
3. **Discover & map** — `syncDevices(config, existingDevices)` lists the
   platform's devices and returns `DeviceMapping[]` reconciling them against
   devices Demeter already knows about (avoiding duplicates).
4. **Ingest** — `mapExternalReading(...)` converts a platform-native reading
   into Demeter's `NormalizedReading` so it joins the same time-series pipeline
   as native sensors.
5. **Monitor** — `getIntegrationStatus(config)` for ongoing health;
   `generateAPIToken(...)` mints tokens for platforms that call **into**
   Demeter.

`listSupportedDevices(platform)` enumerates the device models a platform
exposes.

## Home Assistant bridge

Two directions are supported:

- **Demeter → Home Assistant entities.** `createHomeAssistantEntity(device)`
  produces HA entity descriptors so Demeter sensors appear natively in Home
  Assistant dashboards/automations.
- **MQTT discovery.** `createMQTTDiscoveryPayload(device)` emits Home Assistant
  MQTT-discovery config payloads (`platform: sensor`, …) so HA auto-creates
  entities when Demeter publishes to the discovery topic — no manual HA config.

## Choosing an approach

| You want…                                      | Use                                                                    |
| ---------------------------------------------- | ---------------------------------------------------------------------- |
| A standalone irrigation/weather product's data | Its native platform integration (GARDENA, Rachio, Ecowitt, …)          |
| A unified home-automation hub                  | Home Assistant / openHAB / Hubitat / SmartThings bridge                |
| Raw devices speaking a wire protocol           | The [protocol adapters](../protocols/iot-device-protocols.md) directly |

## Security notes

- Credentials are per-integration and scoped to the declared `authMethod`.
- Tokens minted for inbound platform calls (`generateAPIToken`) follow the same
  hashed-at-rest, scoped-permission model as the API keys described in
  [ADR-0004](../architecture/adr/0004-jwt-refresh-rotation-auth.md).
