diff --git a/README.md b/README.md index fc8c4d7068130e929e307cac46df1cc1855ef567..06610b01a68db5babe13b3d09825a26b061ecd7a 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,155 @@ -[last updated : 2024-08-12 ] +# /e/OS Installer -`app` folder contains the source of the application. +Install /e/OS from a chromium-based browser -`extern` folder contains dependencies that are *not* embedded from package.json - This is the case for fastboot.js the `fastboot.js/dist` folder if modified must be copied into `app\src\static\js\fastboot` folder +- **Online instance**: [https://e.foundation/installer](https://e.foundation/installer) +- **Documentation**: [https://doc.e.foundation/eos-installer](https://doc.e.foundation/eos-installer) +- **Source code**: [https://gitlab.e.foundation/e/devices/eos-installer](https://gitlab.e.foundation/e/devices/eos-installer) -# Build the image +[[_TOC_]] -Go to the `app` folder. +## Features -`docker build -t eos-web-installer .` +- detect the device +- guide the user to unlock the bootloader +- guide the user to flash /e/OS +- when possible, guide the user to lock the bootloader -# Run the project +## Run the project -## Windows -`docker run -v "%cd%"\src:/app/src -p 127.0.0.1:3000:3000 eos-web-installer` +1. Get the docker image: `docker pull registry.gitlab.e.foundation/e/devices/eos-installer:latest` +2. Run a docker container + - Windows: `docker run -v "%cd%"\src:/app/src -p 127.0.0.1:3000:3000 eos-installer` + - Linux: `docker run -v "$(pwd)/src:/app/src" -p 127.0.0.1:3000:3000 eos-installer` +3. The app is available at `http://localhost:3000/` -## Linux -`docker run -v "$(pwd)/src:/app/src" -p 127.0.0.1:3000:3000 eos-web-installer` +## Usage -The project is available at `http://localhost:3000/` +## Contributing -# Installation +### Build -Drop the files used to flash the device in the corresponding folder in `static/assets/sources` -And **overwrite the .json** file in `static/js/resources` of your device with the correct file name - -# Development information - -## Model - -We link device and its resources with deviceName.toLowerCase().replace(/ /g, ''); ex: One Plus Nord -> oneplusnord.json -Since the deviceName may not be the same in fastboot (Android), we need at least a first connexion in adb to retrieve the deviceName. +```shell +docker build -t eos-installer app/. +``` -## Doctrine +### Add a new device + +1. Get the device code from the stock ROM + - We link device and its resources with deviceName.toLowerCase().replace(/ /g, ''); ex: One Plus Nord -> oneplusnord.json + - Since the deviceName may not be the same in fastboot (Android), we need at least a first connexion in adb to retrieve the deviceName +2. Understand how does the flash process works +3. Configure the flash process + - Define the steps in an array of objects describing the process + - template: + ```json + "steps": [ + { + "mode": string?, + "command" : string?, + "instruction": string?, + "needUser": boolean? + } + ] + ``` + - Options + + | key | exemple | description | + |---------------|---------------------------------|-----------------------------------------------------------------------------| + | `mode` | `[fastboot\| adb\| bootloader]` | It's a shortcut for a reboot and a reconnect before the command is executed | + | `needUser` | `[true\| false]` | The user needs to click on continue before the command is executed | + | `instruction` | `Please select unlock` | String displayed to the user at this step. Command is used if not defined | + | `command` | `flashing unlock unlocked` | Command as defined in the next chapter | + - Available commands + + | command | exemple | description | + |----------------------------------------|----------------------------|-----------------| + | `[flashing\| oem] unlock [varName?]` | `flashing unlock unlocked` | -------------- | + | `[flashing\|oem] lock [varName?]` | `flashing lock` | -------------- | + | `flash [partitionName] [fileName.img]` | `flashing unlock unlocked` | -------------- | + | `sideload [fileName.zip]` | `sideload romFile.zip` | -------------- | + | `erase [partitionName]` | `erase userdata` | -------------- | + | `reboot [fastboot\| adb\| bootloader]` | `reboot bootloader` | -------------- | + | `connect [adb\| bootloader]` | `connect device` | -------------- | + + > For oem, recovery, rom and key, we parse these command and execute them. The others commands are not analyzed and executed arbitrarily in the device. + + - Define the folder, an array describing the files involved in the flash process + - template: + ```json + "folder": [ + { + name : fileName used for the command , + path: path used to download the file, + unzip: optional boolean in case we have a zip we want to parse + } + ] + ``` + + > In case of unzip : the file is unzipped, and the retrieved files are stored in the "folder" like the other file + - example: + + ```json + { + "folder": [ + { + "name": "recovery.img" + "path" : "assets/sources/coral/recovery-e-1.14-s-20230818321663-dev-coral.img" + }, + { + "name": "rom.zip", + "path" : "assets/sources/coral/e-1.14-s-20230818321663-dev-coral.zip" + }, + { + "name": "pkmd_pixel.bin", + "path" : "assets/sources/coral/pkmd_pixel.bin" + }, + { + "path" : "assets/sources/emerald/IMG-e-1.14.2-s-20230825321006-stable-emerald.zip", + "name": "Teracube_2e installer", + "unzip": true + }, + ] + } + ``` +4. Adding images + - Add the images files within `app/src/static/assets/images/illustrations/fp5` + - declare the image in the html, at `app/src/static/index.html` + - example: + ```html + +
+
+
+

