ubports / installer-configs

Install configurations for the UBports Installer

UBports Installer configs

This repository contains the config files for UBports Installer devices.

Devices are configured using YAML files following the schema specifcation in the ./v2/devices directory.

If you want to propose changes to the structure or propose a new action, open an issue. Device-specific installation issues should be filed directly against the UBports Installer's repository.

Contributing

If you want to add a or improve a device, run npm run build && npm run validate to make sure your file follows the specification and npm run lint to make it pretty. You can use npm run checksemver to validate semver strings and npm run checkdownloads to make sure all files download successfully. If you modify any specifications, use npm run test to run specification validation tests.

You can use your local config file with the UBports Installer by supplying the --file or -f flag:

ubports-installer -f ./path/to/config.yml

Library usage

Install using npm i ubports-installer-configs.

import validate from "ubports-installer-configs";

validate(object); // will return true or false

TypeScript Types for the config file schema are exported as UBportsInstallerConfig.

import { validate, UBportsInstallerConfig } from "ubports-installer-configs";

validate(object as UBportsInstallerConfig);

Specification

v3

WIP: You can view the open RFCs on the issue tracker or open an issue to propose a change.

v2

• published: November 2020
• lead author: Johannah Sprinz
• JSON Schema

Starting with version 0.8.1-beta, the UBports Installer uses version 2 of the config file structure. The changes in specification draw from the experience made with the initial version of the specification and take some inspiration from Ansible Playbooks and the OPEN-CUTS combination filtering language.

Some of the high-level changes include:

• The full schema will be validated and documented using JSON-schema. Previously, some parts of the structure could not be efficiently validated and documentation was not provided in a convenient way.
• To make the config files easier to read and write, the repository will use YAML syntax.
• For improved API speed, the installer will no longer fetch raw data from raw.githubusercontent.com. Instead, the YAML files from the repository will be transpiled to static minified JSON and served from a highly available web server.
• The aliases.json and index.json files from this repository will no longer be used and instead be generated and served by the server.
• Every device may specify its known aliases in an array on the top level of its config file.
• Multiple devices may claim the same alias. The UBports Installer will then consult the user to resolve the conflict.
• The fallback_user_action property has been deprecated. You can now specify a list of steps as the fallback property. ubports-installer#941
• Implement group step ubports-installer#940
• Implement flexible oem and flashing unlock instructions ubports-installer#1479
• Implement more advanced conditional logic ubports-installer#1537
• Many steps have been renamed to allow namespacing for the UBports Installer's new plugin system.
• Steps may now specify a range of actions that belong together #17

v1

• published: October 2019
• lead author: Johannah Sprinz
• JSON Schema

The initial specification of the UBports Installer config files was drafted for version 0.4.1-beta and presented at Ubucon Europe 2019. It relied on plain JSON files that the UBports Installer either read from disk or downloaded directly from the git repository. The specification was used until UBports Installer version 0.8.0-beta.

The specification includes two general files, that are written manually: The index.json file lists all available devices. If the installer detects a device automatically, it can query aliases.json to resolve the detected string to the canonical codename for the device.

Every device is configured by a <codename>.json file that contains information about the device, as well as a list of steps to install different operating systems. Re-usable instructions for the user ("user actions") can also be specified, as well as configuration options for each available operating system.

License

Original development by Johannah Sprinz. Copyright (C) 2019-2022 UBports Foundation.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

installer-configs's Issues

[v2] steps as keyed objects

For v2, we might thing about implementing steps as keyed objects, eg:

    steps:
      - adb:reboot:
          to_state: "bootloader"
        fallback:
          - user_action:
              action: "bootloader"
        condition:
          var: "bootstrap"
          value: true
      - fastboot:reboot_bootloader:
      - fastboot:set_active:
          slot: "b"

Might make schema validation and documentation easier.

Complete schema definition

Make sure the schema definition covers all cases, including all install steps. This requires some advanced jsonschema-fu.

Lint

We're already (mostly, see #1) validating the schema, but we could take it to the next level and also lint, to make sure all our json files have the same look and feel.

Provide a way to add line breaks to user actions

