Skip to content

Latest commit

 

History

History
452 lines (332 loc) · 21.6 KB

troubleshooting-and-faqs.md

File metadata and controls

452 lines (332 loc) · 21.6 KB
Raw

License Issues Discord

Logo

Troubleshooting and Support

Common Issues

The instructions are too difficult to follow!

  • ChromeOS is based on linux, most troubleshooting will require some familiarity with basic linux commands. It is strongly suggested that users are comfortable with linux before attempting an installation. If you are strugging with a specific step or would like to suggest changes to the guide, please reach out to our community for assistance.

Discord

I followed a video tutorial, now I'm having issues.

  • Video guides are very frequently out of date or use potentially dangerous scripts. For the most up to date information and guides, be sure to read over this github page thouroughly before asking for help.

My computer will not boot a Brunch USB, and I've followed all of the instructions correctly!

  • Some devices (notably Surface Go) will not boot a valid USB flash drive / SD card with secure boot on even if the shim binary is signed. For those devices, you will need to disable secure boot in your bios settings and use the legacy EFI bootloader by adding the -l parameter when running the chromeos-install.sh script.

The first boot and the ones after a framework change or an update are incredibly long!

  • Unfortunately, the Brunch framework has to rebuild itself by copying the original rootfs, modules and firmware files after each significant change. The time this process takes depends mostly on your USB flash drive / SD card write speed. You may try with one that has better write speed or use the dual boot method to install it on your HDD.

ChromeOS reboots randomly!

  • This can in theory be due to a lot of things. However, the most likely reason is that your USB flash drive / SD card is too slow. You may try with one that has better write speed or use the dual boot method to install it on your HDD.

Some apps, like Netflix, do not appear on the playstore or don't run properly!

  • In order to have access to the ChromeOS shell, ChromeOS is started in developer mode by default. If you have a stable enough system, you can manually remove cros_debug from grub.cfg on the 12th partiton and then do a Powerwash (ChromeOS mechanism which will wipe all your data partition) to disable developer mode. This will remove access to the Crosh shell and certain other features though.

Some android apps on the Playstore show as incompatible with my device!

  • Some Playstore apps are not compatible with genuine Chromebooks so this is probably normal. ChromeOS is not Android, so some apps and games are not optimized or avaliable.

A new update is avaliable, is it safe to update?

  • ChromeOS updates can be unpredictable, especially on Brunch devices. Even if it's declared safe by other users, you should always have backups ready in case there is an issue while updating or if the update has serious bugs on your hardware.

My Touchpad, Touchscreen, Wifi or other hardware is not working properly!

  • ChromeOS is not optimized for every device. Brunch has several avaliable framework options and multiple customized kernels avaliable further down on this page to help with these issues. If you're still having issues, you can reach out to other users on one of our communities for help.

Grub doens't appears on the boot options

  • Some older devices (usually Acer, Asus and Samsung) can't detect Brunch's Grub. To solve this, you can manually assign grub on the BIOS but if your bios doesn't have this option you can use efibootmgr to create a boot entry for grub.

Discord

Brunch Configuration Menu

The Brunch Configuration menu is a new feature avaliable in Brunch 93 and higher, this menu will allow users to set and controll options easily without needing to manually edit files themselves.

How to Use

Click for Screenshots and Instructions

The Brunch Configuration Menu can be accessed directly from Grub using the "ChromeOS (settings)" boot option or while logged into a TTY using the sudo edit-brunch-config command.

  • To access TTY2, press Ctrl + Alt + F2 and login as chronos. Crosh

Once you've entered the Brunch Configuration Menu you will be greeted by several pages of options.

  • Use the arrow keys to move the cursor up or down.
  • Use the spacebar to select an option.
    • An empty set [ ] means the option is not selected.
    • A filled set [x] means the option has been selected.
  • When you're ready to continue, press the Enter key.
    • You won't be able to go back, but this menu can be opened again later.
    • You do not need to select something from every page.

Framework Options

Click to learn about framework options

The first two pages of the Brunch Configuration Menu are for selecting Framework Options. These options act as patches and can be used to add more features or support to your installation, you can select multiple with the Spacebar, or use the Enter key to continue. Continue scrolling for details about what each option does. Framework Options 1 Framework Options 2

