Welcome!

# Recommended Additional Setup Steps

The following is not directly related to the openHAB installation but rather recommended on a openHAB system.
The need for these and the exact implementation on a specific system might differ from user to user.

Privileges for Common Peripherals

An openHAB setup will often rely on hardware like a modem, transceiver or adapter to interface with home automation hardware.
Examples are a Z-Wave, Enocean or RXFcom USB Stick or a Raspberry Pi add-on board connected to the serial port on its GPIOs.
In order to allow openHAB to communicate with additional peripherals, it has to be added to corresponding Linux groups.
The following example shows how to add Linux user to the often needed groups and .
Additional groups may be needed, depending on your hardware and software setup.

If you are looking to enable sound privileges for openHAB, it will also be necessary to add openHAB to the «audio» group.

Additionally it’s needed to allow the java environment to access the serial port of the connected peripheral.
Therefore the following setting has to be added/adapted on your system in file :

The shown device handlers are just the most common examples.
Please contact the community forum for more detailed information regarding individual hardware.

Java Network Permissions

The Java Virtual Machine hosting openHAB is restricted in it’s permissions to interact on network level for security reasons.
Some openHAB add-ons, like the Network or AmazonDash bindings, need elevated permissions to work.
If needed, grand these permissions by executing the following command:

Network Sharing

openHAB depends on configuration files and folders with custom content (details in Configuration articles).
Because your openHAB installation most probably is stored on a remote device, being able to easily access and modify these files from your local PC or Mac is important.
Therefore setting up a Samba network share is highly recommended.

The software does also depend on a mounted share to access the openHAB configuration files.

We will now guide you through the Samba network shares setup process.
Start by installing Samba.
Afterwards open it’s configuration file in your favorite editor:

Change the workgroup name if needed, otherwise uncomment and enable WINS support:

Next, add the desired share configurations to the end of the file:

• Package repository based installation:

• Manual installation:

Save and close the samba configuration file.

The shares are configured to be not open for guests nor to the public.
Let’s activate the «openhab» user as a samba user and set his password (e.g. «habopen»):

Be aware, that creating and later using a specific user will ensure, that are honored.
Make sure, the «openhab» user has ownership and/or write access to the openHAB configuration files.
This can be accomplished by executing:

Finally check the configuration file for correctness and restart Samba to load the new settings:

Mounting Locally

After setting up and restarting Samba, check your connection to the shared folder and create a permanent mount.
Check the network devices manager of your local operating system to find and access your openHAB host and share.
These might however not be auto-discovered.
You can also manually connect:

• On Mac OS X: Open Finder → Go → Connect to Server:
• On Windows: Open Windows Explorer → Address bar: → Right click a share and assign a drive letter

If everything went well, you are set and ready to start configuring your openHAB system.

Version: 2.2

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub

# Features

The following features are provided by the openHABian image out of the box:

• Hassle-free setup without a display or keyboard, connected via Ethernet or
• the latest stable version of openHAB 2
• Zulu Embedded OpenJDK Java 8, 11 or AdoptOpenJDK
• including updater functionality
• openHAB Log Viewer (based on frontail)
• Samba file sharing with
• Useful Linux packages pre-installed, including
• Login information screen, powered by FireMotD
• Customized Bash shell experience
• Customized vim settings, including openHAB syntax highlighting
• Customized nano settings, including openHAB syntax highlighting
• Raspberry Pi specific: Extend to the whole SD card, 16MB GPU memory split

Additionally the openHABian Configuration Tool is included and provides the following optional settings and components:

• Switch over to the latest Milestone or Snapshot release of openHAB 2
• Install and Setup a with password authentication and/or HTTPS access (incl. Let’s Encrypt certificate) for self-controlled remote access
• Set up a WiFi connection
• Bind the openHAB remote console to all interfaces
• Setup for your system
• Easily install and preconfigure of your choice
• … and many more
• Raspberry Pi specific:
  • Prepare the serial port for the use with extension boards like Razberry, SCC, Enocean Pi, …
  • Move the system partition to an external USB stick or drive

# Managing the Inbox, Things, and Channels

Managing the Inbox using PaperUI

