¶ L4T Ubuntu 18.04 installation guide
Current version: 5.0.0
Note: hekate 6.0.1+ MUST be used for this release.
If you need help you can ask in our Discord Server
You should also take a look at our FAQ and Common Issues which may already answer to some of your questions
The important parts of the guide are the Installation and Update sections.
You can skip the rest if you don't want extra information about the project.
¶ Updating existing installations (3.x.x/5.x.x)
If you come from a previous release and need to update.
-
In L4T Ubuntu Linux, go to the
Software Updaterapp and click "Install Now"
Or open terminal and execute:sudo apt update && sudo apt-get dist-upgrade.
After update is finished, reboot and done.- If Nvidia BSP was forcefully changed, creating a
.reinitfile into boot directory will restore Kernel, Kernel Modules and Firmware on the next boot and make the installation working again. - In case of an update from
3.x.x, uenv.txt will be backed up. If it was manually edited before, README_CONFIG.txt can be followed to restore the custom boot settings inside .ini this time.
- If Nvidia BSP was forcefully changed, creating a
-
If you haven't already, go to
hekate->Nyx Options->Dump Joy-Con BTand dump Joycon pairing data, with both Joycon connected to console, after first pairing them in hos.
¶ Prerequisites
- hekate 6.0.1 or newer
- A 16GB SD Card MINIMUM (Recommended: 128GB and up U3 or U3/A2 class)
- A computer (for backing up and extracting the installation files)
¶ Installation
-
Download the base image.
-
Backup your SD Card:
- Backup normal files from FAT32 (this also backs up emuMMC if file based)
- If emuMMC raw partition exists, go to
hekate->Tools->Backup eMMC->SD emuMMC RAW Partitionand back it up (BOOT0/1 and Raw GPP) - If android exists, do a TWRP backup
Suggestion: Use hekate UMS (hekate->Tools->USB Tools) with a USB-C cable connecting your switch and PC to mount your SD card and transfer files instead of swapping your card from Switch to PC.
-
WARNING: This following will wipe everything on your SD card.
Partition your SD card inhekate->Tools->Partition SD Cardleave at least 5GB for FAT32 for installation files downloaded in step 1 AND recreate any partition that may have backed up.
-
From your PC, extract the 7z to your SD FAT32 partition. Suggestion: Use hekate UMS (
hekate->Tools->USB Tools) with a USB-C cable connecting your switch and PC to mount your SD card instead of swapping your card from Switch to PC.
-
In Hekate, go to Tools -> Partition SD Card -> Flash Linux.
-
Go to
hekate->Nyx Options->Dump Joy-Con BTto dump Joycon pairing data, with both Joycon connected to console, after they were paired in hos first.
-
Now you can boot L4T Ubuntu.
Make sure any existing online updates are done viaSoftware Updateroraptcommand. -
After making sure everything is fine, you can now restore your backed up files
- Copy your normal files to FAT32
- For emuMMC use Hekate to restore your backup
hekate->Tools->Restore eMMC - For Android, copy your TWRP backup to your FAT32 partition then follow the steps and 4 of our android BUT instead of installing "Lineage zip, followed by your GApps zip" at step 4.g restore your backup in TWRP
¶ Extras
Pairing procons
Pair procons by opening the bluetooth menu in settings and pressing the + button in the bottom left corner. Then press the sync button on the controller and select its name in the pairing window.L4T Megascript
Use the L4T-Megascript app, available in your apps list (installed by default in 3.4.0+)You can get or build various essential stuff, apps or emulators with a single click. All configured and optimized for Switch.
¶ Misc.
- Supported Features
- Changelog:
Ubuntu Bionic 5.0.0 Full Changelog
¶ L4T Ubuntu 5.0.0 Changelog
¶ Kernel/Driver changes
- RAM
409MB RAM was freed from carveouts and was given to CMA so everything can easily use it with mmap - Joycon/Procon driver
Added support for Sio (Switch Lite gamepad)
Improved HD Rumble and fix it once and for all
Improved and reorder init sequence
Improved high speed uart stability
Fixed hangs when using hd rumble
Changed Procon D-Pad from HAT to actual D-Pad
Fixed HORI analog stick limits - WiFi & Bluetooth
Fully unlocked almost all WiFi channels,1-13 for 2.4GHz and 34-165 for 5GHz. 14/144 disabled).
Many 5Ghz channels will only be used if there's an existing AP (radar detection), for regulation reasons.
Fixed Bluetooth SCO mode (HSP/HFP). It now properly transmits audio instead of static
Significantly improved signal on both WiFi 2.4GHz and Bluetooth since default is now USB2
(USB3 can be enabled back via ini config) - Battery Charger and Fuel Gauge
Added Battery % regulation. Sets a limit to battery max % and it's quite useful for when device is always docked.
Added support of charging disable via special GPIO
Improve init sequence - Audio
Added Switch 2019/Lite/OLED speakers EQ
Added fine controls for DAC speaker/headphone volumes
Added minijack Mic support and Headset vs Headphones support
Added Headset button support (all buttons work as play/pause)
Refactored driver and improved init/deinit process - R2P
Refactored driver and added T210B01 support
Check README_CONFIG.txt for more info on how it can be configured - USB-C (DisplayPort/Power Delivery)
Massively refactor USB-C driver, again.
Support for PIN C (adapters that report 4 DisplayPort lanes only)
Removed the requirement for at least 2 USB-PD profile to enable PD charging
Added support for no DisplayPort (Switch Lite)
Improve and make init sequence way faster - Display
Added OLED panel driver
Added HDCP 1.x and 2.2 support for DisplayPort
Fixed TSEC support
Backlight will always get disabled before disabling LCD/OLED panel - DisplayPort CEC
Added support for CEC via DisplayPort
Docking will change source to Switch automatically if supported
CEC tv remote control
Support for OLED dock - Non-PD USB charger detect
Added fine tuners for currents on USB charger detect
Improve detection
Set SDP when a gadget is enabled to 500mA only - eMMC/SD driver
Improve auto calibration
Allow 1-bit mode - XUSB
Fixed T210B01 support
Fixed USB3 device mode
Added proper support for USB2-only mode
Various fixes to USB phy and vbus - Improved kernel driver init sequence. Saves around 4-6s of boot time.
- Added better panic error handling, the relevant log can now be dumped automatically by hekate.
- Added controls for disabling touch panel tuning on boot (some broken flex cables or panels might need that)
- Fixed IMU IRQ mode. This greatly improves IMU Acc/Gyro responsiveness. Also added new IMU chips support.
- Fixed an issue where Power button irq could be stack
- Fixed a hang on boot because of Squash FS driver
- Added DM-CRYPT support
- Fixed max77812 CPU/GPU/RAM regulator and enable it for T210B01
- Added max77801 3.3V regulator for Switch OLED
- Added a new TSKIN driver and changed temperatures and fan curves to match HOS exactly
¶ Ubuntu/Userspace changes
- Theme and Icons
Default theme and icons changed to more modern flat and dark one
If you changed them before, you can useTweaksfrom app menu to change it (Pop-Dark theme and Pop icons) - On-Screen Keyboard
Now rocks a new material you design look
Add special key for Gamepads to Show/Hide it
Enabled physical Keyboard detection
Auto transparency on idle, so user can see behind it.
Fixed an issue which would delay logout 2:30 minutes if osk is enabled - Default settings
Double click is now easier to do on touch
Drag threshold increased to avoid miss-dragging instead of tapping
ALS disabled for backlight control so user can enable it in ini config for emulators and games
Changed Battery levels: Warns LOW at 15%, Warns Critical at 6%. Shutdowns at 4%
Suspend after 10min idle at battery. Never at AC.
Battery percentage always shown
Cursor size default increased
Default scaling changed
Default Dash shorcuts changed so user can pin preferences without first unpinning - Bluetooth A2DP profiles
Automatic profile change
Added AAC, AptX and AptX HD profiles
Also fixed SCO HSP/HFP profiles - Fixed 5.1 surround audio
- Dock-Handler
Fully optimized and fast
Saves boot time
Works properly on Greeter
CEC support
PD power profile support (Will switch to Console if PD charger)
Fixed crashes on boot - Joycon Daemon
Added Sio (Switch Lite Gamepad) support
Now rumble works properly and also doesn't hang system
Removed Procon management from Joycond. Now the controller can be used by any software
IMU now accessible from every app
Various bug fixes - System FFMpeg updated to use latest HW Video codecs
- Switch Multimedia
Updated to use the latest HW Video decoding/encoding
(ffmpeg-l4t, ffplay-l4t and mpv-l4t)
All video files now use SMPV Player by default for hw decoding - Chromium Browser
Full Vulkan HW acceleration support
Full HW Video decoding support for H264 and VP8 videos - Bluetooth is now disabled completely on sleep to save battery
Enabled automatically on resume. - Debloated and remade main image from scratch
- Joystick Mapping
Based on L4T Megascript one and included by default
Reworked all mappings to the following:
A, B, X, Y --> Enter, Backspace, Esc, Task Switch
Minus, Plus --> Rotate Screen, Show/Hide OSK
L3, R3 --> Caps Lock, Middle Click
Home --> Windows Key
D-pad --> Arrow keys
L/R Sticks --> Mouse, Scrolling
Capture --> Disables(/Enables) mappings and allows it to be used as gamepad - Now All updates can be done via APT. 5.0.0 will be the last image provided.
Every new update will be done through Software Updates or Apt command. - Updated ALSA profile to support all SKUs
- Added HDCP support if requested by an App that supports the api
¶ Initramfs changes
- WiFi MAC address is now derived from SoC id
- BT MAC address if no joycon dump is derived from SoC id
- Added error checking at boot
Fixes "bricks" where linux partition is corrupted but can be fixed - Creating
.reinitfile flag in switchroot/ubuntu will force a re-extraction of Kernel and Modules/Firmware
That should always be used if user updates BSP to another one (for example r32.7.3) - If initramfs fails booting it will try to dump kernel log in sd first (l4t_initramfs_kmesg.log) before showing the red screen.
¶ Boot Stack changes
- L4T Loader - specialized bootloader
- Full support for T210B01 (Switch 2019, Lite and OLED)
- .ini file is now the main configuration file and uenv.txt is obsolete (a backup is done for existing copies)
- All configs are described in README_CONFIG.txt
- Careful with what you are booting on T210B01 since it can create hangs in black screen or error messages.
Error message will be shown if that's the case, to avoid a black screen hang.
Ubuntu Bionic 3.4.0 Full Changelog
- Better performances in many scenarios (As always that should affect apps/games/emus/etc)
- Significant better deep sleep. (Measured at 582 hours. 440% better).
- Faster wake up from sleep.
- Saved 240MB ram (fb and active file page pool, aka always used pool)
- Memory remapping 800%-2000% speed up. Mostly used by emulators and VMs (and lot in android).
- Some other memory optimizations, plus enabled huge ram pages
- Faster kernel and OS boot.
- Fixed tearing issues for NVDEC/NVENC. (video hw accel)
- Lower latency for frame end calcs for builtin display
- Fixed Hori pads for joycond
- Fixed an issue where it would make railed jc to disconnect on rumble
- Joycon/Procon rumble was improved and intensity tuned for better user experience
- Kernel now uses the proper display panel init/deinit by checking panel id
- Improved dock/undock script
- Touch stays enabled now in dock mode. Users that use docks that do not cover the screen can use it as alternative input.
- Added low ram protection. Now instead of hanging for minutes it will only stutter for seconds until oom occurs and recovers ram
- Better seamless display on boot
- uenv.txt changed, read uenv_readme.txt. It's simple to transfer over custom settings.
- Reboot action can now be defined in new uenv.txt. Reboot back into Linux by changing `reboot_action=` from `bootloader` to `via-payload`.
Apps Changes:
- Full video HW decoding via new SMPV Player app (also supports youtube links)
- Full video HW encoding via ffmpeg-l4t
- Added L4T-Megascript app
You can get or build various essential stuff, apps or emulators with a single click. All configured and optimized for Switch.
- Nvpmodel was updated to include Battery charging protection limits options
Useful when you are constantly docked and want to protect battery's life.
Limit gets saved and applied on boot.
Reminder that discharging can't happen when plugged in. Even when charging is off, usb power is used to supplement system.
So you need to discharge first if you want the battery % to go inside the limit.
That also disables charging in sleep in order for the feature to work.
If you reboot/shutdown, it gets disabled and re-enabled at the next L4T boot.
As always the source is public and all L4T based projects for Switch will benefit (L4T linux distros/Lakka/Android)
Ubuntu Bionic 3.3.0 Full Changelog
- Significant performance improvements
CPU arch, RAM, GPU, general latency, etc optimizations.
Affects gui, apps, games, emus, etc
- Significant deep sleep power draw fixes
Now almost all non-needed devices power off on deep sleep and ram is set to appropriate frequency.
(Touch panel, LCD, Joycon charging and many more devices now power off in deep sleep as they should)
- IO scheduler was changed to provide way faster storage IO
- Released 15 MiB extra ram
- Fixed voltage calculation for OC. It should provide more stable overclocking
- Refactored thermal management
Fan profiles are now the same with HOS
Added failsafes, throttling and force power off when very high temps for the board are reached
- Faster boot times
- Fixed issues with Joycon charging and Hori power on resume
- Fixed Power button issues
- Touch improvements
- Added Hori and Obirds rail support
- OTG now allows deep sleep, even if linux resides in a USB SSD.
- Various USB fixes
- Allow fuel gauge to wake up system and power off gracefully on empty battery
- Added support for many 3rd party docks
These include Genki, Zenscreen, Nexdock and anything else that uses similar methods
Basically, the support should reach 100% (docks that support DP via pin D)
- Fixed issues with fast charging when docked on boot
- Fixed other issues with charging on certain edge cases
- Fixed DP/HDMI when plugging console while sleeping
- Fixed DP/HDMI when already docked and waking up
- Dock led indicator now has a breathing light when sleeping
- Add exFAT partition support (boot driver still needs to be FAT32)
- Enabled 1GB ZRAM swap
- Status messages on booting
- Seamless display booting (needs hekate higher than v5.5.4)
- Disabled screen blanking on idle. Dimming/Screensaver is still there and can be disabled in Brightness & Lock.
This will help with games/emus where gamepad is used and it does not reset idle times like mouse/keyboard.
- Fixed apt repo urls
- NVPModel is revamped
Allow changing power profiles via touch
Added handheld power profile
Added fan profiles
Added automatic profiles based on handheld or docked
Added USB 3.0 disable toggle for boosting WiFi 2.4G and Bluetooth signal
OC profiles now do not require enabling overclock flag in sysfs
Sources
¶ Credits
CTCaer (kernel/bootloader, distro maintainer, NVENC/NVDEC),
Gavin_Darkglider (distro maintainer),
Azkali (distro maintainer),
Ave (repo management and host),
DanielOgorchock(Switch controller drivers/joycond),
Bylaws,
Langerhans,
Natinusala,
stary2001 (reboot2payload),
NVIDIA (Tegra BSP),
theofficialgman and cobalt2727 (L4T-Megascript),
Everyone else in switchroot