# DIY Sensor Development Guide

You can build your own sensor (ESP32, Raspberry Pi Pico W, etc.) and feed it
into Demeter by speaking one of its
[supported protocols](../protocols/iot-device-protocols.md). 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:

```
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](../protocols/iot-device-protocols.md) for ranges,
power, and the adapter abstraction. For a packaged product rather than a DIY
build, use a
[platform integration](../integrations/third-party-integrations.md).

## 5. Alerts & automation

Once readings flow, set thresholds (**Sensors → Alerts**) and wire the sensor
into [automation rules](../automation/rule-syntax.md) — e.g. your DIY moisture
probe can trigger a valve.
