# LoRaWAN Communication

## General <a href="#id-9d20c0f2-1c16-414f-acc1-59d28264f3a1" id="id-9d20c0f2-1c16-414f-acc1-59d28264f3a1"></a>

The LoRaWAN Interface is in compliance with the LoRa Alliance specifications, and is based on the LoRa transmission standards.

Using the LoRa protocol the device can reliably transmit data over large distances without permanent communication.

The interface constantly adapts to the optimal transmit and receive parameters individually to ensure a stable and reliable link to the LoRaWAN Gateway.

The status of the link to the LoRaWAN network is shown on the device’s display.

* The LoRaWAN interface is compatible with **LoRaWAN V1.0.4** and is a **Class C** devic&#x65;**.**
* The required parameters and configuration of the LoRaWAN interface are permanently saved inside the device.

All devices are delivered with OTAA mode enabled, the DevEUI of the device is listed on the package and on the device itself.

### Infrastructure <a href="#id-9d34aa66-8214-49d3-8687-d3647af691f9" id="id-9d34aa66-8214-49d3-8687-d3647af691f9"></a>

The Customer is responsible for a working LoRaWAN Infrastructure, a typical LoRaWAN infrastructure consists out of;

* LoRaWAN Gateway
* Network Server

If needed YOBIIQ can support customer with the selection and configuration of the infrastructure, this however is not covered by the normal support coverage.

YOBIIQ also supplies a turn-key LoRaWAN Infrastructure if Customer has no experience with the required infrastructure.

### (Re)Join Requests <a href="#id-70356741-40b0-4e43-ae0e-7b4a9c65c899" id="id-70356741-40b0-4e43-ae0e-7b4a9c65c899"></a>

The LoRaWAN interface will perform automatic rejoin requests to the network as configured.

A Rejoin requests will always be sent once every 24 hours, this will allow for easy migrations to another LoRaWAN network.

As long as the device is not connected to a LoRaWAN network, the interface regularly tries to connect to a LoRaWAN network.

These Join requests occur randomly in a \~10 min time period to counteract bandwidth problems if multiple devices are in the same network.

### Time synchronization <a href="#id-9162e73c-e25b-4096-a7c1-62a613f99205" id="id-9162e73c-e25b-4096-a7c1-62a613f99205"></a>

The LoRaWAN Interface performs a time synchronization during normal operation, it performs this at least once every 24 hours.

The device will adjust its internal clock to match with the time returned by the time synchronization.

### Sending measurement registers <a href="#id-1e58632e-79c5-4691-8db9-12f7c5ff3afe" id="id-1e58632e-79c5-4691-8db9-12f7c5ff3afe"></a>

The device sends all requested measurements directly from its datalogger via LoRaWAN without any changes to the data.

The requested measurements are read from the data logger at the due date of the interval.

Example of a transmission interval of 15 minutes:

* 10:00:10am: The LoRaWAN communication module reads out the latest data logger entry. The values stored there are from 10:00:00am.
* 10:00:11am ­ 10:14:59am: The device tries to transmit the data via the LoRaWAN network.

Notes on the transmission of measurements;

* Be aware that, if you operate multiple devices in the same LoRaWAN network, transmissions by these meters may collide. The device will however adjust its transmit parameters to ensure smooth transmissions.
* Please make sure that both the device and the LoRaWAN network are configured in such a way that the device can transmit its full package to avoid losing data in failed transmissions.

***

## Device Payloads <a href="#id-7dfe53ba-1089-4da1-be27-658137cfa693" id="id-7dfe53ba-1089-4da1-be27-658137cfa693"></a>

All data are based on following format(HEX), the Data field should follow big-endian:

| Channel 1 | Type 1 | Data 1  | Channel 2 | Type 2 | Data 2  | … |
| --------- | ------ | ------- | --------- | ------ | ------- | - |
| 1 Byte    | 1 Byte | N Bytes | 1 Byte    | 1 Byte | N Bytes |   |

### Basic Information <a href="#id-8d90ce0f-b608-4cdb-914b-c19cf60cf81f" id="id-8d90ce0f-b608-4cdb-914b-c19cf60cf81f"></a>

The device sends basic information upon joining a network, and after a reboot.

The basic information is sent over fPort 50

