quick_guide.md

layout	title
documentation	Quick Guide for new users

Quick Guide

This Quick Guide is aimed at new users who simply want to install openHAB on their PC to see how it works. It will give you step-by-step instructions for the whole process from downloading openHAB until switching on/off a smart device by your mobile phone and automatically at the time you go to bed.

You will see how easy it is and you do not have to be a home automation or IT expert.

Note

Minimum skill level required for this Quick Guide:

We recommend that you have knowledge how to unzip files and what IP addresses are.

[[toc]]

Step 1: Install and Start openHAB

Estimated time: 3 minutes

We are going to intall openHAB on a Windows PC. Almost any Windows PC will do, as openHAB requires very little resources. If you want to install openHAB on a different platform, please refer for Step 1 of this Quick Guide to our Installation Documentation.

Steps	Notes
Download openHAB Go to openHAB Download Website Click Windows ➡️ Stable ➡️ Download openHAB Stable Runtime.
Installation As there is no installation program, simply unzip the downloaded .zip file to your preferred folder like C:\Program Files\openHAB (requires admin rights) or C:\openHAB.
Download & Install OpenJDK Download OpenJDK from OpenJDK Download Website Double click the .msi file to start installation	openHAB requires Java runtime (JRE) version 17 Installation of OpenJDP requires admin rights
Before installation starts, change "Set JAVA_HOME variable" to "Will be installed on local drive."
Start openHAB Double click ..\openHAB\start.bat and minimize the window when you see the following screen. (In case Windows Defender pops up, click Allow Access.)	If you want to run openHAB as a service, see here.
Open openHAB GUI Open http://localhost:8080/ in your browser (or <IP-address>:8080/ if you connect from another device (such as your mobile phone). On the very first start you are asked to create an admin user.

Congratulations, you have successfully installed openHAB!

Step 2: Setup Wizard

Estimated time: 1 minute

On the first run and after you have created an admin user, a Setup Wizard is started automatically in the GUI.

Steps	Notes
Basic Settings Set Language, Region, Time Zone Set Location of your home Click Configure in Settings Later to skip this step	openHAB does not collect any information from users, so your location will not be sent outside your network. You can cancel this wizard at any time and continue later by navigating to the following site: http://localhost:8080/setup-wizard/.
Add-ons Click Select Add-ons to Install ➡️ select the vendor of your smart device (e.g. Philips hue, Lutron, yeelight, LIFX, ...) or the protocol name supported by your smart device (e.g. KNX, ZigBee, Z-Wave, DALI, MQTT, ...) - we use"Shelly" in our example. Click Install 4 add-ons ➡️ Get Started. You will be redirected back to openHAB's GUI, called MainUI. Note: Add-ons which connect to your smart device (or services) are called Bindings in openHAB.	The setup wizard already added three pre-defined add-ons. During this Quick Guide they are not required but we recommend to install them for a later purpose.
Pin MainUI's side bar (optional)

Step 3: Adding a smart device to openHAB

Estimated time: 3 minutes

Smart lightbulbs, smart roller shutter, temperature sensors (and many other smart devices) are called Internet of Things devices (IoT). In openHAB we call those IoT devices also a "Thing". An openHAB Thing is the digital representative of your real world IoT device.

Before we continue with the next step, please follow our recommendation:

Important

Whenever you add a new binding to openHAB, please always read the documentation of the Add-on! It will save you a lot of time.

Steps	Notes
Configure Binding (optional) Check if there are any important settings available for your Binding first Click Settings ➡️ Show All (Add-on Settings) ➡️ <name of Binding>. (These settings depend on your specific Binding. In our case we provide credentials, because the smart controller is password protected) Note: In our case openHAB has already discovered many Things automatically.
Scan for new Things In case your binding did not discovered your Things yet, we can scan for new Things. Click Settings ➡️ Things ➡️ press the + button ➡️ <name of binding> ➡️ Scan.
Add a new Thing After discovery, click <Thing name> ➡️ Add as Thing ➡️ enter a meaningful name of your Thing. (You could also select Add All at the bottom of the list and can enter a meaningful name after the Things are created from the Thing’s page).	We recommend to define a syntax for your Thing names, such as: BindingName-RoomName-PlaceOrPurpose-ThingType and apply them consistently across all your Things.

Congratulations, you have added your first Thing to openHAB!

Important

For the next step we need to provide a little bit of background information first:

As you already know a Thing in openHAB is the digital representation of a smart device in our real world. A smart device (and its openHAB Thing) offers a lot of functionalities or capabilities. In case of a smart light bulb (or a smart device controlling a light bulb) these are: set brightness, detect physical button press, power consumption, trigger alarms (e.g. overheating), signal strength, and many more.

A Thing in openHAB provides these different information, status, events, etc. seperately in different Communication-Channels. A Thing Channel is similiar to a physical postbox, where information is provided so that a postman can pick them up and transport it to the receiver (such as our MainUI GUI).

In our example the postman is called Item. The nice thing about our postman (i.e. Item) is, he also works for us and can transport commands (like "switch on light") back to the Thing Channel. To be more precise with the terms we use, an Item has a state (like on/off, closed/open, 34 °C, 50%, 2 kWh), can receive commands, can trigger a rule, can be persisted and interact with the GUI we are creating in one of the next steps.

Let's continue with adding an Item (postman) to a Thing Channel (mailbox):

Steps	Notes
Add Item to a Thing Click Things ➡️ select the Thing we just created ➡️ switch to the tab Channels. (As you can see there are quite a few channels available but for now we just need the channel for changing the brightness of our smart dimmer.) Click Brightness ➡️ Add Link to Item... ➡️ Create a new Item ➡️ Link (During this Quick Guide it is not required to change Item attributes and profiles as you may have noticed in this step. You'll find more information for later on here (Items) and here (Model).)
Overview of all Items in openHAB.

Congratulations, you have added your first Item to an openHAB Thing!

Step 4: Configure GUI / create automation

Estimated time: x minutes

In our last step we will be adding a slider button for our dimmable smart device to the GUI. The button switches the light off and restores the dimmed value when switching on. If you click the menu icon of the button ⋮, a popup appears where you comfortably can set the new value.

todo: add gif here of slider widget, to see what we are going to do in this step.

Steps	Notes
Add slider button to GUI Click Pages ➡️ Add Block ➡️ Add Cells ➡️ + ➡️ Slider Cell (for roller shutters use Rollershutter Cell) (for color lamps use Colorpicker Cell) (for switches use Label Cell)
Configure slider button Explanation of the configuration parameters: Header, Title, Subtitle, Footer: these are labels Slider Item: item which we send a command to when using a slider Action: Action to perform when the button is pressed (here: Toggle Item) Action Item: item which we send a command to when pressing the button
WIP below here Test slider button Click Run Now, toggle on off, open popup
no button color change to see if Light is on or off, advanced settings =(@'ShellyLivingRoomFloorLampDimmer_Brightness' == "0")?true:false, hit save button
View the whole page Open http://localhost:8080/page/overview in a new tab of your browser (or <IP-address>:8080/page/overview on other devices such as your mobile phone)
done. these are the fundamentals. now home automation begins: create rule and schedule

todo add a result/gif in the beginning what the reader will have learnt by the end of each step

What next?

Widgets Marketplace widgets and rules Examples of pages