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
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.
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.
Warning:Migrating device sessions will be available in The Things Stack
- User account in The Things Network Stack V2 .
- User account in The Things Stack V3.
- Install LoRaWAN stack 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.
Binaries are available on GitHub. Download the latest version asset according to your OS.
Warning:Make sure to use
ttn-lw-migrateversion 0.5.0 or newer, and The Things Stack version 3.12.0 or newer.
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.
Note:For Windows OS, while configuring the app_id, app_access_key, frequency_plan_id replace
setand remove double-quotes as shown below.
$ 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 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"
Note:If the Discovery Server is not using TLS, you will need to use the
--ttnv2.discovery-server-insecureflag when running the
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
# 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
Warning:The export process will clear the device root keys (AppKey) and session (AppSKey, NwkSKey, DevAddr, FCntUp and FCntDown) from The Things Network Stack V2 by default. You can disable this by using the
Note:The export process will halt if any error occurs.
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
# 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
Note:In The Things Network Stack V2 , underscores ( _ ) are allowed in the end device ID but not in The Things Stack. You can refer to ID And EUI Constraints Document for more information. The
ttn-lw-migratetool replaces an underscore with a dash ( - ) automagically while exporting the devices.
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.