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
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
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 is a category in the UBports forum to discuss your device port with users and developers. If you would like a forum category for your device, make a post in the forum’s General section.
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.
sources: portType: "community" portPath: "android9" deviceGroup: "volla-phone" deviceSource: "volla-yggdrasilx" kernelSource: "kernel-volla-mt6763" issuesLink: "https://github.com/HelloVolla/ubuntu-touch-beta-tests/issues"
In order to list your device on the website, you must publish the sources. Devices will be grouped into three categories based on where the sources are published:
When listing a reference device or a community device you will need to set the portPath to the device group starting from the reference or community ports group on Gitlab and the id of the group in the deviceGroup property. Then set the deviceSource and kernelSource links to the correct IDs of the repositories in the device group. The issuesLink is not required for reference and community ports, it is required only for external ports, it needs to be set to an URL where people can report problems they’re having with your port. On reference and community devices, the issuesLink is the issues URL of the device source repository, if it needs to be changed it can be overwritten with the issuesRepo or issuesLink property.
externalLinks: - name: "Issue tracker" link: "https://github.com/ubports/ubuntu-touch/issues/"
External links help visitors find more information about your device port. This section will be added automatically if the sources of your device are available in the community or reference port repositories. If your device is located in an external repository you will need to add manually the links to the sources in this section. Reference and community ports can also use this section to add more details and useful links that are not already listed in the sources section. The link for issue reports is automatically added for all the ports from the sources and it shouldn't be added to the links.
For ports with external sources 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.
communityHelp: - name: "Telegram - @utonvolla" link: "https://t.me/utonvolla"
Community help links help visitors to get help with using the device. This is the place to add device specific groups to help users and developers with installation and testing. DO NOT add the device subforum, the main UBports group or the WelcomePlus group, they will be added automatically.
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
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
key 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 storage|
|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 block instead.
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>" sources: portType: "<reference|community|external>" portPath: "<path to the device group or repository>" deviceGroup: "<device group name>" deviceSource: "<device source repository name>" kernelSource: "<kernel source repository name>" issuesRepo: "<repository for issues tracking when it isn't the device repository>" showDevicePipelines: "<add pipelines URL to device resources true|false>" issuesLink: "<link to open an issue (for external ports or when is not the device repository)>" externalLinks: - name: "<link label>" link: "<URL for development resources>" noActivityDetection: "<Disable activity checking, if it is a link to Github or Gitlab>" unimplementedFeatures: - name: "<Name of the feature not supported by the OS that the device has>" 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
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>"