v3.23.1

Getting Started Devices Gateways Integrations Reference
Get The Things Stack

Getting Started

    Overview
  • Quick Start
  • What Is The Things Stack?
  • Console
  • Subscription and Billing Management
  • Command-line Interface
  • Installing The Things Stack
  • Upgrading The Things Stack
  • Migrating to The Things Stack
    • Migrating End Devices between The Things Stack distributions
    • Migration Tool
    • Migrating End Devices from V2
    • Import End Devices in The Things Stack
    • Fine-tuning MAC Settings for End Devices
    • Migrating Gateways
    • JSON File Reference
    • CSV File Reference
    • Migration FAQ
  • The Things Stack Cloud
  • The Things Stack AWS Launcher
  • The Things Network
  • Server Addresses
  • Packet Broker
  • Single Sign-On
  • Users and Organizations
  • Using the API
  • Working with Events
  • Troubleshooting Getting Started

JSON File Reference

The Things Stack allows you to import end devices from V2, ChirpStack and other LoRaWAN networks using a JSON file describing those devices.

Using JSON file with device descriptions, you can migrate end devices with or without their existing sessions.

Here is an example of an OTAA device description in the devices.json file:

{
  "ids": {
    "device_id": "my-device",
    "dev_eui": "0102030405060708",
    "join_eui": "0102030405060708"
  },
  "name": "My Device",
  "description": "Living room temperature sensor",
  "lorawan_version": "MAC_V1_0_2",
  "lorawan_phy_version": "PHY_V1_0_2_REV_B",
  "frequency_plan_id": "EU_863_870_TTN",
  "supports_join": true,
  "root_keys": {
    "app_key": {
      "key": "01020304050607080102030405060708"
    }
  }
}

Multiple end devices can also be contained in a single devices.json file like so:

{
  /* device 1 */
}
{
  /* device 2 */
}

The format above is considered by the Console and CLI as a JSON stream, processing one object at a time. For more details in how to use the file, please refer to Import End Devices.

JSON End Device Format

The full specification of the JSON format is defined in the API protos. See the EndDevice message definition for details.

The linked specification is quite extensive, and contains a lot of fields that are not required, or are only set and used internally by the Network Server. Below, the required and most commonly used fields are discussed.

Field Required Type Example Description
ids.device_id Always string "sensor-1" More info
ids.dev_eui Always string "0102030405060708" More info
ids.join_eui Always string "0102030405060708" Also referred to as AppEUI. More info
name No string "My Sensor" Optional, a name for the device
description No string "Situated in living room" Optional, description of the device
lorawan_version Always string "MAC_V1_0_2" See MACVersion for supported versions. See LoRaWAN Version for more information.
lorawan_phy_version Always string "PHY_V1_0_2_REV_B" See PHYVersion for supported versions. See LoRaWAN Version for more information.
frequency_plan_id Always string "EU_863_870_TTN" See Frequency Plans for a list of supported frequency plans (The frequency plan ID is needed). See Frequency Plan for more information.
supports_join Always boolean true true for OTAA devices, false for ABP.
supports_class_c No boolean true true for Class C devices, false otherwise.
root_keys.app_key.key For OTAA devices string "01020304050607080102030405060708" See Application Key for more information.
root_keys.nwk_key.key For OTAA devices string "01020304050607080102030405060708" For LoRaWAN version 1.1 and later only. See Network Key for more information.
mac_settings.rx1_delay No string "RX_DELAY_5" Delay for the first Class A receive window (Rx1). Typical values are "RX_DELAY_1" (1 second) and "RX_DELAY_5" (5 seconds). See MACSettings for more information.
mac_settings.supports_32_bit_f_cnt No boolean false true if device supports 32-bit frame counters, false if device only supports 16-bit frame counters.
session.dev_addr For existing session string "01020304" Needed for ABP devices or when migrating OTAA devices with an existing session. See Device Address for more information.
session.keys.app_s_key.key For existing session string "01020304050607080102030405060708" Needed for ABP devices or when migrating OTAA devices with an existing session. See Application Session Key for more information.
session.keys.f_nwk_s_int_key.key For existing session string "01020304050607080102030405060708" Forwarding Network Session Integrity Key, also referred to as Network Session Key in LoRaWAN v1.0.x compatibility mode. See SessionKeys and Forwarding Network Session Integrity Key for more information.
session.last_f_cnt_up For existing session uint 12 Last uplink frame counter used.
session.last_n_f_cnt_down For existing session uint 12 Last network downlink frame counter used.
session.last_a_f_cnt_down For existing session uint 12 Last application downlink frame counter used.

Note that the dots in the Field column imply an embedded object. For example, root_keys.nwk_key.key must be set as:

"root_keys": {
  "nwk_key:": {
  "key": "<NWK_KEY_HERE>"
  }
}
← Migrating Gateways CSV File Reference →

On this page

  • JSON End Device Format

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 01 Jun 2022.
doc: Add instructions to migrate from Community Edition to Cloud (#858)

Edit on Github