In PaperUI, review the Items in the Inbox and accept those that should be included in your configuration.
You can press the eye icon to hide the Thing from the list if you never plan on including it, such as a dead zwave node.
Once approved browsing to the Configuration -> Things menus and selecting the Thing from the list one can get the list of Channel IDs for that Thing.

Managing the Inbox Using the Karaf Console

In the Karaf console you can see everything in the Inbox with the command:

Note

The screenshot above shows Ignored Inbox Items.
New Items will not show «IGNORED».

To accept a Thing from the Inbox run:

Once approved one can get the list of Channel IDs with the command:

You can narrow down the list using grep:

To ignore a Thing in the Inbox use the command:

Linking Channels to Items

There is more than one way to link Channels to Items using PaperUI, Karaf console, and through the text configuration files.
Only the text configuration files are covered here as they are closer to the openHAB 1.x way of doing things and will cause the least amount of work to migrate.

Open your .items files where you commented out the Items that used the old version of the binding.
Replace the old binding’s configuration with the Channel ID that Item represents.
For example:

becomes

Congratulations, you are now using the 2.x version of the binding.
Assuming the behaviors of the binding are the same, there should be no required changes to your Rules, Sitemaps, or Persitence.
Test your Items each step of the way to verify they are working.

Manually Creating Things

Not all 2.0 bindings support automatic discovery of Things or by their very nature require manual creation of Things.
As with linking Channels to Items, there is more than one way to do this including through PaperUI, Habmin, the REST API, or through text files.
This tutorial will only cover creating Things in text files as that will be closer to the openHAB 1.x way of doing things.

All definitions of new Things are written to .things files in the folder.
The syntax for a Thing definition varies from binding to binding.
See the binding’s readme for the specific format and parameters required.
Also see the binding’s readme for the list of channels the Thing supports.
As discussed above, the Channel ID will be the .

Version: latest

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub

# Necessary Changes

Items

• Jquery tutorial

  You must now manually install any Transformation engine your Items may use.

• The SCALE transformation has evolved.

  • Old syntax that was has to be changed to .
  • Note that you now have the ability to exclude bounds from the ranges (e.g. ) and also define open ranges.

Sitemap

• Change the default icons to png for ClassicUI and BasicUI if migrating custom icons.
  This can be done in PaperUI under Configuration -> Service -> BasicUI and ClassicUI.
  Set the «Default Icon Format» to «Bitmap».

• Not all of the default icons that came with openHAB 1.x are available in the default set for openHAB 2.
  If you are missing an icon in your sitemap that could be the cause.
  The full list of openHAB 2 icons is here.

• Dynamic icons must have a default.
  For example, if one has a bunch of Wunderground icons (e.g. wunderground-chanceflurries.png) there must be a icon as well.

• The URLs to the openHAB frontends have changed:

  • An overview of all installed UIs, including the administration UIs:
  • The direct link to your Sitemap on BasicUI .
  • The direct link to your Sitemap on ClassicUI .
  • These and all further UIs can be accessed through the overview page.

• The default sitemap is configured through a parameter for BasicUI and ClassicUI instead of naming the sitemap .

• Static webview files are now located in instead of

• The name of the sitemap (i.e. the word right after at the top of the file) must match the file name.
  For example the file named should start with .

• Charts no longer display a legend by default.
  If this parameter is not set, the legend is hidden if there is only one chart series.
  Add ‘legend=true’ to restore the chart’s legend.

Rules

Test your rules using commands in Karaf console.
Use smarthome:send to send a command, smarthome:update to update an Item’s state, and smarthome:status to get an Item’s state.
Use smarthome —help for more details.
These can be used to simulate events that can trigger a rule, even in an installation without «active» devices.

Potential pitfalls in rules code:

• All references to org.openhab.* in imports and class references should be removed. All of these classes are automatically included and have moved.
• import org.joda.time.* statements should also be removed, they are also included by default.
• To test for Items with an Undefined state replace with .
  Case matters.
  is only valid when testing an Item’s state to see if it is undefined.
  is used pretty much everywhere else to mean «no value» and usually indicates no result or an error.
• The state type can no longer be constructed using a object, and there is no longer a method.
  Use the following alternatives:

Continue watching the logs as you move files over.
There will likely be a number of errors.
Take note of them with plans to return and correct them if they persist.

# Full Example

Explanation:

• The Sitemap «demo» with the shown title «My home automation» is defined.

• One first Frame with a date stamp is shown.

• Another Frame with a visual label «Demo» is presented, containing:

  • A Switch for the Item «Lights»

  • A Text element showing a temperature in a given format

  • A Group element. Upon clicking the element, a new view containing all «Heating» Items will be shown.

  • Another Text element showing a «Multimedia» summary, e.g. «Currently playing».
    The element is additionally the host for a nested block.
    By clicking in the element, a new view with two elements is presented:

    • A Selection presenting four options in a modal dialog prompt
    • A Slider to set the volume (e.g. 0-100%)

# Concepts

Elements:
Sitemaps are composed by arranging various user interface elements.
A set of different element types supports a user-friendly and clear presentation.
The example above contains , and elements among others.
Elements present information, allow interaction and are highly configurable based on the system state.
One line of Sitemap element definition produces one corresponding UI element.
As shown in the example, each element generates a descriptive text next to an icon on the left side and a status and/or interaction elements on the right.

Parameters:
A certain set of parameters can be configured to customize the presentation of an element.
In the shown example , and are parameters.
Almost all parameters are optional, some are however needed to result in a meaningful user interface.
To avoid very long or unstructured lines of element definition, parameters can be broken down to multiple code lines.

Blocks:
By encapsulating elements with curly brackets, multiple elements can be nested inside or behind others.
The element type is often used in combination with element blocks.
Frames are used to visually distinguish multiple elements of the same topic on one interface page.
When using code blocks behind other element types such as or , these UI elements will, in addition to their normal function, be links to a new view, presenting the nested elements.
In the above example, multiple Frames are defined and some elements are not visible on the main view but are accessible behind their parent element.
These are indicated by the «>» control icon on the right of an element.

Dependencies:
A typical sitemap contains dozens of individual elements.
A system state and possible interactions are however often closely dependent.
openHAB supports these dependencies by providing parameters for dynamic behavior.
Be sure to check out the chapter.

For the technically interested: The Sitemap definition language is an
Xtext Domain Specific Language and the sitemap file model can be found here.

Special Element ‘sitemap’

The element is mandatory in a Sitemap definition.
This element shall be the first line in the sitemap file, and the following code block comprises the entire Sitemap definition.

• shall always be equal to the Sitemaps file name, e.g. the in a sitemap file named must be «demo»
• is free text and will be shown as the title of the main screen.

(Note that the element is written with a lower case «s».)

# Preparation

Now is the time to consider and plan for your newly installed openHAB.
Some questions to ask and answer include:

• Are you happy with your current deployment and maintenance of the deployment?
• Do you have or need to change your backup and configuration management practices?
• Have you wanted to migrate to a container (e.g. Docker or a virtual machine)?
• Do you want to start over fresh on a brand new OS install?

Your answers to these and other similar questions will help guide you to prepare your installation before you start the migration.
For example, if you want to start using git to back up and configuration manage your openHAB configurations, or if you are considering moving to Docker or a VM or starting over fresh (e.g. openHABian), now is a good time to start the process.

The following procedure primarily focuses on an in-place migration.
If you are migrating to a fresh install, container, or another VM some of the following steps can be skipped.
Those steps are identified.

One major consideration is that at the time of this writing openHAB 2 does not implement authentication and authorization (i.e. no username and password).
If you are relying upon port forwarding to access your openHAB server remotely instead of via a VPN, SSH tunneling, or my.openhab, we highly recommend setting up a reverse proxy.

# Backups

The first step is to backup everything that you have modified in the existing openHAB 1.x installation.
If you installed using apt-get these files may include:

• — configuration files
• — openhab user’s home directory, zwave and embedded persistence database files
• — custom icons, custom webviews (e.g. Weather Binding)
• — custom command line arguments to the Java Virtual Machine, changes to the default ports, etc.
• — an alternative place to change default ports

If you are on an operating system that does not support apt-get or performed a manual installation for some other reason simply backup the whole directory.

# Encrypted Communication

Webserver Ports

