## page was renamed from InstallingDebianOn/Teres
#language en
#pragma description How to install Debian/Linux on a Olimex Teres-I DIY open hardware laptop
##
## Read http://wiki.debian.org/InstallingDebianOn/HowToContribute before modifying this page
##
## You will find some comments like this one below to help you write a report.
## ------------------------------------------------------------------------------------------
##
## Location Bar + DebianOn compatibility rating
~-Translation(s): none-~

||<tablestyle="width:100%" style="width:96px;border-right-style:none"><<Include(InstallingDebianOn/Ratings/CategoryEtchUnrated)>>||<style="border-left-style:none"><<Include(InstallingDebianOn/PageFragments/Philosophy)>>||

<<TableOfContents()>>

= Introduction =
The Teres-I is a DIY open hardware laptop sold by Olimex.
Olimex has stated that they intend the Teres-I to be very modular,
allowing main boards built around different !SoCs to be used interchangeably.
However, the only main board available at the moment is based on the Allwinner A64 SoC
with 2GB RAM and 16GB eMMC internal storage.
The CPU is supported by the arm64 architecture in debian.
armhf should work too, but is untested.

The laptop is sold with linux (ubuntu + vendor supplied kernel) preinstalled.
Source code is only partially available for the vendor kernel,
which means that users of the preinstalled system are permanently stuck with an old version of linux.
On the other hand since a linux system is available,
no external computer and no cross-compilation is required to bootstrap a debian system.

While debian runs fine from eMMC internal storage,
it is common to install debian to an external microSD card (there is one slot available)
to have both systems available.
That's also what is described in this guide.

