diff --git a/doc/content/devices/_index.md b/doc/content/devices/_index.md index 3032aad505..36d7467ec4 100644 --- a/doc/content/devices/_index.md +++ b/doc/content/devices/_index.md @@ -7,4 +7,4 @@ menu: weight: 3 --- -This section contains information to help you work with end devices in {{% tts %}}. Here, you'll find guides for adding devices, configuring MAC settings, best practices for designing devices, and much more. +This section contains guides to add, configure and troubleshoot LoRaWAN® end devices in {{% tts %}}. There are also guides on core concepts to learn more and detailed information on popular end devices. diff --git a/doc/content/devices/adding-devices/_index.md b/doc/content/devices/adding-devices/_index.md index 8a996294ce..c43d713c41 100644 --- a/doc/content/devices/adding-devices/_index.md +++ b/doc/content/devices/adding-devices/_index.md @@ -7,386 +7,84 @@ aliases: - /the-things-stack/interact/cli/create-end-device - /the-things-stack/interact/console/create-end-device - /getting-started/device-claiming/claim-devices -weight: -1 +weight: 1 --- -This section contains instructions for adding devices in {{% tts %}}. +This section contains instructions for adding LoRaWAN® devices in {{% tts %}}. -Devices are managed under applications. An application can contain an unlimited number of devices, but it can be helpful to sort devices in to applications by function or geographical area, to make the integrations and live data views more useful. +End devices in {{% tts %}} are managed under **Applications**. +An application is a logical collection of devices that can be used to collect devices by function or geographical area. Before proceeding with this guide, [create an application]({{< ref "/integrations/adding-applications/" >}}) first. -Devices can be easily added using the Console and the CLI, so those methods are extensively explained in this section. It is also possible to add devices [using the API]({{< ref "/the-things-stack/interact/api#multi-step-actions" >}}). +This guide assumes that your device is in the [LoRaWAN® Device Repository](https://github.com/TheThingsNetwork/lorawan-devices/) and that you're using the Console. If your device is not in the LoRaWAN® Device Repository or if you want to use {{% tts %}} CLI, see [Manually adding devices ]({{< ref "/devices/adding-devices/manual/" >}}). -{{< tabs/container "Console" "CLI" >}} - -{{< tabs/tab "Console" >}} - -## Adding devices using the Console - -To create a device, first open the application you wish to add the device in. Go to **End devices** in the left menu and click on **+ Add end device** to reach the end device registration page. +To create a device, first open the application you wish to add the device in. Go to **End devices** in the left menu and click on **+Register end device** to reach the end device registration page. {{< figure src="application-overview.png" alt="Application overview" >}} You will be presented with options to easily onboard your device using its QR code (if you have it), and to register your end device from the [LoRaWAN® Device Repository](https://github.com/TheThingsNetwork/lorawan-devices/) or manually. -{{< figure src="adding-devices-options.png" alt="Options to add devices" >}} - -Keep reading to learn how to register devices using these methods. - -### Onboarding devices using QR codes - -If your device has a [TR005 LoRaWAN® Device Identification QR Code](https://lora-alliance.org/resource_hub/tr005-lorawan-device-identification-qr-codes/), it is a no-brainer to onboard it on {{% tts %}}. Note not all QR codes on the physical device are scannable. If your device doesn't have a QR code or has a vendor specific QR code, you can skip this section. - -Click the **Scan end device QR code** button and allow {{% tts %}} to use your camera. - -{{< figure src="waiting-for-camera.png" alt="Waiting for camera" >}} +{{< figure src="register-devices-option.png" alt="Options to register devices" >}} -Now just bring your device's QR code closer to your camera. A window with data found from the QR code will appear, containing your device's **Claim authentication code**, **JoinEUI**, **DevEUI** and **Brand**. If the data seems correct, click **Apply**. +{{< tabs/container "With QR Code" "Without QR Code" >}} -{{< figure src="found-qr-data.png" alt="Found QR data" >}} +{{< tabs/tab "With QR Code" >}} -Now proceed to choose the **Input Method** under the **End device type** section below and keep following the corresponding instructions for [using the LoRaWAN Device Repository]({{< ref "/devices/adding-devices#using-the-lorawan-device-repository" >}}) or [manual registration]({{< ref "/devices/adding-devices#manually-registering-an-end-device" >}}). +#### Onboarding devices using QR codes -The image below shows an example for when a user chooses to **Enter end device specifics manually**. One can notice that parameters like **Frequency plan**, **LoRaWAN version**, **Regional Parameters version** and **AppKey** have to be set manually, and some advanced settings can be adjusted, while the **JoinEUI** and **DevEUI** fields will be pre-filled from the scanned QR code. +If your device has a [TR005 LoRaWAN® Device Identification QR Code](https://lora-alliance.org/resource_hub/tr005-lorawan-device-identification-qr-codes/), adding a device is a simple process. +Note not all QR codes on the physical device are scannable. Only TR005 LoRaWAN® Device Identification QR Codes, are supported for this method. -{{< figure src="pre-filled-eui-data.png" alt="Registering device with pre-filled EUI data" >}} +Click the **Scan end device QR code** button and allow {{% tts %}} to use your camera. +Now just bring your device's QR code closer to your camera. A window with data found from the QR code will appear, containing your device's **Claim authentication code**, **JoinEUI**, **DevEUI** and **Brand**. -### Using the LoRaWAN Device Repository +{{< figure src="qr-data-found.png" alt="Found QR data" >}} -The [LoRaWAN device repository](https://github.com/TheThingsNetwork/lorawan-devices) contains device profiles, LoRaWAN information, codecs, and more, for many LoRaWAN devices. Using the device repository to add devices in {{% tts %}} automatically uses the correct LoRaWAN version and regional parameters version, which means less information for you to find! +If the data is correct, click **Apply**. -If your device is not in the device repository, see [Manual Registration]({{< ref "/devices/adding-devices#manually-registering-an-end-device" >}}). +Now proceed to choose the **Input Method** under the **End device type** section below. -To use the device repository, make sure you choose the **Select the end device in the LoRaWAN Device Repository** input method. Then, select the **End device brand**, **Model**, **Hardware Version**, **Software Version**, and **Profile (Region)** for your device. - -Choose a **Frequency plan** appropriate for your region. Your device and gateway must use the same [frequency plan]({{< ref "/reference/frequency-plans/" >}}) to communicate. +Choose the **Select the end device in the LoRaWAN Device Repository** input method. Then, select the **End device brand**, **Model**, **Hardware Version**, **Software Version**, and **Profile (Region)** for your device. {{< figure src="device-repo.png" alt="Creating a new device with the Device Repository" >}} -Enter a **JoinEUI/AppEUI** if provided by your manufacturer and click **Confirm**. If it is not provided by the manufacturer and your device is programmable, you can generate a random one in accordance with the test ranges defined by the [IEEE 802 standards](https://ieee802.org/) or use all zeros, just make sure to program the same value into your device. - -Now enter your **DevEUI**. This should be provided by your manufacturer for commercial devices. If your device is programmable, you may generate an EUI using the **Generate** button, and program it in your device. - -{{< note >}} Note that the **JoinEUI** and **DevEUI** fields will be pre-filled if you scanned your device's QR code as explained in [Onboarding Devices using QR Codes]({{< ref "/devices/adding-devices#onboarding-devices-using-qr-codes" >}}) section. {{}} - -For LoRaWAN version 1.0.x devices, you will see an **AppKey** field, and for LoRaWAN version 1.1.x devices you will also see a **NwkKey** field. If these keys are provided by your manufacturer, enter them. Otherwise, use the **Generate** button to create them, and program them into your device. - -{{< figure src="device-repo-settings.png" alt="Device information" >}} - -Finally, give your device a unique **End device ID**, and click the **Register end device** button to create the end device. See [ID and EUI constraints]({{< ref "reference/id-eui-constraints" >}}) for guidelines about choosing a unique ID. - -The device is now activated, and will appear as connected in {{% tts %}} once it sends an uplink. - -### Manually registering a device - -If your device is not available in the device repository, you may manually register it. To do this, choose the **Enter end device specifics manually** input method. Please refer to your device's datasheet to ensure entering the following information correctly. If such sheet has not been provided, please contact the manufacturer to assist you with obtaining this data. - Choose a **Frequency plan** appropriate for your region. Your device and gateway must use the same [frequency plan]({{< ref "/reference/frequency-plans/" >}}) to communicate. -Select the device **LoRaWAN version**. This should be provided with your device as the LoRaWAN version, LoRaWAN specification, or MAC version. - -{{< warning >}} -Choosing the incorrect LoRaWAN version can lead to complex errors. Activation may work, but the device will not be able to communicate consistently. If you are unsure about the LoRaWAN version you have selected, watch the [event log]({{< ref "the-things-stack/management/events" >}}) for errors! -{{}} - -Choose the **Regional Parameters version** provided by the manufacturer of your device. This should be specified in the data sheet as Regional Parameters or PHY version. - -{{< figure src="manual.png" alt="Manually create end device" >}} - -If you need to use a method of activation other than OTAA, create a multicast group, specify a Class B or Class C device, or change Rx Delay and Frequency plan settings, see the [Advanced settings](#advanced-settings) section below. Otherwise, skip the next section and continue with filling in the **Provisioning information**. - -The information that you'll be providing in the **Provisioning information** section depends on the activation method you've chosen. If you choose **OTAA**, follow the [OTAA Devices]({{< ref "/devices/adding-devices#otaa-devices" >}}) subsection, and if you choose **ABP**, follow the [ABP Devices]({{< ref "/devices/adding-devices#abp-devices" >}}) subsection. - -### Advanced settings - -To modify advanced settings, expand the **Show advanced activation, LoRaWAN class and cluster settings** dropdown. - -Here, you may choose your **Activation mode**. If you choose **OTAA**, follow the [OTAA Devices]({{< ref "/devices/adding-devices#otaa-devices" >}}) subsection after this one, and if you choose **ABP**, follow the [ABP Devices]({{< ref "/devices/adding-devices#abp-devices" >}}) subsection. - -If your device supports **Class B** or **Class C** features, you may enable them using the dropdown **Additional LoRaWAN class capabilities**. - -Under **Network defaults**, you can choose to **Use network's default MAC settings**. This option is enabled by default because for most deployments, {{% tts %}} defaults for Rx delay and other MAC settings will be suitable. However, if you want to modify **Rx2 data rate** or **Rx2 frequency**, uncheck this option and provide your custom values. If using [ABP activation mode](#abp-devices), this will also allow you to configure **Rx1 data rate offset**, **Rx1 delay**, **Factory preset frequencies** and to reset frame counters. - -{{< note >}} There are lots of additional options here that aren't mentioned for the sake of keeping this section concise. If you want to learn more about them, see the [MAC Settings]({{< ref "/devices/mac-settings" >}}) section and/or hover over the tooltip icons on the respective inputs. {{}} - -You can also choose to **Skip registration on Join Server** for testing purposes. We advise not to check this option unless you're an expert. - -### OTAA devices - -Over-the-Air-Activation (OTAA) is the secure, scalable way to activate LoRaWAN devices. All commercially available LoRaWAN devices support OTAA, and it is selected by default. If you are using a custom or DIY device, and cannot use OTAA, see the [Activation by Personalisation](#abp-devices) section. - -The example in this guide covers adding a device using [OTAA]({{< ref "reference/glossary#over-the-air-activation" >}}) (the most secure and preferred activation method) and [LoRaWAN version]({{< ref "reference/glossary#lorawan-version" >}}) MAC V1.0.2 (the most common LoRaWAN version, although newer versions are better and more secure) and RP001 Regional Parameters 1.0.2 revision B. Names and keys may vary slightly for other versions, but the process is the same and any differences are noted. - -First, enter a **JoinEUI/AppEUI** if provided by your manufacturer. If it is not provided by the manufacturer and your device is programmable, you can generate a random one in accordance with the test ranges defined by the [IEEE 802 standards](https://ieee802.org/) or use all zeros, just make sure to program the same value into your device. Then click **Confirm**. - -Enter your **DevEUI**. This should be provided by your manufacturer for commercial devices. If your device is programmable, you may generate an EUI using the **Generate** button, and program it in your device. - -{{< note >}} Note that the **JoinEUI** and **DevEUI** fields will be pre-filled if you scanned your device's QR code as explained in [Onboarding Devices using QR Codes]({{< ref "/devices/adding-devices#onboarding-devices-using-qr-codes" >}}) section. {{}} - -If your manufacturer provides an **AppKey**, enter it. Otherwise, use the **Generate** button to create one, and program it into your device. - -Give your device a unique **End device ID**. See [ID and EUI constraints]({{< ref "reference/id-eui-constraints" >}}) for guidelines about choosing a unique ID. - -{{< figure src="manual-network-settings-otaa.png" alt="Manually create OTAA end device" >}} - -Click **Register end device** to create the end device. - -### ABP devices - -If your device cannot be activated using the more secure OTAA, you may manually activate it by programming security keys it, i.e. using ABP. - -In the **Advanced settings** dropdown (see the [Advanced Settings section]({{< ref "/devices/adding-devices#advanced-settings" >}})), select **Activation by Personalization (ABP)**. - -When using ABP, it is important to make sure that the Rx1 settings in your device match those in {{% tts %}}. Uncheck **Use network's Rx and frequency defaults** to specify settings that match those in your device. {{% tts %}} recommends an Rx1 delay of `5` seconds, but this value would have to also be programmed into your device. - -Now proceed with **Provisioning information**. Enter a **JoinEUI/AppEUI** if provided by your manufacturer. If it is not provided by the manufacturer and your device is programmable, you can generate a random one in accordance with the test ranges defined by the [IEEE 802 standards](https://ieee802.org/) or use all zeros, just make sure to program the same value into your device. Then click **Confirm**. - -Enter your **DevEUI**. This should be provided by your manufacturer for commercial devices. If your device is programmable, you may generate an EUI using the **Generate** button, and program it in your device. - -Use the **Generate** button to create a **Device address**, and program it in your device. - -For LoRaWAN versions 1.0.x, generate an **AppSKey** and **NwkSKey** and program them in your device. - -For LoRaWAN versions 1.1.x, generate an **AppSKey**, **FNwkSIntKey**, **SNwkSIntKey**, and **NwkSEncKey**, and program them in your device. - -Finally, give your device a unique **End device ID**. See [ID and EUI constraints]({{< ref "reference/id-eui-constraints" >}}) for guidelines about choosing a unique ID. - -{{< figure src="manual-network-settings-abp.png" alt="Manually create OTAA end device" >}} - -Click **Register end device** to create the end device. +{{< figure src="fp.png" alt="Choosing a frequency plan" >}} {{< /tabs/tab >}} -{{< tabs/tab "CLI" >}} - -## Adding devices using the CLI - -First, list the available frequency plans and LoRaWAN versions: - -```bash -ttn-lw-cli end-devices list-frequency-plans -ttn-lw-cli end-devices create --help -``` - -### Over-The-Air-Activation (OTAA) device - -We define some user parameters that will be used below: - -```bash -APP_ID="app1" -DEVICE_ID="dev1" -FREQUENCY_PLAN="EU_863_870" -DEV_EUI="0004A30B001C0530" -APP_EUI="800000000000000C" -APP_KEY="752BAEC23EAE7964AF27C325F4C23C9A" -``` - -Make sure to modify these according to your setup. - -**LoRaWAN 1.0.x:** - -To create an end device using over-the-air-activation (OTAA): - -```bash -ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ - --dev-eui $DEV_EUI \ - --app-eui $APP_EUI \ - --frequency-plan-id $FREQUENCY_PLAN \ - --root-keys.app-key.key $APP_KEY \ - --lorawan-version 1.0.3 \ - --lorawan-phy-version 1.0.3-a -``` - -This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.0.3 MAC version and 1.0.3-a PHY versions. Make sure to replace the LoRaWAN MAC and PHY versions according to your setup. - -Please note that the `AppEUI` is returned as `join_eui` ({{% tts %}} uses LoRaWAN 1.1 terminology). - -If your device does not have a JoinEUI, you can use the default Join EUI of the Join Server. To use this, leave the `--join-eui`/`--app-eui` field empty. The CLI will contact the Join Server and get its default. - -If your device does not have a DevEUI, set the `--request-dev-eui` flag. The CLI will contact the server and fetch a DevEUI. - -{{< warning >}} -You must either use the value DevEUI/JoinEUI that's allotted to your device or let the server define these values as described above. Do not use `0000000000000000` or other randomly generated values as this is not LoRaWAN compliant and your devices will not be interoperable with other networks in the LoRaWAN ecosystem. -{{}} - -You can also pass `--with-root-keys` to have root keys generated. In this case, you do not need to specify `--root-keys.app-key.key`. - -The end device should now be able to join the private network. - -**LoRaWAN 1.1.x:** - -To create an end device using over-the-air-activation (OTAA): - -```bash -NWK_KEY="01020304050607080102030405060708" -ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ - --dev-eui $DEV_EUI \ - --app-eui $APP_EUI \ - --frequency-plan-id $FREQUENCY_PLAN \ - --root-keys.app-key.key $APP_KEY \ - --root-keys.nwk-key.key $NWK_KEY \ - --lorawan-version 1.1.0 \ - --lorawan-phy-version 1.1.0-b -``` - -This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.1.0 MAC and 1.1.0-b PHY versions. Make sure you replace these versions according to your setup. - -You can also pass `--with-root-keys` to have root keys generated. In this case, you do not need to specify `--root-keys.app-key.key` or `root-keys.nwk-key.key`. - -The end device should now be able to join the private network. - -### Activation By Personalization (ABP) device - -For adding ABP devices, we can define the following parameters: +{{< tabs/tab "Without QR Code" >}} -```bash -APP_ID="app1" -DEVICE_ID="dev1" -FREQUENCY_PLAN="EU_863_870" -DEV_ADDR="00E4304D" -APP_SESSION_KEY="A0CAD5A30036DBE03096EB67CA975BAA" -NWK_SESSION_KEY="B7F3E161BC9D4388E6C788A0C547F255" -``` +#### Onboarding devices without QR codes -Make sure you modify these according to your setup. +If your device doesn't have a standard [TR005 LoRaWAN® Device Identification QR Code](https://lora-alliance.org/resource_hub/tr005-lorawan-device-identification-qr-codes/), or has a vendor specific QR code, then the device identification and keys have to be entered manually. -**LoRaWAN 1.0.x:** +First choose the **Select the end device in the LoRaWAN Device Repository** input method. Then, select the **End device brand**, **Model**, **Hardware Version**, **Software Version**, and **Profile (Region)** for your device. -It is also possible to register an ABP activated device using the `--abp` flag as follows: +{{< figure src="select-dr-non-qr.png" alt="Creating a new device with the Device Repository" >}} -```bash -ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ - --frequency-plan-id $FREQUENCY_PLAN \ - --lorawan-version 1.0.3 \ - --lorawan-phy-version 1.0.3-a \ - --abp \ - --session.dev-addr $DEV_ADDR \ - --session.keys.app-s-key.key $APP_SESSION_KEY \ - --session.keys.nwk-s-key.key $NWK_SESSION_KEY -``` +Choose a **Frequency plan** appropriate for your region. Your device and gateway must use the same [frequency plan]({{< ref "/reference/frequency-plans/" >}}) to communicate. This example uses `Europe 863-870 MHz (SF9 for RX2 - recommended)`. -This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.0.3 MAC and 1.0.3-a PHY versions. Make sure you replace these versions according to your setup. +{{< figure src="fp-non-qr.png" alt="Choosing a frequency plan" >}} -Please note that the `NwkSKey` is returned as `f_nwk_s_int_key` ({{% tts %}} uses LoRaWAN 1.1 terminology). - -You can also pass `--with-session` to have a session generated. - -**LoRaWAN 1.1.x:** - -To register a LoRaWAN 1.1.x end device using ABP: - -```bash -F_NWK_SESSION_INT_KEY="01020304050607080102030405060708" -S_NWK_SESSION_INT_KEY="01020304050607080102030405060708" -NWK_SESSION_ENC_KEY="01020304050607080102030405060708" -ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ - --frequency-plan-id $FREQUENCY_PLAN \ - --lorawan-version 1.1.0 \ - --lorawan-phy-version 1.1.0-b \ - --abp \ - --session.dev-addr $DEV_ADDR \ - --session.keys.app-s-key.key $APP_SESSION_KEY \ - --session.keys.nwk-s-key.key $NWK_SESSION_KEY - --session.keys.f-nwk-s-int-key.key $F_NWK_SESSION_INT_KEY \ - --session.keys.s-nwk-s-int-key.key $S_NWK_SESSION_INT_KEY \ - --session.keys.nwk-s-enc-key.key $NWK_SESSION_ENC_KEY -``` - -This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.1.0 MAC and 1.1.0-b PHY versions. Make sure you replace these versions according to your setup. - -You can also pass `--with-session` to have a session generated. - -{{< /tabs/tab >}} - -{{< /tabs/container >}} - -## Adding devices in bulk - -It is also possible to import end devices in bulk. - -Devices' descriptions need to be in a [JSON]({{< ref "/the-things-stack/migrating/device-json" >}}) or [CSV]({{< ref "/the-things-stack/migrating/device-csv" >}}) format. See [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}) section for instructions on how to import devices in bulk using these files. - -See the following video from [The Things Network youtube channel](https://youtu.be/ouz-VuiosU4) for instructions. - -
Show video -{{< youtube "ouz-VuiosU4" >}} -
- -## Set device location - -{{< tabs/container "Console" "CLI" >}} - -{{< tabs/tab "Console" >}} - -Once you have added your end device to {{% tts %}}, you can also set its location to be displayed on a map widget by clicking **Change location settings**. +Enter a **JoinEUI/AppEUI** if provided by your manufacturer and click **Confirm**. If it is not provided by the manufacturer and your device is programmable, you can generate a random one in accordance with the test ranges defined by the [IEEE 802 standards](https://ieee802.org/) or use all zeros, just make sure to program the same value into your device. -The end device location can be manually set by pinning on the map widget, or entering the **Latitude**, **Longitude** and **Altitude** values. +{{< figure src="non-qr-join-eui.png" alt="Set the Join EUI" >}} -{{< figure src="device-location.png" alt="Gateway location" >}} +Now enter your **DevEUI**. This should be provided by your manufacturer for commercial devices. If your device is programmable, you may generate an EUI using the **Generate** button, and program it in your device. -{{< /tabs/tab >}} +For LoRaWAN version 1.0.x devices, you will see an **AppKey** field, and for LoRaWAN version 1.1.x devices you will also see a **NwkKey** field. If these keys are provided by your manufacturer, enter them. Otherwise, use the **Generate** button to create them, and program them into your device. -{{< tabs/tab "CLI" >}} - -Once you have added your end device to {{% tts %}}, you can also set its location. - -Set your end device's location with: - -```bash -LAT="43.84" -LONG="18.32" -ALT="500" -ttn-lw-cli end-devices set $APP_ID $DEVICE_ID \ - --location.latitude $LAT \ - --location.longitude $LONG \ - --location.altitude $ALT \ -``` - -You can also set the end device location to be updated from various sources with the `--location.source` flag. - -The source of the location data can be the registry, GPS data, results of the LoRa RSSI geolocation, etc. Use `ttn-lw-cli end-devices set $APP_ID $DEVICE_ID --help` command to see the full list of the available location sources and other relatable info. If you set the alternative location source, the location settings you manually set will be overwritten by the automatic updates from that source. - -The CLI will return something like: - -```json -{ - "ids": { - "device_id": "dev1", - "application_ids": { - "application_id": "app1" - }, - "dev_eui": "0004A30B001C0530", - "join_eui": "800000000000000C" - }, - "created_at": "2020-05-27T15:50:38.567Z", - "updated_at": "2020-12-25T11:16:20.592Z", - "locations": { - "user": { - "latitude": 43.84, - "longitude": 18.32, - "altitude": 500, - "source": "SOURCE_REGISTRY" - } - } -} - -``` +{{< figure src="non-qr-all-set.png" alt="Set the Device EUI and Device Keys" >}} {{< /tabs/tab >}} {{< /tabs/container >}} -## Application layer settings - -### Payload crypto override - -LoRaWAN frames are encrypted on the application layer using the AppSKey. Once the end device is registered, you can choose to enforce or skip payload encryption. Skipping payload encryption will cause the Application Server to forward messages to integrations without any processing, for example it will neglect [payload formatters]({{< ref "/integrations/payload-formatters" >}}). If you choose to skip payload encryption, integrations will be responsible for processing the message in order to understand it. - -To configure these settings, navigate to your end device's **General settings** tab in the Console and scroll down to the **Application layer** section. - -Skipping payload encryption and decryption option is also available on an [application level]({{< ref "/integrations/adding-applications#payload-encryption-and-decryption" >}}), so if you want the end device to inherit this setting from its application, choose **Use application default**. +Finally, the console pre-fills **End device ID** in the format `eui-{Device EUI}` by default. You can edit this field and give the device a unique identifier. See [ID and EUI constraints]({{< ref "reference/id-eui-constraints" >}}) for guidelines about choosing a unique ID. -Otherwise, choose to **Enforce skipping payload crypto** or to **Enforce payload crypto** for a single device only. +Now verify that all the fields are filled and click the **Register end device** button to create the end device. -{{< figure src="skip-payload-crypto.png" alt="Skip payload encryption and decryption" >}} +The device is now registered, and will appear as connected in {{% tts %}} once it sends an uplink. diff --git a/doc/content/the-things-stack/migrating/import-devices.md b/doc/content/devices/adding-devices/adding-devices-in-bulk/_index.md similarity index 66% rename from doc/content/the-things-stack/migrating/import-devices.md rename to doc/content/devices/adding-devices/adding-devices-in-bulk/_index.md index d2ee222723..b0f1f3fb46 100644 --- a/doc/content/the-things-stack/migrating/import-devices.md +++ b/doc/content/devices/adding-devices/adding-devices-in-bulk/_index.md @@ -1,17 +1,29 @@ --- -title: Import End Devices in The Things Stack -weight: 4 -aliases: [/getting-started/migrating-from-v2/import-devices, /getting-started/migrating-from-networks/import-devices, /the-things-stack/migrating-from-v2/import-devices, /the-things-stack/migrating-from-networks/import-devices,/getting-started/migrating, /getting-started/migrating/import-devices] +title: "Adding devices in bulk" +description: "" +weight: 3 +aliases: + [ + /getting-started/migrating-from-v2/import-devices, + /getting-started/migrating-from-networks/import-devices, + /the-things-stack/migrating-from-v2/import-devices, + /the-things-stack/migrating-from-networks/import-devices, + /getting-started/migrating, + /getting-started/migrating/import-devices, + /devices/adding-devices/adding-devices-in-bulk, + ] --- -To import end devices, you need access to an application in {{% tts %}}. If you have not created one previously, see the [Adding Applications]({{< ref "integrations/adding-applications" >}}) guide for detailed instructions. +Instead of adding devices one by one, {{% tts %}} supports multiple methods of adding multiple end devices at once. Adding multiple devices is also referred to as **importing devices**. + + There are two ways to import devices in {{% tts %}} - using [Console]({{< ref "/the-things-stack/interact/console" >}}) or [CLI]({{< ref "/the-things-stack/interact/cli" >}}). {{% tts %}} supports importing end devices in JSON and CSV format: -- To import devices that are in a JSON file (for example, the one you created by following [Migrating End Devices from {{% ttnv2 %}}]({{< ref "/the-things-stack/migrating/migrating-from-v2" >}}) or [Exporting Devices from ChirpStack]({{< ref "/the-things-stack/migrating/migration-tool/export-from-chirpstack" >}})), use **{{% tts %}} JSON** format (identified by `the-things-stack`). The JSON format data format is documented in the [JSON File Reference]({{< ref "/the-things-stack/migrating/device-json" >}}). -- To import devices that are in a CSV file, use the **{{% tts %}} CSV** (identified by `the-things-stack-csv`). The CSV data format is documented in the [CSV File Reference]({{< ref "/the-things-stack/migrating/device-csv" >}}), including a handy Excel template. +- To import devices that are in a JSON file (for example, the one you created by following [Migrating End Devices from {{% ttnv2 %}}]({{< ref "/the-things-stack/migrating/migrating-from-v2" >}}) or [Exporting Devices from ChirpStack]({{< ref "/the-things-stack/migrating/migration-tool/export-from-chirpstack" >}})), use **{{% tts %}} JSON** format (identified by `the-things-stack`). The JSON format data format is documented in the [JSON File Reference]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-json" >}}). +- To import devices that are in a CSV file, use the **{{% tts %}} CSV** (identified by `the-things-stack-csv`). The CSV data format is documented in the [CSV File Reference]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-csv" >}}), including a handy Excel template. {{< tabs/container "Console" "CLI" >}} @@ -21,7 +33,7 @@ There are two ways to import devices in {{% tts %}} - using [Console]({{< ref "/ Open your application and click the button **Import end devices** -{{< figure src="../import-end-devices.png" alt="import devices" >}} +{{< figure src="import-end-devices.png" alt="import devices" >}} Select the **File format** and upload the file (e.g. `devices.json` or `devices.csv`). @@ -31,11 +43,11 @@ You can also expand the **Advanced claiming and component settings** to set targ Start the import by clicking the **Import end devices** button. -{{< figure src="../upload-file.png" alt="upload devices.json file" >}} +{{< figure src="upload-file.png" alt="upload devices.json file" >}} Wait for the end devices to be successfully imported. In case any device fails, you will see a relevant error message in the console. -{{< figure src="../operation-finished.png" alt="import finished" >}} +{{< figure src="operation-finished.png" alt="import finished" >}} If the import was successful, your devices are added to the list of end devices in your application. @@ -68,8 +80,10 @@ If the import was successful, you will see your devices added to the list of end {{< /tabs/container >}} -{{< figure src="../successful-import.png" alt="successful-import" >}} +{{< figure src="successful-import.png" alt="successful-import" >}} -Your devices are now registered on {{% tts %}}. +See the following video from [The Things Network youtube channel](https://youtu.be/ouz-VuiosU4) for instructions. -Keep in mind that you still might need to initiate a new join on {{% tts %}} network! See [Migrating End Devices from {{% ttnv2 %}}]({{< ref "/the-things-stack/migrating/migrating-from-v2" >}}) for detailed info on how to complete the migration of your devices. +
Show video +{{< youtube "ouz-VuiosU4" >}} +
diff --git a/doc/content/devices/adding-devices/adding-devices-in-bulk/device-csv.md b/doc/content/devices/adding-devices/adding-devices-in-bulk/device-csv.md new file mode 100644 index 0000000000..fe5e5ce309 --- /dev/null +++ b/doc/content/devices/adding-devices/adding-devices-in-bulk/device-csv.md @@ -0,0 +1,78 @@ +--- +title: "CSV File Reference" +description: "" +weight: 9 +aliases: [/getting-started/device-csv, /getting-started/migrating/device-csv] +--- + +{{% tts %}} has support for importing end devices from CSV (comma-separated values) files. + + + +This method is useful when batches of end devices are managed in Microsoft Excel or any other spreadsheet or database that can export to CSV file. + +The CSV import in {{% tts %}} uses the following settings: + +- Semicolon (`;`) as field delimiter. This makes working with Microsoft Excel and other spreadsheets convenient +- Header row is required +- On each row, the same number of fields as on the header line +- Use quotes to use `;` in a field value +- Use double quotes to escape quotes +- Unknown header columns are permitted and ignored + +The following columns are recognized: + +| Column | Required | Alias | Format | Meaning | +| ----------------------- | ------------------------ | --------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dev_eui` | **Yes** | | Hexadecimal string | LoRaWAN® DevEUI | +| `join_eui` | **Yes** | `app_eui` | Hexadecimal string | LoRaWAN JoinEUI (or AppEUI) | +| `id` | No | | Alphanumeric string, lowercase with hyphens | Device ID (falls back to DevEUI if not set) | +| `name` | No | | Free form | Name | +| `description` | No | | string | Optional, description of the device | +| `lorawan_version` | No \* | | See [`MACVersion`]({{< ref "/reference/api/end_device#enum:MACVersion" >}}) | LoRaWAN version | +| `lorawan_phy_version` | No \* | | See [`PHYVersion`]({{< ref "/reference/api/end_device#enum:PHYVersion" >}}) | LoRaWAN Regional Parameters version | +| `frequency_plan_id` | No \* | | See [Frequency Plans]({{< ref "/reference/frequency-plans" >}}) | Frequency plan ID | +| `brand_id` | No | | Vendor ID string from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Device brand ID | +| `model_id` | No | | Model ID from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Device model ID | +| `firmware_version` | No | | Firmware version from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Firmware version | +| `hardware_version` | No | | Hardware version from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Hardware version | +| `band_id` | No | | See [Frequency Plans]({{< ref "/reference/frequency-plans" >}}) | LoRaWAN Band ID | +| `supports_class_c` | No | | boolean | `true` for Class C devices, `false` otherwise. | +| `app_key` | **Yes** | | Hexadecimal string | LoRaWAN AppKey | +| `nwk_key` | No | | Hexadecimal string | LoRaWAN NwkKey | +| `rx1_delay` | No | | string | 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]({{< ref "reference/api/end_device#message:MACSettings" >}}) for more information. | +| `supports_32_bit_f_cnt` | No | | boolean | `true` if device supports 32-bit frame counters, `false` if device only supports 16-bit frame counters. | +| `dev_addr` | **For existing session** | | Hexadecimal string | **Needed for ABP devices or when migrating OTAA devices with an existing session**. See [Device Address]({{< ref "/reference/glossary#device-address" >}}) for more information. | +| `app_s_key` | **For existing session** | | string | **Needed for ABP devices or when migrating OTAA devices with an existing session**. See [Application Session Key]({{< ref "reference/glossary#application-session-key" >}}) for more information. | +| `f_nwk_s_int_key` | **For existing session** | | string | Forwarding Network Session Integrity Key, also referred to as **Network Session Key** in LoRaWAN v1.0.x compatibility mode. See [SessionKeys]({{< ref "reference/api/end_device#message:SessionKeys" >}}) and [Forwarding Network Session Integrity Key]({{< ref "/reference/glossary#forwarding-network-session-integrity-key" >}}) for more information. | +| `last_f_cnt_up` | **For existing session** | | uint | Last uplink frame counter used. | +| `last_n_f_cnt_down` | **For existing session** | | uint | Last network downlink frame counter used. | +| `last_a_f_cnt_down` | **For existing session** | | uint | Last application downlink frame counter used. | + +\* If you don't set this, you must set the fallback value when importing the CSV file. See [Importing devices]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). + +## Example + +Minimal example: + +```csv +dev_eui;join_eui;frequency_plan_id;lorawan_version;lorawan_phy_version;app_key +1111111111111111;1111111111111111;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;11111111111111111111111111111111 +2222222222222222;2222222222222222;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;22222222222222222222222222222222 +3333333333333333;3333333333333333;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;33333333333333333333333333333333 +``` + +All columns for a LoRaWAN 1.0.4 device: + +```csv +id;dev_eui;join_eui;name;frequency_plan_id;lorawan_version;lorawan_phy_version;brand_id;model_id;hardware_version;firmware_version;band_id;app_key +test-one;1111111111111111;1111111111111111;Device 1;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;the-things-industries;generic-node-sensor-edition;1.0.4;1.0;EU_863_870;11111111111111111111111111111111 +test-two;2222222222222222;2222222222222222;Device 2;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;the-things-industries;generic-node-sensor-edition;1.0.4;1.0;EU_863_870;22222222222222222222222222222222 +test-three;3333333333333333;3333333333333333;Device 3;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;the-things-industries;generic-node-sensor-edition;1.0.4;1.0;EU_863_870;33333333333333333333333333333333 +``` + +## Excel Template + +[Download the Excel template](../tts-end-devices-csv-template.xlsx). You can remove all columns that are not required (see above). + +To export for {{% tts %}}, go to **File**, **Save As** and select **Comma Separated Values** as file format. diff --git a/doc/content/devices/adding-devices/adding-devices-in-bulk/device-json.md b/doc/content/devices/adding-devices/adding-devices-in-bulk/device-json.md new file mode 100644 index 0000000000..be5b8a51f6 --- /dev/null +++ b/doc/content/devices/adding-devices/adding-devices-in-bulk/device-json.md @@ -0,0 +1,99 @@ +--- +title: "JSON File Reference" +description: "" +weight: 8 +aliases: + [ + /the-things-stack/migrating-from-networks/device-json, + /getting-started/migrating/device-json, + ] +--- + +{{% tts %}} has support for importing end devices from JSON files. + + + +This method is useful when batches of end devices are managed as JSON files or to add end devices in bulk from {{% ttnv2 %}}, 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: + +```json +{ + "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: + +```js +{ + /* 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 [Adding End Devices in Bulk]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). + +## JSON End Device Format + +The full specification of the JSON format is defined in the API protos. See the [EndDevice]({{< ref "/reference/api/end_device#message: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]({{< ref "reference/glossary#device-id" >}}) | +| **`ids.dev_eui`** | **Always** | string | `"0102030405060708"` | [More info]({{< ref "reference/glossary#deveui" >}}) | +| **`ids.join_eui`** | **Always** | string | `"0102030405060708"` | Also referred to as **AppEUI**. [More info]({{< ref "reference/glossary#joineui" >}}) | +| **`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]({{< ref "reference/api/end_device#enum:MACVersion" >}}) for supported versions. See [LoRaWAN Version]({{< ref "reference/glossary#lorawan-version" >}}) for more information. | +| **`lorawan_phy_version`** | **Always** | string | `"PHY_V1_0_2_REV_B"` | See [PHYVersion]({{< ref "reference/api/end_device#enum:PHYVersion" >}}) for supported versions. See [LoRaWAN Version]({{< ref "reference/glossary#regional-parameters" >}}) for more information. | +| **`frequency_plan_id`** | **Always** | string | `"EU_863_870_TTN"` | See [Frequency Plans]({{< ref "reference/frequency-plans" >}}) for a list of supported frequency plans (The frequency plan `ID` is needed). See [Frequency Plan]({{< ref "reference/glossary#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]({{< ref "reference/glossary#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]({{< ref "reference/glossary#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]({{< ref "reference/api/end_device#message: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]({{< ref "/reference/glossary#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]({{< ref "reference/glossary#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]({{< ref "reference/api/end_device#message:SessionKeys" >}}) and [Forwarding Network Session Integrity Key]({{< ref "/reference/glossary#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": "" + } +} +``` diff --git a/doc/content/the-things-stack/migrating/import-end-devices.png b/doc/content/devices/adding-devices/adding-devices-in-bulk/import-end-devices.png similarity index 100% rename from doc/content/the-things-stack/migrating/import-end-devices.png rename to doc/content/devices/adding-devices/adding-devices-in-bulk/import-end-devices.png diff --git a/doc/content/the-things-stack/migrating/operation-finished.png b/doc/content/devices/adding-devices/adding-devices-in-bulk/operation-finished.png similarity index 100% rename from doc/content/the-things-stack/migrating/operation-finished.png rename to doc/content/devices/adding-devices/adding-devices-in-bulk/operation-finished.png diff --git a/doc/content/the-things-stack/migrating/successful-import copy.png b/doc/content/devices/adding-devices/adding-devices-in-bulk/successful-import copy.png similarity index 100% rename from doc/content/the-things-stack/migrating/successful-import copy.png rename to doc/content/devices/adding-devices/adding-devices-in-bulk/successful-import copy.png diff --git a/doc/content/the-things-stack/migrating/successful-import.png b/doc/content/devices/adding-devices/adding-devices-in-bulk/successful-import.png similarity index 100% rename from doc/content/the-things-stack/migrating/successful-import.png rename to doc/content/devices/adding-devices/adding-devices-in-bulk/successful-import.png diff --git a/doc/content/the-things-stack/migrating/tts-end-devices-csv-template.xlsx b/doc/content/devices/adding-devices/adding-devices-in-bulk/tts-end-devices-csv-template.xlsx similarity index 100% rename from doc/content/the-things-stack/migrating/tts-end-devices-csv-template.xlsx rename to doc/content/devices/adding-devices/adding-devices-in-bulk/tts-end-devices-csv-template.xlsx diff --git a/doc/content/the-things-stack/migrating/upload-file.png b/doc/content/devices/adding-devices/adding-devices-in-bulk/upload-file.png similarity index 100% rename from doc/content/the-things-stack/migrating/upload-file.png rename to doc/content/devices/adding-devices/adding-devices-in-bulk/upload-file.png diff --git a/doc/content/devices/adding-devices/adding-devices-options.png b/doc/content/devices/adding-devices/adding-devices-options.png deleted file mode 100644 index 51c6f42b4d..0000000000 Binary files a/doc/content/devices/adding-devices/adding-devices-options.png and /dev/null differ diff --git a/doc/content/devices/adding-devices/application-overview.png b/doc/content/devices/adding-devices/application-overview.png index 335f18f0ca..0edf055368 100644 Binary files a/doc/content/devices/adding-devices/application-overview.png and b/doc/content/devices/adding-devices/application-overview.png differ diff --git a/doc/content/devices/atecc608a/_index.md b/doc/content/devices/adding-devices/atecc608a/_index.md similarity index 89% rename from doc/content/devices/atecc608a/_index.md rename to doc/content/devices/adding-devices/atecc608a/_index.md index 6ac3ce51df..9c8e3fa2c3 100644 --- a/doc/content/devices/atecc608a/_index.md +++ b/doc/content/devices/adding-devices/atecc608a/_index.md @@ -1,6 +1,7 @@ --- -title: "ATECC608 Secure Elements" +title: "Adding devices with ATECC608 Secure Elements" description: "" +aliases: ["/devices/atecc608a"] --- The Things Industries and Microchip developed a security solution for LoRaWAN® that enables secure key provisioning and secure cryptographic operations using secure elements. diff --git a/doc/content/devices/atecc608a/claim.md b/doc/content/devices/adding-devices/atecc608a/claim.md similarity index 94% rename from doc/content/devices/atecc608a/claim.md rename to doc/content/devices/adding-devices/atecc608a/claim.md index 7a8c3e0f91..12222f917f 100644 --- a/doc/content/devices/atecc608a/claim.md +++ b/doc/content/devices/adding-devices/atecc608a/claim.md @@ -56,14 +56,14 @@ This provisions the secure elements in The Things Join Server and returns the ge ```js [ { - devEUI: '0004A310001AAED6', - ownerToken: 'C05EA29C', - rootKeysExposed: false - } -] + devEUI: "0004A310001AAED6", + ownerToken: "C05EA29C", + rootKeysExposed: false, + }, +]; ``` -The owner token is called claim authentication code in {{% tts %}}. This is the proof of ownership for claiming devices. See [Device Claiming]({{< ref "/devices/device-claiming" >}}) for more information. +The owner token is called claim authentication code in {{% tts %}}. This is the proof of ownership for claiming devices. See [Device Claiming]({{< ref "/devices/concepts/device-claiming" >}}) for more information. ## Export root keys diff --git a/doc/content/devices/adding-devices/device-id.png b/doc/content/devices/adding-devices/device-id.png new file mode 100644 index 0000000000..3522178d61 Binary files /dev/null and b/doc/content/devices/adding-devices/device-id.png differ diff --git a/doc/content/devices/adding-devices/device-repo.png b/doc/content/devices/adding-devices/device-repo.png index 3fef4d0e7b..f194b69c84 100644 Binary files a/doc/content/devices/adding-devices/device-repo.png and b/doc/content/devices/adding-devices/device-repo.png differ diff --git a/doc/content/devices/adding-devices/fp-non-qr.png b/doc/content/devices/adding-devices/fp-non-qr.png new file mode 100644 index 0000000000..f6d33816cb Binary files /dev/null and b/doc/content/devices/adding-devices/fp-non-qr.png differ diff --git a/doc/content/devices/adding-devices/fp.png b/doc/content/devices/adding-devices/fp.png new file mode 100644 index 0000000000..d69d641753 Binary files /dev/null and b/doc/content/devices/adding-devices/fp.png differ diff --git a/doc/content/devices/adding-devices/manual/_index.md b/doc/content/devices/adding-devices/manual/_index.md new file mode 100644 index 0000000000..da06f4178d --- /dev/null +++ b/doc/content/devices/adding-devices/manual/_index.md @@ -0,0 +1,29 @@ +--- +title: "Manually adding devices" +description: "" +weight: 1 +aliases: +--- + +If your devices are not yet part of the [LoRaWAN® Device Repository](https://github.com/TheThingsNetwork/lorawan-devices/) or you want to set advanced fields, you can add devices manually in {{% tts %}}. + + + +This guide lists the common fields required for registering OTAA and ABP devices via the console. If you want to use the CLI, go to the OTAA/ABP guide at the bottom of the page. + +Choose the **Enter end device specifics manually** input method. Please refer to your device's datasheet to ensure entering the following information correctly. + +Choose the **Enter end device specifics manually** option of the input method. + +Choose an appropriate **Frequency Plan**. Your device and gateway must use the same [frequency plan]({{< ref "/reference/frequency-plans/" >}}) to communicate. + +Select **LoRaWAN Version** and **Regional Parameters version** fields for your specific device. +These values are usually found in the end device documentation either on the vendor/manufacturer's website or on the data sheet. If this data is not available, check with the device vendor/manufacturer. + +{{< warning >}} +Choosing the incorrect LoRaWAN version can lead to complex errors. Activation may work, but the device will not be able to communicate consistently. If you are unsure about the LoRaWAN version you have selected, watch the [event log]({{< ref "the-things-stack/management/events" >}}) for errors! +{{}} + +{{< figure src="device-input-method.png" alt="ABP input method" >}} + +The above fields are common for both OTAA and ABP devices. Now, based on the device you are trying to add, choose the speficic guide for OTAA or ABP below. diff --git a/doc/content/devices/adding-devices/manual/abp/_index.md b/doc/content/devices/adding-devices/manual/abp/_index.md new file mode 100644 index 0000000000..bd25b3f552 --- /dev/null +++ b/doc/content/devices/adding-devices/manual/abp/_index.md @@ -0,0 +1,109 @@ +--- +title: "Activation by Personalization (ABP)" +description: "" +weight: 2 +--- + +If your device cannot be activated using the more secure OTAA, you may manually activate it by programming security keys it, i.e. using ABP. This guide explains how to add ABP devices manually. + + + +{{< tabs/container "Console" "CLI" >}} + +{{< tabs/tab "Console" >}} + +Click on the **Show advanced activation, LoRaWAN class and cluster settings** select **Activation by Personalization (ABP)**. + +Choose the appropriate **Additional LoRaWAN class capabilities**. When using ABP, it is important to make sure that the Rx1 settings in your device match those in {{% tts %}}. Uncheck **Network Defaults** to specify settings that match those in your device. {{% tts %}} recommends an Rx1 delay of `5` seconds, but this value would have to also be programmed into your device. + +{{< figure src="abp-network-defaults.png" alt="ABP Network Settings" >}} + +Now proceed with **Provisioning information**. Enter a **JoinEUI/AppEUI** if provided by your manufacturer. If it is not provided by the manufacturer and your device is programmable, you can generate a random one in accordance with the test ranges defined by the [IEEE 802 standards](https://ieee802.org/) or use all zeros, just make sure to program the same value into your device. Then click **Confirm**. + +Enter your **DevEUI**. This should be provided by your manufacturer for commercial devices. If your device is programmable, you may generate an EUI using the **Generate** button, and program it in your device. + +Use the **Generate** button to create a **Device address**, and program it in your device. + +For LoRaWAN versions 1.0.x, generate an **AppSKey** and **NwkSKey** and program them in your device. + +For LoRaWAN versions 1.1.x, generate an **AppSKey**, **FNwkSIntKey**, **SNwkSIntKey**, and **NwkSEncKey**, and program them in your device. + +Finally, give your device a unique **End device ID**. See [ID and EUI constraints]({{< ref "reference/id-eui-constraints" >}}) for guidelines about choosing a unique ID. + +{{< figure src="abp-fields-set.png" alt="ABP fields set" >}} + +Click **Register end device** to create the end device. + +{{< /tabs/tab >}} + +{{< tabs/tab "CLI" >}} + +First, list the available frequency plans and LoRaWAN versions: + +```bash +ttn-lw-cli end-devices list-frequency-plans +ttn-lw-cli end-devices create --help +``` + +For adding ABP devices, we can define the following parameters: + +```bash +APP_ID="app1" +DEVICE_ID="dev1" +FREQUENCY_PLAN="EU_863_870" +DEV_ADDR="00E4304D" +APP_SESSION_KEY="A0CAD5A30036DBE03096EB67CA975BAA" +NWK_SESSION_KEY="B7F3E161BC9D4388E6C788A0C547F255" +``` + +Make sure you modify these according to your setup. + +**LoRaWAN 1.0.x:** + +It is also possible to register an ABP activated device using the `--abp` flag as follows: + +```bash +ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ + --frequency-plan-id $FREQUENCY_PLAN \ + --lorawan-version 1.0.3 \ + --lorawan-phy-version 1.0.3-a \ + --abp \ + --session.dev-addr $DEV_ADDR \ + --session.keys.app-s-key.key $APP_SESSION_KEY \ + --session.keys.nwk-s-key.key $NWK_SESSION_KEY +``` + +This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.0.3 MAC and 1.0.3-a PHY versions. Make sure you replace these versions according to your setup. + +Please note that the `NwkSKey` is returned as `f_nwk_s_int_key` ({{% tts %}} uses LoRaWAN 1.1 terminology). + +You can also pass `--with-session` to have a session generated. + +**LoRaWAN 1.1.x:** + +To register a LoRaWAN 1.1.x end device using ABP: + +```bash +F_NWK_SESSION_INT_KEY="01020304050607080102030405060708" +S_NWK_SESSION_INT_KEY="01020304050607080102030405060708" +NWK_SESSION_ENC_KEY="01020304050607080102030405060708" +ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ + --frequency-plan-id $FREQUENCY_PLAN \ + --lorawan-version 1.1.0 \ + --lorawan-phy-version 1.1.0-b \ + --abp \ + --session.dev-addr $DEV_ADDR \ + --session.keys.app-s-key.key $APP_SESSION_KEY \ + --session.keys.nwk-s-key.key $NWK_SESSION_KEY + --session.keys.f-nwk-s-int-key.key $F_NWK_SESSION_INT_KEY \ + --session.keys.s-nwk-s-int-key.key $S_NWK_SESSION_INT_KEY \ + --session.keys.nwk-s-enc-key.key $NWK_SESSION_ENC_KEY +``` + +This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.1.0 MAC and 1.1.0-b PHY versions. Make sure you replace these versions according to your setup. + +You can also pass `--with-session` to have a session generated. + +{{< /tabs/tab >}} + +{{< /tabs/container >}} diff --git a/doc/content/devices/adding-devices/manual/abp/abp-fields-set.png b/doc/content/devices/adding-devices/manual/abp/abp-fields-set.png new file mode 100644 index 0000000000..094235c349 Binary files /dev/null and b/doc/content/devices/adding-devices/manual/abp/abp-fields-set.png differ diff --git a/doc/content/devices/adding-devices/manual/abp/abp-network-defaults.png b/doc/content/devices/adding-devices/manual/abp/abp-network-defaults.png new file mode 100644 index 0000000000..ddbf694990 Binary files /dev/null and b/doc/content/devices/adding-devices/manual/abp/abp-network-defaults.png differ diff --git a/doc/content/devices/adding-devices/manual/abp/abp-provisioning.png b/doc/content/devices/adding-devices/manual/abp/abp-provisioning.png new file mode 100644 index 0000000000..e4e7b93b64 Binary files /dev/null and b/doc/content/devices/adding-devices/manual/abp/abp-provisioning.png differ diff --git a/doc/content/devices/adding-devices/manual-network-settings-abp.png b/doc/content/devices/adding-devices/manual/abp/manual-network-settings-abp.png similarity index 100% rename from doc/content/devices/adding-devices/manual-network-settings-abp.png rename to doc/content/devices/adding-devices/manual/abp/manual-network-settings-abp.png diff --git a/doc/content/devices/adding-devices/manual/device-input-method.png b/doc/content/devices/adding-devices/manual/device-input-method.png new file mode 100644 index 0000000000..d2d457f22c Binary files /dev/null and b/doc/content/devices/adding-devices/manual/device-input-method.png differ diff --git a/doc/content/devices/adding-devices/manual.png b/doc/content/devices/adding-devices/manual/manual.png similarity index 100% rename from doc/content/devices/adding-devices/manual.png rename to doc/content/devices/adding-devices/manual/manual.png diff --git a/doc/content/devices/adding-devices/manual/otaa/_index.md b/doc/content/devices/adding-devices/manual/otaa/_index.md new file mode 100644 index 0000000000..69db82feb4 --- /dev/null +++ b/doc/content/devices/adding-devices/manual/otaa/_index.md @@ -0,0 +1,109 @@ +--- +title: "Over the Air Activation (OTAA)" +description: "" +weight: 1 +--- + +Over-the-Air-Activation (OTAA) is the secure, scalable way to activate LoRaWAN devices. All commercially available LoRaWAN devices support OTAA, and it is selected by default. This guide explains how to add OTAA devices manually. + + + +{{< tabs/container "Console" "CLI" >}} + +{{< tabs/tab "Console" >}} + +The example in this guide covers adding a device using [OTAA]({{< ref "reference/glossary#over-the-air-activation" >}}) (the most secure and preferred activation method) and [LoRaWAN version]({{< ref "reference/glossary#lorawan-version" >}}) MAC V1.0.2 (the most common LoRaWAN version, although newer versions are better and more secure) and RP001 Regional Parameters 1.0.2 revision B. Names and keys may vary slightly for other versions, but the process is the same and any differences are noted. + +First, enter a **JoinEUI/AppEUI** if provided by your manufacturer. If it is not provided by the manufacturer and your device is programmable, you can generate a random one in accordance with the test ranges defined by the [IEEE 802 standards](https://ieee802.org/) or use all zeros, just make sure to program the same value into your device. Then click **Confirm**. + +Enter your **DevEUI**. This should be provided by your manufacturer for commercial devices. If your device is programmable, you may generate an EUI using the **Generate** button, and program it in your device. + +{{< note >}} Note that the **JoinEUI** and **DevEUI** fields will be pre-filled if you scanned your device's QR code as explained in [Onboarding Devices using QR Codes]({{< ref "/devices/adding-devices#onboarding-devices-using-qr-codes" >}}) section. {{}} + +If your manufacturer provides an **AppKey**, enter it. Otherwise, use the **Generate** button to create one, and program it into your device. + +Give your device a unique **End device ID**. See [ID and EUI constraints]({{< ref "reference/id-eui-constraints" >}}) for guidelines about choosing a unique ID. + +{{< figure src="manual-network-settings-otaa.png" alt="Manually create OTAA end device" >}} + +Click **Register end device** to create the end device. + +{{< /tabs/tab >}} + +{{< tabs/tab "CLI" >}} + +First, list the available frequency plans and LoRaWAN versions: + +```bash +ttn-lw-cli end-devices list-frequency-plans +ttn-lw-cli end-devices create --help +``` + +We define some user parameters that will be used below: + +```bash +APP_ID="app1" +DEVICE_ID="dev1" +FREQUENCY_PLAN="EU_863_870" +DEV_EUI="0004A30B001C0530" +APP_EUI="800000000000000C" +APP_KEY="752BAEC23EAE7964AF27C325F4C23C9A" +``` + +Make sure to modify these according to your setup. + +**LoRaWAN 1.0.x:** + +To create an end device using over-the-air-activation (OTAA): + +```bash +ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ + --dev-eui $DEV_EUI \ + --app-eui $APP_EUI \ + --frequency-plan-id $FREQUENCY_PLAN \ + --root-keys.app-key.key $APP_KEY \ + --lorawan-version 1.0.3 \ + --lorawan-phy-version 1.0.3-a +``` + +This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.0.3 MAC version and 1.0.3-a PHY versions. Make sure to replace the LoRaWAN MAC and PHY versions according to your setup. + +Please note that the `AppEUI` is returned as `join_eui` ({{% tts %}} uses LoRaWAN 1.1 terminology). + +If your device does not have a JoinEUI, you can use the default Join EUI of the Join Server. To use this, leave the `--join-eui`/`--app-eui` field empty. The CLI will contact the Join Server and get its default. + +If your device does not have a DevEUI, set the `--request-dev-eui` flag. The CLI will contact the server and fetch a DevEUI. + +{{< warning >}} +You must either use the value DevEUI/JoinEUI that's allotted to your device or let the server define these values as described above. Do not use `0000000000000000` or other randomly generated values as this is not LoRaWAN compliant and your devices will not be interoperable with other networks in the LoRaWAN ecosystem. +{{}} + +You can also pass `--with-root-keys` to have root keys generated. In this case, you do not need to specify `--root-keys.app-key.key`. + +The end device should now be able to join the network. + +**LoRaWAN 1.1.x:** + +To create an end device using over-the-air-activation (OTAA): + +```bash +NWK_KEY="01020304050607080102030405060708" +ttn-lw-cli end-devices create $APP_ID $DEVICE_ID \ + --dev-eui $DEV_EUI \ + --app-eui $APP_EUI \ + --frequency-plan-id $FREQUENCY_PLAN \ + --root-keys.app-key.key $APP_KEY \ + --root-keys.nwk-key.key $NWK_KEY \ + --lorawan-version 1.1.0 \ + --lorawan-phy-version 1.1.0-b +``` + +This will create an end device `dev1` in application `app1` with the `EU_863_870` frequency plan, that uses LoRaWAN 1.1.0 MAC and 1.1.0-b PHY versions. Make sure you replace these versions according to your setup. + +You can also pass `--with-root-keys` to have root keys generated. In this case, you do not need to specify `--root-keys.app-key.key` or `root-keys.nwk-key.key`. + +The end device should now be able to join the private network. + +{{< /tabs/tab >}} + +{{< /tabs/container >}} diff --git a/doc/content/devices/adding-devices/manual-network-settings-otaa.png b/doc/content/devices/adding-devices/manual/otaa/manual-network-settings-otaa.png similarity index 100% rename from doc/content/devices/adding-devices/manual-network-settings-otaa.png rename to doc/content/devices/adding-devices/manual/otaa/manual-network-settings-otaa.png diff --git a/doc/content/devices/adding-devices/non-qr-all-set.png b/doc/content/devices/adding-devices/non-qr-all-set.png new file mode 100644 index 0000000000..d59120e427 Binary files /dev/null and b/doc/content/devices/adding-devices/non-qr-all-set.png differ diff --git a/doc/content/devices/adding-devices/non-qr-join-eui.png b/doc/content/devices/adding-devices/non-qr-join-eui.png new file mode 100644 index 0000000000..f81de45f26 Binary files /dev/null and b/doc/content/devices/adding-devices/non-qr-join-eui.png differ diff --git a/doc/content/devices/adding-devices/qr-data-found.png b/doc/content/devices/adding-devices/qr-data-found.png new file mode 100644 index 0000000000..e204ec7826 Binary files /dev/null and b/doc/content/devices/adding-devices/qr-data-found.png differ diff --git a/doc/content/devices/adding-devices/register-devices-option.png b/doc/content/devices/adding-devices/register-devices-option.png new file mode 100644 index 0000000000..30ab8a6540 Binary files /dev/null and b/doc/content/devices/adding-devices/register-devices-option.png differ diff --git a/doc/content/devices/adding-devices/registered.png b/doc/content/devices/adding-devices/registered.png new file mode 100644 index 0000000000..e6979e4195 Binary files /dev/null and b/doc/content/devices/adding-devices/registered.png differ diff --git a/doc/content/devices/adding-devices/select-dr-non-qr.png b/doc/content/devices/adding-devices/select-dr-non-qr.png new file mode 100644 index 0000000000..dae92964a8 Binary files /dev/null and b/doc/content/devices/adding-devices/select-dr-non-qr.png differ diff --git a/doc/content/devices/atecc608a/import-devices-progress.png b/doc/content/devices/atecc608a/import-devices-progress.png deleted file mode 100644 index 5de47bcb47..0000000000 Binary files a/doc/content/devices/atecc608a/import-devices-progress.png and /dev/null differ diff --git a/doc/content/devices/atecc608a/import-devices-settings.png b/doc/content/devices/atecc608a/import-devices-settings.png deleted file mode 100644 index 8d1776dcdc..0000000000 Binary files a/doc/content/devices/atecc608a/import-devices-settings.png and /dev/null differ diff --git a/doc/content/devices/concepts/_index.md b/doc/content/devices/concepts/_index.md new file mode 100644 index 0000000000..16f288b895 --- /dev/null +++ b/doc/content/devices/concepts/_index.md @@ -0,0 +1,7 @@ +--- +title: "Concepts" +description: "" +weight: 3 +--- + +Learn the basic concepts of working with The Things Stack and LoRaWAN® end devices. diff --git a/doc/content/devices/abp-vs-otaa/_index.md b/doc/content/devices/concepts/abp-vs-otaa/_index.md similarity index 59% rename from doc/content/devices/abp-vs-otaa/_index.md rename to doc/content/devices/concepts/abp-vs-otaa/_index.md index 75dff4aaa0..afe2abbf16 100644 --- a/doc/content/devices/abp-vs-otaa/_index.md +++ b/doc/content/devices/concepts/abp-vs-otaa/_index.md @@ -2,6 +2,7 @@ title: "ABP vs OTAA" description: "" weight: 1 +aliases: ["devices/abp-vs-otaa"] --- This section can help you understand the differences between ABP and OTAA activation modes for LoRaWAN® end devices, and comprehend why using OTAA is recommended. @@ -20,7 +21,7 @@ A `DevAddr` and session keys are assigned to an end device during a procedure ca ## ABP -In ABP activation, a **fixed** `DevAddr` and **session keys** for a pre-selected network are hardcoded into the end device, and they remain the same throughout the lifetime of an ABP end device. With this mode, an end device skips the join procedure which seems to be simpler, but there are quite a few limitations of using ABP, which are explained below. +In ABP activation, a **fixed** `DevAddr` and **session keys** for a pre-selected network are hardcoded into the end device, and they remain the same throughout the lifetime of an ABP end device. With this mode, an end device skips the join procedure which seems to be simpler, but there are quite a few limitations of using ABP, which are explained below. ## OTAA @@ -32,29 +33,29 @@ ABP's drawbacks are arising as consequences of its main characteristics. 1. **ABP end devices use a fixed `DevAddr`.** - Taking the structure of `DevAddr` into the account and the fact that, with ABP, `NwkID` is fixed, we come to the conclusion that this device can work correctly only in its predefined network. Even if a network or a cluster allows registering end devices with different `DevAddr` values than the ones that were assigned to that network/cluster, the [Packet Broker]({{< ref "/the-things-stack/packet-broker#packet-broker" >}}) will not route the traffic from those end devices to the right network/cluster. +Taking the structure of `DevAddr` into the account and the fact that, with ABP, `NwkID` is fixed, we come to the conclusion that this device can work correctly only in its predefined network. Even if a network or a cluster allows registering end devices with different `DevAddr` values than the ones that were assigned to that network/cluster, the [Packet Broker]({{< ref "/the-things-stack/packet-broker#packet-broker" >}}) will not route the traffic from those end devices to the right network/cluster. - Also, even if the network/cluster is assigned with additional address blocks, the Network Server will not be able to perform optimization of `DevAddr` allocation, hence the device matching procedure for ABP end devices will not be improved. +Also, even if the network/cluster is assigned with additional address blocks, the Network Server will not be able to perform optimization of `DevAddr` allocation, hence the device matching procedure for ABP end devices will not be improved. - OTAA end devices are assigned a new `DevAddr` at establishing each new session. This allows them to move to different networks/clusters. +OTAA end devices are assigned a new `DevAddr` at establishing each new session. This allows them to move to different networks/clusters. 2. **ABP end devices use a fixed security session.** - Frame counters associated with ABP devices should not be reset during their lifetime, otherwise the messages from those end devices may end up being dropped. When an ABP end device runs out of frame counters, it is the end of its lifetime. +Frame counters associated with ABP devices should not be reset during their lifetime, otherwise the messages from those end devices may end up being dropped. When an ABP end device runs out of frame counters, it is the end of its lifetime. - Session keys are hardcoded into an ABP device, meaning that even if they leak, they cannot be rotated, which is a serious security threat. +Session keys are hardcoded into an ABP device, meaning that even if they leak, they cannot be rotated, which is a serious security threat. - Unlike ABP, OTAA end devices re-negotiate frame counters and session keys at establishing each new session. Hence, the lifetime of an OTAA device is not conditioned by the width of the frame counter. +Unlike ABP, OTAA end devices re-negotiate frame counters and session keys at establishing each new session. Hence, the lifetime of an OTAA device is not conditioned by the width of the frame counter. - Read more about LoRaWAN security in [The Things Network LoRaWAN documentation](https://www.thethingsnetwork.org/docs/lorawan/security/). - - For enhancing security, you can use [The Things Join Server]({{< ref "/the-things-stack/host/join-server" >}}) to handle the join flow, Network Server and Application Server authentication, store root keys and generate session keys. Another option is using Hardware Secured Elements (see [Microchip ATECC608 secure elements]({{< ref "/devices/atecc608a" >}})) which prevent the exposure of keys to software, firmware, manufacturing sites, and other third parties. +Read more about LoRaWAN security in [The Things Network LoRaWAN documentation](https://www.thethingsnetwork.org/docs/lorawan/security/). + +For enhancing security, you can use [The Things Join Server]({{< ref "/the-things-stack/host/join-server" >}}) to handle the join flow, Network Server and Application Server authentication, store root keys and generate session keys. Another option is using Hardware Secured Elements (see [Microchip ATECC608 secure elements]({{< ref "/devices/adding-devices/atecc608a" >}})) which prevent the exposure of keys to software, firmware, manufacturing sites, and other third parties. 3. **ABP end devices use fixed network parameters.** - When registering an ABP device on {{% tts %}}, you will need to provide the **RX1 Delay**, **RX1 Data Rate Offset**, **RX2 Data Rate Index**, **RX2 Frequency** and a list of **Factory Preset Frequencies**. If these values are not correctly configured, uplinks and/or downlinks might not work. +When registering an ABP device on {{% tts %}}, you will need to provide the **RX1 Delay**, **RX1 Data Rate Offset**, **RX2 Data Rate Index**, **RX2 Frequency** and a list of **Factory Preset Frequencies**. If these values are not correctly configured, uplinks and/or downlinks might not work. - OTAA end devices re-negotiate network parameters at establishing each new session, meaning you do not have to worry about them being misconfigured. +OTAA end devices re-negotiate network parameters at establishing each new session, meaning you do not have to worry about them being misconfigured. ## OTAA Requirements @@ -68,6 +69,6 @@ If the network coverage for the end device can not be guaranteed, it does not me A naive approach that has been used in the past to avoid this was to use ABP. ABP allows a device to start transmitting messages immediately when it is switched on, regardless of whether it has the network coverage or not. -A better approach is to perform an OTAA join in a factory or workshop where the network coverage and working downlinks can be guaranteed. There are no drawbacks to this approach as long as the device follows the LoRaWAN [best practices]({{< ref "/devices/best-practices" >}}). +A better approach is to perform an OTAA join in a factory or workshop where the network coverage and working downlinks can be guaranteed. There are no drawbacks to this approach as long as the device follows the LoRaWAN [best practices]({{< ref "/devices/concepts/best-practices" >}}). One more thing to take into account is persisting network parameters between device restarts. For example, an ABP device uses a non-volatile storage to persist frame counters between restarts. A better approach would be to switch to using OTAA and store the OTAA session rather than frame counters. diff --git a/doc/content/devices/best-practices/_index.md b/doc/content/devices/concepts/best-practices/_index.md similarity index 98% rename from doc/content/devices/best-practices/_index.md rename to doc/content/devices/concepts/best-practices/_index.md index 372e040a5a..eda95499ef 100644 --- a/doc/content/devices/best-practices/_index.md +++ b/doc/content/devices/concepts/best-practices/_index.md @@ -1,7 +1,8 @@ --- title: "Best Practices" description: "" -weight: 3 +weight: -1 +aliases: ["/devices/best-practices"] --- This section contains best practices for building connected devices which use {{% tts %}} as a Network Server. @@ -92,7 +93,7 @@ OTAA devices perform a join-procedure with the network, during which a dynamic D Devices should save network parameters between regular power cycles. This includes session parameters like `DevAddr`, session keys, `FCnt`, and nonces. This allows the device to easily Join, as keys and counters remain synchronized. -Devices should also randomize initial power on delay (i.e. Join). See [Synchronization, Backoff, and Jitter]({{< ref "/devices/best-practices#synchronization-backoff-and-jitter" >}}). +Devices should also randomize initial power on delay (i.e. Join). See [Synchronization, Backoff, and Jitter]({{< ref "/devices/concepts/best-practices#synchronization-backoff-and-jitter" >}}). ## Frame Counters diff --git a/doc/content/devices/confirmed-downlinks-behavior/_index.md b/doc/content/devices/concepts/confirmed-downlinks-behavior/_index.md similarity index 95% rename from doc/content/devices/confirmed-downlinks-behavior/_index.md rename to doc/content/devices/concepts/confirmed-downlinks-behavior/_index.md index d202e43ca1..64da69b2ab 100644 --- a/doc/content/devices/confirmed-downlinks-behavior/_index.md +++ b/doc/content/devices/concepts/confirmed-downlinks-behavior/_index.md @@ -1,7 +1,7 @@ --- title: "Confirmed Downlinks Behavior" description: "" -weight: 8 +aliases: ["/devices/confirmed-downlinks-behavior"] --- This section describes differences in behavior of class A, B and C devices when scheduling confirmed downlink messages. @@ -12,9 +12,9 @@ Let's consider scheduling a confirmed downlink message from the Network Server. To confirm a reception of the above mentioned downlink, a confirmation flag is attached to device's next uplink message. The confirmation flag is part of the standard LoRaWAN® frame header. If the flag is an NACK, the end device indicates that it has not previously received a downlink message that required acknowledgement. If the flag is a ACK, the end device indicates that it wants to provide the acknowledgement for the previously received downlink message that requested it. This applies to all [device classes](https://www.thethingsnetwork.org/docs/lorawan/classes/). -In general, upon receiving the next uplink message with an ACK flag, the Network Server decrypts the uplink message and generates the `downlink ack` message. The Application Server receives the `downlink ack` message and forwards it further to the integrations. +In general, upon receiving the next uplink message with an ACK flag, the Network Server decrypts the uplink message and generates the `downlink ack` message. The Application Server receives the `downlink ack` message and forwards it further to the integrations. -Similar to that, if the next uplink message with a NACK flag is received, the Network Server decrypts the uplink, generates the `downlink nack` message and sends it to the Application Server. The Application Server then forwards the `downlink nack` to integrations and regenerates the downlink. +Similar to that, if the next uplink message with a NACK flag is received, the Network Server decrypts the uplink, generates the `downlink nack` message and sends it to the Application Server. The Application Server then forwards the `downlink nack` to integrations and regenerates the downlink. Sending a downlink happens only after an uplink for class A devices. If a NACK is received from a class A device, the downlink will automatically be re-encrypted and resent. diff --git a/doc/content/devices/device-claiming/_index.md b/doc/content/devices/concepts/device-claiming/_index.md similarity index 97% rename from doc/content/devices/device-claiming/_index.md rename to doc/content/devices/concepts/device-claiming/_index.md index 823b3c05a8..e9032113c0 100644 --- a/doc/content/devices/device-claiming/_index.md +++ b/doc/content/devices/concepts/device-claiming/_index.md @@ -1,7 +1,8 @@ --- title: "Device Claiming" description: "" ---- +aliases: ["/devices/device-claiming"] +--- Device claiming is a mechanism that securely transfers ownership from the device maker to the device owner without transferring LoRaWAN® root keys. This section provides an overview to resources for device makers and device owners. diff --git a/doc/content/devices/concepts/lorawan-device-repository/_index.md b/doc/content/devices/concepts/lorawan-device-repository/_index.md new file mode 100644 index 0000000000..4cb83c4478 --- /dev/null +++ b/doc/content/devices/concepts/lorawan-device-repository/_index.md @@ -0,0 +1,6 @@ +--- +title: "LoRaWAN device repository" +description: "" +--- + +The [LoRaWAN device repository](https://github.com/TheThingsNetwork/lorawan-devices) contains device profiles, LoRaWAN information, codecs, and more, for many LoRaWAN devices. Using the device repository to add devices in {{% tts %}} automatically uses the correct LoRaWAN version and regional parameters version, which means less information for you to find! diff --git a/doc/content/devices/configuring-devices/_index.md b/doc/content/devices/configuring-devices/_index.md new file mode 100644 index 0000000000..0b3cd50a8b --- /dev/null +++ b/doc/content/devices/configuring-devices/_index.md @@ -0,0 +1,7 @@ +--- +title: "Configuring Devices" +description: "" +weight: 2 +--- + +This section contains guides on configuring LoRaWAN® end devices. diff --git a/doc/content/devices/class-b/index.md b/doc/content/devices/configuring-devices/class-b/index.md similarity index 75% rename from doc/content/devices/class-b/index.md rename to doc/content/devices/configuring-devices/class-b/index.md index fd63377c56..a6a40e93be 100644 --- a/doc/content/devices/class-b/index.md +++ b/doc/content/devices/configuring-devices/class-b/index.md @@ -1,21 +1,22 @@ --- -title: "Class B" +title: "Class B Settings" description: "" -weight: 4 +aliases: ["/devices/class-b"] +weight: 3 --- -Class B end devices listen for downlink messages during ping slots. This allows applications to send messages to devices at predefined time slots, rather than waiting for a Class A uplink. When combined with [multicast groups]({{< ref "/devices/multicast" >}}), this allows applications to send periodic downlinks to many devices at the same time. +Class B end devices listen for downlink messages during ping slots. This allows applications to send messages to devices at predefined time slots, rather than waiting for a Class A uplink. When combined with [multicast groups]({{< ref "/devices/configuring-devices/multicast" >}}), this allows applications to send periodic downlinks to many devices at the same time. Read more about device classes in [The Things Network LoRaWAN® documentation](https://www.thethingsnetwork.org/docs/lorawan/classes/). -{{< note >}} See the [Confirmed Downlinks Behavior]({{< ref "/devices/confirmed-downlinks-behavior" >}}) section to learn how confirmed downlinks behavior for class B devices differs from confirmed downlinks behavior for class A devices. {{}} +{{< note >}} See the [Confirmed Downlinks Behavior]({{< ref "/devices/concepts/confirmed-downlinks-behavior" >}}) section to learn how confirmed downlinks behavior for class B devices differs from confirmed downlinks behavior for class A devices. {{}} We define some user parameters that will be used below: ```bash -APP_ID="app1" +APP_ID="app1" DEVICE_ID="dev1" FREQUENCY_PLAN="EU_863_870" LORAWAN_VERSION="1.0.3" @@ -45,13 +46,13 @@ To disable Class B scheduling, reset with `--supports-class-b=false`. ## Multicast Group -See [Multicast]({{< ref "devices/multicast" >}}) for instructions for creating and using multicast groups. +See [Multicast]({{< ref "/devices/configuring-devices/multicast" >}}) for instructions for creating and using multicast groups. ## Class B Message Settings {{% tts %}} supports optional settings for Class B downlink messages: the downlink path and the time to send the message. -The downlink path is defined by one or more gateways IDs. The Network Server and Gateway Server schedules only on the specified gateways in the specified order. This is useful for multicast (where no downlink path is known because there is no uplink). A scheduling attempt can fail when the gateway is not connected, if there is a scheduling conflict or if duty-cycle regulations prohibit transmission. +The downlink path is defined by one or more gateways IDs. The Network Server and Gateway Server schedules only on the specified gateways in the specified order. This is useful for multicast (where no downlink path is known because there is no uplink). A scheduling attempt can fail when the gateway is not connected, if there is a scheduling conflict or if duty-cycle regulations prohibit transmission. The time to transmit is an absolute timestamp in ISO 8601 format to send the message. This requires gateways either with GPS lock, or gateways that use a protocol that provide round-trip times (RTT). See the [Example]({{< relref "#example" >}}) section below. @@ -76,26 +77,27 @@ Then, schedule the following message to the [Application Server MQTT server]({{< ```json { - "downlinks": [{ - "frm_payload": "vu8=", - "f_port": 42, - "priority": "NORMAL", - "class_b_c": { - "gateways": [ - { - "gateway_ids": { - "gateway_id": "gtw1" + "downlinks": [ + { + "frm_payload": "vu8=", + "f_port": 42, + "priority": "NORMAL", + "class_b_c": { + "gateways": [ + { + "gateway_ids": { + "gateway_id": "gtw1" + } }, - }, - { - "gateway_ids": { - "gateway_id": "gtw2" - }, - } - ], - "absolute_time": "2019-07-23T13:05:00Z" + { + "gateway_ids": { + "gateway_id": "gtw2" + } + } + ], + "absolute_time": "2019-07-23T13:05:00Z" + } } - }] + ] } ``` - diff --git a/doc/content/devices/class-c/_index.md b/doc/content/devices/configuring-devices/class-c/_index.md similarity index 76% rename from doc/content/devices/class-c/_index.md rename to doc/content/devices/configuring-devices/class-c/_index.md index e986dff085..c9a9b5c7e4 100644 --- a/doc/content/devices/class-c/_index.md +++ b/doc/content/devices/configuring-devices/class-c/_index.md @@ -1,10 +1,11 @@ --- -title: "Class C" +title: "Class C Settings" description: "" -weight: 5 +aliases: ["/devices/class-c"] +weight: 4 --- -Class C end devices continuously listen for downlink messages. This allows applications to send messages to devices at any time, instead of having to wait for a Class A uplink. When combined with [multicast groups]({{< ref "/devices/multicast" >}}), this allows applications to send immediate downlinks to many devices at the same time. +Class C end devices continuously listen for downlink messages. This allows applications to send messages to devices at any time, instead of having to wait for a Class A uplink. When combined with [multicast groups]({{< ref "/devices/configuring-devices/multicast" >}}), this allows applications to send immediate downlinks to many devices at the same time. This guide shows how to enable or disable Class C for an and device, and how to work with multicast groups. @@ -12,12 +13,12 @@ This guide shows how to enable or disable Class C for an and device, and how to Read more about device classes in [The Things Network LoRaWAN® documentation](https://www.thethingsnetwork.org/docs/lorawan/classes/). -{{< note >}} See the [Confirmed Downlinks Behavior]({{< ref "/devices/confirmed-downlinks-behavior" >}}) section to learn how confirmed downlinks behavior for class C devices differs from confirmed downlinks behavior for class A devices. {{}} +{{< note >}} See the [Confirmed Downlinks Behavior]({{< ref "/devices/concepts/confirmed-downlinks-behavior" >}}) section to learn how confirmed downlinks behavior for class C devices differs from confirmed downlinks behavior for class A devices. {{}} We define some user parameters that will be used below: ```bash -APP_ID="app1" +APP_ID="app1" DEVICE_ID="dev1" FREQUENCY_PLAN="EU_863_870" LORAWAN_VERSION="1.0.3" @@ -47,7 +48,7 @@ To disable Class C scheduling, reset with `--supports-class-c=false`. ## Multicast Group -See [Multicast]({{< ref "devices/multicast" >}}) for instructions for creating and using multicast groups. +See [Multicast]({{< ref "/devices/configuring-devices/multicast" >}}) for instructions for creating and using multicast groups. ## Class C Message Settings @@ -78,25 +79,27 @@ Then, schedule the following message to the [Application Server MQTT server]({{< ```json { - "downlinks": [{ - "frm_payload": "vu8=", - "f_port": 42, - "priority": "NORMAL", - "class_b_c": { - "gateways": [ - { - "gateway_ids": { - "gateway_id": "gtw1" + "downlinks": [ + { + "frm_payload": "vu8=", + "f_port": 42, + "priority": "NORMAL", + "class_b_c": { + "gateways": [ + { + "gateway_ids": { + "gateway_id": "gtw1" + } }, - }, - { - "gateway_ids": { - "gateway_id": "gtw2" - }, - } - ], - "absolute_time": "2019-07-23T13:05:00Z" + { + "gateway_ids": { + "gateway_id": "gtw2" + } + } + ], + "absolute_time": "2019-07-23T13:05:00Z" + } } - }] + ] } ``` diff --git a/doc/content/devices/configuring-devices/device-location/_index.md b/doc/content/devices/configuring-devices/device-location/_index.md new file mode 100644 index 0000000000..bc89f429bf --- /dev/null +++ b/doc/content/devices/configuring-devices/device-location/_index.md @@ -0,0 +1,73 @@ +--- +title: "Device location settings" +description: "" +weight: 1 +--- + +Once you have added your end device to {{% tts %}}, you can also set its location to be displayed on a map widget. + + + +{{< tabs/container "Console" "CLI" >}} + +{{< tabs/tab "Console" >}} + +To do this on the console, click the **Change location settings** option on the end device. + +The end device location can be manually set in two ways. + +1. Pinning the location on the map widget. +2. Entering the **Latitude**, **Longitude** and **Altitude** values. + +{{< figure src="device-location.png" alt="Gateway location" >}} + +{{< /tabs/tab >}} + +{{< tabs/tab "CLI" >}} + +Once you have added your end device to {{% tts %}}, you can also set its location. + +Set your end device's location with: + +```bash +LAT="43.84" +LONG="18.32" +ALT="500" +ttn-lw-cli end-devices set $APP_ID $DEVICE_ID \ + --location.latitude $LAT \ + --location.longitude $LONG \ + --location.altitude $ALT \ +``` + +You can also set the end device location to be updated from various sources with the `--location.source` flag. + +The source of the location data can be the registry, GPS data, results of the LoRa RSSI geolocation, etc. Use `ttn-lw-cli end-devices set $APP_ID $DEVICE_ID --help` command to see the full list of the available location sources and other relatable info. If you set the alternative location source, the location settings you manually set will be overwritten by the automatic updates from that source. + +The CLI will return something like: + +```json +{ + "ids": { + "device_id": "dev1", + "application_ids": { + "application_id": "app1" + }, + "dev_eui": "0004A30B001C0530", + "join_eui": "800000000000000C" + }, + "created_at": "2020-05-27T15:50:38.567Z", + "updated_at": "2020-12-25T11:16:20.592Z", + "locations": { + "user": { + "latitude": 43.84, + "longitude": 18.32, + "altitude": 500, + "source": "SOURCE_REGISTRY" + } + } +} +``` + +{{< /tabs/tab >}} + +{{< /tabs/container >}} diff --git a/doc/content/devices/adding-devices/device-location.png b/doc/content/devices/configuring-devices/device-location/device-location.png similarity index 100% rename from doc/content/devices/adding-devices/device-location.png rename to doc/content/devices/configuring-devices/device-location/device-location.png diff --git a/doc/content/devices/downlink-queue-ops/_index.md b/doc/content/devices/configuring-devices/downlink-queue-ops/_index.md similarity index 91% rename from doc/content/devices/downlink-queue-ops/_index.md rename to doc/content/devices/configuring-devices/downlink-queue-ops/_index.md index 5daeb1d467..df583593b1 100644 --- a/doc/content/devices/downlink-queue-ops/_index.md +++ b/doc/content/devices/configuring-devices/downlink-queue-ops/_index.md @@ -12,7 +12,7 @@ You can schedule a downlink using the CLI, MQTT or HTTP webhooks. To schedule downlinks using MQTT, see [MQTT Server]({{< ref "integrations/mqtt" >}}). To schedule downlinks using webhooks, see [Scheduling Downlinks with Webhooks]({{< ref "integrations/webhooks/scheduling-downlinks" >}}). -{{< note >}} See the [Confirmed Downlinks Behavior]({{< ref "/devices/confirmed-downlinks-behavior" >}}) section to learn how confirmed downlinks behavior for class B and class C devices differs from confirmed downlinks behavior for class A devices. {{}} +{{< note >}} See the [Confirmed Downlinks Behavior]({{< ref "/devices/concepts/confirmed-downlinks-behavior" >}}) section to learn how confirmed downlinks behavior for class B and class C devices differs from confirmed downlinks behavior for class A devices. {{}} This guide shows how to interact with the downlink queue from the command-line interface (CLI). @@ -23,7 +23,7 @@ If there are more application downlink messages in the queue, the Network Server We define some user parameters that will be used below: ```bash -APP_ID="app1" +APP_ID="app1" DEVICE_ID="dev1" PAYLOAD="01020304" PRIORITY="NORMAL" diff --git a/doc/content/devices/mac-settings/_index.md b/doc/content/devices/configuring-devices/mac-settings/_index.md similarity index 98% rename from doc/content/devices/mac-settings/_index.md rename to doc/content/devices/configuring-devices/mac-settings/_index.md index 7407fc825a..efbb4b4ad5 100644 --- a/doc/content/devices/mac-settings/_index.md +++ b/doc/content/devices/configuring-devices/mac-settings/_index.md @@ -1,7 +1,8 @@ --- title: "MAC Settings" description: "" -weight: 8 +aliases: ["/devices/configuring-devices/mac-settings"] +weight: 2 --- This section provides guidelines for configuring MAC settings for end devices from the CLI. @@ -125,7 +126,7 @@ See the [End Device API Reference]({{< ref "reference/api/end_device#message:MAC To enable ADR, set the `mac-settings.use-adr` parameter: ```bash -ttn-lw-cli end-devices set --mac-settings.use-adr=true +ttn-lw-cli end-devices set --mac-settings.use-adr=true ``` See the [Adaptive Data Rate]({{< ref "/reference/adr" >}}) section for detailed information on configuring ADR parameters and ADR margin using MAC settings. diff --git a/doc/content/devices/multicast/index.md b/doc/content/devices/configuring-devices/multicast/index.md similarity index 68% rename from doc/content/devices/multicast/index.md rename to doc/content/devices/configuring-devices/multicast/index.md index f2ceffa94b..684fedfcf7 100644 --- a/doc/content/devices/multicast/index.md +++ b/doc/content/devices/configuring-devices/multicast/index.md @@ -1,18 +1,18 @@ --- -title: "Multicast" +title: "Multicast Groups" description: "" -aliases: ["devices/class-c-multicast"] -weight: 6 +aliases: ["devices/multicast"] +weight: 5 --- -It is also possible to create a [Class B]({{< ref "devices/class-b" >}}) or [Class C]({{< ref "devices/class-c" >}}) multicast group to send downlink messages to a group of end devices. A multicast group is a virtual ABP device, where multiple physical devices share the same DevAddr and session keys. It does not support uplink, confirmed downlink nor MAC commands. +It is also possible to create a [Class B]({{< ref "devices/configuring-devices/class-b" >}}) or [Class C]({{< ref "devices/configuring-devices/class-c" >}}) multicast group to send downlink messages to a group of end devices. A multicast group is a virtual ABP device, where multiple physical devices share the same DevAddr and session keys. It does not support uplink, confirmed downlink nor MAC commands. We define some user parameters that will be used below: ```bash -APP_ID="app1" +APP_ID="app1" DEVICE_ID="dev1" FREQUENCY_PLAN="EU_863_870" LORAWAN_VERSION="1.0.3" @@ -30,7 +30,7 @@ Since there are no uplinks in multicast groups, there is no MAC layer communicat - `mac-settings.ping-slot-periodicity.value` -See the [MAC Settings]({{< ref "devices/mac-settings" >}}) guide for more information about configuring MAC layer parameters. +See the [MAC Settings]({{< ref "/devices/configuring-devices/mac-settings" >}}) guide for more information about configuring MAC layer parameters. ## Creating a Multicast Group @@ -76,26 +76,27 @@ Then, schedule the following message to the [Application Server MQTT server]({{< ```json { - "downlinks": [{ - "frm_payload": "vu8=", - "f_port": 42, - "priority": "NORMAL", - "class_b_c": { - "gateways": [ - { - "gateway_ids": { - "gateway_id": "gtw1" + "downlinks": [ + { + "frm_payload": "vu8=", + "f_port": 42, + "priority": "NORMAL", + "class_b_c": { + "gateways": [ + { + "gateway_ids": { + "gateway_id": "gtw1" + } + }, + { + "gateway_ids": { + "gateway_id": "gtw2" + } } - }, - { - "gateway_ids": { - "gateway_id": "gtw2" - } - } - ], - "absolute_time": "2019-07-23T13:05:00Z" + ], + "absolute_time": "2019-07-23T13:05:00Z" + } } - }] + ] } ``` - diff --git a/doc/content/devices/configuring-devices/payload-crypto-override/_index.md b/doc/content/devices/configuring-devices/payload-crypto-override/_index.md new file mode 100644 index 0000000000..f17c579102 --- /dev/null +++ b/doc/content/devices/configuring-devices/payload-crypto-override/_index.md @@ -0,0 +1,16 @@ +--- +title: "Payload Crypto Override" +description: "" +--- + +LoRaWAN frames are encrypted on the application layer using the AppSKey. Once the end device is registered, you can choose to enforce or skip payload encryption. Skipping payload encryption will cause the Application Server to forward messages to integrations without any processing, for example it will neglect [payload formatters]({{< ref "/integrations/payload-formatters" >}}). If you choose to skip payload encryption, integrations will be responsible for processing the message in order to understand it. + + + +To configure these settings, navigate to your end device's **General settings** tab in the Console and scroll down to the **Application layer** section. + +Skipping payload encryption and decryption option is also available on an [application level]({{< ref "/integrations/adding-applications#payload-encryption-and-decryption" >}}), so if you want the end device to inherit this setting from its application, choose **Use application default**. + +Otherwise, choose to **Enforce skipping payload crypto** or to **Enforce payload crypto** for a single device only. + +{{< figure src="skip-payload-crypto.png" alt="Skip payload encryption and decryption" >}} diff --git a/doc/content/devices/adding-devices/skip-payload-crypto.png b/doc/content/devices/configuring-devices/payload-crypto-override/skip-payload-crypto.png similarity index 100% rename from doc/content/devices/adding-devices/skip-payload-crypto.png rename to doc/content/devices/configuring-devices/payload-crypto-override/skip-payload-crypto.png diff --git a/doc/content/devices/generic-node-se/found-qr-data.png b/doc/content/devices/generic-node-se/found-qr-data.png deleted file mode 100644 index 1552b065b2..0000000000 Binary files a/doc/content/devices/generic-node-se/found-qr-data.png and /dev/null differ diff --git a/doc/content/devices/generic-node-se/waiting-for-camera.png b/doc/content/devices/generic-node-se/waiting-for-camera.png deleted file mode 100644 index 8e3983be89..0000000000 Binary files a/doc/content/devices/generic-node-se/waiting-for-camera.png and /dev/null differ diff --git a/doc/content/devices/models/_index.md b/doc/content/devices/models/_index.md new file mode 100644 index 0000000000..0ee5f9f3d1 --- /dev/null +++ b/doc/content/devices/models/_index.md @@ -0,0 +1,7 @@ +--- +title: "Models" +description: "Guides on connecting devices to The Things Stack by model" +weight: 4 +--- + +This subsection contains comprehensive instructions for connecting some of the popular LoRaWAN® devices to {{% tts %}}. diff --git a/doc/content/devices/generic-node-se/_index.md b/doc/content/devices/models/generic-node-se/_index.md similarity index 73% rename from doc/content/devices/generic-node-se/_index.md rename to doc/content/devices/models/generic-node-se/_index.md index 3274933a64..7874dbd6c5 100644 --- a/doc/content/devices/generic-node-se/_index.md +++ b/doc/content/devices/models/generic-node-se/_index.md @@ -1,12 +1,14 @@ --- title: "Generic Node Sensor Edition" description: "" -weight: +weight: --- {{< figure src="generic-node-se.png" alt="Generic Node Sensor Edition" class="float plain" >}} -This section will provide guidance on how to begin using [Generic Node Sensor Edition](https://www.genericnode.com/docs/sensor-edition/) (GNSE) on {{% tts %}}. +This section explains how to get started with the [Generic Node Sensor Edition](https://www.genericnode.com/docs/sensor-edition/) (GNSE) on {{% tts %}}. + + The Generic Node Sensor Edition comes with a pre-loaded application called [vanilla](https://www.genericnode.com/docs/applications/se-vanilla/) that showcases the device's functions and capabilities. This application utilizes a combination of the onboard components including the LEDs, button, buzzer, accelerometer, secure element, temperature sensor, and humidity sensor. The instructions on how to flash a new application onto the Generic Node SE can be found [here](https://www.genericnode.com/docs/getting-started/se-sw/env-setup/). @@ -41,19 +43,20 @@ To continue with the rest of the registration process you can choose either **Lo The [LoRaWAN® Device repository](https://github.com/TheThingsNetwork/lorawan-devices) comprises over 600 end-device profiles, including the Generic Node Sensor Edition, which requires less information for registration with {{% tts %}}. In the **End device type** section, under **Input Method** select **Select the end device in the LoRaWAN device repository**. Then select/enter the following values: - - End device brand: **The Things Industries** - - Model: **Generic Node (Sensor Edition)** - - Hardware Ver.: **1.1** - - Firmware Ver.: **1.1** - - Profile (Region): choose **EU_863_870** for Europe or **US_902_928** for US - - Frequency plan: choose the frequency plan appropriate for your region/country, for example, if you are live in Europe, choose **Europe 863-870 MHz (SF9 for RX2 - recommended)**. + +- End device brand: **The Things Industries** +- Model: **Generic Node (Sensor Edition)** +- Hardware Ver.: **1.1** +- Firmware Ver.: **1.1** +- Profile (Region): choose **EU_863_870** for Europe or **US_902_928** for US +- Frequency plan: choose the frequency plan appropriate for your region/country, for example, if you are live in Europe, choose **Europe 863-870 MHz (SF9 for RX2 - recommended)**. {{< figure src="dev-rep-1.png" alt="Settings for registration through device repository" >}} - - JoinEUI: pre-filled - - DevEUI: pre-filled (this is the secure element’s DevEUI) - - AppKey: select the **Generate** button. - - End device ID: you can continue with the pre-filled value or use any other unique value. +- JoinEUI: pre-filled +- DevEUI: pre-filled (this is the secure element’s DevEUI) +- AppKey: select the **Generate** button. +- End device ID: you can continue with the pre-filled value or use any other unique value. Select the **Register end device** button. @@ -70,19 +73,21 @@ The Generic Node Sensor Edition also supports manual registration, but you need In the **End device type** section, under **Input Method** select **Enter end device specifics manually**. Then select/enter the following values: - - Frequency plan: choose the frequency plan appropriate for your region/country, for example, if you are live in Europe, choose **Europe 863-870 MHz (SF9 for RX2 - recommended)**. - - LoRaWAN version: **LoRaWAN Specification 1.0.2** - - Regional parameters version: **RP001 Regional Parameters 1.0.2 revision B** + +- Frequency plan: choose the frequency plan appropriate for your region/country, for example, if you are live in Europe, choose **Europe 863-870 MHz (SF9 for RX2 - recommended)**. +- LoRaWAN version: **LoRaWAN Specification 1.0.2** +- Regional parameters version: **RP001 Regional Parameters 1.0.2 revision B** Select **Show advanced activation, LoRaWAN class and cluster settings** to expand the section. Ensure that the default selection is **Over the Air Activation (OTAA)**. {{< figure src="manually-1.png" alt="Settings for manual registartion" >}} Under **Provisioning information** enter the following settings: - - JoinEUI: pre-filled - - DevEUI: pre-filled (this is the secure element’s DevEUI) - - AppKey: select the **Generate** button. - - End device ID: you can continue with the pre-filled value or use any other unique value. + +- JoinEUI: pre-filled +- DevEUI: pre-filled (this is the secure element’s DevEUI) +- AppKey: select the **Generate** button. +- End device ID: you can continue with the pre-filled value or use any other unique value. Select the **Register end device** button. diff --git a/doc/content/devices/generic-node-se/application-overview.png b/doc/content/devices/models/generic-node-se/application-overview.png similarity index 100% rename from doc/content/devices/generic-node-se/application-overview.png rename to doc/content/devices/models/generic-node-se/application-overview.png diff --git a/doc/content/devices/generic-node-se/dev-rep-1.png b/doc/content/devices/models/generic-node-se/dev-rep-1.png similarity index 100% rename from doc/content/devices/generic-node-se/dev-rep-1.png rename to doc/content/devices/models/generic-node-se/dev-rep-1.png diff --git a/doc/content/devices/generic-node-se/dev-rep-2.png b/doc/content/devices/models/generic-node-se/dev-rep-2.png similarity index 100% rename from doc/content/devices/generic-node-se/dev-rep-2.png rename to doc/content/devices/models/generic-node-se/dev-rep-2.png diff --git a/doc/content/devices/adding-devices/found-qr-data.png b/doc/content/devices/models/generic-node-se/found-qr-data.png similarity index 100% rename from doc/content/devices/adding-devices/found-qr-data.png rename to doc/content/devices/models/generic-node-se/found-qr-data.png diff --git a/doc/content/devices/generic-node-se/generic-node-se.png b/doc/content/devices/models/generic-node-se/generic-node-se.png similarity index 100% rename from doc/content/devices/generic-node-se/generic-node-se.png rename to doc/content/devices/models/generic-node-se/generic-node-se.png diff --git a/doc/content/devices/generic-node-se/gnse-after-register.png b/doc/content/devices/models/generic-node-se/gnse-after-register.png similarity index 100% rename from doc/content/devices/generic-node-se/gnse-after-register.png rename to doc/content/devices/models/generic-node-se/gnse-after-register.png diff --git a/doc/content/devices/generic-node-se/manually-1.png b/doc/content/devices/models/generic-node-se/manually-1.png similarity index 100% rename from doc/content/devices/generic-node-se/manually-1.png rename to doc/content/devices/models/generic-node-se/manually-1.png diff --git a/doc/content/devices/generic-node-se/manually-2.png b/doc/content/devices/models/generic-node-se/manually-2.png similarity index 100% rename from doc/content/devices/generic-node-se/manually-2.png rename to doc/content/devices/models/generic-node-se/manually-2.png diff --git a/doc/content/devices/generic-node-se/register-end-device.png b/doc/content/devices/models/generic-node-se/register-end-device.png similarity index 100% rename from doc/content/devices/generic-node-se/register-end-device.png rename to doc/content/devices/models/generic-node-se/register-end-device.png diff --git a/doc/content/devices/adding-devices/waiting-for-camera.png b/doc/content/devices/models/generic-node-se/waiting-for-camera.png similarity index 100% rename from doc/content/devices/adding-devices/waiting-for-camera.png rename to doc/content/devices/models/generic-node-se/waiting-for-camera.png diff --git a/doc/content/devices/the-things-node/ActivationInformation.png b/doc/content/devices/models/the-things-node/ActivationInformation.png similarity index 100% rename from doc/content/devices/the-things-node/ActivationInformation.png rename to doc/content/devices/models/the-things-node/ActivationInformation.png diff --git a/doc/content/devices/the-things-node/AddEndDevice.png b/doc/content/devices/models/the-things-node/AddEndDevice.png similarity index 100% rename from doc/content/devices/the-things-node/AddEndDevice.png rename to doc/content/devices/models/the-things-node/AddEndDevice.png diff --git a/doc/content/devices/the-things-node/ConnectUsbCable.png b/doc/content/devices/models/the-things-node/ConnectUsbCable.png similarity index 100% rename from doc/content/devices/the-things-node/ConnectUsbCable.png rename to doc/content/devices/models/the-things-node/ConnectUsbCable.png diff --git a/doc/content/devices/the-things-node/NodeOpenCase.jpg b/doc/content/devices/models/the-things-node/NodeOpenCase.jpg similarity index 100% rename from doc/content/devices/the-things-node/NodeOpenCase.jpg rename to doc/content/devices/models/the-things-node/NodeOpenCase.jpg diff --git a/doc/content/devices/the-things-node/RegisterThingsNodeP1.png b/doc/content/devices/models/the-things-node/RegisterThingsNodeP1.png similarity index 100% rename from doc/content/devices/the-things-node/RegisterThingsNodeP1.png rename to doc/content/devices/models/the-things-node/RegisterThingsNodeP1.png diff --git a/doc/content/devices/the-things-node/RegisterThingsNodeP2.png b/doc/content/devices/models/the-things-node/RegisterThingsNodeP2.png similarity index 100% rename from doc/content/devices/the-things-node/RegisterThingsNodeP2.png rename to doc/content/devices/models/the-things-node/RegisterThingsNodeP2.png diff --git a/doc/content/devices/the-things-node/TheThingsNetworkArduinoLib.png b/doc/content/devices/models/the-things-node/TheThingsNetworkArduinoLib.png similarity index 100% rename from doc/content/devices/the-things-node/TheThingsNetworkArduinoLib.png rename to doc/content/devices/models/the-things-node/TheThingsNetworkArduinoLib.png diff --git a/doc/content/devices/the-things-node/TheThingsNode.jpg b/doc/content/devices/models/the-things-node/TheThingsNode.jpg similarity index 100% rename from doc/content/devices/the-things-node/TheThingsNode.jpg rename to doc/content/devices/models/the-things-node/TheThingsNode.jpg diff --git a/doc/content/devices/the-things-node/TheThingsNodeArduinoLib.png b/doc/content/devices/models/the-things-node/TheThingsNodeArduinoLib.png similarity index 100% rename from doc/content/devices/the-things-node/TheThingsNodeArduinoLib.png rename to doc/content/devices/models/the-things-node/TheThingsNodeArduinoLib.png diff --git a/doc/content/devices/the-things-node/UplinkPayloadFormatter.png b/doc/content/devices/models/the-things-node/UplinkPayloadFormatter.png similarity index 100% rename from doc/content/devices/the-things-node/UplinkPayloadFormatter.png rename to doc/content/devices/models/the-things-node/UplinkPayloadFormatter.png diff --git a/doc/content/devices/the-things-node/_index.md b/doc/content/devices/models/the-things-node/_index.md similarity index 94% rename from doc/content/devices/the-things-node/_index.md rename to doc/content/devices/models/the-things-node/_index.md index a6dee469c0..b3926cea57 100755 --- a/doc/content/devices/the-things-node/_index.md +++ b/doc/content/devices/models/the-things-node/_index.md @@ -1,14 +1,17 @@ --- title: "The Things Node" description: "" -weight: +weight: --- {{< figure src="TheThingsNode.jpg" alt="The Things Node" class="float plain" >}} -**The Things Node** is based on the [SparkFun Pro Micro - 3.3V/8Mhz](https://www.sparkfun.com/products/12587) with an added Microchip LoRaWAN® module ([RN2483](https://www.microchip.com/wwwproducts/en/RN2483) or [RN2903](https://www.microchip.com/wwwproducts/en/RN2903)). It features a temperature sensor, [NXP’s digital accelerometer](http://www.nxp.com/products/sensors/accelerometers/3-axis-accelerometers/2g-4g-8g-low-g-12-bit-digital-accelerometer:MMA8452Q), light sensor, pushbutton, and RGB LED. All this is packaged in a matchbox-sized waterproof (IP54) casing with a 3 AAA battery compartment. +In this quickstart, you will learn how to register your Things Node with {{% tts %}} and program it with the Arduino software for activating with {{% tts %}}. + + -The Things Node is compatible with the **Arduino software (IDE)**. In this quickstart, you will learn how to register your Things Node with {{% tts %}} and program it with the Arduino software for activating with {{% tts %}}. +**The Things Node** is based on the [SparkFun Pro Micro - 3.3V/8Mhz](https://www.sparkfun.com/products/12587) with an added Microchip LoRaWAN® module ([RN2483](https://www.microchip.com/wwwproducts/en/RN2483) or [RN2903](https://www.microchip.com/wwwproducts/en/RN2903)). It features a temperature sensor, [NXP’s digital accelerometer](http://www.nxp.com/products/sensors/accelerometers/3-axis-accelerometers/2g-4g-8g-low-g-12-bit-digital-accelerometer:MMA8452Q), light sensor, pushbutton, and RGB LED. All this is packaged in a matchbox-sized waterproof (IP54) casing with a 3 AAA battery compartment. +The Things Node is compatible with the **Arduino software (IDE)**. ## Setting Up Arduino @@ -44,9 +47,10 @@ Finally, you should add the **SparkFun Pro Micro** board package to the Arduino https://raw.githubusercontent.com/sparkfun/Arduino_Boards/main/IDE_Board_Manager/package_sparkfun_index.json ``` + {{< figure src="additional-boards-manager.png" alt="Additional Board Manager" >}} -Select the **OK** button. +Select the **OK** button. Open the Board Manager by selecting **Tools → Board → Board Manager...** from the menu bar. @@ -54,7 +58,7 @@ Open the Board Manager by selecting **Tools → Board → Board Manager. Then open the Board Manager by clicking **Tools → Board → Boards Manager...** from the menu bar. -Search for **sparkfun** in the Board Manager. You should see the **SparkFun AVR Boards** package appear. Select the **Install** button. +Search for **sparkfun** in the Board Manager. You should see the **SparkFun AVR Boards** package appear. Select the **Install** button. {{< figure src="sparkfun-avr-boards.png" alt="SparkFun AVR Boards" >}} @@ -128,10 +132,9 @@ Replace **REPLACE_ME** with **TTN_FP_EU868** or **TTN_FP_US915** depending on th {{< note "The Things Node supports only **EU868** and **US915** frequency plans." />}} - Select **Sketch → Upload** from the menu bar to upload the sketch. The Arduino IDE verifies your sketch again and uploads it to your Things Node. -Once uploaded, your sketch will immediately start to run but you cannot see any output unless you open the Arduino **Serial Monitor**. The Arduino **Serial Monitor** is a tool that can be used to print information passing through the serial port. +Once uploaded, your sketch will immediately start to run but you cannot see any output unless you open the Arduino **Serial Monitor**. The Arduino **Serial Monitor** is a tool that can be used to print information passing through the serial port. Select **Tools → Serial Monitor** from the menu bar to open the **Serial Monitor**. @@ -160,7 +163,7 @@ The Things Node (or any end device) first needs to be registered with an **appli ## Registering The Things Node with {{% tts %}} -It’s time to register your Things Node with {{% tts %}}. +It’s time to register your Things Node with {{% tts %}}. On the **Applications** page, select your application to view its **Overview** page. @@ -183,30 +186,31 @@ Under **Select the end device**, select the following mandatory fields. - Model – `The Things Node` - Hardware Ver. – `1.0` - Firmware Ver. – `1.0` -- Profile (Region) – Choose `EU_863_870` or `US_902_928` to match with your board. +- Profile (Region) – Choose `EU_863_870` or `US_902_928` to match with your board. {{< figure src="RegisterThingsNodeP1.png" alt="Register Things Node" >}} Under the **Enter registration data**, select/fill the following mandatory fields. - Frequency plan – Select `Europe 863-870 MHz (SF9 for RX2 - recommended)` for **EU_863_870** or `United States 902-928 MHz, FSB2 (used by TTN)` for **US_902_928**. -- AppEUI – Copy the **AppEUI** from the output printed by the ***DeviceInfo*** sketch. -- DevEUI – Copy the **DevEUI** from the output printed by the ***DeviceInfo*** sketch. +- AppEUI – Copy the **AppEUI** from the output printed by the **_DeviceInfo_** sketch. +- DevEUI – Copy the **DevEUI** from the output printed by the **_DeviceInfo_** sketch. - AppKey – Select **Generate** button to generate an **AppKey**. -- End device ID – Give your device a unique human-readable [identifier]({{< ref "reference/id-eui-constraints" >}}). +- End device ID – Give your device a unique human-readable [identifier]({{< ref "reference/id-eui-constraints" >}}). -Select the **Register end device** button. +Select the **Register end device** button. {{< figure src="RegisterThingsNodeP2.png" alt="Register Things Node" >}} Once registered, you will be redirected to the **overview** page of the newly registered Things Node, where you can find the generated **AppKey** which we’ll need next. ## Payload Formatter + The Things Node supports different types of payload formatters. However, for this quickstart you can use the payload formatter which we have provided through our [Device Repository](https://www.thethingsnetwork.org/device-repository/). Click on the **Payload formatters** tab, then click on the **Uplink** tab. -Select **Use Device Repository Formatters** from the **Formatter type** drop-down box. +Select **Use Device Repository Formatters** from the **Formatter type** drop-down box. Click on the **Save changes** button. @@ -216,7 +220,7 @@ Click on the **Save changes** button. To activate the Things Node using Over-the-air-activation (OTAA), you must enter some configuration settings from {{% tts %}}. -In the Arduino IDE, select **File → Examples → TheThingsNode → Basic** from the menu bar. The ***Basic.ino*** sketch will open in a new window. +In the Arduino IDE, select **File → Examples → TheThingsNode → Basic** from the menu bar. The **_Basic.ino_** sketch will open in a new window. Replace the lines following the comment **Set your AppEUI and AppKey**. These keys can be found in your Things Node’s **overview** page under the **Activation information**. diff --git a/doc/content/devices/the-things-node/additional-boards-manager.png b/doc/content/devices/models/the-things-node/additional-boards-manager.png similarity index 100% rename from doc/content/devices/the-things-node/additional-boards-manager.png rename to doc/content/devices/models/the-things-node/additional-boards-manager.png diff --git a/doc/content/devices/the-things-node/decoded-payload.png b/doc/content/devices/models/the-things-node/decoded-payload.png similarity index 100% rename from doc/content/devices/the-things-node/decoded-payload.png rename to doc/content/devices/models/the-things-node/decoded-payload.png diff --git a/doc/content/devices/the-things-node/payload-formatter.png b/doc/content/devices/models/the-things-node/payload-formatter.png similarity index 100% rename from doc/content/devices/the-things-node/payload-formatter.png rename to doc/content/devices/models/the-things-node/payload-formatter.png diff --git a/doc/content/devices/the-things-node/sparkfun-avr-boards.png b/doc/content/devices/models/the-things-node/sparkfun-avr-boards.png similarity index 100% rename from doc/content/devices/the-things-node/sparkfun-avr-boards.png rename to doc/content/devices/models/the-things-node/sparkfun-avr-boards.png diff --git a/doc/content/devices/the-things-uno/AddApplication.png b/doc/content/devices/models/the-things-uno/AddApplication.png similarity index 100% rename from doc/content/devices/the-things-uno/AddApplication.png rename to doc/content/devices/models/the-things-uno/AddApplication.png diff --git a/doc/content/devices/the-things-uno/AddEndDevice.png b/doc/content/devices/models/the-things-uno/AddEndDevice.png similarity index 100% rename from doc/content/devices/the-things-uno/AddEndDevice.png rename to doc/content/devices/models/the-things-uno/AddEndDevice.png diff --git a/doc/content/devices/the-things-uno/ApplicationOverview.png b/doc/content/devices/models/the-things-uno/ApplicationOverview.png similarity index 100% rename from doc/content/devices/the-things-uno/ApplicationOverview.png rename to doc/content/devices/models/the-things-uno/ApplicationOverview.png diff --git a/doc/content/devices/the-things-uno/Board.png b/doc/content/devices/models/the-things-uno/Board.png similarity index 100% rename from doc/content/devices/the-things-uno/Board.png rename to doc/content/devices/models/the-things-uno/Board.png diff --git a/doc/content/devices/the-things-uno/CreateApplication.png b/doc/content/devices/models/the-things-uno/CreateApplication.png similarity index 100% rename from doc/content/devices/the-things-uno/CreateApplication.png rename to doc/content/devices/models/the-things-uno/CreateApplication.png diff --git a/doc/content/devices/the-things-uno/LibraryManager.png b/doc/content/devices/models/the-things-uno/LibraryManager.png similarity index 100% rename from doc/content/devices/the-things-uno/LibraryManager.png rename to doc/content/devices/models/the-things-uno/LibraryManager.png diff --git a/doc/content/devices/the-things-uno/PayloadFormatter.png b/doc/content/devices/models/the-things-uno/PayloadFormatter.png similarity index 100% rename from doc/content/devices/the-things-uno/PayloadFormatter.png rename to doc/content/devices/models/the-things-uno/PayloadFormatter.png diff --git a/doc/content/devices/the-things-uno/Port.png b/doc/content/devices/models/the-things-uno/Port.png similarity index 100% rename from doc/content/devices/the-things-uno/Port.png rename to doc/content/devices/models/the-things-uno/Port.png diff --git a/doc/content/devices/the-things-uno/RegisterEndDeviceManualABP.png b/doc/content/devices/models/the-things-uno/RegisterEndDeviceManualABP.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterEndDeviceManualABP.png rename to doc/content/devices/models/the-things-uno/RegisterEndDeviceManualABP.png diff --git a/doc/content/devices/the-things-uno/RegisterEndDeviceManualCommon.png b/doc/content/devices/models/the-things-uno/RegisterEndDeviceManualCommon.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterEndDeviceManualCommon.png rename to doc/content/devices/models/the-things-uno/RegisterEndDeviceManualCommon.png diff --git a/doc/content/devices/the-things-uno/RegisterEndDeviceManualOTAA.png b/doc/content/devices/models/the-things-uno/RegisterEndDeviceManualOTAA.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterEndDeviceManualOTAA.png rename to doc/content/devices/models/the-things-uno/RegisterEndDeviceManualOTAA.png diff --git a/doc/content/devices/the-things-uno/RegisterEndDeviceRepo.png b/doc/content/devices/models/the-things-uno/RegisterEndDeviceRepo.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterEndDeviceRepo.png rename to doc/content/devices/models/the-things-uno/RegisterEndDeviceRepo.png diff --git a/doc/content/devices/the-things-uno/RegisterEndDeviceRepoABP.png b/doc/content/devices/models/the-things-uno/RegisterEndDeviceRepoABP.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterEndDeviceRepoABP.png rename to doc/content/devices/models/the-things-uno/RegisterEndDeviceRepoABP.png diff --git a/doc/content/devices/the-things-uno/RegisterEndDeviceRepoOTAA.png b/doc/content/devices/models/the-things-uno/RegisterEndDeviceRepoOTAA.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterEndDeviceRepoOTAA.png rename to doc/content/devices/models/the-things-uno/RegisterEndDeviceRepoOTAA.png diff --git a/doc/content/devices/the-things-uno/RegisterTheThingsUnoData.png b/doc/content/devices/models/the-things-uno/RegisterTheThingsUnoData.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterTheThingsUnoData.png rename to doc/content/devices/models/the-things-uno/RegisterTheThingsUnoData.png diff --git a/doc/content/devices/the-things-uno/RegisterTheThingsUnoDeviceRepository.png b/doc/content/devices/models/the-things-uno/RegisterTheThingsUnoDeviceRepository.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterTheThingsUnoDeviceRepository.png rename to doc/content/devices/models/the-things-uno/RegisterTheThingsUnoDeviceRepository.png diff --git a/doc/content/devices/the-things-uno/RegisterTheThingsUnoParameters.png b/doc/content/devices/models/the-things-uno/RegisterTheThingsUnoParameters.png similarity index 100% rename from doc/content/devices/the-things-uno/RegisterTheThingsUnoParameters.png rename to doc/content/devices/models/the-things-uno/RegisterTheThingsUnoParameters.png diff --git a/doc/content/devices/the-things-uno/TheThingsStackConsole1.png b/doc/content/devices/models/the-things-uno/TheThingsStackConsole1.png similarity index 100% rename from doc/content/devices/the-things-uno/TheThingsStackConsole1.png rename to doc/content/devices/models/the-things-uno/TheThingsStackConsole1.png diff --git a/doc/content/devices/the-things-uno/TheThingsUno.png b/doc/content/devices/models/the-things-uno/TheThingsUno.png similarity index 100% rename from doc/content/devices/the-things-uno/TheThingsUno.png rename to doc/content/devices/models/the-things-uno/TheThingsUno.png diff --git a/doc/content/devices/the-things-uno/TheThingsUnoJoinAccept.png b/doc/content/devices/models/the-things-uno/TheThingsUnoJoinAccept.png similarity index 100% rename from doc/content/devices/the-things-uno/TheThingsUnoJoinAccept.png rename to doc/content/devices/models/the-things-uno/TheThingsUnoJoinAccept.png diff --git a/doc/content/devices/the-things-uno/TheThingsUnoLiveData.png b/doc/content/devices/models/the-things-uno/TheThingsUnoLiveData.png similarity index 100% rename from doc/content/devices/the-things-uno/TheThingsUnoLiveData.png rename to doc/content/devices/models/the-things-uno/TheThingsUnoLiveData.png diff --git a/doc/content/devices/the-things-uno/TheThingsUnoOverview.png b/doc/content/devices/models/the-things-uno/TheThingsUnoOverview.png similarity index 100% rename from doc/content/devices/the-things-uno/TheThingsUnoOverview.png rename to doc/content/devices/models/the-things-uno/TheThingsUnoOverview.png diff --git a/doc/content/devices/the-things-uno/TheThingsUnoRawData.png b/doc/content/devices/models/the-things-uno/TheThingsUnoRawData.png similarity index 100% rename from doc/content/devices/the-things-uno/TheThingsUnoRawData.png rename to doc/content/devices/models/the-things-uno/TheThingsUnoRawData.png diff --git a/doc/content/devices/the-things-uno/TheThingsUnoRawData2.png b/doc/content/devices/models/the-things-uno/TheThingsUnoRawData2.png similarity index 100% rename from doc/content/devices/the-things-uno/TheThingsUnoRawData2.png rename to doc/content/devices/models/the-things-uno/TheThingsUnoRawData2.png diff --git a/doc/content/devices/the-things-uno/Things Uno.png b/doc/content/devices/models/the-things-uno/Things Uno.png similarity index 100% rename from doc/content/devices/the-things-uno/Things Uno.png rename to doc/content/devices/models/the-things-uno/Things Uno.png diff --git a/doc/content/devices/the-things-uno/_index.md b/doc/content/devices/models/the-things-uno/_index.md similarity index 94% rename from doc/content/devices/the-things-uno/_index.md rename to doc/content/devices/models/the-things-uno/_index.md index 51ccfb8bb9..9d1ebac31a 100755 --- a/doc/content/devices/the-things-uno/_index.md +++ b/doc/content/devices/models/the-things-uno/_index.md @@ -1,7 +1,8 @@ --- title: "The Things Uno" description: "" -weight: +weight: +aliases: ["/devices/the-things-uno"] --- {{< figure src="TheThingsUno.png" alt="The Things Uno" class="float plain" >}} @@ -10,7 +11,7 @@ This section will help you get started with using The Things Uno on {{% tts %}}. -**The Things Uno** is based on the [Arduino Leonardo](https://store.arduino.cc/usa/leonardo) (not the Arduino Uno) with an added Microchip LoRaWAN® module ([RN2483](https://www.microchip.com/wwwproducts/en/RN2483) or [RN2903](https://www.microchip.com/wwwproducts/en/RN2903)). +**The Things Uno** is based on the [Arduino Leonardo](https://store.arduino.cc/usa/leonardo) (not the Arduino Uno) with an added Microchip LoRaWAN® module ([RN2483](https://www.microchip.com/wwwproducts/en/RN2483) or [RN2903](https://www.microchip.com/wwwproducts/en/RN2903)). The Things Uno is fully compatible with the Arduino software also known as the Arduino Integrated Development Environment (IDE) and the existing Arduino shields. @@ -30,7 +31,7 @@ In the **Library Manager** window, search for `TheThingsNetwork` Arduino library ## Connecting Things Uno to your Computer -To begin, connect your Things Uno to the computer using a micro-USB cable. +To begin, connect your Things Uno to the computer using a micro-USB cable. In the Arduino IDE, select **Tools → Board → Arduino Leonardo** from the menu bar. This will tell your Arduino IDE to upload sketches to your Things Uno board. @@ -68,7 +69,7 @@ Select **Sketch → Include Library → The Things Network** from the me #include ``` -This will import **The Things Network** Arduino library to your sketch and provide you with some useful functions to work with LoRaWAN. +This will import **The Things Network** Arduino library to your sketch and provide you with some useful functions to work with LoRaWAN. Type the following lines to create two serial port objects for **Serial** and **Serial1**. @@ -76,7 +77,7 @@ Type the following lines to create two serial port objects for **Serial** and ** #define loraSerial Serial1 #define debugSerial Serial ``` - + The **Serial** object allows communication between **The Things Uno** and your **computer**. Also, the **Serial1** object allows communication between **The Things Uno** and the **Microchip LoRa module**. Type the following line to define the frequency plan of your Things Uno. Replace `REPLACE_ME` with `TTN_FP_EU868` or `TTN_FP_US915` depending on the frequency plan of your Things Uno and your country/region. @@ -96,7 +97,6 @@ TheThingsNetwork ttn(loraSerial, debugSerial, freqPlan); This will create a `TheThingsNetwork` object named `ttn` with `loraSerial`, `debugSerial`, and `freqPlan` as inputs. - Type the following lines inside the `setup()` function. ``` @@ -104,10 +104,9 @@ debugSerial.begin(9600); loraSerial.begin(57600); ``` -This will call the `begin()` function for each serial port object to set the baud rate for serial data transmission. Use `9600` and `57600` bits per second for `debugSerial` and `loraSerial` respectively. +This will call the `begin()` function for each serial port object to set the baud rate for serial data transmission. Use `9600` and `57600` bits per second for `debugSerial` and `loraSerial` respectively. - -Type the following lines just after the `loraSerial.begin(57600);`. +Type the following lines just after the `loraSerial.begin(57600);`. ``` while (!debugSerial) { @@ -126,23 +125,23 @@ ttn.showStatus(); The `showStatus()` function retrieves some useful device-specific information from the Microchip LoRa module and prints them on the **Serial Monitor**. -After editing your sketch, **save** it as `TheThingsUnoTest` by selecting **File → Save As** from the menu bar. +After editing your sketch, **save** it as `TheThingsUnoTest` by selecting **File → Save As** from the menu bar. Once completed your Arduino sketch should look something like this: -***TheThingsUnoTest.ino*** +**_TheThingsUnoTest.ino_** ``` #include - + #define loraSerial Serial1 #define debugSerial Serial - + // Replace REPLACE_ME with TTN_FP_EU868 or TTN_FP_US915 #define freqPlan TTN_FP_EU868 - + TheThingsNetwork ttn(loraSerial, debugSerial, freqPlan); - + void setup() { loraSerial.begin(57600); @@ -156,7 +155,7 @@ void setup() ttn.showStatus(); } - + void loop() { } @@ -164,7 +163,7 @@ void loop() Make sure that your Things Uno board is connected to your computer and select the **Upload** button in the toolbar. The IDE verifies your sketch again and uploads it to your Things Uno. During this process, the **TX/RX** LEDs on your Things Uno board should blink, indicating the information is traveling between the Things Uno and your computer. -Once uploaded, your sketch will immediately start to run but you cannot see any output unless you open the Arduino **Serial Monitor**. The Arduino Serial Monitor is a tool that can be used to print information passing through the serial port. +Once uploaded, your sketch will immediately start to run but you cannot see any output unless you open the Arduino **Serial Monitor**. The Arduino Serial Monitor is a tool that can be used to print information passing through the serial port. In the Arduino IDE, select **Tools → Serial Monitor** from the menu bar. Once open the Serial Monitor prints something similar to the following output. @@ -185,9 +184,9 @@ Total airtime: 0.00 s ## Registering The Things Uno with {{% tts %}} -It’s time to register your Things Uno with {{% tts %}}. +It’s time to register your Things Uno with {{% tts %}}. -On the **Applications** page, select your application to go to its overview page. +On the **Applications** page, select your application to go to its overview page. Select **+ Add end device** in the bottom-right of the page. @@ -207,8 +206,8 @@ Under **Select the end device**, select the following mandatory fields. - Brand - `The Things Products` - Model – `The Things Uno` - Hardware Ver. – `1.0` -- Firmware Ver. – `quickstart` or `abp`. We recommend you to use `quickstart` as it supports [OTAA]({{< ref "devices/abp-vs-otaa#otaa" >}}). -- Profile (Region) – Choose `EU_863_870` or `US_902_928` to match with your board. +- Firmware Ver. – `quickstart` or `abp`. We recommend you to use `quickstart` as it supports [OTAA]({{< ref "devices/concepts/abp-vs-otaa#otaa" >}}). +- Profile (Region) – Choose `EU_863_870` or `US_902_928` to match with your board. {{< figure src="RegisterEndDeviceRepo.png" alt="Register End Device from LoRaWAN repository" >}} @@ -217,12 +216,12 @@ Under the **Enter registration data**, select/fill the following mandatory field If you have selected `quickstart` from the **Firmware Ver.** in the previous step: - Frequency plan – Select `Europe 863-870 MHz (SF9 for RX2 - recommended)` for **EU_863_870** or `United States 902-928 MHz, FSB2 (used by TTN)` for **US_902_928**. -- AppEUI – Copy the **AppEUI** from the output printed by the ***TheThingsUnoTest*** sketch. -- DevEUI – Copy the **DevEUI** from the output printed by the ***TheThingsUnoTest*** sketch. +- AppEUI – Copy the **AppEUI** from the output printed by the **_TheThingsUnoTest_** sketch. +- DevEUI – Copy the **DevEUI** from the output printed by the **_TheThingsUnoTest_** sketch. - AppKey – Select **Generate** button to generate an **AppKey**. - End device ID – Give your device a unique human-readable [identifier]({{< ref "reference/id-eui-constraints" >}}). -Select the **Register end device** button. +Select the **Register end device** button. {{< figure src="RegisterEndDeviceRepoOTAA.png" alt="Register End Device from LoRaWAN repository OTAA" >}} @@ -234,7 +233,7 @@ If you have selected `abp` from the **Firmware Ver.** in the previous step: - NwkSKey– Select **Generate** button. - End device ID – Give your device a unique human-readable [identifier]({{< ref "reference/id-eui-constraints" >}}). -Select the **Register end device** button. +Select the **Register end device** button. {{< figure src="RegisterEndDeviceRepoABP.png" alt="Register End Device from LoRaWAN repository ABP" >}} @@ -244,7 +243,7 @@ Once registered, you will be redirected to the overview page of the newly regist In this section, you will learn how to use the **Over the air activation (OTAA)** method to activate your Things Uno with {{% tts %}}. To do so you had to register your Things Uno with {{% tts %}} using **From the LoRaWAN Device Repository** with the `quickstart` firmware version. -Open the ***TheThingsUnoTest*** sketch with your Arduino IDE if not already open. +Open the **_TheThingsUnoTest_** sketch with your Arduino IDE if not already open. Type the following code after the `#include `. @@ -299,18 +298,18 @@ Your device is now activated and ready to send/receive messages to/from {{% tts With {{% tts %}}, you can send small packets of data under certain limitations. The following example will explain to you how to send the status of the Things Uno’s built-in LED (pin 13) as a simple message. -In the Arduino IDE, go back to your ***TheThingsUnoTest*** sketch and replace the `loop()` function with the following lines: +In the Arduino IDE, go back to your **_TheThingsUnoTest_** sketch and replace the `loop()` function with the following lines: ``` debugSerial.println("-- LOOP"); - + // Prepare array of 1 byte to indicate LED status byte data[1]; data[0] = (digitalRead(LED_BUILTIN) == HIGH) ? 1 : 0; - + // Send it off ttn.sendBytes(data, sizeof(data)); - + delay(10000); ``` @@ -327,11 +326,11 @@ Sending: mac tx uncnf 1 with 1 bytes Successful transmission ``` -The above output indicates that the data has been sent from your Things Uno side to {{% tts %}}. +The above output indicates that the data has been sent from your Things Uno side to {{% tts %}}. ## Decoding the received messages -Now let’s confirm whether the data has been received to {{% tts %}}. On the **Applications** page, select the **Live data** tab. You should now see the messages come in. What you see on the **Live data** tab are the raw payloads in hex-formatted, space-separated bytes. +Now let’s confirm whether the data has been received to {{% tts %}}. On the **Applications** page, select the **Live data** tab. You should now see the messages come in. What you see on the **Live data** tab are the raw payloads in hex-formatted, space-separated bytes. {{< figure src="TheThingsUnoRawData.png" alt="Raw payload" >}} @@ -348,9 +347,9 @@ function Decoder(bytes, port) { // Decode an uplink message from a buffer // (array) of bytes to an object of fields. var decoded = {}; - + if (port === 1) decoded.led = bytes[0]; - + return decoded; } ``` diff --git a/doc/content/devices/troubleshooting/_index.md b/doc/content/devices/troubleshooting/_index.md index c1689b26cf..621558beca 100644 --- a/doc/content/devices/troubleshooting/_index.md +++ b/doc/content/devices/troubleshooting/_index.md @@ -145,7 +145,7 @@ The `ns.down.data.schedule.fail` event, that can be noticed in the Live data tab The `ns.down.data.schedule.fail` event usually occurs with the following errors: - `no_absolute_gateway_time`: Downlinks are being scheduled with the absolute time, and the absolute time of the Gateway Server is not in sync with the absolute time of the gateway. To sync them, a gateway has to either report its GPS time, or transmit five downlink frames in order for Gateway Server to infer its absolute time by observing RTTs. -- `scheduling_conflict`: Devices are synchronized, i.e. a number of devices are sending joins or uplinks at the same time. To avoid device synchronization, devices need to be configured to initiate joins or send uplinks at random times or with random delays. You can also try with improving the network coverage in your area. See [Best Practices]({{< ref "/devices/best-practices#synchronization-backoff-and-jitter" >}}) for more info about device synchronization. +- `scheduling_conflict`: Devices are synchronized, i.e. a number of devices are sending joins or uplinks at the same time. To avoid device synchronization, devices need to be configured to initiate joins or send uplinks at random times or with random delays. You can also try with improving the network coverage in your area. See [Best Practices]({{< ref "/devices/concepts/best-practices#synchronization-backoff-and-jitter" >}}) for more info about device synchronization. We also advise to double check your network connection. If the connection between the gateway and the Network Server is slow, downlink messages could be sent too late. For example, this can happen in case of: @@ -166,7 +166,7 @@ Read more about skipping payload crypto option on an [application level]({{< ref Your device probably does not have a good network coverage. Some common reasons: - The device is using SF7, while it should be using a higher SF for better coverage and reach. -- There might be a conflict in receiving uplinks due to [synchronization of devices]({{< ref "/devices/best-practices#synchronization-backoff-and-jitter" >}}). +- There might be a conflict in receiving uplinks due to [synchronization of devices]({{< ref "/devices/concepts/best-practices#synchronization-backoff-and-jitter" >}}). Check your network coverage, and make sure your devices are within your gateway's reach and are using a suitable SF. @@ -178,19 +178,19 @@ Possible causes and solutions: - The uplinks could be coming from other devices in the gateways range, that are not registered in {{% tts %}}. In this case, you can just ignore them. - If you are facing this while trying to activate a device, please double-check that the DevEUI and JoinEUI/AppEUI on {{% tts %}} and on your device match. - FCnt mismatch - - For ABP devices, the FCnt mismatch might occur if the device resets while the **Reset Frame Counters** option for the device is disabled. Try enabling the **Reset Frame Counters** option in the device's overview in {{% tts %}} Console, or by setting [MAC commands]({{< ref "/devices/mac-settings#available-mac-settings" >}}) using the CLI. + - For ABP devices, the FCnt mismatch might occur if the device resets while the **Reset Frame Counters** option for the device is disabled. Try enabling the **Reset Frame Counters** option in the device's overview in {{% tts %}} Console, or by setting [MAC commands]({{< ref "/devices/configuring-devices/mac-settings#available-mac-settings" >}}) using the CLI. - For OTAA devices, the FCnt mismatch might occur due to missing packets. The maximum FCnt gap between two consecutive uplinks is `16384` according to the LoRaWAN specification. Try re-joining your OTAA device. - Using inappropriate frequencies - - This case applies only to ABP devices and EU/IN/AS frequency bands. Since the Network Server is initially accepting uplinks from devices only in default channels, uplinks from the device that is using non-default channels are dropped. In this case, **Factory Preset Frequencies** have to be set either in device's overview in {{% tts %}} Console, or by setting [MAC commands]({{< ref "/devices/mac-settings#available-mac-settings" >}}) using the CLI. If these settings are applied to an existing device, you might need to reset the device as well. + - This case applies only to ABP devices and EU/IN/AS frequency bands. Since the Network Server is initially accepting uplinks from devices only in default channels, uplinks from the device that is using non-default channels are dropped. In this case, **Factory Preset Frequencies** have to be set either in device's overview in {{% tts %}} Console, or by setting [MAC commands]({{< ref "/devices/configuring-devices/mac-settings#available-mac-settings" >}}) using the CLI. If these settings are applied to an existing device, you might need to reset the device as well. - Session keys mismatch - For ABP devices, if there is a mismatch between session keys (AppSKey and NwkSKey) that are hardcoded in the device and those used when registering the device on {{% tts %}}, uplinks will not be seen in the device's Live data tab. Please cross-check that your device's session keys match the ones used upon registration on {{% tts %}}. -This problem can also occur after [migrating an active device session]({{< ref "/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session" >}}) from {{% ttnv2 %}} to {{% tts %}}, for devices that transmit uplinks on frequencies that are not part of the standard [frequency plans]({{< ref "/reference/frequency-plans" >}}) used by {{% tts %}}. The issue arises from the fact that factory preset frequencies were not stored in {{% ttnv2 %}}, so they are not present in the [JSON file]({{< ref "/the-things-stack/migrating/device-json" >}}) used for importing devices in {{% tts %}}. There are two possible solutions: +This problem can also occur after [migrating an active device session]({{< ref "/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session" >}}) from {{% ttnv2 %}} to {{% tts %}}, for devices that transmit uplinks on frequencies that are not part of the standard [frequency plans]({{< ref "/reference/frequency-plans" >}}) used by {{% tts %}}. The issue arises from the fact that factory preset frequencies were not stored in {{% ttnv2 %}}, so they are not present in the [JSON file]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-json" >}}) used for importing devices in {{% tts %}}. There are two possible solutions: - If the end device can be reset, i.e. if it can perform a re-join to {{% tts %}} network or at least reset frame counters (for ABP devices) - Go to **General settings** in the device overview in {{% tts %}} Console, navigate to **Network layer → Advanced MAC settings** and set the **Factory preset frequencies**, then click the **Reset session and MAC state** button. By resetting the device, a new session will be established with {{% tts %}} Network Server and the uplinks on the defined frequencies will be accepted. - If the end device cannot be reset - - Changes related to factory preset frequencies take effect only after a device reset, but applying the fix explained above will break the existing device session. If you really want to keep the active session or simply cannot reset the device physically, you can try adding the frequency channels manually in the `mac_state.current.channels` and `mac_state.desired_channels` parameters of the [JSON file]({{< ref "/the-things-stack/migrating/device-json" >}}) before you import it to {{% tts %}}. + - Changes related to factory preset frequencies take effect only after a device reset, but applying the fix explained above will break the existing device session. If you really want to keep the active session or simply cannot reset the device physically, you can try adding the frequency channels manually in the `mac_state.current.channels` and `mac_state.desired_channels` parameters of the [JSON file]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-json" >}}) before you import it to {{% tts %}}. ## I notice a delay in scheduling Class C downlinks. What can I do to fix it? @@ -220,4 +220,4 @@ This error indicates that your end device was added from the [Device Repository] The `COLLISION_PACKET` error occurs when downlink transmissions overlap - this happens when two or more packets overlap in time and use the same spreading factor, bandwith and frequency plan settings. -To avoid packet collisions, users can enable server-side buffering of donwlink messages. If server-side buffering is enabled, the Gateway Server schedules the downlink message to be sent after the downlink message that was already queued but not sent yet, so that their transmissions don't overlap. To enable this, navigate to your gateway's **General settings** section, expand the **LoRaWAN** section and **Enable** the **Schedule downlink late** option by ticking the box. Note that this is a recommended setting for gateways that use [UDP packet forwarder]({{< ref "/gateways/concepts/udp" >}}). \ No newline at end of file +To avoid packet collisions, users can enable server-side buffering of donwlink messages. If server-side buffering is enabled, the Gateway Server schedules the downlink message to be sent after the downlink message that was already queued but not sent yet, so that their transmissions don't overlap. To enable this, navigate to your gateway's **General settings** section, expand the **LoRaWAN** section and **Enable** the **Schedule downlink late** option by ticking the box. Note that this is a recommended setting for gateways that use [UDP packet forwarder]({{< ref "/gateways/concepts/udp" >}}). diff --git a/doc/content/gateways/concepts/_index.md b/doc/content/gateways/concepts/_index.md index e14c7c29d9..bc4f76ff8b 100644 --- a/doc/content/gateways/concepts/_index.md +++ b/doc/content/gateways/concepts/_index.md @@ -4,4 +4,4 @@ description: "Guides on basic concepts of working with The Things Stack and Gate weight: -3 --- -Learn the basic concepts of working with {{% tts %}} and Gateways through the subtopics in the **left menu**. \ No newline at end of file +Learn the basic concepts of working with {{% tts %}} and Gateways. diff --git a/doc/content/gateways/models/_index.md b/doc/content/gateways/models/_index.md index 86b365b831..289ef617f2 100644 --- a/doc/content/gateways/models/_index.md +++ b/doc/content/gateways/models/_index.md @@ -4,4 +4,4 @@ description: "Guides on connecting gateways to The Things Stack by model" weight: -2 --- -This subsection contains comprehensive instructions for connecting some of the popular LoRaWAN® gateway models to {{% tts %}}. Select the gateway model you want to learn about from the **left menu**. +This subsection contains comprehensive instructions for connecting some of the popular LoRaWAN® gateway models to {{% tts %}} diff --git a/doc/content/integrations/cloud-integrations/azure-iot-central/device-templates.md b/doc/content/integrations/cloud-integrations/azure-iot-central/device-templates.md index 528fdf21a5..0413eaeb93 100644 --- a/doc/content/integrations/cloud-integrations/azure-iot-central/device-templates.md +++ b/doc/content/integrations/cloud-integrations/azure-iot-central/device-templates.md @@ -8,11 +8,11 @@ Azure IoT Central allows users to model the telemetry and device properties usin -As part of this tutorial we will build a small DTDL model for [The Things Uno]({{< ref "/devices/the-things-uno" >}}) which allows us to control the built in LED of the device. +As part of this tutorial we will build a small DTDL model for [The Things Uno]({{< ref "/devices/models/the-things-uno" >}}) which allows us to control the built in LED of the device. ## Prerequisites -1. A [The Things Uno]({{< ref "/devices/the-things-uno" >}}) registered in your end device, with the end device version identifiers set, and using the `quickstart` sketch. +1. A [The Things Uno]({{< ref "/devices/models/the-things-uno" >}}) registered in your end device, with the end device version identifiers set, and using the `quickstart` sketch. > You can check if the end device version identifiers are set by checking the Console end device overview, under the **Hardware** section. @@ -29,7 +29,7 @@ A DTDL model ID is a [**_Digital Twin Modeling Identifier_**](https://github.com 3. `{modelID}` is replaced by the normalized form of the end device version identifiers `model_id` field. 4. `{hwVersion}` is replaced by the normalized form of the end device version identifiers `hardware_version` field, prepended by `hw` (as versions may start with numeric values, but DTMI segments cannot start with a numeric value). 5. `{fwVersion}` is replaced by the normalized form of the end device version identifiers `firmware_version` field, -prepended by `fw` (using the same reasoning as above). + prepended by `fw` (using the same reasoning as above). 6. `{bandID}` is replaced by the normalized form of the end device version identifiers `{band_id}` field. 7. `{generation}` is currently always replaced by `1`. @@ -64,10 +64,7 @@ The top level object of a DTDL model is an [_Interface_](https://github.com/Azur "displayName": { "en": "The Things Uno" }, - "@context": [ - "dtmi:iotcentral:context;2", - "dtmi:dtdl:context;2" - ] + "@context": ["dtmi:iotcentral:context;2", "dtmi:dtdl:context;2"] } ``` @@ -130,10 +127,7 @@ We can now put together our intermediate model, by providing the two properties "displayName": { "en": "The Things Uno" }, - "@context": [ - "dtmi:iotcentral:context;2", - "dtmi:dtdl:context;2" - ] + "@context": ["dtmi:iotcentral:context;2", "dtmi:dtdl:context;2"] } ``` @@ -371,10 +365,7 @@ We can now put everything together and thus obtain the following updated model: "displayName": { "en": "The Things Uno" }, - "@context": [ - "dtmi:iotcentral:context;2", - "dtmi:dtdl:context;2" - ] + "@context": ["dtmi:iotcentral:context;2", "dtmi:dtdl:context;2"] } ``` diff --git a/doc/content/integrations/guides/build-an-end-to-end-solution-gn/_index.md b/doc/content/integrations/guides/build-an-end-to-end-solution-gn/_index.md index a49d4c0c64..c028c81fad 100644 --- a/doc/content/integrations/guides/build-an-end-to-end-solution-gn/_index.md +++ b/doc/content/integrations/guides/build-an-end-to-end-solution-gn/_index.md @@ -1,10 +1,10 @@ --- title: "Build an Application using Generic Node Sensor Edition and Kuando Busylight" description: "" -weight: +weight: --- -This section shows how to build an end-to-end solution to control the [Kuando Busylight](https://busylight.com/busylight-iot/) with the [Generic Node Sensor Edition](https://www.thethingsshop.com/products/generic-node-sensor-edition) (GNSE). +This section shows how to build an end-to-end solution to control the [Kuando Busylight](https://busylight.com/busylight-iot/) with the [Generic Node Sensor Edition](https://www.thethingsshop.com/products/generic-node-sensor-edition) (GNSE). ## Registering {{% ttig %}} @@ -37,12 +37,12 @@ To decode the payload you will need a [payload formatter]({{< ref "/integrations Create a payload formatter for the uplink messages using the following JavaScript formatter code: ```js -function decodeUplink(input){ +function decodeUplink(input) { var data = {}; - data.batt_volt = (input.bytes[0]/10) - data.temperature = (((input.bytes[1] <<8) + input.bytes[2]) - 500)/10; - data.humidity = ((input.bytes[3] << 8) + input.bytes[4])/10; - data.button_press = input.bytes[5] + data.batt_volt = input.bytes[0] / 10; + data.temperature = ((input.bytes[1] << 8) + input.bytes[2] - 500) / 10; + data.humidity = ((input.bytes[3] << 8) + input.bytes[4]) / 10; + data.button_press = input.bytes[5]; return { data: data, @@ -84,8 +84,8 @@ Run `yarn install` or `yarn` to install all its dependencies. Clone the GitHub repository to your computer by typing the command `git clone git@github.com:kschiffer/tts-demo-app.git` -Create a file named `config.env` inside the `tts-demo-app` directory. Use the following commands: - +Create a file named `config.env` inside the `tts-demo-app` directory. Use the following commands: + ```bash cd tts-demo-app vim config.env @@ -130,7 +130,7 @@ Press the push button a few more times and see how your chart behaves in time. ## Adding Kuando Busylight -Kuando BusyLight is a light device that you can control using LoRaWAN downlinks. It is a [class C]({{< ref "/devices/class-c" >}}) end device that opens continuous receive windows so it is capable of receiving downlinks anytime. +Kuando BusyLight is a light device that you can control using LoRaWAN downlinks. It is a [class C]({{< ref "/devices/configuring-devices/class-c" >}}) end device that opens continuous receive windows so it is capable of receiving downlinks anytime. {{< figure src="busylight.png" alt="" >}} @@ -142,11 +142,11 @@ Let’s have a look at how to schedule downlink messages from {{% tts %}} applic In {{% tts %}} Console select the **Messaging** tab and then select the **Downlink** tab. Then configure the downlink as follows: - - **Insert Mode**: **Replace Downlink Queue** - - **FPort**: `15` (as per the datasheet) - - **Payload type**: **Bytes** - - **Payload**: type in **FF FF FF FF 00** (this makes the Busylight solid white, no blinking) - +- **Insert Mode**: **Replace Downlink Queue** +- **FPort**: `15` (as per the datasheet) +- **Payload type**: **Bytes** +- **Payload**: type in **FF FF FF FF 00** (this makes the Busylight solid white, no blinking) + Here is the payload structure for the downlink messages for your reference: {{< figure src="busylight-payload-structure.png" alt="" >}} @@ -199,4 +199,4 @@ Save the configuration file (`[esc][:wq][enter]`), source it (`source config.env Now press the push button on GNSE. The Busylight will turn ON. Press the push button again. The Busylight will turn OFF. -This solution can be customized to meet your specific needs and ideas, such as changing the Busylight's color to red when the temperature exceeds a set threshold. \ No newline at end of file +This solution can be customized to meet your specific needs and ideas, such as changing the Busylight's color to red when the temperature exceeds a set threshold. diff --git a/doc/content/integrations/ifttt/_index.md b/doc/content/integrations/ifttt/_index.md index a5898cc262..dbcb8db52c 100644 --- a/doc/content/integrations/ifttt/_index.md +++ b/doc/content/integrations/ifttt/_index.md @@ -16,4 +16,4 @@ To connect {{% tts %}} to IFTTT, [Node-RED](https://nodered.org/) will also be u 2. A running instance of Node-RED. -Detailed instructions on using IFTTT with {{% tts %}} can be found through the subtopics in the **left menu**. \ No newline at end of file +Detailed instructions on using IFTTT with {{% tts %}} are in the topics below. diff --git a/doc/content/integrations/storage/_index.md b/doc/content/integrations/storage/_index.md index ac3e11726b..b289e9dafd 100644 --- a/doc/content/integrations/storage/_index.md +++ b/doc/content/integrations/storage/_index.md @@ -2,7 +2,8 @@ title: Storage Integration description: "" summary: Persistent storage for upstream messages. -distributions: ["Cloud", "Dedicated Cloud", "Enterprise", "AWS Launcher", "Community"] +distributions: + ["Cloud", "Dedicated Cloud", "Enterprise", "AWS Launcher", "Community"] --- The Storage Integration allows storing received upstream messages in a persistent database, and retrieving them at a later time. @@ -30,4 +31,4 @@ The Storage Integration should not be used for querying realtime data. For scala - Long-term storage of historical data for end-devices. - No need to maintain a connection with {{% tts %}} at all times, e.g. for end devices that send messages infrequently. -Detailed instructions about storage integration can be found through the subtopics in the **left menu**. \ No newline at end of file +Detailed instructions about storage integration are in the topics below. diff --git a/doc/content/reference/adr/_index.md b/doc/content/reference/adr/_index.md index 1084534072..59f164e59f 100644 --- a/doc/content/reference/adr/_index.md +++ b/doc/content/reference/adr/_index.md @@ -40,8 +40,10 @@ The implementation is based on Semtech's recommended algorithm described in [thi 1. Determine [the maximum SNR over recent transmissions](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L218) 2. Determine [the minimum SNR to demodulate an uplink given the current parameters](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L232) 3. Calculate [the margin to further optimize the data rate](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L236) - - Part of this is configurable per device (if you use the CLI) - - If less measurements (uplinks) are available than necessary, [include a safety margin](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L238-L240) + +- Part of this is configurable per device (if you use the CLI) +- If less measurements (uplinks) are available than necessary, [include a safety margin](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L238-L240) + 4. [Increase the data rate as long as there's enough margin](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L251-L262) 5. If there's still margin after reaching the maximum data rate, [decrease the transmit power](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L273-L281) 6. Depending on packet loss, [increase the number of retransmissions](https://github.com/TheThingsNetwork/lorawan-stack/blob/5a816e8171f993db9659566286d45725698f032e/pkg/networkserver/mac/adr.go#L288-L296) @@ -76,7 +78,7 @@ The Network Server uses the ADR margin of 15, but this value can be configured p ttn-lw-cli end-devices set --application-id --device-id --mac-settings.adr.mode.dynamic.margin ``` -Keep in mind that changes to `mac-settings.adr.mode.dynamic.` are persistent and will be present even after a device reset/rejoin. Read the [MAC Settings]({{< ref "/devices/mac-settings" >}}) section for detailed info. +Keep in mind that changes to `mac-settings.adr.mode.dynamic.` are persistent and will be present even after a device reset/rejoin. Read the [MAC Settings]({{< ref "/devices/configuring-devices/mac-settings" >}}) section for detailed info. #### Examples @@ -86,7 +88,7 @@ In practice, the ADR margin value should be tuned until the optimization target ##### Case 1: ADR margin set to default -The default ADR margin value in {{% tts %}} is 15, while the minimum SNR required to demodulate a message for DR3 is 12.5. +The default ADR margin value in {{% tts %}} is 15, while the minimum SNR required to demodulate a message for DR3 is 12.5. First, the maximum SNR is computed for recent uplinks. In this example, the `SNRmax` is 7. diff --git a/doc/content/reference/components/_index.md b/doc/content/reference/components/_index.md index 556fe9c135..30cc4e51de 100644 --- a/doc/content/reference/components/_index.md +++ b/doc/content/reference/components/_index.md @@ -4,4 +4,4 @@ description: "" aliases: [/components] --- -This section contains detailed descriptions of each of {{% tts %}} components and can be found in the **left menu**. +This section contains detailed descriptions of each of {{% tts %}} components. diff --git a/doc/content/reference/components/cli.md b/doc/content/reference/components/cli.md index 923304ad2d..4928a19b18 100644 --- a/doc/content/reference/components/cli.md +++ b/doc/content/reference/components/cli.md @@ -82,7 +82,7 @@ The CLI can be used to subscribe to uplink traffic. See the [Getting Started gui ## Downlink Queue -The CLI can manage the downlink queue of end devices. See the [Downlink Queue Operations guide]({{< ref "/devices/downlink-queue-ops" >}}) for more details. +The CLI can manage the downlink queue of end devices. See the [Downlink Queue Operations guide]({{< ref "/devices/configuring-devices/downlink-queue-ops" >}}) for more details. ## Events diff --git a/doc/content/reference/components/device-claiming-server.md b/doc/content/reference/components/device-claiming-server.md index 57cff96fd2..2f34426e59 100644 --- a/doc/content/reference/components/device-claiming-server.md +++ b/doc/content/reference/components/device-claiming-server.md @@ -9,4 +9,4 @@ The Device Claiming Server allows users to claim devices and gateways in a secur The Device Claiming Server takes care of checking verifying ownership and transferring the device or gateway from a source to a target security domain. -For more information about claiming end devices, see [Device Claiming]({{< ref "/devices/device-claiming" >}}). +For more information about claiming end devices, see [Device Claiming]({{< ref "/devices/concepts/device-claiming" >}}). diff --git a/doc/content/reference/fuota/_index.md b/doc/content/reference/fuota/_index.md index a62209de19..806aa9972d 100644 --- a/doc/content/reference/fuota/_index.md +++ b/doc/content/reference/fuota/_index.md @@ -21,9 +21,9 @@ See the [FUOTA Process Summary document from LoRa Alliance](https://lora-allianc On a high level, a FUOTA process implies the following steps: -- Server enables [class C]({{< ref "/devices/class-c" >}}) and joins a [multicast]({{< ref "/devices/multicast" >}}) group +- Server enables [class C]({{< ref "/devices/configuring-devices/class-c" >}}) and joins a [multicast]({{< ref "/devices/configuring-devices/multicast" >}}) group - Server signs the firmware update and splits it in chunks -- Server schedules each update chunk as a [downlink message]({{< ref "/integrations/mqtt#publishing-downlink-traffic" >}}) to the multicast group +- Server schedules each update chunk as a [downlink message]({{< ref "/integrations/mqtt#publishing-downlink-traffic" >}}) to the multicast group - Server verifies that the device has received all chunks, synthesizes them and verifies the update signature - Device applies the firmware update - Device sends a `firmware update complete` uplink message @@ -41,7 +41,7 @@ The preferred fragment size depends on the available data rate, which depends on ### Duty Cycle -Using multiple gateways for updating firmware on the same group of end devices is recommended because of duty cycle restrictions and to avoid packet loss. It is also recommended to use [class B]({{< ref "/devices/class-b" >}}), which takes longer to update but it is likely better for duty cycle distribution. +Using multiple gateways for updating firmware on the same group of end devices is recommended because of duty cycle restrictions and to avoid packet loss. It is also recommended to use [class B]({{< ref "/devices/configuring-devices/class-b" >}}), which takes longer to update but it is likely better for duty cycle distribution. ## Useful Links @@ -51,4 +51,4 @@ For a beginners guide on using multicast and FUOTA, check out [this video](https Regarding devices that implement FUOTA, we recommend you to check out our [Generic Node](https://www.genericnode.com/docs/). -See [this link](https://github.com/ARMmbed/mbed-os-example-lorawan-fuota) for an example application that implements multicast FUOTA for MBed OS 5. \ No newline at end of file +See [this link](https://github.com/ARMmbed/mbed-os-example-lorawan-fuota) for an example application that implements multicast FUOTA for MBed OS 5. diff --git a/doc/content/the-things-stack/concepts/spec-regional-parameters/index.md b/doc/content/the-things-stack/concepts/spec-regional-parameters/index.md index 610385932a..5b28932a8e 100644 --- a/doc/content/the-things-stack/concepts/spec-regional-parameters/index.md +++ b/doc/content/the-things-stack/concepts/spec-regional-parameters/index.md @@ -35,4 +35,4 @@ The LoRaWAN specification versions are available from the [LoRa Alliance resourc The LoRaWAN Regional Parameters specification versions are available from the [LoRa Alliance resource hub](https://lora-alliance.org/resource-hub/). More information is also available in [The Things Network LoRaWAN documentation](https://www.thethingsnetwork.org/docs/lorawan/regional-parameters/). -In addition, {{% tts %}} supports Class A, B, C, and multicast group devices. See the [Class B]({{< ref "devices/class-b" >}}), [Class C]({{< ref "devices/class-c" >}}), and [Multicast]({{< ref "devices/multicast" >}}) references for special instructions when using these device classes. +In addition, {{% tts %}} supports Class A, B, C, and multicast group devices. See the [Class B]({{< ref "devices/configuring-devices/class-b" >}}), [Class C]({{< ref "devices/configuring-devices/class-c" >}}), and [Multicast]({{< ref "/devices/configuring-devices/multicast" >}}) references for special instructions when using these device classes. diff --git a/doc/content/the-things-stack/host/join-server/_index.md b/doc/content/the-things-stack/host/join-server/_index.md index f49f82df73..cf2ad9cae7 100644 --- a/doc/content/the-things-stack/host/join-server/_index.md +++ b/doc/content/the-things-stack/host/join-server/_index.md @@ -25,13 +25,14 @@ The Things Join Server operated by The Things Industries is configured in {{% tt If you have provisioner access to deployment of The Things Join Server, use the [Command-line Interface `ttjs`](https://www.npmjs.com/package/ttjs-cli) to provision devices in bulk. When it comes to using JoinEUIs for provisioning devices on The Things Join Server, there are two cases: + - If you are using The Things Join Server hosted by The Things Industries and you don't have your own EUI, you are free to use `70B3D57ED0000000`. On the other hand, if you do have your own EUI that you want to use, you need to [contact The Things Industries support](mailto:support@thethingsindustries.com) for assistance. - If you are using an externally hosted The Things Join Server, you must acquire your JoinEUI via IEEE. ## Device Claiming -The Things Join Server supports LoRaWAN Backend Interfaces 1.0 and 1.1 as well as device claiming. [Learn more about device claiming]({{< ref "/devices/device-claiming" >}}). +The Things Join Server supports LoRaWAN Backend Interfaces 1.0 and 1.1 as well as device claiming. [Learn more about device claiming]({{< ref "/devices/concepts/device-claiming" >}}). ## Security Features -The Things Join Server operated by The Things Industries supports pre-provisioned Microchip ATECC608 secure elements which provide enhanced hardware security protection for LoRaWAN devices. [Learn more about ATECC608 secure elements]({{< ref "/devices/atecc608a" >}}). +The Things Join Server operated by The Things Industries supports pre-provisioned Microchip ATECC608 secure elements which provide enhanced hardware security protection for LoRaWAN devices. [Learn more about ATECC608 secure elements]({{< ref "/devices/adding-devices/atecc608a" >}}). diff --git a/doc/content/the-things-stack/management/_index.md b/doc/content/the-things-stack/management/_index.md index 3d231d1fbe..932e46bd33 100644 --- a/doc/content/the-things-stack/management/_index.md +++ b/doc/content/the-things-stack/management/_index.md @@ -4,4 +4,4 @@ description: "" weight: 4 --- -This section provides guides on managing and customizing various aspects of {{% tts %}}, which are available in the **left menu**. +This section provides guides on managing and customizing various aspects of {{% tts %}}. diff --git a/doc/content/the-things-stack/migrating/configure-mac-settings.md b/doc/content/the-things-stack/migrating/configure-mac-settings.md index b86bd85b2a..9e6bf99eea 100644 --- a/doc/content/the-things-stack/migrating/configure-mac-settings.md +++ b/doc/content/the-things-stack/migrating/configure-mac-settings.md @@ -1,9 +1,14 @@ --- title: Fine-tuning MAC Settings for End Devices weight: 6 -aliases: [/the-things-stack/migrating-from-v2/configure-mac-settings, /getting-started/configure-mac-settings, /getting-started/migrating/configure-mac-settings] +aliases: + [ + /the-things-stack/migrating-from-v2/configure-mac-settings, + /getting-started/configure-mac-settings, + /getting-started/migrating/configure-mac-settings, + ] --- -MAC settings on {{% tts %}} are configurable per end device. See the [MAC settings guide]({{< ref "/devices/mac-settings" >}}) for instructions. +MAC settings on {{% tts %}} are configurable per end device. See the [MAC settings guide]({{< ref "/devices/configuring-devices/mac-settings" >}}) for instructions. Devices migrated from {{% ttnv2 %}} (The Things Network V2 or The Things Industries V2) are configured with an RX1 delay of 1 second, by default. In all {{% tts %}} deployments, the recommended RX1 delay is 5 seconds to accommodate for high latency backhauls and/or [peering with Packet Broker]({{< ref "/the-things-stack/packet-broker" >}}). diff --git a/doc/content/the-things-stack/migrating/device-csv.md b/doc/content/the-things-stack/migrating/device-csv.md deleted file mode 100644 index b03b866154..0000000000 --- a/doc/content/the-things-stack/migrating/device-csv.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: "CSV File Reference" -description: "" -weight: 9 -aliases: [/getting-started/device-csv, /getting-started/migrating/device-csv] ---- - -{{% tts %}} has support for importing end devices from CSV (comma-separated values) files. This is useful when batches of end devices are managed in Microsoft Excel or any other spreadsheet or database that can export to CSV file. - -The CSV import in {{% tts %}} uses the following settings: - -- Semicolon (`;`) as field delimiter. This makes working with Microsoft Excel and other spreadsheets convenient -- Header row is required -- On each row, the same number of fields as on the header line -- Use quotes to use `;` in a field value -- Use double quotes to escape quotes -- Unknown header columns are permitted and ignored - -The following columns are recognized: - -Column | Required | Alias | Format | Meaning ---- | --- | --- | --- | --- -`dev_eui` | **Yes** | | Hexadecimal string | LoRaWAN® DevEUI -`join_eui` | **Yes** | `app_eui` | Hexadecimal string | LoRaWAN JoinEUI (or AppEUI) -`id` | No | | Alphanumeric string, lowercase with hyphens | Device ID (falls back to DevEUI if not set) -`name` | No | | Free form | Name -`description` | No | | string | Optional, description of the device -`lorawan_version` | No * | | See [`MACVersion`]({{< ref "/reference/api/end_device#enum:MACVersion" >}}) | LoRaWAN version -`lorawan_phy_version` | No * | | See [`PHYVersion`]({{< ref "/reference/api/end_device#enum:PHYVersion" >}}) | LoRaWAN Regional Parameters version -`frequency_plan_id` | No * | | See [Frequency Plans]({{< ref "/reference/frequency-plans" >}}) | Frequency plan ID -`brand_id` | No | | Vendor ID string from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Device brand ID -`model_id` | No | | Model ID from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Device model ID -`firmware_version` | No | | Firmware version from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Firmware version -`hardware_version` | No | | Hardware version from [Device Repository]({{< ref "/integrations/payload-formatters/device-repo" >}}) | Hardware version -`band_id` | No | | See [Frequency Plans]({{< ref "/reference/frequency-plans" >}}) | LoRaWAN Band ID -`supports_class_c` | No | | boolean | `true` for Class C devices, `false` otherwise. -`app_key` | **Yes** | | Hexadecimal string | LoRaWAN AppKey -`nwk_key` | No | | Hexadecimal string | LoRaWAN NwkKey -`rx1_delay` | No | | string | 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]({{< ref "reference/api/end_device#message:MACSettings" >}}) for more information. -`supports_32_bit_f_cnt` | No | | boolean | `true` if device supports 32-bit frame counters, `false` if device only supports 16-bit frame counters. -`dev_addr` | **For existing session** | | Hexadecimal string | **Needed for ABP devices or when migrating OTAA devices with an existing session**. See [Device Address]({{< ref "/reference/glossary#device-address" >}}) for more information. -`app_s_key` | **For existing session** | | string | **Needed for ABP devices or when migrating OTAA devices with an existing session**. See [Application Session Key]({{< ref "reference/glossary#application-session-key" >}}) for more information. -`f_nwk_s_int_key` | **For existing session** | | string | Forwarding Network Session Integrity Key, also referred to as **Network Session Key** in LoRaWAN v1.0.x compatibility mode. See [SessionKeys]({{< ref "reference/api/end_device#message:SessionKeys" >}}) and [Forwarding Network Session Integrity Key]({{< ref "/reference/glossary#forwarding-network-session-integrity-key" >}}) for more information. -`last_f_cnt_up` | **For existing session** | | uint | Last uplink frame counter used. -`last_n_f_cnt_down` | **For existing session** | | uint | Last network downlink frame counter used. -`last_a_f_cnt_down` | **For existing session** | | uint | Last application downlink frame counter used. - -\* If you don't set this, you must set the fallback value when importing the CSV file. See [Importing devices]({{< ref "/the-things-stack/migrating/import-devices" >}}). - -## Example - -Minimal example: - -```csv -dev_eui;join_eui;frequency_plan_id;lorawan_version;lorawan_phy_version;app_key -1111111111111111;1111111111111111;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;11111111111111111111111111111111 -2222222222222222;2222222222222222;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;22222222222222222222222222222222 -3333333333333333;3333333333333333;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;33333333333333333333333333333333 -``` - -All columns for a LoRaWAN 1.0.4 device: - -```csv -id;dev_eui;join_eui;name;frequency_plan_id;lorawan_version;lorawan_phy_version;brand_id;model_id;hardware_version;firmware_version;band_id;app_key -test-one;1111111111111111;1111111111111111;Device 1;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;the-things-industries;generic-node-sensor-edition;1.0.4;1.0;EU_863_870;11111111111111111111111111111111 -test-two;2222222222222222;2222222222222222;Device 2;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;the-things-industries;generic-node-sensor-edition;1.0.4;1.0;EU_863_870;22222222222222222222222222222222 -test-three;3333333333333333;3333333333333333;Device 3;EU_863_870_TTN;MAC_V1_0_4;RP002_V1_0_3;the-things-industries;generic-node-sensor-edition;1.0.4;1.0;EU_863_870;33333333333333333333333333333333 -``` - -## Excel Template - -[Download the Excel template](../tts-end-devices-csv-template.xlsx). You can remove all columns that are not required (see above). - -To export for {{% tts %}}, go to **File**, **Save As** and select **Comma Separated Values** as file format. diff --git a/doc/content/the-things-stack/migrating/device-json.md b/doc/content/the-things-stack/migrating/device-json.md deleted file mode 100644 index bba7c56cb5..0000000000 --- a/doc/content/the-things-stack/migrating/device-json.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "JSON File Reference" -description: "" -weight: 8 -aliases: [/the-things-stack/migrating-from-networks/device-json, /getting-started/migrating/device-json] ---- - -{{% tts %}} allows you to import end devices from {{% ttnv2 %}}, 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: - -```json -{ - "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: - -```js -{ - /* 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]({{< ref "/the-things-stack/migrating/import-devices" >}}). - - -## JSON End Device Format - -The full specification of the JSON format is defined in the API protos. See the [EndDevice]({{< ref "/reference/api/end_device#message: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]({{< ref "reference/glossary#device-id" >}}) | -| **`ids.dev_eui`** | **Always** | string | `"0102030405060708"` | [More info]({{< ref "reference/glossary#deveui" >}}) | -| **`ids.join_eui`** | **Always** | string | `"0102030405060708"` | Also referred to as **AppEUI**. [More info]({{< ref "reference/glossary#joineui" >}}) | -| **`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]({{< ref "reference/api/end_device#enum:MACVersion" >}}) for supported versions. See [LoRaWAN Version]({{< ref "reference/glossary#lorawan-version" >}}) for more information. | -| **`lorawan_phy_version`** | **Always** | string | `"PHY_V1_0_2_REV_B"` | See [PHYVersion]({{< ref "reference/api/end_device#enum:PHYVersion" >}}) for supported versions. See [LoRaWAN Version]({{< ref "reference/glossary#regional-parameters" >}}) for more information. | -| **`frequency_plan_id`** | **Always** | string | `"EU_863_870_TTN"` | See [Frequency Plans]({{< ref "reference/frequency-plans" >}}) for a list of supported frequency plans (The frequency plan `ID` is needed). See [Frequency Plan]({{< ref "reference/glossary#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]({{< ref "reference/glossary#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]({{< ref "reference/glossary#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]({{< ref "reference/api/end_device#message: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]({{< ref "/reference/glossary#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]({{< ref "reference/glossary#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]({{< ref "reference/api/end_device#message:SessionKeys" >}}) and [Forwarding Network Session Integrity Key]({{< ref "/reference/glossary#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": "" - } -} -``` diff --git a/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/establish-new-session/_index.md b/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/establish-new-session/_index.md index f5d21f79c2..f95813de01 100644 --- a/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/establish-new-session/_index.md +++ b/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/establish-new-session/_index.md @@ -2,7 +2,10 @@ title: "Migrate Without Persisting Active Session" description: "" weight: 2 -aliases: [/getting-started/migrating/migrating-between-tts-distributions/establish-new-session] +aliases: + [ + /getting-started/migrating/migrating-between-tts-distributions/establish-new-session, + ] --- This section explains how to migrate end devices from {{% tts %}} Community Edition to {{% tts %}} Cloud without persisting sessions that were established between those devices and {{% tts %}} Community Edition. This is the way to go if you cannot migrate your gateway from {{% tts %}} Community Edition to {{% tts %}} Cloud. @@ -50,7 +53,7 @@ To export device using the [migration tool]({{< ref "/the-things-stack/migrating ttn-lw-migrate device --source tts 'my-device' --tts.no-session > devices.json ``` -Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}). Keep in mind that if you are using the CLI to import devices, you have to configure it to connect to {{% tts %}} Cloud. See [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. +Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). Keep in mind that if you are using the CLI to import devices, you have to configure it to connect to {{% tts %}} Cloud. See [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. The process of migrating OTAA devices using the migration tool ends here and you can ignore the info below the line. @@ -86,7 +89,7 @@ ttn-lw-cli end-devices get --application-id --device-id \ The command above will export your device's description to the `device-description.json` file in the current folder. Open the file with a text editor and remove the following fields: `join_server_address`, `network_server_address` and `application_server_address`. -Next, you need to import the `device-description.json` file in your {{% tts %}} Cloud application. See instructions on how to [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}). Keep in mind that if you are using the CLI to import devices, you first have to re-configure it to connect to {{% tts %}} Cloud. Again, see [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. +Next, you need to import the `device-description.json` file in your {{% tts %}} Cloud application. See instructions on how to [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). Keep in mind that if you are using the CLI to import devices, you first have to re-configure it to connect to {{% tts %}} Cloud. Again, see [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. {{< /tabs/tab >}} @@ -139,7 +142,7 @@ ttn-lw-migrate device --source tts 'my-device' \ --tts.no-session > devices.json ``` -Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}). Keep in mind that if you are using the CLI to import devices, you first have to configure it to connect to {{% tts %}} Cloud. See [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. +Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). Keep in mind that if you are using the CLI to import devices, you first have to configure it to connect to {{% tts %}} Cloud. See [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. You will also need to reset your ABP device. @@ -188,7 +191,7 @@ ttn-lw-cli end-devices get --application-id --device-id \ The command above will export your device's description to the `device-description.json` file in the current folder. Open the file with a text editor and remove the following fields: `join_server_address`, `network_server_address` and `application_server_address`. Also, set the `mac-settings.resets-f-cnt` field value to `true`. -Next, you need to import the `device-description.json` file in your {{% tts %}} Cloud application. See instructions on how to [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}). Keep in mind that if you are using the CLI to import devices, you first have to re-configure it to connect to {{% tts %}} Cloud. Again, see [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. +Next, you need to import the `device-description.json` file in your {{% tts %}} Cloud application. See instructions on how to [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). Keep in mind that if you are using the CLI to import devices, you first have to re-configure it to connect to {{% tts %}} Cloud. Again, see [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. When your device is registered in {{% tts %}} Cloud, you need to completely delete it from {{% tts %}} Community Edition network to prevent conflicts. You will also need to reset your ABP device. diff --git a/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/migrate-active-session/_index.md b/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/migrate-active-session/_index.md index cd606ca4af..7cdf59ee68 100644 --- a/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/migrate-active-session/_index.md +++ b/doc/content/the-things-stack/migrating/migrating-between-tts-distributions/migrate-active-session/_index.md @@ -1,7 +1,10 @@ --- title: "Migrate Active Device Session" description: "" -aliases: [/getting-started/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session] +aliases: + [ + /getting-started/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session, + ] --- This section explains how to migrate end devices from {{% tts %}} Community Edition to {{% tts %}} Cloud while persisting sessions that were already established between those devices and {{% tts %}} Community Edition. @@ -45,7 +48,7 @@ ttn-lw-migrate device --source tts 'my-device' \ --tts.delete-source-device ``` -Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}). Keep in mind that if you are using the CLI to import devices, you first have to configure it to connect to {{% tts %}} Cloud. See [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. +Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). Keep in mind that if you are using the CLI to import devices, you first have to configure it to connect to {{% tts %}} Cloud. See [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. {{}} @@ -90,9 +93,9 @@ ttn-lw-cli end-devices get --application-id --device-id \ The command above will export your device's session to the `device-session.json` file in the current folder. Open the file with a text editor and remove the following fields: `join_server_address`, `network_server_address` and `application_server_address`. -Before your device's session is imported in {{% tts %}} Cloud, you need to completely delete your device from {{% tts %}} Community Edition to prevent conflicts. +Before your device's session is imported in {{% tts %}} Cloud, you need to completely delete your device from {{% tts %}} Community Edition to prevent conflicts. -Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}). Keep in mind that if you are using the CLI to import devices, you first have to configure it to connect to {{% tts %}} Cloud. Again, see [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. +Next, you need to import the `devices.json` file in your {{% tts %}} Cloud application. See instructions on how to [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). Keep in mind that if you are using the CLI to import devices, you first have to configure it to connect to {{% tts %}} Cloud. Again, see [Configuring the CLI]({{< ref "/the-things-stack/interact/cli/configuring-cli" >}}) guide for instructions. {{}} diff --git a/doc/content/the-things-stack/migrating/migrating-from-v2/major-changes.md b/doc/content/the-things-stack/migrating/migrating-from-v2/major-changes.md index dd5e94fd8a..23e7a911c5 100644 --- a/doc/content/the-things-stack/migrating/migrating-from-v2/major-changes.md +++ b/doc/content/the-things-stack/migrating/migrating-from-v2/major-changes.md @@ -1,7 +1,12 @@ --- title: Major Changes In The Things Stack weight: 1 -aliases: [/getting-started/migrating-from-v2/major-changes, /getting-started/migrating-from-v2/mqtt-api-comparison, /getting-started/migrating/migrating-from-v2/major-changes] +aliases: + [ + /getting-started/migrating-from-v2/major-changes, + /getting-started/migrating-from-v2/mqtt-api-comparison, + /getting-started/migrating/migrating-from-v2/major-changes, + ] --- Before going in detail with the migration process, this section will give you a breakdown of differences between {{% ttnv2 %}} and {{% tts %}}, along with some guidelines to make the migration process easier to manage. @@ -12,7 +17,7 @@ Before going in detail with the migration process, this section will give you a ## LoRaWAN support -{{% tts %}} brings full support for all LoRaWAN® versions, as well as modes to support class B and class C capabilities. +{{% tts %}} brings full support for all LoRaWAN® versions, as well as modes to support class B and class C capabilities. {{% tts %}} requires the LoRaWAN version (MAC) and Regional Parameters version (LoRaWAN PHY version) to be set per end device. These default to LoRaWAN version **MAC V1.0.2** and LoRaWAN Regional Parameters version **PHY V1.0.2 Rev B** for end devices imported from {{% ttnv2 %}}, because this configuration is the most commonly used one. @@ -24,23 +29,23 @@ The RX1 delay is the time after which the first receive window (RX1) opens. In t Devices imported from {{% ttnv2 %}} are configured with an RX1 delay of 1 second. In all {{% tts %}} deployments, the recommended RX1 delay is 5 seconds to accommodate for high latency backhauls and/or [peering with Packet Broker]({{< ref "/the-things-stack/packet-broker" >}}). -See the [MAC settings guide]({{< ref "/devices/mac-settings" >}}) for more information and instructions about configuring the RX1 delay. +See the [MAC settings guide]({{< ref "/devices/configuring-devices/mac-settings" >}}) for more information and instructions about configuring the RX1 delay. ## MAC Commands {{% tts %}} expects that all end devices comply with the LoRaWAN specification by default, which means that the end devices should respond to Network Server MAC command requests accordingly. If a device fails to answer a MAC Command in a timely manner, there may be disruptions to the device uplink or downlink traffic. As mentioned in the LoRaWAN specification, the Network Server of {{% tts %}} will always prioritize MAC commands over application payloads on downlink. -In case a device is not fully compliant with the LORaWAN specification, it can still work on {{% tts %}}, but it may require custom [MAC settings configuration]({{< ref "/devices/mac-settings" >}}). +In case a device is not fully compliant with the LORaWAN specification, it can still work on {{% tts %}}, but it may require custom [MAC settings configuration]({{< ref "/devices/configuring-devices/mac-settings" >}}). ### DevStatusReq The `DevStatusReq` MAC command is sent by the Network Server periodically to check the current status of the end device. Devices are expected to send a `DevStatusAns` reply. -For end devices that ignore this MAC command, make sure to configure the `StatusTimePeriodicity` (time duration after which a `DevStatusReq` is issued by the Network Server) and `StatusCountPeriodicity` (number of frames after which a `DevStatusReq` is issued) of the device explicitly to `0`. +For end devices that ignore this MAC command, make sure to configure the `StatusTimePeriodicity` (time duration after which a `DevStatusReq` is issued by the Network Server) and `StatusCountPeriodicity` (number of frames after which a `DevStatusReq` is issued) of the device explicitly to `0`. {{< note >}} In the scope of [Migrating from The Things Network Stack V2]({{< ref "/the-things-stack/migrating/migrating-from-v2" >}}), devices exported with the `ttn-lw-migrate` tool have these MAC settings set to `0` by default. {{}} -See the [MAC settings guide]({{< ref "/devices/mac-settings" >}}) for more information. +See the [MAC settings guide]({{< ref "/devices/configuring-devices/mac-settings" >}}) for more information. ## Gateway Coverage @@ -66,7 +71,7 @@ For details on the data format of {{% tts %}}, see [Data Formats]({{% ref "/the- {{% tts %}} has support for an uplink payload formatter (similar to the payload decoder) and a downlink payload formatter (similar to the payload encoder). These can be set per application, and can even be overridden per end device. CayenneLPP and Javascript functions are still supported, and now payload formatters can also be fetched from the Device Repository. -Migrating the {{% ttnv2 %}} payload encoder and decoder to an uplink and downlink payload formatter should be straightforward. +Migrating the {{% ttnv2 %}} payload encoder and decoder to an uplink and downlink payload formatter should be straightforward. See [Payload Formatters]({{< ref "/integrations/payload-formatters" >}}) for more details. @@ -76,7 +81,7 @@ Read the full documentation dedicated to [Integrations]({{< ref "/integrations" #### MQTT Traffic -{{% tts %}} has a new MQTT server address, so you will need to change this address in your application accordingly. You will also need to create API keys and update your MQTT credentials. +{{% tts %}} has a new MQTT server address, so you will need to change this address in your application accordingly. You will also need to create API keys and update your MQTT credentials. Read more in the [MQTT Server]({{< ref "/integrations/mqtt" >}}) section. @@ -88,85 +93,85 @@ Read more in the [HTTP Webhooks]({{< ref "/integrations/webhooks" >}}) section. #### Storage Integration -{{% tts %}} supports a Storage Integration similar to {{% ttnv2 %}}. +{{% tts %}} supports a Storage Integration similar to {{% ttnv2 %}}. Read details in the [Storage Integration]({{< ref "/integrations/storage" >}}) section. ## API Comparison -{{% tts %}} provides multiple APIs. See the full [API documentation]({{< ref "/reference/api" >}}). + +{{% tts %}} provides multiple APIs. See the full [API documentation]({{< ref "/reference/api" >}}). For example, a comparison between The Things Industries V2 and The Things Stack MQTT API is given below. ### MQTT Connection Details -| **Category/Type** | **The Things Industries V2** | **The Things Stack** | -|---|----|---| -| MQTT Public Address | `{tenant_id}.thethings.industries:1883` | `https://thethings.example.com:1883` (replace with the URL of your deployment) | -| MQTT Public TLS Address | `{tenant_id}.thethings.industries:8883` (with using an appropriate TLS certificate) | `https://thethings.example.com:8883` | -| Username | `{application_id}` | `{application_id}@{tenant_id}` | -| Password | Application Access Key (with default rights) | Application API Key (with **Write downlink application traffic** and **Read application traffic (uplink and downlink)** rights) | -| Uplink topic (subscribe) | `{application_id}/devices/{device_id}/up` | `v3/{application id}@{tenant id}/devices/{device id}/up` | -| Downlink scheduling topic (pub) | `{application_id}/devices/{device_id}/downSchedule` (the downlink as the first or last item in a downlink queue using `schedule` key value in the payload) | Push downlink - `v3/{application id}@{tenant id}/devices/{device id}/down/push`,                                   Replace downlink queue - `v3/{application id}@{tenant id}/devices/{device id}/down/replace` | - +| **Category/Type** | **The Things Industries V2** | **The Things Stack** | +| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| MQTT Public Address | `{tenant_id}.thethings.industries:1883` | `https://thethings.example.com:1883` (replace with the URL of your deployment) | +| MQTT Public TLS Address | `{tenant_id}.thethings.industries:8883` (with using an appropriate TLS certificate) | `https://thethings.example.com:8883` | +| Username | `{application_id}` | `{application_id}@{tenant_id}` | +| Password | Application Access Key (with default rights) | Application API Key (with **Write downlink application traffic** and **Read application traffic (uplink and downlink)** rights) | +| Uplink topic (subscribe) | `{application_id}/devices/{device_id}/up` | `v3/{application id}@{tenant id}/devices/{device id}/up` | +| Downlink scheduling topic (pub) | `{application_id}/devices/{device_id}/downSchedule` (the downlink as the first or last item in a downlink queue using `schedule` key value in the payload) | Push downlink - `v3/{application id}@{tenant id}/devices/{device id}/down/push`,                                   Replace downlink queue - `v3/{application id}@{tenant id}/devices/{device id}/down/replace` | ### Uplinks -| **Category/Type** | **The Things Industries V2** | **The Things Stack** | -|---|----|---| -| Overall Uplink Format |
Show example {
"app_id": "my-app-id",
"dev_id": "my-dev-id",
"hardware_serial": "0102030405060708",
"port": 1,
"counter": 2,
"is_retry": false,
"confirmed": false,
"payload_raw": "AQIDBA==",
"payload_fields": {
"temperature": 1.0,
"luminosity": 0.64
},,
"metadata": {
"airtime": 46336000,
"time": "1970-01-01T00:00:00.000000000Z",
"frequency": 868.1,
"modulation": "LORA",
"data_rate": "SF7BW125",
"coding_rate": "4/5",
"gateways": [
{
"gtw_id": "ttn-herengracht-ams",
"timestamp": 12345,
"time": "1970-01-01T00:00:00.000000000Z",
"channel": 2,
"rssi": -25,
"snr": 5,
"rf_chain": 0,
"latitude": 52.1234,
"longitude": 6.1234,
"altitude": 6
},
//...more if received by more gateways...
],
"latitude": 52.2345,
"longitude": 6.2345,
"altitude": 2
}
}
|
Show example {
"end_device_ids" : {
"device_id" : "my-dev-id",
"application_ids" : {
"application_id" : "my-app-id"
},
"dev_eui" : "0102030405060708",
"join_eui" : "0102030405060708",
"dev_addr" : "01020304"
},
"correlation_ids" : [
// …
],
"received_at" : "1970-01-01T00:00:00.000000000Z",
"uplink_message" : {
"session_key_id" : "AXA50tHUGUucuzS/bCGMNw==",
"f_cnt" : 1,
"frm_payload" : "AQIDBA==",
"decoded_payload" : {
"temperature": 1.0,
"luminosity": 0.64
},
"rx_metadata" : [ {
"gateway_ids" : {
"gateway_id" : "ttn-herengracht-ams",
"eui" : "9C5C8E00001A05C4"
},
"time" : "1970-01-01T00:00:00.000000000Z",
"timestamp" : 12345,
"rssi" : -25,
"channel_rssi" : -25,
"snr" : 5,
"uplink_token" : "ChIKEAoEZ3R3MRIInFyOAAAaBcQQ6L3Vlgk=",
"channel_index" : 2
} ],
"settings" : {
"data_rate" : {
"lora" : {
"bandwidth" : 125000,
"spreading_factor" : 7
}
},
"data_rate_index" : 5,
"coding_rate" : "4/5",
"frequency" : "868100000",
"timestamp" : 12345,
"time" : "1970-01-01T00:00:00.000000000Z"
},
"received_at" : "1970-01-01T00:00:00.000000000Z"
,"consumed_airtime": "0.051321s",
"locations": {
"user": {
"latitude": 37.97155556731436,
"longitude": 23.72678801175413,
"altitude": 10,
"source": "SOURCE_REGISTRY"
}
},}
}
| -| Gateway fields | `metadata.gateways` - This object includes gateway details| `uplink_message.rx_metadata` - This object includes gateway details| -| | `metadata.gateways.timestamp` - Timestamp when the gateway received the message (microseconds)| `uplink_message.rx_metadata.timestamp` - Gateway concentrator timestamp when the Rx finished (microseconds) | -| | `metadata.gateways.time` - Time when the gateway received the message | `uplink_message.rx_metadata.time` - Time when the gateway received the message| -| | `metadata.gateways.channel` - Channel where the gateway received the message| As an alternative `channel_index` is `available.uplink_message.rx_metadata.channel_index` - Index of the gateway channel that received the message | -| | `metadata.gateways.rssi` - Signal strength of the received message| `uplink_message.rx_metadata.rssi` - Signal strength of the received message| -| | `metadata.gateways.snr` - Signal to noise ratio of the received message| `uplink_message.rx_metadata.snr` - Signal to noise ratio of the received message| -| | `metadata.gateways.rf_chain` - RF chain where the gateway received the message| Not available | -| | `metadata.gateways.latitude` - Latitude of the gateway reported in its status updates | Not available | -| | `metadata.gateways.longitude` - Longitude of the gateway| Not available | -| | `metadata.gateways.altitude` - Altitude of the gateway| Not available | -| | Not available | `uplink_message.rx_metadata.channel_rssi` - Received signal strength indicator of the channel (dBm)| -| | Not available | `uplink_message.rx_metadata.uplink_token` - Uplink token injected by gateway, Gateway Server or Network Server | -| ||| -| Uplink Metadata | `metadata` - This object includes metadata| `uplink_message` - This object includes metadata | -| | `metadata.airtime` | `uplink_message.consumed_airtime` - Formatted as a string, with a suffix for the unit used (for example, `"0.051321s"` is 0.051321 seconds) | -| | `metadata.time` - Time when the server received the message| `uplink_message.received_at` - Server time when the Application Server received the message | -| | `metadata.frequency` - Frequency at which the message was sent| `uplink_message.settings.frequency` - Frequency (Hz)| -| | `metadata.modulation` - Modulation that was used (LoRa or FSK) | Not available, but as an alternative the modulation can be derived from `settings.data_rate` | -| | `metadata.data_rate` - Data rate that was used (LoRa only) | `uplink_message.settings.data_rate` - Data rate of LoRa or FSK | -| | `metadata.bit_rate` - Bit rate that was used (FSK only) | `uplink_message.settings.data_rate.fsk.bit_rate` - Bit rate that was used (FSK only) | -| | `metadata.coding_rate` - Coding rate that was used| `uplink_message.settings.coding_rate` - LoRa coding rate | -| | `metadata.latitude`| `uplink_message.locations.user.latitude` - Latitude of the device | -| | `metadata.longitude` | `uplink_message.locations.user.longitude` - Longitude of the device| -| | `metadata.altitude` | `uplink_message.locations.user.altitude` - Altitude of the device | -| | Not available | `uplink_message.locations.user.source` - Location source| -| | `metadata.data_rate_index` - Not available| `uplink_message.data_rate_index` - LoRaWAN data rate index | -| | `metadata.payload_raw` - Base64 encoded payload: [0x01, 0x02, 0x03, 0x04] | `uplink_message.frm_payload` - Frame payload (Base64)| -| | `port` - LoRaWAN FPort| `uplink_message.f_port` - LoRaWAN FPort | -| | `counter` - LoRaWAN frame counter| `uplink_message.f_cnt` - LoRaWAN frame counter | -| | Not available | `uplink_message.session_key_id` - Join Server issued identifier for the session keys used by this uplink | -| ||| -| Common fields | `app_id` | `end_device_ids.application_ids.application_id` | -| | `dev_id` | `end_device_ids.device_id` | -| | `hardware_serial` - In case of LoRaWAN: the `DevEUI` | `end_device_ids.dev_eui` | -| | `confirmed` - `true` if this message was a confirmed message | Not available | -| | Not available | `end_device_ids.join_eui` | -| | Not available | `end_device_ids.dev_addr` | -| | | | -| Uplink Payload fiedls | `payload_fields` - Object containing the results from the payload functions (left out when empty) | `uplink_message.decoded_payload` | -| Correlation IDs | Not available | `correlation_ids` | +| **Category/Type** | **The Things Industries V2** | **The Things Stack** | +| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Overall Uplink Format |
Show example {
"app_id": "my-app-id",
"dev_id": "my-dev-id",
"hardware_serial": "0102030405060708",
"port": 1,
"counter": 2,
"is_retry": false,
"confirmed": false,
"payload_raw": "AQIDBA==",
"payload_fields": {
"temperature": 1.0,
"luminosity": 0.64
},,
"metadata": {
"airtime": 46336000,
"time": "1970-01-01T00:00:00.000000000Z",
"frequency": 868.1,
"modulation": "LORA",
"data_rate": "SF7BW125",
"coding_rate": "4/5",
"gateways": [
{
"gtw_id": "ttn-herengracht-ams",
"timestamp": 12345,
"time": "1970-01-01T00:00:00.000000000Z",
"channel": 2,
"rssi": -25,
"snr": 5,
"rf_chain": 0,
"latitude": 52.1234,
"longitude": 6.1234,
"altitude": 6
},
//...more if received by more gateways...
],
"latitude": 52.2345,
"longitude": 6.2345,
"altitude": 2
}
}
|
Show example {
"end_device_ids" : {
"device_id" : "my-dev-id",
"application_ids" : {
"application_id" : "my-app-id"
},
"dev_eui" : "0102030405060708",
"join_eui" : "0102030405060708",
"dev_addr" : "01020304"
},
"correlation_ids" : [
// …
],
"received_at" : "1970-01-01T00:00:00.000000000Z",
"uplink_message" : {
"session_key_id" : "AXA50tHUGUucuzS/bCGMNw==",
"f_cnt" : 1,
"frm_payload" : "AQIDBA==",
"decoded_payload" : {
"temperature": 1.0,
"luminosity": 0.64
},
"rx_metadata" : [ {
"gateway_ids" : {
"gateway_id" : "ttn-herengracht-ams",
"eui" : "9C5C8E00001A05C4"
},
"time" : "1970-01-01T00:00:00.000000000Z",
"timestamp" : 12345,
"rssi" : -25,
"channel_rssi" : -25,
"snr" : 5,
"uplink_token" : "ChIKEAoEZ3R3MRIInFyOAAAaBcQQ6L3Vlgk=",
"channel_index" : 2
} ],
"settings" : {
"data_rate" : {
"lora" : {
"bandwidth" : 125000,
"spreading_factor" : 7
}
},
"data_rate_index" : 5,
"coding_rate" : "4/5",
"frequency" : "868100000",
"timestamp" : 12345,
"time" : "1970-01-01T00:00:00.000000000Z"
},
"received_at" : "1970-01-01T00:00:00.000000000Z"
,"consumed_airtime": "0.051321s",
"locations": {
"user": {
"latitude": 37.97155556731436,
"longitude": 23.72678801175413,
"altitude": 10,
"source": "SOURCE_REGISTRY"
}
},}
}
| +| Gateway fields | `metadata.gateways` - This object includes gateway details | `uplink_message.rx_metadata` - This object includes gateway details | +| | `metadata.gateways.timestamp` - Timestamp when the gateway received the message (microseconds) | `uplink_message.rx_metadata.timestamp` - Gateway concentrator timestamp when the Rx finished (microseconds) | +| | `metadata.gateways.time` - Time when the gateway received the message | `uplink_message.rx_metadata.time` - Time when the gateway received the message | +| | `metadata.gateways.channel` - Channel where the gateway received the message | As an alternative `channel_index` is `available.uplink_message.rx_metadata.channel_index` - Index of the gateway channel that received the message | +| | `metadata.gateways.rssi` - Signal strength of the received message | `uplink_message.rx_metadata.rssi` - Signal strength of the received message | +| | `metadata.gateways.snr` - Signal to noise ratio of the received message | `uplink_message.rx_metadata.snr` - Signal to noise ratio of the received message | +| | `metadata.gateways.rf_chain` - RF chain where the gateway received the message | Not available | +| | `metadata.gateways.latitude` - Latitude of the gateway reported in its status updates | Not available | +| | `metadata.gateways.longitude` - Longitude of the gateway | Not available | +| | `metadata.gateways.altitude` - Altitude of the gateway | Not available | +| | Not available | `uplink_message.rx_metadata.channel_rssi` - Received signal strength indicator of the channel (dBm) | +| | Not available | `uplink_message.rx_metadata.uplink_token` - Uplink token injected by gateway, Gateway Server or Network Server | +| | | | +| Uplink Metadata | `metadata` - This object includes metadata | `uplink_message` - This object includes metadata | +| | `metadata.airtime` | `uplink_message.consumed_airtime` - Formatted as a string, with a suffix for the unit used (for example, `"0.051321s"` is 0.051321 seconds) | +| | `metadata.time` - Time when the server received the message | `uplink_message.received_at` - Server time when the Application Server received the message | +| | `metadata.frequency` - Frequency at which the message was sent | `uplink_message.settings.frequency` - Frequency (Hz) | +| | `metadata.modulation` - Modulation that was used (LoRa or FSK) | Not available, but as an alternative the modulation can be derived from `settings.data_rate` | +| | `metadata.data_rate` - Data rate that was used (LoRa only) | `uplink_message.settings.data_rate` - Data rate of LoRa or FSK | +| | `metadata.bit_rate` - Bit rate that was used (FSK only) | `uplink_message.settings.data_rate.fsk.bit_rate` - Bit rate that was used (FSK only) | +| | `metadata.coding_rate` - Coding rate that was used | `uplink_message.settings.coding_rate` - LoRa coding rate | +| | `metadata.latitude` | `uplink_message.locations.user.latitude` - Latitude of the device | +| | `metadata.longitude` | `uplink_message.locations.user.longitude` - Longitude of the device | +| | `metadata.altitude` | `uplink_message.locations.user.altitude` - Altitude of the device | +| | Not available | `uplink_message.locations.user.source` - Location source | +| | `metadata.data_rate_index` - Not available | `uplink_message.data_rate_index` - LoRaWAN data rate index | +| | `metadata.payload_raw` - Base64 encoded payload: [0x01, 0x02, 0x03, 0x04] | `uplink_message.frm_payload` - Frame payload (Base64) | +| | `port` - LoRaWAN FPort | `uplink_message.f_port` - LoRaWAN FPort | +| | `counter` - LoRaWAN frame counter | `uplink_message.f_cnt` - LoRaWAN frame counter | +| | Not available | `uplink_message.session_key_id` - Join Server issued identifier for the session keys used by this uplink | +| | | | +| Common fields | `app_id` | `end_device_ids.application_ids.application_id` | +| | `dev_id` | `end_device_ids.device_id` | +| | `hardware_serial` - In case of LoRaWAN: the `DevEUI` | `end_device_ids.dev_eui` | +| | `confirmed` - `true` if this message was a confirmed message | Not available | +| | Not available | `end_device_ids.join_eui` | +| | Not available | `end_device_ids.dev_addr` | +| | | | +| Uplink Payload fiedls | `payload_fields` - Object containing the results from the payload functions (left out when empty) | `uplink_message.decoded_payload` | +| Correlation IDs | Not available | `correlation_ids` | ### Downlinks -| **Category/Type** | **The Things Industries V2** | **The Things Stack** | -|---|----|---| +| **Category/Type** | **The Things Industries V2** | **The Things Stack** | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Downlink message overall format |
Show example{
"port": 1,
"confirmed": false,
"payload_raw": "AQIDBA==",
"schedule": "replace",
}

or use payload_fields instead

{
"port": 1,
"confirmed": false,
"payload_fields": {
"led": true
},
"schedule": "replace", // allowed values: "replace" (default), "first", "last"}
|
Show example {
"downlinks": [{
"f_port": 15,
"frm_payload": "vu8=",
"priority": "HIGH",
"confirmed": true,
"correlation_ids": ["my-correlation-id"]
}]
}
| -| Individual fields comparison | `port` | `f_port` | -| | `confirmed` | `confirmed` | -| | `payload_raw` | `frm_payload` | -| | `schedule` | Replace and push topics are available as an alternative | -| | Not available | `priority` - You can specify `LOWEST`, `LOW`, `BELOW_NORMAL`, `NORMAL`, `ABOVE_NORMAL`, `HIGH` and `HIGHEST` (`LOWEST` is a default if not specified) | -| | Not available | `correlation_ids` - You can add multiple custom correlation IDs, for example to reference events or identifiers of your application | -| | `payload_fields` | Not available | +| Individual fields comparison | `port` | `f_port` | +| | `confirmed` | `confirmed` | +| | `payload_raw` | `frm_payload` | +| | `schedule` | Replace and push topics are available as an alternative | +| | Not available | `priority` - You can specify `LOWEST`, `LOW`, `BELOW_NORMAL`, `NORMAL`, `ABOVE_NORMAL`, `HIGH` and `HIGHEST` (`LOWEST` is a default if not specified) | +| | Not available | `correlation_ids` - You can add multiple custom correlation IDs, for example to reference events or identifiers of your application | +| | `payload_fields` | Not available | ### References diff --git a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-console.md b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-console.md index 77c83d6706..7c34a2cffe 100644 --- a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-console.md +++ b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-console.md @@ -19,7 +19,7 @@ The first step is to add your end device in {{% tts %}}. See [Adding Devices]({{ There are two ways to add devices in {{% tts %}} Console - **Manually** and via the **LoRaWAN Device Repository**. -Configuring settings for end devices depends on their type - OTAA or ABP. We strongly recommend using OTAA over ABP. Read [why using OTAA is better than ABP]({{< ref "/devices/abp-vs-otaa" >}}). +Configuring settings for end devices depends on their type - OTAA or ABP. We strongly recommend using OTAA over ABP. Read [why using OTAA is better than ABP]({{< ref "/devices/concepts/abp-vs-otaa" >}}). {{< tabs/container "OTAA" "ABP" >}} @@ -46,7 +46,7 @@ The **AppKey** value can match the one used in {{% ttnv2 %}}, as this info is us If you still have a good reason to use ABP device, you can add it in {{% tts %}} by following next few steps: - Select **Activation by personalization (ABP)** -Choose **LoRaWAN version** `MAC V1.0.2` (this is the version used in {{% ttnv2 %}}) + Choose **LoRaWAN version** `MAC V1.0.2` (this is the version used in {{% ttnv2 %}}) - Create an **End device ID** (does not have to match the **Device ID** in {{% ttnv2 %}}) - The **DevEUI** field is optional - Select your **Frequency plan** @@ -54,19 +54,19 @@ Choose **LoRaWAN version** `MAC V1.0.2` (this is the version used in {{% ttnv2 % - Do not check the boxes **Supports class B/C** - Enter your device’s **DevAddr** and **NwkSKey** (see considerations below) - Advanced settings must be set on registration (beware that changing these settings might not work later) - - Set **Frame counter width** to `32 bit` (this is the value used in {{% ttnv2 %}}) - - Set **RX1 Delay** to `1` (see considerations below) - - Set **RX1 Data Rate Offset** to `0` - - Your device probably resets frame counters, so check the **Resets Frame Counters** box - - Set **RX2 Data Rate Index** to `3` if your frequency plan is EU868 - - Set **RX2 Frequency** to `869525000` if your frequency plan is EU868 - - Set **Factory Preset Frequencies** for EU868 devices to `868100000, 868300000, 868500000` for all devices, or to `867100000, 867300000, 867500000, 867700000, 867900000, 868100000, 868300000, 868500000` for 8-channel devices + - Set **Frame counter width** to `32 bit` (this is the value used in {{% ttnv2 %}}) + - Set **RX1 Delay** to `1` (see considerations below) + - Set **RX1 Data Rate Offset** to `0` + - Your device probably resets frame counters, so check the **Resets Frame Counters** box + - Set **RX2 Data Rate Index** to `3` if your frequency plan is EU868 + - Set **RX2 Frequency** to `869525000` if your frequency plan is EU868 + - Set **Factory Preset Frequencies** for EU868 devices to `868100000, 868300000, 868500000` for all devices, or to `867100000, 867300000, 867500000, 867700000, 867900000, 868100000, 868300000, 868500000` for 8-channel devices The **DevAddr** and **RX1 Delay** values depend on your specific use case. -If you want your end device traffic to be routed via Packet Broker to {{% tts %}}, [Packet Broker Requirements for End Device Migration]({{< ref "/the-things-stack/migrating/migrating-from-v2/packet-broker-requirements" >}}) need to be fulfilled. If you are migrating from **The Things Industries {{% ttnv2 %}}** to **{{% tts %}} Cloud**, you might be able to keep the existing **DevAddr** (please contact [The Things Industries support](mailto:support@thethingsindustries.com)). If the existing **DevAddr** is not routable by the Packet Broker (i.e. you are not migrating from **The Things Industries V2** to **The Things Stack Cloud**), you will need to auto-generate new **DevAddr** during device registration on {{% tts %}}, then re-program the device to assign it with the new **DevAddr**. Note that in both of these cases, you will have to adjust your device's **RX1 Delay** to 5 seconds using MAC commands, otherwise your device's traffic might not reach {{% tts %}} in time. +If you want your end device traffic to be routed via Packet Broker to {{% tts %}}, [Packet Broker Requirements for End Device Migration]({{< ref "/the-things-stack/migrating/migrating-from-v2/packet-broker-requirements" >}}) need to be fulfilled. If you are migrating from **The Things Industries {{% ttnv2 %}}** to **{{% tts %}} Cloud**, you might be able to keep the existing **DevAddr** (please contact [The Things Industries support](mailto:support@thethingsindustries.com)). If the existing **DevAddr** is not routable by the Packet Broker (i.e. you are not migrating from **The Things Industries V2** to **The Things Stack Cloud**), you will need to auto-generate new **DevAddr** during device registration on {{% tts %}}, then re-program the device to assign it with the new **DevAddr**. Note that in both of these cases, you will have to adjust your device's **RX1 Delay** to 5 seconds using MAC commands, otherwise your device's traffic might not reach {{% tts %}} in time. -Re-programming the ABP device to change **DevAddr** to the one issued by {{% tts %}} and **RX1 Delay** to 5 seconds is **recommended**. Re-programming the ABP device to do this might also be a good time to reconsider switching it to OTAA by flashing the firmware and adopting some [best practices]({{< ref "/devices/best-practices" >}}). [Check why using OTAA is recommended]({{< ref "/devices/abp-vs-otaa" >}}). +Re-programming the ABP device to change **DevAddr** to the one issued by {{% tts %}} and **RX1 Delay** to 5 seconds is **recommended**. Re-programming the ABP device to do this might also be a good time to reconsider switching it to OTAA by flashing the firmware and adopting some [best practices]({{< ref "/devices/concepts/best-practices" >}}). [Check why using OTAA is recommended]({{< ref "/devices/concepts/abp-vs-otaa" >}}). If you do not want your traffic to be routed by the Packet Broker, i.e. you want to migrate your gateway to {{% tts %}} too, you do not have to re-program your device. You can keep the existing **DevAddr** and **RX1 Delay** of 1 second, and use these values when adding the device to {{% tts %}}. Be aware that if you are using a high-latency backhaul, keeping the **RX1 Delay** of 1 second still might cause latency issues, even if you migrate your gateway. @@ -90,7 +90,7 @@ To prevent OTAA devices from re-joining {{% ttnv2 %}}, the recommended practice ## Let the OTAA End Device Join {{% tts %}} Network -Next, your end device needs to join {{% tts %}} network. +Next, your end device needs to join {{% tts %}} network. Some OTAA devices ocasionally perform new joins - with these end devices, you can only wait for them to do this on their own. Depending on the end device, you can also: @@ -102,7 +102,7 @@ Some OTAA devices ocasionally perform new joins - with these end devices, you ca {{< tabs/tab "ABP" >}} -ABP devices must be completely deleted from {{% ttnv2 %}}, especially if they are not re-programmed for a new **DevAddr**. Having the device registered in both {{% ttnv2 %}} and {{% tts %}} introduces serious conflicts, including race conditions for Joins and unpredictable, out-of-spec operation. +ABP devices must be completely deleted from {{% ttnv2 %}}, especially if they are not re-programmed for a new **DevAddr**. Having the device registered in both {{% ttnv2 %}} and {{% tts %}} introduces serious conflicts, including race conditions for Joins and unpredictable, out-of-spec operation. {{< /tabs/tab >}} @@ -114,7 +114,7 @@ ABP devices must be completely deleted from {{% ttnv2 %}}, especially if they ar {{< tabs/tab "OTAA" >}} -Since we assume you have not migrated your gateway from {{% ttnv2 %}} yet, new Join Requests sent by your OTAA device are still being received by the {{% ttnv2 %}} network. However, if you have prevented your device from joining {{% ttnv2 %}} network (as recommended above), these Join Requests are not going to be accepted by the {{% ttnv2 %}} Network Server. +Since we assume you have not migrated your gateway from {{% ttnv2 %}} yet, new Join Requests sent by your OTAA device are still being received by the {{% ttnv2 %}} network. However, if you have prevented your device from joining {{% ttnv2 %}} network (as recommended above), these Join Requests are not going to be accepted by the {{% ttnv2 %}} Network Server. Instead, if your devices respect the previously mentioned Packet Broker requirements, these Join Requests are going to be routed to {{% tts %}} via Packet Broker and {{% tts %}} will accept them. Upon Join Request acceptance, your OTAA device will negotiate with {{% tts %}} 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 {{% tts %}} thanks to the newly assigned **DevAddr** and **RX1 Delay** of 5 seconds. @@ -122,7 +122,7 @@ Instead, if your devices respect the previously mentioned Packet Broker requirem {{< tabs/tab "ABP" >}} -ABP devices do not perform the join procedure, so they do not get assigned with a new **DevAddr**, **RX1 Delay** and some other parameters like OTAA devices do. These values must be coded in the device itself. +ABP devices do not perform the join procedure, so they do not get assigned with a new **DevAddr**, **RX1 Delay** and some other parameters like OTAA devices do. These values must be coded in the device itself. As previously mentioned, routing traffic from your ABP devices to {{% tts %}} via Packet Broker will be possible only if Packet Broker requirements are met. If you want your traffic to be routed via Packet Broker, you will need to re-program your ABP device to use a **DevAddr** issued by {{% tts %}} and **RX1 Delay** of 5 seconds. Please note that this is a recommended practice. An exception to this rule is the case of migrating from **The Things Industries {{% ttnv2 %}}** to **{{% tts %}} Cloud** deployment - here you might be able to keep your device's **DevAddr**, but you will still have to adjust your device's **RX1 Delay** to 5 seconds. diff --git a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/_index.md b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/_index.md index e604200e42..3653b45e09 100644 --- a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/_index.md +++ b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/_index.md @@ -2,7 +2,8 @@ title: "Migrate using the Migration Tool" description: "" weight: 2 -aliases: [/getting-started/migrating/migrating-from-v2/migrate-using-migration-tool] +aliases: + [/getting-started/migrating/migrating-from-v2/migrate-using-migration-tool] --- This section refers to migrating end devices to {{% tts %}} using [`ttn-lw-migrate` migration tool](https://github.com/TheThingsNetwork/lorawan-stack-migrate). @@ -49,7 +50,7 @@ If the Discovery Server of your private The Things Industries V2 (SaaS) cluster ## Export End Devices from {{% ttnv2 %}} -Next, you can proceed with exporting one or more end devices, with or without their active session, from {{% ttnv2 %}} to a [JSON file]({{< ref "/the-things-stack/migrating/device-json" >}}). +Next, you can proceed with exporting one or more end devices, with or without their active session, from {{% ttnv2 %}} to a [JSON file]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-json" >}}). {{< note >}} Migrating end devices from {{% ttnv2 %}} to {{% tts %}} is a one-way process, since LoRaWAN® devices may be handled by only one Network Server at a time. {{}} diff --git a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session.md b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session.md index 466208a322..af1b6d154a 100644 --- a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session.md +++ b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session.md @@ -2,10 +2,13 @@ title: "Migrate without Persisting Active Sessions" description: "" weight: 1 -aliases: [/getting-started/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session] +aliases: + [ + /getting-started/migrating/migrating-from-v2/migrate-using-migration-tool/establish-new-session, + ] --- -This section explains how to export one or more of your end devices from {{% ttnv2 %}} to a [JSON file]({{< ref "/the-things-stack/migrating/device-json" >}}), without persisting their session. +This section explains how to export one or more of your end devices from {{% ttnv2 %}} to a [JSON file]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-json" >}}), without persisting their session. @@ -95,9 +98,9 @@ ABP devices must be completely deleted from {{% ttnv2 %}}, especially if you hav {{< /tabs/container >}} -## Import End Devices in {{% tts %}} Application +## Add end devices in bulk in {{% tts %}} 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 {{% tts %}} via Console or via CLI. See [Import End Devices in The Things Stack]({{< ref "/the-things-stack/migrating/import-devices" >}}) for detailed instructions on how to do this. +Now that you have exported one or more of your devices to a `devices.json` file, you can continue by importing this file in {{% tts %}} via Console or via CLI. See [add end devices in bulk in The Things Stack]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}) for detailed instructions on how to do this. {{< tabs/container "OTAA" "ABP" >}} diff --git a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session.md b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session.md index 28df397e50..fdcaa19283 100644 --- a/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session.md +++ b/doc/content/the-things-stack/migrating/migrating-from-v2/migrate-using-migration-tool/migrate-active-session.md @@ -2,14 +2,17 @@ title: "Migrate Active Sessions" description: "" weight: 2 -aliases: [/getting-started/migrating/migrating-between-tts-distributions/migrate-active-session/] +aliases: + [ + /getting-started/migrating/migrating-between-tts-distributions/migrate-active-session/, + ] --- -Starting from {{% tts %}} version `3.12.0`, it is possible to migrate end devices together with their active sessions using the `ttn-lw-migrate` tool. This section explains how to export one or more of your end devices from {{% ttnv2 %}} to a [JSON file]({{< ref "/the-things-stack/migrating/device-json" >}}), with persisting their active sessions. +Starting from {{% tts %}} version `3.12.0`, it is possible to migrate end devices together with their active sessions using the `ttn-lw-migrate` tool. This section explains how to export one or more of your end devices from {{% ttnv2 %}} to a [JSON file]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-json" >}}), with persisting their active sessions. -Active device sessions can be migrated via Packet Broker only from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud**, and this is achievable only on a customer request. Contact [The Things Industries support](mailto:support@thethingsindustries.com) for more information. +Active device sessions can be migrated via Packet Broker only from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud**, and this is achievable only on a customer request. Contact [The Things Industries support](mailto:support@thethingsindustries.com) for more information. For all other scenarios, migrating active session is achievable only if you [migrate your gateway to {{% tts %}}]({{< ref "/the-things-stack/migrating/gateway-migration" >}}) too. @@ -25,7 +28,7 @@ In the case of persisting active sessions during migration, OTAA devices do not {{< tabs/tab "ABP" >}} -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 {{% tts %}} with its active session. +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 {{% tts %}} with its active session. {{< /tabs/tab >}} @@ -49,7 +52,7 @@ ttn-lw-migrate device --source ttnv2 "v2-end-device-ID" > devices.json ### Export a Batch of End Devices -First, create a text file `device_ids.txt`. This file needs to contain a {{% ttnv2 %}} **Device ID** for every end device you want to export from {{% ttnv2 %}}. +First, create a text file `device_ids.txt`. This file needs to contain a {{% ttnv2 %}} **Device ID** for every end device you want to export from {{% ttnv2 %}}. The format of this file is one **Device ID** per one line, i.e.: @@ -73,11 +76,11 @@ To export all devices contained in {{% ttnv2 %}} application and clear their sec ttn-lw-migrate application --source ttnv2 "ttn-v2-application-ID" > devices.json ``` -## Import End Devices in {{% tts %}} Application +## Add end devices in bulk in {{% tts %}} 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 {{% tts %}} via Console or via CLI. +Now that you have exported one or more of your devices to a `devices.json` file, you can continue by importing this file in {{% tts %}} via Console or via CLI. -> See [Import End Devices in The Things Stack]({{< ref "/the-things-stack/migrating/import-devices" >}}) for detailed instructions on how to do this. +> See [add end devices in bulk in The Things Stack]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}) for detailed instructions on how to do this. ## Next Step - Migrate Gateways @@ -85,7 +88,7 @@ Now that you have exported one or more of your devices to a `devices.json` file, {{< tabs/tab "OTAA" >}} -Migrating your OTAA device from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud** with its active session means it will keep its **DevAddr**, channel settings and MAC parameters from {{% ttnv2 %}}. It will not send new Join Requests, but the uplink traffic from your device should automatically show up in {{% tts %}}, because it will be routed via Packet Broker thanks to preserving your device's existing session. +Migrating your OTAA device from **The Things Industries V2 (SaaS)** to **{{% tts %}} Cloud** with its active session means it will keep its **DevAddr**, channel settings and MAC parameters from {{% ttnv2 %}}. It will not send new Join Requests, but the uplink traffic from your device should automatically show up in {{% tts %}}, because it will be routed via Packet Broker thanks to preserving your device's existing session. {{< /tabs/tab >}} @@ -97,7 +100,7 @@ Migrating your ABP device from {{% ttnv2 %}} to {{% tts %}} with its active sess {{< /tabs/container >}} -If you are migrating an end device with its active session via Packet Broker (from **The Things Industries V2** to **{{% tts %}} Cloud**), you might need to set the **RX1 Delay** of the device to 5 seconds by [configuring MAC settings]({{< ref "/the-things-stack/migrating/configure-mac-settings" >}}), otherwise the traffic might not reach {{% tts %}} in time via Packet Broker. +If you are migrating an end device with its active session via Packet Broker (from **The Things Industries V2** to **{{% tts %}} Cloud**), you might need to set the **RX1 Delay** of the device to 5 seconds by [configuring MAC settings]({{< ref "/the-things-stack/migrating/configure-mac-settings" >}}), otherwise the traffic might not reach {{% tts %}} in time via Packet Broker. In case you want to leave the **RX1 Delay** value as is (1 second from {{% ttnv2 %}}), you will need to [migrate your gateway to {{% tts %}}]({{< ref "/the-things-stack/migrating/gateway-migration" >}}) too. diff --git a/doc/content/the-things-stack/migrating/migration-tool/_index.md b/doc/content/the-things-stack/migrating/migration-tool/_index.md index 43b8cd144a..c5ece86b6d 100644 --- a/doc/content/the-things-stack/migrating/migration-tool/_index.md +++ b/doc/content/the-things-stack/migrating/migration-tool/_index.md @@ -9,7 +9,7 @@ aliases: [/getting-started/migrating/migration-tool] -This tool works in a way that it exports descriptions of end devices and applications to a [JSON file]({{< ref "/the-things-stack/migrating/device-json" >}}), that can later be [imported in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}). +This tool works in a way that it exports descriptions of end devices and applications to a [JSON file]({{< ref "/devices/adding-devices/adding-devices-in-bulk/device-json" >}}), that can later be [imported in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}). ## Installation @@ -75,8 +75,8 @@ Currently, there are three available sources listed in the table below. For deta > The `tts` source can be used for migrating devices between applications in the same {{% tts %}} tenant, migrating between different tenants, or migrating between different {{% tts %}} deployments. -| Source | Section | Used for | -| :----------- | :---------------------------------------------------------------------------------------------------------------------------------- | :------------------------ | -| `tts` | [Export Devices from {{% tts %}}]({{< ref "/the-things-stack/migrating/migration-tool/export-from-tts" >}}) | [Migrating between {{% tts %}} distributions]({{< ref "/the-things-stack/migrating/migrating-between-tts-distributions" >}}) -| `chirpstack` | [Export Devices from ChirpStack]({{< ref "/the-things-stack/migrating/migration-tool/export-from-chirpstack" >}}) | Migrating devices from ChirpStack -| `ttnv2` | Discontinued | Migrating from legacy {{% ttnv2 %}} deployments +| Source | Section | Used for | +| :----------- | :---------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | +| `tts` | [Export Devices from {{% tts %}}]({{< ref "/the-things-stack/migrating/migration-tool/export-from-tts" >}}) | [Migrating between {{% tts %}} distributions]({{< ref "/the-things-stack/migrating/migrating-between-tts-distributions" >}}) | +| `chirpstack` | [Export Devices from ChirpStack]({{< ref "/the-things-stack/migrating/migration-tool/export-from-chirpstack" >}}) | Migrating devices from ChirpStack | +| `ttnv2` | Discontinued | Migrating from legacy {{% ttnv2 %}} deployments | diff --git a/doc/content/the-things-stack/migrating/migration-tool/export-from-chirpstack.md b/doc/content/the-things-stack/migrating/migration-tool/export-from-chirpstack.md index f078caaa32..109cd0efcd 100644 --- a/doc/content/the-things-stack/migrating/migration-tool/export-from-chirpstack.md +++ b/doc/content/the-things-stack/migrating/migration-tool/export-from-chirpstack.md @@ -2,7 +2,11 @@ title: "Export End Devices from ChirpStack" description: "" weight: 3 -aliases: [/the-things-stack/migrating-from-networks/migrate-from-chirpstack, /getting-started/migrating/migration-tool/export-from-chirpstack] +aliases: + [ + /the-things-stack/migrating-from-networks/migrate-from-chirpstack, + /getting-started/migrating/migration-tool/export-from-chirpstack, + ] --- This section contains instructions on how to configure migration tool and use it to export end devices from ChirpStack, that can later be imported in {{% tts %}}. This is a base for migrating end devices from ChirpStack to {{% tts %}}. @@ -88,4 +92,4 @@ Please note that `MaxEIRP` parameter may not be always set properly, and that th --- -After exporting, devices and applications can be imported in {{% tts %}}. See [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}) for details about importing devices. +After exporting, devices and applications can be imported in {{% tts %}}. See [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}) for details about importing devices. diff --git a/doc/content/the-things-stack/migrating/migration-tool/export-from-tts.md b/doc/content/the-things-stack/migrating/migration-tool/export-from-tts.md index 49839a1ec1..27ffcf39e1 100644 --- a/doc/content/the-things-stack/migrating/migration-tool/export-from-tts.md +++ b/doc/content/the-things-stack/migrating/migration-tool/export-from-tts.md @@ -108,4 +108,4 @@ export TTS_CA_FILE="/path/to/ca.file" # Path to a CA file (optional) --- -After exporting, devices and applications can be imported in other {{% tts %}} deployments. See [Import End Devices in {{% tts %}}]({{< ref "/the-things-stack/migrating/import-devices" >}}) for details about importing devices. See [Migrating End Devices between {{% tts %}} Distributions]({{< ref "/the-things-stack/migrating/migrating-between-tts-distributions" >}}) to wrap up the whole process of migration between {{% tts %}} distributions. +After exporting, devices and applications can be imported in other {{% tts %}} deployments. See [add end devices in bulk in {{% tts %}}]({{< ref "/devices/adding-devices/adding-devices-in-bulk" >}}) for details about importing devices. See [Migrating End Devices between {{% tts %}} Distributions]({{< ref "/the-things-stack/migrating/migrating-between-tts-distributions" >}}) to wrap up the whole process of migration between {{% tts %}} distributions. diff --git a/doc/content/whats-new/3.20.2.md b/doc/content/whats-new/3.20.2.md index 1f8a330864..5dcf67db8d 100644 --- a/doc/content/whats-new/3.20.2.md +++ b/doc/content/whats-new/3.20.2.md @@ -5,7 +5,7 @@ title: "3.20.2" ### Added -- More fields were added to the csv end-device migration procedure. The details on which fields were added can be found [here](https://www.thethingsindustries.com/docs/the-things-stack/migrating/device-csv/). +- More fields were added to the csv end-device migration procedure. The details on which fields were added can be found [here](https://www.thethingsindustries.com/docs/devices/adding-devices/adding-devices-in-bulk/device-csv/). - Authorization management in the Account app. - Gateway remote address to gateway connection statistics. diff --git a/doc/themes/the-things-stack/assets/css/common/global.scss b/doc/themes/the-things-stack/assets/css/common/global.scss index 3b49dc91dc..fd4f5d03b1 100644 --- a/doc/themes/the-things-stack/assets/css/common/global.scss +++ b/doc/themes/the-things-stack/assets/css/common/global.scss @@ -438,6 +438,15 @@ table.api + table.api { } } +.table-devices { + th:nth-child(1) { + width: 1em; + } + th:nth-child(2) { + width: 6em; + } +} + .table-tts-components { th:nth-child(1) { width: 20em; diff --git a/doc/themes/the-things-stack/layouts/_default/list.html b/doc/themes/the-things-stack/layouts/_default/list.html index 6f674d9177..080994737f 100644 --- a/doc/themes/the-things-stack/layouts/_default/list.html +++ b/doc/themes/the-things-stack/layouts/_default/list.html @@ -34,9 +34,7 @@

{{ .Content }}
- {{ if and .Pages (not (eq .Parent .FirstSection)) }} {{ partial "pages-cards.html" .Pages }} - {{ end }} {{ partial "prev-next-in-section" . }} {{ partial "feedback" . }}