How it works

1. Open an Area in PLNTRK and use Add Sensor to create a Setup Key.
2. Enter the Setup Key on the physical sensor or automation device.
3. The device identifies itself with a permanent hardware UID and polls PLNTRK to determine whether logging is currently due.
4. PLNTRK validates both the Setup Key and hardware identity.
5. When logging is due, the device submits environmental measurements, device telemetry, firmware information, and optionally an image.

Authentication & hardware identity

Every device request must include a valid PLNTRK Setup Key. Bearer authentication is the preferred method:

Authorization: Bearer YOUR_SETUP_KEY

For backward compatibility, PLNTRK also accepts the Setup Key through:

X-PLNTRK-APIKEY: YOUR_SETUP_KEY

PLNTRK also requires a permanent hardware identity:

X-PLNTRK-HARDWARE-UID: YOUR_HARDWARE_UID

Current PLNTRK sensor firmware sends the hardware UID in both the header and the multipart form when posting readings.

Available endpoints

1. Check whether the device should log

Call this endpoint on the device's configured polling interval. PLNTRK validates the Setup Key and hardware identity, records the sensor as seen, and returns whether the device should submit a reading now.

The response also includes the current polling interval and may include an OTA firmware offer when a compatible firmware update has been requested for the sensor.

curl -X GET "https://www.plntrk.com/api/Automation/device/should-log" \
  -H "Authorization: Bearer YOUR_SETUP_KEY" \
  -H "X-PLNTRK-HARDWARE-UID: YOUR_HARDWARE_UID"

Polling response information

A successful response includes the logging decision, sensor/Area identity, polling schedule, and firmware-update information when applicable.

• should_I_Log_Data — whether the sensor should submit readings now.
• pollingIntervalMinutes — the configured polling/logging interval.
• Last-log and next-allowed-log timestamps.
• Sensor node and Area identifiers.
• firmwareUpdateRequested — whether a compatible OTA update is being offered.
• When an update is offered: target version, temporary download URL, SHA-256 hash, and firmware file size.

2. Submit sensor data

The logging endpoint accepts multipart/form-data. It does not use a JSON request body.

At least one sensor measurement or an image must be included. Device/network telemetry by itself does not count as a sensor measurement.

curl -X POST "https://www.plntrk.com/api/Automation/device/log" \
  -H "Authorization: Bearer YOUR_SETUP_KEY" \
  -H "X-PLNTRK-HARDWARE-UID: YOUR_HARDWARE_UID" \
  -F "hardwareUID=YOUR_HARDWARE_UID" \
  -F "deviceName=Custom Sensor" \
  -F "temperatureF=75.4" \
  -F "humidity=58.2" \
  -F "soilMoistureRaw=420" \
  -F "soilMoisturePercent=42.0"

To include an image, add a multipart file field such as:

-F "image=@snapshot.jpg;type=image/jpeg"

POST form fields

These are the fields currently accepted by the POST /api/Automation/device/log request model. Multipart form field names are matched case-insensitively by the server.

Individual measurements are optional, but the request must contain at least one measurement field or an image.

Soil moisture semantics

PLNTRK supports separate raw and calibrated soil-moisture values:

• soilMoistureRaw is the raw sensor/ADC value.
• soilMoisturePercent is the calibrated percentage and is the preferred field.
• soilMoisture remains available only for backward compatibility and is also interpreted as a percentage.

If both soilMoisturePercent and the legacy soilMoisture field are supplied, PLNTRK uses soilMoisturePercent.

-F "soilMoistureRaw=420" \
-F "soilMoisturePercent=42.0"

Logging behavior

• A missing Setup Key returns an authentication error.
• A missing hardware identity is rejected.
• A Setup Key that does not match the sensor's hardware identity is rejected.
• If auto logging is disabled for the sensor, PLNTRK accepts the device contact but does not create a new reading.
• If the sensor already logged within its configured polling window, PLNTRK returns successfully but tells the device to wait until the next allowed log time.
• A POST containing no sensor measurement and no image is rejected.
• When temperature and humidity are both supplied, PLNTRK calculates VPD server-side.
• Standardized measurements are saved as an Area sensor reading.
• When active plants exist in the Area, supported environmental measurements can also create plant environmental logs.
• Soil-moisture values are stored with the Area sensor reading; they are not currently written into plant environmental-condition logs.
• An uploaded image is stored as a plant photo only when active plants exist in the Area.

Current PLNTRK sensor flow

Current PLNTRK firmware follows this sequence:

1. Read local environmental sensors.
2. Call GET /device/should-log using the Setup Key and hardware UID.
3. Process the server's logging decision and any compatible OTA firmware offer.
4. If logging is due, create a multipart/form-data request.
5. Include device identity, firmware inventory, environmental measurements, network telemetry, and optional soil readings.
6. If a camera snapshot is available, stream it as the multipart image field.
7. POST the request to /api/Automation/device/log.