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

# Overview

Configure devices on site by scanning a QR code, with names, tags, and custom fields filled in from a mapping file.

The **Device Setup Assistant** is the app an installer uses at the point of installation. They scan the QR code on a device, confirm it is the right one, and the device is recorded as belonging to a particular desk, room, or floor.

It exists because the hard part of a large rollout is not mounting the sensors, it is keeping track of which sensor ended up where. Doing that afterwards, from a spreadsheet and a photo of a serial number, is where rollouts lose their afternoons. The Device Setup Assistant moves that step to the moment the device goes up, and it can be handed to someone who has never used akenza.

It runs on a phone and on a desktop browser, so the same flow works whether devices are being mounted in a building or configured at a bench.

{% hint style="info" %}
The Device Setup Assistant is available on **Expert plans**. See [akenza.io/pricing](https://akenza.io/pricing) for what each tier includes.
{% endhint %}

## Before you start

Three things have to exist before an installer arrives on site:

* **The devices**, created in the workspace. The assistant configures devices that are already there, it does not create them. For a fleet, create them with a [bulk import](/device-management/create-new-device/asset-bulk-import.md).
* **The** [**tags**](/device-management/managing-a-workspace/tags.md) **and** [**custom fields**](/device-management/managing-a-workspace/custom-fields.md) you want filled in, defined in the workspace.
* **A mapping file**, if you want values pre-filled rather than typed. It is uploaded in the [workspace settings](/device-management/managing-a-workspace/general-settings/device-setup-assistant.md).

## Setting up a device

{% stepper %}
{% step %}

### Scan the QR code

Scanning the code on the device opens it directly in the assistant. The code has to resolve to this URL, where the parameter is the device ID or DevEUI:

```url
https://api.akenza.io/v3/resolve-device?deviceId=0018B20000001122
```

Many manufacturers ship LoRaWAN sensors with a code in this form on request. Where a device has no usable code, the installer picks it from the list of devices in the workspace instead.
{% endstep %}

{% step %}

### Check that it is the right device

The device overview confirms what was scanned. If the device has already sent data, **Last Message Time** tells you it is alive, alongside its signal quality and battery level. Any tags and custom fields it already carries are shown here too.

This is the moment to catch a device that is dead on arrival, while you are still standing next to it and a ladder is still in the room.
{% endstep %}

{% step %}

### Configure it

Fill in the tags and custom fields for the physical device: where it is, what it monitors, whatever your fleet is organized by.

With a mapping file in place this collapses to a single choice. The installer selects the **primary field**, for example the desk they are standing at, and the rest is filled in from the file.
{% endstep %}

{% step %}

### Save

Saving writes the values onto the device in akenza. It is immediately visible in the asset inventory, and the values can be used in filters, [rules](/device-management/rule-engine.md), and the [Data Fusion Layer](/data-fusion-layer/data-fusion-layer.md) like any other.
{% endstep %}
{% endstepper %}

<figure><img src="https://2165942204-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MMKXTFIN5ZlLOjBlfC4%2Fuploads%2Fgit-blob-bec7875f38d965f43e4338ebc29fea6665a2d132%2Fdevice-setup-assistant-phone.jpeg?alt=media" alt="The Device Setup Assistant on a phone" width="188"><figcaption><p>The assistant on a phone, at the point of installation</p></figcaption></figure>

## The mapping file

A mapping file is a CSV that describes the installation in advance: every position that will receive a device, and what should be recorded about it. On site the installer chooses one value and everything else follows, which is both faster and harder to get wrong than typing at the top of a ladder.

### How the columns work

<table><thead><tr><th width="200">Column</th><th>What it does</th></tr></thead><tbody><tr><td><code>deviceName</code></td><td>Reserved. Sets the name of the device. The column has to be spelled exactly like this.</td></tr><tr><td><code>tags</code></td><td>Reserved. The tags to assign, separated by commas inside one cell. The column has to be spelled exactly like this.</td></tr><tr><td><em>your custom fields</em></td><td>One column per custom field, named exactly as the field is named in the workspace.</td></tr></tbody></table>

One of the custom field columns is nominated as the **primary field**. That is the one the installer picks from on site, so it has to be something readable in the physical world: a desk label, a room number, an asset sticker. Every other column is filled in from the row that matches.

{% hint style="warning" %}
Tags and custom fields named in the file must already exist in the workspace, spelled identically. A column that does not match anything is not applied, and nothing warns the installer on site.
{% endhint %}

### An example

{% file src="/files/ZCALLA9vxX8tHLRY7ufV" %}

The template describes a desk occupancy rollout:

| assetId | deviceName | building | floor | type | tags           |
| ------- | ---------- | -------- | ----- | ---- | -------------- |
| A102    | Desk A102  | A        | 1     | Desk | Occupancy,Desk |
| A201    | Desk A201  | A        | 2     | Desk | Occupancy,Desk |
| A300    | Desk A300  | A        | 3     | Desk | Occupancy,Desk |

Here `assetId` is the primary field, matching the label already on each desk. `building`, `floor`, and `type` are custom fields, and the two tags are assigned from one cell. An installer mounting a sensor under desk A201 scans it, picks `A201`, and the device is named, placed on floor 2 of building A, and tagged, in one action.

## Configuring it for a workspace

The mapping file is uploaded per workspace, in the workspace settings:

{% content-ref url="/pages/Eb0oWEKbLMdX9wd02KZL" %}
[Device Setup Assistant](/device-management/managing-a-workspace/general-settings/device-setup-assistant.md)
{% endcontent-ref %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akenza.io/device-setup-assistant/device-setup-assistant.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