+

+
+ +
+
+
+ +
+
+ ``` + +### Other + +- Vues + - `vue.manager.js` + - Need log.manager.js and translation.manager.js + - Need a div with id "process" + - `log.manager.js` + - Need a div with id "log-ctn" to scroll on log added + - Need a select with id "log" to add log + - `translation.manager.js` + - Need a select with id "translation" to listen to. + - On select change : download the translation file and render the DOM + - Translation are in `static/assets/languages` +- Controller + - `controller.manager.js` + +### Doctrine - my-class are for css class - camelCase are for variable @@ -42,119 +158,22 @@ Since the deviceName may not be the same in fastboot (Android), we need at least - object.manager.js are for class directing subClass or vue. It's just my arbitrary concept to mark a class as "directive" in the process - object.class.js are for class used by object.manager.js where functions should have a single responsibility -Please respect ♥ - - -## Defining a process - -A process is in 2 parts : steps and folder - -### Steps - -#### Description - -Steps is an array on objects describing the process - -``` -"steps": [ - { - "mode": string?, - "command" : string?, - "instruction": string?, - "needUser": boolean? - } - ] -``` -#### Options - -| key | exemple | description | -|---------------|---------------------------------|-----------------------------------------------------------------------------| -| `mode` | `[fastboot\| adb\| bootloader]` | It's a shortcut for a reboot and a reconnect before the command is executed | -| `needUser` | `[true\| false]` | The user needs to click on continue before the command is executed | -| `instruction` | `Please select unlock` | String displayed to the user at this step. Command is used if not defined | -| `command` | `flashing unlock unlocked` | Command as defined in the next chapter | - -#### Available commands - -| command | exemple | description | -|----------------------------------------|----------------------------|-----------------| -| `[flashing\| oem] unlock [varName?]` | `flashing unlock unlocked` | -------------- | -| `[flashing\|oem] lock [varName?]` | `flashing lock` | -------------- | -| `flash [partitionName] [fileName.img]` | `flashing unlock unlocked` | -------------- | -| `sideload [fileName.zip]` | `sideload romFile.zip` | -------------- | -| `erase [partitionName]` | `erase userdata` | -------------- | -| `reboot [fastboot\| adb\| bootloader]` | `reboot bootloader` | -------------- | -| `connect [adb\| bootloader]` | `connect device` | -------------- | - - -For oem, recovery, rom and key, we parse these command and execute them. The others commands are not analyzed and executed arbitrarily in the device. - -#### Exemples - - -### Folder - -#### Description - -You need to add a variable folder to define the files needed in the installation. -Folder is an array of file : -``` -{ - name : fileName used for the command , - path: path used to download the file, - unzip: optional boolean in case we have a zip we want to parse -} -``` -In case of unzip : the file is unzipped, and the retrieved files are stored in the "folder" like the other file - - -#### Exemples -``` -{ - "folder": [ - { - "name": "recovery.img" - "path" : "assets/sources/coral/recovery-e-1.14-s-20230818321663-dev-coral.img" - }, - { - "name": "rom.zip", - "path" : "assets/sources/coral/e-1.14-s-20230818321663-dev-coral.zip" - }, - { - "name": "pkmd_pixel.bin", - "path" : "assets/sources/coral/pkmd_pixel.bin" - }, - { - "path" : "assets/sources/emerald/IMG-e-1.14.2-s-20230825321006-stable-emerald.zip", - "name": "Teracube_2e installer", - "unzip": true - }, - ] - } - ``` - - - -## Vue - -### vue.manager.js -Need log.manager.js and translation.manager.js -Need a div with id "process" - -### log.manager.js -Need a div with id "log-ctn" to scroll on log added -Need a select with id "log" to add log - -### translation.manager.js -Need a select with id "translation" to listen to. -On select change : download the translation file and render the DOM +Please respect ♥ -Translation are in `static/assets/languages` +## License -## Controller +[GPLv3](https://gitlab.e.foundation/e/devices/web-easy-installer/-/blob/main/LICENSE) -### controller.manager.js +## Acknowledgments +Using: +- vanilla Javascript, CSS and HTML +- Docker for packaging -CAUTION +Libraries: +- fastboot.js (License: MIT): https://github.com/kdrag0n/fastboot.js/ +- ya-webadb (License: MIT): https://github.com/yume-chan/ya-webadb +- zip-no-worker-inflate.js (License: BSD3): https://github.com/gildas-lormeau/zip.js/blob/master/lib/zip-no-worker-inflate.js +Contributors: +- Frank Preel (frank.preel@espridigital.fr) and Paula Grente (paula.grente@8espridigtal.fr) from [ESPRI Digital](https://espridigital.fr/) \ No newline at end of file diff --git a/app/README.md b/app/README.md deleted file mode 100644 index 3b26add6baec24b38fcba86eb46d7e1d409d667d..0000000000000000000000000000000000000000 --- a/app/README.md +++ /dev/null @@ -1,174 +0,0 @@ -[last updated : 2023-10-17 ] - -`app` folder contains the source of the application. - -`extern` folder contains dependencies that are *not* embedded from package.json - This is the case for fastboot.js the `fastboot.js/dist` folder if modified must be copied into `app\src\static\js\fastboot` folder - - - -# Build the image - -Go to the `app` folder. - -`docker build -t eos-web-installer .` - -# Run the project - -## Windows -`docker run -v "%cd%"\src:/app/src -p 127.0.0.1:3000:3000 eos-web-installer` - -## Linux -`docker run -v "$(pwd)/src:/app/src" -p 127.0.0.1:3000:3000 eos-web-installer` - -The project is available at `http://localhost:3000/` - -# Installation - -Drop the files used to flash the device in the corresponding folder in `static/assets/sources` -And **overwrite the .json** `static/resources` file of your device with the correct file name - -# Development information - - -## Model - -We link device and its resources with deviceName.toLowerCase().replace(/ /g, ''); ex: One Plus Nord -> oneplusnord.json -Since the deviceName may not be the same in fastboot (Android), we need at least a first connexion in adb to retrieve the deviceName. - -## Doctrine - -- my-class are for css class -- camelCase are for variable -- $variableName are for DOM Nodes -- MAJUSCULE are for global constant -- object.manager.js are for class directing subClass or vue. It's just my arbitrary concept to mark a class as "directive" in the process -- object.class.js are for class used by object.manager.js where functions should have a single responsibility - -Please respect ♥ - - -## Defining a process - -A process is in 2 parts : steps and folder - -### Steps - -#### Description - -Steps is an array on objects describing the process - -``` -"steps": [ - { - "mode": string?, - "command" : string?, - "instruction": string?, - "needUser": boolean? - } - ] -``` -#### Options - -| key | exemple | description | -|---------------|---------------------------------|-----------------------------------------------------------------------------| -| `mode` | `[fastboot\| adb\| bootloader]` | It's a shortcut for a reboot and a reconnect before the command is executed | -| `needUser` | `[true\| false]` | The user needs to click on continue before the command is executed | -| `instruction` | `Please select unlock` | String displayed to the user at this step. Command is used if not defined | -| `command` | `flashing unlock unlocked` | Command as defined in the next chapter | - -#### Available commands - -| command | exemple | description | -|----------------------------------------|----------------------------|-----------------| -| `[flashing\| oem] unlock [varName?]` | `flashing unlock unlocked` | -------------- | -| `[flashing\|oem] lock [varName?]` | `flashing lock` | -------------- | -| `flash [partitionName] [fileName.img]` | `flashing unlock unlocked` | -------------- | -| `sideload [fileName.zip]` | `sideload romFile.zip` | -------------- | -| `erase [partitionName]` | `erase userdata` | -------------- | -| `reboot [fastboot\| adb\| bootloader]` | `reboot bootloader` | -------------- | -| `connect [adb\| bootloader]` | `connect device` | -------------- | - - -For oem, recovery, rom and key, we parse these command and execute them. The others commands are not analyzed and executed arbitrarily in the device. - - - - - -#### Exemples - - -### Folder - -#### Description - -You need to add a variable folder to define the files needed in the installation. -Folder is an array of file : -``` -{ - name : fileName used for the command , - path: path used to download the file, - unzip: optional boolean in case we have a zip we want to parse -} -``` -In case of unzip : the file is unzipped, and the retrieved files are stored in the "folder" like the other file - - -#### Exemples -``` -{ - "android": 13, - "security_patch_level": "2024-04-05", - "steps": [ - ... - ], - "folder": [ - { - "name": "recovery.img" - "path" : "assets/sources/coral/recovery-e-1.14-s-20230818321663-dev-coral.img" - }, - { - "name": "rom.zip", - "path" : "assets/sources/coral/e-1.14-s-20230818321663-dev-coral.zip" - }, - { - "name": "pkmd_pixel.bin", - "path" : "assets/sources/coral/pkmd_pixel.bin" - }, - { - "path" : "assets/sources/emerald/IMG-e-1.14.2-s-20230825321006-stable-emerald.zip", - "name": "Teracube_2e installer", - "unzip": true - }, - ] - } - ``` - -* android: Android version (optional) => Display warning if version mistach (this is the minimal current version than needs to be present in order to continue process see: Before following these instructions please ensure that the device is on the latest Android 13.0.0 firmware)) -* security_patch_level (optional) => Allow to load safe procedure descriptor file (postfixed with '-safe' eg: 'teracube2e.json vs teracube2e-safe.json') that contain a specific install process (eg does not lock the bootloader if current_security_path_level > new_security_path_level new_security_path_level is the one the json file) -* folder: must be an array - -## Vue - -### vue.manager.js -Need log.manager.js and translation.manager.js -Need a div with id "process" - -### log.manager.js -Need a div with id "log-ctn" to scroll on log added -Need a select with id "log" to add log - -### translation.manager.js -Need a select with id "translation" to listen to. -On select change : download the translation file and render the DOM - -Translation are in `static/assets/languages` - -## Controller - -### controller.manager.js - - -CAUTION - diff --git a/app/installation.pdf b/app/installation.pdf deleted file mode 100644 index 427a7a227dc164fb96ba9b76a463e791b70cf3c3..0000000000000000000000000000000000000000 Binary files a/app/installation.pdf and /dev/null differ diff --git a/assets/Auto-deployment.png b/assets/Auto-deployment.png deleted file mode 100644 index dd9f435e42286a559e3b6dd56970c429435d15eb..0000000000000000000000000000000000000000 Binary files a/assets/Auto-deployment.png and /dev/null differ diff --git a/assets/pipeline_stage1.jpeg b/assets/pipeline_stage1.jpeg deleted file mode 100644 index f380c2c67b904859e1fb73c5eb0da6059f6dd189..0000000000000000000000000000000000000000 Binary files a/assets/pipeline_stage1.jpeg and /dev/null differ diff --git a/assets/pipeline_stage2.jpeg b/assets/pipeline_stage2.jpeg deleted file mode 100644 index 0d1e315927516310f38df04c81816fda58c4cdcd..0000000000000000000000000000000000000000 Binary files a/assets/pipeline_stage2.jpeg and /dev/null differ diff --git a/assets/pipeline_stage3.jpeg b/assets/pipeline_stage3.jpeg deleted file mode 100644 index 840b8c49f08562ba2d3489ccf3887655475e120f..0000000000000000000000000000000000000000 Binary files a/assets/pipeline_stage3.jpeg and /dev/null differ diff --git a/assets/pipeline_stage4.jpeg b/assets/pipeline_stage4.jpeg deleted file mode 100644 index 1f5775e690d8b662f98c1c4bc12eab8994a64fe4..0000000000000000000000000000000000000000 Binary files a/assets/pipeline_stage4.jpeg and /dev/null differ diff --git a/assets/pipeline_stage5.jpeg b/assets/pipeline_stage5.jpeg deleted file mode 100644 index 38a2153fc5e2b5ac7e033b189dc6d7145f74e4d5..0000000000000000000000000000000000000000 Binary files a/assets/pipeline_stage5.jpeg and /dev/null differ