From 5763fce26ec519d966f05511e20fe7be312d2d7b Mon Sep 17 00:00:00 2001
From: Abhas Abhinav
Date: Mon, 31 Jan 2022 06:59:50 +0530
Subject: [PATCH] Adds more details for the MH-USB documentations
---
docs/usb/advanced.md | 10 +++
docs/usb/faqs.md | 108 ++++++++++++++++++++++++++
docs/usb/index.md | 24 ++++++
docs/usb/internals.md | 77 ++++++++++++++++++
docs/usb/troubleshooting.md | 0
docs/usb/update.md | 73 +++++++++++++++++
docs/usb/use.md | 5 +-
mkdocs.yml | 4 +-
site/404.html | 42 ++++------
site/css/extra.css | 7 ++
site/index.html | 42 ++++------
site/lc230/index.html | 42 ++++------
site/lc230/troubleshooting/index.html | 46 ++++-------
site/lc230/user-guide/index.html | 42 ++++------
site/le01/index.html | 42 ++++------
site/ledc/index.html | 42 ++++------
site/mhsw/index.html | 42 ++++------
site/search/search_index.json | 2 +-
site/sitemap.xml | 58 +++++++-------
site/sitemap.xml.gz | Bin 216 -> 216 bytes
20 files changed, 448 insertions(+), 260 deletions(-)
create mode 100644 docs/usb/faqs.md
delete mode 100644 docs/usb/troubleshooting.md
diff --git a/docs/usb/advanced.md b/docs/usb/advanced.md
index e69de29..093ebca 100644
--- a/docs/usb/advanced.md
+++ b/docs/usb/advanced.md
@@ -0,0 +1,10 @@
+# Advanced Usage
+
+## Booting from another disk after booting with the MH-USB
+
+## Customising boot parameters for an OS
+
+## Accessing the Grub2 command-line
+
+## Booting Haiku
+
diff --git a/docs/usb/faqs.md b/docs/usb/faqs.md
new file mode 100644
index 0000000..f968b62
--- /dev/null
+++ b/docs/usb/faqs.md
@@ -0,0 +1,108 @@
+# Troubleshooting & FAQs
+
+## Boot Issues
+
+### Help! The MH-USB won't boot!
+
+First don't panic! :)
+
+Try out the following steps:
+
+ 1. If you insert the USB disk into a computer, does it show up?
+
+ A quick way to test this out on a GNU/Linux system would be to run `lsblk`
+ or check `dmesg`.
+
+ 2. If the USB does not get detected, then it could either be an issue with
+ your USB disk. (Or, at times, the USB port / hub.) See if it gets detected
+ in other computers. Or change the USB port. Or try to use it without a USB
+ hub (if you're using one).
+
+ Still nothing? Do write in to us at with
+ "MH-USB" somewhere in the email subject and we'll help you out.
+
+ The [MH-USB discussion forum](https://ask.libre.support/c/usb/) is another
+ option.
+
+ 3. If it does get detected, then try to mount the partition called "MH-USB".
+ It should get mounted just fine on any OS. If you're able to mount this
+ filesystem, check its contents.
+
+ 4. If the contents are okay and readable, then its probably a Grub2 issue.
+ Unless you want to debug it and learn about Grub and Ventoy in this
+ process, that one option.
+
+ Otherwise, a simple solution might be to just
+ backup the contents of the USB disk and re-install the MH-USB software
+ using the scripts included with the source code.
+
+### I'm unable to boot operating system X!
+
+That could happen due to multiple reasons:
+
+ 1. Its possible that the OS image on the disk has errors in it. The easiest
+ way to verify that is to calculate and verify its checksum.
+
+ 2. When using SeaBIOS with Coreboot, it possible that the OS image might not
+ be able to initialise graphics mode and show its internal boot menu. Try
+ pressing the ++tab++ key twice to show boot options.
+
+ 3. Does Ventoy include support for that operating system? The list of
+ supported (ie. tested out) operating systems is available here:
+
+
+If you still face problems, please do post on the [MH-USB discussion
+forum](https://ask.libre.support/c/usb/) so that we can try to debug it
+together.
+
+### I formatted the disk by mistake and now it won't boot!
+
+You can easily recreate the MH-USB on the USB disk (or, for that matter, any
+USB disk out there!) by using the scripts provided with the source code.
+
+## MH-USB Questions
+
+### Can I use it as a portable storage device?
+
+Yes - Sure. The reason the MH-USB partition is formatted as exFAT is so that
+its possible to detect and use it on all operating systems. You can store any
+data on it and use it to transfer files.
+
+!!! warning
+ It is not safe to store important or private or sensitive data on a
+ portable USB disk. Please be careful. Consider encrypting the storage disk
+ if you need to secure the data stored on it.
+
+### Does the MH-USB require upgrades?
+
+Not really. The MH-USB is basically a Grub2 bootable disk which in turn loads
+and boots up operating system images. In case there is a specific bug that
+stops it from working, there isn't any real reason to upgrade Venoty/Grub.
+
+However, if you are interested in contributing to the development effort or
+further customising the MH-USB - that's a good reason to upgrade / update its
+configuration.
+
+### The MH-USB is slow!
+
+Check the [performance benchmarks](/usb/internals/#dd-read-test) for the USB2
+model. Try to replicate them and see if your results come close to it. That
+would indicate a limit of the USB disk's performance.
+
+If you have a USB3 disk and connecting it to a USB2 port, that might result in
+slower transfer speeds as well. Do check that out.
+
+### I really like the 3D printed disk. How do I customise its looks?
+
+Yes sure! By all means. The source code for the 3D printed enclosure is
+included within the MH-USB source code.
+
+If you need help with design, production, customisation or distribution, please
+feel free to reach out.
+
+### Can you send me a USB disk with the OS images I need?
+
+MH-USB variants with custom images would require too much effort - unless what
+you have is a volume requirement (ie. at least 100 units). You can make your
+own custom USB disk very easily by adding the OS images of your choice and
+customising the Grub2 theme.
diff --git a/docs/usb/index.md b/docs/usb/index.md
index bfb6976..aa7df4e 100644
--- a/docs/usb/index.md
+++ b/docs/usb/index.md
@@ -11,6 +11,30 @@ margin-top: 1em;">
Details and rationale for the MH-USB:
+## Screen-share of the MH-USB
+
+
+
+## Powered by [Ventoy](https://ventoy.net)
+
+The main component of the MH-USB disk is the Ventoy bootloader - derived from Grub2.
+
+
+
+- Website:
+- Source code:
+- Documentation:
+- License: **GPLv3+** -
+
## Operating Systems
By default, the following operating systems are available for live boot or
diff --git a/docs/usb/internals.md b/docs/usb/internals.md
index e69de29..922bc7c 100644
--- a/docs/usb/internals.md
+++ b/docs/usb/internals.md
@@ -0,0 +1,77 @@
+# MH-USB Internals
+
+## MH-USB Performance
+
+### USB2 Version
+
+From
+
+> USB 2.0 has a theoretical maximum signaling rate of 480 Mbits/s or 60
+> Mbytes/s. However due to various constraints the maximum throughput is
+> restricted to around 280 Mbit/s or 35 Mbytes/s.
+
+#### `hdparm` tests
+
+``` console
+$ sudo hdparm -Ttv /dev/sde1
+/dev/sde1:
+ multcount = 0 (off)
+ readonly = 0 (off)
+ readahead = 256 (on)
+ geometry = 15600/64/32, sectors = 31881176, start = 2048
+ Timing cached reads: 16422 MB in 2.00 seconds = 8221.42 MB/sec
+ Timing buffered disk reads: 64 MB in 3.01 seconds = 21.28 MB/sec
+```
+
+#### `dd` write test
+
+``` console
+$ dd if=/dev/zero of=perf oflag=direct bs=128k count=8k
+8192+0 records in
+8192+0 records out
+1073741824 bytes (1.1 GB, 1.0 GiB) copied, 6.94198 s, 155 MB/s
+```
+
+#### `dd` read test
+
+``` console
+## Clear the memory cache before benchmarking reads
+$ sudo sh -c "sync && echo 3 > /proc/sys/vm/drop_caches"
+$ dd if=perf of=/dev/null bs=4k
+262144+0 records in
+262144+0 records out
+1073741824 bytes (1.1 GB, 1.0 GiB) copied, 44.5847 s, 24.1 MB/s
+```
+### USB3 Version
+
+*Coming soon!*
+
+## The MH-USB partition layout
+
+### The Ventoy partion layout
+
+*Document how Ventoy creates partitions for both GPT and MBR partition tables*
+
+### The 16 GB model
+
+*Standard ventoy partitions*
+
+### The 32 GB model
+
+*Coming soon! (special partitions to accommodate haiku.)*
+
+## Using the MH-USB Source Code
+
+### Overview of the source code
+
+### The scripts
+
+#### `download-images.sh`
+
+#### `prepare-usb.sh`
+
+#### `qemu-*.sh`
+
+### Installing MH-USB
+
+### Customising the MH-USB
diff --git a/docs/usb/troubleshooting.md b/docs/usb/troubleshooting.md
deleted file mode 100644
index e69de29..0000000
diff --git a/docs/usb/update.md b/docs/usb/update.md
index e69de29..43bbb7a 100644
--- a/docs/usb/update.md
+++ b/docs/usb/update.md
@@ -0,0 +1,73 @@
+# Adding / Updating Images on the MH-USB Disk
+
+## How do OS images get listed on the boot screen?
+
+Recall the MH-USB directory layout:
+
+```
+MH-USB/
+ /OS/ <-- Contains OS Images
+ /Tools/ <-- Contains some tools and software
+ /RPi/ <-- OS Images for the Raspberry Pi
+ /ventoy/ <-- Config files for the Ventoy/Grub2 bootloader
+```
+
+While the operating system images are stored in the `/OS/` directory in the
+root of the USB disk, the actual display and order of display is controlled by
+the ventoy config file: `/ventoy/ventoy.json`.
+
+An excerpt from the `ventoy.json` config file:
+
+``` json
+{
+ "menu_alias":[
+ {
+ "image": "/OS/debian-live-11.2.0-amd64-cinnamon.iso",
+ "alias": "Debian 11.2.0 (Live)"
+ },
+ {
+ "image": "/OS/devuan_chimaera_4.0.0_amd64_desktop-live.iso",
+ "alias": "Devuan Chimaera 4.0.0"
+ },
+ {
+ "image": "/OS/guix-system-install-1.3.0.x86_64-linux.iso",
+ "alias": "Guix System Installer 1.3.0"
+ },
+ {
+ "image": "/OS/LibreELEC-Generic.x86_64-10.0.1.img",
+ "alias": "LibreELEC 10.0.1 (Live)"
+ }
+ ]
+}
+```
+
+The image would get listed on the boot screen in the alphabetical order even
+without this configuration. However, in the absence of this, the file name of
+the ISO image would show up instead of a more useful OS description.
+
+## Adding, updating and removing a OS image
+
+### Removing an image
+
+Don't think you're likely to use an OS image that exists on the USB
+disk? No problem. Just go ahead and delete it! It will shop showing up
+on the boot screen and you will also have some free space on the USB
+drive.
+
+### Adding a new image
+
+You can copy a new bootable OS image anywhere on the USB disk. You could
+copy it to the `/OS/` directory to keep things neat. But that's not
+mandatory. You can copy it anywhere.
+
+### Updating an image
+
+Updating an OS image simply the process of deleting an older image file
+and adding the new one.
+
+### Update the Ventoy configuration
+
+If you would like to see a proper descriptive name for your new or
+updated OS image, then you can add or update the corresponding section
+in the `/ventoy/ventoy.json` file.
+
diff --git a/docs/usb/use.md b/docs/usb/use.md
index b6ffa7d..1ec5000 100644
--- a/docs/usb/use.md
+++ b/docs/usb/use.md
@@ -10,7 +10,6 @@ MH-USB/
/Tools/ <-- Contains some tools and software
/RPi/ <-- OS Images for the Raspberry Pi
/ventoy/ <-- Config files for the Ventoy/Grub2 bootloader
- (Important - do not modify!)
```
The MH-USB partition of the USB disk is formatted with [exFAT](https://en.wikipedia.org/wiki/ExFAT).
@@ -67,7 +66,9 @@ This will boot the USB via QEMU and show you the boot screen in a popup window.
### Booting a virtual machine with a UEFI BIOS
If you want to try booting the USB with QEMU with the `tianocore` UEFI BIOS, first install the OVMF
-(Open Virtual Machine Firmware) packages. On Debian and Debian-based distributions run:
+(Open Virtual Machine Firmware) packages.
+
+On Debian and Debian-based distributions run:
``` shell-session
# apt-get install ovmf
diff --git a/mkdocs.yml b/mkdocs.yml
index 080a6ab..3dffb74 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -40,8 +40,8 @@ nav:
- (MHUSB) Using the USB disk: usb/use.md
- (MHUSB) Add / Update images: usb/update.md
- (MHUSB) Internals: usb/internals.md
- - (MHUSB) Advanced Options: usb/advanced.md
- - (MHUSB) Troubleshooting: usb/troubleshooting.md
+ #- (MHUSB) Advanced Options: usb/advanced.md
+ - (MHUSB) FAQs: usb/faqs.md
- Routers:
- Introduction: routers/index.md
- First Use: routers/first-use.md
diff --git a/site/404.html b/site/404.html
index 3385da2..793b56f 100644
--- a/site/404.html
+++ b/site/404.html
@@ -12,8 +12,8 @@
-
-
+
+
@@ -28,7 +28,7 @@
-
+
@@ -53,7 +53,7 @@
-
+
@@ -74,7 +74,7 @@