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/.