openHAB has a built-in webserver, which listens on port 8080 for HTTP and 8443 for HTTPS requests.
In general, it is advised to use HTTPS communication over HTTP.

The default ports 8080 and 8443 can be changed by setting the environment variables resp. .
In an apt installation, you would best do this in the file .

SSL Certificates

On the very first start, openHAB generates a personal (self-signed, 256-bit ECC) SSL certificate and stores it in the Jetty keystore (in ).
This process makes sure that every installation has an individual certificate, so that nobody else can falsely mimic your server.
Note that on slow hardware, this certificate generation can take up to several minutes, so be patient on a first start — it is all for your own security.

# Setup variants

Before you can start, two decisions have to be made:

1. openHAB 2 is available as a platform independent archive file or through a package repository:

   • Manual setup: Download and extract a platform independent zip archive: macOS, Windows,
   • Package setup: Install through a package repository, including automatic updates.
     This option is only available for Debian or Ubuntu derivatives and the recommended choice:

2. Stable release or cutting edge:

   • Stable: Use the latest official release (hosted on Bintray).
   • Snapshot: Benefit from the latest changes in the daily created snapshot (hosted on openhab.org).

# Features

The following features are provided by the openHABian images out of the box:

• Hassle-free setup without a display or keyboard, connected via
• openHAB 2 in the latest stable version
• Zulu Embedded OpenJDK Java 8 (newest revision)
• including updater functionality
• openHAB Log Viewer (based on frontail)
• Samba file sharing with
• Useful Linux packages pre-installed, including
• Login information screen, powered by FireMotD
• Customized Bash shell experience
• Customized vim settings, including openHAB syntax highlighting
• Customized nano settings, including openHAB syntax highlighting
• Version control for by the help of etckeeper (git)
• Raspberry Pi specific: Extend to the whole SD card, 16MB GPU memory split

Additionally the openHABian Configuration Tool is included and provides the following optional settings and components:

• Switch over to the latest openHAB 2
• Install and Setup a with password authentication and/or HTTPS access (incl. Let’s Encrypt certificate) for self-controlled remote access
• Set up a Wi-Fi connection
• Bind the openHAB remote console to all interfaces
• Easily install and preconfigure of your choice
• … and many more
• Raspberry Pi specific:
  • Prepare the serial port for the use with extension boards like Razberry, SCC, Enocean Pi, …
  • Move the system partition to an external USB stick or drive
• Pine A64 specific:
  • Longsleep’s platform scripts
  • Assign

# Using the Console

After successful connection and authentication, the console will appear:

The command is listing all available commands or describes a specific subsystem/command:

The console also supports auto-completion during input.
Auto-completion proposes possible commands based on the current input and is triggered by a <TAB> press on your keyboard.
So for example entering «bund» and pressing the <TAB> key will first extend to the only viable candidate «bundle», a subsequent <TAB> press will result in:

Another useful feature is the combination of the (pipe) and functionality, which can be used to filter output:

The session is ended by using the logout command:

Learn about all available commands by using the initially introduced command.

# Dynamic Sitemaps

All Sitemap elements can be configured to be hidden, color highlighted or to have a , depending on certain Item states.
A few practical use cases are:

• Show a battery warning if the voltage level of a device is below 30%
• Hide further control elements for the TV if it is turned off
• Highlight a value with a warning color if it is outside accepted limits
• Present a special icon, depending on the state of an item (a )

Visibility

The parameter is used to dynamically show or hide an Item.
If the parameter is not provided, the default is to display the Item.

Visibility syntax:

Valid comparison operators are:

• equal to , unequal to
• less than or equal to , greater than or equal to
• less than , greater than

Expressions are evaluated from left to right.
The Item will be visible if any one of the comparisons is evaluated as , otherwise it will be hidden.

Examples:

In the third example above, a control for a lawn sprinkler will be visible if it is Morning, OR if it is Afternoon, OR if the temperature is above 19 °C.
Combining multiple conditions, for example Morning AND above 19 °C is not supported.
To control visibility based upon combining multiple Items, or on more complex conditions, consider defining and using an additional intermediate Item that is set by a Rule.
Rules have a rich set of features that can support more involved scenarios.

Label and Value Colors

