Abhas Abhinav
2 years ago
20 changed files with 448 additions and 260 deletions
Split View
Diff Options
-
+10 -0docs/usb/advanced.md
-
+108 -0docs/usb/faqs.md
-
+24 -0docs/usb/index.md
-
+77 -0docs/usb/internals.md
-
+0 -0docs/usb/troubleshooting.md
-
+73 -0docs/usb/update.md
-
+3 -2docs/usb/use.md
-
+2 -2mkdocs.yml
-
+14 -28site/404.html
-
+7 -0site/css/extra.css
-
+14 -28site/index.html
-
+14 -28site/lc230/index.html
-
+16 -30site/lc230/troubleshooting/index.html
-
+14 -28site/lc230/user-guide/index.html
-
+14 -28site/le01/index.html
-
+14 -28site/ledc/index.html
-
+14 -28site/mhsw/index.html
-
+1 -1site/search/search_index.json
-
+29 -29site/sitemap.xml
-
BINsite/sitemap.xml.gz
+ 10
- 0
docs/usb/advanced.md
View File
| @ -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 | |||
+ 108
- 0
docs/usb/faqs.md
View File
| @ -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 <guide@mostlyharmless.io> 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: | |||
| <https://www.ventoy.net/en/isolist.html> | |||
| 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. | |||
+ 24
- 0
docs/usb/index.md
View File
+ 77
- 0
docs/usb/internals.md
View File
| @ -0,0 +1,77 @@ | |||
| # MH-USB Internals | |||
| ## MH-USB Performance | |||
| ### USB2 Version | |||
| From <https://www.blackmoreops.com/2017/04/04/usb-and-ssd-drive-speedtest-in-linux/> | |||
| > 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 | |||
+ 0
- 0
docs/usb/troubleshooting.md
View File
+ 73
- 0
docs/usb/update.md
View File
| @ -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. | |||