Eve library

Demeter Third-Party Integration Guide

Guide

Revision 1

On this page

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#

  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 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.