= Overall Status =
To get an overview of mainline kernel support,
see the [[http://linux-sunxi.org/Linux_mainlining_effort#Status_Matrix|status matrix of the linux sunxi community]].

## If you installed Debian from scratch on this computer, please rate it!
## see InstallingDebianOn/Ratings (change the "included" file above).
||||<tablestyle="margin-left:3em;width:90%">'''Core Components'''||<|10 style="text-align:right;border-style:none;vertical-align:top;"> {{attachment:photo.png}}||
||Boot Standard Kernel:		|| {OK} ||
|| Detect mmc:		        || {OK} ||
## If Xorg doesn't work at all (not even with vesa driver), then move Xorg line here.
||||'''Extra Features'''||
|| CPU Frequency Scaling	|| {OK} ||
|| Hibernation			|| {OK} ||
|| Sleep / Suspend		|| {OK} - with [[DebianPackage:crust-firmware|Crust ]] [[Firmware/Open|open-source firmware]] ||
|| Xorg         		|| {OK} ||
||  - OpenGL			|| {OK} ||
||  - Resize-and-Rotate(randr)	|| {OK} ||
|| Wayland         		|| {OK} ||
|| Switch to External Screen	|| {OK} ||
|| Mouse			|| {OK} ||
||  - Built-in (Touchpad)	|| {OK} ||
|| Wireless/Wifi        	|| X-( - With DebPkg:firmware-realtek or hardware mod ||
|| Keyboard's Hotkeys (a.k.a. media keys) || {OK} - since udev 245 ||
~-Legend :<<BR>>
{OK} = OK ;
{X} Unsupported(No Driver) ;
/!\ = Error (Couldn't get it working);
[?] Unknown, Not Test ;
[-] Not-applicable <<BR>>
{i} = Configuration Required;
X-( = Only works with a non-free driver and or firmware-~

= Installation =
The laptop is sold as a kit for self-assembly.
Here we assume that the kit is completely assembled
and correctly functioning with the preinstalled system.

== Image install ==

Several images exist for directly writing to your microSD card:

## sorted by distance to debian - e.g. add official installer images at the top
 * [[https://github.com/AerithForge/AerithForge|AerithForge]]
  * Description: Fork of armbian by the device's maintainer focused to be as close to debian as possible with device-specific optimizations
  * Source: apt-based distributions + optional AerithForge repository
  * Build: Mostly debootstrap + custom management
 * [[https://deb.debian.org/debian/dists/stable/main/installer-arm64/current/images/netboot/SD-card-images|Debian Installer]]
  * Description: Rarely works due to trying to be "one image for all arm64 devices"
 * [[https://www.armbian.com/olimex-teres-a64/|Armbian]]
  * Description: Framework used to build apt-based distributions
  * Source: Debian (or Ubuntu) + optional Armbian repository
  * Build: debootstrap + [[https://github.com/armbian/build|custom scripts]]
 * [[https://box.redpill.dk/|Redpill]]
  * Description: Seems to be an abandonware, doesn't work anymore
  * Source: Debian
  * Build: Boxer + qemu + multistrap + [[https://salsa.debian.org/tinker-team/box/|custom scripts]]
  * Quirks: in addition to main purely Free Debian image, a separate nonfree image is provided with support for internal wifi
 * [[ftp://staging.olimex.com/Allwinner_Images/A64-Teres/linux/xenial-teres-bspkernel-20190121_144941_EET-1_hdmi_out_v1_5.torrent|Olimex (torrent link)]]
  * Description: Very outdated and unmaintained image, kept for legacy and design reference
  * Source: Ubuntu + Olimex + Olimex-maintained forks of kernel and bootloader
  * Build: qemu-debootstrap + [[https://github.com/OLIMEX/DIY-LAPTOP|custom scripts]]
 * [[ftp://staging.olimex.com/Allwinner_Images/A64-Teres/linux/armbian_experimental/|Olimex (Armbian)]]
  * Description: Very broken, someone though it's good idea
  * Source: Ubuntu + Armbian + Olimex + Olimex-maintained forks of kernel and bootloader
  * Build: qemu-debootstrap + [[https://github.com/OLIMEX/build|custom scripts]]
 * [[https://git.dotya.ml/kreyren/teres-a64-arch-preliminary|Preliminary image for ArchLinux]]
  * Description: Image developed during porting for parabola linux, abandoned due to upstream incompetence
  * Source: Parabola GNU/Linux
  * Build: Parabola build system
 * [[https://labs.parabola.nu/issues/3450|Parabola GNU/Linux]]
  * Description: Official support on Parabola GNU/Linux
  * Source: Parabola GNU/Linux
  * Build: Parabola build system
 * [[https://issues.guix.gnu.org/62024|GNU Guix (patch)]]
  * Description: Patch for an official support, never merged
  * Source: GNU Guix
  * Build: GNU Guile

For links, further information and discussion
see the [[https://www.olimex.com/forum/index.php?topic=6092.0|dedicated thread at the olimex forum]].

== Manual install ==
Buster and newer include boot-loader, kernel and arm64 userspace tools working out of the box.

=== partitioning ===
There are no real requirements for disk layout
other than that the bootloader is stored in an area close to the start of the disk but outside any partition.
Most microSD cards already come with a compatible partition layout,
so you only have to change the type of the existing partition from Windows to Linux
and format it with your favorite filesystem.

=== device tree ===

Buster and newer ships with working device-tree (DT) file for the teres.

=== u-boot ===

Stage 1 and 3 of bootstrapping the hardware is U-boot.

mainline u-boot supports Teres-I since 2019.05,
and the debian package DebPkg:u-boot-sunxi since release 2019.01+dfsg-5.

Built-in keyboard requires special care to get enabled in u-boot.

U-boot before v2020.01 fails to enable the built-in keyboard,
and require [[https://gitlab.denx.de/u-boot/u-boot/-/commit/1949232|this patch]] to be applied.  
U-boot since v2022.04 (possible earlier) again fails to enable the built-in keyboard,
and require [[https://lists.denx.de/pipermail/u-boot/2022-June/485862.html|this patch]] to be applied.  
The issue is tracked at DebianBug:935035.

==== arm trusted firmware ====

Stage 2 of bootstrapping the hardware is ARM Trusted Firmware.

The debian package DebPkg:arm-trusted-firmware has support for Teres I
using this binary:{{{
/usr/lib/arm-trusted-firmware/sun50i_a64/bl31.bin
}}}

Debian-packaged u-boot embeds this firmware since release 2020.04+dfsg-1.

=== rootfs ===
Follow the debootstrap chapter
in the [[https://www.debian.org/releases/stable/arm64/apds03.html.en|installation manual]].

The default bootscript built into u-boot probably won't find all the files necessary to boot the system.
The simplest way to fix this is to install DebPkg:u-boot-menu which should work out of the box.

Alternatively you can try write a custom bootscript
and reformat it with mkimage from the package u-boot-tools:
{{{
mkimage -T script -d boot.txt /boot.scr
}}}

Here is a minimal [[attachment:boot.txt|example bootscript]]
which assumes that /dtb, /vmlinuz and /initrd.gz are symlinks to the real files.

== Using debian installer ==
## This section is about using Debian directly.
## If you want to document alternatives to using Debian directly,
## then please add a separate section *below* this one,
## instead of misguiding those reading this section because they want Debian (not KREYRIAN or some other superior alternative)

Vanilla Debian may be installed onto the TERES-I using Debian-installer.
The following procedure installs Debian onto internal eMMC storage.

=== Disclaimer: Mitigating a known issue ===

Following installation, the user will be greeted with a black screen every time the device is powered on or rebooted.
Until this issue is patched upstream, the easiest workaround is to follow the procedure as described below in both the linked video and the section entitled "No output on monitor (black screen) when booting/rebooting".

=== Installation ===

1. Using a host computer, download and configure the installation image:

{{{
wget -nd https://deb.debian.org/debian/dists/stable/main/installer-arm64/current/images/netboot/SD-card-images/firmware.teres_i.img.gz
wget -nd https://deb.debian.org/debian/dists/stable/main/installer-arm64/current/images/netboot/SD-card-images/partition.img.gz
zcat firmware.teres_i.img.gz partition.img.gz > complete_image.img
}}}

2. On the same computer you used to create the image above, run the following command:

{{{
lsblk
}}}

3. Still using the same host computer, insert a spare microSD card.
This microSD card will be used to run debian-installer in order to install Debian onto the TERES-I local eMMC.

4. Run the following command again:

{{{
lsblk
}}}

Verify that the device path of the microSD card is shown by comparing the output to the previously-issued command.
The device path should look something like /dev/sdX (and NOT the path to a partition e.g. /dev/sdX1).

5. Run the following command to burn the installation image to the microSD card:

{{{
sudo dd bs=4M if=/path/to/complete_image.img of=/dev/sdX status=progress oflag=sync
}}}

'''NOTE''': At this point, you may wish to follow this video walkthrough on ([[https://archive.org/details/install-vanilla-debian-olimex-teres-i|archive.org]][[https://odysee.com/@jc:a/installing-vanilla-debian-on-an-olimex-teres-i-laptop:9|odysee.com]]) which corresponds to the next steps in the installation process.

6. Insert the imaged microSD card into the TERES-I and power on the device.

7. U-Boot will launch and the boot select menu will display Debian-installer as an option.
Select your language, location, and keyboard settings.
Select your desired host name and domain name.
Network hardware will now be scanned and you may select your mirror and proxy settings.
If you receive a "bad mirror" error, try using an RJ45-to-USB adapter and try detecting network hardware again via the "Go Back" menu option.
Set up users and passwords, and choose a time zone.
Choose a partitioning method.
When you reach the "Partitioning disks" menu, you will be prompted to "select disk to partition."
You should see two options:

 * MMC/SD card #1 (mmcblk0) - XX.X GB SD XXXXX
 * MMC/SD card #3 (mmcblk2) - 14.8 GB MMC B1J56L

Select the MMC option.
Choose a partioning scheme.
Select "Finish partitioning and write changes to disk" and select "Yes."
Wait for a while.
When you reach the software selection menu, toggle what software to install by pressing <Space> and "Continue" using <Enter>.

8. At the conclusion of the installation, you will be prompted to remove the installation media and either "Go Back" or "Continue".
Leave the microSD card inserted and select "Continue" to reboot the device.
You are now at the point where you must perform a known workaround to avoid a black/blank screen when booting the TERES-I.
Please continue to the section below entitled "No output on monitor (black screen) when booting/rebooting".

== Troubleshooting ==

=== No output on monitor (black screen) when booting/rebooting ===

1. Ensure that a bootable microSD card is inserted into the microSD slot on the device.

2. Power on or reboot the device.

3. When U-Boot appears (like it did when you were intentionally installing Debian), remove the microSD card.

4. Depending how long you wait to remove the microSD card, several errors may be shown due to missing files, but ignore them.

5. The TERES-I will continue to boot Debian normally from local eMMC storage.

If the screen remains blank or the system doesn't boot (e.g. is stuck in u-boot or initramfs), you can connect a serial console.
The serial console is multiplexed with the headphone output.
Instructions how to make or buy a proper connector are at the Olimex forum.

= Configuration =

== Backlight ==

The backlight is adjustable by echo'ing values 0-10 to `/sys/class/backlight/backlight/brightness`
since Linux 5.2.

Keys to control backlight (and other media keys)
need udev 245 or newer.

Older udev can be taught as well:
Add file `/etc/udev/hwdb.d/70-keyboard.hwdb` with this content:{{{
###########################################################
# Olimex
###########################################################

# Teres-I
evdev:input:b0003v15BAp003C*
 KEYBOARD_KEY_70066=sleep                               # Fn+F1
 KEYBOARD_KEY_700f6=wlan                                # Fn+F2
 KEYBOARD_KEY_700c7=f21                                 # Fn+F3 touchpad toggle
 KEYBOARD_KEY_7006f=brightnessdown                      # Fn+F7
 KEYBOARD_KEY_70070=brightnessup                        # Fn+F8
 KEYBOARD_KEY_7006e=switchvideomode                     # Fn+F9
}}}

One way to tie backlight keys to backlight control is with package `backlightctl`
and adding the file `/etc/udev/rules.d/90-brightnessctl.rules` with this content:{{{
ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chown nobody /sys/class/backlight/%k/brightness"
ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chgrp video /sys/class/backlight/%k/brightness"
ACTION=="add", SUBSYSTEM=="backlight", RUN+="/bin/chmod g+w /sys/class/backlight/%k/brightness"
ACTION=="add", SUBSYSTEM=="leds", RUN+="/bin/chgrp nobody /sys/class/leds/%k/brightness"
ACTION=="add", SUBSYSTEM=="leds", RUN+="/bin/chgrp input /sys/class/leds/%k/brightness"
ACTION=="add", SUBSYSTEM=="leds", RUN+="/bin/chmod g+w /sys/class/leds/%k/brightness"
}}}

== Display ==
## First say what's the Display adapter model (lspci may help)
## Then explain how to get it working (or just the module used)
## what about : 3D ; DRI ; xrandr ; external/secondary screen...
## attach your xorg.conf at the bottom of the page.
LCD works with simplefb framebuffer.

Mali-400 MP2 ("Utgard") GPU is recognized since Linux 5.2 but not yet used.

Use of Mali GPU requires the lima driver,
developed as part of Mesa3d in (among others) package DebPkg:libgl1-mesa-dri,
where the lima driver is expected enabled from release 4.19.2 onwards.

Possibly use of Mali GPU additionally requires X11 driver fbturbo,
not currently packaged for Debian (see DebianBug:760025).

Video decoding/encoding accelerator [[https://linux-sunxi.org/Video_Engine|Video Engine]]
is supported since Linux 5.0.
Use of Video Engine however requires [[https://linux-sunxi.org/Cedrus|Cedrus]]
(and wrappers e.g. for vdpau and ffmpeg)
not currently packaged for Debian.

As of 2021-09-22,
direct uAPI support in GStreamer is [[http://briandaniels.me/2021/07/06/hardware-accelerated-video-playback-on-the-pinephone-with-clapper.html|possible but not quite available]],
and support via V4L2 requests for mpv is [[https://xnux.eu/devices/feature/cedrus-pp.html|maybe usable too]]
using [[https://github.com/uniformbuffer/libva-v4l2-request|experimental fork of libva-v4l2-requests driver]].

## If this computer has variants with various Display adapter, simply 
## duplicate this section, like "Display / Ati".

== Audio ==
Current stable release depends on package DebPkg:pulseaudio.

If used with pipewire then make sure that DebPkg:pipewire-pulse is installed.

Some systems might not work out of the box on pipewire+pulseaudio+alsa configuration in which case you need to install DebPkg:pavucontrol and make sure that the card profile is set on `Pro Audio` or use the command:

    $ pactl set-card-profile alsa_card.platform-sound pro-audio 

== Power Management ==
Sleep is supported since Linux 4.19.

Battery status data is available since Linux 5.2,
at non-standard path `/sys/class/power_supply/axp20x-battery`.

== WiFi ==
Realtek RTL8723BS,
requiring non-free package DebPkg:firmware-realtek

NOTE: Since bookworm the package is present in the 'non-free-firmware' sub-repository see https://lists.debian.org/debian-boot/2023/01/msg00235.html

A possible race condition between wifi driver and mmc driver
is avoided by adding "rtl8723bs" to the file /etc/initramfs-tools/modules
and then regenerating initramfs with "update-initramfs -u".
This issue and workaround was found [[https://en.opensuse.org/HCL:Teres-I|here]].

== Bluetooth ==
 (not covered yet)

------
= System Summary =
## The content of some files are embedded here, because they are very useful for search engines

== lsusb ==
## Uncomment and Paste the output of one of the three lines (within some {{{ }}}} brackets) 
## (lsusb missing)
## lsusb
lsusb -v | grep -E '\<(Bus|iProduct|bDeviceClass|bDeviceProtocol)' 2>/dev/null 
{{{
Bus 002 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
  bDeviceClass            9 Hub
  bDeviceProtocol         0 Full speed (or root) hub
  iProduct                2 SW USB2.0 'Open' Host Controller (OHCI) Driver
Bus 001 Device 005: ID 15ba:003c Olimex Ltd. 
  bDeviceClass            0 (Defined at Interface level)
  bDeviceProtocol         0 
  iProduct                2 TERES Keyboard+Touchpad
  (Bus Powered)
Bus 001 Device 003: ID 1908:2311 GEMBIRD 
  bDeviceClass          239 Miscellaneous Device
  bDeviceProtocol         1 Interface Association
  iProduct                2 USB2.0 PC CAMERA
      (Bus Powered)
  bDeviceClass          239 Miscellaneous Device
  bDeviceProtocol         1 Interface Association
  (Bus Powered)
Bus 001 Device 002: ID 05e3:0608 Genesys Logic, Inc. Hub
  bDeviceClass            9 Hub
  bDeviceProtocol         1 Single TT
  iProduct                1 USB2.0 Hub
  bDeviceClass            9 Hub
  bDeviceProtocol         0 Full speed (or root) hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
  bDeviceClass            9 Hub
  bDeviceProtocol         0 Full speed (or root) hub
  iProduct                2 SW USB2.0 'Enhanced' Host Controller (EHCI) Driver
Bus 004 Device 001: ID 1d6b:0001 Linux Foundation 1.1 root hub
  bDeviceClass            9 Hub
  bDeviceProtocol         0 Full speed (or root) hub
  iProduct                2 SW USB2.0 'Open' Host Controller (OHCI) Driver
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
  bDeviceClass            9 Hub
  bDeviceProtocol         0 Full speed (or root) hub
  iProduct                2 SW USB2.0 'Enhanced' Host Controller (EHCI) Driver
}}}

= Resources =
<<Anchor(attachments)>>
== Attachments ==
## Some interesting files you can attach: (Named with computer name and model, and Debian version, like "dmidecode.Etch_Thinkpad_T60_1952-W5R.txt") 
## - Xorg.conf file (then "include" it inline below)
## - Output of dmidecode (make sure to remove Serial Number and UUID before), you'd may choose to use:
##        sudo dmidecode | sed 's/\(Serial Number\|UUID\).*/\1: Not Disclosed/g'
## - Output of lsmod
''Some configuration files and sample outputs.''
<<AttachList>> 

== Useful Links ==
## Link to related installation-report
## Link to related bug(s) report(s)
## Avoid linking to other installation Howto from this page.

== Credits ==
----
CategoryLaptopComputer