Demeter integrates with commercial smart-garden, irrigation, and home-automation
platforms through
@demeter/sensors integrations.
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#
- Create —
createIntegration(config)registers a platform connection (platform, credentials, options) and assigns it an id. - Test —
testConnection(config)returns anIntegrationStatus(reachable? authenticated? last error) before you rely on it. - Discover & map —
syncDevices(config, existingDevices)lists the platform's devices and returnsDeviceMapping[]reconciling them against devices Demeter already knows about (avoiding duplicates). - Ingest —
mapExternalReading(...)converts a platform-native reading into Demeter'sNormalizedReadingso it joins the same time-series pipeline as native sensors. - 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 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.