Painless Linux Switch

Painless Linux
General
Author	natinusala
Type	Operating systems
Version	2018
License	Mixed
Last Updated	2018/06/02
Links
Download
Website
Source

Painless Linux is a project that allows you to boot Linux on the Switch without using imx_usb_loader.

It supports Windows, Linux, Mac OS and Android as host machines.

User guide

Disclaimer

The authors are not responsible in case you brick or blow up your Switch, its LCD screen or its battery. Use this at your own risks, as Linux is known to cause battery calibration and RTC desync as well as potential damage to the LCD display.

You have been warned.

What am I booting

The system

It's Arch Linux ARM (ALARM) with the GNOME desktop manager and some utilities :

• sudo
• chromium browser
• scripts to manage GPU clock profiles
• SSH server enabled by default
• automatic root filesystem expand to fit your SD card

The default user is alarm, its password is alarm. The root password is root.

How to see and select the current GPU clock profile

The system comes with two scripts to see and select the current GPU clock profile. There are currently three profiles which can be enabled :

• low (03) : normal undockedspeed
• (default) normal (0a) : normal docked speed
• high (0d) : (not recommended) maximum speed, will cause power failures

The system will reset to the normal profile at each reboot.

To see the current clock profile, run the get-gpu-clock-profile command as root. It will list all the available profiles, with a star next to the one currently activated.

To set the current clock profile, use the set-gpu-clock-profile command.

First boot

When booting for the first time, the system will expand the root partition to fill your entire SD card, and then reboot (like a Raspberry Pi). You will need to run the exploit again once the screen turns black to finalize the reboot process, like when enabling Wi-Fi.

Good practices

When shutting down the Switch from Linux, it doesn't actually power it off. Press the power button for 10 seconds and reboot into Horizon before shutting down from there.

How to use it

Step 0 what you'll need