To improve readability, it would be nice to have support for line breaks in user actions, for example:

  fastbootd:
    title: "Reboot to Fastbootd"
    description: "With the device powered off, hold Volume Down + Power to boot into recovery.<br><br>Inside the recovery, press on 'Advanced' and select 'Enter fastboot'."
    image: "phone_power_down"
    button: true

<br> does not get handled and is rendered in text.
\n does not get handled and removed from text.

[v3] function definitions

We could have an object with keys so you can have re-usable "functions". If you for example have multiple operating systems that require TWRP, you could have a twrp function that has the steps to flash it and "call" it multiple times.

[v3] Shrink core plugin

It might make sense to have the core plugin only handle actual core actions and implement a new fs plugin for things like writing and copying files and archive (de-)compression, as well as a download plugin that handles, well, you get the idea. The core plugin would then do things like info, group, end, user_action, and the like.

Contributing config file for moto g5

I have a moto g5 phone (not moto g5+). It has 3 GB RAM, 16 GB internal memory, has android 8.1.0 running on it, and Snapdragon 430. I was looking to run Ubuntu Touch on it, when I came to this site. I would love to contribute and was looking for guidance on how to do so. Maybe the community can help.

Ubuntu

Redmi Note 8 Pro begonia Fakap

Ubports installs version 16.04 from 21/09/2021, regardless of whether Channel 20.04 or 16.04/stable is selected, according to the page, the last update was from 4/17/2023 (https://devices.ubuntutouch.io/device/begonia/#portStatus)

Incomplete device configs are not prompting the user to enter lock code

In the installer repo we get a lot of issues like ubports/ubports-installer#2831 (comment).
This is mainly happening to users with Xiaomi devices because they require an unlock code to unlock the bootloader. I went through some of the device configs and recognized that

handlers:
  bootloader_locked:
    actions:
      - fastboot:oem_unlock:

is implemented but without the field code_url: "someurl" they get no input to enter the code. Which causes the unlock to fail.
Of course you can prompt the user to unlock the device before he even starts the install but this case should be handled properly.
One solution would be to add those missing field. (I don't know if all vendors are providing codes - other tools might be needed)

Investigate fastboot reboot recovery

Fixed. On related note, there currently seems to be no way to reboot from fastboot to recovery? (fastboot reboot recovery command)

Originally posted by @NotKit in #133 (comment)

Update Suzu config to use manual_download step and OEM fastboot flash

With the addition of ubports/ubports-installer#1377, the suzu.json config needs to be updated to make use of the manual_download step for the OEM binary and the follow-on fastboot flash oem to install it.

The specific OEM for Suzu is: SW_binaries_for_Xperia_AOSP_N_MR1_5.7_r1_v08_loire.zip (named "Software binaries for AOSP Nougat (Android 7.1) – Kernel 4.4 – Loire")
SHA256: 9d9d6df01f0816e74b386daf82658768a54e515161ee9fb907a7aae292167e51
The download location is: https://developer.sony.com/file/download/software-binaries-for-aosp-nougat-android-7-1-kernel-4-4-loire/

expand handlers

we already have handlers for bootloader_locked, but it might be possible to extend this for more errors. needs some thinking

fastboot:flashing_unlock does not handle code_url

fastboot:oem_unlock: allows providing a code_url to specify a link to follow for instructions regarding how to obtain a code to unlock the bootloader.

fastboot:flashing_unlock: does the same as fastboot:oem_unlock: but does not allow providing a code_url according to action.schema.yml.

installer-configs/v2/devices/yggdrasil.yml pulls wrong sailfishos version

Included link in yaml file

https://gitlab.com/sailfishos-porters-ci/yggdrasil-ci/-/jobs/artifacts/master/download?job=run-build-lvm

downloads and installs non working run-mic-lvm artefact, run-mic-lvm-testing should be used instead.

[v3] option interdependencies

It should be possible to only display certain options if other options are met. A possible structure could be:

options:
      - var: "opengapps"
        name: "Install OpenGapps"
        type: "boolean"
        value: false
      - var: "opengappsChannel"
        name: "OpenGapps Channel"
        tooltip: "Do you want to install pico nano micro mini full version of OpenGapps?"
        link: "https://opengapps.org/"
        type: "select"
        remote_values:
          opengapps:channels:
        condition:
          var: "opengapps"
          value: true

Originally posted by @Vince1171 in #86 (comment)

Usecases:

• #86
• https://gitlab.com/postmarketOS/postmarketos/-/issues/38

Implement "similar" devices

It should be possible to declare a list of codenames that are similar and often confused with each other. This could replace the hacky confirm_model unlock step we implemented in #11.

It would allow us to generate a prompt from it in the installer and immediately provide buttons that send you to the os selection page for the correct device.

rmor_6e

Add Volla OS 12.1 for yggdrasil

Should be https://ota.volla.tech/volla-10.0-20210927-release-k63v2_64_bsp-signed.zip

https://yaml.org/

What It Is:
YAML is a human-friendly data serialization
language for all programming languages.

YAML Resources:
YAML Specifications:

• YAML 1.2:
  • Revision 1.2.2 # Oct 1, 2021 New
  • Revision 1.2.1 # Oct 1, 2009
  • Revision 1.2.0 # Jul 21, 2009
• YAML 1.1
• YAML 1.0

YAML Matrix Chat: '#chat:yaml.io' # Our New Group Chat Room!
YAML IRC Channel: libera.chat#yaml # The old chat
YAML News: twitter.com/yamlnews
YAML Mailing List: yaml-core # Obsolete, but historical

YAML on GitHub: # github.com/yaml/
YAML Specs: yaml-spec/
YAML 1.2 Grammar: yaml-grammar/
YAML Test Suite: yaml-test-suite/
YAML Issues: issues/

YAML Reference Parsers:

• Generated Reference Parsers
• YPaste Interactive Parser

YAML Test Matrix: matrix.yaml.io

YAML Frameworks and Tools:
C/C++:

• libfyaml # "C" YAML 1.2 processor (YTS)
• libyaml # "C" Fast YAML 1.1 (YTS)
• libcyaml # YAML de/serialization of C data (using libyaml)
• yaml-cpp # C++ YAML 1.2 implementation

Crystal:

• YAML # YAML 1.1 from the standard library

C#/.NET:

• YamlDotNet # YAML 1.1/(1.2) library + serialization (YTS)
• yaml-net # YAML 1.1 library

D:

• D-YAML # YAML 1.1 library w/ official community support (YTS)

Dart:

• yaml # YAML package for Dart

Delphi:

• Neslib.Yaml # YAML 1.1 Delphi binding to libyaml (YTS)

Elixir:

• yaml-elixir # YAML support for the Elixir language

Erlang:

• yamerl # YAML support for the Erlang language

Golang:

• Go-yaml # YAML support for the Go language
• Go-gypsy # Simplified YAML parser written in Go
• goccy/go-yaml # YAML 1.2 implementation in pure Go

Haskell:

• HsYAML # YAML 1.2 implementation in pure Haskell (YTS)
• YamlReference # Haskell 1.2 reference parser
• yaml # YAML 1.1 Haskell framework (based on libyaml)

Java:

• SnakeYAML Engine # Java 8+ / YAML 1.2
• SnakeYAML # Java 5 / YAML 1.1
• YamlBeans # To/from JavaBeans. YAML 1.0/1.1
• eo-yaml # YAML 1.2 for Java 8. Packaged as a Module (Java 9+)
• Chronicle-Wire # Java Implementation

JavaScript:

• yaml # JavaScript parser/stringifier (YAML 1.2, 1.1) (YTS)
• js-yaml # Native PyYAML port to JavaScript (Demo)

Nim:

• NimYAML # YAML 1.2 implementation in pure Nim (YTS)

OCaml:

• ocaml-yaml # YAML 1.1/1.2 via libyaml bindings
• ocaml-syck # YAML 1.0 via syck bindings

Perl Modules:

• YAML # Pure Perl YAML 1.0 Module
• YAML::XS # Binding to libyaml
• YAML::Syck # Binding to libsyck
• YAML::Tiny # A small YAML subset module
• YAML::PP # A YAML 1.2/1.1 processor (YTS)

PHP:

• The Yaml Component # Symfony Yaml Component (YAML 1.2)
• php-yaml # libyaml bindings (YAML 1.1)
• syck # syck bindings (YAML 1.0)
• spyc # yaml loader/dumper (YAML 1.?)

Python:

• PyYAML # YAML 1.1, pure python and libyaml binding
• ruamel.yaml # YAML 1.2, update of PyYAML; comments round-trip
• PySyck # YAML 1.0, syck binding
• strictyaml # Restricted YAML subset

R:

• R YAML # libyaml wrapper

Raku:

• YAMLish # Port of YAMLish to Raku
• YAML::Parser::LibYAML # LibYAML wrapper

Ruby:

• psych # libyaml wrapper (in Ruby core for 1.9.2)
• RbYaml # YAML 1.1 (PyYAML Port)
• yaml4r # YAML 1.0, standard library syck binding

Rust:

• yaml-rust # YAML 1.2 implementation in pure Rust
• serde-yaml # YAML de/serialization of structs

Shell:

• parse_yaml # Simple YAML parser for Bash using sed and awk
• shyaml # Read YAML files - jq style

Swift:

• Yams # libyaml wrapper

Others:

• yamlvim # YAML dumper/emitter in pure vimscript

Related Projects:

• Rx # Multi-Language Schemata Tool for JSON/YAML
• Kwalify # Ruby Schemata Tool for JSON/YAML
• pyKwalify # Python Schemata Tool for JSON/YAML
• yatools.net # Visual Studio editor for YAML
• JSON # Official JSON Website
• Pygments # Python language Syntax Colorizer /w YAML support
• yamllint # YAML Linter based on PyYAML
• YAML Diff # Semantically compare two YAML documents
• JSON Schema # YAML-compliant JSON standard for data validation

Installer and devices website unable to get device configs

Hello, this API now points to a 404: https://ubports.github.io/installer-configs/v2/
Devices website and installer need this API to fetch the list of compatible devices.

Serve boot image and vbmeta on UBports CD Image server

@Flohack74 Hello! Can you please upload boot and vbmeta images to cd image server from my gitlab repo?

Implement resumable steps

Implement a property on the steps that indicates that a failure on a step does not need the whole installation to restart.

Ubuntu for Ulefone Amor_6e

[v2] Other operations than installs

It might be nice to also support describing other operations with our step syntax. This could include things such as maintenance tasks, flashing system partitions without replacing the OS, backups, etc. There might be operations that only apply to a specific OS, as well as some that apply to all.

Xiaomi Redmi 9A config

Please add this :)

`$schema: https://json-schema.org/draft/2020-12/schema
$id: "_.schema.yml"
title: "UBports Installer Config"
description: "Device configuration for the UBports Installer"
type: "object"
properties:
name: "Xiaomi Redmi 9A"
codename: "redmi-9a"
formfactor:
brand: "Xiaomi"
model: "Redmi 9A"
physical: "smartphone"
aliases: ["mi-redmi9a"]
doppelgangers: []
user_actions: {}
handlers:
bootloader_locked:
title: Handle a bootloader locked error
command: "fastboot oem unlock"
unlock: ["unlock_bootloader"]
operating_systems:
- version: "20.04"
rootfs: "ubuntu_touch_arm64.img.xz"
channel: "stable"
required:

• "name"
• "codename"
• "operating_systems"
• "formfactor"
  additionalProperties: false
  `

[v3] Localization

If we want to localize the installer ubports-installer#101, we also need to translate the instruction strings on here. I think it is important not to bloat the config files themselves, so i suggest we continue writing them in English and then build translated versions for the API.

We could make a script to collect all the strings that need to be translated, such as user action bodies and titles and option descriptions. It should output a file to be committed to the repository and parsed by UBports Weblate. Translators gonna translate. Weblate then makes a PR once a week with the updated translated strings. The api build script will then build localized json files in namespaces (eg /v3/devices/eo/bacon.json) with all available translated strings replaced. Unavailable strings remain in English.

Since the API is statically built, we might want to avoid offering languages that are only partially translated or unlikely to be maintained in the future. Once added, it'll be impossible to remove a language again.