Device data format specification

The devices shown on this website are added from markdown and yaml files stored at the website repository in the data/devices folder. Each device has its own folder named by the codename the manufacturer has assigned to the device.

The device folder has a main file called data.md that contains all the data that does not change between software releases. Data on the device type and specifications will be placed in this file.

In the same folder is located the releases directory that contains a markdown file for each version of Ubuntu Touch available. These files are named after the adjective of the Ubuntu release on which the release is based, for example xenial.md or focal.md.

We will then have a structure similar to the following:

suzu
├── data.md
└── releases
    ├── focal.md
    └── xenial.md

Adding new devices

You can add new devices by creating a Markdown file with a YAML metadata block under data/devices/<codename>/data.md and a Markdown file for each release available under data/devices/<codename>/releases/<release>.md. The YAML metadata block is a snippet of YAML in your otherwise Markdown-formatted document, and is denoted by three dashes alone on the line above and below the block.

---
name: My Ported Device
deviceType: phone
...
---

## You should know...

This device occasionally requests an offering of bacon. Don't ask, just provide.

## Preinstallation instructions

Before using the UBports Installer on this device, ...

There are complete templates of device markdown files for devices and releases downloadable from the website. Copy that document and fill in your device’s information as needed. Note that some optional sections which are listed in the YAML metadata block reference are not included in the example document. Carefully review the available information and fill in as much as you can.

Device file

Your YAML metadata block will have four primary sections. For more information on filling these sections, see the YAML metadata block reference below.

Device description

name: "My Cool Device"
deviceType: "phone"
description: "My Cool Device features an absurd 100:1 screen ratio that ensures you never have to scroll a webpage."
buyLink: "https://example.com"

The root level of the YAML contains base information about the device, such as its name and type.

The subforum

subforum: <the subforum id on forums.ubports.com, should be added in the format number/my-device>

The subforum id is necessary to display forum posts in the sidebar. To add it search for the subforum on the Ubports forum. The url should look like this “https://forums.ubports.com/category/number/my-awesome-device”. Take only the last two parameters in the url bar that should be in the format “number/my-awesome-device”.

Device variants

variantOf: "main-device-codename"

In case your device has many codenames or you are grouping devices of the same port you can use the variantOf keyword to inherit properties of another device by its codename.

Device specifications

deviceInfo:
  - id: "chipset"
    value: "Qualcomm MSM8956 Snapdragon 650"

The deviceInfo section contains an overview of the device’s specifications. The following data should be filled in:

Specification ID Specification name
cpu CPU
chipset Chipset
gpu GPU
rom Storage
ram Memory
android Android Version
battery Battery
display Display
rearCamera Rear Camera
frontCamera Front Camera
arch Architecture
dimensions Dimensions
weight Weight
releaseDate Release date

Contributors

contributors:
  - name: Yumi
    photo: <link to avatar picture>
    forum: <link to ubports forum profile>
    role: <Phone maker|Maintainer|Developer|Tester|Contributor>
    renewals:
        - <Maintainership renewal date in format YYYY-MM-DD (maintainers only)>

This is a place to credit the people who have worked on this device port. List them by name and their UBports Forum profile link. If they have a profile picture set on the forum, copy the image link for that picture and add it as the photo key. Otherwise, a 3D render of the Yumi mascot for UBports will be used instead.

The devices website also keeps track of device maintenance. Devices running Ubuntu Touch need to be updated from time to time on a device-specific basis in order to enable new features or complete porting progress. In addition, during system updates following the completion of porting, it is possible that some changes may cause a device's functionality to regress. Therefore, and in order to apply security patches at the hardware level, we need someone who is willing to perform these functions for an extended period of time.

If you would like to become a maintainer of your device, you can register by setting the role to maintainer and writing today's date for the first renewal. Each renewal lasts for 6 months, before the end of which you can renew the maintainer role by writing a new date in the renewals in a merge request. In case you can no longer fulfil the role of maintainer you can always open a merge request to inform us and set the property expired: true.

If the phone manufacturer supports Ubuntu Touch on the device, the "Phone maker" role can be added, which for the purposes of maintaining the device is equivalent to the maintainer but does not require periodic renewals. When the manufacturer decides to stop providing updates, they can inform us by setting the expired: true property.

externalLinks:
  - name: "Issue tracker"
    link: "https://github.com/ubports/ubuntu-touch/issues/"

External links help visitors find more information about your device port. You should have at least two links in this section:

  • An issue tracker, where people can report problems they’re having with your port. If you’re using github.com/ubports/ubuntu-touch, make sure its admins have set you up to access your bug reports there. Otherwise, use an issue tracker that you are comfortable with and have access to.
  • Links to the device’s source repositories. All relevant source repositories (device, device_common, kernel, manifest) should be linked if possible. Or, even better, add links to all of the relevant repositories from the manifest or device repository and just link to that location. This is what was done for the Sony Xperia X, for example. See fredldotme/device-sony-suzu for an example of linking to all the relevant repositories.

Community help links help visitors to get help with using the device. The following link should be added to this section:

  • A place to discuss your device port. Usually this will be a category on the UBports Forum. If you would like a forum category for your device, make a post in the forum’s General section.

Doc links are links to UBports docs and blog posts that mention the device or might be useful to the user.

Releases file

You’ll need to add a release file to display a working release on the devices website. This file contains the feature matrix and information about the porting type.

Feature IDs

portStatus:
  - categoryName: "Sound"
    - id: "earphones"
      value: "-"
      bugTracker: "https://link to my bug report"

