Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Automated] Fetch openhabian docs #1694

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file removed installation/images/openHABian-menu-freshsetup.png
Binary file not shown.
21 changes: 11 additions & 10 deletions installation/openhabian-DEBUG.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ This document is meant to give a guiding hand to users when their openHABian ins
Set `debugmode=maximum`in `/etc/openhabian.conf` and see `/boot/first-boot.log` for image installation else record the terminal output.
:::

**Do not ask for help on the forum unless you have _FULLY_ read this guide.**
**Please do not ask for help on the forum unless you have _FULLY_ read this guide.**

**Attention:**
If you do not use the image but use `openhabian-config` manually - either to run `openhabian-config unattended` or interactive use -, **there is no logfile**.
Expand All @@ -25,34 +25,35 @@ Keep in mind that parts of the following information such as for example Wi-Fi a
## Prerequisites
First, please make sure you use the proper host hardware that is supported as per [README](https://github.com/openhab/openhabian/blob/main/README.md).

openHABian requires a minimum of 1GB of RAM to run well. While you can get away with a 512MB box like a RPi0W, you must not run anything other than openHAB itself, in particular do **not** run memory hogs such as InfluxDB or Grafana.
openHABian requires a minimum of 1GB of RAM to run well. While you can get away with 512MB when your box has enough CPU power like a RPi0W2, you must not run anything other than openHAB itself, in particular do **not** run memory hogs such as InfluxDB or Grafana.

openHABian requires you to provide direct Internet access.
openHABian requires you to provide direct Internet access for the duration of the installation.
Using private IP addresses is fine as long as your router properly provides NAT (Network Address Translation) services.
Either Ethernet or WiFi is supported at install time. WiFi requires either user configuration prior to the first boot of openHABian or to use the [hotspot](openhabian.md#wi-fi-hotspot) which will be launched whenever there's no Internet connectivity.
To configure WiFi, edit the `wifi_password=`, `wifi_ssid=` and `wifi_country=`fields in the `boot/openhabian.conf` file on your new SD card.

Your router (or a different device) needs to to provide properly configured DHCP services so your openHABian box gets an IP address assigned when you boot it for the first time.
The DHCP server also has to announce which DNS resolver to use so your box knows how to translate DNS names into IP addresses.
It also needs to announce which IP address to use as the default gateway to the internet - a typical access router is also the DHCP server will announce it's own address here.
Your router (or a separate device) needs to provide properly configured DHCP services so your openHABian box gets an IP address assigned when you boot it for the first time.
The DHCP server also has to announce which DNS resolver to use so the box we install knows how to translate DNS names into IP addresses.
It also needs to announce which IP address to use as the default gateway to the internet - a typical access router is also the DHCP server and will announce it's own address here.
Finally, the DHCP server should also announce the NTP server(s) to use for proper time services.
Lack thereof will not break the installation procedure but can lead to all sorts of long term issues so we recommend to setup DHCP to announce a reachable and working NTP server.

A note on fixed IP addressing: openHABian does NOT support these as it'll interfere with the other methods to configure networking. If you want to have a static IP, instead get the MAC address of your box and configure your DHCP server to map that MAC to the very specific IP you would like to use.
A note on fixed IP addressing: openHABian does NOT support setting fixed IP address. That'll interfere with the other methods to configure networking. Don't mess with the Linux config files even if you are proficient in Linux. If you want to have a static IP, instead get the MAC address of your box and configure your DHCP server to map that MAC to the very specific IP you would like to obtain.

A note on IPv6: openHABian was reported failing to boot in some environments that make use of IPv6.
If basic IP initialization fails (you cannot `ping` your box) or installation gets stuck trying to download software packages, you might want to try disabling IPv6.
You can also do that before the very first install attempt if you're sure you don't need any IPv6 connectivity on your openHABian box.
See [this section of openhabian.md](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#ipv6-notes) how to disable IPv6 on your system.

Note that this is just a summary to cover the most commonly encountered cases.
The full boot procedure and how to obtain IP addresses, DNS resolver, default route and NTP server addresses are highly complex and widely customizable and a comprehensive description on how to properly configure your Internet access and router are out of scope of openHABian docs.
Please use an internet search to find more on your own.

## Install
Proceed to installation: Etch-Burn-d(isk)d(ump)-Flash-whatever the image to an SD card.
Proceed to installation: Flash-whatever the image to an SD card. Use the Raspi Imager or Etcher.

NOW, read [openhabian.md](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#openhabianconf) how to mount your SD card and how to modify the openHABian config file.
Some parameters are self-explanatory but please nonetheless read the full explanation in the linked document.
NOW, read [openhabian.md](https://github.com/openhab/openhabian/blob/main/docs/openhabian.md#openhabianconf) how to access your SD card and how to modify the openHABian config file on there.
Some parameters are self-explanatory but some are not so please nonetheless read their full explanation in the linked document.
Given that you're already reading the debug guide, the most important parameter to set is likely `debugmode=maximum`.
Once you have passed the first time boot initialization phase and you can login to the system, `/etc/openhabian.conf` will be used from there on.
You can change it at any time to get output on future boot runs or if you use `openhabian-config` interactively.
Expand Down
Loading