Skip to content

Commit cb8bec6

Browse files
saironsairon
authored
Migrate HAOS docs from the OS repo (#2748)
1 parent 2f76134 commit cb8bec6

File tree

16 files changed

+806
-0
lines changed

16 files changed

+806
-0
lines changed

‎docs/operating-system/boards/asus.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: "Asus Tinker Board"
3+
sidebar_label: Asus Tinker Board
4+
---
5+
6+
## Supported Hardware
7+
8+
| Device | Release Date | Support | Config |
9+
|----------------|---------------|---------|----------|
10+
| Tinker RK3288 | April 2017 | yes | [tinker](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/tinker_defconfig) |
11+
| Tinker S RK3288| January 2018 | yes | [tinker](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/tinker_defconfig) |
12+
| Tinker Edge T | November 2019 | no? | |
13+
| Tinker Edge R | November 2019 | no? | |
14+
15+
## eMMC
16+
17+
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.
18+
19+
The Home Assistant OS provided U-Boot does support UMS as well,
20+
however manual intervention is necessary:
21+
22+
1. Set the jumper between Micro-USB and HDMI the maskrom mode
23+
2. Insert SD card and connect the board via Micro-USB to your PC
24+
3. Continusly press Ctrl+C to interrupt boot
25+
4. Set the jumper back to the park position
26+
5. Start UMS using:
27+
```
28+
ums 0 mmc 0
29+
```
30+
6. A mass storage device should appear. Flash Home Assistant OS to it.
31+
32+
## Serial console
33+
34+
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.

‎docs/operating-system/boards/generic-aarch64.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: "Generic AArch64"
3+
sidebar_label: Generic AArch64
4+
---
5+
6+
## Supported Hardware
7+
8+
This board configuration aims to support most aarch64 systems with UEFI boot
9+
Hardware it has been tested with is listed below.
10+
11+
## Tested Hardware
12+
13+
| Device | Release Date | Support | Config |
14+
|-----------------------|--------------|---------|-------------|
15+
| QEMU | QEMU | yes | [generic_aarch64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_aarch64_defconfig) |
16+
17+
18+
## Requirements
19+
20+
- aarch64 support
21+
- UEFI boot
22+
23+
## Wifi
24+
25+
WiFi is untested.
26+
27+
## Bluetooth
28+
29+
Bluetooth is untested.
30+
31+
## Installation
32+
33+
Make sure secure boot is disabled in the UEFI BIOS settings.
34+
35+
Currently there is no shiny installation method. Checklist:
36+
- Boot PC to live environment using PXE or USB
37+
- Copy or download the Home Assistant OS image into your live environment
38+
- unxz the image and dd to the local hard disk
39+
- Reboot

‎docs/operating-system/boards/generic-x86-64.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: "Generic x86-64"
3+
sidebar_label: Generic x86-64
4+
---
5+
6+
## Supported Hardware
7+
8+
This board configuration aims to support most x86-64 systems with UEFI boot. The
9+
main aim is to support Intel NUC mini PCs and similar systems. Hardware it has
10+
been tested with is listed below.
11+
12+
## Tested Hardware
13+
14+
| Device | Release Date | Support | Config |
15+
|-----------------------|--------------|---------|-------------|
16+
| Intel NUC5CPYH | Q3 2015 | yes | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
17+
| Intel NUC6CAYH | Q4 2016 | yes | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
18+
| Intel NUC6CAYS | Q4 2016 | yes | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
19+
| Intel NUC7i3DNHE | Q3 2017 | yes | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
20+
| Intel NUC10i3FNK2 | Q4 2019 | yes | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
21+
| Gigabyte GB-BPCE-3455 | 2017 | yes* | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
22+
23+
\* needs 'nomodeset' in cmdline.txt if you want a console
24+
25+
26+
## Requirements
27+
28+
- x86-64 support
29+
- UEFI boot
30+
- SATA/AHCI or eMMC storage
31+
- Supported NIC:
32+
- Intel Gigabit NIC (e1000, igb - via Linux mainline)
33+
- Intel PCIe Gigabit NIC (e1000e - via out-of-tree module in *https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/package/intel-e1000e*)
34+
- Realtek Gigabit NIC (r8169)
35+
- Intel Wireless Wifi 802.11ac (iwlwifi, see below)
36+
37+
## Wifi
38+
39+
The following cards are supported:
40+
41+
- Intel Wireless 3160
42+
- Intel Wireless 7260
43+
- Intel Wireless 7265
44+
- Intel Wireless-AC 3165
45+
- Intel Wireless-AC 3168
46+
- Intel Wireless-AC 8260
47+
- Intel Wireless-AC 8265
48+
- Intel Wireless-AC 9260
49+
- Intel Wireless-AC 9461
50+
- Intel Wireless-AC 9462
51+
- Intel Wireless-AC 9560
52+
53+
## Bluetooth
54+
55+
Bluetooth integrated in Intel Wireless cards working OK, other options untested.
56+
57+
## Installation
58+
59+
Make sure secure boot is disabled in the UEFI BIOS settings.
60+
61+
Currently there is no shiny installation method. Checklist:
62+
- Boot PC to live environment using PXE or USB
63+
- Copy or download the Home Assistant OS image into your live environment
64+
- unxz the image and dd to the local hard disk
65+
- Reboot

‎docs/operating-system/boards/hardkernel.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
title: "Hardkernel boards"
3+
sidebar_label: Hardkernel boards
4+
---
5+
6+
## Supported Hardware
7+
8+
| Device | Release Date | Support | Config |
9+
|----------------|---------------|--------------|-----------|
10+
| ODROID-C2 | 2016 | yes | [odroid_c2](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_c2_defconfig) |
11+
| ODROID-C4 | 2020 | yes | [odroid_c4](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_c4_defconfig) |
12+
| ODROID-M1 | 2022 | yes | [odroid_m1](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_m1_defconfig) |
13+
| ODROID-M1S | 2023 | yes | [odroid_m1s](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_m1s_defconfig)|
14+
| ODROID-N2 | 2019 | yes | [odroid_n2](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_n2_defconfig) |
15+
| ODROID-XU4 | 2015 | yes | [odroid_xu4](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_xu4_defconfig)|
16+
17+
See separate documentation for each board.
18+
19+
## Connectivity devices
20+
21+
### Wi-Fi
22+
23+
The following devices have been tested on Home Assistant OS 5.8:
24+
25+
- [Bluetooth Module 2](https://www.hardkernel.com/shop/bluetooth-module-2/)
26+
- [WiFi Module 3](https://www.hardkernel.com/shop/wifi-module-3/)
27+
28+
The [WiFi Module 5A](https://www.hardkernel.com/shop/wifi-module-5a/) is not
29+
recommended as there is no upstream driver support available. The driver
30+
currently compatible with recent Linux kernel version seems to have issues
31+
connecting to 5GHz networks.

‎docs/operating-system/boards/odroid-c2.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
---
2+
title: "Hardkernel ODROID-C2"
3+
sidebar_label: ODROID-C2
4+
---
5+
6+
## eMMC
7+
8+
eMMC support is provided transparently. Just flash the image to the eMMC board as you would an SD card.
9+
10+
## Console
11+
12+
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.
13+
eg. `console=ttyAML0,115200n8 console=tty0`
14+
15+
## USB
16+
17+
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.
18+
19+
### OTG
20+
21+
The OTG USB is untested.
22+
23+
## GPIO
24+
25+
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-c2/hardware/expansion_connectors).

‎docs/operating-system/boards/odroid-c4.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
title: "Hardkernel ODROID-C4"
3+
sidebar_label: ODROID-C4
4+
---
5+
6+
## Experimental
7+
8+
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.
9+
10+
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.
11+
12+
Common C4 issues that have been specifically tested and appear to be working:
13+
- boot from SD
14+
- boot from eMMC
15+
- MAC address obtained from eFuse
16+
17+
## GPIO
18+
19+
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-c4/hardware/expansion_connectors).

‎docs/operating-system/boards/odroid-m1.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
---
2+
title: "Hardkernel ODROID-M1"
3+
sidebar_label: ODROID-M1
4+
---
5+
6+
Home Assistant OS 10 and newer support the ODROID-M1 board.
7+
8+
## SD-card
9+
10+
SD-card boot is supported via on-board bootloader (SPL) or recovery button.
11+
12+
## eMMC
13+
14+
eMMC boot via on-board bootloader requires a newer version of Petitboot
15+
(spiboot 20230328 or later). To install the latest version download the SPI boot image
16+
from [linuxfactory.or.kr][1] as follows:
17+
18+
1. Download `spiupdate_odroidm1_20240415.img.xz`
19+
2. Use balenaEtcher or another tool to flash the updater onto an SD card
20+
3. Download `spiboot-20240109.img`
21+
4. Rename the `spiboot-20240109.img` file to`spiboot.img`.
22+
5. Paste the `spiboot.img` file onto the FAT partition of that same SD card.
23+
6. Plug-in that SD card to your ODROID-M1. Petitboot will update itself, you can verify the progress on the HDMI output.
24+
7. If you see the version 20240109 in the top left corner, the installation was successful.\
25+
If you see any other version there, the installation failed.
26+
27+
Once Petitboot is updated you can flash Home Assistant OS directly onto an eMMC.
28+
29+
## NVMe
30+
31+
Booting directly from NVMe is not supported. The NVMe card can be used as a data disk.
32+
33+
## Technical notes on boot flow
34+
35+
The Home Assistant OS image is bootable by the SoC directly. This means that no help
36+
from the Hardkernel provided and pre-installed bootloader Petitboot is necessary.
37+
However, the ODROID-M1 automatically boots from internal SPI. To boot
38+
directly off the SD-card or eMMC you need to press the recovery button.
39+
40+
The SPI flashed U-Boot SPL tries searches for an U-Boot binary on the SD-card
41+
(and from eMMC with Petitboot 20230328 and later). This mechanism allows you to
42+
boot the Home Assistant OS U-Boot without pressing the recovery button.
43+
44+
## Console
45+
46+
By default, console access is available on the serial header (CON1) and on HDMI.
47+
The serial console's baudrate is 1500000 by default.
48+
49+
The systemd startup messages will only appear on the serial console by default.
50+
To show the messages on the HDMI console instead, add the console manually
51+
to the `cmdline.txt` file on the boot partition (e.g. `console=tty0`).
52+
53+
[1]: http://ppa.linuxfactory.or.kr/images/petitboot/odroidm1/

‎docs/operating-system/boards/odroid-m1s.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
title: "Hardkernel ODROID-M1S"
3+
sidebar_label: ODROID-M1S
4+
---
5+
6+
Home Assistant OS 12 and newer support the ODROID-M1S board.
7+
8+
## SD-card
9+
10+
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.
11+
12+
## eMMC
13+
14+
HAOS can be installed directly to the eMMC using a special boot image, to do that:
15+
16+
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.
17+
2. Use balenaEtcher or another tool to flash the _UMS utility_ onto an SD card.
18+
3. Plug-in that SD card to your ODROID-M1S and boot it. Connect your PC to the Micro USB OTG port.
19+
4. The eMMC will show as a drive on your PC and you can directly flash the HAOS image with balenaEther.
20+
21+
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.
22+
23+
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:
24+
25+
```sh
26+
curl https://dn.odroid.com/RK3566/ODROID-M1S/Installer/ODROID-M1S_EMMC2UMS.img | dd of=/dev/mmcblk0
27+
```
28+
29+
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.
30+
31+
## NVMe
32+
33+
Booting directly from NVMe is not supported. The NVMe card can be used as a data disk.
34+
35+
## Technical notes on boot flow
36+
37+
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.
38+
39+
## Console
40+
41+
By default, console access is available on the serial header (UART) and on HDMI.
42+
The serial console's baudrate is 1500000 by default.
43+
44+
The systemd startup messages will only appear on the serial console by default.
45+
To show the messages on the HDMI console instead, add the console manually
46+
to the `cmdline.txt` file on the boot partition (e.g. `console=tty0`).
47+
48+
## GPIO
49+
50+
Odroid-M1S introduces a new 14pin expansion header. Refer to [the ODROID wiki][4].
51+
At this point not all functionality is supported by the upstream kernel used by Home Assistant OS.
52+
Supported modules include:
53+
- UPS
54+
- Internal USB
55+
- Mini IO board (partial support)
56+
57+
58+
[1]: https://dn.odroid.com/RK3566/ODROID-M1S/Installer/ODROID-M1S_EMMC2UMS.img
59+
[2]: https://wiki.odroid.com/odroid-m1s/getting_started/os_installation_guide#user_installer
60+
[3]: https://wiki.odroid.com/odroid-m1s/board_support/boot_sequence
61+
[4]: https://wiki.odroid.com/odroid-m1s/hardware/expansion_connectors

‎docs/operating-system/boards/odroid-n2.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: "Hardkernel ODROID-N2"
3+
sidebar_label: ODROID-N2
4+
---
5+
6+
## eMMC
7+
8+
eMMC support is provided transparently. Just flash the image to the eMMC board as you would an SD card.
9+
10+
## Console
11+
12+
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.
13+
eg. `console=ttyAML0,115200n8 console=tty0`
14+
15+
## GPIO
16+
17+
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-n2/hardware/expansion_connectors).
18+
At this point not all functionality is supported by the upstream kernel used
19+
by Home Assistant OS.
20+
21+
The GPIO on pin 11 is used as a low active power button input.

‎docs/operating-system/boards/odroid-xu4.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: "Hardkernel ODROID-XU4"
3+
sidebar_label: ODROID-XU4
4+
---
5+
6+
## eMMC
7+
8+
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:
9+
10+
1. **Working** e.g. the eMMC already had a working image before flashing HassOS:
11+
- It will be booting to U-Boot (but no further).
12+
- If you have the serial adapter, you should be able to enter `distro_bootcmd` at the uboot prompt to continue booting.
13+
- If not, flash the HassOS image to an SD card and boot off that temporarily (while the eMMC is also plugged in).
14+
- 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.
15+
- Reboot with eMMC (don't forget to flip the boot switch to eMMC)
16+
2. **Not Working** e.g. a clean/wiped/corruped eMMC boot partition:
17+
- 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.
18+
- 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..
19+
20+
If you are getting permissions issues when using the dd command, try disabling RO:
21+
`echo 0 > /sys/block/mmcblk0boot0/force_ro`
22+
to re-enable after running dd:
23+
`echo 1 > /sys/block/mmcblk0boot0/force_ro`
24+
25+
## Console
26+
27+
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.
28+
eg. `console=tty1 console=ttySAC2,115200`
29+
30+
## GPIO
31+
32+
Refer to [the odroid wiki](https://wiki.odroid.com/odroid-xu4/hardware/expansion_connectors).

0 commit comments

Comments
 (0)