Colors can be used to emphasize an items label or its value based on conditions.
Colors may be assigned to either the label or the value associated with an Item.

Label and Value Color Syntax:

Note that and are both optional.
If is not provided, the Item name will default to the current Item.
If an operator is not specified, the operator will default to .

The comparison operators for and are the same as for the visibility parameter.

Examples:

The following three lines are equivalent.

The line below illustrates the importance of operator order:

Note that expressions are evaluated from left to right; the first matching expression determines the color.
If the order of the expressions was reversed, the color assignment would not work properly.
Note also, the effect of omitting and the comparison operator in the expression (as compared to ).

Below is a list of standard colors and their respective RGB color codes.

Color Name	Preview	RGB Color Code
maroon	⬤
red	⬤
orange	⬤
olive	⬤
yellow	⬤
purple	⬤
fuchsia	⬤
pink	⬤
white	⬤
lime	⬤
green	⬤
navy	⬤
blue	⬤
teal	⬤
aqua	⬤
black	⬤
silver	⬤
gray	⬤
gold	⬤

Please take note that colors other than those listed in the list above may be used.
Generally, you can expected that valid HTML colors will be accepted (e.g. , , ), but note that a UI may only accept internally defined colors, or work with a special theme.
The color names above are agreed on between all openHAB UIs and are therefore your safest choice.
Colors defined by a human-readable name may be adjusted for higher contrast, e.g. on a dark theme may be displayed as white, because white has a higher contrast to the dark background compared to black.

Icons

openHAB allows a set of icons to be assigned to the different states of an Item and therefore to be presented in a Sitemap.
Please refer to the documentation on Item configuration for details.

# Optional Components

openHABian comes with a number of additional routines to quickly install and set up home automation related software.
You’ll find all of these in the

• Frontail — openHAB Log Viewer accessible from http://openhab:9001
• Mi Flora MQTT demon
• InfluxDB and Grafana — persistence and graphing available from http://openhab:3000
• Eclipse Mosquitto — Open Source MQTT v3.1/v3.1.1 Broker
• Node-RED — «Flow-based programming for the Internet of Things», with preinstalled openHAB2 and BigTimer add-ons. Accessible from http://openhab:1880
• Homegear — Homematic control unit emulation
• KNXd — KNX daemon running at
• OWServer — 1wire control system
• FIND — the Framework for Internal Navigation and Discovery
• Tellstick core

# openHABian Configuration Tool

The following instructions are oriented at the Raspberry Pi openHABian setup but are transferable to all openHABian environments.

Once connected to the command line console of your system, please execute the openHABian configuration tool by typing the following command.
(Hint: sudo executes a command with elevated rights and will hence ask for your password: ).

The configuration tool is the heart of openHABian.
It is not only a menu with a set of options, it’s also used in a special unattended mode inside the ready to use images.

— A quick note on menu navigation.
Use the cursor keys to navigate, <Enter> to execute, <Space> to select and <Tab> to jump to the actions on the bottom of the screen. Press <Esc> twice to exit the configuration tool.

Linux Hints

If you are unfamiliar with Linux, SSH and the Linux console or if you want to improve your skills, read up on these important topics.
A lot of helpful articles can be found on the internet, for example:

• «Learn the ways of Linux-fu, for free» interactively with exercises at linuxjourney.com.
• The official Raspberry Pi help articles over at raspberrypi.org
• «Now what?», Tutorial on the Command line console at LinuxCommand.org

The good news: openHABian helps you to stay away from Linux — The bad news: Not for long…

Regardless of if you want to copy some files or are on the search for a solution to a problem, sooner or later you’ll have to know some Linux.
Take a few minutes to study the above Tutorials and get to know the most basic commands and tools to be able to navigate on your Linux system, edit configurations, check the system state or look at log files.
It’s not complicated and something that doesn’t hurt on ones résumé.

Further Configuration Steps

openHABian is supposed to provide a ready-to-use openHAB base system. There are however a few things we can not decide for you.

