sdrangel/json_udp_data_format.readme.md

# Meshtastic Demodulator JSON UDP Packet Format

## Conditions

    Condition                    lora.packet_type   meshtastic section
    ---------------------------  -----------------  --------------------------------------------------
    Meshtastic, decrypted        meshtastic         present, decryption: decrypted, parsed: true, full fields
    Meshtastic, plaintext        meshtastic         present, decryption: plaintext, parsed: true, full fields
    Meshtastic, not decrypted    meshtastic         present, decryption: not_decrypted, parsed: false, no fields
    LoRaWAN                      lorawan            absent
    Helium                       helium             absent
    Unknown/unset                unset              absent
    Other private network        custom             absent


## Fields Always Present

    timestamp           Local ISO 8601, no timezone, e.g. 2026-04-24T18:40:25.123
    timestamp_unix      Milliseconds since Unix epoch
    rf.center_freq_hz   Device center frequency plus channel offset in Hz
    rf.bandwidth_hz     LoRa bandwidth in Hz
    rf.spreading_factor LoRa spreading factor integer
    rf.signal_db        Signal power in dB
    rf.noise_db         Noise floor in dB
    rf.snr_db           Signal minus noise in dB
    lora.packet_type    meshtastic, lorawan, helium, unset, or custom
    lora.sync_word      Hex string e.g. 0x2b
    lora.header_fec     ok, fix, err, or n/a
    lora.header_crc     ok or err
    lora.payload_fec    ok, fix, err, or n/a (n/a when early_eom is true)
    lora.payload_crc    ok, err, or n/a (n/a when early_eom is true)
    lora.early_eom      true or false
    lora.packet_length  Payload length in bytes
    lora.nb_symbols     Symbol count integer
    lora.nb_codewords   Codeword count integer
    lora.payload_hex    Raw payload as continuous lowercase hex string


## Fields Present Only When lora.packet_type Is meshtastic

    meshtastic.channel_hash        Hex string e.g. 0x08
    meshtastic.packet_id           Meshtastic 32-bit unique packet ID hex string e.g. 0x5a42f351
    meshtastic.hash_matching_index Integer index of matched key, or none
    meshtastic.decryption          decrypted, plaintext, or not_decrypted
    meshtastic.key_label           Key name, no_key, or unknown_key
    meshtastic.parsed              true or false


## Fields Present Only When meshtastic.parsed Is true

    meshtastic.channel_type    Modem preset name e.g. LONG_FAST
    meshtastic.hop_start       Integer
    meshtastic.hop_limit       Integer
    meshtastic.hops_consumed   Integer, equals hop_start minus hop_limit
    meshtastic.relay_node      Integer node ID of last relay
    meshtastic.fields          Object containing all decoded fields as dot-path key/value pairs


## Decryption Values

    decrypted      Payload was successfully decrypted using a matching key
    plaintext      Payload parsed directly without encryption
    not_decrypted  All available keys were tried, none succeeded


## Key Label Values

    <name>         Actual key label e.g. LongFast:default
    no_key         Packet was plaintext, no key was used
    unknown_key    Decryption failed, key is unknown


## FEC and CRC Values

    ok    Check passed with no errors
    fix   Errors detected and corrected by FEC
    err   Errors detected but not correctable
    n/a   Not applicable, packet ended early before payload was received


## Note on packet_id

    The Meshtastic packet ID is a large random 32-bit value generated by the originating node.
    Its primary purpose is to serve as a cryptographic nonce component for AES-CTR decryption,
    combined with the from node ID. It also serves as a deduplication key in the mesh so that
    relay nodes can discard copies of already-forwarded packets. It is not a sequential counter.


## Example: Fully Decoded Meshtastic Packet

    {
      "timestamp": "2026-04-24T18:40:25.123",
      "timestamp_unix": 1745541625123,
      "rf": {
        "center_freq_hz": 906875000,
        "bandwidth_hz": 250000,
        "spreading_factor": 11,
        "signal_db": -46.0,
        "noise_db": -84.2,
        "snr_db": 13.6
      },
      "lora": {
        "packet_type": "meshtastic",
        "sync_word": "0x2b",
        "header_fec": "ok",
        "header_crc": "ok",
        "payload_fec": "ok",
        "payload_crc": "ok",
        "early_eom": false,
        "packet_length": 58,
        "nb_symbols": 152,
        "nb_codewords": 58,
        "payload_hex": "ffffffff363e0c47..."
      },
      "meshtastic": {
        "channel_hash": "0x08",
        "packet_id": "0x5a42f351",
        "hash_matching_index": 0,
        "decryption": "decrypted",
        "key_label": "LongFast:default",
        "parsed": true,
        "channel_type": "LONG_FAST",
        "hop_start": 3,
        "hop_limit": 1,
        "hops_consumed": 2,
        "relay_node": 165,
        "fields": {
          "header.to": "0xffffffff",
          "header.from": "0xc4a4bc28",
          "header.via_mqtt": "false",
          "data.port_name": "NODEINFO_APP",
          "nodeinfo.long_name": "us.tx.addison.001",
          "nodeinfo.short_name": "nvx2",
          "nodeinfo.macaddr": "c7:d4:17:07:43:8a",
          "nodeinfo.hw_model": "9",
          "nodeinfo.is_licensed": "true"
        }
      }
    }


## Example: Not Decrypted

    {
      "timestamp": "2026-04-24T18:40:25.123",
      "timestamp_unix": 1745541625123,
      "rf": { ... },
      "lora": {
        "packet_type": "meshtastic",
        "sync_word": "0x2b",
        ...
      },
      "meshtastic": {
        "channel_hash": "0x08",
        "packet_id": "unknown",
        "hash_matching_index": "none",
        "decryption": "not_decrypted",
        "key_label": "unknown_key",
        "parsed": false
      }
    }


## Example: LoRaWAN Packet

    {
      "timestamp": "2026-04-24T18:40:25.123",
      "timestamp_unix": 1745541625123,
      "rf": { ... },
      "lora": {
        "packet_type": "lorawan",
        "sync_word": "0x12",
        ...
        "payload_hex": "ffffffff363e0c47..."
      }
    }