• A first-gen Switch.
• A way to run the exploit (the host machine) :
  • A PC on Windows or Linux  * A Mac  * An Android device with Android 4.3 or newer, USB OTG support and a XHCI controller (you can't really know that before trying)
• A way to plug your Switch in the host machine :
  • If using a computer, an USB A-to-C or C-to-C cable.
  • If using an Android device with a Micro USB port, find a Micro USB cable (often labelled "OTG") and chain it to a Type-C cable.
  • If using an Android device with a Type-C port, find a C-to-C cable or a C-to-A chained to a A-to-C cable.
• A SD card for you Switch (of at least 8Gb).
  • 128Gb cards are currently not supported by the Switch, a Linux kernel patch is required.
• A way to put your Switch in RCM mode (a jig, a paperclip, a wire, a Joy-Con mod, a screwdriver, a soldering iron...).

Step 1 downloading things

• Clone or download this repository (here)
• Download the latest image file :
  • from mega.co.gz
  • from Google Drive (thanks to kevandkkim)

Step 2 SD card preparation

Follow this guide with your SD card and the image file you downloaded.

TL;DR : on Windows use Etcher, on Linux & Mac OS use dd

Step 3 booting Linux

From a Windows PC

On Windows, you will first need to install the required driver :

• Get your Switch in RCM mode and plug it into your PC.
  • It should appear as "APX" in Windows.
• Download and run the Zadig Driver Installer from here : https://zadig.akeo.ie/
• In the list, choose the device "APX".
  • If it's not showing up, check "List all devices" in the options.
• At the right end of the green arrow, choose "libusbK (v3.0.7.0)".
• Click on the big "Install driver" button.

Then, make sure that your Switch is plugged in your PC and in RCM mode. Open the folder of this repository (the one you downloaded and extracted) and run windows-boot.bat (or windows-win32-boot.bat on a 32bit machine). Voilà !

Having a Win32 error 31 is normal.

From a Linux PC or a Mac

Install Python 3 (usually already installed). Open a terminal to install the required package : pip3 install pyusb==1.0.0. You will have to deal with permissions issues (hint : sudo works on Linux).

Then, plug your switch in your PC and put it in RCM mode. You should use a blue "SS" port as these have a greater chance of success (EHCI controller doesn't work, XHCI controller works, blue ports have a greater chance of using XHCI).

Once ready, run the linux-macos-boot.sh script from this repository's folder. Again, you will have to with permissions issues (if it cannot find the module usb it means that you have insufficient permissions). Voilà.

From an Android device

• Download and install the latest release of Switch Linux Launcher for Android.
• Run it - it will tell you that some files are missing, remember the folder in the dialog, it should look like one of these :
  • /storage/emulated/0/Android/data/io.mrarm.switchlinuxlauncher.noimx/files/shofel2
  • /sdcard/Android/data/io.mrarm.switchlinuxlauncher.noimx/files/shofel2
• Exit the app (if you can close the task using the multitask button it's better).
• From the payloads folder of the repository, copy the cbfs.bin and coreboot.rom files to the shofel2 folder on your Android device (the folder of the previous step).
• Run the app again - if the dialog doesn't show up then you can go on, otherwise you did something wrong.
• (Optional) Depending on your device, you might need to enable "OTG" or "OTG Storage" in the Android settings.
• Plug your Switch in your Android device.
  • If the Switch is charging from your phone, you can go on.
  • If your phone is charging from the Switch, try to reverse the cabling so that your phone charges the Switch instead.
  • If nothing happens, I'm afraid your phone doesn't have OTG (or it's not enabled) - the exploit might now work.
• Put your Switch in RCM mode.
• Voilà.

Troubleshooting

Having a black screen despite the fact that the exploit worked?

Just shut down the Switch (10 seconds power button press) and try again, it happens sometimes.

Wi-Fi doesn't work?

Make sure you reboot properly :

• Plug your Switch back into your host machine.
• Using the touchscreen, open the top-right menu and click on the power button.
• Click on the Restart button.
• Wait for the full reboot of the console.
• Launch the exploit again so that Linux boots.

What works / what doesn't work

• Wi-Fi :
  • Works after a reboot.
  • After each cold boot, you should reboot (it will reboot to RCM) and run the exploit again to enable Wi-Fi.
• Bluetooth :
  • Works partially.
  • Keyboards and mice work.
  • Joy-Cons, speakers and headphones don't.
• Touch screen :
  • Works.
• Audio :
  • Not working, even through Bluetooth headphones or speakers.
• Hardware graphics acceleration :
  • Works.
  • You have to select a power profile manually at each reboot using the switchpower script.
• Wired Joy-Cons :
  • To be implemented.
• Volume buttons :
  • Recognized but don't do anything since there is no audio device.
• Power button :
  • Only works to halt the system with a long-press.
  • No graceful shutdown.
  • No sleep mode.
• USB :
  • Not working.
• Dock :
  • To be implemented.
• Power management :
  • Works partially.
  • No graceful shutdown.
  • No reboot to Linux, only reboot to RCM.
  • GPU profile has to be selected by hand.
  • Battery level correctly recognized.
  • Be careful as staying for a long time in Linux desyncs the battery calibration on Horizon and can cause the console to shutdown unexpectedly (at 50%)
• Gnome-terminal :
  • Tofix - It crash use xterm instead.

How to build it yourself

Follow the steps on fail0verflow's repository, but instead of using their fork of u-boot, use this. If you already built everything, you will need to rebuild u-boot using my fork and then rebuild coreboot.

Then, make sure that the first partition of the console's SD card is FAT32 and create a boot folder. Inside, put :

• Image.gz : the zipped Linux kernel
• tegra210-nintendo-switch.dtb : the DTB
• boot.scr : you can generate it by using the make.sh script in the src folder of this repository

Put the SD card in the console.

Then, use shofel2 to run the coreboot you recompiled, like usual. Linux should boot immediately without the need to run imx_usb.

(You should probably put a rootfs in mmcblk0p2.)

Credits

• kombos for the pre-built kernel and DTB.
• rajkosto for TegraRcmSmash.
• MCMrARM for the Switch Linux Launcher app.
• Gigaa for the GPU clock speed service.
• 00cancer for the initial GNOME image.
• ctyler for the rootfs-resize script.
• fail0verflow for shofel2 and their coreboot, u-boot & Linux port.
• Everyone else who participated.

External links

• GitHub - https://github.com/natinusala/painless-linux
• GBAtemp - https://gbatemp.net/threads/painless-linux-its-linux-but-painless-windows-mac-os-linux-android.503108/