Document using ttn-lw-migrate to migrate from v2 #130
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
benolayinka
requested review from
neoaggelos,
johanstokking and
laurensslats
neoaggelos
approved these changes
Nov 30, 2020
|
|
||
| ## Export End Devices from {{% ttnv2 %}} | ||
|
|
||
| In order to export a single device, use the following command. The device with ID `mydevice` will exported and saved to `device.json`. |
There was a problem hiding this comment.
Suggested change
| In order to export a single device, use the following command. The device with ID `mydevice` will exported and saved to `device.json`. | |
| In order to export a single device, use the following command. The device with ID `mydevice` will be exported and saved to `device.json`. |
johanstokking
requested changes
Dec 2, 2020
| @@ -11,6 +11,14 @@ This section documents the process of migrating end devices from {{% ttnv2 %}} t | |||
|
|
|||
| For a breakdown of differences between {{% ttnv2 %}} and {{% tts %}}, see the [Major Changes]({{< relref "major-changes" >}}) section. | |||
|
|
|||
| >**Note**: | |||
| > | |||
| >When migrating devices from the Public Community Network to {{< tts >}} Cloud, you may choose to transfer the active device sessions as well, which means that your devices will continue to work with {{% tts %}}. | |||
There was a problem hiding this comment.
Suggested change
| >When migrating devices from the Public Community Network to {{< tts >}} Cloud, you may choose to transfer the active device sessions as well, which means that your devices will continue to work with {{% tts %}}. | |
| >When migrating devices from the Public Community Network to {{% tts %}} Cloud, you may choose to transfer the active device sessions as well, which means that your devices will continue to work with {{% tts %}}. |
| > | ||
| >When migrating from a private {{% ttnv2 %}}, devices that are outside of the DevAddr address block supported by {{% tts %}} Cloud will have to rejoin the network, otherwise {{% tts %}} will be unable to route their uplink and downlink traffic. | ||
| > | ||
| >{{% tts %}} Dedicated Cloud, Enterprise and Marketplace Launcher deployments are not affected by this issue. |
There was a problem hiding this comment.
Then use the distributions for this section?
| @@ -19,13 +27,82 @@ For a breakdown of differences between {{% ttnv2 %}} and {{% tts %}}, see the [M | |||
|
|
|||
| **Finally**: Once you are confident that your end devices are working properly, migrate the rest of your devices and gateways to {{% tts %}}. | |||
|
|
|||
| ## Configure V2 CLI | |||
| ## Configure ttn-lw-migrate | |||
There was a problem hiding this comment.
Suggested change
| ## Configure ttn-lw-migrate | |
| ## Configure `ttn-lw-migrate` |
| ## Configure V2 CLI | ||
| ## Configure ttn-lw-migrate | ||
|
|
||
| End devices and applications can easily be migrated from {{% ttnv2 %}} to {{% tts %}} with the [`ttn-lw-migrate`](https://github.com/TheThingsNetwork/lorawan-stack-migrate) tool. This tool is used for exporting end devices and applications to a [JSON file]({{< ref "getting-started/migrating/device-json.md" >}}) containing their description. This file can later be imported in {{% tts %}} as described in the [Import End Devices in The Things Stack]({{< ref "getting-started/migrating/import-devices.md" >}}) section. |
There was a problem hiding this comment.
Suggested change
| End devices and applications can easily be migrated from {{% ttnv2 %}} to {{% tts %}} with the [`ttn-lw-migrate`](https://github.com/TheThingsNetwork/lorawan-stack-migrate) tool. This tool is used for exporting end devices and applications to a [JSON file]({{< ref "getting-started/migrating/device-json.md" >}}) containing their description. This file can later be imported in {{% tts %}} as described in the [Import End Devices in The Things Stack]({{< ref "getting-started/migrating/import-devices.md" >}}) section. | |
| End devices and applications can easily be migrated from {{% ttnv2 %}} to {{% tts %}} with the [`ttn-lw-migrate`](https://github.com/TheThingsNetwork/lorawan-stack-migrate) tool. This tool is used for exporting end devices and applications to a [JSON file]({{< ref "getting-started/migrating/device-json.md" >}}) containing their description. This file can later be imported in {{% tts %}} as described in the [Import End Devices in {{% tts %}}]({{< ref "getting-started/migrating/import-devices.md" >}}) section. |
|
|
||
| >**Note:**: Payload formatters are not exported. See [Payload Formatters](https://thethingsstack.io/integrations/payload-formatters/). | ||
|
|
||
| >**Warning:**: Active device sessions are exported by default. You can disable this by using the `--ttnv2.with-session=false` flag. It is recommended that you do not export session keys for devices that can instead re-join on The Things Stack. |
There was a problem hiding this comment.
- Too many colons here (2x)
- What are "active device sessions"? Probably just sessions
- Why is this not recommended? People can't really go to their devices and power cycle them
There was a problem hiding this comment.
@neoaggelos i don't have these answers so I'm reassigning you
|
|
||
| An end device can only be registered in one Network Server at a time. After importing an end device to {{% tts %}}, you should remove it from {{% ttnv2 %}}. | ||
|
|
||
| For OTAA devices, it is enough to simply change the AppKey, so the device can no longer join but the existing session is preserved. Next time the device joins, the activation will be handled by {{% tts %}}. |
There was a problem hiding this comment.
It's not if people imported the session as well
|
|
||
| For OTAA devices, it is enough to simply change the AppKey, so the device can no longer join but the existing session is preserved. Next time the device joins, the activation will be handled by {{% tts %}}. | ||
|
|
||
| It is important that you unset the `AppKey` property of your exported devices, so that they are able to join properly on {{% tts %}}. This can be done from |
There was a problem hiding this comment.
What do you mean with "join properly"?
|
|
||
| In this step, the end devices from {{% ttnv2 %}} will be exported in a JSON format that can then be parsed and imported by {{% tts %}}. | ||
| > Optional: define an alias on ttnctl --config /home/<user_name>/.ttnctl/community.yml to go faster |
There was a problem hiding this comment.
Suggested change
| > Optional: define an alias on ttnctl --config /home/<user_name>/.ttnctl/community.yml to go faster | |
| > **Optional:** define an alias on `ttnctl --config /home/<user_name>/.ttnctl/community.yml` to go faster |
How?
| ### Disable Exported End Devices on V2 | ||
|
|
||
| After exporting, make sure to clear the AppKey of your OTAA devices. This can be achieved with the following command: | ||
| To clear the AppKey of an OTAA device, use the following command: |
There was a problem hiding this comment.
This means that the session is still in V2, and that V2 is still sending downlink messages and managing the end device's MAC state, which may lead to problems
neoaggelos
force-pushed
the
doc/ttn-lw-migrate
branch
from
d0ad4c5
to
7d2da55
Compare
|
Why is this not followed up on? @neoaggelos if you don't request reviews, it does not show up on the list for reviews and nothing happens. |
i3mSuperMan
force-pushed
the
doc/ttn-lw-migrate
branch
from
703fb13
to
7d2da55
Compare
benolayinka
force-pushed
the
doc/ttn-lw-migrate
branch
from
7d2da55
to
6c904c8
Compare
added 5 commits
February 2, 2021 17:22
benolayinka
force-pushed
the
doc/ttn-lw-migrate
branch
from
6c904c8
to
18ffa7d
Compare
neoaggelos
approved these changes
Feb 2, 2021
| $ ttnctl devices convert-all-to-abp --save-to-attribute "original-app-key" | ||
| # dry run first, verify that no errors occur | ||
| $ ttn-lw-migrate application --verbose --dry-run --source ttnv2 "my-ttn-app" > all-devices.json | ||
| # export device |
There was a problem hiding this comment.
Suggested change
| # export device | |
| # export devices |
benolayinka
commented
Feb 3, 2021
| @@ -4,9 +4,17 @@ weight: 2 | |||
| aliases: "/getting-started/migrating-from-v2/gateway-migration" | |||
| --- | |||
|
|
|||
| For instructions on adding gateways to {{% tts %}} using the CLI or Console, see [Adding Gateways]({{< ref "gateways/adding-gateways" >}}). | |||
| Migrating gateway is a two step process. | |||
There was a problem hiding this comment.
Suggested change
| Migrating gateway is a two step process. | |
| Migrating gateways is a two step process. |
|
|
||
| Update the server address in the gateway configuration settings. | ||
| - When using the Semtech UDP Packet Forwarder, make sure to update the `server_address` in the gateway configuration settings to the address of the ateway Server (e.g. `my-tts-network.nam1.cloud.thethings.industries`). | ||
| - When using the LoRa Basics Station protocol refer [LoRa Basics Station document]({{< ref "gateways/lora-basics-station" >}}) |
| @@ -74,9 +73,10 @@ Read more on [HTTP Webhooks]({{< ref "/integrations/webhooks" >}}). | |||
|
|
|||
| #### Storage Integration | |||
|
|
|||
| {{% tts %}} does not currently support a Storage integration similar to {{% ttnv2 %}}. This feature will be added in a future release. | |||
| {{% tts %}} does support a Storage integration similar to {{% ttnv2 %}}. Refer [Storage Integration]({{< ref "/integrations/storage" >}}). | |||
|
|
||
| ## Pre-requisites | ||
|
|
||
| 1. User account in V2. |
There was a problem hiding this comment.
User account in {{% ttnv2 %}}
User account in {{% tts %}} v3
| @@ -64,7 +84,7 @@ $ ttn-lw-migrate devices --dry-run --verbose --source ttnv2 "mydevice" > devices | |||
| $ 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 {{% ttnv2 %}}. Execute any commands with the `--dry-run` first, which will do everything except delete the device keys from {{% ttnv2 %}}. {{</ warning >}} | |||
| {{< warning >}} The export process will clear the device root keys (**AppKey**) and session (**AppSKey**, **NwkSKey**, **DevAddr**, **FCntUp** and **FCntDown**) from {{% ttnv2 %}} by default. You can disable this by using the `--ttnv2.with-session=false` flag. {{</ warning >}} | |||
There was a problem hiding this comment.
Why not use --dry-run ?
There was a problem hiding this comment.
Regarding the --dry-run flag, the usage is already mentioned in the same section.
There was a problem hiding this comment.
Right, it makes sense to say to use that and then use it in the example. I don't think it make sense to say
"disable this by using the --ttnv2.with-session=false flag"
and then
$ ttn-lw-migrate device --source ttnv2 --dry-run "mydevice" > devices.json
that is confusing. Let's stick to one. @neoaggelos recommended --dry-run, so i prefer that.
There was a problem hiding this comment.
@benolayinka, By default the export process will export session information of the device and clears off all the info from V2. If the --ttnv2.with-session=false flag is used, it will not include session info in the exported file and doesn’t delete it from V2.
So if the customer wants to export their devices without session info, --ttnv2.with-session=false flag needs to be added in the command. Hence, the purpose of this is different from that of the --dry-run flag.
|
this is critical documentation so i vote if there are no serious issues that we merge now and improve along the way. @johanstokking, waiting on your review. |
neoaggelos
approved these changes
Feb 5, 2021
johanstokking
approved these changes
Feb 9, 2021
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Update documentation to use ttn-lw-migrate instead of
ttnctlfor migrating from v2 to v3.Checklist
make servernew-in-versionshortcode, according to the guidelines in CONTRIBUTING.