First-Run Setup Wizard

After the first administrator is created, the admin panel offers the setup wizard in the dialog Your setup wizard is ready — click Start setup. The wizard walks you through commissioning: what kind of project, where it is, how it reaches the KNX bus, which services run, and what the building contains. You can also open it later with the Setup wizard button on the System page.

How the wizard works

• Nothing is written to the server until the final apply. Every earlier step only stages a draft.
• The draft survives reloads — it is kept in the browser you are using, so you can close the page and come back on the same computer; your answers are still there.
• Save & exit, in the header, leaves the wizard and keeps the draft for later. Skip setup — configure later, below the step list, leaves the wizard and discards the draft. Both land on the System page.
• Navigate with Back and Continue. The header shows your progress ("Step 2 of 7" — the ETS route has one extra step, so it counts to 8).

Step 1 — Setup mode

"How do you want to build this project?" Three choices:

• Import an ETS project (Fastest route) — upload the .knxproj file from the installation and HyperVisu rebuilds the visualization from what ETS already knows: buildings and rooms become floors and rooms, group addresses arrive named and typed, ETS functions become devices with their group objects already assigned.
• Configure manually (No file needed) — describe the building yourself. Best when there is no ETS project at hand, or when the visualization should not follow it.
• Restore a HyperVisu backup instead — a backup brings back a full server (rooms, devices, users and services), so the rest of the wizard is not needed. Choose a file does not open a file picker: it leaves the wizard and opens the Backup & Restore page, where you restore the file under Restore from file (see “Backup & Restore”). There you are not asked for a password or for a selection of services — the whole file is restored and replaces what is on the server, including the administrator you just created.

📘 Note: You can change your mind later — switching mode sends you back to step 4, because the two screens after it belong to the other route. What you entered on the abandoned route is kept in case you switch back.

Step 2 — Project & location

"Name the project and place it on the map."

Coordinates and timezone drive sunrise and sunset times, scheduled automations, and every timestamp the server writes — set them accurately.

Step 3 — KNX bus interface

"Connect to the bus." The wizard scans the network once for KNX/IP interfaces when the step opens and lists what answered as cards showing the interface name, type (Interface or Router), address and serial. Click Scan again to repeat the scan.

If nothing answers, or the interface is on another subnet or behind a VPN, use Enter an address manually: type the address and the port in the one field, for example 192.168.1.20:3671. Without a port, 3671 is used.

Also set:

• Connection type — Tunnel (UDP, for a KNX/IP interface) or Multicast (for a KNX/IP router). Selecting a discovered card sets it for you; for an address typed by hand, set it yourself.
• HyperVisu physical address — the individual address the server itself takes on the bus. It is pre-filled with 1.1.250 and must be free on the bus.

The connection test. Click Run connection test to see how far the connection gets. Five results appear:

When the tunnel opens, the panel shows Tunnel open and the footer reads "Tunnel open — the bus answers."

An open tunnel proves the connection; only Telegrams seen proves real bus traffic. Once the tunnel is open, the test listens for about five seconds, so 0 on a quiet bus is not a fault. To see traffic, click Test again and operate a wall switch straight away, while the test runs.

📘 Note: When you run the wizard again on a server that is already connected to the bus, the test does not open a second tunnel, because that could take the running connection down. It reports the live connection and counts no telegrams.

If the tunnel does not open, the panel shows No response and the wizard suggests three things to check: tunnelling enabled on the interface, no other ETS client holding every channel, and the server and interface on the same VLAN.

This step never blocks: you can continue without testing, or after a failed test, and fix the connection later.

No bus on site yet? Click I'll configure KNX later. The wizard applies without a bus connection — rooms, devices and services are created normally, and anything bound to KNX stays silent until an interface is set in Connections (see “Connections”).

Step 4 — Services

"Which services should run?" The toggles are grouped in three sections, the same ones as on the Services page. Each section carries one chip that says what a change in it costs:

Defaults on: the KNX and Virtual protocols, and InfluxDB (the history database). The button above the cards shows how many are enabled and resets them to these defaults.

A card badged API key needed also needs a key or credentials: complete it on the Services page after the wizard (see “Services & Protocols”).

Enable only what this project uses — each service costs memory and startup time. Everything can be switched on later from Services & protocols.

Manual branch — Building structure

(Steps 5–6 depend on the setup mode. This screen and the next appear on the manual route.)

"List the floors and their rooms."

