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. + +
+ + Ventoy + +
+ +- 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 @@