• Time Zone: The time zone of your openHABian system will be determined based on your internet connection. In some cases you might have to adjust that setting.
• Language: The setting of the openHABian base system is set to «en_US.UTF-8». While this setting will not do any harm, you might prefer e.g. console errors in German or Spanish. Change the locale settings accordingly. Be aware, that error solving might be easier when using the English error messages as search phrases.
• Passwords: Relying on default passwords is a security concern you should care about! The openHABian system is preconfigured with a few passwords you should change to ensure the security of your system. This is especially important of your system is accessible from outside your private subnet.

All of these settings can easily be changed via the openHABian Configuration Tool.

Here are the passwords in question, their default «username:password» value and the way to change them:

• User password needed for SSH or sudo (e.g. «openhabian:openhabian») :
• Samba share password (e.g. «openhabian:openhabian»):
• openHAB remote console (e.g. «openhab:habopen»): Change via the openHABian menu
• Nginx reverse proxy login (no default): Change via the openHABian menu, please see for more

# Installation

The openHAB runtime is distributed using a platform-independent zip file.
To install it, follow these simple steps:

1. Download the latest Windows Stable or Snapshot ZIP archive file for manual installation from the Download page.

2. Unzip the file in your chosen directory (e.g. )

3. Start the server: Launch the runtime by executing the script and wait a while for it to start and complete.

4. Point your browser to .
   You should be looking at the openHAB package selection page.
   When you’ve selected an appropriate package, this page will contain the UI selection screen, see here for example.

File Locations

Assuming a successful install, you will now have various folders inside :

	Windows Installation
openHAB application
Additional add-on files
Site configuration
Log files
Userdata like rrd4j databases
Service configuration

# Creating a Skeleton

For the openHAB namespace: Choose the option «openHAB 2 Add-ons» in your IDE setup, and create a skeleton for your binding.
To do this, go into your Git repository under and call the script with two arguments.
It is important that your binding name is in camel case (e.g. ‘ACMEProduct’ or ‘SomeSystem’).
After the binding name, provide your name as the author (surrounded by quotes if you want to use whitespaces to separate your fist and last name).

For the Eclipse SmartHome namespace: Choose the option «Eclipse SmartHome Extensions» in your IDE setup, and create a skeleton for your binding.
To do this, go to and run in order to install the archetype definition in your local Maven repo.
Now go to and call the script with two parameters.
The first one is your binding name in camel case (e.g. ‘ACMEProduct’ or ‘SomeSystem’).
The second one is your name as author (surrounded by quotes if you want to use whitespaces to separate your fist and last name).

Now switch back to Eclipse and choose , enter the folder of the newly created skeleton as the root directory, and press «Finish».

Note: Here you can find a screencast of the binding skeleton creation.

# Migrating to openHAB 2 Bindings

Integrated Development Environment

As mentioned above, openHAB Designer is no longer recommended or supported. There is a new Integrated Development Environment (IDE) for openHAB 2 configurations, /docs/configuration/editors.html#openhab-vs-code-extension).

myopenHAB.org

There is no 1.x My.openHAB binding that is compatible with openHAB 2, only a native 2.0 openHAB Cloud Connector binding.
Furthermore, one can have only one openHAB instance linked to a http://myopenhab.org account at a time.
This is why we have saved migrating this binding until now.

Each openHAB instance generates its own unique UUID and Secret so one cannot simply copy these files from your old openHAB 1.x installation.

Using your preferred method for add-on installation (see above) install the openHAB Cloud Connector binding (Misc tab in PaperUI).
Once installed a new and file will be created.
These two files are located in a different place in openHAB 2: and .

Copy the contents of the file into the openHAB UUID field.
Copy the contents of the file into the openHAB Secret field.

You may need to restart openHAB at this point to get the binding to reconnect.
It should now show your system as being online and running openHAB 2.

Other Bindings

One is not required to use 2.x version addi-ons with openHAB 2.
It is highly recommended to do so as most cases where there is a 1.x and a 2.x add-on, only the 2.x binding is undergoing continued development.
On-the-other-hand, some of the 2.x bindings work significantly differently from their 1.x versions. See the add-on’s 1.x and to compare and contrast the two versions.

Identify an add-on where there is a 2.x version that you want to migrate to.
Begin by identifying those Items that use this binding.
On Linux/OSX this can easily be done with the following command

where is the string used in the binding config on the Item.
For example:

Now comment out those Items to ensure there are no unexpected interactions between the old configurations and the new ones.