1. The wizard starts with a Ground floor (level 0). To add another floor, type its name in the Add a floor line and press Enter.
2. Type a room name and press Enter to add the next one — one room per line, as fast as you can type.
3. To add many at once, use Add several rooms at once: pick the floor, type names separated by commas ("Bedroom 2, Bedroom 3, Dressing"), and click the add button.
4. Icons are optional now — the app falls back to the room name until you set one.
5. Click Continue to categories. The button stays disabled until there is at least one room.

📘 Note: The wizard cannot set a floor's level. Floors are numbered 0, 1, 2… in the order you add them, so a basement added here gets a positive level. To give it a negative level afterwards, open Building → Floors, edit the floor and change its Floor Number (see “Building Structure & Categories”).

Manual branch — Categories

"Decide how the app groups devices." Categories become the tiles on the app home screen and the filters in every room; a device belongs to one category and one room.

The wizard seeds seven defaults: Lighting, Shutters, Heating, Sockets, Scenes, Energy, Security.

• Click a name to rename it.
• Remove a category the project doesn't need.
• Add a category of your own (name + icon), e.g. "Home cinema".

Then click Review everything to go to the final step (see “Final step — Review & apply” below).

📘 Note: The manual route creates no devices. You add them per room from the Devices page after setup (see “The Devices Workspace”).

ETS branch — Import selection

(This screen replaces this article when you chose "Import an ETS project".)

"Choose what to import."

1. Drop the .knxproj file (ETS 5 or ETS 6 project export) on the area Drop the .knxproj file here, or click that area to choose the file. There is no separate browse button.
2. If the project is password-protected in ETS, enter the Project password and click Unlock and read. The password is used to read the file and is never stored.
3. The wizard reads the project and offers three tickable parts, each with real counts from your file:
   • Building structure — the floors and rooms the ETS project describes ("3 floors · 14 rooms").
   • Group addresses — the full address table, so the bus monitor and the address picker know every address by name; typed and untyped counts are shown.
   • Devices from ETS functions — each ETS function becomes one device, already bound to its group addresses.
4. Untick what you do not want, then click Continue to categories. Keep Building structure ticked: without it there are no rooms to file devices under, and nothing is created from the project.

The ETS route then shows the Categories screen with the categories the project produced — one per kind of device it describes. Rename them, change icons, or add one the project doesn't cover, as on the manual route's Categories screen. A category that devices still use cannot be deleted until those devices are moved to another category on the review screen. Click Review rooms and devices to go on to the review (see “ETS branch — Review import” below).

ETS branch — Review import

"Check what we found." This is the correction pass over everything the import will create, organized as a tree of floors, rooms and devices. Before applying you can:

• Rename rooms and devices that still read like ETS labels — the original ETS name stays visible ("was … in ETS"), with a Revert action.
• Change a device's widget type where the import guessed wrong — the bound addresses limit which types fit.
• Move devices to another room or category, or Exclude ones the app should not show.
• Confirm inferred datapoint types — addresses without a DPT in ETS get an inferred one marked for confirmation.
• Work the "No room found" bucket: real devices whose room could not be worked out. Move each to a room; anything left is created without one.

📘 Note: If the project declares no ETS functions, the wizard works devices out from the actuator channels instead and flags every one guessed — check rooms, names and types before continuing.

Filters ("Needs attention", "Renamed"), search, and a "Next room with an issue" shortcut help you sweep large projects quickly. You can apply with issues remaining and fix them later in Devices. When you are done, click Review everything.

Final step — Review & apply

"Project Review" summarizes everything in six cards — setup mode & project, location & time, KNX bus, services, building, devices & addresses — each with an Edit link that jumps back to its step.

Blocking problems are listed above the cards (for example "No coordinates — the apply will stop on the settings stage", "No rooms — the app will open empty"). Fix them, or confirm they are intentional.

What apply does, in order:

1. Write the server settings — location, timezone, bus interface and the services you enabled.
2. Create the structure — floors, rooms, categories, and (on the ETS route) devices and group addresses.
3. Restart the KNX bridge — one reconnect; the bus itself is untouched.

Click Apply and finish. A live progress panel follows the stages and shows the elapsed time. When it reads Setup complete, the wizard closes and the System page opens.

📘 Note: If you switched a service of the Services section on or off (see “Step 4 — Services” above), the dialog Reboot to finish setup appears instead: these services only start or stop when the server reboots, which takes about two minutes. Click Reboot now, or click Later and reboot from the System page when it suits you.

If something goes wrong: the run stops on the failing stage and tells you. What earlier stages wrote stays in place; Retry runs all stages again, so check the building on the System page first if the failure came late. If the server restarted mid-apply, the wizard says the job was lost — check the result on the System page and re-run the wizard if the structure is missing.