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,
We will then have a structure similar to the following:
suzu ├── data.md └── releases ├── focal.md └── xenial.md
You can add new devices by creating a Markdown file with a YAML metadata
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.
Your YAML metadata block will have four primary sections. For more information on filling these sections, see the YAML metadata block reference below.
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.
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”.
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.
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|
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
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:
Community help links help visitors to get help with using the device. The following link should be added to this section:
Doc links are links to UBports docs and blog posts that mention the device or might be useful to the user.
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.
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
value: key to
If possible, include a bug report link with the
when marking a feature as broken or partially working.
|Category||Feature ID||Feature name|
|switchCamera||Switching between cameras|
|Cellular||carrierInfo||Carrier info, signal strength|
|dualSim||Dual SIM functionality|
|calls||Incoming, outgoing calls|
|mms||MMS in, out|
|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)|
|factoryReset||Reset to factory defaults|
|sdCard||SD card detection and access|
|shutdown||Shutdown / Reboot|
|wirelessExternalMonitor||Wireless External monitor|
|dt2w||Double touch to wake|
|wiredExternalMonitor||Wired External monitor|
--- ## 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
The YAML metadata block for
data.md should have the following
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
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>"