The portStatus matrix allows the site to display the hardware compatibility of your port. This helps users discover ports that meet their needs and sets expectations for people looking to buy a device for Ubuntu Touch.

If your device has hardware support for a given feature and it can be used under Ubuntu Touch, set the value: key to "+". This marks the feature as working.

If your device does not have hardware support for a given feature, set the value: key to "x". The site will ignore any missing features when calculating the progress value for your device.

If your device has hardware support for a feature but it does not work when running Ubuntu Touch, set the value: key to "-". This marks the feature as broken.

Mark a feature as partially working if your device has hardware support for the feature and it works most of the time when running Ubuntu Touch, but most users will encounter a critical issue with the feature within 1 week of booting the device. The value: key for partially working features is "+-"

If you haven’t tested a feature or you don’t know its state you can set the value: key to "?".

If possible, include a bug report link with the bugTracker key when marking a feature as broken or partially working.

Category Feature ID Feature name
Actors manualBrightness Manual brightness
notificationLed Notification LED
torchlight Torchlight
vibration Vibration
Camera flashlight Flashlight
photo Photo
video Video
switchCamera Switching between cameras
Cellular carrierInfo Carrier info, signal strength
dataConnection Data connection
dualSim Dual SIM functionality
calls Incoming, outgoing calls
mms MMS in, out
pinUnlock PIN unlock
sms SMS in, out
audioRoutings Change audio routings
voiceCall Voice in calls
volumeControl Volume control in calls
Endurance batteryLifetimeTest 24+ hours battery lifetime
noRebootTest 7+ days stability
GPU uiBoot Boot into UI
videoAcceleration Hardware video playback
Misc anboxPatches Anbox patches (deprecated)
waydroid Waydroid
apparmorPatches AppArmor patches
batteryPercentage Battery percentage
offlineCharging Offline charging
onlineCharging Online charging
recoveryImage Recovery image
factoryReset Reset to factory defaults
rtcTime RTC time
sdCard SD card detection and access
shutdown Shutdown / Reboot
wirelessCharging Wireless charging
wirelessExternalMonitor Wireless External monitor
Network bluetooth Bluetooth
flightMode Flight mode
fmRadio FM radio
hotspot Hotspot
nfc NFC
wifi WiFi
Sensors autoBrightness Automatic brightness
fingerprint Fingerprint reader
gps GPS
proximity Proximity
rotation Rotation
touchscreen Touchscreen
dt2w Double touch to wake
Sound earphones Earphones
loudspeaker Loudspeaker
microphone Microphone
volumeControl Volume control
USB mtp MTP access
adb ADB access
wiredExternalMonitor Wired External monitor

The markdown block

---

## This is the Markdown block

I can write Markdown content here. Have [a link](https://example.com)!

The markdown block of your file will be rendered as installation instructions on your device’s page. For example, if your device needs to have a certain version of Android installed prior to running the UBports Installer, those instructions should be written in Markdown after the metadata block.

Do not place a description or a marketing blurb in the markdown block. It will look out of place. Use the description key in the YAML metadata block instead.

YAML metadata block reference

The YAML metadata block for data.md should have the following format:

name: "<retail name of the device>"
description: "<marketing-style description that helps a user decide if this device is right for them>"
subforum: "<the subforum id on forums.ubports.com, should be added in the format number/my-device>"
deviceType: "<phone|tablet|tv|other>"
tag: "<promoted|unmaintained>"
buyLink: "<link to manufacturer's store, if it is available>"
disableBuyLink: "<true|false>"
image: "<link to a picture of the device (currently unused)>"
price:
  min: "<minimum estimated price>"
  max: "<maximum estimated price>"
  currency: "<currency in the ISO 4217 format USD|EUR>"
  currencySymbol: "<currency symbol $|€>"
variantOf: "<device codename to inherit config from>"
deviceInfo:
  - id: "<device specification ID, you can find the complete list above>"
    value: "<device technical specification, model...>"
contributors:
  - name: "<contributor name>"
    role: "<Phone maker|Maintainer|Developer|Tester|Contributor>"
    renewals:
      - "<date of maintainership renewal (add a new one every 6 months)>"
    expired: "<mark as true if maintainership ended before the 6 months of renewal>"
    forum: "<link to ubports forum profile>"
    photo: "<link to avatar picture>"
communityHelp:
  - name: "<link label>"
    link: "<URL for the user to get help during installation and usage>"
docLinks:
  - name: "<link label>"
    link: "<URL to UBports docs or blog posts>"
externalLinks:
  - name: "<link label>"
    link: "<URL for development resources>"
seo:
  description: "<Page description, used as content in <meta name='description' content=''>>"
  keywords: "<Comma-separated list of keywords, used as content in <meta name='keywords' content=''>>"

The YAML metadata block for release.md should have the following format:

portType: "<Legacy|Native|Halium 5.1|Halium 7.1|Halium 9.0|Halium 10.0|Halium 11.0|Halium 12.0>"
kernelVersion: "<version of the Linux kernel running in the format x.y.z>"
installLink: "<link to install instructions (repo), if installer isn't available>"
portStatus:
  - categoryName: "<name of the category of the features>"
    features:
      - id: "<feature ID, you can find the complete list above>"
        value: "< + | - | +- | x | ? >"
        bugTracker: "<link to the relevant issue report if this feature is not working>"
maturity: "<fallback value for progress calculation, MUST NOT be used>"