Some device specific options can be enabled through brunch configuration menu:

  • "enable_updates": allow native ChromeOS updates (use at your own risk: ChromeOS will be updated but not the Brunch framework/kernel which might render your ChromeOS install unstable or even unbootable),
  • "pwa": use this option to enable the brunch PWA:
  • "android_init_fix": alternative init to support devices on which the android container fails to start with the standard init,
  • "mount_internal_drives": allows automatic mounting of HDD partitions in ChromeOS:
    • Android media server will scan those drives which will cause high CPU usage until it has finished, it might take hours depending on your data,
    • Partition label will be used if it exists,
  • "chromebook_audio": enable audio on EOL chromebook devices using the brunch recommended recovery image,
  • "native_chromebook_image": enable it to use brunch on a non-EOL chromebook using its official recovery image, make sure to also select the chromebook kernel version used by your device in ChromeOS,
  • "broadcom_wl": enable this option if you need the broadcom_wl module,
  • "iwlwifi_backport": enable this option if your intel wireless card is not supported natively in the kernel,
  • "rtl8188eu": enable this option if you have a rtl8188eu wireless card/adapter,
  • "rtl8188fu": enable this option if you have a rtl8188fu wireless card/adapter,
  • "rtl8192eu": enable this option if you have a rtl8192eu wireless card/adapter,
  • "rtl8723bu": enable this option if you have a rtl8723bu wireless card/adapter,
  • "rtl8723de": enable this option if you have a rtl8723de wireless card/adapter,
  • "rtl8723du": enable this option if you have a rtl8723du wireless card/adapter,
  • "rtl8812au": enable this option if you have a rtl8812au wireless card/adapter,
  • "rtl8814au": enable this option if you have a rtl8814au wireless card/adapter,
  • "rtl8821ce": enable this option if you have a rtl8821ce wireless card/adapter,
  • "rtl8821cu": enable this option if you have a rtl8821cu wireless card/adapter,
  • "rtl88x2bu": enable this option if you have a rtl88x2bu wireless card/adapter,
  • "rtbth": enable this option if you have a RT3290/RT3298LE bluetooth device,
  • "ipts_touchscreen": enable support for ipts touchscreen (SP4/5/6/7,SB1/2),
  • "ithc_touchscreen": enable support for ithc touchscreen (SP7+,SB3 and above),
  • "goodix": improve goodix touchscreens support,
  • "invert_camera_order": use this option if your camera order is inverted,
  • "no_camera_config": if your camera does not work you can try this option which disables the camera config,
  • "oled_display": enable this option if you have an oled display (use with kernel 5.10),
  • "acpi_power_button": try this option if long pressing the power button does not display the power menu,
  • "alt_touchpad_config": try this option if you have touchpad issues,
  • "alt_touchpad_config2": another option to try if you have touchpad issues,
  • "internal_mic_fix": fix for internal mic on some devices,
  • "internal_mic_fix2": alternative fix for internal mic on some devices,
  • "sysfs_tablet_mode": allow to control tablet mode from sysfs:
    • echo 1 | sudo tee /sys/bus/platform/devices/tablet_mode_switch.0/tablet_mode to activate it or use 0 to disable it,
  • "force_tablet_mode": same as above except tablet mode is enabled by default on boot,
  • "suspend_s3": disable suspend to idle (S0ix) and use S3 suspend instead,
  • "advanced_als": default ChromeOS auto-brightness is very basic:
    • This option activates more auto-brightness levels (based on the Pixel Slate implementation).

Kernels

Click to learn about kernels

Brunch has several precompiled kernels avaliable for users, you can select one from the Brunch Configuration Menu by highlighting the kernel you want, then pressing enter. If you are unsure which to choose, 5.4 is the default kernel for Brunch. Continue scrolling for more information about each avaliable option.

WARNING: Changing kernel can prevent you from logging into your ChromeOS account, in which case a powerwash is the only solution (Ctrl + Alt + Shift + R at the login screen). Therefore, before switching to a different kernel, make sure you have a backup of all your data. Kernels

Several kernels can be enabled throught the configuration menu:

  • LTS kernels (6.1, 5.15, 5.10, 5.4, 4.19): use those kernels for non-chromebook devices, 6.1 is the default.
  • Chromebook kernels (6.1, 5.15, 5.10, 5.4, 4.19): For Chromebook devices, select the same kernel version used by your device in ChromeOS.

Kernel command line parameters

Click to learn about kernel line parameters

