Observability Platform

Plant Caravan currently supports three telemetry patterns for the sensor platform:

• Plant Caravan hosted tenant ingestion backed by InfluxDB 3.x
• Self-hosted Plant Caravan backed by your own InfluxDB 3.x
• Prometheus pull-based metrics scraped directly from the device

They are not all at the same maturity level today. Prometheus pull already works on the current ESPHome firmware. The hosted and self-hosted InfluxDB paths have a working backend ingest API and device-key auth model, but the real ESP32 push firmware is still in flight.

Current status

Current ingest schema: the cloud ingest route currently accepts temperature, humidity, soilMoisture, and light. CO2 and pressure are not on the public ingest contract yet.

Choose a connection mode

Plant Caravan hosted tenant InfluxDB

This is the SaaS path under active development. The important architecture detail is that the sensor does not talk to InfluxDB directly. It posts readings to the Plant Caravan API, and the API writes tenant-tagged points into InfluxDB server-side.

Flow

1. Create a sensor record in the Plant Caravan tenant.
2. Mint a per-sensor device key.
3. Configure the sensor to POST readings to https://<plant-caravan-host>/api/sensors/<sensor-id>/readings.
4. Plant Caravan authenticates the device key, resolves the tenant, and writes the readings to InfluxDB with sensor_id and tenant_id tags.

Device auth

Mint a key once:

pnpm --dir web tsx scripts/mint-device-key.ts --sensor-id <sensor-id>

Use that raw key as a Bearer token from the device:

POST /api/sensors/<sensor-id>/readings
Authorization: Bearer <device-key>
Content-Type: application/json

{
  "readings": [
    {
      "timestamp": "2026-04-30T18:30:00Z",
      "temperature": 74.1,
      "humidity": 48.2,
      "soilMoisture": 43.0,
      "light": 820.0
    }
  ]
}

What exists today

• The API route exists at web/src/app/api/sensors/[id]/readings/route.ts
• The InfluxDB 3.x write/query wrapper exists at web/src/lib/influxdb.ts
• A fake device can exercise the exact path today:

PLC_DEVICE_KEY=<raw-key> pnpm --dir web tsx scripts/fake-device.ts \
  --sensor-id <sensor-id> \
  --url https://<plant-caravan-host>

What is still missing

• The committed ESPHome firmware does not yet push readings to this API.
• That work is tracked in issue #55.
• Devices behind NATs are the reason this push model exists; Prometheus scrape alone is not enough for hosted SaaS.

Self-hosted Plant Caravan + InfluxDB

This path uses the exact same device protocol as the hosted path. The only difference is that you run the Plant Caravan web app and point it at your own InfluxDB 3.x instance.

Architecture

• Sensor posts to your Plant Caravan API endpoint
• Plant Caravan writes to your InfluxDB 3.x database
• Dashboard reads flow back through Plant Caravan query helpers

Required environment

INFLUXDB_URL=http://127.0.0.1:8181
INFLUXDB_DATABASE=sensor-data
INFLUXDB_TOKEN=<optional-bearer-token>

For local development, the repo already provisions this stack in web/process-compose.yaml.

Important boundary

Self-hosted InfluxDB does not currently mean “device writes directly to InfluxDB.” The implemented path is still:

sensor -> Plant Caravan API -> InfluxDB

That keeps tenant/device auth and dashboard reads consistent between hosted and self-hosted deployments.

Prometheus pull metrics

This is the path that works on the real ESPHome firmware right now.

The current firmware already exposes a metrics endpoint because hardware/firmware/plant-monitor.yaml enables:

web_server:
  port: 80
 
prometheus:
  include_internal: true

Prometheus can scrape the sensor directly:

scrape_configs:
  - job_name: plant_caravan_sensor
    metrics_path: /metrics
    static_configs:
      - targets:
          - 192.168.1.50:80

Use this mode when

• The sensor and Prometheus server are on the same LAN, VPN, or routable network
• You want a fully local stack with Home Assistant, Prometheus, and Grafana
• You do not need Plant Caravan-hosted multi-tenant dashboards

Limitations

• Hosted Plant Caravan cannot scrape devices hidden behind home NATs
• Tenant-aware cloud features do not apply to direct Prometheus scrape
• This path is local-first rather than SaaS-first

Recommended guidance

• Use Prometheus pull today if you want the fastest working setup on the current ESPHome firmware.
• Use Plant Caravan hosted InfluxDB if you are building toward the managed cloud path and are comfortable with the device push firmware still being in progress.
• Use self-hosted Plant Caravan + InfluxDB if you want the same API architecture as the hosted product but under your own infrastructure.

← Back to Docs