Migrating from The Things Network Stack V2

This section documents the process of migrating end devices from The Things Network Stack V2 to The Things Stack.

For a breakdown of differences between The Things Network Stack V2 and The Things Stack, see the Major Changes section.

Suggested Migration Process

First: Update your integrations to support the The Things Stack Data Format. If you are using Payload Formatters, make sure to set them correctly from the Application settings page.

Second: Follow this guide in order to migrate a single end device (and gateway, if needed) to The Things Stack. Continue by gradually migrating your end devices in small batches. Avoid migrating production workloads before you are certain that they will work as expected.

Finally: Once you are confident that your end devices are working properly, migrate the rest of your devices and gateways to The Things Stack.

Migrating Active Sessions

When migrating devices from the public The Things Network Stack V2 to The Things Stack Cloud, you may choose to transfer the active device sessions as well, which means that your devices will continue to work with The Things Stack without rejoining.

When migrating from a private The Things Network Stack V2 , devices that are outside of the DevAddr address block supported by The Things Stack Cloud will have to rejoin the network, otherwise The Things Stack will be unable to route their uplink and downlink traffic.

Pre-requisites

1. User account in The Things Network Stack V2 .
2. User account in The Things Stack V3.
3. Install LoRaWAN stack migrate tool.

ttn-lw-migrate Tool

End devices and applications can easily be migrated from The Things Network Stack V2 to The Things Stack with the ttn-lw-migrate tool. This tool is used for exporting end devices and applications to a JSON file containing their description. This file can later be imported in The Things Stack as described in the Import End Devices in The Things Stack section.

Installation

Binaries are available on GitHub. Download the latest version asset according to your OS.

Configuration

Configure the environment with the following variables modified according to your setup:

$ export TTNV2_APP_ID="my-ttn-app"                    # TTN App ID
$ export TTNV2_APP_ACCESS_KEY="ttn-account-v2.a..."   # TTN App Access Key (needs `devices` permissions)
$ export FREQUENCY_PLAN_ID="EU_863_870_TTN"           # Frequency Plan ID for exported devices

See Frequency Plans for the list of frequency plans available on The Things Stack. Make sure to specify the correct Frequency Plan ID. For example, the ID EU_863_870_TTN corresponds to the Europe 863-870 MHz (SF9 for RX2 - recommended) frequency plan.

$ set TTNV2_APP_ID=my-ttn-app                    # TTN App ID
$ set TTNV2_APP_ACCESS_KEY=ttn-account-v2.a...   # TTN App Access Key (needs `devices` permissions)
$ set FREQUENCY_PLAN_ID=EU_863_870_TTN           # Frequency Plan ID for exported devices

Configuration for The Things Network Stack V2

private deployments

Private The Things Network Stack V2 deployments are also supported, and require extra configuration. See ttn-lw-migrate device --help for more details. For most cases, it is enough to configure ttn-lw-migrate to use the Discovery Server of your installation, by setting the following environment variables:

$ export TTNV2_DISCOVERY_SERVER_ADDRESS="<instance-id>.thethings.industries:1900"

Export End Devices from The Things Network Stack V2

Migration from The Things Network Stack V2 to The Things Stack is one-way. LoRaWAN devices may only be handled by one Network Server at a time. The commands below will clear both the root keys and the session keys from The Things Network Stack V2 after the devices are exported. This means that the devices will no longer work in The Things Network Stack V2 .

Execute commands with the --dry-run flag first to test exporting the devices without deleting the device keys from The Things Network Stack V2 . When you are ready to migrate, be sure to export the devices without the --dry-run flag to remove the device keys from The Things Network Stack V2 , as having the session keys present on both Network Servers is not supported, and will most likely lead to traffic issues and/or a corrupted device MAC state.

In order to export a single device, use the following command. The device with ID mydevice will exported and saved to device.json.

# dry run first, verify that no errors occur
$ ttn-lw-migrate devices --dry-run --verbose --source ttnv2 "mydevice" > devices.json
# export device and delete keys from The Things Network Stack V2

$ ttn-lw-migrate device --source ttnv2 "mydevice" > devices.json

In order to export a large number of devices, create a file named device_ids.txt with one device ID per line:

mydevice
otherdevice
device3
device4
device5

And then export with:

# dry run first, verify that no errors occur
$ ttn-lw-migrate devices --verbose --dry-run --source ttnv2 < device_ids.txt > devices.json
# export devices
$ ttn-lw-migrate devices --source ttnv2 < device_ids.txt > devices.json

Alternatively, you can export all the end devices associated with your application, and save them in all-devices.json.

# dry run first, verify that no errors occur
$ ttn-lw-migrate application --verbose --dry-run --source ttnv2 "my-ttn-app" > all-devices.json
# export devices
$ ttn-lw-migrate application --source ttnv2 "my-ttn-app" > all-devices.json

After exporting the end devices in to a json file you can refer to Import End Devices Document in The Things Stack for next steps.