v3.23.1

Getting Started Devices Gateways Integrations Reference
Get The Things Stack

Reference

    Overview
  • Adaptive Data Rate
  • API
  • Application Packages
  • Billing with Stripe
  • Command-Line Interface
  • Components
  • Configuration
  • Data Formats
  • Data Retention and Privacy
  • Email Templates
  • Federated Authentication
  • Frequency Plans
  • FUOTA
  • Gateway RTT
  • Glossary
  • ID and EUI Constraints
  • Last Activity
  • LoRa Basics Station Implementation Guide
  • LoRaWAN Backend Interfaces Interoperability
  • LoRaWAN Specification and Regional Parameters
  • Networking
  • Packet Broker Routing
  • Packet Forwarders
  • Purging Entities
  • Rate Limiting
  • Resource Limiting
  • Root Certificates
  • Telemetry
  • Tenant Management
  • Web UI Branding

Data Formats

The streaming data integrations provide multiple formats for the delivery of application uplink messages and downlink queue operations. This section will delve into the common formats used by them.

Read about LoRaWAN message types in The Things Network documentation.

JSON

The JSON message format is described in the sections below.

Note:
Empty fields are omitted from payloads. As such, if a certain field has a value of "", 0 or false it will not be present in the message.

Join-accept Messages

The JSON join-accept messages use the following format:

{
  "end_device_ids" : {
    "device_id" : "dev1",                    // Device ID
    "application_ids" : {
      "application_id" : "app1"              // Application ID
    },
    "dev_eui" : "0004A30B001C0530",          // DevEUI of the end device
    "join_eui" : "800000000000000C",         // JoinEUI of the end device (also known as AppEUI in LoRaWAN versions below 1.1)
    "dev_addr" : "00BCB929"                  // Device address known by the Network Server
  },
  "correlation_ids" : [ "as:up:01..." ],     // Correlation identifiers of the message
  "received_at" : "2020-02-12T15:15..."      // ISO 8601 UTC timestamp at which the message has been received by the Application Server
  "join_accept" : {
    "session_key_id" : "AXBSH1Pk6Z0G166...", // Join Server issued identifier for the session keys
    "received_at" : "2020-02-17T07:49..."    // ISO 8601 UTC timestamp at which the uplink has been received by the Network Server
  }
}
Join message example
{
  "end_device_ids" : {
    "device_id" : "dev1",
    "application_ids" : {
      "application_id" : "app1"
    },
    "dev_eui" : "0004A30B001C0530",
    "join_eui" : "800000000000000C",
    "dev_addr" : "01497ECC"
  },
  "correlation_ids" : [
    "as:up:01E191YN5F2HMBQCBCVRF731VY",
    "gs:conn:01E191S6ZEWB630NTR45K5QN4Q",
    "gs:uplink:01E191YMZ2S7ZRTEGATVE2S3HH",
    "ns:uplink:01E191YMZ2J64K6FEW5F0WE7TQ",
    "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01E191YMZ2KK3TJYG5C4XZP8JK"
  ],
  "received_at" : "2020-02-17T07:49:09.935284891Z",
  "join_accept" : {
    "session_key_id" : "AXBSH1Pk6Z0G166RlH16CQ==",
    "received_at" : "2020-02-17T07:49:09.736532315Z"
  }
}

Uplink Messages

The JSON uplink messages use the following format:

{
  "end_device_ids" : {
    "device_id" : "dev1",                    // Device ID
    "application_ids" : {
      "application_id" : "app1"              // Application ID
    },
    "dev_eui" : "0004A30B001C0530",          // DevEUI of the end device
    "join_eui" : "800000000000000C",         // JoinEUI of the end device (also known as AppEUI in LoRaWAN versions below 1.1)
    "dev_addr" : "00BCB929"                  // Device address known by the Network Server
  },
  "correlation_ids" : [ "as:up:01...", ... ],// Correlation identifiers of the message
  "received_at" : "2020-02-12T15:15..."      // ISO 8601 UTC timestamp at which the message has been received by the Application Server
  "uplink_message" : {
    "session_key_id": "AXA50...",            // Join Server issued identifier for the session keys used by this uplink
    "f_cnt": 1,                              // Frame counter
    "f_port": 1,                             // Frame port
    "frm_payload": "gkHe",                   // Frame payload (Base64)
    "decoded_payload" : {                    // Decoded payload object, decoded by the device payload formatter
      "temperature": 1.0,
      "luminosity": 0.64
    },
    "rx_metadata": [{                        // A list of metadata for each antenna of each gateway that received this message
      "gateway_ids": {
        "gateway_id": "gtw1",                // Gateway ID
        "eui": "9C5C8E00001A05C4"            // Gateway EUI
      },
      "time": "2020-02-12T15:15:45.787Z",    // ISO 8601 UTC timestamp at which the uplink has been received by the gateway
      "timestamp": 2463457000,               // Timestamp of the gateway concentrator when the message has been received
      "rssi": -35,                           // Received signal strength indicator (dBm)
      "channel_rssi": -35,                   // Received signal strength indicator of the channel (dBm)
      "snr": 5.2,                            // Signal-to-noise ratio (dB)
      "uplink_token": "ChIKEA...",           // Uplink token injected by gateway, Gateway Server or fNS
      "channel_index": 2                     // Index of the gateway channel that received the message
      "location": {                          // Gateway location metadata (only for gateways with location set to public)
        "latitude": 37.97155556731436,       // Location latitude
        "longitude": 23.72678801175413,      // Location longitude
        "altitude": 2,                       // Location altitude
        "source": "SOURCE_REGISTRY"          // Location source. SOURCE_REGISTRY is the location from the Identity Server.
      }
    }],
    "settings": {                            // Settings for the transmission
      "data_rate": {                         // Data rate settings
        "lora": {                            // LoRa modulation settings
          "bandwidth": 125000,               // Bandwidth (Hz)
          "spreading_factor": 7              // Spreading factor
        }
      },
      "coding_rate": "4/6",                  // LoRa coding rate
      "frequency": "868300000",              // Frequency (Hz)
    },
    "received_at": "2020-02-12T15:15..."     // ISO 8601 UTC timestamp at which the uplink has been received by the Network Server
    "consumed_airtime": "0.056576s",         // Time-on-air, calculated by the Network Server using payload size and transmission settings
    "locations": {                           // End device location metadata
      "user": {
        "latitude": 37.97155556731436,       // Location latitude
        "longitude": 23.72678801175413,      // Location longitude
        "altitude": 10,                      // Location altitude
        "source": "SOURCE_REGISTRY"          // Location source. SOURCE_REGISTRY is the location from the Identity Server.
      }
    },
    "version_ids": {                          // End device version information
        "brand_id": "the-things-products",    // Device brand
        "model_id": "the-things-uno",         // Device model
        "hardware_version": "1.0",            // Device hardware version
        "firmware_version": "quickstart",     // Device firmware version
        "band_id": "EU_863_870"               // Supported band ID
    },
    "network_ids": {                          // Network information
      "net_id": "000013",                     // Network ID
      "tenant_id": "tenant1",                 // Tenant ID
      "cluster_id": "eu1"                     // Cluster ID
    }
  },
  "simulated": true,                         // Signals if the message is coming from the Network Server or is simulated.
}
Uplink message example
{
  "end_device_ids" : {
    "device_id" : "dev1",
    "application_ids" : {
      "application_id" : "app1"
    },
    "dev_eui" : "0004A30B001C0530",
    "join_eui" : "800000000000000C",
    "dev_addr" : "00BCB929"
  },
  "correlation_ids" : [
    "as:up:01E0WZGT6Y7657CPFPE5WEYDSQ",
    "gs:conn:01E0WDEC6T5T4XXBAX7S1VMFKE",
    "gs:uplink:01E0WZGSZWT07NE5TS2APTV1Z9",
    "ns:uplink:01E0WZGSZXZXZS8RFAWZX0F2FY",
    "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01E0WZGSZXGE1KS577PFBWRJEE"
  ],
  "received_at" : "2020-02-12T15:15:46.014773143Z",
  "uplink_message" : {
    "session_key_id" : "AXA50tHUGUucuzS/bCGMNw==",
    "f_cnt" : 1,
    "frm_payload" : "gkHe",
    "decoded_payload" : {
      "temperature": 1.0,
      "luminosity": 0.64
    },
    "rx_metadata" : [ {
      "gateway_ids" : {
        "gateway_id" : "gtw1",
        "eui" : "9C5C8E00001A05C4"
      },
      "time" : "2020-02-12T15:15:45.787Z",
      "timestamp" : 2463457000,
      "rssi" : -35,
      "channel_rssi" : -35,
      "snr" : 5,
      "uplink_token" : "ChIKEAoEZ3R3MRIInFyOAAAaBcQQ6L3Vlgk=",
      "channel_index" : 2
    } ],
    "settings" : {
      "data_rate" : {
        "lora" : {
          "bandwidth" : 125000,
          "spreading_factor" : 7
        }
      },
      "coding_rate" : "4/6",
      "frequency" : "868300000",
      "timestamp" : 2463457000,
      "time" : "2020-02-12T15:15:45.787Z"
    },
    "consumed_airtime": "0.056576s",
    "locations": {
      "user": {
        "latitude": 37.97155556731436,
        "longitude": 23.72678801175413,
        "altitude": 10,
        "source": "SOURCE_REGISTRY"
      }
    },
    "version_ids": {
        "brand_id": "the-things-products",
        "model_id": "the-things-uno",
        "hardware_version": "1.0",
        "firmware_version": "quickstart",
        "band_id": "US_902_928"
    },
    "network_ids": {
      "net_id": "000013",
      "tenant_id": "tenant1",
      "cluster_id": "nam1"
    },
    "received_at" : "2020-02-12T15:15:45.789585559Z"
  }
}
Note:

End device key-value attributes are not included in uplink messages, because these attributes are stored in the Identity Server and normally they are static, so sending that data with every uplink is inefficient. Users can instead fetch device’s attributes using the API:

curl --request GET /
  --location 'https://thethings.example.com/api/v3/applications/<application-id>/devices/<device-id>?field_mask=attributes' /
  --header "Authorization: Bearer <api-key>"

Downlink Events Messages

The JSON downlink ack, nack, queued and sent events messages use the following format:

{
  "end_device_ids" : {
    "device_id" : "dev1",                    // Device ID
    "application_ids" : {
      "application_id" : "app1"              // Application ID
    },
    "dev_eui" : "0004A30B001C0530",          // DevEUI of the end device
    "join_eui" : "800000000000000C",         // JoinEUI of the end device (also known as AppEUI in LoRaWAN versions below 1.1)
    "dev_addr" : "00BCB929"                  // Device address known by the Network Server
  },
  "correlation_ids" : [ "as:downlink:..." ], // Correlation identifiers of the message
  "received_at" : "2020-02-17T10:32:24...",  // ISO 8601 UTC timestamp at which the message has been received by the Network Server
  "downlink_queued" : {                      // Name of the event (ack, nack, queued or sent)
    "session_key_id" : "AXBSH1Pk6Z0G166...", // Join Server issued identifier for the session keys
    "f_port" : 15,                           // Frame port
    "f_cnt" : 1,                             // Frame counter
    "frm_payload" : "vu8=",                  // Frame payload (Base64)
    "confirmed" : true,                      // If the downlink expects a confirmation from the device or not
    "priority" : "NORMAL",                   // Priority of the message in the downlink queue
    "correlation_ids" : [ "as:downlink..." ] // Correlation identifiers of the message
  }
}
Downlink event message example
{
  "end_device_ids" : {
    "device_id" : "dev1",
    "application_ids" : {
      "application_id" : "app1"
    },
    "dev_eui" : "0004A30B001C0530",
    "join_eui" : "800000000000000C",
    "dev_addr" : "00C30DFA"
  },
  "correlation_ids" : [
    "as:downlink:01E19B99501X84X6CV471TVSZ1",
    "as:up:01E19B9J8ED6HZW5CC41KPGHVD",
    "gs:conn:01E191S6ZEWB630NTR45K5QN4Q",
    "gs:uplink:01E19B9J17SRJWJ4GV3MCJHNWZ",
    "ns:uplink:01E19B9J1CG3QNWS5M8G3DBMPN",
    "rpc:/ttn.lorawan.v3.GsNs/HandleUplink:01E19B9J17K85MJ1MXPHTW0410"
  ],
  "received_at" : "2020-02-17T10:32:24.590413417Z",
  "downlink_ack" : {
    "session_key_id" : "AXBSp8v2brG0jqkri+sIkw==",
    "f_port" : 15,
    "f_cnt" : 1,
    "frm_payload" : "vu8=",
    "confirmed" : true,
    "priority" : "NORMAL",
    "correlation_ids" : [ "as:downlink:01E19B99501X84X6CV471TVSZ1" ]
  }
}

