# Introduction LibreELEC is a minimalist 'Just enough OS' Linux distribution for running [Kodi](https://kodi.tv). Our documentation can help you install and configure LibreELEC to run Kodi, or develop and build installation images using our buildsystem. Documentation is authored and maintained by LibreELEC users. If you see something is incorrect or missing please click the GitBook link below to join our documentation team. The GitBook online app makes changing documentation simple, with your changes sent directly to our [documentation repo on GitHub](https://github.com/LibreELEC/documentation) as a pull-request that project staff can review and merge. {% hint style="info" %} Please do not be concerned about your English language skills when contributing changes to our documentation. It is easier for a native speaker to merge your content and then make corrections than to write everything themselves. {% endhint %} All content is licensed under the Creative Commons [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license. ## Support User support is managed through our forum: and the #libreelec IRC channel on Libera Chat. Start a forum thread to ask a question, and someone will reply. Please be patient and wait for answers, we are all unpaid volunteers with jobs and families! For support on Kodi itself, please refer to the official [Kodi Wiki](https://kodi.wiki/view/Main_Page) and [Kodi Forums](https://forum.kodi.tv). # Log Files If you experience problems and want to investigate yourself or ask others for help in the forum or the IRC channel, a log file (or files) and configuration data provides useful info. Kodi has `default` and `debug` log modes. As you'd expect, debug logs show more detail and are more useful for staff and forum regulars to work with. If you are asked for a log - assume the request is for a `debug` log and for the entire log file, not just the small snippet you think is useful (often we need to see and understand the configuration too). Enable 'debug logging' at Settings → System → Logging, then paste or copy/share the logs. ## LibreELEC Settings The settings add-on has a built-in "paste" function that grabs the current Kodi log file and other useful system configuration details and sends them to the pastebin service. It is an easy way for inexperienced (or command-line phobic) users to share logs. Navigate to LibreELEC → System → scroll down to `Paste system logs` and press enter to submit them. Once the upload completes the GUI will show a short URL that you can copy and use in a forum post or while chatting to developers on IRC. ## SSH/Console SSH into your LibreELEC machine and run the following command: ``` pastekodi ``` You will get a short URL back. That will look like this: ``` LibreELEC:~ # pastekodi http://ix.io/2f5 ``` Copy and paste the URL link to a forum post or an IRC chat session, or review it yourself. ## Samba/SMB If Samba (SMB Sharing) is enabled you can collect the log file by accessing the `Logfile` folder over the network. This is a special folder. When you access the folder it triggers a task to collect the current Kodi log and system configuration, and package everything into a single zip file that can be copied back to your local machine or unpacked in the share. The auto-created files are named with date and time to make it easier to find the latest file. Inside the zip are multiple files. The main one project staff will be interested in is `KODI.log` **!! PLEASE DO NOT UPLOAD LOG/ZIP FILES TO THE FORUM !!** Instead, open `KODI.log` in a text editor and copy/paste the content to an internet "paste" service like then share the paste URL. This makes reviewing your log a "one click" exercise so more people are likely to review it, and it saves a ton of disk space on our forum server. ## Kodi Log Uploader The "Kodi Log Uploader" add-on can be installed from the Kodi add-on repo. It will detect that is being used on LibreELEC to collect the correct log files, and it performs the same task as the paste function in the LibreELEC settings add-on. The main difference is that Kodi Log Uploader displays a QR code on-screen to make the process of copying the pastebin URL for use easier (for some). It also sends the log to the Team Kodi pastebin service, which uses highlighting to make reading the logfile easier for developers and forum staff. # Updating Updating LibreELEC is (mostly) simple and can be done automatically, manually from inside the Kodi GUI via the LibreELEC Settings add-on, by [downloading an update file from our website](https://libreelec.tv/downloads_new) and copying the file to a local Samba share, or by running a command from the SSH console. We publish two image file types: * LibreELEC-Project.arch-11.0.1.**tar** (update) files which are used for updates only. * LibreELEC-Project.arch-11.0.1.**img.gz** (update + image) files which are used for creating new USB/SD installation media but can also be used for updates. We can update from both **.tar** and **.img.gz** files. ## Auto-Update Auto-Update is enabled by default and tracks minor version updates, e.g. LibreELEC 11.0.0 will update to 11.0.1, 11.0.2, etc. as they are released. It will not perform major version updates as these involve Kodi add-on updates (broken add-ons are the main source of update issues) and user-experience changes we do not want to force onto users. If auto-update is enabled the latest update file will download in the background, then Kodi will prompt you to reboot and start the update process. If you prefer to manage system updates manually, auto-update can be disabled in the settings add-on. ## Settings Add-On Navigate to the Update section of the settings add-on, select the update channel (LibreELEC major version) and then the specific minor version to update to. The update file will start downloading, and once complete the system will reboot to perform the update. Please see the following video {% embed url="" %} ## Samba Share Using a file browser (explorer.exe, not a web browser) copy/paste an update file to the `\\LIBREELEC\UPDATE` Samba share on your LibreELEC device. Once the file transfer has completed, reboot LibreELEC to start the update process. ## SSH Console SSH into your LibreELEC device and navigate to the (hidden) update folder ``` cd /storage/.update ``` Check to make sure there are no files in the folder ``` ls -la ``` Download the update file (change the URL for the current release, etc.) ``` wget http://releases.libreelec.tv/LibreELEC-RPi4.arm-11.0.1.img.gz ``` Once the download has completed, reboot to start the update process ``` reboot ``` ## USB Drive Download the LibreELEC image or update file and copy it to a USB drive. Connect the USB drive to your HTPC and navigate to the `/storage/.update/` update folder using Kodi File Manager (you will need to enable viewing of hidden files and folders in Kodi settings). Copy the update file from the USB drive to `/storage/.update` then reboot to start the update process. ## Downgrade Kodi does not support downgrading. If "updating" within the same LibreELEC/Kodi major release, e.g. LibreELEC 11.0.1 to 11.0.0, the downgrade will normally work. If downgrading to an older LibreELEC/Kodi major version e.g. LibreELEC 11.0.1 to 10.0.4, the downgrade process will complete but Kodi may not gracefully handle being restarted with configuration files and add-ons from the (newer) previous release. Always make a backup before upgrading so that you can clean install then restore the backup to effect a downgrade without problems. ## Migrate OpenELEC In 2016 when we forked from OpenELEC the differences between projects were small and it was simple to migrate by using our update .tar file. Today there are some challenges: * LibreELEC images for Generic x86\_64 hardware have grown to 240MB+ in size and most older OpenELEC installs have a small 230MB boot partition so LibreELEC files will not fit and the manual .tar update process will fail (gracefully). Raspberry Pi and similar images are smaller and will still fit, but read on: * Older Kodi add-ons are frequently incompatible with newer Kodi versions, causing crashes when the system restarts, and the bigger the version jump the more likely add-ons will cause problems. LibreELEC will detect when Kodi repeatedly fails to start and defaults to a "safe mode" configuration, but this normally requires you to access the SSH console to get back to a working setup. * Kodi does not self-manage media and add-on package caches so over-time filesystem litter accumulates. Starting over from a clean install removes all the not-needed junk resulting in a faster/lighter installation with an improved Kodi user experience. To migrate essential Kodi data from the old installation before migrating (which is likely to fail) or making a clean installation, enable the SSH service in the Settings add-on, then log-in over SSH to stop Kodi and back-up the userdata folder: ``` cd /storage/backup systemctl stop kodi tar -czf kodi_userdata.tar.gz /storage/.kodi/userdata ``` Backup files are normally 1-2GB in size so move them off-box by copying to USB or moving them to `/storage/backup` which is accessible over the network via the `\\LIBREELEC\BACKUP` Samba share. After clean installing LibreELEC you can restore the backup: ``` systemctl stop kodi rm -rf /storage/.kodi tar -xzf /storage/kodi_userdata.tar.gz systemctl start kodi ``` The following video shows the migration process from OpenELEC v7.0 to LibreELEC v7.0 as it looked in 2016. The Kodi GUI now looks different (the skin changed) but the process remains the same: # Create Media The “LibreELEC USB-SD Creator” app helps you select and download the latest LibreELEC image for your HTPC device and create bootable USB or SD Card media. The tool is available for current 64-bit Windows 10/11 versions, and macOS v14.x and newer. Download Links: * [LibreELEC.USB-SD.Creator.x64.exe](https://releases.libreelec.tv/LibreELEC.USB-SD.Creator.x64.exe) ([sha256](https://releases.libreelec.tv/LibreELEC.USB-SD.Creator.x64.exe?mirrorlist)) * [LibreELEC.USB-SD.Creator.macOS.dmg](https://releases.libreelec.tv/LibreELEC.USB-SD.Creator.macOS.dmg) ([sha256](https://releases.libreelec.tv/LibreELEC.USB-SD.Creator.macOS.dmg?mirrorlist)) Note: The Linux version of the app for Ubuntu and Debian derivatives is not currently available. Please see the note on [#alternatives](#alternatives "mention") below. ## Step 1 Choose the LibreELEC image and the app will show the latest stable release, e.g. * Generic x86\_64 - LibreELEC-Generic.x86\_64-12.0.1.img.gz * RaspberryPi 2/3 - LibreELEC-RPi2.arm-12.0.1.img.gz * RaspberryPi 4 - LibreELEC-RPi4.arm-12.0.1.img.gz * RaspberryPi 5 - LibreELEC-RPi5.arm-12.0.1.img.gz If you select the 'Show all' check-box the drop list includes older stable releases too. ## Step 2 After selecting the LibreELEC image and version click the `Download` button. This will prompt you to select a folder to download to. You can also select a previously downloaded image file on your machine for installation. Hit the `Select file` button and browse your computer for the .img.gz file, or drag/drop the file on the app GUI. ## Step 3 Select the USB stick or SD card to write the image onto. Click the refresh button if the removable device is not listed. Note: **ALL DATA ON THE TARGET DEVICE WILL BE OVERWRITTEN** so please ensure there is no important data on it! ## Step 4 After selecting an image and target device the `Write` button is available. Click it to write the image. Once the progress bar reaches 100% and shows `Writing done!` you can exit the app, eject the USB or SD media, and boot your device to install LibreELEC. ## Support If you have problems with the app, please post in the [USB-SD Creator Support forum](https://forum.libreelec.tv/forum-41.html). ## Alternatives Here are some alternative tools that can be used for creating LibreELEC boot media: * [Raspberry Pi Imager](https://www.raspberrypi.com/software/) can create Raspberry Pi images using files from our servers * [Balena Etcher](https://etcher.balena.io/) is popular but huge (almost the same size as our distro images!) * [Win32DiskImager](https://win32diskimager.org/) is a reliable tool for Windows OS devices * [dd](https://linux.die.net/man/1/dd) is available from most Linux OS command lines # Add-Ons LibreELEC builds and hosts a number of Kodi binary add-ons to extend functionality, e.g. * Audio Encoders * Audio Decoders * Image Decoders * Inputstream parsers * PVR clients * Screensavers * Virtual Filesystems * Visualisations We also provide a range of program/service add-ons, including: * .net Core Runtime * Adafruit Libraries * BTRFS Tools * DVB Tools * FFmpeg Tools * Game Tools * JRE for BD-J menus * Multimedia Tools * Network Tools * Raspberry Pi Tools * System Tools * VDR Configuration "Tools" add-ons bundle multiple binaries into a single add-on with a themed purpose to reduce repo maintenance. Look in the Kodi GUI and the info panel will tell you the list of binaries in each bundle. # Containers The awesome folks at [LinuxServer.io](https://linuxserver.io) maintain a range of popular Docker containers installable as Kodi add-ons. After installing the Docker add-on (from the LibreELEC add-on repo) you can install the LinuxServer repo add-on (from the LibreELEC add-on repo) and then install container add-ons from within the Kodi GUI. To make maintenance easier LinuxServer add-ons are designed to pull the latest Docker image automatically on Kodi startup to keep the containers fresh. It is also possible to install Docker containers manually from the SSH console using `docker pull` commands. This allows you to install a container from any public container repository. This is also how you can access the full [fleet of LinuxServer containers](https://fleet.linuxserver.io). ## Container Architecture Docker containers often ship in multiple CPU "architecture" or "arch" variants. To run, the container architecture must match the "userspace" CPU arch of the LibreELEC image which can be different from "kernel" CPU architecture. The userspace arch is noted in the image filename, e.g. * LibreELEC-Generic.**x86\_64**-11.0.1.img.gz has `x86_64` userspace * LibreELEC-RPi4.**arm**-11.0.1.img.gz has `arm` userspace * LibreELEC-RPi4.**aarch64**-12.0-nightly-20230310.img.gz has `aarch64` userspace Userspace CPU arch can also be read from the `/etc/os-release` file in the filesystem, e.g. ``` RPi4:~ # cat /etc/os-release NAME="LibreELEC" VERSION="11.0.3" ID="libreelec" VERSION_ID="11.0" PRETTY_NAME="LibreELEC (official): 11.0.3" HOME_URL="https://libreelec.tv" BUG_REPORT_URL="https://github.com/LibreELEC/LibreELEC.tv" BUILD_ID="1189cdb0f43e6f4208f747d54fefb70478ebee9d" LIBREELEC_ARCH="RPi4.arm" <= This contains the userspace CPU arch LIBREELEC_BUILD="official" LIBREELEC_PROJECT="RPi" LIBREELEC_DEVICE="RPi4" ``` Docker containers may also use different arch naming, e.g. * The `arm` arch may be referred to as `linux/arm` and `linux/arm/v7` * The `aarch64` arch may be referred to as `linux/arm64` and `linux/arm64/v8` * The `x86_64` arch may be referred to as `amd64` {% hint style="warning" %} LibreELEC 12 will switch most ARM SoC devices capable of running a 64-bit kernel from `arm` to `aarch64` userspace. This will require affected users to remove `arm` containers before they update and redeploy `arm64` versions post-update. {% endhint %} # Security This article documents LibreELEC's insecurities: the services we run by default and the security design choices and compromises the OS makes. Where options exist, it also provides guidance or warnings to help you better-secure your LibreELEC installation. {% hint style="danger" %} LibreELEC is designed for home networks and the out-of-box configuration is a compromise of security, supportability, and usability. It should not be used in security-sensitive networks. {% endhint %} ## Avahi Avahi (Zeroconf) runs in the background to announce services like Kodi, Samba, SSH over mDNS to the local network to make connecting from mDNS-aware OS and client applications easier. The service list is updated automatically when individual services are enabled or disabled. Avahi can be disabled in the LibreELEC settings add-on. ## Bluetooth Bluetooth is enabled by default if hardware is detected to facilitate connections from remote controls and keyboards, and the OS listens for connections and pairing requests. Devices like speakers normally pair automatically while keyboards, remote controls, and compute devices with input capabilities normally prompt for a PIN code (shown on the screen). Bluetooth services including OBEX file transfer can be disabled in the LibreELEC settings add-on. ## Credentials In a conventional Linux distro users access the OS with a non-privileged user account and use `sudo`to elevate privileges to perform tasks as the `root`user. This provides security isolation between user and system processes, with the side benefit of preventing easy end-user access to disruptive configuration options that are easily changed or misconfigured resulting in complex support activity. In LibreELEC there is a single`root`user and most internal services run as the root user. This reduces distro maintenance and eliminates the need for `sudo` to provide a simple console experience for users with typically low or no Linux CLI experience. Although users have `root`privileges, most of the filesystem exists in a read-only state so there is limited scope for unskilled users to misconfigure the OS from its default known-good state. As the default `root/libreelec`credential is a well-known secret the first-run wizard prompts for it to be changed. It can also be changed from the console using `passwd`. It is *not* possible to add users, groups, or change the `user:group` context applications run under without creating a custom OS image with baked-in changes. {% hint style="danger" %} Users are strongly advised to change default credentials. The default `root/libreelec` and `libreelec/libreelec` have long been observed in common password dictionary lists that are available to anyone. {% endhint %} ## Firewall The OS is intended for use inside a home network behind a NAT router/firewall device. It embeds the `iptables` firewall but this is disabled by default. It can be enabled via the LibreELEC settings add-on, and we provide simple `Home/Public` options for inexperienced users to enable for essential protection. The "Home" option allows traffic from 192.168.x.x, 172.16.x.x, 10.x.x.x IP ranges (RFC1918) while the "Public" option blocks all traffic from all networks. The firewall automatically enables when custom iptables configuration is provided by the `/storage/.config/iptables` file. ## Samba Samba is enabled by default to facilitate end-user access to the `\Logfiles` share when installation completes but the system does not boot to the Kodi home screen. Accessing the`\Logfiles`share auto-generates a zip archive containing logs and config info that can be downloaded and shared with project staff and end-users providing support assistance in the forum. On successful boot the first-run wizard is shown and users can disable Samba. After the wizard has completed Samba services can be enabled/disabled or reconfigured via the LibreELEC settings add-on. Here you can enable authentication and change the default credential used to access the Samba server. You can also downgrade SMB protocol support to min/max SMBv1 to support legacy devices that cannot connect to an SMBv2/v3 capable server. {% hint style="info" %} Samba **server** configuration located in the LibreELEC settings add-on, has nothing to do with Kodi SMB **client** configuration located in Kodi settings. These are separate functions with separate configuration. {% endhint %} ## SSH SSH services are disabled by default but can be enabled on successful boot in the first-run wizard. If you enable services you are prompted to change the default `root/libreelec`credential. After the wizard has completed SSH services can be enabled/disabled or reconfigured via the LibreELEC settings add-on. Here you can reset the root password. The password can also be changed from the local console or SSH console using the standard Linux `passwd`tool. For better security and convenience, add a public key to `/storage/.ssh/authorized_keys` and then disable password authentication in the LibreELEC settings add-on. You can replace the default 2048-bit RSA keys generated on first-boot and stored in the `/storage/.ssh` directory. New SSH keys must be secured with 600 permissions else the SSH daemon will not start. {% hint style="info" %} Enabling the "Disable SSH Password" feature does not disable the password login prompt. It simply ensures no password provided will be accepted. {% endhint %} ## VPN Connecting to any commercial or private VPN server that provides a public IP address to the VPN tunnel network interface requires the server to block inbound connections or the [#firewall](#firewall "mention") to be enabled with either `Home` or `Public` profiles. Services like Samba and SSH listen on all available interfaces so the VPN connection exposes services to the public internet. ## WSDD2 The WSDD2 service broadcasts information on Samba share to Windows OS devices to support auto-discovery in Explorer. It is started and stopped alongside the Samba service. # Allwinner ## Disclaimer * **Only nightly releases are available right now. Use at your own risk!** * **Boards/STBs with less than 1GiB of RAM are not supported** ## Boards Supported ### **A64 based boards** * OrangePi Win * Pine64 * Pine64 LTS * Pine64 Plus ### **H3 based boards** * BananaPi M2+ * Beelink X2 * Libretech ALL-H3-CC (Tritium) * NanoPi M1 * OrangePi 2 * OrangePi PC * OrangePi PC plus * OrangePi Plus/Plus 2 * OrangePi Plus 2E ### H5 based boards * OrangePi PC 2 ### **H6 based boards** * Beelink GS1 * OrangePi 3 * OrangePi 3 LTS * OrangePi Lite 2 * OrangePi One Plus * Pine H64 * Tanix TX6 ### **R40 based boards** * BananaPi M2 Ultra # Amlogic LibreELEC images for Amlogic with modern Linux kernels use boot processes and device-tree files that are not compatible with older LibreELEC images (LE 9.x and earlier) that use Amlogic Linux 3.14 or 4.9 kernels. The change to boot processes means you cannot update from older releases and must make a new/clean installation. There are two images supporting Amlogic Gen10+ (64-bit) SoCs and older Gen8 (32-bit) SoCs used in a range of Linux SBC and Android STB devices: `AMLGX` supports the following 64-bit SoCs: * GXBB (S905) * GXL (S805X/S905X/D/W/L) * GXM (S912) * G12A (S905X2/D2/Y2) * G12B (S922X/A311D) * SM1 (S905X3/D3) `AMLMX` supports the following 32-bit SoCs: * Meson 8 (S805) * Meson 8b (S802) * Meson 8m2 (S812) > WeTek Play(1) aka WeTek OpenELEC uses Meson 6 (8726MX) hardware. There is little support for Meson 6 hardware in the upstream kernel and low probability of support evolving to the point where modern-kernel LibreELEC images are viable. Support ends with LibreELEC 9.0. `AMLGX` and `AMLMX` provide a "box" image for use with devices that run Amlogic (aka Vendor or Legacy) boot firmware (U-Boot 2015.01 with Amlogic and manufacturer customisations) and "board" images using modern boot firmware (mainline U-Boot) specific to a single SBC board or STB device. The image type can be identified by the filename `-suffix`: * `LibreELEC-AMLGX.arm-11.0.0-box.img.gz` is the `AMLGX` "box" image * `LibreELEC-AMLGX.arm-11.0.0-khadas-vim3.img.gz` is a "board" image for VIM3 * `LibreELEC-AMLMX.arm-11.0.0-box.img.gz` is a "box" image for Meson 8 devices ## Box Images Box images support SBC and STB devices with Android or "vendor" boot firmware running on the internal eMMC storage. LibreELEC is installed by triggering "recovery" mode boot in the Amlogic U-Boot firmware. Recovery mode searches for some standard files on SD and USB media. LibreELEC provides files tweaked to boot and run LibreELEC instead of recovering the device. Once recovery mode is activated the device will search and find LibreELEC on each boot; until Android recovery completes (which never happens). As `box` images can be used on many devices you must configure the device-tree file to use first. This is done by editing `uEnv.ini` in the root folder of the SD card. Change `@@DTB_NAME@@` to the name of the .dtb file to use. Current supported device-tree files are in the `dtb` folder. For example, here is the default `uEnv.ini` file: ``` dtb_name=/amlogic/@@DTB_NAME@@ bootargs=boot=UUID=2306-0801 disk=UUID=8268da37-3a8d-4f6d-aba0-08918faded56 quiet systemd.debug_shell=ttyAML0 console=ttyAML0,115200n8 console=tty0 ``` To boot a Beelink GT-King box change `@@DTB_NAME@@` to `meson-g12b-gtking.dtb` ``` dtb_name=/amlogic/meson-g12b-gtking.dtb bootargs=boot=UUID=2306-0801 disk=UUID=8268da37-3a8d-4f6d-aba0-08918faded56 quiet systemd.debug_shell=ttyAML0 console=ttyAML0,115200n8 console=tty0 ``` Once the device-tree name is set you can insert the SD card in the box and power on. Some box devices detect the presence of the SD card automatically. Others may need recovery mode to be triggered using a reset button on the device. Common locations for the button are: * Visible button marked "reset" or "recovery" or "power" button * Visible pin-hole on the underside of the case * Hidden button visible through ventilation holes in the case * Hidden at the end of the 3.5mm audio jack In most cases you will need a small pin, unfolded paper-clip, or toothpick to press the reset button with - hence the install process is often referred to as the "toothpick method" in forum posts. Press and hold the button, then power-on the box. After 5-7 seconds release the button to interrupt boot and start the recovery process. Due to differences in box speeds and vendor U-Boot the exact timing for button release varies and you will need to experiment to find the timing that works for your box. It is possible to see U-Boot output and remove the guesswork by attaching a UART serial cable to the board, although most set-top box devices will need connector pins soldering to the board as manufacturers omit them to save manufacturing costs. ## Board Images These images are built for Single Board Computer (SBC) devices which boot modern U-Boot via an SD card or removable eMMC module. Installation is normally simple requiring you to write the image to the SD card or eMMC module and boot the device. If the board has eMMC storage soldered (not on a removable module) it may be necessary to boot from the "box" image first. Once booted to a box image on SD card (so eMMC is not in use) you can write the correct `board` image to eMMC (overwriting Android or other factory-installed images) using `dd` to write the image. You can use the `emmctool` command to help that process (see below). ## Android Images If you are searching for an Android firmware image to recover/restore a set-top box please be advised that the project cannot help you. We have no interest in Android and Android images and do not have a secret stash of vendor firmware files. Please contact the original manufacturer of your box, or use their support forum, or (often best) search Android focussed community forums like 4pda. > The sole exceptions are the WeTek Hub and Play2 devices: we have the original Android firmware update files and raw 'dd' images of the internal storage of the boxes. ## installtointernal Community images using Amlogic Linux 3.14/4.9 kernels often include the `installtointernal` script to reconfigure the factory boot process and run LibreELEC from internal eMMC storage. We do not provide or support this script. There are two main reasons: 1. Amlogic uses a proprietary partitioning scheme that relocates partition data structures to non-standard locations. This is supported in Amlogic Linux kernels and Amlogic-modified versions of tools like parted, fdisk and fsck used to create and manage filesystems. It is not supported in modern upstream Linux kernels or modern versions of filesystem tools. This means the Linux kernel used in AMLGX images cannot read the offset partition data to mount (and repurpose) Android partitions as a persistent /storage area. 2. The script causes a high volume of support issues. When the script fails to modify the boot process or create partitions correctly the user ends up with a "bricked" box. Amlogic builds several factory-restore mechanisms into their software that mean it is always possible to recover the box, but this normally requires the user to find the correct Android image for the device and reflash it with a Windows OS tool that often has issues. Our forum staff are all volunteers who give time to the project for fun. Helping a never-ending stream of pissed-off inexperienced users recover bricked boxes is not fun, nor do we have a collection of Android images to use, so we actively discourage the existence and use of this script. In short: It was technically possible (but heavily discouraged) to use `installtointernal` with older LibreELEC images. It is NOT POSSIBLE to use `installtointernal` with AMLGX and running the script will either fail, or fail *and* break boot. To run LibreELEC from eMMC storage please purchase a supported "board" device. ## emmctool In the `AMLGX` image there is an eMMC helper script called `emmctool` that supports a range of useful functions for backup/write/erase (and more) for eMMC storage. See: ``` LibreELEC:~ # emmctool info: boot device is /dev/mmcblk0, U-Boot version is 2021.04 info: emmc device is /dev/mmcblk1 Model: MMC 8WPD3R (sd/mmc) Disk /dev/mmcblk1: 7818MB Sector size (logical/physical): 512B/512B Partition Table: gpt Disk Flags: Number Start End Size File system Name Flags 1 17.4kB 7818MB 7818MB ext4 EMMC_STORAGE usage: emmctool (w)rite : write .img/.img.gz to the eMMC module (b)backup : dump the emmc partition to an .img.gz file (d)etect : detect an eMMC module attached after boot (i)nfo : show info about the eMMC module (l)abels : change eMMC disk labels to / (r)esize : resize the storage partition to 100% (s)storage : convert emmc for use as /storage (boot from sdcard) (z)ero : zero (erase/wipe) the eMMC module (h)elp : displays this help message ``` The `emmctool` helper supports a limited range of SBC boards with eMMC modules. On a generic Android device it will output the (i) info only. # BananaPi M5 / M2S ## Enabling WiFi and Bluetooth BananaPi M5 and M2S have an optional WiFi mezzanine board with an RTL8822CS chip providing 802.11 b/g/n/ac on 2.4GHz/5GHz channels and Bluetooth 5.0 connectivity. The board is not active unless enabled through a device tree modification. On BPI-M5 create `/storage/.config/autostart.sh` with the following content: ```shell mount -o remount,rw /flash fdtput -t s /flash/meson-sm1-bananapi-m5.dtb /soc/sd@ffe03000 status okay fdtput -t s /flash/meson-sm1-bananapi-m5.dtb /soc/bus@ffd00000/serial@24000 status okay mount -o remount,ro /flash ``` On BPI-M2S create `/storage/.config/autostart.sh` with the following content: ```sh mount -o remount,rw /flash fdtput -t s /flash/meson-sm1-bananapi-m2s.dtb /soc/sd@ffe03000 status okay fdtput -t s /flash/meson-sm1-bananapi-m2s.dtb /soc/bus@ffd00000/serial@24000 status okay mount -o remount,ro /flash ``` After rebooting the board, the WiFi and BT devices should be detected: ```bash LibreELEC:/ # dmesg | grep rtw [ 8.547372] rtw_8822cs mmc2:0001:1: WOW Firmware version 9.9.4, H2C version 15 [ 8.548447] rtw_8822cs mmc2:0001:1: Firmware version 9.9.14, H2C version 15 LibreELEC:/ # dmesg | grep -i Blue [ 8.099139] Bluetooth: Core ver 2.22 [ 8.099306] NET: Registered PF_BLUETOOTH protocol family [ 8.099317] Bluetooth: HCI device and connection manager initialized [ 8.099538] Bluetooth: HCI socket layer initialized [ 8.099557] Bluetooth: L2CAP socket layer initialized [ 8.099797] Bluetooth: SCO socket layer initialized [ 8.272210] Bluetooth: HCI UART driver ver 2.3 [ 8.272242] Bluetooth: HCI UART protocol H4 registered [ 8.272930] Bluetooth: HCI UART protocol Three-wire (H5) registered [ 8.307537] Bluetooth: HCI UART protocol Broadcom registered [ 8.316217] Bluetooth: HCI UART protocol QCA registered [ 9.038966] Bluetooth: hci0: RTL: examining hci_ver=0a hci_rev=000c lmp_ver=0a lmp_subver=8822 [ 9.042736] Bluetooth: hci0: RTL: rom_version status=0 version=3 [ 9.042767] Bluetooth: hci0: RTL: loading rtl_bt/rtl8822cs_fw.bin [ 9.053947] Bluetooth: hci0: RTL: loading rtl_bt/rtl8822cs_config.bin [ 9.094258] Bluetooth: hci0: RTL: cfg_sz 33, total sz 36529 [ 9.518223] Bluetooth: hci0: RTL: fw version 0xffb8abd6 [ 9.574916] Bluetooth: MGMT ver 1.22 ``` # LaFrite LibreComputer LaFrite (AML-S805X-AC) is an S805X (GXL) board with 512MB or 1GB of RAM and 16MB SPI boot flash. The board runs upstream U-Boot from SPI, and has no SD card slot, so you can boot the AMLGX `box` or `lafrite` images written to a USB stick or eMMC module. Default boot order is: * SPI (built-in) * EMMC (optional module) * USB (socket furthest from the GPIO header) ### Run LibreELEC from eMMC LibreComputer preinstalls their eMMC modules with Android, so if you power on the board with the module attached it will always boot into Android. To erase Android or overwrite with LibreELEC the board must first boot from USB without the module attached. Once in LibreELEC booted from USB, the module can be attached, detected, and erased or imaged with the `lafrite` image: 1. Power on the Board, and boot the AMLGX `box` image from USB 2. Attach the eMMC module, and from the SSH console: 3. Run `emmctool d` to detect the module 4. Run `emmctool z` to erase (zero) the module 5. Copy the `lafrite` image to `/storage/` on the USB stick 6. Run `emmctool w /storage/LibreELEC-AMLGX.arm-11.0.0-lafrite.img.gz` to write the `lafrite` image to the eMMC module. 7. Power off the board, remove the USB stick 8. Power on the board, and LibreELEC will boot to eMMC and resize /storage ### Updating U-Boot in SPI LibreComputer provides [U-Boot firmware](https://boot.libre.computer/release/aml-s805x-ac/) files for updating the SPI flash. LibreELEC does not need a minimum version to boot, but newer U-Boot firmware fixes some graphical on-screen glitches seen in the early boot stages. To update: 1. Download the latest `aml-s805x-ac-spiflash.img` and flash it to a USB stick 2. Connect the USB drive to the socket furthest from the GPIO header 3. Power on the board 4. Current U-Boot checks if the new image matches existing firmware, and when it does not (as it is newer) the firmware will be updated. When complete: 5. Power off the board and remove the USB stick ### UART The debugging UART is accessible on the 40pin GPIO header: * TX (Green) on Pin 3 * RX (Grey) on Pin 5 * GND (Black) on Pin 6 # WeTek Hub/Play2 Installing LibreELEC to internal eMMC storage Create a bootable SD card using the `AMLGX` "box" image, then edit the `uEnv.ini` file in the root folder of the SD card and change `@@DTB_NAME@@` to `meson-gxbb-wetek-hub.dtb` or `meson-gxbb-wetek-play2.dtb` then save/eject and boot the box using the SD card. If you have been booting from SD card before it should automatically detect the card and boot into LibreELEC. If you have been booting from eMMC you may need to select "boot from SD Card" during boot. Once the box has booted into the "box" image you can download the latest WeTek "board" image and install LibreELEC to internal eMMC storage using `emmctool`. **This permanently overwrites the Android vendor OS with LibreELEC.** Find the URL for the relevant board image on the [download page](https://libreelec.tv/downloads/amlogic/). For example, the LibreELEC 11.0 image for the WeTek Play2 will be: ``` https://releases.libreelec.tv/LibreELEC-AMLGX.arm-11.0.0-wetek-play2.img.gz ``` Enable SSH and login, then run the following commands to download the board image to /storage and run `emmctool` to write (`w`) the `LibreELEC-AMLGX.arm-11.0.0-wetek-play2.img.gz` image to eMMC: ``` cd /storage wget https://releases.libreelec.tv/LibreELEC-AMLGX.arm-11.0.0-wetek-play2.img.gz emmctool w LibreELEC-AMLGX.arm-11.0.0-wetek-play2.img.gz ``` The `emmctool` utility will write the board image to eMMC, expand the /storage partition to 100% size and change the partition labels to `BOOT` and `DISK` to avoid name-clashing with the default labels used in the SD card image (so you can boot from SD card if needed). Once `emmctool` has finished, run `shutdown` and remove the SD card. Then cycle power to boot into LibreELEC running from the internal storage. # NXP - iMX6/iMX8 Current iMX6 images support the ARMv7-A dual-lite and quad versions (ARM Cortex-A9) of the following boards: * Cubox-i * Wandboard * Udoo Current iMX8 images are experimental and do not support a specific board. Installation is done by writing the LibreELEC \*.img file to an SD card. The boards have internal hardware identifiers so there is no need to edit `extlinux.conf` on the card. Selection of the correct device dtb is handled internally within U-Boot. **NOTE** - \*\*\*\* It is not possible to update from older LibreELEC or OpenELEC imx6.arm images to LE 11.0 as the boot configuration for LE 11.0 is different and older kernels do not support zstd compression. If you attempt an upgrade, the boot configuration of the old installation will be broken. You are advised to clean install LE 11.0 and manually restore sources and library DB files. Backups can be taken and restored, but as there is now a long time gap since LE 8.2.5 (and OE 8.0.x) it is best to start over with a clean system. # Intel x86-64 (Generic) The LibreELEC "Generic" image supports a (very) broad range of x86\_64 compatible hardware using AMD, Intel, and nVidia GPU hardware. The GPU in a device determines what media can be played using hardware decoding and modern features like HDR, and the CPU determines if any unsupported codecs can be software decoded for playback by ffmpeg. ## HDR HDR support in the Linux kernel, in Kodi, and in LibreELEC is ongoing "work in progress" that continues to evolve. HDR depends on a combination of the media format and colourspace properties, GPU hardware, HDMI output, and TV panel capabilities. Most users wrongly view HDR support like codec support, but it is significantly more complicated. Few people outside the broadcast media industry truly understand how it works (in theory and in practice) but we are fortunate to have users with that professional background providing testing and insightful feedback to the team as progress is made. As GPU hardware is one of the major variables, please read the AMD, Intel, and nVidia GPU sections below for further information relevant to HDR support on that GPU type: ## Intel GPUs Intel NUC and similar-sized Intel GPU devices are popular for building an HTPC device around since they combine well supported upstream GPU drivers with entry level Celeron and Core i3 chips to intermediate Core i5 and high-end Core i7 CPUs. Modern Intel GPUs have been shipping since "Nehalem" in 2010, and over time the number of different CPU and GPU generations and codenames have multiplied, making it confusing to figure out what media features a device can support. The following table is based on public sources like Wikipedia, and it indicates hardware features, which do not always translate into what Linux and Kodi currently support in software:
CPUCodenameDriverH264HEVCAV14KHDR
Gen1Nehalemi965YesNoNoNoNo
Gen2Sandy-bridgei965YesNoNoNoNo
Gen3Ivy-Bridgei965YesNoNoNoNo
Gen4Haswelli965YesNoNoNoNo
Gen5Broadwell, Braswelli915YesNoNoNoNo
Gen6Skylakei915YesYesNoDPNo
Gen7Kaby-lake, Apollo-lakei915YesYesNoYesHDMI
Gen8Coffee-lake, Kaby-lake refresh, Whiskey-lakei915YesYesNoYesHDMI
Gen9Coffee-lake refreshi915YesYesNoYesHDMI
Gen10Comet-lake, Ice-lake, Amber-lakei915YesYesNoYesYes
Gen11Rocket-lake, Tiger-lakei915YesYesYesYesYes
Gen12Alder-lakei915YesYesYesYesYes
Gen13Raptor-lakei915YesYesYesYesYes
* Gen6 CPUs (Skylake) have HDMI 1.4b and DisplayPort 1.2 connectors. HDMI can run at max 1920x1200\@60 resolution, while DP can run at max 3840x2160\@60 resolution. * Gen7 and Gen8 CPUs use an LSPCON chip for HDMI 2.0 output. HDR is supported only when the HDMI output is connected to an HDMI 2.0 port on the TV. Users with Intel NUC devices are recommended to run the latest Intel firmware for their device. Lots of bugs in original/factory LSPCON firmwares have been fixed. * Linux supports LSPCON chips for HDR from Linux 5.12 onwards * Linux has full support for Tiger-Lake CPUs from Linux 5.12 onwards * Intel GPUs are known as *Integrated graphics processors (IGPs)* and are embedded within the CPU core. Each CPU generation uses a single GPU generation but the generation ID's do not match, e.g. Gen10 CPUs have Gen11 GPUs. **LibreELEC 10.0 shipped with Linux 5.10 kernel support and Xorg graphics, so it does not have support for HDR or Gen11 hardware**. Community created LibreELEC 10.0 images with newer Linux kernels supporting Gen11 hardware and`GBM` graphics with experimental HDR patches can be downloaded from the LibreELEC forums. LibreELEC 11.0 use GBM graphics, include Kodi 20.0 support for HDR, and an updated kernel supporting Gen11, Gen12 hardware. ## AMD GPUs AMD GPUs are a popular option for users building custom HTPCs from motherboards without onboard Intel graphics. LibreELEC embeds two AMD drivers: `radeon` is used with older cards, and `amdgpu` is used with newer cards (starting from the 'Southern Islands' family). Determining media features (H264, HEVC, AV1, 4K, 4K60, HDR, etc.) is complicated due to the sheer number of different AMD cards available. Each new GPU generation ships with low-end cards limited in capabilities, and high-end cards with multiple connectors. Media features like 4K and HDR also have a dependency on connectors (HDMI or DisplayPort) and the standards the connectors support. For example, some cards support HDMI 1.4b and a max resolution of up to 3840x2160\@30 with 8-bit HDR output, while cards with DisplayPort 1.4 or HDMI 2.0 may support up to 3840x2160\@60 with 10-bit output. The most accurate source of information is [https://www.x.org/wiki/RadeonFeature](https://www.x.org/wiki/RadeonFeature/) ## nVidia GPUs LibreELEC v7.x - v10.x include two different nVidia GPU drivers; a "legacy" driver (340.xx) and the latest stable driver. The drivers provide `OpenGL` support via `Xorg` so Kodi can display a GUI on-screen, and Kodi supports`VDPAU` hardware decoding of H264 and some older SD era media codecs for efficient playback. Newer nVidia cards support 4K resolutions and `NVDEC` hardware decoding, but Kodi does not support `NVDEC`, and while Kodi can output 4K, nVidia VDPAU drivers have no support for HEVC or VP9 (the formats used with most 4K media) and there is no support for HDR. It is no surprise that project active-install stats show most nVidia installs are using the legacy nVidia driver, and the number of installs continues to decline over time: which means LibreELEC users are replacing older nVidia devices with something that does not use an nVidia GPU. This trend is not new and influences our technical decisions: LibreELEC v11.x has switched "Generic" from Xorg OpenGL graphics to the Mesa OpenGL and the same DRM PRIME video stack used with ARM SoC devices. A "Generic\_Legacy" image using Xorg is available, but if "GBM" image development continues to progress well our intention is to drop the legacy image in the future (and with it, nVidia support). In lieu of this: ***The team does not recommend users purchase nVidia hardware for use with Kodi*** LibreELEC v11.x "GBM" images are built with Mesa `nouveau` OpenGL support so nVidia users who upgrade will see Kodi on-screen. However `nouveau` has no ability to "reclock" modern nVidia GPUs so the card runs at its lowest clock frequency and performance is bad (too bad to be useful). This issue is caused by nVidia requiring the use of signed (closed-source) firmware to interact with newer card generations, and it is a problem with all modern nVidia cards and all Linux distributions. It means the `nouveau` driver only works with very old nVidia cards, and is not a long-term solution for nVidia support in LibreELEC. Update (Oct 2021): [nVidia has announced the latest drivers support GBM and Mesa](https://www.phoronix.com/scan.php?page=news_item\&px=NVIDIA-495.29.05-Linux). This will allow Kodi to render the GUI via Mesa OpenGL. It removes one technical blocker to LibreELEC supporting newer nVidia devices in future releases. However, it is not the only blocker. The latest driver uses `NVDEC` for hardware decoding so either Kodi would need to add support for `NVDEC` or nVidia would need to support `VAAPI` which is used by Intel and AMD. In theory `NVDEC` is not a big technical challenge to implement, but Team Kodi has an established policy of refusing to include more/new proprietary hardware-decoding APIs that complicate code maintenance. So far nobody on the current Kodi staff has volunteered to implement `NVDEC` support and run the gauntlet of getting it accepted and merged. Even if an attempt was successful (which is unlikely) it would not benefit the majority of LibreELEC users with older nVidia cards which still depend upon the legacy driver and `VDPAU` decoding. So the latest drivers and `NVDEC` support are not the long-term solution for nVidia support in LibreELEC either. NB: If (when) LibreELEC drops support for Xorg and nVidia users, it does not mean Kodi has dropped support. nVidia users can continue to use their nVidia card with Xorg and any desktop Linux distro that supports Kodi (Arch, Debian, Ubuntu, etc.) - although the long-term trend with desktop distros is to move away from Xorg to Wayland (which depends on Mesa) so the trend there is against nVidia too. In lieu of this, we say again: ***The team does not recommend users purchase nVidia hardware for use with Kodi*** ## Legacy Hardware Despite the range of devices that Generic x86\_64 images can run on, team development and testing has always been focused on current and recent hardware packaged for use as HTPC devices. Users frequently mistake the minimalist nature of LibreELEC as perfect for recycling an older device (laptops with a broken screen are a recurring theme) into a media player. You might be able to boot LibreELEC, but we are often missing hardware drivers for old hardware and the overall playback performance (and power consumption) of first generation Raspberry Pi boards is often way (way) better. As a general rule, project staff view any hardware over 7-8 years old as legacy hardware. If you do need to use legacy hardware; use an era-appropriate LibreELEC (or OpenELEC) image. ## i386 Support Support for i386 hardware was dropped between OpenELEC v5.x and v6.x in 2015 due to low numbers of users, and LibreELEC has no interest in resurrecting support. It is still technically possible to hack/restore i386 support into our buildsystem and self-build an i386 image since we support 32-bit ARM SoC devices and use 32-bit userspace with 64-bit ARM SoCs so most packages in are still 32-bit compilable with little or no tweaking. However, there are still a few packages that do need tweaking to restore i386 support, and there is no HOWTO guide that you can follow. Some users enjoy the intellectual challenge of figuring out how to restore i386 support, but i386 hardware is super low-spec for modern Kodi use and our recommendation is to invest in a Raspberry Pi board instead of spending tens or hundreds of hours on codebase archaeology. An inexpensive Pi board will give a better overall result, costs less to run, and be zero hassle to maintain over time. # Laptops How to disable the internal screen and force external HDMI/DP/VGA output LibreELEC images are targeted at common HTPC device hardware: typically small form-factor and single-board computer devices that are static/attached to a TV or AVR device. One characteristic of common target hardware is a single active display connection even if the hardware has several output connector options. Laptops are not target hardware devices for the project, but the "Generic" x86\_64 image(s) boot and run on a wide range of x86\_64 devices and some users recycle old laptops as their HTPC. Laptops normally support multiple active display outputs: the internal LCD screen plus one of the following: * HDMI * DisplayPort * VGA Some laptops can disable the internal screen and force display to an external output using BIOS configuration. Some detect whether the laptop lid is open or closed, and when closed output is automatically directed to an active external connector. Others require run-time switching using keyboard function keys, e.g. Fn+F7 but this needs software support in the OS, and since we are intentionally minimalist LibreELEC does not have that support. In most cases with multiple display outputs the internal display probes first and display output is directed there. In this scenario users need to manually edit kernel boot parameters to disable the internal display connector, allowing the external connector to be found and used instead. Enable SSH services and SSH into the laptop, then identify output devices: ```shell LibreELEC:~ # tail /sys/class/drm/*/status ==> /sys/class/drm/card1-eDP-1/status <== connected ==> /sys/class/drm/card1-HDMI-A-1/status <== connected ``` The above output shows two display "connectors" are active and connected: * eDP-1 = the internal screen * HDMI-A-1 = the external HDMI connector NB: Some laptops may use "LVDS-1" for the internal screen, and "VGA-1" for the external connector. Next we make the boot partition writeable so boot parameters can be edited: ```shell mount -o remount,rw /flash ``` Now we edit them in the nano text editor: ```shell nano /flash/syslinux.cfg ``` Connectors are disabled by adding `video=` options, e.g. `video=eDP-1:d` will disable the eDP-1 connector allowing HDMI-A-1 to be used instead. In the example below the APPEND line has been modified to disable the eDP-1 connector: ```sh APPEND boot=UUID=10B4-4A77 disk=UUID=93786be3-5652-e2f498d33733 quiet video=eDP-1:d ``` After adding the details for the connector, you need to disable, save (ctr+o) and exit (ctrl+x) then `reboot` to test the change. On restart, the external connector should be the only active connector and Kodi should appear on the external display device. As the output capabilities of the external connector will be different to the internal screen, you may need to adjust the Kodi desktop resolution in Kodi display settings to match e.g. 720p or 1080p output. # Qualcomm Dragonboard 410c support exists in LibreELEC as open-source `freedreno` drivers provided a stable Linux reference implementation of stateful V4L2m2m uAPI usage, allowing Team Kodi developers to evolve support for GBM and EGL/DRMPRIME rendering with zero-copy hardware decoding, which is now the foundation for future support of Kodi on Linux. Kodi runs well on the Dragonboard 410c due to mature support in the Linux kernel and ffmpeg, but it is a expensive board to purchase and rather fiddly to flash with a LibreELEC image, so is not hardware the project staff recommends. Device support remains in the buildsystem for occasional reference testing of changes and we do not provide release images. # Raspberry Pi ## HEVC on LibreELEC 9.2.x and 10.x or newer The following table summarises LibreELEC support for HEVC media on different Raspberry Pi hardware generations: | Device | 9.2.8 | 10.x and newer | | -------------------- | --------------------------- | ------------------------- | | Raspberry Pi 0/1 | Not supported | Not supported | | Raspberry Pi 2/3 | Up to 1080p in Software | Up to SD in Software | | Raspberry Pi 4 / 400 | Up to 4K, basic HDR (8-bit) | Up to 4K, 8/10/12-bit HDR | | Raspberry Pi 5 | Not supported | Up to 4K, 8/10/12-bit HDR | Raspberry Pi 4, 400, and 5 are the ONLY devices with native hardware decoding of HEVC content, and in LE10 and newer releases (LE11 for RPi5) we support 8/10/12-bit output for great results with 4K HDR material. Note that the original LE 9.2.9 release for RPi4/400 devices only supports 8-bit output for basic playback. Older Raspberry Pi devices support only software decoded HEVC. In practice Raspberry Pi 3 devices running LE 9.2.x with mild overclocking can play lower-bitrate 1080p content without issues, but if media has higher bitrates and larger filesizes you should expect poor results. Raspberry Pi 2/1/0 models can normally manage 720p media but will struggle with 1080p. LibreELEC 9.2.x runs best on older Raspberry Pi hardware because the video pipeline in Kodi v18 supports vendor proprietary hardware decoding methods (MMAL and OMXplayer) and custom optimisations for software-based HEVC decoding on Pi hardware. The optimisations for HEVC are very clever, but also require a large and invasive patch (more than 50,000 lines of additional code for FFMpeg). The complexity and Raspberry Pi specific nature of the optimisations has prevented them from being accepted upstream into FFMpeg, and few Linux distributions have allowed such a large patch into their codebase. Kodi v19 (LibreELEC 10.x) also removed support for vendor proprietary hardware decoding methods (on Raspberry Pi, the MMAL and OMX decoders) to focus on a standards-based approach (V4L2, named for the Linux kernel 'Video for Linux v2' API used). LibreELEC 10.x also dropped support for Raspberry Pi Zero and other 512MB RAM devices as 1GB is now considered as the minimum RAM needed for a good Kodi experience. The Raspberry Pi Foundation have rewritten their video drivers and FFMpeg support to follow the common V4L2 frameworks. As their goal is to upstream all driver and player-app changes, allowing them to be included and used with all Linux distros, the rewrites do not include the custom HEVC optimisations that would never be accepted. This means HEVC support on Raspberry Pi 4, 400, and 5 hardware is excellent as these devices support native HEVC hardware decoding, and the newer drivers support 8/10/12-bit output for better 4K HDR, but playback on older Pi 0/1/2/3 devices will be challenging as FFMpeg software decoding is no longer as-optimised for Pi hardware, and users can expect SD media support only, not HD (720p and 1080p) support as seen with older LibreELEC releases. In summary: **If you need HEVC support on older Raspberry Pi 0/1/2/3 hardware use LibreELEC 9.2.x and do not update to LibreELEC 10.x or newer releases.** **If you have Raspberry Pi 4 or 400 hardware, use LibreELEC 10.x or newer to benefit from better HEVC and 4K HDR support. Raspberry Pi 5 devices require LE11.x or newer.** ## Composite Output LibreELEC images for all Raspberry Pi boards ship pre-configured for HDMI output. Two simple changes are required to switch the image into Composite mode: First, edit `config.txt` in the root folder of the SD card to comment out `include distroconfig.txt` and uncomment `include distroconfig-composite.txt` , e.g. the comments should look like this: ``` #include distroconfig.txt include distroconfig-composite.txt ``` Second, edit `cmdline.txt` in the root folder of the SD card to configure PAL or NTSC output. This is done by appending a `video=Composite-1` option to the line of boot params in the file. Append to the existing single line; do not add them on a new/separate line. The two options are: * `video=Composite-1:720x576@50ie` for PAL output * `video=Composite-1:720x480@60ie` for NTSC output Boot after saving the changes and HDMI will be disabled and Composite enabled. You may also need to adjust audio output preferences in Kodi as the pre-configured default is for HDMI. # Rockchip # Samsung (Exynos) Odroid XU4 and XU3 boards can run the `Exynos` image which uses a current upstream Linux kernel with a mesa/panfrost open-source graphics pipeline and the latest Kodi version. H264, H263, VP8 and other older codecs are supported. XU4/XU3 do not have HEVC or VP9 support and cannot handle software decoding those formats. Note: The Samsung S5-MFP decoding drivers regressed after Linux 5.4 when a cleanup was done on the driver that removed functionality. The original plan was to restore function in later changes, but this never happened. Due to the age of the boards now, is unlikely to happen. You may find the Linux 5.4 kernel images in the HardKernel forums are more functional. `Exynos` images are designed to boot and run from SD card, but can also boot from an eMMC module if upstream u-boot is installed to the `/dev/mmcblk1boot0` or `/dev/mmcblk1boot1` partitions. The boot process requires `extlinux` support so will not work with the older vendor u-boot versions that sometime ship pre-installed on XU4 eMMC modules. # Virtual Image The project builds an OVA version of the Generic (x86\_64) imported which can be imported into current versions of vmware Workstation, Fusion (on Intel macOS hardware), and vSphere (ESXi). The OVA exists to support project team-member development activities, e.g. functional testing of userspace changes and the LibreELEC settings add-on without needing to use HTPC hardware. We have never formally supported running LibreELEC in a hypervisor. This is mainly because none of the active project maintainers do this, so when software breakage to the OVA occurs the break often goes undiscovered and unfixed for many months (until the next time some development needing it takes place). As we do not support the current VMware oriented OVA image, there are no plans to extend virtual image non-support to include Hyper-V, KVM, QEMU or any other hypervisors. # 4K / HDR This page explains the configuration points: * Desktop Resolution * Modeline Whitelist * Adjust Refresh * Deinterlacing * 4K60 Support * HDR Questions ### Desktop Resolution The primary impact of the Kodi desktop resolution is GUI performance, or how Kodi feels when you navigate around menus and libraries. Kodi leverages GPU hardware to accelerate rendering of GUI elements, but fanart and thumbnails are frequently adapted from original artwork on-the-fly as you scroll around, and even when all images have been pre-processed, they must still be read from disk caches before being displayed. Higher levels of CPU and I/O activity from larger artwork and media also mean higher power consumption from the HTPC device. The second impact of the Kodi desktop resolution is how media is scaled. If "Adjust Refresh" is not enabled, Kodi will scale all media played up or down to the desktop resolution and refresh rate, which by default is 1080p @ 60 fps. Scaling SD and 720p media up to 1080p while adding extra frames to match 60fps is handled well, as Kodi simply needs to duplicate frames to reach the higher fps rate, and the simple scaling algorithms Kodi uses to reduce artefacts in the upscaled image move smaller amounts of data in/out of memory. Hardware as low-spec as the first generation Raspberry Pi can normally manage this well. Scaling SD and 1080p media to 4K is a literally bigger challenge. Frame sizes for 4K media are 4x the size of 1080p so the amount of data being processed in/out of memory increases and the CPU resources needed also increase. Scaling 4K to 1080p is a larger challenge again. Source 4K media has huge frame sizes and sophisticated (down)scaling algorithms are required to create a lossy image without massive visual artefacts. Higher-spec Intel CPU devices with recent Core i7 chips and SSD storage can normally run the Kodi GUI at 4K with 60fps refresh rates and scale media with reasonable quality, but older and lower-spec Intel CPU devices and anything running from a spinning HDD or removable USB/SD media will struggle with a 4K desktop. This also includes ARM SoC devices. They might be capable of displaying the Kodi desktop in 4K but the experience is poor since they don't have the memory bandwidth or CPU speeds to process the data volumes needed. However, all 4K resolution TV's have dedicated scaling hardware with sophisticated algorithms to upscale 1080p images to the native 4K resolution of the screen. TVs do this better and much more efficiently than Kodi can scale images itself. **Recommendation: Keep the Desktop resolution at 1080p, with 60fps refresh rate. Allow Kodi to upscale SD media to HD, and let the TV handle 1080p upscaling to 4K** ### Mode Whitelist Most 4K televisions support a broad range of resolutions and refresh rates to support different media standards. In Linux each output format is known as a "modeline" and Kodi allows you to configure a list of allowed modes to use in combination with the "Adjust Refresh" option. Some hardware supports 4096x2160 modes. Kodi evaluates the whitelist using the height (2160) and refresh rate, so if you include these in your whitelist selection Kodi will switch to them instead of 3840x2160 modes which are an exact or more accurate match with 4K streaming media. If you see black bars on the sides of 4K media while playing, remove 4096 modes from the whitelist. **Recommendation: Configure Kodi to allow the following modes, if available:** * **3840x2160 @ 60/59.94/50/30/29.97/25/24/23.976** * **1920x1080 @ 60/59.94/50/24/23.976** ### Adjust Refresh Kodi can either upscale media to match the desktop resolution and refresh rate, or switch to a resolution and rate that exactly or better matches the media. Switching to match the rate can eliminate or minimise the need for Kodi to make corrections (to keep things in-sync) by adding or dropping frames. Adding frames to the stream is generally harmless and rarely causes noticeable artefacts, but dropping frames causes skips, glitches and audio pops. Kodi has three "Adjust Refresh" settings: * Off (scale media to the desktop resolution/rate) * On start/stop (change resolution/rate when playback starts and stops) * Always (change on start/stop and during playback if the media changes resolution/rate) **Recommendation: Set the Adjust Refresh setting to "On Start/Stop"** ### Deinterlacing 4K media is progressive so this is not a requirement for 4K or HDR playback, but many Kodi users have DVB setups where interlaced streams are common so we need to set the mode whitelist to support them. The challenge with interlaced media is: * Kodi cannot output interlaced frames, it always outputs progressive frames * Kodi cannot detect media is interlaced until you start playing it Kodi converts interlaced media for progressive output by doubling the original refresh rate and rendering each half-frame in its own full frame, e.g. PAL 1080i @ 25fps media becomes 1080p @ 50fps, and NTSC 1080i @ 29.97 becomes 1080p @ 59.94fps. For this rate doubling to work, we need to ensure the whitelisted 1080p modes do not contain 1080p @ 25/29.97/30Hz rates, else Kodi will see an exact match against resolution and refresh rate and you will see high CPU loads and 50% of frames being dropped. If the modes are removed, Kodi will use 50Hz/59.94Hz rates, and if the media is interlaced, Kodi can still render 100% of the frames. **Recommendation: Remove 1080 @ 30, 29.97 and 25 fps rates from the Modelist** ### 4K @ 60Hz Successful 4K output at 60Hz depends on HDMI output capabilities from the HTPC device, certified cables that can provide the higher bandwidth required for higher bit-depth video and higher bit-rate audio, HDMI input ports on the TV or AVR that match the outputs from the HTPC, and media that aligns to the hardware capabilities. Common problems that we see include: * Some TV's and AVR's support different HDMI capabilities on different ports. Some support 4K60 4:2:2 (12-bit) input on specific ports, while other ports support 4K60 4:2:0 (8/10-bit) input. * Some TV's and AVR's require 4K60 4:2:2 capabilities to be enabled in TV settings else the port defaults to 4K60 4:2:0 input. There is no standardised naming among vendors so we have seen "Deep Colour" and "Enhanced HDMI" used to describe 4K60 4:2:2 support. * Raspberry Pi 4/5 boards notably do not support 4K60 4:2:0 output. If the TV or connected port only supports 4K60 4:2:0 input the 4K60 modes will (correctly) not be available. * Raspberry Pi 4 boards need configuration in `/flash/config.txt` to enable 4K @ 60/59.94/50 mode output. This is not enabled by default because it increases power consumption, and as most media uses 4K\@30/23.976 most users do not need to enable 4K60 modes. * Raspberry Pi 5 devices support 4K60 output by default and do not require `/flash/config.txt` configuration. This is one reason why Raspberry Pi 5 boards require a higher rated PSU. If you do not need 4K60 output most 5V/3A PSU's used with RPi4 work fine with an RPi5 too. * 4K @ 60/59.94/50 modes require an HDMI 2.0 cable that supports the much higher bandwidth needed. Suitable cables are normally sold as 4K\@60 "certified" cables. Cheaper and lower-spec cables that support HDMI 1.4 modes (up to 4K\@30) are a frequent cause of "I've enabled 4K\@60 but have a blank screen" issue reports in the forums. **If you are unable to use 4K60 modes: please check cables, check port capabilities, and if using SBC boards; check the PSU can handle the needed current draw before reporting issues in the forums!** ### HDR Broadcast and Internet media follow a multitude of formal standards for resolution, refresh-rate, bit-depth, video format and colour-space. HDR formats add static or dynamic metadata to the stream or even individual video frames to enhance how colours are displayed. Kodi on Linux can support static HDR formats like HLG and HDR10, but not dynamic (proprietary) formats like HDR10+ and Dolby Vision which do not have open-source implementations. Users should understand HDR is not a simple "My TV can do 4K" type standard. HDR is a collection of competing technical standards (format wars are in progress) and the number of variables that must be determined and processed to render something nice looking on screen is huge. Kodi aims to hide the mind-bending complexity of choosing how HDR media will be displayed on screen by detecting what your HTPC device and TV support and what the media to be played requires, allowing the display pipeline to automatically configure itself for the best result; whether that is an exact match or the best compromise. Kodi and LibreELEC support for HDR formats is still in early stages. **Recommendation: There is nothing specific to configure for HDR itself (only 4K things) so sit back and enjoy that Kodi and LibreELEC developers are working to bring HDR support to your living room, for free. Please be patient, because it's a long and complicated task!** Here are some answers to common HDR questions: * Kodi does not support HDR to SDR conversion (tonemapping) on Linux. If you play HDR media on a TV that does not support HDR, it will often play but colours will be muted and washed out. In the future Kodi may support conversion, but it is not currently implemented. * Kodi has no way to present OSD menus in SDR when playing HDR media, so menus will have bright saturated colours. In the future, plane based tonemapping may be able to correct this, but it is not currently implemented and not all hardware supports multiple planes. * Kodi will attempt to output in the highest bit-depth supported by the display pipeline, e.g. on a Raspberry Pi 4 it will attempt 12-bit before falling back to 10-bit, then 8-bit. Not all 4K HDR capable hardware supports higher 12-bit and 10-bit depths. * Kodi supports Dolby Vision under Android (if the device is licensed for it) but not Linux. Dolby requires manufacturers to license their Intellectual Property and use integration libraries to decode the HDR metadata. Until FFMpeg comes up with a "clean room" reverse engineered open-source implementation, Kodi will not support it. # Blu-ray Playback No official Blu-ray player software exists for Linux, but open-source libraries allow Kodi (on LibreELEC) to play most Blu-ray discs once `/storage/.config/aacs/KEYDB.cfg` has been populated with a flat-file database of known encryption keys and certificates. To avoid legal issues with DMCA laws in the USA we cannot pre-configure a key database, so you must install this yourself. Connect to your LibreELEC device via SSH, then run the following commands: ``` mkdir -p /storage/.config/aacs curl -k -L http://fvonline-db.bplaced.net/fv_download.php?reduced -o /storage/.config/aacs/keydb.zip unzip /storage/.config/aacs/keydb.zip -d /storage/.config/aacs/ mv /storage/.config/aacs/keydb.cfg /storage/.config/aacs/KEYDB.cfg rm /storage/.config/aacs/keydb.zip ``` The current file contains PK, HC, VUK and UK data required for attempting disc decryption with more than 170,000 titles. Periodically running the commands will refresh the `KEYDB.cfg` file and add support for new Blu-ray discs. {% hint style="info" %} For a more detailed description on how Blu-ray DRM works on Linux, please refer to this article on the Arch Linux wiki: {% endhint %} # Config.txt On Raspberry Pi hardware, the `config.txt` file is used to configure boot and hardware configuration, similar to how the BIOS or UEFI are used on an PC. ## Editing config.txt There are two options for editing `config.txt`: over the network using SSH or removing the storage medium (SD card, USB drive) and editing the file directly on your computer. ### Editing via SSH `config.txt` is usually on the `/boot` partition in Raspberry Pi OS. In LibreELEC, the `/flash` boot partition is read-only by default, so we need to remount it in read-write mode: ``` mount -o remount,rw /flash ``` We will use the `nano` text editor to modify the file. Save changes with `ctrl+o` and exit using `ctrl+x`: ``` nano /flash/config.txt ``` After editing, set the `/flash` partition back to read-only mode: ``` mount -o remount,ro /flash ``` Finally, reboot for the changes in `config.txt` to be applied: ``` reboot ``` ## Editing on your computer Turn off the Raspberry Pi, remove the SD card or USB drive on which LibreELEC is installed, and use a card reader connected to your Windows, Linux, or macOS computer. If using Windows, use a text editor capable of saving text files in Unix format, e.g. [Notepad++](https://notepad-plus-plus.org/downloads) or Wordpad.exe (not Notepad.exe). ## Adding codec licenses or specific hardware HATs ### MPEG2 and VC-1 Licenses * Raspberry Pi 0/1/2 cannot hardware-decode MPEG2/VC-1 media files without a license key that can be purchased from the [Raspberry Pi Foundation](https://codecs.raspberrypi.com/license-keys/). The hardware is too slow to software decode these formats without the keys. * Raspberry Pi 3 hardware has higher spec CPUs and is capable of software-decoding without the licenses, although purchasing them allows hardware-decoding and your device will run cooler. * Raspberry Pi 4 is capable of software decoding these formats and license keys are not available. To purchase license keys you need the serial number of your Raspberry Pi. This can be read with the following command: ``` cat /proc/cpuinfo ``` Edit `config.txt` as described above, uncommenting the license key lines by removing the `#` marks, and replacing `00000000` with the keys you received after purchasing: ``` decode_MPG2=0x00000000 decode_WVC1=0x00000000 ``` Reboot and confirm the license keys are installed correctly by running these commands: ``` vcgencmd codec_enabled MPG2 vcgencmd codec_enabled WVC1 ``` If the licenses are enabled you should see this: ``` MPG2=enabled WVC1=enabled ``` If any key that you purchased shows `disabled` check that: * You entered the correct serial number * You added the licence key to `config.txt` correctly * You uncommented the lines in `config.txt` by removing the `\#` mark (and space) * You rebooted before testing ### Overlays for HATs and extra hardware Raspberry Pi kernels use a board-specific device-tree file to describe the board's hardware and how things are connected. As the Raspberry Pi is designed to be extended with extra hardware via HATs and peripheral connectors the kernel also supports device-tree "overlay" files. When configured, these overlay "fragments" of device-tree content that describe the extra hardware on the board device-tree, and the kernel reads them as a single combined file. Overlays can be found in `/flash/overlays` and they are configured in `config.txt` in the root folder of the SD card that you boot the Raspberry Pi from. The following are examples of common overlay changes. #### Audio Interfaces ``` dtoverlay=hifiberry-dac dtoverlay=hifiberry-dacplus dtoverlay=hifiberry-digi dtoverlay=hifiberry-amp dtoverlay=iqaudio-dac dtoverlay=iqaudio-dacplus ``` On RPi 5, using Libreelec 12 and upwards, different audio interfaces are needed: ``` dtoverlay=hifiberry-dacplus dtoverlay=hifiberry-dacplus-std dtoverlay=hifiberry-dacplus-pro ``` With kernels older than 6.1.77 on RPi 5, "slave" mode must be forced: ``` dtoverlay=hifiberry-dacplus,slave ``` #### Infra-Red Receivers ``` dtoverlay=gpio-ir ``` Override defaults for the gpio-ir module: ``` dtoverlay=gpio-ir,gpio_pin=25,gpio_pull=up,rc-map-name=rc-technisat-usb2 ``` #### Optional hardware interfaces ``` dtparam=i2c1=on # for later RPi's dtparam=i2c0=on # for early RPi's dtparam=spi=on ``` ## Overclocking Please see [the Raspberry Pi documentation](https://www.raspberrypi.com/documentation/computers/config_txt.html#overclocking-options) for more details on overclocking. # Cron cron can be used to schedule timed event execution of binaries and scripts, e.g. download of EPG guides on a repeating time interval (hourly, every 12 hours, etc.) or running a nightly backup script in the background at 2am. Running `crontab -e` will open the root user crontab in `nano` allowing you to paste content your cron commands. Use `ctrl+o` to save the file and `ctrl-x` to exit nano. For more info on cron commands, see: # Dual Boot It is technically possible to dual-boot LibreELEC alongside an existing Windows or Linux installation, but the installation process is complex and less experienced users are prone to mistakes that result in their main Desktop OS and personal data being wiped from the hard drive. LibreELEC installers assume a dedicated disk target and cannot install into a spare partition or free space on the same drive that boots the Desktop OS. For this reason the project staff do not encourage or support dual-boot configurations. If you choose to attempt one and things go wrong, you were warned! # EDID ## Custom EDID To change the order of turning on your devices (normally your HTPC has to be powered on last) or to use your LibreELEC device without the TV turned on, you need to dump/save the EDID information from your TV (or AVR). In the steps below we will explain how this can be done: **Note:** Your devices should all be turned on and you should have a screen and audio working. Otherwise the EDID information isn't provided properly and this How-To won't work. In the sections below we explain different ways to dump and use the EDID information. We also provide a script which performs the specific steps for the various devices automatically. On x86\_64 the steps for Intel and nVidia based GPUs differ significantly from each other. ## Generic x86\_64 **Note:** This script will also only work for Intel or nVidia based GPUs. AMD/ATI GPU's are not supported. To use the getedid script you need to have SSH access to your LibreELEC machine. Once you are in, just type in ``` getedid ``` to see which options are available. It will look like this. ![](/files/-MMfAHRSCXupi7KY6YTG) The available options are `create`, `gpu`, `delete` and `help`. These are explained below. #### getedid help This will show a help message and a little explanation for the specific options. #### getedid gpu This will check which GPU you are using and you will either get "Intel", "NVidia" or "GPU is not supported" after running that command. #### getedid create This will do all needed steps which are needed to dump the EDID for the GPU you are using. It first checks if the GPU is supported, then it checks if you already have done changes to the files which the script needs to change, too. If you already have done some changes to those files, the script will stop and you should dump the EDID manually. Those steps are explained in the other tabs. The reason for that is, that we can't know what you already have changed and therefore the script might do something horrible wrong and we don't want to break your system. As you already know how to edit those files it should not be that hard to do that again. If the files are like they should be from a vanilla installation, the script does its thing and will do everything which is necessary and reboot your machine after everything is done as expected. After that you shouldn't take care about the ordering how to turn on your devices, anymore. Your HTPC should also be turned on as the first device in the chain now. #### getedid delete This will delete all the created files from `getedid create` if you have used it before. After using `getedid delete` the default configuration is restored. No unneeded files on it, everything is like a vanilla installation and you have to take care about the ordering how to turn on your devices again. For the source of that script please look at: ### Intel #### Get the needed information about your system First, you have to SSH in your LibreELEC machine. Then enter the following command. ``` tail /sys/class/drm/*/status ``` Look for the connected device: ![how it looks like at the shell](/files/-MMfAOuZssX4hIDQ2uoj) ``` ==> /sys/class/drm/card0-HDMI-A-2/status <== connected ``` The information we need **HDMI-A-2** is connected. #### Create the EDID file Now we will create a copy of the EDID binary data and put it where it needs to go. Change the cat command to match the active HDMI/DP port. For the possibility to copy and paste the correct commands, change the tabs below to the matching port. ``` mkdir -p /storage/.config/firmware/edid ``` HDMI-A-1 ``` cat /sys/class/drm/card0-HDMI-A-1/edid > /storage/.config/firmware/edid/edid.bin ``` HDMI-A-2 ``` cat /sys/class/drm/card0-HDMI-A-2/edid > /storage/.config/firmware/edid/edid.bin ``` Next a cpio archive file will be created which will be loaded at boot. ``` cd ~ mkdir -p cpio/lib/firmware/edid cp .config/firmware/edid/edid.bin cpio/lib/firmware/edid/ cd cpio/ find . -print | cpio -ov -H newc > ../edid.cpio ``` #### Editing the extlinux.conf or syslinux.cfg Now mount the boot partition as "RW" and move the file to it ``` mount -o remount,rw /flash mv ../edid.cpio /flash/ ``` After the file is moved to the correct place, we have to add some boot parameters. For this we have edit either the "extlinux.conf" or the "syslinux.cfg" file in your /flash/ directory. Use this command to check which one is available. ``` ls /flash/ ``` Search for "extlinux.conf" or "syslinux.cfg" and edit it. Only one of them is available. **syslinux.cfg** ``` nano /flash/syslinux.cfg ``` **extlinux.conf** ``` nano /flash/extlinux.conf ``` Note: If you are not using LibreELEC 9.0 or newer please use nano -w instead of nano Add to the APPEND line the following things. HDMI-A-1 ``` initrd=/edid.cpio drm.edid_firmware=edid/edid.bin video=HDMI-A-1:D ``` The APPEND line should look this like this after (everything in a single line): ``` APPEND boot=LABEL=System disk=LABEL=Storage ssh quiet initrd=/edid.cpio drm.edid_firmware=edid/edid.bin video=HDMI-A-1:D ``` HDMI-A-2 ``` initrd=/edid.cpio drm.edid_firmware=edid/edid.bin video=HDMI-A-2:D ``` The APPEND line should look this like this after (everything in a single line). ``` APPEND boot=LABEL=System disk=LABEL=Storage ssh quiet drm.edid_firmware=edid/edid.bin video=HDMI-A-2:D ``` Last step is to reboot the device. ``` reboot ``` ### nVidia If you boot your nVidia GPU based LibreELEC box before the TV/AVR and you see a black screen on boot - follow this guide to create an edid.bin file that tricks Xorg into thinking the TV/AVR are powered on at boot time. **Note:** This example will NOT work on Intel or AMD GPU's. #### Get the needed information about your system Open an SSH session to your LibreELEC machine. Once logged into the console we need to work out the DFP number. ``` grep ": connected" /var/log/Xorg.0.log | head -n 1 ``` You should see message like the following: ``` [3241512.110] (--) NVIDIA(0): SAMSUNG (DFP-0): connected ``` Note the DFP number - in this example it is "DFP-0" but yours may be different. #### Set Xorg to Debug Mode To extract EDID data we need we need to place Xorg into debug mode. First we stop Xorg. ``` systemctl stop xorg.service ``` Next we clone the xorg.conf to the config override location in `/storage/.config`. ``` cp /etc/X11/xorg-nvidia.conf /storage/.config/xorg.conf ``` Then we edit the file with `sed` to enable debug mode. ``` sed -i 's/"ModeDebug" "false"/"ModeDebug" "true"/g' /storage/.config/xorg.conf ``` The device section in the modified file should look something like this. ``` Section "Device" Identifier "nvidia" Driver "nvidia" Option "DynamicTwinView" "False" Option "NoFlip" "false" Option "NoLogo" "true" Option "ConnectToAcpid" "0" Option "FlatPanelProperties" "Scaling = Native" Option "ModeValidation" "NoVesaModes, NoXServerModes" Option "HWCursor" "false" Option "ModeDebug" "true" EndSection ``` Now restart Xorg. ``` systemctl start xorg.service ``` #### Create the EDID file Extract the RAW binary EDID information from the debug /var/log/Xog.0.log to a file. ``` nvidia-xconfig --extract-edids-from-file=/var/log/Xorg.0.log --extract-edids-output-file=/storage/.config/edid.bin ``` The command should output something like. ``` Found 1 EDID in "/var/log/Xorg.0.log". Wrote EDID for "ONK TX-NR616 (DFP-0)" to "/storage/.config/edid.bin" (256 bytes). ``` #### Edit xorg.conf Now we edit /storage/.config/xorg.conf - set ModeDebug back to False (edit the word true to false) and uncomment the following lines. ``` Option "ConnectedMonitor" "DFP-0" Option "CustomEDID" "DFP-0:/storage/.config/edid.bin" Option "IgnoreEDID" "false" Option "UseEDID" "true" ``` Make sure you change the DFP number to match the one we found earlier. In the end your config will look something like. ``` Section "Device" Identifier "nvidia" Driver "nvidia" Option "DynamicTwinView" "False" Option "NoFlip" "false" Option "NoLogo" "true" Option "ConnectToAcpid" "0" Option "FlatPanelProperties" "Scaling = Native" Option "ModeValidation" "NoVesaModes, NoXServerModes" Option "HWCursor" "false" Option "ModeDebug" "false" Option "ConnectedMonitor" "DFP-0" Option "CustomEDID" "DFP-0:/storage/.config/edid.bin" Option "IgnoreEDID" "false" Option "UseEDID" "true" EndSection Section "Screen" Identifier "screen" Device "nvidia" DefaultDepth 24 Option "ColorRange" "Full" # Option "ColorRange" "Limited" # Option "ColorSpace" "RGB" SubSection "Display" Depth 24 EndSubSection EndSection Section "Extensions" Option "Composite" "false" EndSection ``` Finally we stop/restart xorg.service to disable debug mode and use the new edid.bin file. ``` systemctl restart xorg.service ``` If all has gone to plan Xorg now detects the EDID file and the order of powering on equipment no longer matters! ## Amlogic (Legacy) Amlogic legacy kernel devices (using 3.10, 3.14 kernels) do not capture "edid.bin" files like Intel and nVidia devices, but a similar process can capture, store and force the resolutions of a device. Connect your HTPC device directly to the HDMI source that you want to capture EDID information from, then login over SSH and run the following command. ``` cat /sys/class/amhdmitx/amhdmitx0/disp_cap > /storage/.kodi/userdata/disp_cap ``` This stores a list of the supported resolutions. It looks like ``` 480p60hz 480p_rpt 576p50hz 720p60hz 1080i60hz 1080p60hz 720p50hz 1080i50hz 1080p30hz 1080p50hz 1080p25hz 1080p24hz 2160p30hz 2160p25hz 2160p24hz smpte24hz smpte25hz smpte30hz smpte50hz smpte60hz smpte50hz420 smpte60hz420 2160p50hz 2160p60hz 2160p50hz420 2160p60hz420 ``` To remove or add specific resolutions, e.g. if 1080p24hz is missing, edit disp\_cap. ``` nano /storage/.kodi/userdata/disp_cap ``` Ctrl+o to save, Ctrl+x to exit the nano editor. Next restart Kodi by rebooting the box or running. ``` systemctl restart kodi ``` ## Raspberry Pi The getedid script can be used as described for [Generic x86\_64](#generic-x86_64). # Fonts Kodi includes a default font that supports a large number of languages in a reasonable file size. It does not support all languages as this would require a font file larger than a LibreELEC image! If you see blank squares for titles and filenames instead of readable text - You need to add a custom Arial True-Type (.ttf) font that supports the missing language characters and glyphs. In LibreELEC create `/storage/.kodi/userspace/Fonts/` (note the capital F) and place an Arial based font in the folder, e.g. `/storage/.kodi/userspace/Fonts/Arial.ttf` - after rebooting or restarting Kodi the font can be selected in Kodi Settings > Interface > Skin > Fonts. # Hidden WiFi WiFi networks with a hidden SSID are not visible to the connection manager (ConnMan) so cannot be selected in the LibreELEC settings add-on, and even if you manually configure a new ConnMan network profile via SSH, ConnMan cannot see the network to use the stored profile to connect. LE10 and older use ConnMan to manage connections and `wpa_supplicant` to create the actual connection. LE11 also use ConnMan to manage connections, but switched from `wpa_supplicant` to `iwd` allowing a simple `systemd` service to be used for connecting to hidden networks. Create `/storage/.config/system.d/hidden-ssid.service` with the following content: ```sh [Unit] Description=Hidden SSID Connect Service After=network-online.target connman.service iwd.service Wants=network-online.target connman.service iwd.service Before=kodi.target [Service] Type=oneshot RemainAfterExit=yes ExecStart=/usr/bin/iwctl --passphrase station wlan0 connect-hidden ExecStop=/usr/bin/iwctl station wlan0 disconnect [Install] WantedBy=multi-user.target ``` Replace `` with the WiFi passphrase and `` with the name of the network. On most LE devices there will only be a single `wlan0` wireless network interface, but if you have more than one card and `wlan1` or `wlan2` etc. are visible, set the correct NIC/card to use. Next enable and start the `systemd` service: ```sh systemctl enable /storage/.config/system.d/hidden-ssid.service systemctl start hidden-ssid.service ``` Starting the service will initiate the connection and `ifconfig` should show an active NIC with an IP address. Ensure testing is done with Ethernet cables unplugged else the default traffic `route` will be on the `eth0` Ethernet connection. {% hint style="info" %} **Users often hide the network SSID to improve privacy and network security, but the SSID is disclosed in client connection requests making a hidden network easily discoverable to anyone sniffing WiFi packets and looking for it. Hiding the SSID provides zero protection.** {% endhint %} # Hypercon ## Not working anymore since LE10 Starting with LE10 Hyperion no longer works due to changes in the video pipeline. Consider hardware/external grabbers. HyperCon is a graphical application which allows you to configure [Hyperion](https://github.com/LibreELEC/documentation/tree/bb394d22013fdc5f491418b7367a92b73ca7c45a/hyperion.md) (an ambient lighting system) running on a remote LibreELEC device, from a Windows, macOS or Linux desktop. Hypercon is a Java application, and so requires you to have a working Java runtime environment (JRE) installed to run it. Java v1.7 or higher is required. The latest version is here ## Linux On Ubuntu/Debian systems ``` sudo apt-get install openjdk-7-jre wget http://releases.libreelec.tv/hypercon-LE.jar ``` On Fedora/CentOS systems ``` yum install java-1.7.0-openjdk*. wget http://releases.libreelec.tv/hypercon-LE.jar ``` To run Hypercon: ``` java -jar ./hypercon-LE.jar ``` ## Windows Download and install the correct 32-bit or 64-bit Java Runtime for your Windows OS version from the official Java download site [https://www.java.com/](https://www.java.com). Open the .jar file as you would a regular .exe file and it should launch using Java (JRE). If not, right click and select “Open with” then “Java” listed in the list. # Hyperion WARNING: Hyperion does not support the GBM/V4L2 video pipeline used in LibreELEC 10.x and 11.x: including all Raspberry Pi and Generic x86\_64 (GBM) releases. Users with x86\_64 hardware can update to the Generic\_Legacy (X11) image. Users with Raspberry Pi hardware must use an external grabber hardware device or remain on older releases. Changes to add GBM support to Hyperion are tracked here: [Hyperion](https://github.com/hyperion-project/hyperion) is an open source project that provides an ambient lighting system, compatible with Kodi. Hyperion requires hardware and software configuration. This page describes the process to add Hyperion to Generic x86\_64 and Raspberry Pi hardware. For software configuration please head over to [Hypercon](/configuration/hypercon). ## Adalight If you want hardware that will work on any LibreELEC device, an "Adalight" setup is the best choice. It works by sending serial data to an Arduino micro controller which controls the LEDs. You need: * Arduino (Uno, nano, etc) * WS2801 LED strand * 5V power supply * Wire/Jumpers * Breadboard/Protoboard (optional) * Soldering iron (optional) ![Adalight wiring](/files/SDH5ExwaGmtraenl4jNo) Follow the tutorial here . In [Hypercon](/configuration/hypercon) you will need to enable: ![Hypercon configuration Adalight](/files/-MLrOZr42991jQfV9JRd) ## Raspberry Pi Pi devices can drive an SPI output directly, and hyperion can output to an spidev device. You need: * Raspberry Pi * WS2801 LED strand * 5V power supply * Wire/Jumpers ![Raspberry Pi wiring](/files/-MLrMcnE8872AlKjX49s) You can find the pinout here . You will need to connect the following pins: ``` 19 MOSI -> Data 23 SCLK -> Clock 25 GND -> Ground ``` You need to enable SPI in the config.txt file: ``` mount -o remount,rw /flash nano /flash/config.txt ``` Add the following line to the end of the file: ``` dtparam=spi=on ``` Then reboot. In [Hypercon](/configuration/hypercon) you will need to enable: ![Hypercon configuration Raspberry Pi](/files/HWNTugSfeTyrqHeZPX0Z) # Infra-Red Remotes ## Introduction Modern Linux kernels (used in LibreELEC) have built-in support for IR remotes. IR signals are decoded by the kernel and programs see button presses from IR remotes in the same way as key presses from a keyboard, as Linux input events. This supersedes the older LIRC approach where a separate program, lircd, decodes IR signals and programs obtain button presses from a socket as LIRC events. However, Kodi's remote handling was built for LIRC so LibreELEC runs the `eventlircd` service in the background to translate Linux input events into LIRC events. So "under the hood" the kernel scheme is being used, but remote buttons are still handled as LIRC events in Kodi. Kodi translates the received LIRC events to Kodi button names via `Lircmap.xml` and then buttons are mapped to Kodi actions via `remote.xml` and `keyboard.xml` files. This wiki page describes LibreELEC configuration. Information on Kodi configuration is available in the [Kodi LIRC](http://web.archive.org/web/20201111212253/https://kodi.wiki/view/LIRC) and [Kodi Keyboard.xml](http://web.archive.org/web/20201111212253/https://kodi.wiki/view/Keyboard.xml) wiki pages. {% hint style="info" %} LIRC is still shipped in LibreELEC so IR remotes with non-standard protocols that need special setups can still be supported, but it is disabled by default. LIRC is only required in exceptional cases. {% endhint %} Note that LIRC requires compatible hardware to decode IR signals. An in-depth discussion of IR decoder hardware is outside the scope of this document. On a Raspberry Pi, LibreELEC can use the GPIO pins to communicate with a hardware IR receiver diode, as long as `config.txt` has been suitably modified to enable GPIO support. ## Configuration Like most modern Linux distros LibreELEC uses `ir-keytable` to configure Infra-Red remotes. Each IR receiver kernel driver installs a default `keytable` which specifies the IR protocol to use, e.g. RC5, RC6, NEC, and the scancode to Linux keycode mappings. Most universal receivers work with the rc-rc6-mce table so RC6 MCE remotes can be used without further configuration. Drivers for DVB devices sold with a remote usually install their own keytable, e.g. the Hauppauge remote that came with a Hauppauge DVB stick. After the kernel driver is loaded `ir-keytable -a` is automatically run to change the kernel default configuration. First `/etc/rc_maps.cfg` determines which keytable to load. Then the corresponding keytable file from `/usr/lib/udev/rc_keymaps` is used to configure the remote control driver. As most of the LibreELEC filesystem is read-only, we use a system of boot-time file overrides to read user-created configuration from the persistent `/storage` area: * `/storage/.config/rc_maps.cfg` overrides `/etc/rc_maps.cfg` * `/storage/.config/rc_maps.cfg.sample` has simple examples * `/storage/.config/rc_keymaps` overrides `/usr/lib/udev/rc_keymaps` * `/etc/rc_maps.cfg` uses the `libreelec_multi` keytable instead of `rc6_mce` The default `libreelec_multi` keytable allows us to support Xbox 360/One remotes "out of box" in addition to MCE/RC6 remotes. This is configured via the following change: ``` # use combined multi-table on MCE receivers #* rc-rc6-mce rc6_mce * rc-rc6-mce libreelec_multi ``` ## Can I use any remote? While most IR receivers can be used with a large variety of remotes the answer to “Can I use remote X with IR receiver Y?” depends on many factors: * Some IR receivers cannot be configured and you can only use the remote they came with. * Some receivers only support a subset of protocols, e.g. only RC5, not RC6. * If a remote uses a protocol not supported by the IR receiver, or a protocol not supported by the Linux kernel, the last option is the RAW (lirc) protocol which allows userspace LIRC to be configured though a custom `lirc.conf` file. ## Configuration (Basic) LibreELEC ships with 100+ remote keytable files so there is a good chance of finding an existing remote configuration that works, or a partially working keytable that can be used as a starting point for adding the missing buttons (see the "Advanced" section). 1. Look at the keytable files in `/usr/lib/udev/rc_keymaps/` 2. If one of the filenames suggests it could match your remote, try using it 3. If it doesn't work, keep trying.. To test a different keytable file run `ir-keytable -c -w /path/to/keytable-file` e.g. ``` LibreELEC:~ # ir-keytable -c -w /usr/lib/udev/rc_keymaps/samsung Read samsung table Old keytable cleared Wrote 30 keycode(s) to driver Protocols changed to nec ``` If the output ends with these lines the protocol is not supported by the IR receiver: ``` Invalid protocols selected Couldn't change the IR protocols ``` If the keytable loaded without errors try pressing the up, down, left, right and OK buttons to see if GUI navigation in Kodi works? If you find a working keytable make the config persistent by creating `/storage/.config/rc_maps.cfg` with the name of the keytable, e.g. if the `samsung` keytable works, create `rc_maps.cfg` with: ``` * * samsung ``` Then run `ir-keytable -a /storage/.config/rc_maps.cfg` and the output should look like: ``` LibreELEC:~ # ir-keytable -a /storage/.config/rc_maps.cfg Old keytable cleared Wrote 30 keycode(s) to driver Protocols changed to nec ``` Test the buttons work again, and if all is okay, you can reboot. ## Configuration (Advanced) If you cannot find a working keymap or the current keymap has missing buttons you can create your own. Since LibreELEC 10.x the keytable file is plain text file in `toml` markup format. The first section describes the name of the keymap (free text, but avoid special characters and spaces) and the remote protocol and variant. This is followed by lines that map the remote scancode to a Linux keycode. A typical keytable file in toml format looks like this: ``` [[protocols]] name = "khadas" protocol = "nec" variant = "nec" [protocols.scancodes] 0x14 = "KEY_POWER" 0x03 = "KEY_UP" 0x02 = "KEY_DOWN" 0x0e = "KEY_LEFT" 0x1a = "KEY_RIGHT" 0x07 = "KEY_OK" 0x01 = "KEY_BACK" 0x5b = "KEY_MUTE" 0x13 = "KEY_MENU" 0x58 = "KEY_VOLUMEDOWN" 0x0b = "KEY_VOLUMEUP" 0x48 = "KEY_HOME" ``` {% hint style="info" %} Older LibreELEC releases (v7.x to v9.x) use a plain text format not `toml` but the process is essentially the same. Look at existing keymaps in `/usr/lib/udev/rc_keymaps` to crib the format. {% endhint %} To capture the keycodes you must stop Kodi and eventlircd first, or these services capture IR input and you will see no output from `ir-keytable`: ``` systemctl stop kodi systemctl stop eventlircd ``` Next we have to identify the IR protocol. If you found a partially working keytable file (with the protocol listed in the header) you can skip this step. First we run `ir-keytable` to find out which protocols the receiver driver supports. Look at the `Supported protocols:` line, e.g. ``` LibreELEC:~ # ir-keytable Found /sys/class/rc/rc0/ (/dev/input/event1) with: Driver gpio-rc-recv, table rc-rc6-mce Supported protocols: lirc rc-5 rc-5-sz jvc sony nec sanyo mce_kbd rc-6 sharp xmp Enabled protocols: lirc nec rc-6 Name: gpio_ir_recv bus: 25, vendor/product: 0001:0001, version: 0x0100 Repeat delay = 500 ms, repeat period = 125 ms ``` Run `ir-keytable -p PROTOCOL -t` and press buttons on the remote. If you discover the correct protocol you will see `EV_MSC` events and the scancode of the button pressed, e.g. ``` LibreELEC:~ # ir-keytable -p rc-5 -t Protocols changed to rc-5 Testing events. Please, press CTRL-C to abort. 1503592437.660155: event type EV_MSC(0x04): scancode = 0x101a 1503592437.660155: event type EV_SYN(0x00). 1503592437.774129: event type EV_MSC(0x04): scancode = 0x101a 1503592437.774129: event type EV_SYN(0x00). 1503592437.921009: event type EV_MSC(0x04): scancode = 0x101a ``` If you see no events stop ir-keytable with `CTRL-C` and try another protocol from the list. You can ignore `lirc` as this is not a real protocol. Once you find the correct IR protocol create `/storage/.config/rc_keymaps/custom_remote` and set the header file. In the example above the protocol is `rc-5` so we set: ``` # table custom_remote, type: rc-5 ``` If you found a partially working keytable, clone it and then edit the header to say `custom_remote`: ``` cp /usr/lib/udev/rc_keymaps/samsung /storage/.config/rc_keymaps/custom_remote ``` Next we capture the scancodes and document the keycode mapping. Some users find it easiest to open two SSH connections; one to see ir-keytable scancode output in, and one so they can copy/paste scancodes directly into the `custom_remote` keytable file, e.g. in one open the `nano` editor: ``` nano /storage/.config/rc_keymaps/custom_remote ``` And in the second run `ir-keytable -t` to find out the scancode of each button. For each button do the following: * Press a button and note the scancode (the 0x… value after scancode:) * Add a new line with the scancode (including 0x). * Add the Linux keycode in "quoted" format and separated with a blank. You can get a list of all supported Linux keycodes via `irrecord -l | grep ^KEY` but it is easiest to use keycodes listed in the `` section of `/usr/share/kodi/system/Lircmap.xml` else you must also create a Kodi `lircmap.xml` with Linux keycode to action mappings. The table below has a selection of common keycodes: | Keycode | Keycode | Keycode | Keycode | | -------------- | ------------------ | ----------------- | ------------------- | | KEY\_LEFT | KEY\_STOPCD | KEY\_INFO | KEY\_TEXT | | KEY\_RIGHT | KEY\_FASTFORWARD | KEY\_PROPS | KEY\_1 | | KEY\_UP | KEY\_FORWARD | KEY\_ZOOM | KEY\_2 | | KEY\_DOWN | KEY\_REWIND | KEY\_ANGLE | KEY\_3 | | KEY\_OK | KEY\_VOLUMEUP | KEY\_MUTE | KEY\_4 | | KEY\_ENTER | KEY\_VOLUMEDOWN | KEY\_POWER | KEY\_5 | | KEY\_SELECT | KEY\_CHANNELUP | KEY\_SLEEP | KEY\_6 | | KEY\_DELETE | KEY\_CHANNELDOWN | KEY\_WAKEUP | KEY\_7 | | KEY\_ESC | KEY\_PAGEUP | KEY\_EJECTCD | KEY\_8 | | KEY\_MEDIA | KEY\_PAGEDOWN | KEY\_EJECTCLOSECD | KEY\_9 | | KEY\_HOME | KEY\_NEXT | KEY\_DVD | KEY\_0 | | KEY\_EXIT | KEY\_NEXTSONG | KEY\_MENU | KEY\_NUMERIC\_STAR | | KEY\_BACK | KEY\_PREVIOUS | KEY\_VIDEO | KEY\_NUMERIC\_POUND | | KEY\_BACKSPACE | KEY\_PREVIOUSSONG | KEY\_AUDIO | KEY\_RED | | KEY\_ESC | KEY\_EPG | KEY\_MP3 | KEY\_GREEN | | KEY\_RECORD | KEY\_TITLE | KEY\_CAMERA | KEY\_BLUE | | KEY\_PLAY | KEY\_TV2 | KEY\_IMAGES | KEY PVR | | KEY\_PLAYPAUSE | KEY\_CONTEXT\_MENU | KEY\_TUNER | KEY\_RADIO | | KEY\_PAUSE | KEY\_SUBTITLE | KEY\_TV | | | KEY\_STOP | KEY\_LANGUAGE | KEY\_PVR | | Once you are finished with the keytable, save the file, stop ir-keytable -t with `CTRL-C` and then restart it with the keytable file: ``` LibreELEC:~ # ir-keytable -c -w /storage/.config/rc_keymaps/custom_remote Read justboom table Old keytable cleared Wrote 12 keycode(s) to driver Protocols changed to rc-5 ``` Now run `ir-keytable -t` and press buttons. In addition to EV\_MSC scancode events you should now see EV\_KEY events, e.g. ``` LibreELEC:~ # ir-keytable -t Testing events. Please, press CTRL-C to abort. 1503599395.150849: event type EV_MSC(0x04): scancode = 0x1019 1503599395.150849: event type EV_KEY(0x01) key_down: KEY_VOLUMEUP(0x0073) 1503599395.150849: event type EV_SYN(0x00). 1503599395.264827: event type EV_MSC(0x04): scancode = 0x1019 1503599395.264827: event type EV_SYN(0x00). 1503599395.413668: event type EV_MSC(0x04): scancode = 0x1019 1503599395.413668: event type EV_SYN(0x00). 1503599395.673626: event type EV_KEY(0x01) key_up: KEY_VOLUMEUP(0x0073) 1503599395.673626: event type EV_SYN(0x00). ``` If the test is successful, make the keytable persistent by creating `/storage/.config/rc_maps.cfg` with the following content: ``` * * custom_remote ``` Reboot and you should have a working remote in Kodi. ## Troubleshooting Check the obvious. Batteries run down and either stop the remote from working or reduce the working range. Try using the remote in-front of the receiver. You can also try pointing the IR transmitter at the sensor of a digital camera or smartphone in a dark room. If the IR transmitter works you should see it light up the camera/smartphone screen. If the remote is sending signals, there are several steps until a button press on your remote triggers an action in Kodi. Use this guide to check each step and trace the problem: To check if the IR receiver driver is loaded run `ir-keytable`. If you see the error message `/sys/class/rc/: No such file or directory` no driver is loaded. To check if the IR receiver is receiving any signals, see if `ir-keytable` shows `lirc` as a supported protocol. If yes, run `ir-ctl -r` to show raw, undecoded signals from the receiver. If IR reception works you will see lots of pulse and space lines when pressing a button. Note: On kernels before 4.3 lirc may be listed in Supported protocols but not in Enabled protocols. In this case run `ir-keytable -p lirc` to enable it first (remembering this will disable other decoders). To check if `lircd` is running run `ir-keytable`. If only `lirc` shows up in `Enabled protocols:` lircd is running. When it starts it disables all other protocols). You can also run `ps | grep /usr/sbin/lircd` to check for `/usr/sbin/lircd` and `/usr/sbin/lircd-uinput` processes. If you see them LIRC enabled. If LIRC is enabled, disable it in LibreELEC Settings > Services and reboot. To check if the correct keytable is loaded run `ir-keytable -r` to show the current keytable and protocol. Compare this to the header in `/storage/.config/rc_keymaps/custom_remote` and check `/storage/.config/rc_maps.cfg` references the correct keytable name. To check if IR decoding works correctly stop Kodi and eventlircd: ``` systemctl stop kodi systemctl stop eventlircd ``` Then run `ir-keytable -t` and press buttons on the remote. You should see EV\_MSC events with the scancode and EV\_KEY events with the Linux keycode, e.g. ``` LibreELEC:~ # ir-keytable -t Testing events. Please, press CTRL-C to abort. 1503599395.150849: event type EV_MSC(0x04): scancode = 0x1019 1503599395.150849: event type EV_KEY(0x01) key_down: KEY_VOLUMEUP(0x0073) ``` If you only get EV\_MSC but no EV\_KEY events, verify if the correct keytable is configured. After this test, restart eventlircd and Kodi (or reboot): ``` systemctl start eventlircd systemctl start kodi ``` To check if eventlircd translates the input events to LIRC events run `irw` to show the translated LIRC events Kodi sees. When pressing a button you should see messages like this: ``` LibreELEC:~ # irw 72 0 KEY_VOLUMEDOWN devinput 72 1 KEY_VOLUMEDOWN devinput 72 2 KEY_VOLUMEDOWN devinput ``` To check if Kodi receives the translated LIRC events enable debug logging in System Settings > Logging then watch the logfile: ``` tail -f /storage/.kodi/temp/kodi.log ``` When you press a button you should see log entries with `LIRC: Update` like this: ``` 21:55:33.891 T:1945866240 DEBUG: LIRC: Update - NEW at 60659:6c 0 KEY_DOWN devinput (KEY_DOWN) 21:55:33.891 T:1945866240 DEBUG: OnKey: 167 (0xa7, obc88) pressed, action is Down ``` The LIRC line indicates Kodi received the LIRC event. The `OnKey:` line shows the action generated after applying `Lircmap.xml` and `remote.xml`. If you see LIRC lines but incorrect actions, check your Kodi `Lircmap.xml` and `remote.xml` config files are correct. ## Known Issues USB data transfers can interfere with GPIO IR receivers on Raspberry Pi 0/1/2/3 hardware, and since Ethernet is internally connected via USB playing large movies from a NAS can exhibit the problem. This is a known issue: [see this forum post for details](https://github.com/raspberrypi/linux/issues/906) and there is nothing we can do. Common workarounds are to use a USB IR receiver like [Flirc](https://flirc.tv) or CEC. ## LIRC Support Most remotes are now supported by the Linux kernel but "LIRC" (the userspace lircd daemon and tools) is still useful for handling unusual remotes with odd protocols and no kernel drivers. Since LibreELEC 8.2.0 LIRC is disabled by default, but can be enabled in LibreELEC Settings > Services > Lirc. Configuration is handled in (almost) the same way as most desktop Linux distros: * The `/etc/lirc/lirc_options.conf` file configures the default LIRC driver and /dev/lirc0. * The `/etc/lirc/lircd.conf` file includes remote configs for MCE, Xbox 360, Xbox One, and a few others. The embedded files can be overridden at boot time by creating `/storage/.config/lircd.conf` and `/storage/.config/lirc_options.conf` with needed changes. In LibreELEC `lircd-uinput` reads decoded LIRC events from `/run/lirc/lircd.socket` and translates these to Linux input events via the Linux uinput driver. The Linux input events from lircd-uinput are then picked up by `eventlircd` and fed to Kodi as LIRC events via the `/run/lirc/lircd` socket. It might seem odd to translate between LIRC, Linux input and (again) LIRC events, but Kodi can only receive LIRC events on a single LIRC socket, and this allows eventlircd to collect all remote events and feed them to Kodi so we can support LIRC-decoded and kernel-decoded remotes without needing user input or complex scripts to change the configuration. To use LIRC with an IR receiver that supports in-kernel decoding it's best to disable ir-keytable auto configuration with an empty `rc_maps.cfg` file: ``` touch /storage/.config/rc_maps.cfg ``` Although lircd disables all remote protocols (and thus in-kernel decoding) on startup ir-keytable auto-configuration runs in parallel, and if it happens to run after lircd starts it can re-enable in-kernel decoding. This causes duplicate decoding as both lircd and kernel will receive and process the IR signals. This issue is often intermittent since it depends on the timing of lircd start. Sometimes lircd will run after ir-keytable and in-kernel decoding is disabled as expected. Note: If you stop or disable LIRC in LibreELEC Settings you will need too reboot or set ir-keytable manually from the SSH console. Disabling LIRC does not automatically re-enable in-kernel decoding. ## Apple IR Remotes Older LibreELEC releases used `atvclient` to support the Apple IR sensor and send LIRC events to Kodi. Since 9.2.0 we use the native Linux kernel driver for the IR sensor, which sends normal HID events. Create a custom keymap in `/storage/.kodi/userdata/keymaps/keymap.xml` with the following content to map a White or Silver remote: ```markup Left Right Up Down Back VolumeUp VolumeDown VolumeUp VolumeDown ``` # LCDProc Since Kodi v17 LCD/VFD displays are supported through the LCDProc add-on which must be installed from the Kodi add-on repo. See [script.xbmc.lcdproc/wiki](https://github.com/herrnst/script.xbmc.lcdproc/wiki) for documentation and [LCD.xml.defaults](https://github.com/herrnst/script.xbmc.lcdproc/blob/master/resources/LCD.xml.defaults) for a sample file, and the [LCDProc add-on support thread in Kodi forums](https://forum.kodi.tv/showthread.php?tid=143912). ## Configuration The `/storage/.kodi/userdata/LCD.xml` file can be created to customise output to an LCD or VFD display. It contains "content" sections that describe how the display will look: * `` is used for navigation in menus * `` is used when listening to music * `