docs: add some initial more advanced documentationHEADmaster

The primary point of this is to describe installation procedure but we
should also describe basic router usage with NixOS as that ain't
documented elsewhere.

1 files changed, 181 insertions, 0 deletions

diff --git a/docs/install-omnia.adoc b/docs/install-omnia.adoc
new file mode 100644
index 0000000..4c5abac
--- /dev/null
+++ b/docs/install-omnia.adoc
@@ -0,0 +1,181 @@
+= NixOS on Turris Omnia
+
+CAUTION: PCIe devices are not functional right now on the Turris Omnia!
+
+The Turris Omnia is little bit more complex regarding the initial setup compared
+to Turris Mox. One issue is that armv7 builds are not provided by official
+Hydra. The second issue is that there is not a single reasonable installation
+(such as SD card on Turris Mox).
+
+Turris Omnia can be booted either from USB or internal disk or from internal
+MMC. The USB drive is the easies to setup from PCs and thus it is suggested for
+testing NixOS on your Turris Omnia. You can always return to the Turris OS just
+by unplugging the USB drive.
+
+== 1.) Updating U-Boot
+
+The updated U-Boot is required to make Turris Omnia work with NixOS in most
+cases. The reason is that the original U-Boot 2015.10 does not support booting
+from USB or internal drive. The newer Turris Omnia routers have newer U-Boot
+versions but always verify the U-Boot version before you continue by running the
+following command as root on the router:
+
+include::shards/install-uboot.adoc[]
+
+----
+strings /dev/mtd0 | grep 'U-Boot [0-9.]\+'
+----
+
+The minimal suggested version is U-Boot 2022.07.
+
+=== Updating U-Boot on Turris OS
+
+These instructions apply if you have SD card with Turris OS and want to use the
+official way of updating firmware on Turris Mox. The minimal version of Turris
+OS to get new stable version of U-Boot is Turris OS 6.0. Please update the
+Turris OS installation to this version or newer before you continue.
+
+The next step is to install `turris-nor-update` and run it:
+
+----
+opkg update
+opkg install turris-nor-update
+turris-nor-update
+----
+
+This should give you at least U-Boot 2022.07.
+
+=== Updating U-Boot on NixOS
+
+TODO
+
+== 2.) Get tarball with NixOS
+
+The initial system can either be downloaded from Gitlab or build locally. Note
+that version available for download can be pretty old. It is just some version
+that was build with latest commit to the NixTurris repository.
+
+* TODO (we do not have CI builds yet)
+* ./build-tarball.adoc[Documentation on how to build your own tarball]
+
+== 3a.) Boot from USB drive
+
+This is the easies option to get NixOS on Turris Omnia. You can prepare the
+drive in any Linux system and then just plug it into the Omnia.
+
+You should use some reliable and preferably USB 3.0 flash drive or just regular
+SSD drive. The suggested minimal size is 8GB but that is pretty much every USB
+drive on the market right now. You might want to use swap and thus make sure
+that you use some higher quality one as swap can kill cheap flash drives pretty
+fast.
+
+You need to format the USB drive first. The required partition table is GPT. You
+can use only one partition that would be preferably formatted with BTRFS. The
+important thing is to set label `NixTurris` so boot can locate the correct
+partition by it. 
+
+It is up to you which tool are you going to use. The instructions here are going
+to be for GNU Parted. The following shell log should give you an idea of what
+you should do to get the correct layout:
+
+----
+~# parted /dev/sdx
+(parted) mktable gpt
+(parted) mkpart NixTurris 0% 100%
+(parted) set 1 boot on
+(parted) quit
+~# mkfs.btrfs /dev/sdx1
+----
+
+The next step is to unpack the tarball to the USB drive.
+
+----
+~# mkdir -p mnt
+~# mount /dev/sdx1 mnt
+~# tar -xf nixos-system-armv7-linux.tar.xz -C mnt
+~# umount mnt
+~# eject /dev/sdx
+----
+
+Now you can take this drive and plug it in the Turris Omnia. The last step is to
+instruct firmware to boot from USB.
+
+TIP: If you have USB to serial converter (see
+https://docs.turris.cz/hw/serial/#turris-omnia[official documentation]) then you
+can trigger USB boot only once using it. You have to reboot Omnia and halt boot
+process by pressing kbd:[Enter] few times once you see `U-Boot` booting. You
+should get U-Boot prompt shortly after (the line starting with `> `). USB boot
+is initialized by entering `run usb_boot` to it and confirming by kbd:[Enter].
+
+You need to have `uboot-envtools` package installed on Turris OS or `ubootTools`
+on NixOS.
+
+First you have to verify your environment access configuration by printing the
+current environment using `fw_printenv` (as root). You should get output with no
+message informing you about invalid CRC. Do not proceed if you get it.
+
+To set USB boot as a preferred method run:
+
+----
+fw_setenv boot_targets usb0 mmc0 nvme0 scsi0 pxe dhcp
+----
+
+Feel free to validate settings by running `fw_printenv` again.
+
+Now you can reboot your Omnia to NixOS. The next step is to do first
+configuration and for that you have to be able to ./initial-access.adoc[access
+the router].
+
+== 3b.) Install on internal storage
+
+It is highly suggested not to use internal MMC for the whole system. The
+suggested deployment is rather the `/boot` partition on MMC or the whole system
+on internal drive (note that U-Boot might not be able to boot from all internal
+drives).
+
+TODO
+
+WARNING: this is not fully supported at the moment as tarball contains in
+`/boot` only Syslinux configuration and thus boot simply from `/boot` is not
+possible. You have to copy kernel, initrd and dtb to the `/boot` partition and
+modify Syslinux's configuration file.
+
+
+== Reverting to Turris OS
+
+The steps required to revert to Turris OS differ from how deep have you went
+with installation. If you are lucky it is just about restarting U-Boot
+environment, if not then you have to use Medkit to install Turris OS back.
+
+=== Resetting U-Boot environment to the default
+
+The modification suggested by this document are only to the single variable
+(`boot_targets`). The revert to the previous value should be in most cases
+enough. This can be done by (see previous usage in this document for required
+packages):
+
+----
+fw_setenv boot_targets mmc0 nvme0 scsi0 usb0 pxe dhcp
+----
+
+You can also reset environment to the default if you want to be sure. For that
+you need USB to serial converter connected (see
+https://docs.turris.cz/hw/serial/#turris-omnia[official documentation]). Reboot
+the board and halt boot process by pressing kbd:[Enter] few times once you see
+`U-Boot` booting. You should get U-Boot prompt shortly after (the line starting
+with `> `). To reset environment enter:
+
+----
+env default -a
+saveenv
+----
+
+To continue boot you can enter command `boot`.
+
+=== Using Medkit to install Turris OS back to the MMC
+
+You have to do this only if you attempted installation on internal storage.
+First you have to reset U-Boot environment and thus follow steps in the previous
+section. Next follow the
+https://docs.turris.cz/hw/omnia/rescue-modes/#re-flash-router[official medkit
+steps].