The JSON downlink failed event provides both the downlink and the error details, in the following format:

{
  "end_device_ids" : {
    "device_id" : "dev1",                    // Device ID
    "application_ids" : {
      "application_id" : "app1"              // Application ID
    }
  },
  "correlation_ids" : [ "as:downlink:..." ], // Correlation identifiers of the message
  "downlink_failed" : {
    "downlink" : {                           // Downlink that which triggered the failure
      "f_port" : 15,                         // Frame port
      "frm_payload" : "YWFhYWFhY...",        // Frame payload (Base64)
      "confirmed" : true,                    // If the downlink expects a confirmation from the device or not
      "priority" : "NORMAL",                 // Priority of the message in the downlink queue
      "correlation_ids" : [ "as:downli..." ] // Correlation identifiers of the message
    },
    "error" : {                              // Error that was encountered while sending the downlink
      "namespace" : "pkg/networkserver",     // Component in which the error occurred
      "name" : "application_downlink_to...", // Error ID
      "message_format" : "application ...",  // Error message
      "correlation_id" : "2e7f786912e94...", // Correlation identifiers of the error
      "code" : 3                             // gRPC error code
    }
  }
}
Downlink failed event message example
{
  "end_device_ids" : {
    "device_id" : "dev1",
    "application_ids" : {
      "application_id" : "app1"
    }
  },
  "correlation_ids" : [ "as:downlink:01E19Z5W3BZBG7CXSJE9C0A3CE" ],
  "downlink_failed" : {
    "downlink" : {
      "f_port" : 15,
      "frm_payload" : "vu8=",
      "confirmed" : true,
      "priority" : "NORMAL",
      "correlation_ids" : [ "as:downlink:01E19Z5W3BZBG7CXSJE9C0A3CE" ]
    },
    "error" : {
      "namespace" : "pkg/networkserver",
      "name" : "application_downlink_too_long",
      "message_format" : "application downlink payload is too long",
      "correlation_id" : "2e7f786912e946e597894e381d0ad7b0",
      "code" : 3
    }
  }
}

Downlink Messages

The JSON downlink messages use the following format:

{
  "end_device_ids" : {
    "device_id" : "dev1",                    // Device ID
    "application_ids" : {
      "application_id" : "app1"              // Application ID
    }
  },
  "downlinks": [{
    "f_port": 15,                            // Frame port
    "frm_payload": "vu8=",                   // Frame payload (Base64)
    "decoded_payload" : {                    // Decoded payload object, to be encoded by the device payload formatter
      "temperature": 1.0,
      "luminosity": 0.64
    },
    "priority": "NORMAL",                    // Priority of the message in the downlink queue
    "confirmed": true,                       // If the downlink expects a confirmation from the device or not
    "correlation_ids" : [ "custom-id" ]      // Correlation identifiers of the message
  }]
}

The end device identifiers need to be supplied only to frontends that do not derive it from other sources (such as the URL for webhooks or topic name for MQTT).

Downlink message example
{
  "end_device_ids" : {
    "device_id" : "dev1",
    "application_ids" : {
      "application_id" : "app1"
    }
  },
  "downlinks": [{
    "f_port": 15,
    "frm_payload": "vu8=",
    "decoded_payload" : {
      "temperature": 1.0,
      "luminosity": 0.64
    },
    "priority": "NORMAL",
    "confirmed": true,
    "correlation_ids" : [ "custom-id" ]
  }]
}
← Packet Broker Agent Options Data Retention and Privacy →

On this page

  • JSON

The Things Stack

Getting Started

Devices

Gateways

Integrations

Reference

Contributing

GitHub

Forum

About Us

The Things Network

The Things Industries

About this page

Last changed by Nejra Selimović on 11 Feb 2022.
doc: Add network and device hardware info to uplink data format (#775)

Edit on Github