| Channel | Type                    | Description                                    |
| ------- | ----------------------- | ---------------------------------------------- |
| **ff**  | 00 (Status)             | Status of the device                           |
|         | 01 (Manufacturer)       | Hex of the manufacturer                        |
|         | 02 (Model)              | Hex of the model                               |
|         | 03 (Device SN)          | 7 digits serial number                         |
|         | 11 (Device Class)       | 0x00: Class A, 0x01: Class B, 0x02: Class C    |
|         | 06 (Power Event)        | 0x00: AC Power Off, 0x01: AC Power On          |
|         | 05 (Hardware Version)   | Hardware version, example 0100 is version 1.00 |
|         | 04 (Firmware Version)   | Firmware version, example 0100 is version 1.00 |
|         | 07 (Battery Voltage)    | Random voltage                                 |
|         | 08 (Battery Percentage) | Random percentage                              |

### Device Data <a href="#a7f7674a-7d57-4fb6-9003-eb313812905a" id="a7f7674a-7d57-4fb6-9003-eb313812905a"></a>

The device allows for configuration of the registers that should be sent and in which interval by using a downlink message.

There are 10 ports available for this configuration which are represented by the fPorts 1-10, each fPort can hold 5 channels.\
This means that a total of 50 registers can be configured.

The lower slots have a higher priority.\
The device comes with a “Default Uplink” configured on fPort 1.\
All downlink commands should be send to the Application port, which the configuration is for