These are optional parameters that are not needed by every user. Some commonly used options are selectable, and more can be input manually. If you do not need any command line parameters, you can just press Enter to skip these sections. Command Line Paramters Custom Parameters

The most common kernel command line parameters are listed below:

  • "enforce_hyperthreading=1": improve performance by disabling a ChromeOS security feature and forcing hyperthreading everywhere (even in crositini).
  • "i915.enable_fbc=0 i915.enable_psr=0": if you want to use crouton (needed with kernel 5.4).
  • "psmouse.elantech_smbus=1": fix needed for some elantech touchpads.
  • "psmouse.synaptics_intertouch=1": enables gestures with more than 2 fingers on some touchpad models.

Additional kernel parameters can also be added manually from the configuration menu.

Verbose Mode

Click to learn about Verbose Mode

Brunch has a Verbose Mode, formerly called Debug Mode. Enabling this boot option will disable any selected Brunch Bootsplash and display a log while booting. This is particularly useful for debugging and solving issues that may prevent your system from booting. To enable Verbose Mode you must enter yes at the prompt, then press enter. Verbose Mode

Brunch Bootsplashes

Click to learn about Brunch Bootsplashes

Brunch Bootsplashes can be selected using the Brunch Configuration Menu, these determine the logo visible while Brunch is booting. (before the ChromeOS logo appears) These bootsplashes will not appear if you have enabled Verbose Mode above. You can select any of these options with the Enter key. Brunch Bootsplash

Click for previews of each avaliable bootsplash option

Currently avaliable bootsplashes are below, the "light" options will show as a framed window while booting.

Default

bs-default1 bs-default2

Blank

bs-blank

(What did you expect?)

Brunchbook

bs-bb1 bs-bb2

Colorful

bs-color1 bs-color2

Croissant

bs-croi1 bs-croi2

Neon Blue

bs-nb1 bs-nb2

Neon Green

bs-ng1 bs-ng2

Neon Pink

bs-np1 bs-np2

Neon Red

bs-nr1 bs-nr2

Saving Changes

Click for more info

The last page of the Brunch Configuration Menu will allow you to confirm your changes. Upon hitting enter, your PC will reboot. The next time you boot into Brunch, it will be a long boot. (Just like when you first installed) This is normal. If the options you selected were not correct, or you want to change things back, you can reopen the Brunch Configuration Menu and start over. Summary

Updates

It is currently recommended to only update ChromeOS when the matching version of the Brunch framework has been released, however it's not a strict requirement that Brunch and ChromeOS be the same version.

How to update Brunch and ChromeOS together

Click to learn how to update Brunch and ChromeOS together

The easiest way to update Brunch and ChromeOS is to use the [Brunch PWA][brunch-pwa-info], although it's also possible to update manually.

To manually update Brunch and ChromeOS together:

  • Download the latest Brunch release
  • Download the latest recovery matching your install and extract the bin.
  • Open a TTY with Crtl + Alt + F2 and login as chronos.
  • Run the built in command to update Brunch.
    • Replace brunch_archive.tar.gz with the file's actual filename.
    • Replace recovery.bin with the file's actual filename.

sudo chromeos-update -r ~/Downloads/recovery.bin -f ~/Downloads/brunch_archive.tar.gz

  • Restart ChromeOS after the update finishes.

Brunch and ChromeOS can also be updated with BiteDasher's Script

How to update ChromeOS

Click to learn how to update ChromeOS

The easiest way to update ChromeOS is to enable the enable_updates framework option, then update directly from the Settings page.

To enable the framework option:

  • Open a TTY with Crtl + Alt + F2 and login as chronos.
  • Enter sudo edit-brunch-config to open the Brunch Configuration Menu described above.
  • Select enable_updates with the spacebar, then continue through the menu with the enter key.
  • When finished, the Brunch Configuration Menu will prompt to restart ChromeOS.
  • Update from the standard ChromeOS settings page after rebooting.

How to update Brunch

Click to learn how to update Brunch

The easiest way to update Brunch is to use the [Brunch PWA][brunch-pwa-info], although it's also possible to update manually.

To manually update Brunch:

  • Download the latest Brunch release
  • Open a TTY with Crtl + Alt + F2 and login as chronos.
  • Run the built in command to update Brunch.
    • Replace brunch_archive.tar.gz with the file's actual filename.

sudo chromeos-update -f ~/Downloads/brunch_archive.tar.gz

  • Restart ChromeOS after the update finishes.