github
/
ha-operating-system
mirror of https://github.com/home-assistant/operating-system
1
Fork 0
Code Releases Activity

Remove developer documentation (#1580) 

Remove developer documentation in favor of the developer docs website.
This commit is contained in:
Stefan Agner 2021-10-21 16:57:01 +02:00 committed by GitHub
parent b72acfa648
commit c7ec9468c0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 14 additions and 269 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
Documentation/README.md
View File

@ -1,12 +1,8 @@
# Developer Documentation
# Documentation
## Contents
- [Getting started](./getting_started_development.md) - the place for developers to begin
- [Development](./development.md) - more details for developers
- [Deployment](./deployment.md) - approach to git branching and releases
- [Configuration](./configuration.md) - how users can configure HassOS
- [Partition](./partition.md) - partition layout
- [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

22
Documentation/deployment.md
View File

@ -1,22 +0,0 @@
# Deployment
We provide 3 different types of release builds:
- development (dev)
- staging (beta)
- production (stable)
## Versioning
The format of version is *MAJOR.BUILD*. Everytime we create a new release with same userland, we bump the build number.
The development number they will be bump for the stable release version and the development version go to next major number.
## Git branch/Tag
The branch `dev` ist the actual development branch and from there we never make a release. The `master` branch contains the development version and from there we build a beta release.
If we create a new productive/staging release, we create a new branch `rel-{MAJOR}`. They will be used for the whole cycle of this release.
## Upload release files
We use [ghr](https://github.com/tcnksm/ghr) to upload files to our repository. A binary version is available inside `scripts`.

60
Documentation/development.md
View File

@ -1,60 +0,0 @@
# Development
## Boot system
`BOOT_SYS`:
- efi
- hybrid
- mbr
HassOS is using GPT. But to use GPT we need own the first 1024 of boot drive. Is that's not possible, you can use MBR for your device. This also work with SPLs.
Hybrid and SPL use both a hybrid MBR/GPT table but SPL move the GPT header 8 MB for give space to write SPL and boot images before.
`BOOT_SPL`:
- true
- false
Enable SPL update handling.
`BOOTLOADER`:
- U-Boot
- barebox
We support mainly U-Boot but for UEFI systems we can also use [barebox](https://barebox.org/). In the future, we hope to remove barebox with U-Boot also on UEFI.
`DISK_SIZE`:
Default 2. That is the size of end image in GB.
## Supervisor
`SUPERVISOR_MACHINE`:
- intel-nuc
- odroid-c2
- odroid-c4
- odroid-n2
- odroid-xu
- qemuarm
- qemuarm-64
- qemux86
- qemux86-64
- raspberrypi
- raspberrypi2
- raspberrypi3
- raspberrypi4
- raspberrypi3-64
- raspberrypi4-64
- tinker
`SUPERVISOR_ARCH`:
- amd64
- i386
- armhf
- armv7
- aarch64

101
Documentation/getting_started_development.md
View File

@ -1,101 +0,0 @@
# Getting started with HassOS development using Docker on GNU/Linux
First, install `docker-ce` for your distribution. I'd advise to use your distro's provided packages, since that will make sure permissions et al. are sanely set up for what you are about to run. You're also expected to have your current user properly set up in in your sudoers policy, so that this account may elevate to root and execute arbitrary commands as UID 0 (this is required, since at some point during the build process, a new loopback device-backed filesystem image will be mounted inside a Docker container - which requires a "privileged" container to run, which can only be done as root).
Next, make sure the Docker daemon is running:
```bash
$ sudo systemctl status docker
● docker.service - Docker Application Container Engine
Loaded: loaded (/usr/lib/systemd/system/docker.service; disabled; vendor preset: disabled)
Active: inactive (dead)
Docs: https://docs.docker.com
```
My desktop distro doesn't start newly installed services by default, which means I'll have to manually fire up the `docker` service:
```bash
$ sudo systemctl start docker
$ sudo systemctl --no-pager status docker -n0
● docker.service - Docker Application Container Engine
Loaded: loaded (/usr/lib/systemd/system/docker.service; disabled; vendor preset: disabled)
Active: active (running) since Wed 2018-10-10 21:08:23 CEST; 25s ago
Docs: https://docs.docker.com
Main PID: 1531 (dockerd)
Tasks: 27 (limit: 4915)
Memory: 163.4M
CGroup: /system.slice/docker.service
├─1531 /usr/bin/dockerd -H fd://
└─1539 docker-containerd --config /var/run/docker/containerd/containerd.toml
```
Now, change your working directory to your home-assistant/operating-system repository checkout (please adapt path names as needed), make sure your intended changes to the source tree are applied (and committed, ideally :)), and execute the `enter.sh` helper script:
```bash
$ cd ~/codebase/operating-system/
$ sudo scripts/enter.sh
Sending build context to Docker daemon 30.48MB
Step 1/6 : FROM ubuntu:18.04
[...]
---> 4dc25a21556b
Successfully built 4dc25a21556b
Successfully tagged hassbuildroot:latest
```
Note that the current iteration of `enter.sh` will try to load the **overlayfs** kernel module, which is not strictly required for Docker's operation, as far as I can tell. It's OK if loading that module fails; the shell script will continue executing. If everything works out, you will find yourself in an interactive login shell inside your Docker container/build environment, where you can peek around:
```bash
root@somehashinhex:/build#
root@somehashinhex:/build# make help
[...]
```
The HassOS developers provide a `Makefile` that will build HassOS images for a list of targets. For example run the command below to start building the _ova_ variant, and go make a cup of tea. Or fifteen.
```bash
root@0db6f7079872:/build# make ova
[...]
```
That will result in a single VMDK image file at the very end of the build process. This image file is a compressed block device dump with a proper GPT partition table, prepared to ship into any OVA-compatible hypervisor's innards. For me, the end of the **ova** build steps looks like this:
```bash
[...]
2097152+0 records out
1073741824 bytes (1.1 GB, 1.0 GiB) copied, 12.2145 s, 87.9 MB/s
make: Leaving directory '/build/buildroot'
make: Entering directory '/build/buildroot'
rm -rf /build/buildroot/output/target /build/buildroot/output/images /build/buildroot/output/host \
/build/buildroot/output/build /build/buildroot/output/staging \
/build/buildroot/output/legal-info /build/buildroot/output/graphs
make: Leaving directory '/build/buildroot'
```
The artifacts you just built are placed in the `target/` subdirectory:
```bash
root@fd292c061896:/build# ls -lh release/
total 141M
-rw-r--r-- 1 root root 141M Oct 10 20:22 hassos_ova-2.2.vmdk.gz
```
In order to be able to use this image file with the QEMU hypervisor, you'll need to unpack it, and convert it to an image format that QEMU can work with. Conveniently, the HassOS buildenv already provides all the tools we need for this conversion:
```bash
root@fd292c061896:/build# gunzip release/hassos_ova-2.2.qcow2.gz
root@fd292c061896:/build# ls -lh release/
total 673M
-rw-r--r-- 1 root root 337M Oct 10 20:25 hassos_ova-2.2.qcow2
```
Now, exit the docker container's environment, and find the build artifacts in the `releases/` directory beneath your repository checkout dir. (The generated files will be owned by _root_; make sure to `chown` them to your user account, if needed.)
From there, QEMU can try to boot it. Since the generated image assumes UEFI support in the host/hypervisor, this is slightly more tricky than with "classic"(/legacy) MBR-based images. On the *Debian* host I use to run my QEMU virtual machine on, you'll need to install the **ovmf** package which provides the "UEFI firmware for 64-bit x86 virtual machines". That package will install a **TianoCore**-derived QEMU UEFI image build at `/usr/share/OVMF/OVMF_CODE.fd`, which we'll use with QEMU to boot the generated qcow2 image. (Please adapt path names as necessary, for example if you have installed the ovmf firmware image at another location.)
```bash
$ /usr/bin/qemu-system-x86_64 -enable-kvm -name hassos_ova -smp 2 -m 1024 -drive file=release/hassos_ova-2.2.qcow2,index=0,media=disk,if=ide,cache=none,format=qcow2 -drive file=/usr/share/ovmf/x64/OVMF_CODE.fd,if=pflash,format=raw,readonly=on
```
This should pop up QEMU's SDL frontend, displaying _hassos_' VT/CLI environment. Specifying additional options and flags to QEMU for network access, keyboard layout et al. are left as an exercise for the reader.
After the boot process has finished, you can log in to _hassos_ without a password, providing *root* as the username. From there, executing `login` on the *ha>* shell prompt will yield a root shell in the host OS.

68
Documentation/partition.md
View File

@ -1,68 +0,0 @@
# Partition
The partition layout is a bit different than the typical setup. We prefer GPT, if possible. With SoCs which don't support GPT, we use a hybrid GPT. For more details about this topic, please refer to the [development](development.md) documentation.
The system is designed to have as few write operations to the storage media as possible. This means that we only write during the OTA updates and 5-6 times per week on the overlay partition. The data partition receives the main I/O operations and for this reason is ideal for placing on a different drive.
A visual representation looks like this:
```text
-------------------------
| Bootloader |
-------------------------
| Kernel A |
-------------------------
| System A |
| |
-------------------------
| Kernel B |
-------------------------
| System B |
| |
-------------------------
| Bootstate |
-------------------------
| Overlay |
| |
...
-------------------------
| Data |
| |
-------------------------
```
Sometime the bootloader part can look different because there can be firmware or SPLs for boot the CPU on the SoC.
## Data disk
![Data-Disk preview](./usb-disk.png)
The data partition is the only partition with real I/O. It will be expanded automatically at boot to the full size of the disk.
## Using CLI to move the data partition.
In a Home Assistant OS installation, the data is stored on the `/mnt/data` partition of the boot storage (typically the SD card). This is the only read/write partition on the boot storage. Using the `datadisk` move command, this partition can be moved to an externally connected drive, leaving the rest of the read-only system on the boot storage.
The storage capacity of the external drive must be larger than the storage capacity of the existing disk.
```sh
$ ha os datadisk move /dev/sdx
```
This will make a reboot which going significantly longer than usual; please be patient!
For getting a list of supported detected devices which can be used by `datadisk`:
```sh
$ ha os datadisk list
```
## Using UI to move the data partition.
__follow__
## Check Power Supply Rating
Using an USB attached SSD can draw quite some power. For instance on Raspberry Pi 3 the official Raspberry Pi power supply (PSU) only provides 2.5A which can be too tight. Use a power supply which can at least provide 3.5A. Alternatively use a powered USB hub. Connect the Hub to one of the USB slots of your Raspberry Pi, and connect the SSD to the Hub. The power supply that came with the Hub will power the attached device(s).

24
README.md
View File

@ -1,8 +1,8 @@
# Home Assistant Operating System
Home Assistant Operating System (formerly HassOS) is an operating system optimized for hosting [Home Assistant](https://www.home-assistant.io) and its [Add-ons](https://www.home-assistant.io/addons/).
Home Assistant Operating System (formerly HassOS) is a Linux based operating system optimized to host [Home Assistant](https://www.home-assistant.io) and its [Add-ons](https://www.home-assistant.io/addons/).
Home Assistant Operating System uses Docker as Container engine. It by default deploys the Home Assistant Supervisor as a container. Home Assistant Supervisor in turn uses the Docker container engine to control Home Assistant Core and Add-Ons in separate containers. Home Assistant Operating System is **not** based on a regular Linux distribution like Ubuntu. It is built using [buildroot](https://buildroot.org/) and it is optimized for running Home Assistant, especially on single board compute (SBC) devices like the Pi, ODROID, NUC and Tinker Board (see supported hardware below).
Home Assistant Operating System uses Docker as Container engine. It by default deploys the Home Assistant Supervisor as a container. Home Assistant Supervisor in turn uses the Docker container engine to control Home Assistant Core and Add-Ons in separate containers. Home Assistant Operating System is **not** based on a regular Linux distribution like Ubuntu. It is built using [Buildroot](https://buildroot.org/) and it is optimized to run Home Assistant. It targets single board compute (SBC) devices like the Raspberry Pi or ODROID but also supports x86-64 systems with UEFI.
## Features
@ -10,7 +10,7 @@ Home Assistant Operating System uses Docker as Container engine. It by default d
- Minimized I/O
- Over The Air (OTA) updates
- Offline updates
- Modular using Docker
- Modular using Docker container engine
## Supported hardware
@ -28,11 +28,17 @@ If you just want to use Home Assistant the official [getting started guide](http
If you're interested in finding out more about Home Assistant Operating System and how it works read on...
## HassOS components
## Development
If you don't have experience with embedded systems, Buildroot or the build process for Linux distributions it is recommended to read up on these topics first (e.g. [Bootlin](https://bootlin.com/docs/) has excellent resources).
The Home Assistant Operating System documentation can be found on the [Home Assistant Developer Docs website](https://developers.home-assistant.io/docs/operating-system).
### Components
- **Bootloader:**
- [Barebox](https://barebox.org/) for devices that support EFI
- [U-Boot](https://www.denx.de/wiki/U-Boot) for devices that don't support EFI
- [Barebox](https://barebox.org/) for devices that support UEFI
- [U-Boot](https://www.denx.de/wiki/U-Boot) for devices that don't support UEFI
- **Operating System:**
- [Buildroot](https://buildroot.org/) LTS Linux
- **File Systems:**
@ -45,12 +51,6 @@ If you're interested in finding out more about Home Assistant Operating System a
- **Security:**
- [AppArmor](https://apparmor.net/) Linux kernel security module
If you don't have experience with these, embedded systems, buildroot or the build process for Linux distributions, then please read up on these topics. The rest of the documentation in this project is for developers and assumes you have experience with embedded systems or a strong understanding of the internal workings of operating systems.
## Developer Documentation
All developer documentation is in the [Documentation](./Documentation) directory.
### Development builds
The Development build GitHub Action Workflow is a manually triggered workflow