Next uninstall the 1.x binding.
In the Karaf console use the command .
If you used addons.cfg to install the addons you must uninstall it using the Karaf console.
In PaperUI, browse to the add-on and choose uninstall.

Move the add-on’s .cfg file to a backup location.
Some bindings have significantly changed their configurations but much of the old information will still be relevant.

Install the 2.0 version of the add-on using your preferred method as described above.
If this is the zwave binding, install the Habmin UI at this time as well if you have not done so already.

Configure the add-on as described in the add-on’s readme file.
Once it is properly configured and if the binding supports automatic Thing discovery, new Things will start to slowly appear in the Inbox.
If left on its own this process can take five minutes to an hour.
However, one can press the scan button in PaperUI -> Inbox to speed this up.
Or from the Karaf console one can run:

# Include the Binding in the Build and the Distro

Once you are happy with your implementation, you need to integrate it in the Maven build and add it to the official distro.
For the Maven build, please add a new line in the binding pom.xml at the alphabetically correct position.
In order to have the binding being included by the distro, you furthermore need to add it to the feature.xml, again at the alphabetically correct position.
If you have a dependency on a transport bundle (e.g. upnp, mdns or serial), make sure to add a line for this dependency as well (see the other bindings as an example).

Before you create a pull request on GitHub, you should now run

from the repository root to ensure that the build works smoothly.
If it does, it is time to contribute your work!

Static code analysis

The Build includes Tooling for static code analysis that will validate your code against the openHAB Coding Guidelines and some additional best practices.
Information about the checks can be found .

The tool will generate an individual report for each binding, which you can find in file and a report for the whole build that contains links to the individual reports in the .
The tool categorizes the found issues by priority: 1(error), 2(warning) or 3(info).
If any error is found within your code the Maven build will end with failure.
You will receive detailed information (path to the file, line and message) listing all problems with priority 1 on the console:

Please fix all the priority 1 issues and all issues with priority 2 and 3 that are relevant (if you have any doubt don’t hesitate to ask).
Re-run the build to confirm that the checks are passing.

Version: 2.3

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub

# About data persistence

By default, when running HABPanel on a new browser or device, a tutorial will be displayed allowing the user to start from scratch, or switch to an previously defined panel configuration. Until a panel configuration is created (or chosen), HABPanel will run in «local storage» mode for this device: the settings will be retained in the browser’s local storage only and nothing will be persisted on the server. By contrast, when an active panel configuration is set, each change performed on the device will update the panel configuration on the server. This allows the sharing of panel configuration among devices, because other browsers and devices using this panel configuration will pick up the changes with a page refresh — this is useful for instance to design a panel comfortably on a computer, then use it on a tablet.

To switch from the local storage to a server-hosted panel configuration, go to the Settings page from the main menu or the side drawer (see below). A list of panel configurations will be presented in the Current storage configuration section; if only the «Local storage» option is available, click on the Save the current configuration to a new panel configuration link, give it a name to identify it (avoid spaces or special characters), and it should be added to the list. The radio button is also automatically checked, meaning it is now the active panel configuration.

Even when there is an active panel configuration, HABPanel uses the browser’s storage to sync a locally-managed copy. With the Edit the local panel configuration (experts only) link under the «Local storage» storage configuration option in the settings screen, the raw structure of the panel configuration can be inspected, modified, and exported or imported from/to a .json file. It is also an alternative way to backup, restore and share the configuration.

HABPanel uses service configuration variables to store its data on the openHAB server. They can be accessed using Paper UI (Configuration > Services > UI > HABPanel > Configure) or in the openHAB Karaf console:

The following properties are defined:

• : contains the entire registry serialized in JSON, it is maintained by the application and shouldn’t be modified directly (editing it by hand, while possible, is strongly discouraged);
• : when enabled, all HABPanel instances will hide their editing features (a page refresh is necessary). When panels are complete and stable, it is advisable to turn on this setting so they cannot be easily modified by end users;
• : if this option is unset and no prior local configuration is detected, the tutorial will be displayed until some dashboards are added or a panel configuration is selected. This setting allows to bypass the tutorial and switch directly to the existing panel configuration with the given name.