mirror of
https://github.com/home-assistant/operating-system.git
synced 2025-08-07 12:17:41 +00:00
Migrate docs to developers.home-assistant.io (#4215)
* Migrate docs to developers.home-assistant.io Move all documentation (except the kernel.md, for which it makes sense to be kept here) to developers.home-assistant.io. Just bluetooth.md was intentionally not preserved, as the information value was low and it was out of date anyway. See home-assistant/developers.home-assistant#2748 * Fix reference links
This commit is contained in:
Jan Čermák
GitHub
parent
4c09ceb656
commit
cbcf9ae34e
@ -1,9 +1,9 @@
|
||||
# Documentation
|
||||
|
||||
## Contents
|
||||
Documentation for the Home Assistant Operating System is available at [developers.home-assistant.io/docs/operating-system/][docs].
|
||||
If you want to contribute to this documentation, please refer to the [home-assistant/developers.home-assistant][docs-repo] repository.
|
||||
|
||||
- [Configuration](./configuration.md) - how users can configure HAOS
|
||||
- [Network](./network.md) - approach to networking
|
||||
- [Bluetooth](./bluetooth.md) - approach to bluetooth
|
||||
- [Kernel](./kernel.md) - kernel versions
|
||||
- [Boards](./boards/README.md) - board specific documentation
|
||||
For the list of Linux kernel versions used currently in this branch of Home Assistant Operating System, see [kernel.md](./kernel.md).
|
||||
|
||||
[docs]: https://developers.home-assistant.io/docs/operating-system/
|
||||
[docs-repo]: https://github.com/home-assistant/developers.home-assistant/
|
||||
|
||||
@ -1,12 +0,0 @@
|
||||
# Bluetooth
|
||||
|
||||
We support `bluetoothctl` on the host. Later we want to support Bluetooth through the UI.
|
||||
All pairs and settings are persistent over reboots and updates.
|
||||
|
||||
If you want to setup Bluetooth on the host, use the `bluetoothctl` utility.
|
||||
|
||||
## Scan devices
|
||||
|
||||
```
|
||||
[bluetooth]# scan on
|
||||
```
|
||||
@ -1,62 +0,0 @@
|
||||
# Boards
|
||||
|
||||
## Overview
|
||||
|
||||
The following boards/devices are supported:
|
||||
|
||||
- Nabu Casa
|
||||
- [Home Assistant Green](https://www.home-assistant.io/green/)
|
||||
- [Home Assistant Yellow](https://www.home-assistant.io/yellow/) (based custom carrier board and powered by a Raspberry Pi 4 Compute Module)
|
||||
- [Home Assistant Blue](https://www.home-assistant.io/blue/) (based on ODROID-N2+)
|
||||
- Raspberry Pi
|
||||
- Pi 5 ([4 GB](https://www.raspberrypi.com/products/raspberry-pi-5/?variant=raspberry-pi-5-4gb) and [8 GB](https://www.raspberrypi.com/products/raspberry-pi-5/?variant=raspberry-pi-5-8gb) model) 64-bit
|
||||
- Pi 4 Model B ([1 GB](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-1gb), [2 GB](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-2gb), [4 GB](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-4gb) and [8 GB](https://www.raspberrypi.com/products/raspberry-pi-4-model-b/?variant=raspberry-pi-4-model-b-8gb) model) 32-bit or 64-bit (recommended)
|
||||
- [Pi 3 Model B](https://www.raspberrypi.com/products/raspberry-pi-3-model-b/) and [B+](https://www.raspberrypi.com/products/raspberry-pi-3-model-b-plus/) 32-bit or 64-bit (recommended)
|
||||
- [Pi 2](https://www.raspberrypi.com/products/raspberry-pi-2-model-b/) (not recommended)
|
||||
- Hardkernel
|
||||
- [ODROID-C2](https://www.hardkernel.com/shop/odroid-c2/) (discontinued)
|
||||
- [ODROID-C4](https://www.hardkernel.com/shop/odroid-c4/)
|
||||
- [ODROID-M1](https://www.hardkernel.com/shop/odroid-m1/)
|
||||
- ODROID-M1S [4 GB](https://www.hardkernel.com/shop/odroid-m1s-with-4gbyte-ram/) or [8 GB](https://www.hardkernel.com/shop/odroid-m1s-with-8gbyte-ram/)
|
||||
- [ODROID-N2](https://www.hardkernel.com/shop/odroid-n2/) (discontinued)
|
||||
- ODROID-N2+ [2 GB](https://www.hardkernel.com/shop/odroid-n2-with-2gbyte-ram-2/) or [4 GB](https://www.hardkernel.com/shop/odroid-n2-with-4gbyte-ram-2/)
|
||||
- [ODROID-XU4](https://www.hardkernel.com/shop/odroid-xu4-special-price/)
|
||||
- Asus
|
||||
- [Tinker Board](https://tinker-board.asus.com/product/tinker-board.html)
|
||||
- Generic x86-64 (UEFI, not suited for virtualization)
|
||||
- [Intel NUC5CPYH](https://www.intel.com/content/www/us/en/products/sku/85254/intel-nuc-kit-nuc5cpyh/specifications.html)
|
||||
- [Intel NUC6CAYH](https://www.intel.com/content/www/us/en/products/sku/95062/intel-nuc-kit-nuc6cayh/specifications.html)
|
||||
- [Intel NUC10I3FNK2](https://www.intel.com/content/www/us/en/products/sku/195503/intel-nuc-10-performance-kit-nuc10i3fnk/specifications.html)
|
||||
- [Gigabyte GB-BPCE-3455](https://www.gigabyte.com/Mini-PcBarebone/GB-BPCE-3455-rev-10/sp#sp)
|
||||
- Computers supporting x86-64 architecture and UEFI boot should generally work
|
||||
- Virtual appliance (x86_64/UEFI):
|
||||
- VMDK
|
||||
- OVA ?
|
||||
- VHDX ?
|
||||
- VDI ?
|
||||
- QCOW2 ?
|
||||
|
||||
Notes:
|
||||
- see ? above: are these currently supported? see ova documentation which explains issues with previous OVA distribution)
|
||||
|
||||
## Board specifics
|
||||
|
||||
|Board|Build|Config|Docs|
|
||||
|-----|----|------|----|
|
||||
|Green |`make green` |[green](../../buildroot-external/configs/green_defconfig)|-|
|
||||
|Yellow |`make yellow` |[yellow](../../buildroot-external/configs/yellow_defconfig)|-|
|
||||
|Pi5 64-bit |`make rpi5_64` |[rpi5_64](../../buildroot-external/configs/rpi5_64_defconfig)|[raspberrypi](./raspberrypi/)|
|
||||
|Pi4B 64-bit |`make rpi4_64` |[rpi4_64](../../buildroot-external/configs/rpi4_64_defconfig)|[raspberrypi](./raspberrypi/)|
|
||||
|Pi4B 32-bit |`make rpi4` |[rpi4](../../buildroot-external/configs/rpi4_defconfig)|[raspberrypi](./raspberrypi/)|
|
||||
|Pi3B 64-bit |`make rpi3_64` |[rpi3_64](../../buildroot-external/configs/rpi3_64_defconfig)|[raspberrypi](./raspberrypi/)|
|
||||
|Pi3B 32-bit |`make rpi3` |[rpi3](../../buildroot-external/configs/rpi3_defconfig)|[raspberrypi](./raspberrypi/)|
|
||||
|Pi2 |`make rpi2` |[rpi2](../../buildroot-external/configs/rpi2_defconfig)|[raspberrypi](./raspberrypi/)|
|
||||
|ODROID-C2 |`make odroid_c2` |[odroid_c2](../../buildroot-external/configs/odroid_c2_defconfig)|[hardkernel](./hardkernel/)|
|
||||
|ODROID-C4 |`make odroid_c4` |[odroid_c4](../../buildroot-external/configs/odroid_c4_defconfig)|[hardkernel](./hardkernel/)|
|
||||
|ODROID-M1 |`make odroid_m1` |[odroid_m1](../../buildroot-external/configs/odroid_m1_defconfig)|[hardkernel](./hardkernel/)|
|
||||
|ODROID-M1S |`make odroid_m1s` |[odroid_m1s](../../buildroot-external/configs/odroid_m1s_defconfig)|[hardkernel](./hardkernel/)|
|
||||
|ODROID-N2/N2+ |`make odroid_n2` |[odroid_n2](../../buildroot-external/configs/odroid_n2_defconfig)|[hardkernel](./hardkernel/)|
|
||||
|ODROID-XU4 |`make odroid_xu4` |[odroid_xu4](../../buildroot-external/configs/odroid_xu4_defconfig)|[hardkernel](./hardkernel/)|
|
||||
|Tinker Board |`make tinker` |[tinker](../../buildroot-external/configs/tinker_defconfig)|[asus](./asus/)|
|
||||
|Generic x86-64|`make generic_x86_64`|[generic_x86_64](../../buildroot-external/configs/generic_x86_64_defconfig)|[generic-x86-64](./generic-x86-64/)|
|
||||
|OVA |`make ova` |[ova](../../buildroot-external/configs/ova_defconfig)|[ova](./ova/)|
|
||||
@ -1,31 +0,0 @@
|
||||
# Tinker Board
|
||||
|
||||
## Supported Hardware
|
||||
|
||||
| Device | Release Date | Support | Config |
|
||||
|----------------|---------------|---------|----------|
|
||||
| Tinker RK3288 | April 2017 | yes | [tinker](../../../buildroot-external/configs/tinker_defconfig) |
|
||||
| Tinker S RK3288| January 2018 | yes | [tinker](../../../buildroot-external/configs/tinker_defconfig) |
|
||||
| Tinker Edge T | November 2019 | no? | |
|
||||
| Tinker Edge R | November 2019 | no? | |
|
||||
|
||||
## eMMC
|
||||
|
||||
eMMC support is provided with the same image. Just flash the image to the eMMC by connecting your Tinker Board S to your PC via Micro-USB. Refer to the Tinkerboard documentation how-to flash using Micro-USB and UMS.
|
||||
|
||||
The Home Assistant OS provided U-Boot does support UMS as well,
|
||||
however manual intervention is necessary:
|
||||
|
||||
1. Set the jumper between Micro-USB and HDMI the maskrom mode
|
||||
2. Insert SD card and connect the board via Micro-USB to your PC
|
||||
3. Continusly press Ctrl+C to interrupt boot
|
||||
4. Set the jumper back to the park position
|
||||
5. Start UMS using:
|
||||
```
|
||||
ums 0 mmc 0
|
||||
```
|
||||
6. A mass storage device should appear. Flash Home Assistant OS to it.
|
||||
|
||||
## Serial console
|
||||
|
||||
To access the terminal over serial console, add `console=ttyS2,115200` to `cmdline.txt`. GPIO pins are: 34 = GND / 32 = UART TXD / 33 = UART RXD.
|
||||
@ -1,36 +0,0 @@
|
||||
# Generic aarch64
|
||||
|
||||
## Supported Hardware
|
||||
|
||||
This board configuration aims to support most aarch64 systems with UEFI boot
|
||||
Hardware it has been tested with is listed below.
|
||||
|
||||
## Tested Hardware
|
||||
|
||||
| Device | Release Date | Support | Config |
|
||||
|-----------------------|--------------|---------|-------------|
|
||||
| QEMU | QEMU | yes | [generic_aarch64](../../../buildroot-external/configs/generic_aarch64_defconfig) |
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
- aarch64 support
|
||||
- UEFI boot
|
||||
|
||||
## Wifi
|
||||
|
||||
WiFi is untested.
|
||||
|
||||
## Bluetooth
|
||||
|
||||
Bluetooth is untested.
|
||||
|
||||
## Installation
|
||||
|
||||
Make sure secure boot is disabled in the UEFI BIOS settings.
|
||||
|
||||
Currently there is no shiny installation method. Checklist:
|
||||
- Boot PC to live environment using PXE or USB
|
||||
- Copy or download the Home Assistant OS image into your live environment
|
||||
- unxz the image and dd to the local hard disk
|
||||
- Reboot
|
||||
@ -1,62 +0,0 @@
|
||||
# Generic x86-64
|
||||
|
||||
## Supported Hardware
|
||||
|
||||
This board configuration aims to support most x86-64 systems with UEFI boot. The
|
||||
main aim is to support Intel NUC mini PCs and similar systems. Hardware it has
|
||||
been tested with is listed below.
|
||||
|
||||
## Tested Hardware
|
||||
|
||||
| Device | Release Date | Support | Config |
|
||||
|-----------------------|--------------|---------|-------------|
|
||||
| Intel NUC5CPYH | Q3 2015 | yes | [generic_x86_64](../../../buildroot-external/configs/generic_x86_64_defconfig) |
|
||||
| Intel NUC6CAYH | Q4 2016 | yes | [generic_x86_64](../../../buildroot-external/configs/generic_x86_64_defconfig) |
|
||||
| Intel NUC6CAYS | Q4 2016 | yes | [generic_x86_64](../../../buildroot-external/configs/generic_x86_64_defconfig) |
|
||||
| Intel NUC7i3DNHE | Q3 2017 | yes | [generic_x86_64](../../../buildroot-external/configs/generic_x86_64_defconfig) |
|
||||
| Intel NUC10i3FNK2 | Q4 2019 | yes | [generic_x86_64](../../../buildroot-external/configs/generic_x86_64_defconfig) |
|
||||
| Gigabyte GB-BPCE-3455 | 2017 | yes* | [generic_x86_64](../../../buildroot-external/configs/generic_x86_64_defconfig) |
|
||||
|
||||
\* needs 'nomodeset' in cmdline.txt if you want a console
|
||||
|
||||
|
||||
## Requirements
|
||||
|
||||
- x86-64 support
|
||||
- UEFI boot
|
||||
- SATA/AHCI or eMMC storage
|
||||
- Supported NIC:
|
||||
- Intel Gigabit NIC (e1000, igb - via Linux mainline)
|
||||
- Intel PCIe Gigabit NIC (e1000e - via out-of-tree module in *buildroot-external/package/intel-e1000e*)
|
||||
- Realtek Gigabit NIC (r8169)
|
||||
- Intel Wireless Wifi 802.11ac (iwlwifi, see below)
|
||||
|
||||
## Wifi
|
||||
|
||||
The following cards are supported:
|
||||
|
||||
- Intel Wireless 3160
|
||||
- Intel Wireless 7260
|
||||
- Intel Wireless 7265
|
||||
- Intel Wireless-AC 3165
|
||||
- Intel Wireless-AC 3168
|
||||
- Intel Wireless-AC 8260
|
||||
- Intel Wireless-AC 8265
|
||||
- Intel Wireless-AC 9260
|
||||
- Intel Wireless-AC 9461
|
||||
- Intel Wireless-AC 9462
|
||||
- Intel Wireless-AC 9560
|
||||
|
||||
## Bluetooth
|
||||
|
||||
Bluetooth integrated in Intel Wireless cards working OK, other options untested.
|
||||
|
||||
## Installation
|
||||
|
||||
Make sure secure boot is disabled in the UEFI BIOS settings.
|
||||
|
||||
Currently there is no shiny installation method. Checklist:
|
||||
- Boot PC to live environment using PXE or USB
|
||||
- Copy or download the Home Assistant OS image into your live environment
|
||||
- unxz the image and dd to the local hard disk
|
||||
- Reboot
|
||||
@ -1,28 +0,0 @@
|
||||
# ODROID
|
||||
|
||||
## Supported Hardware
|
||||
|
||||
| Device | Release Date | Support | Config |
|
||||
|----------------|---------------|--------------|-----------|
|
||||
| ODROID-C2 | 2016 | yes | [odroid_c2](../../../buildroot-external/configs/odroid_c2_defconfig) |
|
||||
| ODROID-C4 | 2020 | yes | [odroid_c4](../../../buildroot-external/configs/odroid_c4_defconfig) |
|
||||
| ODROID-M1 | 2022 | yes | [odroid_m1](../../../buildroot-external/configs/odroid_m1_defconfig) |
|
||||
| ODROID-M1S | 2023 | yes | [odroid_m1s](../../../buildroot-external/configs/odroid_m1s_defconfig)|
|
||||
| ODROID-N2 | 2019 | yes | [odroid_n2](../../../buildroot-external/configs/odroid_n2_defconfig) |
|
||||
| ODROID-XU4 | 2015 | yes | [odroid_xu4](../../../buildroot-external/configs/odroid_xu4_defconfig)|
|
||||
|
||||
See separate documentation for each board.
|
||||
|
||||
## Connectivity devices
|
||||
|
||||
### Wi-Fi
|
||||
|
||||
The following devices have been tested on Home Assistant OS 5.8:
|
||||
|
||||
- [Bluetooth Module 2](https://www.hardkernel.com/shop/bluetooth-module-2/)
|
||||
- [WiFi Module 3](https://www.hardkernel.com/shop/wifi-module-3/)
|
||||
|
||||
The [WiFi Module 5A](https://www.hardkernel.com/shop/wifi-module-5a/) is not
|
||||
recommended as there is no upstream driver support available. The driver
|
||||
currently compatible with recent Linux kernel version seems to have issues
|
||||
connecting to 5GHz networks.
|
||||
@ -1,22 +0,0 @@
|
||||
# ODROID-C2
|
||||
|
||||
## eMMC
|
||||
|
||||
eMMC support is provided transparently. Just flash the image to the eMMC board as you would an SD card.
|
||||
|
||||
## Console
|
||||
|
||||
By default, console access is granted over the serial header and over HDMI. Certain startup messages will only appear on the serial console by default. To show the messages on the HDMI console instead, swap the order of the two consoles in the `cmdline.txt` file on the boot partition. You can also delete the AML0 console if you don't plan on using the serial adapter.
|
||||
eg. `console=ttyAML0,115200n8 console=tty0`
|
||||
|
||||
## USB
|
||||
|
||||
A long-standing kernel bug currently results in some odd behavior. To use the USB, a device must be plugged into one of the USB ports at hard boot. If all devices are removed from the USB ports, the USB will cease to function until a reboot.
|
||||
|
||||
### OTG
|
||||
|
||||
The OTG USB is untested.
|
||||
|
||||
## GPIO
|
||||
|
||||
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-c2/hardware/expansion_connectors).
|
||||
@ -1,16 +0,0 @@
|
||||
# ODROID-C4
|
||||
|
||||
## Experimental
|
||||
|
||||
ODROID-C4 support is based heavily on the Odroid-C2 and N2 configurations. Given the similarity of the SoCs, as well as the comparable level of support in the Linux kernel, the C4 should hopefully present few surprises. However, Home Assistant support should be regarded as experimental.
|
||||
|
||||
Please also refer to the documentation pages for the [ODROID-C2](./odroid-c2.md) and [Odroid-N2](./odroid-n2.md), as some of that information may apply to the C4 as well.
|
||||
|
||||
Common C4 issues that have been specifically tested and appear to be working:
|
||||
- boot from SD
|
||||
- boot from eMMC
|
||||
- MAC address obtained from eFuse
|
||||
|
||||
## GPIO
|
||||
|
||||
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-c4/hardware/expansion_connectors).
|
||||
@ -1,50 +0,0 @@
|
||||
# ODROID-M1
|
||||
|
||||
Home Assistant OS 10 and newer support the ODROID-M1 board.
|
||||
|
||||
## SD-card
|
||||
|
||||
SD-card boot is supported via on-board bootloader (SPL) or recovery button.
|
||||
|
||||
## eMMC
|
||||
|
||||
eMMC boot via on-board bootloader requires a newer version of Petitboot
|
||||
(spiboot 20230328 or later). To install the latest version download the SPI boot image
|
||||
from [linuxfactory.or.kr][1] as follows:
|
||||
|
||||
1. Download `spiupdate_odroidm1_20240415.img.xz`
|
||||
2. Use balenaEtcher or another tool to flash the updater onto an SD card
|
||||
3. Download `spiboot-20240109.img`
|
||||
4. Rename the `spiboot-20240109.img` file to`spiboot.img`.
|
||||
5. Paste the `spiboot.img` file onto the FAT partition of that same SD card.
|
||||
6. Plug-in that SD card to your ODROID-M1. Petitboot will update itself, you can verify the progress on the HDMI output.
|
||||
7. If you see the version 20240109 in the top left corner, the installation was successful.\
|
||||
If you see any other version there, the installation failed.
|
||||
|
||||
Once Petitboot is updated you can flash Home Assistant OS directly onto an eMMC.
|
||||
|
||||
## NVMe
|
||||
|
||||
Booting directly from NVMe is not supported. The NVMe card can be used as a data disk.
|
||||
|
||||
## Technical notes on boot flow
|
||||
|
||||
The Home Assistant OS image is bootable by the SoC directly. This means that no help
|
||||
from the Hardkernel provided and pre-installed bootloader Petitboot is necessary.
|
||||
However, the ODROID-M1 automatically boots from internal SPI. To boot
|
||||
directly off the SD-card or eMMC you need to press the recovery button.
|
||||
|
||||
The SPI flashed U-Boot SPL tries searches for an U-Boot binary on the SD-card
|
||||
(and from eMMC with Petitboot 20230328 and later). This mechanism allows you to
|
||||
boot the Home Assistant OS U-Boot without pressing the recovery button.
|
||||
|
||||
## Console
|
||||
|
||||
By default, console access is available on the serial header (CON1) and on HDMI.
|
||||
The serial console's baudrate is 1500000 by default.
|
||||
|
||||
The systemd startup messages will only appear on the serial console by default.
|
||||
To show the messages on the HDMI console instead, add the console manually
|
||||
to the `cmdline.txt` file on the boot partition (e.g. `console=tty0`).
|
||||
|
||||
[1]: http://ppa.linuxfactory.or.kr/images/petitboot/odroidm1/
|
||||
@ -1,58 +0,0 @@
|
||||
# ODROID-M1S
|
||||
|
||||
Home Assistant OS 12 and newer support the ODROID-M1S board.
|
||||
|
||||
## SD-card
|
||||
|
||||
ODROID-M1S can boot HAOS directly from an SD card, as it has higher priority than the system on the eMMC. Simply flash the image to the SD card using your favorite tool and insert it to the micro SD slot on the board. This works even when the eMMC is wiped, or when it contains the factory-default U-Boot SPL loader, which is still able to load U-Boot provided in the HAOS image. In the second case, however, if the SD card fails to probe (e.g. due to a hardware failure), the system on the eMMC may be booted instead of HAOS.
|
||||
|
||||
## eMMC
|
||||
|
||||
HAOS can be installed directly to the eMMC using a special boot image, to do that:
|
||||
|
||||
1. Download the _UMS Utility_ image: [`ODROID-M1S_EMMC2UMS.img`][1]. The _UMS Utility_ is a special image that switches ODROID-M1S to USB Mass Storage device.
|
||||
2. Use balenaEtcher or another tool to flash the _UMS utility_ onto an SD card.
|
||||
3. Plug-in that SD card to your ODROID-M1S and boot it. Connect your PC to the Micro USB OTG port.
|
||||
4. The eMMC will show as a drive on your PC and you can directly flash the HAOS image with balenaEther.
|
||||
|
||||
Installing HAOS replaces the firmware and SPL on the eMMC with the mainline version provided by HAOS. As a result, it is not possible to use the SD card with the EMMC2UMS image anymore, because the mainline SPL is not compatible with U-Boot in the EMMC2UMS image at this time (February 2024). This does not pose any problem for standard use, just makes it more complicated in case you want to return to the Hardkernel-provided OS.
|
||||
|
||||
A reliable way of reflashing the eMMC in this case is to use HAOS booted from an SD card. To do that, insert the SD card with HAOS to the micro SD slot and plug the board in. Once the device boots to the HA CLI, enter `login` to enter the root shell and use `curl` to download an image and `dd` it to the eMMC block device:
|
||||
|
||||
```sh
|
||||
curl https://dn.odroid.com/RK3566/ODROID-M1S/Installer/ODROID-M1S_EMMC2UMS.img | dd of=/dev/mmcblk0
|
||||
```
|
||||
|
||||
This way the device will start in the UMS mode on the next boot with the SD card removed. Alternatively you can use the [Hardkernel installer image][2] directly instead of the EMMC2UMS image.
|
||||
|
||||
## NVMe
|
||||
|
||||
Booting directly from NVMe is not supported. The NVMe card can be used as a data disk.
|
||||
|
||||
## Technical notes on boot flow
|
||||
|
||||
The Home Assistant OS image is bootable by the SoC directly. Refer to the [boot sequence documentation][3] for the details on what part of the boot is executed from the eMMC and what from the SD card. The steps documented above should however cover all scenarios that a standard user may encounter during usage.
|
||||
|
||||
## Console
|
||||
|
||||
By default, console access is available on the serial header (UART) and on HDMI.
|
||||
The serial console's baudrate is 1500000 by default.
|
||||
|
||||
The systemd startup messages will only appear on the serial console by default.
|
||||
To show the messages on the HDMI console instead, add the console manually
|
||||
to the `cmdline.txt` file on the boot partition (e.g. `console=tty0`).
|
||||
|
||||
## GPIO
|
||||
|
||||
Odroid-M1S introduces a new 14pin expansion header. Refer to [the ODROID wiki][4].
|
||||
At this point not all functionality is supported by the upstream kernel used by Home Assistant OS.
|
||||
Supported modules include:
|
||||
- UPS
|
||||
- Internal USB
|
||||
- Mini IO board (partial support)
|
||||
|
||||
|
||||
[1]: https://dn.odroid.com/RK3566/ODROID-M1S/Installer/ODROID-M1S_EMMC2UMS.img
|
||||
[2]: https://wiki.odroid.com/odroid-m1s/getting_started/os_installation_guide#user_installer
|
||||
[3]: https://wiki.odroid.com/odroid-m1s/board_support/boot_sequence
|
||||
[4]: https://wiki.odroid.com/odroid-m1s/hardware/expansion_connectors
|
||||
@ -1,18 +0,0 @@
|
||||
# ODROID-N2
|
||||
|
||||
## eMMC
|
||||
|
||||
eMMC support is provided transparently. Just flash the image to the eMMC board as you would an SD card.
|
||||
|
||||
## Console
|
||||
|
||||
By default, console access is granted over the serial header and over HDMI. Certain startup messages will only appear on the serial console by default. To show the messages on the HDMI console instead, swap the order of the two consoles in the `cmdline.txt` file on the boot partition. You can also delete the AML0 console if you don't plan on using the serial adapter.
|
||||
eg. `console=ttyAML0,115200n8 console=tty0`
|
||||
|
||||
## GPIO
|
||||
|
||||
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-n2/hardware/expansion_connectors).
|
||||
At this point not all functionality is supported by the upstream kernel used
|
||||
by Home Assistant OS.
|
||||
|
||||
The GPIO on pin 11 is used as a low active power button input.
|
||||
@ -1,29 +0,0 @@
|
||||
# ODROID-XU4
|
||||
|
||||
## eMMC
|
||||
|
||||
The ODROID XU4 uses the eMMC boot partition to boot from. Typically eMMC readers can't write to this eMMC boot partition. There are a couple of possibilities:
|
||||
|
||||
1. **Working** e.g. the eMMC already had a working image before flashing HassOS:
|
||||
- It will be booting to U-Boot (but no further).
|
||||
- If you have the serial adapter, you should be able to enter `distro_bootcmd` at the uboot prompt to continue booting.
|
||||
- If not, flash the HassOS image to an SD card and boot off that temporarily (while the eMMC is also plugged in).
|
||||
- Once booted, login at the prompts and then enter `dd if=/dev/mmcblk0 of=/dev/mmcblk0boot0 bs=512 skip=63 seek=62 count=1440` at the linux prompt.
|
||||
- Reboot with eMMC (don't forget to flip the boot switch to eMMC)
|
||||
2. **Not Working** e.g. a clean/wiped/corruped eMMC boot partition:
|
||||
- You'll need to follow [Hardkernel's instructions](https://forum.odroid.com/viewtopic.php?f=53&t=6173) to get a working boot sector. Then flash HassOS and follow instructions above.
|
||||
- Alternatively, you can try flash HassOS to both an SD and eMMC, then boot off the SD with the eMMC also plugged in, then run `dd if=/dev/mmcblk1 of=/dev/mmcblk0boot0 bs=512 skip=1 seek=0 count=16381` at the Linux prompt. Note that this is untested, but in theory should work..
|
||||
|
||||
If you are getting permissions issues when using the dd command, try disabling RO:
|
||||
`echo 0 > /sys/block/mmcblk0boot0/force_ro`
|
||||
to re-enable after running dd:
|
||||
`echo 1 > /sys/block/mmcblk0boot0/force_ro`
|
||||
|
||||
## Console
|
||||
|
||||
By default, console access is granted over the serial header and over HDMI. Certain startup messages will only appear on the serial console by default. To show the messages on the HDMI console instead, swap the order of the two consoles in the `cmdline.txt` file on the boot partition. You can also delete the SAC2 console if you don't plan on using the serial adapter.
|
||||
eg. `console=tty1 console=ttySAC2,115200`
|
||||
|
||||
## GPIO
|
||||
|
||||
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-xu4/hardware/expansion_connectors).
|
||||
@ -1,22 +0,0 @@
|
||||
# Virtual Machine
|
||||
|
||||
## Supported Hypervisors
|
||||
|
||||
| Hypervisor | Vendor | Support | Config |
|
||||
|---------------------|-----------|-----------------|--------------------|
|
||||
| HyperV | Microsoft | yes, via VMDK | [ova](../../../buildroot-external/configs/ova_defconfig) |
|
||||
| VirtualBox | Oracle | yes, via VMDK | [ova](../../../buildroot-external/configs/ova_defconfig) |
|
||||
| VMware | VMware | yes, via VMDK | [ova](../../../buildroot-external/configs/ova_defconfig) |
|
||||
|
||||
Currently we only publish a VMDK virtual disk due to issues with our previous OVA distribution. We are investigating our options to bring back the OVA distribution, however, the VMDK works for the hypervisors listed above.
|
||||
|
||||
## Requirements
|
||||
|
||||
Using this VMDK in a virtual machine requires the following:
|
||||
|
||||
- Operating system: Other 4.x or later Linux (64-bit)
|
||||
- Enabled support for UEFI boot
|
||||
- SATA disk controller
|
||||
- Minimal of 1GB RAM
|
||||
- At least 2x vCPU
|
||||
- An assigned network
|
||||
@ -1,50 +0,0 @@
|
||||
# Raspberry PI
|
||||
|
||||
## Supported Hardware
|
||||
|
||||
| Device | Release Date | Support | Config |
|
||||
|---------------------|---------------|-----------------|--------------------|
|
||||
| Raspberry Pi 2 B |2015 | not recommended | [rpi2](../../../buildroot-external/configs/rpi2_defconfig) |
|
||||
| Raspberry Pi 3 B/B+ |2016/2018 | yes | [rpi3](../../../buildroot-external/configs/rpi3_defconfig) / [rpi3_64](../../../buildroot-external/configs/rpi3_64_defconfig) |
|
||||
| Raspberry Pi 4 B |2019 | yes | [rpi4](../../../buildroot-external/configs/rpi4_defconfig) / [rpi4_64](../../../buildroot-external/configs/rpi4_64_defconfig) |
|
||||
| Raspberry Pi 5 |2023 | yes (beta) | [rpi5_64](../../../buildroot-external/configs/rpi5_64_defconfig) |
|
||||
|
||||
## Serial console
|
||||
|
||||
For access to terminal over serial console, add `console=ttyAMA0,115200` to `cmdline.txt` and `enable_uart=1`, `dtoverlay=pi3-disable-bt` into `config.txt`. GPIO pins are: 6 = GND / 8 = UART TXD / 10 = UART RXD.
|
||||
|
||||
## I2C
|
||||
|
||||
Add `dtparam=i2c1=on` and `dtparam=i2c_arm=on` to `config.txt`. After that we create a module file on host with [config usb stick][config] or direct into `/etc/modules-load.d`.
|
||||
|
||||
rpi-i2c.conf:
|
||||
```
|
||||
i2c-dev
|
||||
i2c-bcm2708
|
||||
```
|
||||
|
||||
## USB Boot
|
||||
|
||||
USB mass storage boot is available on Raspberry Pi 4 (64-bit only), 3B, 3B+, 3A+, and 2B v1.2.
|
||||
|
||||
For Raspberry 3B, 3A+ and 2B v1.2, to enable USB boot, add `program_usb_boot_mode=1` into `config.txt`. Note that this **permanently** alters the one-time programmable memory of the device.
|
||||
|
||||
For Raspberry 4
|
||||
|
||||
* Make sure to update the bootloader to a stable release supporting USB mass storage boot (see [bcm2711_bootloader_config.md](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bcm2711_bootloader_config.md#usbmassstorageboot)).
|
||||
* If no SD card is used add `sd_poll_once=on` to `dtparam` in `config.txt` (comma separated). This gets rid of `mmc0: timeout waiting for hardware interrupt` kernel errors.
|
||||
* If install still fails, then your SSD likely needs quirks enabled to work correctly (see [Finding the VID and PID of your USB SSD](https://www.raspberrypi.org/forums/viewtopic.php?t=245931)). Once you find your adapter's ID, add the quirks parameter in `cmdline.txt`.
|
||||
|
||||
For more information see [RaspberryPi](https://www.raspberrypi.org/documentation/hardware/raspberrypi/bootmodes/msd.md).
|
||||
|
||||
### Caveats
|
||||
|
||||
* All bootable SD cards must be removed.
|
||||
* Boot time can be significantly longer with USB. This is due to the boot process first attempting to boot from SD card, failing, and resorting to USB.
|
||||
* Many USB drives simply do not work for boot. This is likely due to minimal driver support in uboot and will not be fixed. If you can't get it to boot on one drive, try a different brand/model. SanDisk Cruzer drives seem to have a higher rate of issues.
|
||||
|
||||
## Tweaks
|
||||
|
||||
If you don't need bluetooth, disabled it with add `dtoverlay=pi3-disable-bt` into `config.txt`.
|
||||
|
||||
[config]: ../../configuration.md#automatic
|
||||
@ -1,63 +0,0 @@
|
||||
# Configuration
|
||||
|
||||
## Automatic
|
||||
|
||||
You can use an USB drive with HassOS to configure network options, SSH access to the host and to install updates.
|
||||
Format a USB stick with FAT32/EXT4/NTFS and name it `CONFIG` (in all capitals). Alternative you can create a `CONFIG` folder inside the `boot` partition. Use the following directory structure within the USB drive:
|
||||
|
||||
```text
|
||||
network/
|
||||
modules/
|
||||
modprobe/
|
||||
udev/
|
||||
authorized_keys
|
||||
timesyncd.conf
|
||||
hassos-xy.raucb
|
||||
```
|
||||
|
||||
- The `network` folder can contain any kind of NetworkManager connection files. For more information see [Network][network.md].
|
||||
- The `modules` folder is for modules-load configuration files.
|
||||
- The `modprobe` folder is for modules configuration files (/etc/modprobe.d)
|
||||
- The `udev` folder is for udev rules files.
|
||||
- The `authorized_keys` file activates debug SSH access on port `22222`. See [Debugging Home Assistant][debug-homeassistant].
|
||||
- The `timesyncd.conf` file allow you to set different NTP servers. HassOS won't boot without correct working time servers!
|
||||
- The `hassos-*.raucb` file is a firmware OTA update which will be installed. These can be found on on the [release][hassos-release] page.
|
||||
|
||||
Text files that are on USB stick must have Unix (LF) end of line characters. If you create USB stick on Windows machine, be sure to use Notepad++, Visual Studio Code or any other editor, that supports different line endings. In Notepad++ LF EOL can be enabled with setting `Edit -> EOL Conversion -> Unix (LF)`.
|
||||
|
||||
You can put this USB stick into the device and it will be read on startup and files written to the correct places. You can also trigger this process later using `ha os import` from the CLI or by calling `systemctl restart hassos-config` on the OS shell. *The USB Stick just needs to be inserted to the device during this setup process and can be removed afterwards.*
|
||||
|
||||
## Local
|
||||
|
||||
### Bootargs
|
||||
|
||||
You can edit or create a `cmdline.txt` in your boot partition. That will be read from the bootloader.
|
||||
|
||||
### Kernel-Module
|
||||
|
||||
The kernel module folder `/etc/modules-load.d` is persistent and you can add your configuration files there. See [Systemd modules load][systemd-modules]. You can add the modules configuration files in `/etc/modprobe.d` that is also persistent.
|
||||
|
||||
### Udev rules
|
||||
|
||||
The udev rules folder `/etc/udev/rules.d` is persistent and you can add your configuration files there.
|
||||
|
||||
### Network
|
||||
|
||||
You can manual add, edit or remove connections configurations from `/etc/NetworkManager/system-connections`.
|
||||
|
||||
### NTP
|
||||
|
||||
You can manual edit the systemd timesync file on `/etc/systemd/timesyncd.conf`.
|
||||
|
||||
Our default NTP configuration look like:
|
||||
|
||||
```
|
||||
[Time]
|
||||
NTP=time.cloudflare.com
|
||||
FallbackNTP=0.pool.ntp.org 1.pool.ntp.org 2.pool.ntp.org 3.pool.ntp.org
|
||||
```
|
||||
|
||||
[systemd-modules]: https://www.freedesktop.org/software/systemd/man/modules-load.d.html
|
||||
[network.md]: network.md
|
||||
[hassos-release]: https://github.com/home-assistant/hassos/releases/
|
||||
[debug-homeassistant]: https://developers.home-assistant.io/docs/operating-system/debugging
|
||||
@ -1,193 +0,0 @@
|
||||
# Network
|
||||
|
||||
Home Assistant Operating System uses NetworkManager to control the host network.
|
||||
|
||||
## Configure network
|
||||
|
||||
By default the device will be in DHCP state.
|
||||
|
||||
Basic network settings can be set through the Supervisor frontend in the System
|
||||
tab. Advanced configurations such as VLAN are also available through the
|
||||
`ha network` CLI command.
|
||||
|
||||
To restore the default configuration the `ha network` CLI command can be used as
|
||||
well:
|
||||
|
||||
```
|
||||
ha network update default --ipv4-method auto
|
||||
```
|
||||
|
||||
If more advanced network settings are required network connection files can be
|
||||
placed on a USB drive and imported to the host as described in
|
||||
[Configuration][configuration-usb].
|
||||
|
||||
## Manual Network Configuration
|
||||
|
||||
If the frontend or `ha network` CLI cannot meet your use case, it is still
|
||||
possible to configure the underlying NetworkManager manually.
|
||||
|
||||
You can read the [NetworkManager manual][nm-manual] or find many configuration
|
||||
examples across the internet. Note that changes to `NetworkManager.conf` are
|
||||
not supported currently, only connection keyfiles are supported. Keep in mind
|
||||
that the system is read-only. If you don't want the IP address to change on
|
||||
every boot, you should modify the UUID property to a generic [UUID4][uuid].
|
||||
Inside the `\CONFIG\network\` directory on the USB drive or SD card, create a
|
||||
file called `my-network` and add the appropriate contents below:
|
||||
|
||||
**NOTE: Please make sure to save this file with UNIX line endings (LF, and not Windows' default CRLF endings). You can do this using Notepad these days!**
|
||||
|
||||
### Default
|
||||
|
||||
A preinstalled connection profile for wired network is active by default:
|
||||
|
||||
```ini
|
||||
[connection]
|
||||
id=Home Assistant OS default
|
||||
uuid=f62bf7c2-e565-49ff-bbfc-a4cf791e6add
|
||||
type=802-3-ethernet
|
||||
llmnr=2
|
||||
mdns=2
|
||||
|
||||
[ipv4]
|
||||
method=auto
|
||||
|
||||
[ipv6]
|
||||
addr-gen-mode=stable-privacy
|
||||
method=auto
|
||||
```
|
||||
|
||||
### Wired connection to the LAN
|
||||
|
||||
```ini
|
||||
[connection]
|
||||
id=my-network
|
||||
uuid=d55162b4-6152-4310-9312-8f4c54d86afa
|
||||
type=802-3-ethernet
|
||||
llmnr=2
|
||||
mdns=2
|
||||
|
||||
[ipv4]
|
||||
method=auto
|
||||
|
||||
[ipv6]
|
||||
addr-gen-mode=stable-privacy
|
||||
method=auto
|
||||
```
|
||||
|
||||
### Wireless LAN WPA/PSK
|
||||
|
||||
```ini
|
||||
[connection]
|
||||
id=my-network
|
||||
uuid=72111c67-4a5d-4d5c-925e-f8ee26efb3c3
|
||||
type=802-11-wireless
|
||||
|
||||
[802-11-wireless]
|
||||
mode=infrastructure
|
||||
ssid=MY_SSID
|
||||
# Uncomment below if your SSID is not broadcasted
|
||||
#hidden=true
|
||||
|
||||
[802-11-wireless-security]
|
||||
auth-alg=open
|
||||
key-mgmt=wpa-psk
|
||||
psk=MY_WLAN_SECRET_KEY
|
||||
|
||||
[ipv4]
|
||||
method=auto
|
||||
|
||||
[ipv6]
|
||||
addr-gen-mode=stable-privacy
|
||||
method=auto
|
||||
```
|
||||
|
||||
### Static IP
|
||||
|
||||
Replace the following configuration:
|
||||
|
||||
```ini
|
||||
[ipv4]
|
||||
method=manual
|
||||
address=192.168.1.111/24;192.168.1.1
|
||||
dns=8.8.8.8;8.8.4.4;
|
||||
```
|
||||
|
||||
For `address`, the value before the semicolon is the IP address and subnet prefix bitlength. The second value (after the semicolon) is the IP address of the local gateway.
|
||||
|
||||
## Tips
|
||||
|
||||
### Reset network
|
||||
|
||||
If you want to reset the network configuration back to the default connection
|
||||
profile using DHCP, use the following commands on the host console:
|
||||
|
||||
```bash
|
||||
# rm -r /mnt/overlay/etc/NetworkManager/system-connections
|
||||
# reboot
|
||||
```
|
||||
|
||||
Home Assistant OS will recreate the default connection profile during boot.
|
||||
|
||||
### Enabling Wi-Fi
|
||||
|
||||
Wi-Fi is discouraged for reliability reasons. However, if you still prefer to use Wi-Fi, you can us the `ha network` command to set up Wi-Fi (example for a Raspberry Pi 4, check `ha network info` to check if your board supports Wi-Fi and the name of the Wi-Fi device):
|
||||
|
||||
```bash
|
||||
ha network update wlan0 --ipv4-method auto --wifi-auth wpa-psk --wifi-mode infrastructure --wifi-ssid "MY-SSID" --wifi-psk MY_PASS
|
||||
````
|
||||
|
||||
### Powersave
|
||||
|
||||
If you have trouble with powersave then apply the following changes:
|
||||
|
||||
```ini
|
||||
[wifi]
|
||||
# Values are 0 (use default), 1 (ignore/don't touch), 2 (disable) or 3 (enable).
|
||||
powersave=0
|
||||
```
|
||||
|
||||
## Using `nmcli` to set a static IPv4 address
|
||||
|
||||
Log into the the Home Assistant OS base system via a console:
|
||||
|
||||
```bash
|
||||
Welcome to Home Assistant
|
||||
homeassistant login:
|
||||
```
|
||||
|
||||
- Login as `root` (no password needed). At the `ha >` prompt, type `login` (as instructed).
|
||||
|
||||
From there you use the `nmcli` configuration tool.
|
||||
|
||||
- `# nmcli con show` will list the "Home Assistant OS default" connection in use.
|
||||
- `# nmcli con show "Home Assistant OS default"` will list all the properties of the connection.
|
||||
|
||||
To start editing the configuration setting for "Home Assistant OS default":
|
||||
|
||||
```bash
|
||||
# nmcli con edit "Home Assistant OS default"
|
||||
```
|
||||
|
||||
To add your static IP address (select 'yes' for manual method);
|
||||
|
||||
```bash
|
||||
nmcli> set ipv4.addresses 192.168.100.10/24
|
||||
Do you also want to set 'ipv4.method' to 'manual'? [yes]:
|
||||
```
|
||||
|
||||
In addition, it's recommended to set the DNS server and the local gateway. For most home routers the DNS server will have the same IP address as the router itself. If you are using Pi-Hole or a third-party DNS system then you can set the DNS server to that.
|
||||
|
||||
```bash
|
||||
nmcli> set ipv4.dns 192.168.100.1
|
||||
nmcli> set ipv4.gateway 192.168.100.1
|
||||
```
|
||||
|
||||
`nmcli> print ipv4` will show you the IPv4 properties of this connection. With `nmcli> save` you will save the changes afterwards.
|
||||
|
||||
If you now view the default connection `cat /etc/NetworkManager/system-connections/default` you should see the method is manual and the address is set.
|
||||
|
||||
Doing a `nmcli con reload` does not always work, so restart the virtual machine or the physical system.
|
||||
|
||||
[nm-manual]: https://networkmanager.dev/docs/api/1.40/manpages.html
|
||||
[configuration-usb]: configuration.md
|
||||
[uuid]: https://www.uuidgenerator.net/version4
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 67 KiB |
Loading…
x
Reference in New Issue
Block a user