# openHABian - Hassle-free openHAB Setup
You just discovered openHAB and now you are eager to start but you're afraid of setting up a standalone system for it?
openHABian is here to help.
# Features
openHABian is a self-configuring Linux system setup to reliably operate your openHAB instance 24 hours a day. It provides:
- Complete SD-card images pre-configured with openHAB for the Raspberry Pi line of small single-board computers
- The openHABian configuration tool to set up and configure openHAB and many related things on any Debian based system
- Fully automated hassle-free setup without a need for a display or keyboard, connected via Ethernet or Wi-Fi
- Comprehensive capabilities to ensure your system will keep working reliably 24/7 including:
- Web based openHAB Log Viewer (based on frontail (opens new window))
- Tailscale (opens new window) VPN and WireGuard (opens new window) for remote VPN access
- Samba file sharing pre-configured ready to use shares (opens new window)
- Login information screen, powered by FireMotD (opens new window)
- The Mosquitto (opens new window) MQTT broker
- The InfluxDB (opens new window) database to store home automation data and Grafana (opens new window) to visualize it
- FIND, the Framework for Internal Navigation and Discovery (opens new window)
- Self-controlled remote access using a reverse proxy with a Let's Encrypt (opens new window) certificate
# openHABian basics
openHABian installs the latest major version of openHAB (currently 4.x) by default. Currently the default Java version that will be installed is Java 17.
# Who should use openHABian?
openHABian is for starters and expert users. We sometimes read about people deciding against use of openHABian because they want to install additional software and believe openHABian does not let them do this. This is not true, however, the best way to ensure a stable system is to avoid installing packages unrelated to openHAB as they may cause issues. Therefore our recommendation is and will always be to dedicate a single system to only your openHAB instance and avoid using it for other purposes. Saving another 100 bucks is not worth putting the reliable day-to-day operations of your home at risk.
With that being said, we can't and won't stop you from doing whatever you want, but don't say we didn't warn you.
# Unsupported usecases
We do have to make one thing clear, we cannot and will not provide support for changes made beyond the scope of the base system provided by openHABian.
This means any changes not made by openhabian-config
to your system will not be supported by the maintainers.
We as the openHABian maintainers are really committed to providing you with a fine user experience.
This takes enormous efforts in testing and is only possible with a fixed set of hardware and software parameters.
If you feel like something is missing and should be supported, feel free to ask if you could contribute support for it to the project.
# Hardware
# Hardware recommendation
Our current recommendation is to get a RPi model 4/5 with 2/4 GB of RAM, whatever you can get hold of for a good price. Older RPi models (or models with less RAM) can be sufficient to run a smallish openHAB setup. Be warned though, they will not be enough to run a full-blown system with many bindings and memory consuming openHABian features/components such as zram or InfluxDB.
We also recommend an "Endurance" SD card. Cards labelled "Endurance" can handle more write cycles and will typically last longer for openHAB's use conditions.
We also recommend that you get a 2nd SD card right away and prepare to make use of the SD mirroring feature. Typically this means getting an SD card of the same model or at least the size of your primary one, plus a USB card reader.
If you want to be on the safe side, order the official 3A power supply, otherwise any old mobile charger will usually do fine.
# Hardware support
All Raspberry Pi models are supported by openHABian.
Note
With the upcoming openHAB 5 release, we will drop support for anything older than an RPi 3 as openHAB 5 will require a 64 bit processor.
openHABian can run on x86 based systems but you will need to install the OS yourself.
Anything else ARM based such as ODroids, OrangePis and the like may or may not work. NAS servers such as QNAP and Synology boxes are not supported. We do not actively prohibit installation on any hardware, including unsupported systems, but we probably will not offer support for any issues you encounter.
We strongly suggest that you stay with a supported version. This will help you and those you will want to ask for help on the forum focus on a known set of issues and solutions.
For ARM hardware that we don't support, you can try any of the fake hardware parameters to 'simulate' RPi hardware and Raspberry Pi OS.
# Hardware modifications
Plugging in HATs like an UPS or USB sticks or even SSDs for storage is fine.
Though please note that we cannot support attaching any hardware that requires additional software or configuration changes.
Also remember that any future changes to openHABian (i.e. by the openhabian-config
tool) can interfere with any modifications of yours.
Beware that in the future changes you've made may break your box and openHAB experience at anytime.
# SSD
We don't recommend or support using an SSD as your boot device. If you know Linux well enough to manually apply all the required modifications, feel free to do so. Be warned that this is completely untested and unsupported. Please don't ask for help if you run into trouble.
Anybody afraid of SD card issues should use the SD mirroring feature to mitigate. This will provide you with a secondary, up to date SD card, available for swapping in at any time.
# OS support
Going beyond RPi images, because openHABian is really just a set of scripts, we support running openHABian on x86 hardware using generic Debian.
We provide code that is reported to run on Ubuntu but we do not support Ubuntu so please don't open issues for this (PRs adding support are welcome). Several optional components such as WireGuard or Homegear are known to expose problems on Ubuntu.
As of openHAB 4, buster
and older distros are no longer supported.
You must be on bookworm
or newer.
We do not recommend upgrading from an older distro without a fresh install.
Please save yourself the pain and re-install using the latest openHABian image and import your config manually instead.
# 32/64 Bit support
Any RPi 3 or newer supports 64 bit operation. Unless you really know what you are doing and have a compelling reason to do so, stick with the 64 bit image. If you do install a 32 bit image, please note that you will be unable to upgrade to openHAB 5 in the future.
# Networking
A working DHCP server is a mandatory prerequisite to openHABian's networking setup. We recommend you configure your DHCP server to always assign the same IP based based on your RPi's MAC address. That'll effectively get you a fixed local IP address.
Most DHCP servers are part of your router and have an option to allow for this type of mapping. For example in AVM Fritz!boxes (popular in Germany), it's a simple checkbox you can tick - note it only appears after the address was assigned to a client (your openHABian box) for the first time.
Please note that it is not supported to setup openHABian with a static IP address as described in the Raspberry Pi OS documentation.
When you boot a flashed image for the first time, openHABian will setup and use Ethernet if it is connected.
If not Ethernet is detected it'll also use the wifi_ssid
and wifi_password
parameters from /boot/openhabian.conf
to determine if/how to setup the Wi-Fi interface.
After these stages it checks for connectivity to the Internet and if that fails, it'll try to open a Wi-Fi hotspot that will let you manually connect your system Wi-Fi. Remember that once the hotspot is started, it'll hide once you have successfully used it to connect your Wi-Fi. If connection fails it'll return again.
# Raspberry Pi prepackaged SD card image
Flash, plug, wait, enjoy: The provided image is based on the Raspberry Pi OS Lite (opens new window) (previously called Raspbian) standard system. openHABian is designed as a headless system, you will not need a display or a keyboard. On first boot, the system will set up openHAB, its tools and settings. Packages will be downloaded in their newest version and configured. The whole process will take some minutes, then openHAB and all other tools required to get started will be ready to use without further configuration steps.
Installation:
- Make sure you meet the hardware prerequisites first
- Prepare your local router
- Write the image to your SD card using the official Raspberry Pi Imager (opens new window). openHABian can be selected via 'Other specific purpose OS / Home assistants and home automation'.
- Alternatively, you can download the card image file (opens new window) and use any flash tool such as Etcher (opens new window).
- Optionally, you can change a number of parameters now to affect the installation. See this section (https://www.openhab.org/docs/installation/openhabian.html#openhabian-conf (opens new window)). As a beginner or if in doubt what an option does, don't change anything.
- Insert the SD card into your Raspberry Pi. Connect your Ethernet. If you want to use Wi-Fi instead, configure Wi-Fi before booting or use the hotspot function later on. Do not attach a keyboard. Power on and wait approximately 10-30 minutes for openHABian to do its magic. The system will be accessible by its IP or via the local DNS name
openhabian
and you can watch the install progress in your browser at http://openhabian:81 (opens new window). If for whatever reason networking does not work, openHABian will launch a hotspot so if you see that, something's up with your networking. - Connect to the openHAB UI at http://openhabian:8080 (opens new window)
- Connect to the Samba network shares (opens new window)
- Connect to the openHAB Log Viewer (frontail): http://openhabian:9001 (opens new window)
- If you encounter any setup problem, please continue here
When openHABian has installed and configured your openHAB system, you can start to use it right away.
Connect to your Raspberry Pi SSH console (opens new window) using the username openhabian
and password openhabian
.
You should be seeing a welcome screen like the following:
➜ Continue at the "openHABian Configuration Tool" chapter below.
# Wi-Fi Hotspot
When your openHABian box does not get Internet connectivity through either Ethernet or Wi-Fi (if configured), openHABian will launch a hotspot.
Use your mobile phone to scan for Wi-Fi networks, you should be seeing a new network called openHABian-<n>
with <n>
being a digit.
Connecting will work without a password. Once connected, most smartphones will transfer you to a web page.
If this does not happen on your mobile device, open your browser on the mobile and point it at http://raspberrypi.local
or http://comitup-<n>
.
This may or may not work for your mobile browser as it requires Bonjour/ZeroConf abilities.
If you cannot connect to this address, go to http://10.41.0.1
.
On that page you can select the SSID of the network you want to connect your system to.
Provide the password and press the button.
Note that as soon as you do, the wlan0 IP address of your system changes so your mobile browser will not be able to provide you any feedback if that worked out.
Try to ping the new system's hostname (default is openhabian
) or check DHCP on your router if your openHABian system appeared there.
You can use sudo comitup-cli
inside openHABian to change networks and eventually remove network credentials.
Note the hotspot may not only become available during installation: it will remain on standby and will show up again every time your wlan0
interface is losing connectivity.
For more information on hotspot functions see comitup-cli (opens new window). Most behavior can be tweaked by setting parameters (such as a default password) in /etc/comitup.conf
.
The hotspot feature is known to work on RPi0W, RPi3 and newer but is known to often expose problems with Wi-Fi USB adapters.
# Other Linux Systems (add openHABian just like any other software)
Going beyond what the RPi image provides, you can also install openHABian on x86 hardware on top of any existing Debian installation. Please note that the unattended install is tailored to work for Raspberries. We cannot test HW/OS combos beyond RPis upfront so there is no promise for this work. Note that although the core parts of openHABian were reported to work on Ubuntu, it is not supported and untested. If you try and fail, please help and drop us a note on GitHub with debug log enabled, see DEBUG guide.
Start with a fresh installation of your operating system, login and run
# start shell as root user
sudo bash
then start installation
# install git - you can skip this if it's already installed
apt-get update
apt-get install git
# download, link and create config file
git clone -b openHAB https://github.com/openhab/openhabian.git /opt/openhabian
ln -s /opt/openhabian/openhabian-setup.sh /usr/local/bin/openhabian-config
cp /opt/openhabian/build-image/openhabian.conf /etc/openhabian.conf
Edit /etc/openhabian.conf
to match your needs, then finally use
openhabian-config unattended
to install.
# openHABian Configuration Tool
The following instructions are written for a Raspberry Pi but should be applicable to all hardware / 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 default is openhabian
).
sudo openhabian-config
The configuration tool is the heart and center of openHABian. It is not only a menu with a set of options but also used in a special unattended mode to automate the setup run, either as part of the RPi image or in a manual install run.
⌨ - 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.
# First steps with openHAB
After your first setup of openHABian completed successfully, please access the openHAB dashboard to dig into its possibilites. Check out the openHAB primers tutorial (opens new window). Be sure to read up on the Configuration (opens new window) section of the documentation pages to learn more.
# Linux Hints
If you're a newbie to Linux, you sooner or later will have to know some Linux if you want to copy some files or are on the search for a solution to a problem. Take some time at this stage to study 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.
- "Learn the ways of Linux-fu, for free" interactively with exercises at linuxjourney.com (opens new window).
- The official Raspberry Pi help articles over at raspberrypi.org (opens new window)
- "Now what?", Tutorial on the Command line console at LinuxCommand.org (opens new window)
# more openHABian configuration
openHABian is supposed to provide a ready-to-use openHAB base system. There are a few things, however, we need you to decide and act on right now at the beginning:
- Timezone: 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
locale
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 if your system is accessible from outside your private subnet.
All of these settings can be changed via the openHABian configuration tool.
Here are the passwords in question with their respective default "username:password" values. They can be changed from openHABian menu.
# Passwords
- 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")
- Amanda backup password (no default, applied when installing)
- Nginx reverse proxy login (no default, applied when installing) For manual configuration see here (opens new window).
- InfluxDB (No password set by default)
- Grafana visualization ("admin:admin")
# Availability and Backup
openHABian is designed to reliably run 24 hours a day, seven days a week. That's a complex challenge involving hardware, software and operational procedures. This is the right time to prepare your system for disasters such as getting hit by hardware outages or the SD card wear-out/corruption problem.
Preparing for hardware breakage is the challenge that is the most easy one to overcome with common-off-the-shelf hardware that is known to work as a drop-in replacement the very moment you will be in need of (e.g. when your smart home server just died).
get your spare hardware ready
Order spare pieces of all hardware components your home automation relies on to work. At a minimum, that's the computer itself and another storage medium. Have it ready for use on site, unboxed, mounted and tested to be working.
HEADS UP: that statement applies to EVERY hardware setup, even if you run openHAB in some virtualization environment on some $$$ x86 server rackmounted in your basement. For our recommended hardware setup that means getting another Raspberry Pi (same model), 2 more SD cards and a power supply (in case of emergency, a smartphone charger will also do).
That being said, openHABian has a number of built in software features we borrowed from professional data center operations.
SD cards are known they can 'wear out' after some time and crash your OS and openHAB setup and data when they do. See this community forum post (opens new window) for more information. The Zram feature moves write intensive parts of openHABian into RAM to mitigate the risk of SD card corruption. WARNING: power failure will result in some data to get lost (albeit the system should continue to run) so we recommend to also get an UPS. Zram is enabled by default for swap, logs and persistence data. You can toggle use in [menu option 38].
SD cards, SSDs and HDDs can break or crash just like any hardware. Mirror your SD card to have a ready-to-use alternative boot medium ready on site at any time ! Get an USB card writer and another SD card and set up SD mirroring using [menu option 53]. This will ensure you have an always ready-to-use clone of your storage medium handy at all times. In case of emergency, you can simply swap SD cards and get back online within just a few minutes. See auto backup documentation.
remote replacement
Disasters love to happen when you're not at home. With an openHABian RPi mirror SD setup, you can instruct your partner, kid or your cottage neighbour to replace the SD card and/or computer from remote, by phone. No need for Internet or any sort of configuring to get your system back up running.
Use the integrated original openHAB openhab-cli tool (opens new window) at regular intervals to interactively backup/restore your openHAB config [menu option 50/51].
Use Amanda Network Backup (opens new window) to create full system backups. HEADS UP: This is NOT meant to be a replacement for #1 or #3, it's a complement that will also enable you to restore your system to any point in time of the past. The specific Amanda documentation is here. Use [menu option 52] to set up.
For completeness, openHABian still provides the historic option to move the root filesystem to USB-attached devices. See [menu option 37]. We don't recommend or support doing so but if you're convinced this is beneficial to your situation, feel free to go for it.
WARNING 1: openHABian maintainers do not support you in applying hardware modifications to have an effect on the system itself such as to add an SSD drive to boot from. We clearly recommend not to do this, for your own sake of reliability.
WARNING 2: USB sticks are as susceptible to flash wear-out as SD cards are, making zram the better choice for a standard Pi to run off its internal SD card.
Standard openHABian install enables zram by default (#1). You can disable zram and move the system over using menu options 37 (#5) once you attached a safe external medium to your system (such as an SSD), but we recommend against doing so. To restate: this setup is not supported by us maintainers and you'll be on your very own to find and fix any problems you might run into.
Finally, we strongly suggest you install Amanda (#4) right after you finish your setup. Amanda is to take care to backup the whole system to be able to quickly restore it when in need. This is not done by default because it requires a number of user inputs, but you should not skip it for your own safety!
# Setup notes
# openhabian.conf
You can actually set a number of parameters before you run an unattended installation. This applies to the RPi image on an SD card as well as to a manual installation. You can also try with a different set of parameters if your initial attempt fails:
- Flash the system image to your micro SD card as described, do not remove the SD card yet
- Use Windows file explorer to access the first SD card partition. Re-plug if needed to open in Windows file explorer, it's a vfat/FAT-32 (Windows) filesystem.
- Open the file
openhabian.conf
in a text editor - Uncomment and complete the lines to contain the parameters you want to set
- Save, unmount/eject, remove and insert into the RPi and boot it
- Continue with the instructions for your hardware
Mind the comments for each configuration parameter. Browse the next documentation section for more explanations.
# Initial configuration
You can have openHABian import a working openHAB configuration right from the start at installation time like when you migrate or reinstall:
make the initialconfig
parameter point to either a file or URL.
Note that you can only place config zipfiles on the 1st (Windows) partition, and that partition will finally be accessible as /boot
from inside Linux.
So a filename would need to be /boot/xxx.zip
. Default is /boot/initial.zip
.
So if you have a openHAB configuration backup zipfile (created e.g. by using menu option 50), put it to the E: device that the first partition of your SD card shows up as on a Windows PC and change its name to 'initial.zip'.
# Administration user
Raspberry Pi OS images include a Linux user (pi
) that you can use for openHAB administration.
openHABian renames the user to what you specify in the username
parameter and assigns the userpw
password first, then it proceeds and makes various settings that are either useful (such as some aliases) or required to run openHAB.
You can also make use of this if you don't use the image but unattended installation on non-RPi hardware, openHABian will then create that user for you if it does not yet exist.
# Admin key
Make the adminkeyurl
point to an URL to contain a public SSH key.
This will be included with your administration user's .ssh/authorized_keys
and the openHAB console so the admin user (yourself, usually) can login right after installation without a password. This helps with automating deployments.
# Wi-Fi based setup notes
To setup openHABian via Wi-Fi only, make your SSID and password known to the system before the first boot.
In addition to the setup instructions given above, uncomment and complete the lines reading wifi_ssid=""
and wifi_password=""
in openhabian.conf
.
# Disable zram
Zram is activated by default on fresh installations on ARM hardware.
If you want to disable zram for some reason, use zraminstall=disable
in openhabian.conf
to install without.
# Debug mode
See Troubleshooting section if you run into trouble installing.
If you want to turn on debug mode edit openhabian.conf
and set the debugmode=
parameter to either off
, on
or maximum
.
Mind you that if you intend to open an issue, we need you to provide the output of debugmode=maximum
so if you're in interactive mode, set your terminal to record output.
# Auto backup
Auto backup is a marketing name for two distinct features that you can deploy in one go at unattended installation time on a RPi (when you deploy the image).
Technically it is a "low-cost" version of disk mirroring PLUS the setup of the Amanda backup system which all by itself has been available in a long time.
So don't let the name confuse you. If you didn't choose to set this up at installation time, you can also individually select these functions via openhabian-config
menu options 53 (mirroring) and 52 (Amanda).
Note mirroring is available on RPi hardware only while Amanda as the backup system is available on any openHABian-supported hardware-OS combo.
# SD mirroring
SD cards are known to 'wear out' the more you write to them. The SD mirroring feature uses an USB-attached card writer to keep a 2nd SD card in (loose) sync with the internal card. In case of the primary SD card to fail, you can easily swap cards to relaunch your OH and get it working again within just minutes. You can even instruct others with physical access if you cannot be on site, and you can make use of this feature to create system copies that you can store off-site to recover your smart home server in case a disaster happens.
To setup openHABian to automatically backup and mirror your internal SD card to an external storage unit, we suggest to use another SD card in an external card writer device so that in case your internal SD card fails, you can switch SD cards to get the system back up running fast.
We recommend to put in another card that has at least twice the size of the internal card. We can make use of that extra space as storage for the backup system. Note most "16GB" cards are not exactly 16 GB and your mirror mustn't have less bytes than the internal one so at setup time, openHABian ensures the second card has at least the same size as your internal card.
NO Do-It-Yourself mirroring
Note you must NOT use dd
or any other tool such as 'Win32 disk imager' to copy an SD card or partition on your own. If you do and boot with source and destination cards plugged in, they will have the same partition IDs and this will likely mess up things and can irreversibly devastate your whole system. Use the blkid
command in shell to see those IDs. This also means you must not take mirrors of the mirror.
Also be aware that only the first two partitions are mirrored - the storage (3rd) partition will never be mirrored even if you have set that up for use as your backup area.
To setup mirroring right during unattended installation of a RPi (using the image flash method):
Define backupdrive=/dev/sdX
(replace X with the proper character) to enable this functionality right during unattended installation.
The first attached disk type device is usually called /dev/sda
.
Use storagecapacity=xxx
to override how much space to consume at most for Amanda backup storage (in MB).
openHABian will create partitions 1 and 2 to be mirrors of your internal card and will assign the remaining space to another partition that you can use for storage.
NOTE: if you do and if the remaining space is sufficient, selecting this will also result in setting up the Amanda backup system on that extra space.
You can change where it stores its backup data via storagedir=/storage
, but you cannot unselect the Amanda setup at this stage.
If you want to setup mirroring only and Amanda anywhere else but on the extra SD space, you must not choose unattended installation method (i.e. do not define backupdrive
).
You can still setup both, mirroring and Amanda, separately at any later time using the 53 (mirroring) and 52 (Amanda) menu options.
Full mirroring of the full SD card will take place semiannually and only for the 2nd partition (Linux root), changes will be synced once every day.
See systemctl list-timers
, timers are defined in /etc/systemd/system/sd*.timer
.
Menu 5X provides interactive access to the aforementioned functions:
52 Amanda System Backup
will prepare an existing directory as your backup storage and make Amanda launch once a day. See the separate Amanda setup document.
53 Setup SD mirroring
prepares the partitions on an SD card and sets up timers to execute both, a full mirroring and complementary rsync 'diff' runs.
54 Raw copy SD
is a one-time raw copy (mirror) run.
55 Sync SD
propagates (syncs) differences from your main SD card to your external card.
In case of failure of your primary SD card, replace the broken SD card in the internal slot with your backup card from the external reader. Get another SD card that matches the size of the backup (now in internal slot) card and use menu option 54 to copy your active backup card back to the new one.
# Tailscale VPN network
Tailscale is a management toolset to establish a WireGuard based VPN between multiple systems if you want to connect to openHAB(ian) instances outside your LAN over Internet.
It'll take care to detect and open ports when you and your peers are located behind firewalls.
Download the client (opens new window) and eventually get the Solo service plan from Tailscale, that's free for private use and will automatically be selected when you fire up your first VPN node.
The Windows client has a link to the admin console where you can create pre-auth one-time keys.
These you can put as the preauthkey
into openhabian.conf
to automatically deploy remote openHABian nodes (unattended install) and have them join the VPN.
The tstags
option allows you to specify tags for use in Tailscale ACL (opens new window) definition.
# IPv6 notes
You might encounter problems when you make use of IPv6 on some networks and systems. openHABian installation may stop or hang forever.
In that case or if you are sure that you do not need IPv6 on your openHABian server, you can disable IPv6.
Follow the instructions in the previous section and insert a line into openhabian.conf
reading ipv6=disable
.
# Fake hardware mode
If to install openHABian fails because you have a non-supported hardware or run an unsupported OS release, you can "fake" your hardware and OS to make openHABian behave as if you did own that HW/OS.
In openhabian.conf
, uncomment and complete the lines reading hw=
, hwarch=
and/or osrelease=
with the hw and os versions you want to attempt installation with.
# Optional Components
openHABian comes with a number of additional tools to quickly install and set up additional home automation related software. You'll find all of these in the openHABian Configuration Tool, menu option 20.
- Frontail (opens new window) - openHAB Log Viewer accessible from http://openhabian:9001 (opens new window)
- InfluxDB and Grafana (opens new window) - persistence and graphing available from http://openhabian:3000 (opens new window)
- Eclipse Mosquitto (opens new window) - Open Source MQTT v3.1/v3.1.1 Broker
- Node-RED (opens new window) - "Flow-based programming for the Internet of Things". Access at http://openhabian:1880 (opens new window).
- Homegear (opens new window) - Homematic control unit emulation
- KNXd (opens new window) - KNX daemon running at
224.0.23.12:3671/UDP
- OWServer (opens new window) - 1wire control system
- FIND (opens new window) - the Framework for Internal Navigation and Discovery
- Mi Flora MQTT demon
# Troubleshooting
If you're having problems with getting openHABian to install properly, check out the debug guide. It's also available on your system as /opt/openhabian/docs/openhabian-DEBUG.md
.
You can ask for help on the openHABian community forum (opens new window) when the debug guide doesn't help but please first, read and mind the rules (opens new window).
If you want to get involved, you found a bug, or just want to see what's planned for the future, visit us on GitHub:
# Where can I find a changelog for openHABian?
Official announcements are displayed on starting openhabian-config
and stored in NEWS.md
(a file in /opt/openhabian
).
Release notes are also co-located with the download links here (opens new window).
If you want to stay in touch with all the latest code changes under the hood, see commit history (opens new window) for openHABian.
You'll also see commits "fly by" when executing the "Update" function within the openHABian Configuration Tool.
# Did my Installation succeed? What to do in case of a problem?
openHABian setup will take 15 up to 45 minutes to complete all steps, depending on your device's performance and your internet connection.
Watch the progress on the console or the web interface at http://:81(yourIP)/ (opens new window) or http://openhabian:81/ (opens new window) if that name has become available.
Double-check the IP address and name with your router while you wait.
If there is absolutely no output for more than 10 minutes, there probably is a problem with the way your router or local network are setup.
Read on in the Troubleshooting section.
Set debugmode=maximum
in openhabian.conf
to see what openHABian is doing.
After a few minutes of boot up time, you can connect to the SSH console (opens new window) of your device.
During the setup process you'll be redirected to the live progress report of the setup (you can Ctrl-C to get into the shell).
The report can also be checked for errors at any time, see /boot/first-boot.log
.
The progress of a successful installation will look like this:
Wait till the log tells you that the setup was "successful", then reconnect to the device.
# SSH Login Screen
If the installation was successful you will see the normal login screen as shown in the first screenshot. If the installation was not successful you will see a warning and further instructions as shown in the second screenshot.
# openHAB Dashboard
After the installation of openHABian was successful, you should be able to access the openHAB dashboard:
- Raspberry Pi image setup: http://openhabian:8080 (opens new window)
- In any case: http://your-device-hostname:8080 (opens new window) or http://192.168.0.2:8080 (opens new window) (replace name/IP with yours)
If you are not able to access your system via the openHAB dashboard or SSH after more than one hour, chances are high that your hardware setup is the problem. Consult the debug guide and move on from there.
openHABian is designed to install and work with the latest version of openHAB (currently 4.x). We do not support migrating older installation's persistence/configuration files to the latest version. Users will need to migrate and fix any issues with their persistence/configuration files on their own. Note: we will upgrade to a new major version of openHAB after warning and asking the user for confirmation, but will not do so automatically.
# Where is the graphical user interface?
I've just installed openHABian and now I'm confused. No fancy login screen, no windows, no mouse support. What did I get into?
You are not the first one to get confused about the intended use case of openHABian. Maybe it helps to not think of the RPi as a PC as we know it. An RPi is not (well, not necessarily) to be used with a keyboard and display. Its intended use case is to sit in a corner and provide a service reliably 24 hours a day, 7 days a week. You already own a powerful PC or Mac to work on.
What we actually want openHABian to be is a dedicated, headless system to reliably operate your home automation on and to expose all interfaces needed to interact and configure it (MainUI, openHAB LogViewer, Samba Network Shares, openHABian maintenance tool, SSH, you-name-it). If you know how to work with these interfaces, you are set for a way better experience than the alternatives. The main challenge is to get used to the Linux command line, not even a GUI will relieve you from that in the long run. If you are not willing to teach yourself a few fundamental Linux skills you will not become happy with any Linux system and should resort to a e.g. Windows machine. However as you are willing to tinker with smart home technology, I'm sure you are ready to teach yourself new stuff and expand your experience.