> For the complete documentation index, see [llms.txt](https://docs.informationhub.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.informationhub.io/project/sensors.md).

# Sensors

The Sensors module lets your project collect data automatically from IoT sensor devices connected through **TTN (The Things Network)**. Instead of someone filling in a form, your sensors send their readings directly to Information Hub, where each reading is decoded and written into your project tables.

Sensors is an **optional module**. It only appears once a project admin turns it on, and all sensor configuration is **admin-only**.

## How it works

At a high level:

1. You create a **metadata table** - one row per device - that tells Information Hub which devices to expect, where their data should go, and how to decode it.
2. You give TTN a **webhook URL and token** so it forwards your sensors' readings to your project.
3. You set up **column maps** so each decoded reading lands in the right table column.
4. Devices then appear automatically on the **Devices** tab as they start sending data, where you can monitor and pause them.

## Before you start

Sensors is off by default. A project **admin** enables it from the project settings page:

1. Open **Settings** from the project sidebar.
2. Find the **Sensors** section and turn on **Enable IoT sensors (TTN) for this project**.

Once enabled, a **Sensors** item (chip icon) appears in the project sidebar and on the project overview page.

{% hint style="info" %}
Everything in the Sensors module is restricted to **project admins**. If you can see the project but not the Sensors module, or you open it and cannot change anything, you likely do not have admin rights on the project.
{% endhint %}

## The Sensors tabs

The Sensors module is organised into tabs across the top:

| Tab             | What it is for                                                                              |
| --------------- | ------------------------------------------------------------------------------------------- |
| **Devices**     | See every device that has sent data, monitor its status, and pause or resume it.            |
| **Setup**       | Designate the metadata table and get your TTN webhook URL and token.                        |
| **Column Maps** | Map decoded sensor fields to the columns in your destination tables.                        |
| **Parsers**     | Build custom parsers that decode raw payloads (see [Parsers](/project/sensors/parsers.md)). |
| **Help**        | An in-app walkthrough of the full TTN setup.                                                |

The first time you open Sensors you land on **Setup**. Once at least one device has sent data, you land on **Devices** instead.

***

## Step 1 - Create the metadata table

The metadata table is an ordinary project table where **each row configures one device**. Create a table (from the **Tables** module) with these columns:

| Column       | Required                                  | Purpose                                                                                                                      |
| ------------ | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `device_eui` | Yes - must be **required** and **unique** | The device's TTN EUI (its unique hardware ID).                                                                               |
| `tables`     | Yes - must be **required**                | The destination table(s) that receive this device's data. Use a comma-separated list of table IDs to write to more than one. |
| `parser`     | Yes                                       | How to decode the device's payload - a built-in parser key or the name of a custom parser.                                   |
| `device_id`  | Optional                                  | A human-readable name for the device.                                                                                        |

{% hint style="info" %}
`device_eui` must be marked **required** and **unique** when you create the column, and `tables` must be marked **required**. The Setup tab validates this for you before you can save.
{% endhint %}

***

## Step 2 - Designate the metadata table and set up the webhook

Open the **Setup** tab.

### Sensor metadata table

1. In the **Metadata Table** search box, find and select the table you created in Step 1.
2. Click **Validate**. Information Hub checks the table has the right columns and settings.
   * If it is correct, you see **Table structure is valid**.
   * If not, a list of validation errors tells you exactly what to fix (for example, a missing column or a `device_eui` column that is not marked unique).
3. Once valid, click **Save** to designate this as the project's sensor metadata table.

### TTN webhook

The Setup tab shows the values you paste into TTN:

* **Endpoint URL** - a unique URL for your project (it includes the project ID so data reaches the right place). Copy it with the copy button.
* **Bearer Token** - a secret token, shown masked. Click the copy button to copy it, or **Regenerate Token** to create a new one (which immediately invalidates the old one).

***

## Step 3 - Configure the webhook in TTN

In the **TTN Console**:

1. Open your application and go to **Integrations → Webhooks → Add webhook → Custom webhook**.
2. Set the **Base URL** to the **Endpoint URL** from the Setup tab.
3. Add a header with key `Authorization` and value `Bearer <token>`, using the **Bearer Token** from the Setup tab.
4. Enable **Uplink message** events.
5. Save the webhook.

TTN will now forward each sensor reading to your project. Information Hub matches each reading to a row in your metadata table by its `device_eui`, decodes it with the chosen parser, and writes it into the destination table(s).

***

## Step 4 - Map fields to columns

Open the **Column Maps** tab to tell Information Hub which decoded sensor field goes into which table column.

1. Use **Add Target Table** to add a destination table. Each table you add gets its own section.
2. In a table's section, add a mapping row for each field:
   * **Sensor field** - the field name from the decoded payload (for example `temperature`).
   * **Target column** - the column in that table where the value should be written.
3. Click **Add Row** for more fields, and **Save All** to save the mappings for that table.

{% hint style="info" %}
Column maps store the column's stable ID rather than its name, so renaming a column later does not break the mapping. Saving a table's maps replaces all current mappings for that table.
{% endhint %}

***

## Devices

The **Devices** tab lists every device that has sent data to your project's webhook. Click **Refresh** to reload the list.

Each device row shows its ID or EUI, how many times it has failed in a row (out of 10), and when it last succeeded. Devices you have not configured yet show a **Add to Metadata Table** button so you can register them quickly, and a status badge shows whether the device is **Active** (green) or **Blacklisted** (red).

### Register a device from the Devices tab

For a device that has sent data but is not yet in the metadata table, click **Add to Metadata Table**:

1. The device's **EUI** (and ID, if known) are filled in for you.
2. Choose the **Target Table** the device's data should go to.
3. Choose a **Parser** - **Decoded Payload (default)**, **Message Default Parser**, or **SenseCap Default Parser** (see [Parsers](/project/sensors/parsers.md) for what these do).
4. Click **Register Device**. This adds a row to your metadata table.

### Pause or resume a device

Each device has a toggle. Switch it **off** to blacklist the device - its incoming readings are paused. Switch it back **on** to resume.

{% hint style="warning" %}
If a device fails to deliver data **10 times in a row**, it is automatically blacklisted and its readings are dropped until you re-enable it. You receive a push notification when this happens. To re-enable a device, go to the **Devices** tab and toggle it back on.
{% endhint %}

***

## Built-in parsers

When you register a device you choose a parser. The built-in options are:

* **Decoded Payload (default)** - uses whatever TTN's payload formatter has already decoded. Best for most sensors.
* **Message Default Parser** - a decoder for SNOET, Dragino, Sentrius, Smart Room, and Milesight devices.
* **SenseCap Default Parser** - for SenseCAP sensors; maps their numeric measurement codes to readable names such as temperature, humidity, CO₂, and light.

If none of these fit your device, you can build your own - see [Parsers](/project/sensors/parsers.md).

## In this section

{% content-ref url="/pages/atuzeQEr2s0KfQend12B" %}
[Parsers](/project/sensors/parsers.md)
{% endcontent-ref %}