The fPort and Channel are configured under the device as discused within the [Serial Communication](https://docs.yobiiq.com/welcome/user-manual-iq-opentherm/lorawan/broken-reference) chapter.

{% hint style="info" %}
If a configuration downlink is send to fPort 1, the default uplink is overwritten!
{% endhint %}

The structure of modbus data point is as follow:

| Channel           | Type                     | Data                | Description                                             |
| ----------------- | ------------------------ | ------------------- | ------------------------------------------------------- |
| 0xDD              | 0xFE                     | Device timestamp    | Current timestamp of the device, taken from device RTC. |
| Modbus Channel ID | Modbus Channel data type | 4 - 7 bytes of data | Modbus Channel data point                               |

The data field of modbus channel data point has between 4 to 7 bytes and contains the following information:

| Data Byte (4 - 7 bytes)     | Byte Field Name                   | Data Byte Description                                                                                                           |
| --------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Byte0 + Byte1 + Byte2\[7:4] | Logger Timestamp Offset           | <p>Uint20, 20 bits<br> Logger Timestamp Offset :<br>Channel Logger Timestamp = Device Timestamp - Logger Timestamp Offset</p>   |
| Byte2\[3:2]                 | Modbus Channel Byte Order         | <p>Uint2, 2 bits<br>Modbus Channel Byte Order : <br>0 = ABCD<br>1 = CDBA<br>2 = BADC<br>3 = DCBA</p>                            |
| Byte2\[1:0]                 | Modbus Channel Register Data Size | <p>Uint2, 2 bits<br>Modbus Channel Register Data Size : <br>0 = 4 bytes of data<br>1 = 1 byte<br>2 = 2 bytes<br>3 = 3 bytes</p> |
| 1 to 4 bytes                | Modbus Channel Register Data      | The data size is specified in the **Modbus Channel Register Data Size** field                                                   |

### Default Uplink <a href="#id-8b99be12-e222-4095-a4e4-bf8bab89bc7a" id="id-8b99be12-e222-4095-a4e4-bf8bab89bc7a"></a>

The device reports a default uplink on fPort 1 with an interval of 15 minutes.

This allows for testing the connectivity of the device and receive basic registers readings without any configuration to the device.

| Channel                       | Type                     | Item                | Description                                             |
| ----------------------------- | ------------------------ | ------------------- | ------------------------------------------------------- |
| 0xDD                          | 0xFE                     | Device timestamp    | Current timestamp of the device, taken from device RTC. |
| 0xC8 => Modbus Channel ID 200 | Modbus Channel data type | 4 - 7 bytes of data | Modbus Channel data point                               |
| 0xC9 => Modbus Channel ID 201 | Modbus Channel data type | 4 - 7 bytes of data | Modbus Channel data point                               |

The default modbus channel configuration :&#x20;

<table><thead><tr><th width="235">Modbus Channel ID</th><th width="131">Log Interval</th><th>Slave ID</th><th width="157">Modbus Address</th><th width="190">Modbus Data Type</th><th width="171">Byte Order</th><th width="189">Channel Active</th></tr></thead><tbody><tr><td>0xC8 => Channel ID 200</td><td>5 minutes</td><td>1</td><td>0x0038</td><td>4 =>  Holding 32bit</td><td>3 => DCBA</td><td>1 => channel enabled</td></tr><tr><td>0xC9 => Channel ID 201</td><td>5 minutes</td><td>1</td><td>0x003A</td><td>5 =>  Holding Float</td><td>3 => DCBA</td><td>1 => channel enabled</td></tr></tbody></table>

### Alarms <a href="#e678f20a-9dfb-49eb-a2be-6cfa7697d0e8" id="e678f20a-9dfb-49eb-a2be-6cfa7697d0e8"></a>

If an alarm occurs within the device an uplink message is immediately send over fPort 11.\
The message contains the register number of the alarm and the current value.<br>

<table><thead><tr><th width="182">Channel</th><th width="228.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>0xAA</td><td>0xFE</td><td>Current timestamp of the device, taken from device RTC.</td></tr><tr><td>0xAA</td><td>0x00</td><td></td></tr><tr><td>0xAA</td><td>0x01</td><td>LoRaWAN watchdog alarm<br>0x00 : normal<br>0x01 : alarm</td></tr><tr><td>0xAA</td><td>0x02</td><td>Serial watchdog alarm<br>0x00 : normal<br>0x01 : alarm</td></tr><tr><td>0xAA</td><td>Modbus Channel ID : Uint8 [200 to 249]</td><td>Modbus Channel Operation Alarm<br>0x00 : normal<br>0x01 : generic exception<br>0x02 : crc checking failure<br>0x03 : response size error<br>0x04 : illegal slave id<br>0x05 : response timeout<br>0x81 : illegal function code <br>0x82 : illegal modbus address<br>0x83 : illegal write value<br>0x84 : slave device failure<br>0x85 : write operation failure</td></tr></tbody></table>

## Downlink Commands <a href="#id-047b17f3-16e3-430f-ac7b-dc40c4237a55" id="id-047b17f3-16e3-430f-ac7b-dc40c4237a55"></a>

### Device Configuration <a href="#id-1eda7896-759c-476b-9e8e-698ec6b7d7b9" id="id-1eda7896-759c-476b-9e8e-698ec6b7d7b9"></a>

The device supports downlink commands to configure the device, the application port is 50 by default.

| Channel | Type         | Description                                                     |
| ------- | ------------ | --------------------------------------------------------------- |
| ff      | 0a (Reboot)  | <p>1 Byte, Uint8<br>01 => Reboot the device<br></p>             |
| ff      | 0b (Restart) | <p>1 Byte, Uint8</p><p>01 => Restart the LoRaWAN Interface.</p> |

#### Example <a href="#id-96a98756-a169-4865-bf24-32b5d3bd59f8" id="id-96a98756-a169-4865-bf24-32b5d3bd59f8"></a>

Restart the LoRaWAN Interface.

| ff0b01      |              |               |   |   |   |
| ----------- | ------------ | ------------- | - | - | - |
| **Channel** | **Type**     | **Value**     |   |   |   |
| ff          | 0b (Restart) | 01 => Restart |   |   |   |

### Periodic Packages <a href="#id-494cd571-d683-4841-a478-c6f2b0934f45" id="id-494cd571-d683-4841-a478-c6f2b0934f45"></a>

To configure the periodic uplinks by the device you can send a downlink to fPort 1 to 5.\
Each fPort can hold 5 modbus channel IDs.\
To configure a modbus channel, please go to [Modbus Channel Configuration](https://docs.yobiiq.com/welcome/user-manual-iq-opentherm/lorawan/broken-reference)

{% hint style="info" %}
If confirmed mode is off, the device will send a package 1 time; if confirmed mode is on, the device will resend a package maximum of 3 times if it does not get an acknowledgement from the network.
{% endhint %}

<table><thead><tr><th width="120.33333333333331">Channel</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>ff</td><td>14 (Interval)</td><td><p>1 Byte, Uint 8</p><p>Set the interval of the uplink, in minutes.</p></td></tr><tr><td></td><td>15 (Confirmed)</td><td><p>1 Byte, Uint 8</p><p>Confirmed mode off => 0 or confirmed mode on => 1</p></td></tr><tr><td></td><td>16 (Active)</td><td><p>1 Byte, Uint 8</p><p>Set the status of the fPort : inactive => 0 or active => 1</p></td></tr><tr><td></td><td>17 (Registers)</td><td>Maximum of 5 modbus channel ID<br>(only configured modbus channels will be sent periodically)</td></tr></tbody></table>

### Device Parameter Reading

The device supports downlink commands to read its readable parameters, the application port is 100 by default.<br>

<table><thead><tr><th width="120.33333333333331">Channel</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>FF</td><td>CC (Read Parameter)</td><td>Maximum of 10 parameter types<br>(only readable parameters)</td></tr></tbody></table>