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, higher bits indicate alarm source flags (port/system)

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 (0x11, 0x15, 0x17) are not used in production configurations.

Temperature

Environmental

Voltage

Magnetic field

Current

Industrial analog

Vibration

Dry contact

Integration rules (backend)

• Use serial_number (from payload) as a practical key for device identification and data organization in ingest pipelines.
• Persist raw payload and decoded JSON for traceability.
• For int16 scaled values, apply scale before storing business metrics (0.1 step).
• For float32 channels, unit is application-dependent; expose unit metadata from your device configuration context.
• If status indicates keepalive, do not expect measurement keys.
• If payload length is inconsistent with configured port measurements, reject the frame and flag decoding error.

Dashboard recommendations

• Separate clearly:
• device health metrics (storageVoltage, thermogenVoltage, internal temperatures),
• process metrics (port measurements),
• alarm state (status + source flags).

Example decoded payloads

Keepalive frame

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

Measurement frame (PT1000 on port 1)

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