Harvestree LoRaWAN Payload Decoding

← Communication

This document is focused on server-side usage:

• how to decode each field into business data,
• what units to expose in APIs and dashboards,
• how to handle keepalive vs measurement payloads,
• what to do with invalid or unsupported data.
• The manufacturer provides reference decoding examples (for example JavaScript) to accelerate integration on common LoRaWAN platforms.

Reference JavaScript decoder (ChirpStack / TTN)

harvestree_decoder.js — reference decoder for ChirpStack (v3/v4) and The Things Network. Copy it into your LoRaWAN application payload codec. MOIZ updates this file to match the latest decoding documentation.

Uplink structure

Packed fields (bytes 10..12)

• Storage voltage (mV): bytes[10] + ((bytes[11] & 0x03) << 8) + 3300
• Thermogenerator voltage (mV): ((bytes[11] >> 2) & 0x3F) + ((bytes[12] & 0x0F) << 6)
• Status nibble: (bytes[12] >> 4) & 0x0F

Status interpretation

• status & 0x03 == 0: keepalive (no measurement section expected)
• status & 0x03 == 1: normal measurement payload
• status & 0x03 == 2: alarm payload
• On alarm payloads, bits 2–3 of the status nibble indicate sources; the reference decoder exposes them as alarm_source_port (bit 2) and alarm_source_system (bit 3, HVT/HEAT/MOVE)

Measurement keys for APIs and dashboards

Naming: <key>_<port> or <key>_<port>_<suffix>, with <port> in 1..4 (examples below use port 1).

Reserved port codes (0x15, 0x17) are not used in production configurations.

Temperature

Environmental

Voltage

Magnetic field

Current

Industrial analog

Vibration

Dry contact

Industrial integration (IT / data)

Database design, ingestion pipelines, SCADA/historian patterns, validation checklist, and runnable examples (Python, Node.js) are documented in the Harvestree Integration Guide.

Summary backend rules:

• Use serial_number and DevEUI for device identification in ingest pipelines.
• Persist raw payload and decoded JSON for traceability.
• Apply int16 scale factors before storing business metrics.
• If status is keepalive (0), do not expect port measurement keys.

Example decoded payloads

Keepalive frame

{
  "serial_number": 23104,
  "boardTemperature": 16,
  "baseTemperature": 45,
  "storageVoltage": 3600,
  "thermogenVoltage": 52,
  "status": 0,
  "alarm_source_port": 0,
  "alarm_source_system": 0
}

Measurement frame (PT1000 on port 1)

{
  "serial_number": 23118,
  "boardTemperature": 23,
  "baseTemperature": 30,
  "storageVoltage": 3600,
  "thermogenVoltage": 49,
  "status": 1,
  "alarm_source_port": 0,
  "alarm_source_system": 0,
  "pt_1": 25.0
}