# TheThingsNetwork Integration

### Overview

TheThingsNetwork is LoRaWAN network designed for connecting your devices using LoRaWAN stack. After integrating TheThingsNetwork with Tesenso IoT Cloud, you can connect, communicate, process and visualize data from devices in the Tesenso IoT Cloud.

### The ThingsNetwork setup

The first step is to create an **application** in TheThingsNetwork console. Go to console (<https://console.cloud.thethings.network/>), open **Applications** section, press **add application** button and fill required fields.

* **Application ID** - tb\_platform
* **Handler registration** - ttn-handler-eu

Handler registration - used to identify region where application will be registered. In our example it will be *eu* region.

<figure><img src="https://111806075-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mg4otljWU9FsHKYhTsW%2Fuploads%2FvHHWOcDtsdWZyfZCZOPU%2Fttn-add-application.png?alt=media&#x26;token=cffe6286-8908-4b8a-949a-dc740853819f" alt=""><figcaption></figcaption></figure>

### Payload Decoder

Our device submits data in binary format. We have 2 options where to decode this data:

* **TheThingsNetwork decoder** - data will be decoded before entering the Tesenso IoT Cloud
* Tesenso IoT Cloud **converters** - uplink/downlink converters will be used to decode data from binary format into JSON

In this tutorial, we will make an initial transformation into JSON with TTN decoder and then use Tesenso IoT Cloud converters for correct data processing. In real life scenario, it is up to you where to decode/encode data, because it is possible to do this on any side.

After application registered in TTN, go to **payload\_formats**, select decoder function. We will take the first byte as a temperature value from a device and transform it into JSON.

#### Decode Function

```
function Decoder(bytes, port) {
  var decoded = {temperature: bytes[0]};
  return decoded;
}
```

#### Output json:

```
{
  "temperature": 15
}
```

<figure><img src="https://111806075-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mg4otljWU9FsHKYhTsW%2Fuploads%2FCw5TQ3ZLdZHwYsTjjWMN%2Fttn-decoder.png?alt=media&#x26;token=fb64b89e-f48d-4723-9e77-775327a4adb3" alt=""><figcaption></figcaption></figure>

Press **Save payload function**

### Device Registration in TheThingsNetwork

Next step is a Device creation in the TTN. Open **Devices** page and press **register device**

* Device ID - thermostat\_a
* Device EUI - press generate button for generating random identified

<figure><img src="https://111806075-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-Mg4otljWU9FsHKYhTsW%2Fuploads%2FGqhqUzE3L6uasHqjD6eG%2Fttn-add-device.png?alt=media&#x26;token=3f0445c1-3427-4eb4-b0ba-1912d270b60a" alt=""><figcaption></figcaption></figure>

Press **Register** button.&#x20;

### Integration with Tesenso IoT Cloud

We made all required configurations in the TheThingsNetwork (register application, add decoder function and register device). Now we can start configuring Tesenso IoT Cloud.

#### Tesenso IoT Cloud Uplink Data Converter

First, we need to create an Uplink Data Converter which will be used for receiving messages from the TTN. The converter should transform incoming payload into the required message format. Message must contain **deviceName** and **deviceType**. Those fields are used for submitting data to the correct device. If a device was not found a new device will be created. Here is how payload from TheThingsNetwork will look like:

```
{
    "app_id": "tb_platform",
    "dev_id": "thermostat_a",
    "hardware_serial": "*********",
    "port": 1,
    "counter": 0,
    "payload_raw": "Dw==",
    "payload_fields": {
        "temperature": 15
    },
    "metadata": {
        "time": "2018-06-07T17:31:18.670792607Z"
    }
}
```

We will take **dev\_id** and map it to the **deviceName** and **app\_id** to the **deviceType**. But you can use another mapping, which fits your specific use cases. Also, we will take the value of the **temperature** field and use it as a device telemetry.

Go to **Data Converters** and create new **uplink** Converter with this function:

```
var data = decodeToJson(payload);
var deviceName = data.dev_id;
var deviceType = data.app_id;

var result = {
    deviceName: deviceName,
    deviceType: deviceType,
    telemetry: {
         temperature: data.payload_fields.temperature
    }
};

function decodeToString(payload) {
    return String.fromCharCode.apply(String, payload);
}

function decodeToJson(payload) {
    var str = decodeToString(payload);
    var data = JSON.parse(str);
    return data;
}

return result;
```

(insert "Add Data Converter" Picture)

#### Tesenso IoT Cloud Downlink Data Converter

For sending Downlink messages from Tesenso IoT Cloud to the device inside TTN, we need to define a Downlink Converter. In general, the output from the Downlink Converter should have the following structure:

```
Insert Converter here
```

* **contentType** - defines how data will be encoded {TEXT | JSON | BINARY}
* **data** - actual data will be sent to the device in TTN. More details about API can be found in this TTN API (<https://www.thethingsnetwork.org/docs/applications/mqtt/api/>)
* **metadata** - in this object you should place correct devId value  that will be used to identify target device in TTN

Go to **Data Converters** and create new **downlink** Converter with this function:

```
Insert downlink Converter here
```

This converter will take the **version** field from the incoming message and add it as a payload field in the outbound message. The destination device is a **thermostat\_a** device.

(insert "Add Data Converter" Picture)

#### TTN Integration

Next we will create the integration with TheThingsNetwork inside Tesenso IoT Cloud. Open **Integrations** section and add new Integration with type **TheThingsNetwork**

* Name: ttn\_integration
* Type: TheThingsNetwork
* Uplink data converter: ttn\_converter
* Downlink data converter: ttn\_*downlink\_*&#x76;ersion
* Region: eu (region where your application was registered inside TTN)
* Application ID: tb\_platform (use **Application ID** from TTN)
* Access Key: use **Access Key** from TTN