> For the complete documentation index, see [llms.txt](https://docs.widgelix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.widgelix.com/lorawan-network-server/user-guide.md).

# User Guide

### Table of contents

1. Overview
2. Access requirements
3. Activating the Network Server
4. Recommended setup workflow
5. Gateways
6. Device profiles
7. Devices
8. Monitoring connectivity
9. Troubleshooting
10. Quick reference checklist

***

### Overview

The **LoRaWAN Network Server** module lets your organization manage LoRaWAN infrastructure directly from the platform:

* **Gateways** — base stations that receive and forward LoRaWAN radio traffic
* **Device profiles** — reusable radio and protocol settings for groups of devices
* **Devices** — individual LoRaWAN end devices registered on the network server

Open the module from the sidebar: **LoRaWAN Server**.

The page has three tabs:

| Tab                 | Purpose                                                   |
| ------------------- | --------------------------------------------------------- |
| **Gateways**        | Register and monitor LoRaWAN gateways                     |
| **Device Profiles** | Define radio region, MAC version, and activation settings |
| **Devices**         | Register end devices and configure OTAA/ABP keys          |

***

### Access requirements

To use LoRaWAN features, a user must have:

1. **Menu access** — **LoRaWAN Server** must be enabled for their role
2. **Module permissions** — at minimum **Read** on the **LoRaWAN** module

| Action                                            | Required permission  |
| ------------------------------------------------- | -------------------- |
| View gateways, profiles, and devices              | LoRaWAN → **Read**   |
| Activate the Network Server, add or edit entities | LoRaWAN → **Write**  |
| Delete gateways, profiles, or devices             | LoRaWAN → **Delete** |

> **Note:** The default **Viewer** role does **not** include LoRaWAN access. Viewers can see the menu item only if an administrator grants it explicitly via a custom role.

For details on roles, permissions, and entity-level restrictions, see Roles & Permissions — User Guide.

***

### Activating the Network Server

Before you can manage gateways, profiles, or devices, the LoRaWAN Network Server must be activated for your organization.

1. Go to **LoRaWAN Server** in the sidebar.
2. If the server is not yet active, you will see **Activate LoRaWAN Network Server**.
3. Click **Activate**.

Activation is a one-time setup step per organization. It provisions the underlying network server tenant and application for your organization.

> **Who can activate:** Users with **Write** permission on the LoRaWAN module (typically **Admin** or **Contributor** roles).

After activation, the three management tabs become available.

***

### Recommended setup workflow

For a new LoRaWAN deployment, follow this order:

```
1. Activate the Network Server
        ↓
2. Create device profile(s)
        ↓
3. Register gateway(s)
        ↓
4. Register device(s)
        ↓
5. Configure OTAA or ABP keys on the physical device
```

**Why this order matters:**

* Every device must be linked to a **device profile** before registration.
* Gateways should be registered before devices start transmitting, so uplinks can be received immediately.
* Device keys (OTAA or ABP) must match what is configured in both the platform and on the physical device.

***

### Gateways

Gateways are LoRaWAN base stations. They receive radio packets from end devices and forward them to the network server.

#### Viewing gateways

The **Gateways** tab shows a table with:

| Column          | Description                                           |
| --------------- | ----------------------------------------------------- |
| **Gateway ID**  | Unique identifier of the gateway (EUI)                |
| **Name**        | Human-readable label                                  |
| **Description** | Optional notes                                        |
| **Last Seen**   | Last time the gateway connected to the network server |

If gateways have location coordinates, a **Locations** map is shown below the table.

Use the **Refresh** button (↻) in the tab bar to reload the list.

#### Adding a gateway

1. Open the **Gateways** tab.
2. Click **Add Gateway**.
3. Fill in the form:

| Field           | Required | Description                                                                      |
| --------------- | -------- | -------------------------------------------------------------------------------- |
| **Gateway ID**  | Yes      | The gateway EUI as printed on the device or in its documentation                 |
| **Name**        | Yes      | A descriptive name for your team                                                 |
| **Description** | No       | Optional notes                                                                   |
| **Location**    | No       | Enable the location toggle and use **Select On Map** to pin the gateway on a map |

4. Click **OK** to save.

> **Tip:** Adding a location helps with network planning and map-based monitoring.

#### Editing or deleting a gateway

* Click the **Edit** icon (pencil) to change the name or description. The Gateway ID cannot be changed after creation.
* Click the **Delete** icon (trash) to remove a gateway. This action is permanent.

Edit and delete actions require **Write** and **Delete** permissions respectively. If your role uses entity-level restrictions, you may only manage gateways explicitly assigned to you.

***

### Device profiles

A **device profile** defines the radio and protocol behavior for a group of LoRaWAN devices: frequency region, LoRaWAN MAC version, activation method (OTAA/ABP), and optional Class B/C support.

#### Viewing device profiles

The **Device Profiles** tab lists all profiles with:

| Column                | Description                                       |
| --------------------- | ------------------------------------------------- |
| **Name**              | Profile name                                      |
| **Region**            | Frequency plan (e.g. EU868, US915)                |
| **MAC Version**       | LoRaWAN protocol version                          |
| **OTAA**              | Whether Over-The-Air Activation is supported      |
| **Class B / Class C** | Whether the profile supports these device classes |

#### Adding a device profile

1. Open the **Device Profiles** tab.
2. Click **Add Device Profile**.
3. Configure the profile in the collapsible sections:

**General**

| Field                            | Required | Description                                          |
| -------------------------------- | -------- | ---------------------------------------------------- |
| **Name**                         | Yes      | Profile name (e.g. "EU868 OTAA Sensors")             |
| **Description**                  | No       | Optional notes                                       |
| **Region**                       | Yes      | Frequency band — must match your gateway and devices |
| **MAC Version**                  | Yes      | LoRaWAN version supported by your devices            |
| **Regional Parameters Revision** | Yes      | Regional parameters spec revision                    |
| **Region Config ID**             | No       | Optional advanced region configuration               |

**Join & Activation**

| Setting                            | Description                                                            |
| ---------------------------------- | ---------------------------------------------------------------------- |
| **OTAA**                           | Enable for devices that join over the air (recommended for production) |
| **Flush queue on activate**        | Clear downlink queue when a device activates                           |
| **Allow roaming**                  | Enable roaming support                                                 |
| **Auto-detect measurements**       | Automatically detect device measurements                               |
| **Uplink interval**                | Expected uplink interval in seconds                                    |
| **Device-status request interval** | How often to request device status                                     |
| **RX1 delay**                      | Receive window 1 delay in seconds                                      |
| **ADR algorithm ID**               | Adaptive Data Rate algorithm identifier                                |

**Class B / Class C**

Enable only if your devices support these classes. Additional timeout and ping-slot settings appear when enabled.

**ABP Parameters**

Configure RX window settings used when OTAA is disabled or for ABP-activated devices.

4. Click **OK** to save.

> **Important:** Choose the **Region** and **MAC Version** that match your hardware. Mismatched settings will prevent devices from joining or communicating.

#### Supported regions

EU868, US915, CN779, EU433, AU915, CN470, AS923, KR920, IN865, RU864, ISM2400, AS923-2, AS923-3, AS923-4

#### Supported MAC versions

LoRaWAN 1.0.0 through 1.0.4, and LoRaWAN 1.1.0

***

### Devices

LoRaWAN **devices** in this module are network-server registrations. They are separate from, but can be linked to, platform **Devices** used for data visualization and rules.

#### Viewing devices

The **Devices** tab shows:

| Column             | Description                                               |
| ------------------ | --------------------------------------------------------- |
| **DevEUI**         | Unique device identifier                                  |
| **Name**           | Device name                                               |
| **Description**    | Optional notes                                            |
| **Device Profile** | Assigned profile                                          |
| **Last Seen**      | Last time the device communicated with the network server |

#### Adding a device

1. Open the **Devices** tab.
2. Click **Add Device**.
3. Configure the device in the form sections:

**General**

| Field              | Required | Description                                                      |
| ------------------ | -------- | ---------------------------------------------------------------- |
| **DevEUI**         | Yes      | Select an existing platform device, or enter the DevEUI manually |
| **Name**           | Yes      | Device name                                                      |
| **Description**    | No       | Optional notes                                                   |
| **Device Profile** | Yes      | Select a previously created profile                              |
| **JoinEUI**        | No       | Join EUI (AppEUI) for OTAA activation                            |

> **Tip:** Selecting a device from the platform list automatically fills the DevEUI and name, linking the network-server registration to your existing device record.

**Options**

| Setting             | Description                                             |
| ------------------- | ------------------------------------------------------- |
| **Skip FCnt check** | Disable frame counter validation (use only for testing) |
| **Disabled**        | Temporarily disable the device on the network server    |

**Tags / Variables**

Optional key-value metadata attached to the device on the network server.

**OTAA Keys**

Root keys for Over-The-Air Activation:

| Key           | Description                             |
| ------------- | --------------------------------------- |
| **NwkKey**    | Network root key                        |
| **AppKey**    | Application root key                    |
| **GenAppKey** | General application root key (optional) |

Enter the keys exactly as configured on the physical device or printed on its label.

**ABP Activation**

For Activation By Personalization, provide:

| Field                              | Description                              |
| ---------------------------------- | ---------------------------------------- |
| **DevAddr**                        | Device address                           |
| **AppSKey**                        | Application session key                  |
| **NwkSEncKey**                     | Network session encryption key           |
| **SNwkSIntKey**                    | Serving network session integrity key    |
| **FNwkSIntKey**                    | Forwarding network session integrity key |
| **FCntUp / NFCntDown / AFCntDown** | Frame counters                           |

4. Click **OK** to save.

#### OTAA vs ABP — which to use?

| Method                 | When to use                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| **OTAA** (recommended) | Production deployments; devices join securely over the air           |
| **ABP**                | Testing, legacy devices, or environments where OTAA is not supported |

Ensure the activation method matches your **device profile** settings and the configuration on the physical device.

#### Editing or deleting a device

* Click **Edit** to update name, profile, keys, or options. DevEUI cannot be changed.
* Click **Delete** to remove the device from the network server.

***

### Monitoring connectivity

Both gateways and devices show a **Last Seen** timestamp indicating the most recent communication with the network server.

| Last Seen value  | Likely meaning                                      |
| ---------------- | --------------------------------------------------- |
| Recent date/time | Entity is online and communicating                  |
| Empty (—)        | Entity has never connected, or no data is available |
| Stale date/time  | Entity may be offline or out of range               |

Use the **Refresh** button to update timestamps without reloading the page.

***

### Troubleshooting

| Problem                                      | Things to check                                                                          |
| -------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Cannot see **LoRaWAN Server** in the sidebar | Your role lacks **LoRaWAN Server** menu access — contact an administrator                |
| **Activate** button is missing               | Your role lacks **Write** permission on LoRaWAN                                          |
| Device never shows **Last Seen**             | Gateway registered and online? Correct region in profile? Keys match physical device?    |
| Device cannot join (OTAA)                    | JoinEUI, NwkKey, and AppKey correct? Profile has OTAA enabled? Gateway covers the area?  |
| No data in platform dashboards               | Network-server device linked to a platform device? Input node configured for the device? |
| Cannot add gateway/device/profile            | Insufficient **Write** permission, or entity-level restrictions apply                    |

***

### Quick reference checklist

* [ ] User has LoRaWAN Server menu access and Write permission
* [ ] Network Server activated
* [ ] Device profile(s) created with correct region and MAC version
* [ ] Gateway(s) registered with correct Gateway ID
* [ ] Device(s) registered with matching DevEUI and profile
* [ ] OTAA/ABP keys configured on both platform and physical device
* [ ] Last Seen timestamps updating for gateways and devices

***

*This guide describes the LoRaWAN Network Server features available in the platform UI. For role and permission configuration, see Roles & Permissions — User Guide.*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.widgelix.com/lorawan-network-server/user-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.