Eve library

DIY Sensor Development Guide

Guide

Revision 1

On this page

You can build your own sensor (ESP32, Raspberry Pi Pico W, etc.) and feed it into Demeter by speaking one of its supported protocols. MQTT is the simplest path for a DIY device.

1. Register the sensor#

Create the sensor in Demeter (UI Sensors → Pairing, or POST /v1/sensors) so it belongs to a garden/bed and has an id. Note its id and type (soil_moisture, temperature, …).

2. Publish readings over MQTT#

Point your device at the MQTT broker and publish to the garden / bed / sensor topic hierarchy:

text
demeter/<garden>/<bed>/<sensor>

Send a JSON payload matching the NormalizedReading shape:

json
{
  "sensorType": "soil_moisture",
  "value": 27.4,
  "unit": "%",
  "timestamp": "2026-05-31T14:00:00.000Z",
  "metadata": { "raw": 1840, "fw": "1.2.0" }
}
  • timestamp is ISO-8601; omit it and the server stamps receipt time.
  • Extra fields go in metadata.
  • Malformed payloads are rejected — send valid JSON with a numeric value and a known sensorType, or the reading is dropped (by design, so a flaky device can't poison the time-series).

3. Batch and back off#

For battery devices, batch readings and publish on an interval (e.g. every 5–15 min) rather than continuously. Report batteryLevel in metadata so Demeter can surface a low-battery state.

4. Other transports#

  • Zigbee via zigbee2mqtt — Demeter parses the standard zigbee2mqtt JSON (temperature, humidity, soil_moisture, …).
  • BLE — characteristic JSON.
  • LoRa/LoRaWAN — decoded uplink JSON (great for far-flung outdoor probes).

See the protocol reference for ranges, power, and the adapter abstraction. For a packaged product rather than a DIY build, use a platform integration.

5. Alerts & automation#

Once readings flow, set thresholds (Sensors → Alerts) and wire the sensor into automation rules — e.g. your DIY moisture probe can trigger a valve.