v3.20.2

Getting Started Devices Gateways Integrations Reference
Get The Things Stack

Getting Started

    Overview
  • Quick Start
  • What Is The Things Stack?
  • Console
  • Command-line Interface
  • Installing The Things Stack
  • Upgrading The Things Stack
  • Migrating to The Things Stack
    • Migrating End Devices from Community Edition to Cloud
    • Migrating End Devices from ChirpStack
    • Migrating End Devices from V2
      • Major Changes In The Things Stack
      • Packet Broker Requirements for End Device Migration
      • Migrate using the Console
      • Migrate using the Migration Tool
        • Migrate without Persisting Active Sessions
        • Migrate Active Sessions
      • Migrate using the V2 Takeout Tool
    • Migration Tool
    • 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

Migrate without Persisting Active Sessions

This section explains how to export one or more of your end devices from V2 to a JSON file, without persisting their session.

We strongly recommend migrating end devices without persisting active sessions.

  • OTAA
  • ABP

When migrating OTAA devices without persisting active sessions, a new join needs to be performed on The Things Stack to establish a new session.

By establishing the new session with The Things Stack, an OTAA device gets assigned a new DevAddr and default values of some other parameters (like 5 seconds RX1 Delay). This ensures that the traffic sent by these end devices can be properly routed by the Packet Broker to and from The Things Stack.

The DevAddr and some other parameters (like RX1 Delay) are hardcoded for ABP devices. If you do not re-program the device to change these values, you can migrate it to The Things Stack using the migration tool without its security keys, network parameters, etc. without its active session.

If you want your end device traffic to be routed via Packet Broker to The Things Stack, the DevAddr must be routable by the Packet Broker and the RX1 Delay value must be 5 seconds. Note that the DevAddr is routable only if you are using The Things Industries V2 (SaaS) and migrating to The Things Stack Cloud, and even that is being achieved only on customer request by contacting The Things Industries support.

If you are not migrating from The Things Industries V2 (SaaS) to The Things Stack Cloud, Packet Broker will not be able to route your ABP device’s traffic properly, so you will have to migrate your gateway to The Things Stack too. Be aware that in this case the RX1 Delay value of 1 second is persisted, and even if you do migrate your gateway, you could still be experiencing latency issues if your gateway has a high latency backhaul.

Warning:

This is not a recommended practice. We advise re-programming the ABP device to change the DevAddr to the one issued by The Things Stack and RX1 Delay to 5 seconds, even if you do not want your traffic to be routed by Packet Broker.

In case you are able to re-program your ABP device, you will have to follow the Migrate using the Console guide. The reason for this is that when you re-program your ABP device, its DevAddr and other parameters will no longer match the device description stored in V2, so you will not be able to export the current device description using the ttn-lw-migrate tool.

Before exporting end devices, you can first test the execution by appending the --dry-run and --verbose flags to the commands presented in the sections below.

Use the --ttnv2.resets-to-frequency-plan flag to configure the factory preset frequencies of the device, so that it can keep working with The Things Stack. The list of uplink frequencies is inferred from the Frequency Plan.

Export a Single End Device

To export a single end device from V2:

ttn-lw-migrate device --source ttnv2 "v2-end-device-ID" --ttnv2.with-session=false > devices.json

Export a Batch of End Devices

First, create a text file device_ids.txt. This file needs to contain a V2 Device ID for every end device you want to export from V2.

The format of this file is one Device ID per one line, i.e.:

dev1
dev2
dev3

To export a batch of end devices from V2:

ttn-lw-migrate device --source ttnv2 --ttnv2.with-session=false < device_ids.txt > devices.json

Export All End Devices Associated With V2 Application

To export all devices contained in V2 application:

ttn-lw-migrate application --source ttnv2 "ttn-v2-application-ID" --ttnv2.with-session=false > devices.json

Prevent the End Device from Joining V2 Network

Exporting end devices without their active sessions does not clear root and session keys on V2. Hence, you need to prevent your devices from re-joining the V2 network.

  • OTAA
  • ABP
To prevent OTAA device from re-joining the V2 network, the recommended practice is to change the AppKey in the V2. By changing the AppKey, the existing session on V2 will not be terminated yet, but the end device will not be able to re-join because the V2 cluster will reject its new Join Requests.
ABP devices must be completely deleted from V2, especially if you have not re-programmed them with a new DevAddr. Having a device registered in V2 and The Things Stack will cause a race condition and communication issues.

Import End Devices in The Things Stack Application

Now that you have exported one or more of your devices to a devices.json file, you can continue by importing this file in The Things Stack via Console or via CLI. See Import End Devices in The Things Stack for detailed instructions on how to do this.

  • OTAA
  • ABP

Let the OTAA End Device Join The Things Stack Network

Next, your OTAA end device needs to join The Things Stack network. Since you have not migrated your device with its active session, it will need to perform a new join.

Some OTAA devices ocasionally perform new joins - with these end devices, you can only wait for them to do this on their own.

You could also send a downlink message from the V2 Console to trigger a new join if your device supports this - contact your device maker for detailed instructions.

Some devices are also triggered when power cycled, or when deleted from V2.

Next Step - Migrate Gateways

Since we assume that you have not migrated your gateway from V2 yet, new Join Requests sent by your OTAA device are still being received by the V2 network. However, if you have prevented your device from joining V2 network (as recommended above), these Join Requests are not going to be accepted by the V2 Network Server.

Instead, these Join Requests are going to be routed to The Things Stack via Packet Broker and The Things Stack will accept them. Your OTAA device will negotiate with The Things Stack Network Server to obtain a new DevAddr, channel settings and other MAC parameters. The traffic from your end device can from now on be routed to The Things Stack thanks to the newly assigned DevAddr and RX1 Delay of 5 seconds, which fulfills the Packet Broker requirements.

Next Step - Migrate Gateways

This section implies that you are keeping the DevAddr and RX1 Delay values from V2, which means Packet Broker will be able to route the traffic properly only if you are migrating from The Things Industries V2 to The Things Stack Cloud. This can be only achieved on a customer request, so if this is the case please contact The Things Industries support for more information.

If you are not migrating from The Things Industries V2 to The Things Stack Cloud, please follow the guide to migrate your gateway to The Things Stack.

Even if you manage to get your end device traffic routed to The Things Stack by Packet Broker, we recommend to migrate your gateways as soon as possible.

← Migrate using the Migration Tool Migrate Active Sessions →

On this page

  • Prevent the End Device from Joining V2 Network
  • Import End Devices in The Things Stack Application
  • Let the OTAA End Device Join The Things Stack Network
  • Next Step - Migrate Gateways
  • Next Step - Migrate Gateways

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 23 Dec 2021.
doc: Remove $ character from code blocks, add variables (#678)

Edit on Github