home-assistant · sairon · Aug 6, 2025 · Aug 6, 2025
diff --git a/docs/operating-system/boards/asus.md b/docs/operating-system/boards/asus.md
@@ -0,0 +1,34 @@
+---
+title: "Asus Tinker Board"
+sidebar_label: Asus Tinker Board
+---
+
+## Supported Hardware
+
+| Device         | Release Date  | Support | Config   |
+|----------------|---------------|---------|----------|
+| Tinker RK3288  | April 2017    | yes     | [tinker](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/tinker_defconfig) |
+| Tinker S RK3288| January 2018  | yes     | [tinker](https://github.com/home-assistant/operating-system/tree/dev/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.
diff --git a/docs/operating-system/boards/generic-aarch64.md b/docs/operating-system/boards/generic-aarch64.md
@@ -0,0 +1,39 @@
+---
+title: "Generic AArch64"
+sidebar_label: 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](https://github.com/home-assistant/operating-system/tree/dev/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
diff --git a/docs/operating-system/boards/generic-x86-64.md b/docs/operating-system/boards/generic-x86-64.md
@@ -0,0 +1,65 @@
+---
+title: "Generic x86-64"
+sidebar_label: 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](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
+| Intel NUC6CAYH        | Q4 2016      | yes     | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
+| Intel NUC6CAYS        | Q4 2016      | yes     | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
+| Intel NUC7i3DNHE	| Q3 2017      | yes     | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
+| Intel NUC10i3FNK2     | Q4 2019      | yes     | [generic_x86_64](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/generic_x86_64_defconfig) |
+| 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) |
+
+\* 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 *https://github.com/home-assistant/operating-system/tree/dev/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
diff --git a/docs/operating-system/boards/hardkernel.md b/docs/operating-system/boards/hardkernel.md
@@ -0,0 +1,31 @@
+---
+title: "Hardkernel boards"
+sidebar_label: Hardkernel boards
+---
+
+## Supported Hardware
+
+| Device         | Release Date  | Support      | Config    |
+|----------------|---------------|--------------|-----------|
+| ODROID-C2      | 2016          | yes          | [odroid_c2](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_c2_defconfig) |
+| ODROID-C4      | 2020          | yes          | [odroid_c4](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_c4_defconfig) |
+| ODROID-M1      | 2022          | yes          | [odroid_m1](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_m1_defconfig) |
+| ODROID-M1S     | 2023          | yes          | [odroid_m1s](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_m1s_defconfig)|
+| ODROID-N2      | 2019          | yes          | [odroid_n2](https://github.com/home-assistant/operating-system/tree/dev/buildroot-external/configs/odroid_n2_defconfig) |
+| ODROID-XU4     | 2015          | yes          | [odroid_xu4](https://github.com/home-assistant/operating-system/tree/dev/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.
diff --git a/docs/operating-system/boards/odroid-c2.md b/docs/operating-system/boards/odroid-c2.md
@@ -0,0 +1,25 @@
+---
+title: "Hardkernel ODROID-C2"
+sidebar_label: 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).
diff --git a/docs/operating-system/boards/odroid-c4.md b/docs/operating-system/boards/odroid-c4.md
@@ -0,0 +1,19 @@
+---
+title: "Hardkernel ODROID-C4"
+sidebar_label: 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).
diff --git a/docs/operating-system/boards/odroid-m1.md b/docs/operating-system/boards/odroid-m1.md
@@ -0,0 +1,53 @@
+---
+title: "Hardkernel ODROID-M1"
+sidebar_label: 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/
diff --git a/docs/operating-system/boards/odroid-m1s.md b/docs/operating-system/boards/odroid-m1s.md
@@ -0,0 +1,61 @@
+---
+title: "Hardkernel ODROID-M1S"
+sidebar_label: 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
diff --git a/docs/operating-system/boards/odroid-n2.md b/docs/operating-system/boards/odroid-n2.md
@@ -0,0 +1,21 @@
+---
+title: "Hardkernel ODROID-N2"
+sidebar_label: 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.
diff --git a/docs/operating-system/boards/odroid-xu4.md b/docs/operating-system/boards/odroid-xu4.md
@@ -0,0 +1,32 @@
+---
+title: "Hardkernel ODROID-XU4"
+sidebar_label: 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).