Merge branch...

> Informationen über das /e/OS-Projekt und seine Apps

- [/e/OS easy-installer]({% translate_link easy-installer %})

- [/e/OS Installer]({% translate_link eos-installer %})

- [Karten-App]({% translate_link maps %})

- [Verschiedene Build-Arten]({% translate_link build-status %})

- [App Lounge ]({% translate_link app-lounge-main %})

{% include alerts/warning.html content=" Ein neues Installationsprogramm, [der WebInstaller](https://e.foundation/installer/) ist nun als Alpha-Version verfügbar. Dieser Webinstaller funktioniert in Browsern, die auf Chrome basieren, weil er WebUSB benötigt.

Der EasyInstaller wird bald nicht mehr unterstützt. " %}

## /e/OS Easy-Installer-Build-Dokumentation

### Tools required to build

> The team member who developed the easy-installer used

- Netbeans 11.3 (/!\ netbeans 11.0 doesn't work properly with javaFX)

- Gradle 4.10

- OpenJFX11+: [doc](https://openjfx.io/openjfx-docs/#IDE-NetBeans)

- Java JDK 11+

### Das Projekt klonen

Führen Sie diesen Befehl im Terminal aus

```shell

git clone https://gitlab.e.foundation/e/tools/easy-installer.git

```

### Wie man Builds erstellt

Öffnen Sie ein Terminal an der Wurzel des Projektes.

Prompt: `./gradlew dist`

Hinweis: „dist“ steht für „Distribution“

#### Ergebnis

Es wird 3 gezippte Artefakte erstellen, die in ein gemeinsames Archiv gepackt sind:

- linux-x64

- windows-x64

- mac

Ort der Artefakte :

Archiviertes Build : "/build/distributions/"

Entzippter Build : "/build/image/"

#### Was macht dieser Befehl?

Die kompilierte Java-Version wird im Ordner „buildSrc“ bereitgestellt. Es gibt eine Version für jede Plattform (Windows, OSX, Linux). Dies ermöglicht eine installationsfreie Anwendung. Dank Java 9+ enthält sie nur die erforderlichen Module.

99% erledigt "badass jlink plugin" (siehe obere Sektion).

Die verbleibenden 1% werden erledigt von:

- ADB kopieren

- heimdall kopieren

- fastboot kopieren

- Flash-Skripte

von den "buildSrc"- und "flash-scripts"-Ordnern in das Build.

#### Was wird benutzt, um das Build zu erstellen ?

Es benutzt das ["badass jlink plugin"](https://badass-jlink-plugin.beryx.org/releases/latest/#_properties)

{% include alerts/warning.html content=" Ein neues Installationsprogramm, [der WebInstaller](https://e.foundation/installer/) ist nun als Alpha-Version verfügbar. Dieser Webinstaller funktioniert in Browsern, die auf Chrome basieren, weil er WebUSB benötigt.

Der EasyInstaller wird bald nicht mehr unterstützt. " %}

## Feature idea

- **Add support for a new device**

    - You need to own the device

    - First step is to create configuration files for the Easy Installer

    - If necessary, create the missing scripts to be able to achieve the installation

1. Ich möchte helfen **/e/ auf Windows zu portieren**

    - Sie können uns helfen, Skripte für Windows zu übersetzen.

    - wenn Sie etwas Wissen mitbringen, um Windows-Anwendungen zu paketieren (wie wir mit Snap auf Linux gemacht haben)

    - Sobald die 2 vorherigen Punkte erledigt sind, können Sie testen, ob alles unter Windows genauso läuft wie unter Linux

## How to support or add a new device ?

The easy-installer uses two configuration files for each device.

_note: We are using herolte (Samsung galaxy S7) as an example here_

The config files are located in "src/main/resources/yaml/" folder.

```

src

--main

----java

----resources

------css

------fonts

------fxml

------images

------instructions

------lang

------yaml

--------**herolte.yml**

--------**herolte_fs.yml**

```

#### 1. First file: <device_code_name>.yml

The first file "herolte.yml" defines the flashing process.

The file is a [YAML](https://yaml.org/) resource.

#### Structures and nodes of the file

``` yaml

name: herolte

flash:

    f1:

        script: wait-download

        parameters:

            heimdall_folder_path: ${HEIMDALL_FOLDER_PATH}

        codes:

            ok:

                0: ~

            ko:

                1: script_error_waitDownload_1

        output: ~

        succeed: f2

        failed: ~  

    f2:

        script: oem-unlock

        parameters:

            heimdall_folder_path: ${HEIMDALL_FOLDER_PATH}

        codes:

            ok:

                0: ~

            ko:

                10: script_error_oemUnlock_10

        output: ~

        succeed: f3

        failed: ~

...

```

- `Name` defines the codename of the device. This value is a simple String.

_example: `herolte` for S7, `hero2lte` for S7 edge, `dreamlte` for S8, ..._

- `f1` is the step key (it identifies the step). The value is the step defined by following elements:

- `script` contains the name of the flash-script to call. There is no extension because it is defined at runtime (this allows to use either ".sh" for linux and mac or ".bat" for windows)

- `parameters` contains a map of parameters to use when the script is called. The order should be the one expected by the script. There are two types of values for a parameter:

- `Name` defines the codename of the device. This value is a simple String.

_example: `herolte` for S7, `hero2lte` for S7 edge, `dreamlte` for S8, ..._

- `codes` contains two sub lists: `ok` corresponds to script's exit when the step succeeds, and `ko` corresponds to script's exit when there is an error.

The codes returned by the script are always numeric value.

	The `ko` codes can be defined with an error message which will be displayed to the user if it happened.

	_example: `10: script_error_oemUnlock_10`_.

	The error message is a key corresponding to a value in the translations file (`src/main/resources/lang/traduction.properties`)

- `output` can be used to define a variable than must be read from the last line of the running script.

example: `output: ${MY_KEY}` corresponds to a step where the installer should read the last line provided by the script and store it in a java variable "MY_KEY" which would be used in a later step. The value of output is always structured like a changing parameter.

- `succeed` specifies the next step's code after a success.

- `failed:` defines the next step's code to call after a failure.

#### Special step:

``` yaml

    f7:

        script: askAccount

        parameters: ~

        codes: ~

        output: ~

        succeed: f8

        failed: ~

```

This is the only step which is empty. There is no script "askAccount". It is used by easy-intaller to know when to show the UI which lets the user request an invitation email to create an account. Please always add this step before the last step.

#### 2. Second files: <device_code_name>_fs.yml

This second file specifies extra data (which aren't optional)

### Structures and nodes of the file

``` yaml

sources:

   rom:

        url: https://images.ecloud.global/stable/herolte/e-latest-herolte.zip

        filePath: e-latest-herolte.zip

   twrp:         

        url: https://images.ecloud.global/stable/twrp/herolte/twrp-3.2.3-0-herolte.img

        filePath: twrp-3.2.3-0-herolte.img

flash:

    f1:

        ui:

            type: action

            title: stepTitle1On7

            instruction:

            - install_instr_turnOff

            - install_instr_startDownload

            - install_instr_acceptWarning

            stepNumber: 1/7

            titleIcon: Download.png

            instructionImg: group2.png

    f2:

        ui:

            type: load

            title: stepTitle2On7

            instruction:

            - install_instr_oemUnlock

            stepNumber: 2/7

            averageTime: 8

...

```

It contains two parts: `sources` which specifies files that need to be downloaded and `flash` which defines UI for the different steps.

### `sources`

Each different files that needs to be downloaded should be specified here.

Use a key to identify it :

_example: `rom`, `twrp`, `vendor`, `patch`, ..._

``` yaml

sources:

   rom:

        url: https://images.ecloud.global/stable/herolte/e-latest-herolte.zip

        filePath: e-latest-herolte.zip

   twrp:         

        url: https://images.ecloud.global/stable/twrp/herolte/twrp-3.2.3-0-herolte.img

        filePath: twrp-3.2.3-0-herolte.img

flash:

    f1:

        ui:

            type: action

            title: stepTitle1On7

            instruction:

            - install_instr_turnOff

            - install_instr_startDownload

            - install_instr_acceptWarning

            stepNumber: 1/7

            titleIcon: Download.png

            instructionImg: group2.png

    f2:

        ui:

            type: load

            title: stepTitle2On7

            instruction:

            - install_instr_oemUnlock

            stepNumber: 2/7

            averageTime: 8

...

```

It contains two parts: `sources` which specifies files that need to be downloaded and `flash` which defines UI for the different steps.

__/!\ files must have a sha256sum to check integrity. The sha256 should be the exact filename(with extension) +".sha256sum". The sha256sum should be in the same folder as the target file. It will be downloaded automatically.__

#### `flash`

- `url` specifies the url that points to the resource.

	_example: `url: https://path/to/the/file.extension`_

-`filePath` specifies the file's name on the user's computer once it has been downloaded

There are three types of UI (user interface): `action`, `load` and `askAccount`

#### `action` type

It corresponds to the step where the user has to perform an action (like pressing button).

It has the following structure:

```yaml

            type: action

            title: stepTitle1On7

            instruction:

            - install_instr_turnOff

            - install_instr_startDownload

            - install_instr_acceptWarning

            stepNumber: 1/7

            titleIcon: Download.png

            instructionImg: group2.png

```

- `title` contains the translations' key for the step's title. The value is defined in `src/main/resources/lang/traduction.properties`

- `instruction` are translations' keys for the instruction at this step. Their values are defined in `src/main/resources/lang/traduction.properties`

It is also used to identify pictures to display along with the instruction. Pictures are defined like instructions' text but are located in `src/main/resources/instructions/imageName.properties`

- `stepNumber` defines the step place in the process

- `titleIcon` is displayed left to the title value

- `instructionImg` is ignored and will be removed soon.

#### `load` type

``` yaml

            type: load

            title: stepTitle2On7

            instruction:

            - install_instr_oemUnlock

            stepNumber: 2/7

            averageTime: 8

```

- `title` is the same as for `action type`

- `instruction` is the same as for `action` type except that it must have only one instruction.

- `stepNumber` is the same as for `action` type.

- `averageTime` defines the average time the step is required to do its job. it is in second.

- `instruction` is the same as for `action` type except that it must have only one instruction.

#### Good practice:

- '~': is used for empty or null value.

- defines "normal" step code with 'f' and a incremental number. It helps to understand the whole process.

- defines "failure" step code with 'e' and a incremental number. It helps to understand the whole process.

## Lets make the translation file

### Was ist die Translation-Datei?

Eine Translation-Datei hat die Erweiterung „.properties“.

It also contains country code & local lang code before the extension and is separated by `"_"`.

Base name is: translation.

The complete name is:

- `translation.properties` for the default translation's file. This file will be used when no translations are found in a specific language.

- `translation_xx_XX.properties` It is a language specific translation's file.

__i.e :__ `translation_fr_FR.properties`.

It is stored in the project and build with the App.

`To update translation, we need to rebuild the application.`

### Contents of the translation file

The content of a translation file is not limited in size.

_one row = one translation

a Row is structured with the following pattern: `reference=value`

- `reference` is the code used to load the value.

- `value` is the raw text that will be display to the user

_example:_ trad_1_title=first title of the translation

_one row = one translation

a Row is structured with the following pattern: `reference=value`

- `reference` is the code used to load the value.

- `value` is the raw text that will be display to the user

_example_: trad-example=firstline\nsecondline

Result:

```

firstline

secondline

```

_example_: trad-example=firstline\nsecondline

Each part of the pattern will be separated by `"_"`

1. First part is an identifier for the UI which use the button.

Result:

```

firstline

secondline

```

3. third part is a unique identifier

_Theorical examples:_

```

UI-1_label_uid1

UI-2_button_uid1

UI-2_button_uid2

UI-2_title_uid1

```

#### a. UI identifier

The different interface are listed below (inspired by the tab's name in [this document](https://office.ecloud.global/products/files/doceditor.aspx?fileid=2121#) :

- welcome

- before

- connect

- devMode

- ADBdebug

- detect

- download

- install

- eAccount

- congrats

- feedback

_note:_  we don't use `UI` with a number corresponding at the order of the interface in the whole process.

Because if we want to change the process order, we'll have to change all translation reference...

#### b. Element type

possible element's type with corresponding code to use, are:

- Main title : `mTitle`

- title: `title`

- subtitle : `sbTitle`

- Label : `lbl`

- Button : `btn`

- instruction: `instr`

#### c. Unique identifier

use 'uid' with a simple incremental value.

The incremental value restart from 0 for each UI's identifier and each element type.

or use a text identifier.

- Main title : `mTitle`

- title: `title`

- subtitle : `sbTitle`

- Label : `lbl`

- Button : `btn`

- instruction: `instr`

#### d. Real example

_note_: in the following example, the value describe the position or the content, but it can be anything else.

```

interface_mTitle_uid1=This is a main title

interface_sbTitle_uid1=this is the first subtitle

interface_sbTitle_uid2=this is the second subtitle

interface_sbTitle_uid3=this is the third subtitle

interface_lbl_version=this is the version Number

interface_lbl_uid1=this is the label below the first subtitle

interface_lbl_uid2=this is the label below the second subtitle

interface_lbl_uid3=this is the label below the third subtitle

interface_btn_uid1=this is the button to change interface

```

{% include alerts/warning.html content=" Ein neues Installationsprogramm, [der WebInstaller](https://e.foundation/installer/) ist nun als Alpha-Version verfügbar. Dieser Webinstaller funktioniert in Browsern, die auf Chrome basieren, weil er WebUSB benötigt.

Der EasyInstaller wird bald nicht mehr unterstützt. " %}

## What does the Easy Installer do?

The Easy Installer is a software that will guide you as you flash /e/OS on your phone all by yourself. Unfortunately, you can't just plug in your phone and wait until the process is done. There is always some manual action required. The Easy Installer will tell you what and when you have to do something. For example: pressing one or several physical buttons, taping on some buttons, enabling options, rebooting your phone, etc.

It will also perform commands in the background that you would otherwise have to run yourself. 

Within a shell...(you know, this scary black screen window where geeks write strange things :computer:)

<img src="../images/Shell2.png" width="400" alt="Linux shell prompt example">

In addition, it will download source files and check their integrity. 

Please do not rush, and read all the instructions carefully. They aren't perfect yet, and are still being improved.

## My phone isn't detected

###  **Windows users**:  YOU NEED drivers for your phone.

This is a complicated subject, but you have to know that there isn't one single driver that works for everything.

A driver is a piece of software that allows your Windows computer to communicate with a plugged phone. There are drivers for your screen, mouse, keyboard, printer, gamepad, smartphone, etc. Unfortunately, some drivers are hard to find and don't work with all smartphone modes. 

{% tf pages/easy-installer-install-drivers.md %}

### The phone asks me to allow USB debugging. What should I do?

The Easy Installer communicates with your phone thanks to a tool called ADB (Android Debug Bridge). When you use it for the first time, on a specific computer, a prompt message is displayed on your phone. 

<img src="../images/Easy-installer-rsaFingerprint.png" width="300" alt="Example of RSA fingerprint message">

If you're on a trusted computer, you should also tick the checkbox to always allow connections between the computer and the device. If you do not tick the checkbox, you will have to accept it again next time.

You must accept this message by clicking on the "Allow" button. 

####  I cancelled the message on my phone 

If you clicked on the cancel button, then your phone can't communicate with your PC.

Just unplug then replug your phone, the message will show up again.

### Try another cable

You should try to use a different USB cable. Only use a cable that allows data transfer.

Some cables are only meant for battery charging.

USB cables are the source of many issues, because they're often not made to last.

### Try another computer

If any of the above solutions worked, you should try with another computer

## Downloading of sources failed immediately after the beginning

[Check that "images" server is available](https://status.e.foundation).

If server is unavailable, please try again later.

## Downloading of sources failed after a long period

Click on the restart button displayed, then the downloading will restart from where it stopped.

The sources server has a timeout set to 1 hours. Consequently, if your connection is slow, it might stop before the end. 

## Instructions and illustrations don't correspond to my phone

Pictures are here to help but there aren't the main content. If you must choose, please follow the text intructions.

You'll find  help from [the community forum](https://community.e.foundation/c/community/easy-installer/136)

Help to improve instruction by making suggestion, translating or providing screenshots of your phone would be appreciate a lot!

## I want to select community or official builds

This is possible for some devices. Check the `Additional Info` column in [this table](https://doc.e.foundation/easy-installer#list-of-devices-supported-by-the-easy-installer) 

## Ich verstehe kein Englisch, ich möchte den Easy-Installer in meiner Sprache benutzen

Der Easy-Installer benutzt die Sprache deines Computers. Falls die Unterstützung für deine Sprache fehlt, 

wird Englisch als Standard benutzt.

Easy-installer supports (partially sometimes) the following languages:

- English

- French

- German

- Dutch

- Russian

- Basque

## GS290 flashing does not finalize

We don't have all the card in hand yet, but we're investigating into this issue to bring a solution as soon as possible.

Please share logs with us, and join [this discussion](https://community.e.foundation/t/gs290-easy-installer-stops/27917)  on our community forum.

## "OEM unlock" option is missing in settings of my Samsung phone

The Samsung process to enable to activate "oem unlock" option in developer settings is quite complicated

because they want to block the bootloader. Consequently, you won't find official documentation about it.

However, you can find many links on internet on how to enable

the "OEM unlock" option.

Community members also suggested:

- https://www.xda-developers.com/fix-missing-oem-unlock-samsung-galaxy-s9-samsung-galaxy-s8-samsung-galaxy-note-8/

- https://androidmore.com/fix-missing-oem-unlock-toggle-samsung/

There are already several discussions on our forum about this:

- https://community.e.foundation/t/i-do-not-have-the-option-for-unlock-oem-in-developer-options/20222/2

- https://community.e.foundation/t/galaxy-s8-oem-unlock/28305

- https://community.e.foundation/t/unclear-about-instructions-unlock-oem/20875/9

You might also want to do the following:

- Connect your phone to Wi-fi

- Update your device to the latest version of the original OS

## The installation of "TWRP" (the recovery) fails

There is a "special" step during the process for Samsung phones. After the recovery is installed,

you'll have to leave the download mode (by pressing continuously on "Power"+"volume down"). As soon as the screen become black (like an off device) you must immediately start into recovery (by pressing continuously on "Power"+"volume up"+"bixby"/"home"). Our tip is to only move the finger from the volume button.

The manipulation is a little tricky but not impossible.

**Note:** We know that there is no warning about it yet, but we'll add it in future release. 

You can find more information on the community forum :

- https://community.e.foundation/t/e-on-samsung-galaxy-s8-cant-reboot-into-twrp/21696

- https://community.e.foundation/t/e-easy-installer-samsung-galaxy-s7-no-teamwin-help-please/27887/3

If it still blocked, and if you have a windows computer, you can try to flash TWRP (the recovery) by using [ODIN tools](https://samsungodin.com/) instead of heimdall. Once TWRP is installed, you can restart easy-installer and finish the process.

## Unlock code from Fairphone website doesn't work

Your smartphone must have the latest version of Fairphone OS to make the oem unlock code to work.

If you are still unable to unlock your Fairphone, please [contact Fairphone directly](https://www.fairphone.com/en/about/contact-us/) 

## On which OS did you test the easy-installer ?

We developed the Easy-installer on Ubuntu (20.04) and Windows (10).

It should work without any issue on Windows 7, 8, 10, Ubuntu, ElementaryOS and Linux Mint.

## I want to install the Easy Installer on a Windows without admin access

You will be able to install, but you won't get a shortcut in your non-admin account.

You have some knowledge in NSIS (tools to create windows installer)? Feel free to give us an hand at <the issue>

## I want to see log files

The installer creates a log file with a randomly generated name (e.g. 45761d08-711f-435a-881d-a236949654bb.log) that might contain useful information if something doesn’t work as expected.

Location of the log file:

- **Linux:** ~/snap/easy-installer/common

- **Windows:** %LOCALAPPDATA%\easy-installer

The log file is too large to upload to the forum directly. If you report a problem, please paste the contents of the logfile to https://haste.tchncs.de/ and click the save icon there which will generate a link which you can then use here.

If the log is too large even to be pasted and you already have an Murena Workspace account, you can ZIP the log and upload it to your Murena Workspace storage.

## My device is not detected on Windows

The Easy Installer requires drivers to be installed on Windows OS for device detection. You can download vendor specific drivers [here](https://developer.android.com/studio/run/oem-usb). For Google Nexus devices check [this guide](https://developer.android.com/studio/run/win-usb). Please note both are external links.

## My question is not listed here

If you don't find an answer to your question, a solution to your issue, please contact the [community support](https://t.me/joinchat/D1jNSmJHKo4u70ha).

You can also check on the [community forum](https://community.e.foundation/c/community/easy-installer/) or directly ask for help there.

You should also check [this page](https://community.e.foundation/t/howto-troubleshoot-issues-with-the-easy-installer/23290) which contains many hints.