PINE64 - User contributions [en]

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-15T17:33:18Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}
{{hint|'''For prospective editors:''' This guide was authored by [[User:CounterPillow]]. Please read the lengthy comment at the top of the article in the edit window before trying to contribute to it in any way.}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it. You require no preexisting Linux knowledge whatsoever.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

{{note|'''Note:''' If you see a heartbeat pattern but the board never gets a DHCP lease, please follow the steps in [[#Is My Ethernet Broken?]].}}

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

=== Permissions ===

On Unix-like systems like Linux, files and directories are owned by one user and one group. Additionally, there are read/write/execute permissions applying for each file or directory for either the user, the group or everyone else. A user may be part of multiple groups at the same time.

We can view these permissions with <code>ls -al</code> in the first column. You'll see something like:

-rwxrw-r--

This would indicate a file (<code>d</code> not being present as the first letter, instead being <code>-</code>) that is

* '''r'''eadable by the user that owns it, '''w'''ritable by the user that owns it, e'''x'''ecutable by the user that owns it
* readable by anyone in the group that owns it, writable by anyone in the group that owns it, '''not''' executable by anyone in the group that owns it (unless, in this case, that specific user owns it)
* readable by everyone else, but neither writable nor executable by them.

You can ignore the next column (the number) in the output. The two columns that come after that are the user and the group that own the file/directory respectively.

{{hint|'''Further Explanation:''' "Executable" on a directory doesn't quite do what one might think it does: it means one is able to <code>cd</code> into the directory and read what files/directories it contains.}}

We can change the owner of a file with the <code>chown</code> command:

sudo chown <var>newuser</var>:<var>newgroup</var> <var>foo</var>

This would change the user that owns <var>foo</var> to <var>newuser</var>, and the group that owns the <var>foo</var> to <var>newgroup</var>. By adding the <code>-R</code> argument, we can also make this operation apply recursively to every file and directory contained within a targeted directory.

Similarly, we can modify the permission flags for the '''u'''ser, '''g'''roup and '''o'''ther users with the <code>chmod</code> command. This is best illustrated with a few examples:

* <code>chmod o+w <var>foo</var></code>: give everybody write permissions to <var>foo</var>.
* <code>chmod g=rw <var>foo</var></code>: set group permissions to read and write <var>foo</var>, but remove the group execute flag if present.
* <code>chmod u-x <var>foo</var></code>: remove execute permissions for the user that owns <var>foo</var>, but leave read/write flags as-is.
* <code>chmod ug=rw <var>foo</var></code>: set user and group permissions for <var>foo</var> to read/write but not execute.

You can once again combine this with the <code>-R</code> argument to make the operation recursive.

{{hint|'''Hint:''' Only the superuser can change the permissions of files or directories not owned by them.}}
{{hint|'''Further Explanation:''' Consult <code>man chown</code> and <code>man chmod</code> for further details. You can close the manual reader by pressing '''q'''.}}

== Setting Up The Network ==

=== Configuring A Fixed LAN IP Address ===

By default, the Plebian images use NetworkManager to automatically configure the ethernet interface in such a way that it asks your router to assign it an IP address inside your local network with a protocol called DHCP. What happens is that the Quartz64 asks the router for an IP address, and the router hands it one from a pool of addresses for a limited span of time, a so-called "lease". Dynamically configuring the IP address like this is great for quickly getting started, especially when in combination with mDNS, as everything just works automatically out of the box.

However, a bit later on in this guide, we'll want the router to know exactly what IP address our Quartz64 Model B is going to respond to even across power cycles of either device. That's why at this point, we'll set it up to have a fixed local network address, with '''one''' of two methods.

==== Method A: Using Reserved DHCP Leases ====

With this method, we'll simply configure your router to always hand the same IP address out over DHCP for the hardware address (MAC) of your Quartz64 Model B.

Many routers will have a web interface through which you can configure them. To find your router's IP address, type <code>ip route</code> into your SSH session with the Quartz64 Model B and hit enter to run the command. It should output something like:

default via 192.168.0.1 dev end0 proto dhcp src 192.168.0.58 metric 100
192.168.0.0/24 dev end0 proto kernel scope link src 192.168.0.58 metric 100

In this case, we can see that our router is <code>192.168.0.1</code>, as the ''default via'' route goes through it. Yours may be different.

You can now type this router IP address into your web browser, and with any luck, you'll be greeted with a web login prompt. If you've never set a password on your router's management interface, check the bottom or sides of your device for a sticker that lists a default password.

The precise management interface differs from router to router, so this guide can't give precise instructions. However, once logged in, there is usually a section labelled "DHCP". In it, you may be able to configure reserved IP addresses for a specific MAC address. To find the MAC address of your Quartz64 Model B, run "ip link" on it, which will give you output like this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: end0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 76:36:c7:c4:57:e2 brd ff:ff:ff:ff:ff:ff

What we want here is the first colon separated address in the second link (end0), in this case <code>76:36:c7:c4:57:e2</code>. Your router should let you enter this MAC address somewhere to reserve a specific address from the DHCP pool for it.

==== Method B: Using A Fixed IP ====

If Method A isn't available to you, this method should always work.

Instead of using DHCP to request a lease for an IP address, our Quartz64 Model B can also simply assume it can communicate using a fixed IP address.

'''Important:''' Our fixed IP address should be ''outside'' the range of IP addresses our router hands out through DHCP, as otherwise collisions may occur! In the router web interface, look for a DHCP start address field and DHCP pool size field. An IP address either smaller than the start address (though above 0 and not colliding with the router's address) or larger than the start address plus the pool size (though below 255) will work; you may have to reduce the size of the DHCP pool if it's all maxed out though.

For example, with a DHCP pool that starts at 192.168.0.40 and has a size of 215, we could use a fixed IP address like 192.168.0.10 without accidentally colliding with one the router hands out.

Run the command

sudo nmtui

which should open up an interactive connection editor. Use your cursor keys to highlight the entry "Wired connection 1", and hit the right arrow key to navigate towards the "Edit" option, and hit enter.

Navigate to "IPv4 CONFIGURATION" and hit enter on "<Automatic>", then select "<Manual>". Navigate to the right over the "<Show>", and hit enter again. You should now be greeted by a whole host of options:

# In "Addresses:", hit "<Add...>" and enter your chosen fixed IPv4 address followed by <code>/32</code>, for example <code>192.168.0.21/32</code>.
# In "Gateway", enter your router's IPv4 address.
# In DNS Servers, enter on "<Add...>" and add <code>1.1.1.1</code>. Repeat the same process, but with <code>1.0.0.1</code>. This will add Cloudflare's DNS servers, as we'll no longer be receiving the router's DNS servers with manual configuration.
# Check the box next to "Ignore automatically obtained DNS parameters" by navigating over it and hitting the space bar. This makes sure that if our router tries to give us some DNS servers anyway, we don't use them.
# Check "Require IPv4 addressing for this connection" in the same way.
# Just to be consistent, go to "IPv6 CONFIGURATION", but this time leave it on Automatic. Hit "<Show...>" to expand it.
# Add the following two Cloudflare DNS servers: <code>2606:4700:4700::1111</code> and <code>2606:4700:4700::1001</code>.
# Check "Ignore automatically obtained DNS parameters".
# Navigate down to "<OK>" and hit enter
# Hit escape twice to quit nmtui

The easiest way to make sure your new network connection settings are used is to reboot your board with

sudo reboot

After logging back in, the command

ip addr

should show your chosen IP under end0 after "inet".

=== Configuring A Firewall ===

Even in a home network that is behind a router's NAT (more on that later), it's good practice to have your individual devices protected by firewalls as well. A firewall can work in many ways, but the simplest and most common method of operation is that it drops all incoming connection attempts originating from globally routed IPs and only allows those on network ports the administrator has explicitly allowed. This prevents locally running services that accidentally listen to incoming connections from all IPs from being accessible to any surprise guests.

While the Linux kernel includes all the logic to filter network packets, we still need an application to set up and manage these filter rules persistently. There are a multitude of such applications that can do this by building their own concept on top of Linux's packet filtering infrastructure, but the one we will be using in this guide is firewalld. firewalld is the default service for managing firewall rules in RedHat Enterprise Linux, Fedora and openSUSE, and is also available to be used on many other Linux distributions, such as Debian (the one we're using).

firewalld has a concept of "zones", which are logical constructs that either allow certain services through or not, can either be applied to specific interfaces or source IPs, and can pass network traffic between each other with policies. In our case, NetworkManager has assigned the ''end0'' interface the pre-defined ''public'' zone already. Our plan here is to use the pre-defined ''home'' zone for any traffic originating from Local Area Network IP addresses, and let ''public'' handle all the rest.

We first need to install firewalld through Debian's package manager, apt. The first command refreshes our index of packages, the second installs firewalld:

sudo apt update
sudo apt install firewalld

{{note|'''Warning:''' Debian automatically starts firewalld and configures it to auto-start on boot. It happens to be configured in a way that breaks our mDNS (.local domain) resolution. After installing firewalld, immediately work through the next few steps without closing your SSH session as you'll otherwise have to type the board's IP address manually to get back in.}}

We should now tell firewalld about what IP prefixes we consider to be our local network:

sudo firewall-cmd --permanent --new-ipset=lanv4 --type=hash:net
sudo firewall-cmd --permanent --ipset=lanv4 --add-entry=10.0.0.0/8
sudo firewall-cmd --permanent --ipset=lanv4 --add-entry=172.16.0.0/12
sudo firewall-cmd --permanent --ipset=lanv4 --add-entry=192.168.0.0/16
sudo firewall-cmd --permanent --new-ipset=lanv6 --option=family=inet6 --type=hash:net
sudo firewall-cmd --permanent --ipset=lanv6 --add-entry=fe80::/64

{{hint|'''Further Explanation:''' We've used [https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation CIDR notation] here to denote entire ranges of IP addresses. These specific ranges are specified by the IETF and IANA to be used for private networks, such as our local area network (LAN).}}

Now that we have a ''lanv4'' and ''lanv6'' ipset, we can tell firewalld that any traffic originating from these IPs should be considered part of our ''home'' zone:

sudo firewall-cmd --permanent --zone=home --add-source=ipset:lanv4
sudo firewall-cmd --permanent --zone=home --add-source=ipset:lanv6

We should now reload those new permanent settings, so that our mDNS announcements work again:

sudo firewall-cmd --reload

Next, we'll want to remove the ''ssh'' service from the ''public'' zone, as Debian added it there by default:

sudo firewall-cmd --permanent --zone=public --remove-service=ssh
sudo firewall-cmd --reload

Finally, we want to add a service definition for Minecraft, which uses port 25565 with the TCP protocol, and allow it for our ''home'' and ''public'' zone:

sudo firewall-cmd --permanent --new-service=minecraft
sudo firewall-cmd --permanent --service=minecraft --add-port=25565/tcp
sudo firewall-cmd --permanent --zone=home --add-service=minecraft
sudo firewall-cmd --permanent --zone=public --add-service=minecraft
sudo firewall-cmd --reload

{{hint|'''Further Explanation:''' You can find a (somewhat lacking) documentation for firewalld on [https://firewalld.org/documentation/ the official firewalld website]. A better resource is, as always, <code>man firewall-cmd</code>.}}

{{hint|'''For Expert Users:''' Experienced users might at this point run <code>sudo iptables -L</code> to look at the actual filtering rules that firewalld has added, and they would be shocked to see some completely empty chains with an ACCEPT policy. Fear not, the firewall is working, but the iptables utility isn't. Modern kernels all use nftables, which confuses the legacy iptables specific tools when something like firewalld makes full use of nftables. Use <code>sudo nft list table inet firewalld</code> to get a listing of the filtering rules.}}

== Formatting The NVMe Drive ==

{{note|'''TODO:''' Explain how to wipefs + fdisk + format the NVMe drive, make a mount point and put it in fstab.}}

== Setting Up The Minecraft Java Edition Server ==

{{note|'''TODO:'''
# Add a minecraft system user with a minecraft group that has write permissions to the minecraft directory on NVMe, add minecraft to supplemental groups for user.
# Install Java, download PaperMC to the Minecraft directory, symlink it to paper.jar, run it once, accept the EULA.
# Edit server.properties, enable rcon with a password, enable whitelist, edit motd and set difficulty.
# Add the systemd unit to /etc/systemd/system/, set it to auto-start, then start it.
# Add player to whitelist and ops through rcon.
# Connect to the server for the first time!}}

=== Getting An RCon Client ===

Minecraft's server has a control protocol called "rcon". We'll need this protocol to gracefully shut down the Minecraft server, and add ourselves to ops later on. For this, we'll need a Minecraft RCon client. [https://github.com/Tiiffi/mcrcon Tiiffi/mcrcon] is a good one, but we need to compile and install it first.

To start off, let's install some required tools to compile it. In your Quartz64 Model B's SSH session, type:

sudo apt update
sudo apt install build-essential

Next we'll download the source code for mcrcon:

wget --content-disposition https://github.com/Tiiffi/mcrcon/archive/refs/tags/v0.7.2.tar.gz

This should have downloaded us an ''mcrcon-0.7.2.tar.gz'' archive file. Let's verify that what we've downloaded matches what this guide expects:

sha256sum mcrcon-0.7.2.tar.gz

This should output the following; compare the first string of letter and numbers to yours, they must match:

1743b25a2d031b774e805f4011cb7d92010cb866e3b892f5dfc5b42080973270 mcrcon-0.7.2.tar.gz

Now let's unpack the ''.tar.gz'' archive and change into the directory it contains:

tar -xf mcrcon-0.7.2.tar.gz
cd mcrcon-0.7.2/

{{hint|'''Explanation:''' <code>tar</code> is the standard utility for creating, modifying, inspecting and unpacking tar archives, commonly referred to as "tarballs". The <code>-x</code> argument states that we want to e'''x'''tract, and the <code>-f</code> argument specifies that the next argument is the filename of the tarball we wish to operate on. <code>tar</code> will automatically infer the compression of the tarball, in this case gzip, and decompress it as it is unpacking.}}

In this directory (check with <code>ls -l</code>!) there should be some files, including a ''Makefile''. This allows us to now compile the source code and install the resulting binary:

make
sudo make install

{{hint|'''Explanation:''' A Makefile instructs the <code>make</code> command on how to build a project that uses it. In this case, it also contains a ''install'' target, which copies the resulting binary into ''/usr/local/bin'' and its manual page into the local prefix for manual pages. Since only the superuser can write to these directories, we need to run the install target with <code>sudo</code>.}}

If everything went well, we should now have the <code>mcrcon</code> command available, as well as its manual page with <code>man mcrcon</code>.

{{hint|'''For The Future:''' If you ever need to recompile <code>mcrcon</code>, for example, after a major version distribution upgrade years down the line that gets rid of ''libc.so.6'', you can run:

sudo make uninstall
make clean
make
sudo make install

}}

== Making The Server Accessible From Outside Your Home Network ==

{{note|'''TODO:'''
# Explain what a dynamic IP is, set up ddclient with DuckDNS, have a systemd timer for that.
# Explain what port forwarding is, why it's needed, and why this depends on your router. Warn not to forward port 22/tcp, only port 25565/tcp.}}

== Maintaining Your Server ==

{{note|'''TODO:'''
# Explain how to start, stop, restart the Minecraft server with systemctl.
# Explain how to access server logs with journalctl.
# Explain how to keep PaperMC updated (including changing the symlink).
# Explain apt update and apt upgrade. Recommend unattended-upgrades.
# Explain Debian major releases and to keep an eye out for them.
# Recommend htop to see how CPU and RAM usage is looking.
# Recommend some backup solutions; rsync to flash drive, short mention of borg/borgmatic over the network.
# Explain how to transfer files to/from server: sftp, rsync, winscp, etc.}}

== Security Advice ==

This section will give some general security advice on running your own server, and elaborates on some decisions this guide makes.

=== SSH Public Key Authentication ===

If you absolutely insist on opening up the SSH port to the public internet, you should use public key authentication and disable password authentication for SSH altogether.

This way, public key cryptography is used to authenticate, which is computationally extremely hard to break in this case. The password you encrypt your private key with never travels over the network.

To generate an SSH public/private key pair, run

ssh-keygen

on '''your client machine''', i.e. not the Quartz64 Model B.

Then copy the newly generated SSH public key over to the Quartz64 Model B with

ssh-copy-id <var>youruser</var>@<var>yourhost</var>.local

Try logging in with ssh now. It should prompt you for your key's password, rather than the user account's password.

If it works, you should then finally disable password authentication by editing ''/etc/ssh/sshd_config'' as the superuser and setting:

PasswordAuthentication no

Then, restart the ''sshd.service'' with <code>sudo systemctl restart sshd.service</code>.

Note that from this point on, if you want to log in from a different machine, you'll need to either copy your public/private keypair over or generate a new one there and edit ''~/.ssh/authorized_keys'' manually, or run <code>ssh-copy-id</code> with the <code>-i</code> argument pointing to that public key.

=== On Minecraft Server Modifications And Plugins ===

Please note that Minecraft server modifications or plugins run with the same access as your Minecraft server. While we tried our best in this guide to restrict the Minecraft server's access to the rest of the system, it can obviously still do bad things to our Minecraft world, our computational resources and our network. That's why, whenever you install a server-side modification or plugin, you should ask yourself these questions:

# Do you trust the website/service you are downloading the mod/plugin from to not be malicious?
# Do you trust the website/service you are downloading the mod/plugin from to have the latest version uploaded by the mod/plugin's author rather than an untrustworthy third party?
# Do you trust the mod/plugin author to not be malicious?
# Do you trust the mod/plugin author to have good security practices, as to not get their account compromised or development computer infected with malware?
# Do you trust the mod/plugin to not open up security vulnerabilities in your server?

Chances are the answers to some of these questions will be "no". In that case you have some leg work to do: research the site and users, double-check you're on the right domain, read the code for anything fishy, and if you're ever unsure, ask for a second opinion from somebody knowledgeable on the topics.

This is not unwarranted paranoia: Minecraft server modifications [https://github.com/dogboy21/serializationisbad have introduced security vulnerabilities before]. Well trusted people's accounts [https://github.com/fractureiser-investigation/fractureiser have been hijacked before, or their uploads unknowingly infected with malware]. And the way this happened? They themselves were downloading modifications from malicious users.

Please do note that all these issues generally do not apply to Minecraft Data Packs. While they are more limited than modifications or plugins that hook into the actual code, these limitations are good in the context of security.

=== Do Not Engage In Security By Obscurity ===

You may be tempted to not enable a whitelist because you think nobody is going to find your Minecraft server anyway. This is false. People and bots are constantly scanning the entire internet for open services. This includes Minecraft servers. If you do not have a whitelist, you will sooner or later get uninvited visitors.

Similarly, if you expose any service other than the Minecraft server to the internet through your router, expect that to be instantly discovered as well. Automated exploit scanners will then likely be hitting it regularly.

This sounds scary, but it's really not: if your system is up-to-date and follows best security practices, you generally won't have much to fear. It just means that you can't expose any insecurely configured service to the internet and expect nobody to find it.

=== Can't Be Bothered To Maintain It? Turn It Off ===

One of the biggest possible dangers to your home network's security is unwillingness to take responsibility. If you no longer want to maintain the server, turn the board off, unplug it, and delete the port forwarding rule in your router's web interface.

The majority of security breaches don't happen because somebody tries very hard to breach one target, but because a lot of people try very little to breach many targets. Chances are they will find a system somewhere that nobody feels responsible for anymore, and which hasn't been updated in 5 years, and runs a service of a version with a known vulnerability. Avoid being that system: if your Quartz64 Model B begins operating as part of a botnet due to your indifference, the rest of the internet will suffer.

=== Why Reboots Are Sometimes Recommended ===

Occasionally, your Linux kernel package (''linux-image-arm64'') will update. This is great! The kernel is the most basic part of the operating system, and responsible for enforcing fundamental privilege separation. Unfortunately, live-patching the running kernel (i.e. updating it in memory without requiring a reboot) is something that only enterprise-grade commercial Linux distributions like RedHat Enterprise Linux or SUSE Linux do. Since we're running Debian here and Debian doesn't have this feature, the only way to run the newly updated kernel is to reboot the system.

You can run <code>cat /var/run/reboot-required</code> to see if your Quartz64 Model B requires a reboot. It's worth noting that the Linux kernel development community does not distinguish regular bugs from security bugs, as many a "regular" bug could be a security bug in the right circumstances. However, Debian itself [https://www.debian.org/security/#DSAS publishes security advisories] when a Linux kernel update they ship fixes known potential security issues.

Whether or not you want to reboot for a specific kernel update is up to you. People run servers with hundreds of days of uptime (check with the command <code>uptime</code>) just fine; just because a potential security issue was fixed in the Linux kernel doesn't mean it'd be part of a realistic attack scenario on a specific system. In our case, the attack scenario we're most worried about is that somebody manages to breach the PaperMC Minecraft server, and then gains arbitrary code execution in its context, from which they will then likely attempt to attack the kernel to gain additional privileges. A second, much less likely attack scenario is that the Linux kernel would have a vulnerability in its network stack that would allow an attacker to remotely exploit it. Such vulnerabilities are exceedingly rare in Linux.

=== Why Not Docker: On Software Supply Chains And Understanding Your Stack ===

For the majority of this guide, self-declared DevOps EpicPoggers Awesomeninjas have probably been foaming at their mouth jumping at the opportunity to exclaim that one should just use Docker. This section serves as a soapbox to talk about the problems with that suggestion.

While a Docker container may be, well, contained, it pulls in an entire stacking doll of other images it is built upon. This means an entire operating system to support the application being run, minus a kernel.

This is great if you are the person writing the image manifests, know what your dependency requirements are, and track the entire software supply chain to ensure you always get the right versions for your stack, with all the latest vulnerabilities patched.

However, this is not how the vast majority of people use Docker. The overwhelming majority of Docker users simply pull some random person's image, run it, and thus make these assumptions:

# That the author of the image is not malicious. Malicious images [https://sysdig.com/blog/analysis-of-supply-chain-attacks-through-public-docker-images/ are widespread on Docker Hub].
# That the author of the image has good security practices in order to avoid publishing malicious images. We know account compromises will happen as Docker Hub seemingly does not require Two-Factor Authentication.
# That the author will update the images when critical security fixes in any of the things they depend on are fixed. A [https://dl.acm.org/doi/10.1145/3029806.3029832 2017 research paper] found that many images are hundreds of days old.
# That any of the things that image depends on, recursively, will also meet these three points.

For a single service/single node scenario, Docker complicates the software supply chain massively. Instead of getting most of our system from a source we already trust (Debian), we're now getting a whole second system from a myriad of sources opaquely compiled into one image.

Additionally, Docker complicates the following things:

* Knowing what version a specific runtime dependency is, and that all copies of this dependency on the entire system are patched against the latest vulnerability.
* Updating the container image and spinning up a new container based on it; this is not handled through your system's package manager.
* Persistent data; it's stored in Docker volumes, which may or may not be attached to containers, and you need to actively try to have them stored somewhere other than the default location.
* Service management; Docker reinvents service management in its own, arguably worse way.
* Networking; things are on a virtual network with Docker, which complicates firewall rules and other network configurations.
* Logging; Docker reinvents this too.

By not using a Docker container, but rather a locked down systemd service, we get the following benefits:

* All system software updates, including the Java Runtime, are handled by Debian, irrespective of the version of the Minecraft server we run.
* All of our services use the same system dependencies, and we can answer the question of "has <var>xyz</var> been patched?" by just looking at <code>apt</code>.
* We still get reasonably strong process isolation thanks to the various security sandboxing options our systemd service uses, despite not using Linux namespaces (containers).
* Our persistent data is where we expect it to be, owned by the user and group we expect it to be owned by.
* Our network is not burdened with virtual interfaces and forwarding rules.
* Our Minecraft server is tracked and dependency ordered by systemd's service management. It's automatically started on boot, and gracefully stopped on shutdown.
* Our Minecraft server's logs will show up in the system journal, and we can filter through them or correlate them with other sources just as with any other service reporting to the journal.

Container images built from manifests start to make sense when you are running complex sets of services scaled horizontally across a massive homogeneous cluster, where you want to rescale as needed and deploy new versions of your entire stack as immutable images that you can roll back easily. They also make some amount of sense in a case where you only have access to a very old userland (e.g. a stable enterprise Linux release) but need to run software requiring a myriad of dependencies that are either not packaged or not of a recent enough version in your distribution.

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

To hook up UART serial debug, connect your Woodpecker, ideally with a decent USB extension cord, to your computer's USB port. Make sure the yellow jumper is set to 3.3V.

Connect the GND pin of the Woodpecker to a GND pin of your Quartz64 Model B, which are coloured as black pins. A good one to use is pin number 6 (the one after the red pin 2 and pin 4), as it's right next to the other UART pins we'll need.

Next, hook up the Woodpecker's RXD pin to the Quartz64 Model B's pin number 8, which is next to (lengthwise down the row of pins) the aforementioned pin number 6, coloured in green.

Finally, hook up the Woodpecker's TXD pin to the QUartz64 Model B's pin number 10, which is down yet another pin in the same direction, also coloured in green.

{{note|'''TODO:''' Add a diagram showing the connections here.}}

==== Accessing The Serial Console On Windows ====

{{note|'''TODO:''' Add a guide on how to install, configure and use PuTTY}}

==== Accessing The Serial Console On Linux ====

{{note|'''TODO:''' Validate the serial settings here.}}
{{note|'''Warning:''' Some poorly written software, like <code>gpsd</code> or <code>brltty</code>, will randomly and happily claim and mess with any USB-to-serial adapters on the system, especially when you least want them to. Use <code>sudo lsof /dev/ttyUSB<var>n</var></code> to determine whether this is the case for you if you run into any trouble with the following steps.}}

First, list all the available USB-to-Serial adapters on your system:

ls /dev/ttyUSB*

If you only have one plugged in, this should probably only return <code>/dev/ttyUSB0</code>.

Next, you have some choice of serial terminal to use: <code>screen</code> (likely already installed), <code>minicom</code> and <code>picocom</code>.

For screen, (replacing <var>n</var> with the number of your serial adapter) use:

screen /dev/ttyUSB<var>n</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

For minicom, (replacing <var>n</var> with the number of your serial adapter) use:

minicom -D /dev/ttyUSB<var>n</var> -b 1500000 -8

You can quit minicom by hitting Ctrl+a, then hit q.

For picocom, (replacing <var>n</var> with the number of your serial adapter) use:

picocom /dev/ttyUSB<var>n</var> -b 1500000

You can quit picocom by hitting Ctrl+a, then hit Ctrl+q.

==== Accessing The Serial Console On macOS ====

{{note|'''TODO:''' Validate the serial settings here, and validate the device name.}}

Open up a terminal, then list all the available serial devices on your system:

ls /dev/tty.*

This will likely return something starting with <code>/dev/tty.usbserial-</code>.

Now we can open this serial port with <code>screen</code> as follows, replacing <var>foo</var> with the adapter name from the previous step:

screen /dev/tty.usbserial-<var>foo</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

==== Using The Serial Console ====

If you just hooked it up to a running system, you're unlikely to see any output. You will only be able to see messages from the point on when you've opened up your serial communication program.

If your board is doing the heartbeat pattern (i.e., it booted, but you're unable to log in over the network) you can hit Enter to (hopefully) make it show you a login prompt. If the login prompt is your first time communicating with the board, use username ''pleb'' and password ''pleb''. From then on, the serial terminal should work like any normal shell you'd have on the system, modulo some possible weirdness with special escape sequences making things a little more prone to drawing in broken ways.

If your board is not doing the heartbeat pattern, hit the reset button (small white button on side of board, the one closer towards the antenna mount) and you should be getting serial output from a fresh boot.

If you still don't get any output, make sure that you flashed the microSD card correctly, and make sure the TXD and RXD lines aren't the wrong way around. If you still don't get any output after that, your Quartz64 Model B may have defective level shifting transistors on the serial lines, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

=== Is My Ethernet Broken? ===

Pine Store has sold a number of boards where the ethernet PHY chip was seemingly broken. If your board exhibits the heartbeat LED pattern but never shows up on the network, either hook up a monitor and a keyboard or use your Woodpecker to hook up to serial (see [[#Connecting UART]]) and try to log in.

After logging in, type:

sudo dmesg | grep rk_gmac-dwmac

If the output contains any lines like

rk_gmac-dwmac fe010000.ethernet end0: __stmmac_open: Cannot attach to PHY (error: -22)

then your hardware is defective, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-15T15:50:30Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}
{{hint|'''For prospective editors:''' This guide was authored by [[User:CounterPillow]]. Please read the lengthy comment at the top of the article in the edit window before trying to contribute to it in any way.}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

{{note|'''Note:''' If you see a heartbeat pattern but the board never gets a DHCP lease, please follow the steps in [[#Is My Ethernet Broken?]].}}

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

=== Permissions ===

On Unix-like systems like Linux, files and directories are owned by one user and one group. Additionally, there are read/write/execute permissions applying for each file or directory for either the user, the group or everyone else.

We can view these permissions with <code>ls -al</code> in the first column. You'll see something like:

-rwxrw-r--

This would indicate a file (<code>d</code> not being present as the first letter, instead being <code>-</code>) that is

* '''r'''eadable by the user that owns it, '''w'''ritable by the user that owns it, e'''x'''ecutable by the user that owns it
* readable by anyone in the group that owns it, writable by anyone in the group that owns it, '''not''' executable by anyone in the group that owns it (unless, in this case, that specific user owns it)
* readable by everyone else, but neither writable nor executable by them.

You can ignore the next column (the number) in the output. The two columns that come after that are the user and the group that own the file/directory respectively.

{{hint|'''Further Explanation:''' "Executable" on a directory doesn't quite do what one might think it does: it means one is able to <code>cd</code> into the directory and read what files/directories it contains.}}

We can change the owner of a file with the <code>chown</code> command:

sudo chown <var>newuser</var>:<var>newgroup</var> <var>foo</var>

This would change the user that owns <var>foo</var> to <var>newuser</var>, and the group that owns the <var>foo</var> to <var>newgroup</var>. By adding the <code>-R</code> argument, we can also make this operation apply recursively to every file and directory contained within a targeted directory.

Similarly, we can modify the permission flags for the '''u'''ser, '''g'''roup and '''o'''ther users with the <code>chmod</code> command. This is best illustrated with a few examples:

* <code>chmod o+w <var>foo</var></code>: give everybody write permissions to <var>foo</var>.
* <code>chmod g=rw <var>foo</var></code>: set group permissions to read and write <var>foo</var>, but remove the group execute flag if present.
* <code>chmod u-x <var>foo</var></code>: remove execute permissions for the user that owns <var>foo</var>, but leave read/write flags as-is.
* <code>chmod ug=rw <var>foo</var></code>: set user and group permissions for <var>foo</var> to read/write but not execute.

You can once again combine this with the <code>-R</code> argument to make the operation recursive.

{{hint|'''Hint:''' Only the superuser can change the permissions of files or directories not owned by them.}}
{{hint|'''Further Explanation:''' Consult <code>man chown</code> and <code>man chmod</code> for further details. You can close the manual reader by pressing '''q'''.}}

== Setting Up The Network ==

=== Configuring A Fixed LAN IP Address ===

By default, the Plebian images use NetworkManager to automatically configure the ethernet interface in such a way that it asks your router to assign it an IP address inside your local network with a protocol called DHCP. What happens is that the Quartz64 asks the router for an IP address, and the router hands it one from a pool of addresses for a limited span of time, a so-called "lease". Dynamically configuring the IP address like this is great for quickly getting started, especially when in combination with mDNS, as everything just works automatically out of the box.

However, a bit later on in this guide, we'll want the router to know exactly what IP address our Quartz64 Model B is going to respond to even across power cycles of either device. That's why at this point, we'll set it up to have a fixed local network address, with '''one''' of two methods.

==== Method A: Using Reserved DHCP Leases ====

With this method, we'll simply configure your router to always hand the same IP address out over DHCP for the hardware address (MAC) of your Quartz64 Model B.

Many routers will have a web interface through which you can configure them. To find your router's IP address, type <code>ip route</code> into your SSH session with the Quartz64 Model B and hit enter to run the command. It should output something like:

default via 192.168.0.1 dev end0 proto dhcp src 192.168.0.58 metric 100
192.168.0.0/24 dev end0 proto kernel scope link src 192.168.0.58 metric 100

In this case, we can see that our router is <code>192.168.0.1</code>, as the ''default via'' route goes through it. Yours may be different.

You can now type this router IP address into your web browser, and with any luck, you'll be greeted with a web login prompt. If you've never set a password on your router's management interface, check the bottom or sides of your device for a sticker that lists a default password.

The precise management interface differs from router to router, so this guide can't give precise instructions. However, once logged in, there is usually a section labelled "DHCP". In it, you may be able to configure reserved IP addresses for a specific MAC address. To find the MAC address of your Quartz64 Model B, run "ip link" on it, which will give you output like this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: end0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 76:36:c7:c4:57:e2 brd ff:ff:ff:ff:ff:ff

What we want here is the first colon separated address in the second link (end0), in this case <code>76:36:c7:c4:57:e2</code>. Your router should let you enter this MAC address somewhere to reserve a specific address from the DHCP pool for it.

==== Method B: Using A Fixed IP ====

If Method A isn't available to you, this method should always work.

Instead of using DHCP to request a lease for an IP address, our Quartz64 Model B can also simply assume it can communicate using a fixed IP address.

'''Important:''' Our fixed IP address should be ''outside'' the range of IP addresses our router hands out through DHCP, as otherwise collisions may occur! In the router web interface, look for a DHCP start address field and DHCP pool size field. An IP address either smaller than the start address (though above 0 and not colliding with the router's address) or larger than the start address plus the pool size (though below 255) will work; you may have to reduce the size of the DHCP pool if it's all maxed out though.

For example, with a DHCP pool that starts at 192.168.0.40 and has a size of 215, we could use a fixed IP address like 192.168.0.10 without accidentally colliding with one the router hands out.

Run the command

sudo nmtui

which should open up an interactive connection editor. Use your cursor keys to highlight the entry "Wired connection 1", and hit the right arrow key to navigate towards the "Edit" option, and hit enter.

Navigate to "IPv4 CONFIGURATION" and hit enter on "<Automatic>", then select "<Manual>". Navigate to the right over the "<Show>", and hit enter again. You should now be greeted by a whole host of options:

# In "Addresses:", hit "<Add...>" and enter your chosen fixed IPv4 address followed by <code>/32</code>, for example <code>192.168.0.21/32</code>.
# In "Gateway", enter your router's IPv4 address.
# In DNS Servers, enter on "<Add...>" and add <code>1.1.1.1</code>. Repeat the same process, but with <code>1.0.0.1</code>. This will add Cloudflare's DNS servers, as we'll no longer be receiving the router's DNS servers with manual configuration.
# Check the box next to "Ignore automatically obtained DNS parameters" by navigating over it and hitting the space bar. This makes sure that if our router tries to give us some DNS servers anyway, we don't use them.
# Check "Require IPv4 addressing for this connection" in the same way.
# Just to be consistent, go to "IPv6 CONFIGURATION", but this time leave it on Automatic. Hit "<Show...>" to expand it.
# Add the following two Cloudflare DNS servers: <code>2606:4700:4700::1111</code> and <code>2606:4700:4700::1001</code>.
# Check "Ignore automatically obtained DNS parameters".
# Navigate down to "<OK>" and hit enter
# Hit escape twice to quit nmtui

The easiest way to make sure your new network connection settings are used is to reboot your board with

sudo reboot

After logging back in, the command

ip addr

should show your chosen IP under end0 after "inet".

=== Configuring A Firewall ===

Even in a home network that is behind a router's NAT (more on that later), it's good practice to have your individual devices protected by firewalls as well. A firewall can work in many ways, but the simplest and most common method of operation is that it drops all incoming connection attempts originating from globally routed IPs and only allows those on network ports the administrator has explicitly allowed. This prevents locally running services that accidentally listen to incoming connections from all IPs from being accessible to any surprise guests.

While the Linux kernel includes all the logic to filter network packets, we still need an application to set up and manage these filter rules persistently. There are a multitude of such applications that can do this by building their own concept on top of Linux's packet filtering infrastructure, but the one we will be using in this guide is firewalld. firewalld is the default service for managing firewall rules in RedHat Enterprise Linux, Fedora and openSUSE, and is also available to be used on many other Linux distributions, such as Debian (the one we're using).

firewalld has a concept of "zones", which are logical constructs that either allow certain services through or not, can either be applied to specific interfaces or source IPs, and can pass network traffic between each other with policies. In our case, NetworkManager has assigned the ''end0'' interface the pre-defined ''public'' zone already. Our plan here is to use the pre-defined ''home'' zone for any traffic originating from Local Area Network IP addresses, and let ''public'' handle all the rest.

We first need to install firewalld through Debian's package manager, apt. The first command refreshes our index of packages, the second installs firewalld:

sudo apt update
sudo apt install firewalld

{{note|'''Warning:''' Debian automatically starts firewalld and configures it to auto-start on boot. It happens to be configured in a way that breaks our mDNS (.local domain) resolution. After installing firewalld, immediately work through the next few steps without closing your SSH session as you'll otherwise have to type the board's IP address manually to get back in.}}

We should now tell firewalld about what IP prefixes we consider to be our local network:

sudo firewall-cmd --permanent --new-ipset=lanv4 --type=hash:net
sudo firewall-cmd --permanent --ipset=lanv4 --add-entry=10.0.0.0/8
sudo firewall-cmd --permanent --ipset=lanv4 --add-entry=172.16.0.0/12
sudo firewall-cmd --permanent --ipset=lanv4 --add-entry=192.168.0.0/16
sudo firewall-cmd --permanent --new-ipset=lanv6 --option=family=inet6 --type=hash:net
sudo firewall-cmd --permanent --ipset=lanv6 --add-entry=fe80::/64

{{hint|'''Further Explanation:''' We've used [https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation CIDR notation] here to denote entire ranges of IP addresses. These specific ranges are specified by the IETF and IANA to be used for private networks, such as our local area network (LAN).}}

Now that we have a ''lanv4'' and ''lanv6'' ipset, we can tell firewalld that any traffic originating from these IPs should be considered part of our ''home'' zone:

sudo firewall-cmd --permanent --zone=home --add-source=ipset:lanv4
sudo firewall-cmd --permanent --zone=home --add-source=ipset:lanv6

We should now reload those new permanent settings, so that our mDNS announcements work again:

sudo firewall-cmd --reload

Next, we'll want to remove the ''ssh'' service from the ''public'' zone, as Debian added it there by default:

sudo firewall-cmd --permanent --zone=public --remove-service=ssh
sudo firewall-cmd --reload

Finally, we want to add a service definition for Minecraft, which uses port 25565 with the TCP protocol, and allow it for our ''home'' and ''public'' zone:

sudo firewall-cmd --permanent --new-service=minecraft
sudo firewall-cmd --permanent --service=minecraft --add-port=25565/tcp
sudo firewall-cmd --permanent --zone=home --add-service=minecraft
sudo firewall-cmd --permanent --zone=public --add-service=minecraft
sudo firewall-cmd --reload

{{hint|'''Further Explanation:''' You can find a (somewhat lacking) documentation for firewalld on [https://firewalld.org/documentation/ the official firewalld website]. A better resource is, as always, <code>man firewall-cmd</code>.}}

== Formatting The NVMe Drive ==

{{note|'''TODO:''' Explain how to wipefs + fdisk + format the NVMe drive, make a mount point and put it in fstab.}}

== Setting Up The Minecraft Java Edition Server ==

{{note|'''TODO:'''
# Add a minecraft system user with a minecraft group that has write permissions to the minecraft directory on NVMe, add minecraft to supplemental groups for user.
# Install Java, download PaperMC to the Minecraft directory, symlink it to paper.jar, run it once, accept the EULA.
# Edit server.properties, enable rcon with a password, enable whitelist, edit motd and set difficulty.
# Add the systemd unit to /etc/systemd/system/, set it to auto-start, then start it.
# Add player to whitelist and ops through rcon.
# Connect to the server for the first time!}}

=== Getting An RCon Client ===

Minecraft's server has a control protocol called "rcon". We'll need this protocol to gracefully shut down the Minecraft server, and add ourselves to ops later on. For this, we'll need a Minecraft RCon client. [https://github.com/Tiiffi/mcrcon Tiiffi/mcrcon] is a good one, but we need to compile and install it first.

To start off, let's install some required tools to compile it. In your Quartz64 Model B's SSH session, type:

sudo apt update
sudo apt install build-essential

Next we'll download the source code for mcrcon:

wget --content-disposition https://github.com/Tiiffi/mcrcon/archive/refs/tags/v0.7.2.tar.gz

This should have downloaded us an ''mcrcon-0.7.2.tar.gz'' archive file. Let's verify that what we've downloaded matches what this guide expects:

sha256sum mcrcon-0.7.2.tar.gz

This should output the following; compare the first string of letter and numbers to yours, they must match:

1743b25a2d031b774e805f4011cb7d92010cb866e3b892f5dfc5b42080973270 mcrcon-0.7.2.tar.gz

Now let's unpack the ''.tar.gz'' archive and change into the directory it contains:

tar -xf mcrcon-0.7.2.tar.gz
cd mcrcon-0.7.2/

{{hint|'''Explanation:''' <code>tar</code> is the standard utility for creating, modifying, inspecting and unpacking tar archives, commonly referred to as "tarballs". The <code>-x</code> argument states that we want to e'''x'''tract, and the <code>-f</code> argument specifies that the next argument is the filename of the tarball we wish to operate on. <code>tar</code> will automatically infer the compression of the tarball, in this case gzip, and decompress it as it is unpacking.}}

In this directory (check with <code>ls -l</code>!) there should be some files, including a ''Makefile''. This allows us to now compile the source code and install the resulting binary:

make
sudo make install

{{hint|'''Explanation:''' A Makefile instructs the <code>make</code> command on how to build a project that uses it. In this case, it also contains a ''install'' target, which copies the resulting binary into ''/usr/local/bin'' and its manual page into the local prefix for manual pages. Since only the superuser can write to these directories, we need to run the install target with <code>sudo</code>.}}

If everything went well, we should now have the <code>mcrcon</code> command available, as well as its manual page with <code>man mcrcon</code>.

{{hint|'''For The Future:''' If you ever need to recompile <code>mcrcon</code>, for example, after a major version distribution upgrade years down the line that gets rid of ''libc.so.6'', you can run:

sudo make uninstall
make clean
make
sudo make install

}}

== Making The Server Accessible From Outside Your Home Network ==

{{note|'''TODO:'''
# Explain what a dynamic IP is, set up ddclient with DuckDNS, have a systemd timer for that.
# Explain what port forwarding is, why it's needed, and why this depends on your router. Warn not to forward port 22/tcp, only port 25565/tcp.}}

== Maintaining Your Server ==

{{note|'''TODO:'''
# Explain how to start, stop, restart the Minecraft server with systemctl.
# Explain how to access server logs with journalctl.
# Explain how to keep PaperMC updated (including changing the symlink).
# Explain apt update and apt upgrade. Recommend unattended-upgrades.
# Explain Debian major releases and to keep an eye out for them.
# Recommend htop to see how CPU and RAM usage is looking.
# Recommend some backup solutions; rsync to flash drive, short mention of borg/borgmatic over the network.
# Explain how to transfer files to/from server: sftp, rsync, winscp, etc.}}

== Security Advice ==

This section will give some general security advice on running your own server, and elaborates on some decisions this guide makes.

=== SSH Public Key Authentication ===

If you absolutely insist on opening up the SSH port to the public internet, you should use public key authentication and disable password authentication for SSH altogether.

This way, public key cryptography is used to authenticate, which is computationally extremely hard to break in this case. The password you encrypt your private key with never travels over the network.

To generate an SSH public/private key pair, run

ssh-keygen

on '''your client machine''', i.e. not the Quartz64 Model B.

Then copy the newly generated SSH public key over to the Quartz64 Model B with

ssh-copy-id <var>youruser</var>@<var>yourhost</var>.local

Try logging in with ssh now. It should prompt you for your key's password, rather than the user account's password.

If it works, you should then finally disable password authentication by editing ''/etc/ssh/sshd_config'' as the superuser and setting:

PasswordAuthentication no

Then, restart the ''sshd.service'' with <code>sudo systemctl restart sshd.service</code>.

Note that from this point on, if you want to log in from a different machine, you'll need to either copy your public/private keypair over or generate a new one there and edit ''~/.ssh/authorized_keys'' manually, or run <code>ssh-copy-id</code> with the <code>-i</code> argument pointing to that public key.

=== On Minecraft Server Modifications And Plugins ===

Please note that Minecraft server modifications or plugins run with the same access as your Minecraft server. While we tried our best in this guide to restrict the Minecraft server's access to the rest of the system, it can obviously still do bad things to our Minecraft world, our computational resources and our network. That's why, whenever you install a server-side modification or plugin, you should ask yourself these questions:

# Do you trust the website/service you are downloading the mod/plugin from to not be malicious?
# Do you trust the website/service you are downloading the mod/plugin from to have the latest version uploaded by the mod/plugin's author rather than an untrustworthy third party?
# Do you trust the mod/plugin author to not be malicious?
# Do you trust the mod/plugin author to have good security practices, as to not get their account compromised or development computer infected with malware?
# Do you trust the mod/plugin to not open up security vulnerabilities in your server?

Chances are the answers to some of these questions will be "no". In that case you have some leg work to do: research the site and users, double-check you're on the right domain, read the code for anything fishy, and if you're ever unsure, ask for a second opinion from somebody knowledgeable on the topics.

This is not unwarranted paranoia: Minecraft server modifications [https://github.com/dogboy21/serializationisbad have introduced security vulnerabilities before]. Well trusted people's accounts [https://github.com/fractureiser-investigation/fractureiser have been hijacked before, or their uploads unknowingly infected with malware]. And the way this happened? They themselves were downloading modifications from malicious users.

Please do note that all these issues generally do not apply to Minecraft Data Packs. While they are more limited than modifications or plugins that hook into the actual code, these limitations are good in the context of security.

=== Do Not Engage In Security By Obscurity ===

You may be tempted to not enable a whitelist because you think nobody is going to find your Minecraft server anyway. This is false. People and bots are constantly scanning the entire internet for open services. This includes Minecraft servers. If you do not have a whitelist, you will sooner or later get uninvited visitors.

Similarly, if you expose any service other than the Minecraft server to the internet through your router, expect that to be instantly discovered as well. Automated exploit scanners will then likely be hitting it regularly.

This sounds scary, but it's really not: if your system is up-to-date and follows best security practices, you generally won't have much to fear. It just means that you can't expose any insecurely configured service to the internet and expect nobody to find it.

=== Can't Be Bothered To Maintain It? Turn It Off ===

One of the biggest possible dangers to your home network's security is unwillingness to take responsibility. If you no longer want to maintain the server, turn the board off, unplug it, and delete the port forwarding rule in your router's web interface.

The majority of security breaches don't happen because somebody tries very hard to breach one target, but because a lot of people try very little to breach many targets. Chances are they will find a system somewhere that nobody feels responsible for anymore, and which hasn't been updated in 5 years, and runs a service of a version with a known vulnerability. Avoid being that system: if your Quartz64 Model B begins operating as part of a botnet due to your indifference, the rest of the internet will suffer.

=== Why Reboots Are Sometimes Recommended ===

Occasionally, your Linux kernel package (''linux-image-arm64'') will update. This is great! The kernel is the most basic part of the operating system, and responsible for enforcing fundamental privilege separation. Unfortunately, live-patching the running kernel (i.e. updating it in memory without requiring a reboot) is something that only enterprise-grade commercial Linux distributions like RedHat Enterprise Linux or SUSE Linux do. Since we're running Debian here and Debian doesn't have this feature, the only way to run the newly updated kernel is to reboot the system.

You can run <code>cat /var/run/reboot-required</code> to see if your Quartz64 Model B requires a reboot. It's worth noting that the Linux kernel development community does not distinguish regular bugs from security bugs, as many a "regular" bug could be a security bug in the right circumstances. However, Debian itself [https://www.debian.org/security/#DSAS publishes security advisories] when a Linux kernel update they ship fixes known potential security issues.

Whether or not you want to reboot for a specific kernel update is up to you. People run servers with hundreds of days of uptime (check with the command <code>uptime</code>) just fine; just because a potential security issue was fixed in the Linux kernel doesn't mean it'd be part of a realistic attack scenario on a specific system. In our case, the attack scenario we're most worried about is that somebody manages to breach the PaperMC Minecraft server, and then gains arbitrary code execution in its context, from which they will then likely attempt to attack the kernel to gain additional privileges. A second, much less likely attack scenario is that the Linux kernel would have a vulnerability in its network stack that would allow an attacker to remotely exploit it. Such vulnerabilities are exceedingly rare in Linux.

=== Why Not Docker: On Software Supply Chains And Understanding Your Stack ===

For the majority of this guide, self-declared DevOps EpicPoggers Awesomeninjas have probably been foaming at their mouth jumping at the opportunity to exclaim that one should just use Docker. This section serves as a soapbox to talk about the problems with that suggestion.

While a Docker container may be, well, contained, it pulls in an entire stacking doll of other images it is built upon. This means an entire operating system to support the application being run, minus a kernel.

This is great if you are the person writing the image manifests, know what your dependency requirements are, and track the entire software supply chain to ensure you always get the right versions for your stack, with all the latest vulnerabilities patched.

However, this is not how the vast majority of people use Docker. The overwhelming majority of Docker users simply pull some random person's image, run it, and thus make these assumptions:

# That the author of the image is not malicious. Malicious images [https://sysdig.com/blog/analysis-of-supply-chain-attacks-through-public-docker-images/ are widespread on Docker Hub].
# That the author of the image has good security practices in order to avoid publishing malicious images. We know account compromises will happen as Docker Hub seemingly does not require Two-Factor Authentication.
# That the author will update the images when critical security fixes in any of the things they depend on are fixed. A [https://dl.acm.org/doi/10.1145/3029806.3029832 2017 research paper] found that many images are hundreds of days old.
# That any of the things that image depends on, recursively, will also meet these three points.

For a single service/single node scenario, Docker complicates the software supply chain massively. Instead of getting most of our system from a source we already trust (Debian), we're now getting a whole second system from a myriad of sources opaquely compiled into one image.

Additionally, Docker complicates the following things:

* Knowing what version a specific runtime dependency is, and that all copies of this dependency on the entire system are patched against the latest vulnerability.
* Updating the container image and spinning up a new container based on it; this is not handled through your system's package manager.
* Persistent data; it's stored in Docker volumes, which may or may not be attached to containers, and you need to actively try to have them stored somewhere other than the default location.
* Service management; Docker reinvents service management in its own, arguably worse way.
* Networking; things are on a virtual network with Docker, which complicates firewall rules and other network configurations.
* Logging; Docker reinvents this too.

By not using a Docker container, but rather a locked down systemd service, we get the following benefits:

* All system software updates, including the Java Runtime, are handled by Debian, irrespective of the version of the Minecraft server we run.
* All of our services use the same system dependencies, and we can answer the question of "has <var>xyz</var> been patched?" by just looking at <code>apt</code>.
* We still get reasonably strong process isolation thanks to the various security sandboxing options our systemd service uses, despite not using Linux namespaces (containers).
* Our persistent data is where we expect it to be, owned by the user and group we expect it to be owned by.
* Our network is not burdened with virtual interfaces and forwarding rules.
* Our Minecraft server is tracked and dependency ordered by systemd's service management. It's automatically started on boot, and gracefully stopped on shutdown.
* Our Minecraft server's logs will show up in the system journal, and we can filter through them or correlate them with other sources just as with any other service reporting to the journal.

Container images built from manifests start to make sense when you are running complex sets of services scaled horizontally across a massive homogeneous cluster, where you want to rescale as needed and deploy new versions of your entire stack as immutable images that you can roll back easily. They also make some amount of sense in a case where you only have access to a very old userland (e.g. a stable enterprise Linux release) but need to run software requiring a myriad of dependencies that are either not packaged or not of a recent enough version in your distribution.

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

To hook up UART serial debug, connect your Woodpecker, ideally with a decent USB extension cord, to your computer's USB port. Make sure the yellow jumper is set to 3.3V.

Connect the GND pin of the Woodpecker to a GND pin of your Quartz64 Model B, which are coloured as black pins. A good one to use is pin number 6 (the one after the red pin 2 and pin 4), as it's right next to the other UART pins we'll need.

Next, hook up the Woodpecker's RXD pin to the Quartz64 Model B's pin number 8, which is next to (lengthwise down the row of pins) the aforementioned pin number 6, coloured in green.

Finally, hook up the Woodpecker's TXD pin to the QUartz64 Model B's pin number 10, which is down yet another pin in the same direction, also coloured in green.

{{note|'''TODO:''' Add a diagram showing the connections here.}}

==== Accessing The Serial Console On Windows ====

{{note|'''TODO:''' Add a guide on how to install, configure and use PuTTY}}

==== Accessing The Serial Console On Linux ====

{{note|'''TODO:''' Validate the serial settings here.}}
{{note|'''Warning:''' Some poorly written software, like <code>gpsd</code> or <code>brltty</code>, will randomly and happily claim and mess with any USB-to-serial adapters on the system, especially when you least want them to. Use <code>sudo lsof /dev/ttyUSB<var>n</var></code> to determine whether this is the case for you if you run into any trouble with the following steps.}}

First, list all the available USB-to-Serial adapters on your system:

ls /dev/ttyUSB*

If you only have one plugged in, this should probably only return <code>/dev/ttyUSB0</code>.

Next, you have some choice of serial terminal to use: <code>screen</code> (likely already installed), <code>minicom</code> and <code>picocom</code>.

For screen, (replacing <var>n</var> with the number of your serial adapter) use:

screen /dev/ttyUSB<var>n</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

For minicom, (replacing <var>n</var> with the number of your serial adapter) use:

minicom -D /dev/ttyUSB<var>n</var> -b 1500000 -8

You can quit minicom by hitting Ctrl+a, then hit q.

For picocom, (replacing <var>n</var> with the number of your serial adapter) use:

picocom /dev/ttyUSB<var>n</var> -b 1500000

You can quit picocom by hitting Ctrl+a, then hit Ctrl+q.

==== Accessing The Serial Console On macOS ====

{{note|'''TODO:''' Validate the serial settings here, and validate the device name.}}

Open up a terminal, then list all the available serial devices on your system:

ls /dev/tty.*

This will likely return something starting with <code>/dev/tty.usbserial-</code>.

Now we can open this serial port with <code>screen</code> as follows, replacing <var>foo</var> with the adapter name from the previous step:

screen /dev/tty.usbserial-<var>foo</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

==== Using The Serial Console ====

If you just hooked it up to a running system, you're unlikely to see any output. You will only be able to see messages from the point on when you've opened up your serial communication program.

If your board is doing the heartbeat pattern (i.e., it booted, but you're unable to log in over the network) you can hit Enter to (hopefully) make it show you a login prompt. If the login prompt is your first time communicating with the board, use username ''pleb'' and password ''pleb''. From then on, the serial terminal should work like any normal shell you'd have on the system, modulo some possible weirdness with special escape sequences making things a little more prone to drawing in broken ways.

If your board is not doing the heartbeat pattern, hit the reset button (small white button on side of board, the one closer towards the antenna mount) and you should be getting serial output from a fresh boot.

If you still don't get any output, make sure that you flashed the microSD card correctly, and make sure the TXD and RXD lines aren't the wrong way around. If you still don't get any output after that, your Quartz64 Model B may have defective level shifting transistors on the serial lines, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

=== Is My Ethernet Broken? ===

Pine Store has sold a number of boards where the ethernet PHY chip was seemingly broken. If your board exhibits the heartbeat LED pattern but never shows up on the network, either hook up a monitor and a keyboard or use your Woodpecker to hook up to serial (see [[#Connecting UART]]) and try to log in.

After logging in, type:

sudo dmesg | grep rk_gmac-dwmac

If the output contains any lines like

rk_gmac-dwmac fe010000.ethernet end0: __stmmac_open: Cannot attach to PHY (error: -22)

then your hardware is defective, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-15T13:53:19Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}
{{hint|'''For prospective editors:''' This guide was authored by [[User:CounterPillow]]. Please read the lengthy comment at the top of the article in the edit window before trying to contribute to it in any way.}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

{{note|'''Note:''' If you see a heartbeat pattern but the board never gets a DHCP lease, please follow the steps in [[#Is My Ethernet Broken?]].}}

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

=== Permissions ===

On Unix-like systems like Linux, files and directories are owned by one user and one group. Additionally, there are read/write/execute permissions applying for each file or directory for either the user, the group or everyone else.

We can view these permissions with <code>ls -al</code> in the first column. You'll see something like:

-rwxrw-r--

This would indicate a file (<code>d</code> not being present as the first letter, instead being <code>-</code>) that is

* '''r'''eadable by the user that owns it, '''w'''ritable by the user that owns it, e'''x'''ecutable by the user that owns it
* readable by anyone in the group that owns it, writable by anyone in the group that owns it, '''not''' executable by anyone in the group that owns it (unless, in this case, that specific user owns it)
* readable by everyone else, but neither writable nor executable by them.

You can ignore the next column (the number) in the output. The two columns that come after that are the user and the group that own the file/directory respectively.

{{hint|'''Further Explanation:''' "Executable" on a directory doesn't quite do what one might think it does: it means one is able to <code>cd</code> into the directory and read what files/directories it contains.}}

We can change the owner of a file with the <code>chown</code> command:

sudo chown <var>newuser</var>:<var>newgroup</var> <var>foo</var>

This would change the user that owns <var>foo</var> to <var>newuser</var>, and the group that owns the <var>foo</var> to <var>newgroup</var>. By adding the <code>-R</code> argument, we can also make this operation apply recursively to every file and directory contained within a targeted directory.

Similarly, we can modify the permission flags for the '''u'''ser, '''g'''roup and '''o'''ther users with the <code>chmod</code> command. This is best illustrated with a few examples:

* <code>chmod o+w <var>foo</var></code>: give everybody write permissions to <var>foo</var>.
* <code>chmod g=rw <var>foo</var></code>: set group permissions to read and write <var>foo</var>, but remove the group execute flag if present.
* <code>chmod u-x <var>foo</var></code>: remove execute permissions for the user that owns <var>foo</var>, but leave read/write flags as-is.
* <code>chmod ug=rw <var>foo</var></code>: set user and group permissions for <var>foo</var> to read/write but not execute.

You can once again combine this with the <code>-R</code> argument to make the operation recursive.

{{hint|'''Hint:''' Only the superuser can change the permissions of files or directories not owned by them.}}
{{hint|'''Further Explanation:''' Consult <code>man chown</code> and <code>man chmod</code> for further details. You can close the manual reader by pressing '''q'''.}}

== Setting Up The Network ==

=== Configuring A Fixed LAN IP Address ===

By default, the Plebian images use NetworkManager to automatically configure the ethernet interface in such a way that it asks your router to assign it an IP address inside your local network with a protocol called DHCP. What happens is that the Quartz64 asks the router for an IP address, and the router hands it one from a pool of addresses for a limited span of time, a so-called "lease". Dynamically configuring the IP address like this is great for quickly getting started, especially when in combination with mDNS, as everything just works automatically out of the box.

However, a bit later on in this guide, we'll want the router to know exactly what IP address our Quartz64 Model B is going to respond to even across power cycles of either device. That's why at this point, we'll set it up to have a fixed local network address, with '''one''' of two methods.

==== Method A: Using Reserved DHCP Leases ====

With this method, we'll simply configure your router to always hand the same IP address out over DHCP for the hardware address (MAC) of your Quartz64 Model B.

Many routers will have a web interface through which you can configure them. To find your router's IP address, type <code>ip route</code> into your SSH session with the Quartz64 Model B and hit enter to run the command. It should output something like:

default via 192.168.0.1 dev end0 proto dhcp src 192.168.0.58 metric 100
192.168.0.0/24 dev end0 proto kernel scope link src 192.168.0.58 metric 100

In this case, we can see that our router is <code>192.168.0.1</code>, as the ''default via'' route goes through it. Yours may be different.

You can now type this router IP address into your web browser, and with any luck, you'll be greeted with a web login prompt. If you've never set a password on your router's management interface, check the bottom or sides of your device for a sticker that lists a default password.

The precise management interface differs from router to router, so this guide can't give precise instructions. However, once logged in, there is usually a section labelled "DHCP". In it, you may be able to configure reserved IP addresses for a specific MAC address. To find the MAC address of your Quartz64 Model B, run "ip link" on it, which will give you output like this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: end0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 76:36:c7:c4:57:e2 brd ff:ff:ff:ff:ff:ff

What we want here is the first colon separated address in the second link (end0), in this case <code>76:36:c7:c4:57:e2</code>. Your router should let you enter this MAC address somewhere to reserve a specific address from the DHCP pool for it.

==== Method B: Using A Fixed IP ====

If Method A isn't available to you, this method should always work.

Instead of using DHCP to request a lease for an IP address, our Quartz64 Model B can also simply assume it can communicate using a fixed IP address.

'''Important:''' Our fixed IP address should be ''outside'' the range of IP addresses our router hands out through DHCP, as otherwise collisions may occur! In the router web interface, look for a DHCP start address field and DHCP pool size field. An IP address either smaller than the start address (though above 0 and not colliding with the router's address) or larger than the start address plus the pool size (though below 255) will work; you may have to reduce the size of the DHCP pool if it's all maxed out though.

For example, with a DHCP pool that starts at 192.168.0.40 and has a size of 215, we could use a fixed IP address like 192.168.0.10 without accidentally colliding with one the router hands out.

Run the command

sudo nmtui

which should open up an interactive connection editor. Use your cursor keys to highlight the entry "Wired connection 1", and hit the right arrow key to navigate towards the "Edit" option, and hit enter.

Navigate to "IPv4 CONFIGURATION" and hit enter on "<Automatic>", then select "<Manual>". Navigate to the right over the "<Show>", and hit enter again. You should now be greeted by a whole host of options:

# In "Addresses:", hit "<Add...>" and enter your chosen fixed IPv4 address followed by <code>/32</code>, for example <code>192.168.0.21/32</code>.
# In "Gateway", enter your router's IPv4 address.
# In DNS Servers, enter on "<Add...>" and add <code>1.1.1.1</code>. Repeat the same process, but with <code>1.0.0.1</code>. This will add Cloudflare's DNS servers, as we'll no longer be receiving the router's DNS servers with manual configuration.
# Check the box next to "Ignore automatically obtained DNS parameters" by navigating over it and hitting the space bar. This makes sure that if our router tries to give us some DNS servers anyway, we don't use them.
# Check "Require IPv4 addressing for this connection" in the same way.
# Just to be consistent, go to "IPv6 CONFIGURATION", but this time leave it on Automatic. Hit "<Show...>" to expand it.
# Add the following two Cloudflare DNS servers: <code>2606:4700:4700::1111</code> and <code>2606:4700:4700::1001</code>.
# Check "Ignore automatically obtained DNS parameters".
# Navigate down to "<OK>" and hit enter
# Hit escape twice to quit nmtui

The easiest way to make sure your new network connection settings are used is to reboot your board with

sudo reboot

After logging back in, the command

ip addr

should show your chosen IP under end0 after "inet".

=== Configuring A Firewall ===

{{note|'''TODO:''' Explain how to set up a persistent firewall that allows ports 22/tcp from LAN and 25565/tcp from anywhere.}}

== Formatting The NVMe Drive ==

{{note|'''TODO:''' Explain how to wipefs + fdisk + format the NVMe drive, make a mount point and put it in fstab.}}

== Setting Up The Minecraft Java Edition Server ==

{{note|'''TODO:'''
# Add a minecraft system user with a minecraft group that has write permissions to the minecraft directory on NVMe, add minecraft to supplemental groups for user.
# Install Java, download PaperMC to the Minecraft directory, symlink it to paper.jar, run it once, accept the EULA.
# Edit server.properties, enable rcon with a password, enable whitelist, edit motd and set difficulty.
# Add the systemd unit to /etc/systemd/system/, set it to auto-start, then start it.
# Add player to whitelist and ops through rcon.
# Connect to the server for the first time!}}

=== Getting An RCon Client ===

Minecraft's server has a control protocol called "rcon". We'll need this protocol to gracefully shut down the Minecraft server, and add ourselves to ops later on. For this, we'll need a Minecraft RCon client. [https://github.com/Tiiffi/mcrcon Tiiffi/mcrcon] is a good one, but we need to compile and install it first.

To start off, let's install some required tools to compile it. In your Quartz64 Model B's SSH session, type:

sudo apt update
sudo apt install build-essential

Next we'll download the source code for mcrcon:

wget --content-disposition https://github.com/Tiiffi/mcrcon/archive/refs/tags/v0.7.2.tar.gz

This should have downloaded us an ''mcrcon-0.7.2.tar.gz'' archive file. Let's verify that what we've downloaded matches what this guide expects:

sha256sum mcrcon-0.7.2.tar.gz

This should output the following; compare the first string of letter and numbers to yours, they must match:

1743b25a2d031b774e805f4011cb7d92010cb866e3b892f5dfc5b42080973270 mcrcon-0.7.2.tar.gz

Now let's unpack the ''.tar.gz'' archive and change into the directory it contains:

tar -xf mcrcon-0.7.2.tar.gz
cd mcrcon-0.7.2/

{{hint|'''Explanation:''' <code>tar</code> is the standard utility for creating, modifying, inspecting and unpacking tar archives, commonly referred to as "tarballs". The <code>-x</code> argument states that we want to e'''x'''tract, and the <code>-f</code> argument specifies that the next argument is the filename of the tarball we wish to operate on. <code>tar</code> will automatically infer the compression of the tarball, in this case gzip, and decompress it as it is unpacking.}}

In this directory (check with <code>ls -l</code>!) there should be some files, including a ''Makefile''. This allows us to now compile the source code and install the resulting binary:

make
sudo make install

{{hint|'''Explanation:''' A Makefile instructs the <code>make</code> command on how to build a project that uses it. In this case, it also contains a ''install'' target, which copies the resulting binary into ''/usr/local/bin'' and its manual page into the local prefix for manual pages. Since only the superuser can write to these directories, we need to run the install target with <code>sudo</code>.}}

If everything went well, we should now have the <code>mcrcon</code> command available, as well as its manual page with <code>man mcrcon</code>.

{{hint|'''For The Future:''' If you ever need to recompile <code>mcrcon</code>, for example, after a major version distribution upgrade years down the line that gets rid of ''libc.so.6'', you can run:

sudo make uninstall
make clean
make
sudo make install

}}

== Making The Server Accessible From Outside Your Home Network ==

{{note|'''TODO:'''
# Explain what a dynamic IP is, set up ddclient with DuckDNS, have a systemd timer for that.
# Explain what port forwarding is, why it's needed, and why this depends on your router. Warn not to forward port 22/tcp, only port 25565/tcp.}}

== Maintaining Your Server ==

{{note|'''TODO:'''
# Explain how to start, stop, restart the Minecraft server with systemctl.
# Explain how to access server logs with journalctl.
# Explain how to keep PaperMC updated (including changing the symlink).
# Explain apt update and apt upgrade. Recommend unattended-upgrades.
# Explain Debian major releases and to keep an eye out for them.
# Recommend htop to see how CPU and RAM usage is looking.
# Recommend some backup solutions; rsync to flash drive, short mention of borg/borgmatic over the network.
# Explain how to transfer files to/from server: sftp, rsync, winscp, etc.}}

== Security Advice ==

This section will give some general security advice on running your own server, and elaborates on some decisions this guide makes.

=== SSH Public Key Authentication ===

If you absolutely insist on opening up the SSH port to the public internet, you should use public key authentication and disable password authentication for SSH altogether.

This way, public key cryptography is used to authenticate, which is computationally extremely hard to break in this case. The password you encrypt your private key with never travels over the network.

To generate an SSH public/private key pair, run

ssh-keygen

on '''your client machine''', i.e. not the Quartz64 Model B.

Then copy the newly generated SSH public key over to the Quartz64 Model B with

ssh-copy-id <var>youruser</var>@<var>yourhost</var>.local

Try logging in with ssh now. It should prompt you for your key's password, rather than the user account's password.

If it works, you should then finally disable password authentication by editing ''/etc/ssh/sshd_config'' as the superuser and setting:

PasswordAuthentication no

Then, restart the ''sshd.service'' with <code>sudo systemctl restart sshd.service</code>.

Note that from this point on, if you want to log in from a different machine, you'll need to either copy your public/private keypair over or generate a new one there and edit ''~/.ssh/authorized_keys'' manually, or run <code>ssh-copy-id</code> with the <code>-i</code> argument pointing to that public key.

=== On Minecraft Server Modifications And Plugins ===

Please note that Minecraft server modifications or plugins run with the same access as your Minecraft server. While we tried our best in this guide to restrict the Minecraft server's access to the rest of the system, it can obviously still do bad things to our Minecraft world, our computational resources and our network. That's why, whenever you install a server-side modification or plugin, you should ask yourself these questions:

# Do you trust the website/service you are downloading the mod/plugin from to not be malicious?
# Do you trust the website/service you are downloading the mod/plugin from to have the latest version uploaded by the mod/plugin's author rather than an untrustworthy third party?
# Do you trust the mod/plugin author to not be malicious?
# Do you trust the mod/plugin author to have good security practices, as to not get their account compromised or development computer infected with malware?
# Do you trust the mod/plugin to not open up security vulnerabilities in your server?

Chances are the answers to some of these questions will be "no". In that case you have some leg work to do: research the site and users, double-check you're on the right domain, read the code for anything fishy, and if you're ever unsure, ask for a second opinion from somebody knowledgeable on the topics.

This is not unwarranted paranoia: Minecraft server modifications [https://github.com/dogboy21/serializationisbad have introduced security vulnerabilities before]. Well trusted people's accounts [https://github.com/fractureiser-investigation/fractureiser have been hijacked before, or their uploads unknowingly infected with malware]. And the way this happened? They themselves were downloading modifications from malicious users.

Please do note that all these issues generally do not apply to Minecraft Data Packs. While they are more limited than modifications or plugins that hook into the actual code, these limitations are good in the context of security.

=== Do Not Engage In Security By Obscurity ===

You may be tempted to not enable a whitelist because you think nobody is going to find your Minecraft server anyway. This is false. People and bots are constantly scanning the entire internet for open services. This includes Minecraft servers. If you do not have a whitelist, you will sooner or later get uninvited visitors.

Similarly, if you expose any service other than the Minecraft server to the internet through your router, expect that to be instantly discovered as well. Automated exploit scanners will then likely be hitting it regularly.

This sounds scary, but it's really not: if your system is up-to-date and follows best security practices, you generally won't have much to fear. It just means that you can't expose any insecurely configured service to the internet and expect nobody to find it.

=== Can't Be Bothered To Maintain It? Turn It Off ===

One of the biggest possible dangers to your home network's security is unwillingness to take responsibility. If you no longer want to maintain the server, turn the board off, unplug it, and delete the port forwarding rule in your router's web interface.

The majority of security breaches don't happen because somebody tries very hard to breach one target, but because a lot of people try very little to breach many targets. Chances are they will find a system somewhere that nobody feels responsible for anymore, and which hasn't been updated in 5 years, and runs a service of a version with a known vulnerability. Avoid being that system: if your Quartz64 Model B begins operating as part of a botnet due to your indifference, the rest of the internet will suffer.

=== Why Reboots Are Sometimes Recommended ===

Occasionally, your Linux kernel package (''linux-image-arm64'') will update. This is great! The kernel is the most basic part of the operating system, and responsible for enforcing fundamental privilege separation. Unfortunately, live-patching the running kernel (i.e. updating it in memory without requiring a reboot) is something that only enterprise-grade commercial Linux distributions like RedHat Enterprise Linux or SUSE Linux do. Since we're running Debian here and Debian doesn't have this feature, the only way to run the newly updated kernel is to reboot the system.

You can run <code>cat /var/run/reboot-required</code> to see if your Quartz64 Model B requires a reboot. It's worth noting that the Linux kernel development community does not distinguish regular bugs from security bugs, as many a "regular" bug could be a security bug in the right circumstances. However, Debian itself [https://www.debian.org/security/#DSAS publishes security advisories] when a Linux kernel update they ship fixes known potential security issues.

Whether or not you want to reboot for a specific kernel update is up to you. People run servers with hundreds of days of uptime (check with the command <code>uptime</code>) just fine; just because a potential security issue was fixed in the Linux kernel doesn't mean it'd be part of a realistic attack scenario on a specific system. In our case, the attack scenario we're most worried about is that somebody manages to breach the PaperMC Minecraft server, and then gains arbitrary code execution in its context, from which they will then likely attempt to attack the kernel to gain additional privileges. A second, much less likely attack scenario is that the Linux kernel would have a vulnerability in its network stack that would allow an attacker to remotely exploit it. Such vulnerabilities are exceedingly rare in Linux.

=== Why Not Docker: On Software Supply Chains And Understanding Your Stack ===

For the majority of this guide, self-declared DevOps EpicPoggers Awesomeninjas have probably been foaming at their mouth jumping at the opportunity to exclaim that one should just use Docker. This section serves as a soapbox to talk about the problems with that suggestion.

While a Docker container may be, well, contained, it pulls in an entire stacking doll of other images it is built upon. This means an entire operating system to support the application being run, minus a kernel.

This is great if you are the person writing the image manifests, know what your dependency requirements are, and track the entire software supply chain to ensure you always get the right versions for your stack, with all the latest vulnerabilities patched.

However, this is not how the vast majority of people use Docker. The overwhelming majority of Docker users simply pull some random person's image, run it, and thus make these assumptions:

# That the author of the image is not malicious. Malicious images [https://sysdig.com/blog/analysis-of-supply-chain-attacks-through-public-docker-images/ are widespread on Docker Hub].
# That the author of the image has good security practices in order to avoid publishing malicious images. We know account compromises will happen as Docker Hub seemingly does not require Two-Factor Authentication.
# That the author will update the images when critical security fixes in any of the things they depend on are fixed. A [https://dl.acm.org/doi/10.1145/3029806.3029832 2017 research paper] found that many images are hundreds of days old.
# That any of the things that image depends on, recursively, will also meet these three points.

For a single service/single node scenario, Docker complicates the software supply chain massively. Instead of getting most of our system from a source we already trust (Debian), we're now getting a whole second system from a myriad of sources opaquely compiled into one image.

Additionally, Docker complicates the following things:

* Knowing what version a specific runtime dependency is, and that all copies of this dependency on the entire system are patched against the latest vulnerability.
* Updating the container image and spinning up a new container based on it; this is not handled through your system's package manager.
* Persistent data; it's stored in Docker volumes, which may or may not be attached to containers, and you need to actively try to have them stored somewhere other than the default location.
* Service management; Docker reinvents service management in its own, arguably worse way.
* Networking; things are on a virtual network with Docker, which complicates firewall rules and other network configurations.
* Logging; Docker reinvents this too.

By not using a Docker container, but rather a locked down systemd service, we get the following benefits:

* All system software updates, including the Java Runtime, are handled by Debian, irrespective of the version of the Minecraft server we run.
* All of our services use the same system dependencies, and we can answer the question of "has <var>xyz</var> been patched?" by just looking at <code>apt</code>.
* We still get reasonably strong process isolation thanks to the various security sandboxing options our systemd service uses, despite not using Linux namespaces (containers).
* Our persistent data is where we expect it to be, owned by the user and group we expect it to be owned by.
* Our network is not burdened with virtual interfaces and forwarding rules.
* Our Minecraft server is tracked and dependency ordered by systemd's service management. It's automatically started on boot, and gracefully stopped on shutdown.
* Our Minecraft server's logs will show up in the system journal, and we can filter through them or correlate them with other sources just as with any other service reporting to the journal.

Container images built from manifests start to make sense when you are running complex sets of services scaled horizontally across a massive homogeneous cluster, where you want to rescale as needed and deploy new versions of your entire stack as immutable images that you can roll back easily. They also make some amount of sense in a case where you only have access to a very old userland (e.g. a stable enterprise Linux release) but need to run software requiring a myriad of dependencies that are either not packaged or not of a recent enough version in your distribution.

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

To hook up UART serial debug, connect your Woodpecker, ideally with a decent USB extension cord, to your computer's USB port. Make sure the yellow jumper is set to 3.3V.

Connect the GND pin of the Woodpecker to a GND pin of your Quartz64 Model B, which are coloured as black pins. A good one to use is pin number 6 (the one after the red pin 2 and pin 4), as it's right next to the other UART pins we'll need.

Next, hook up the Woodpecker's RXD pin to the Quartz64 Model B's pin number 8, which is next to (lengthwise down the row of pins) the aforementioned pin number 6, coloured in green.

Finally, hook up the Woodpecker's TXD pin to the QUartz64 Model B's pin number 10, which is down yet another pin in the same direction, also coloured in green.

{{note|'''TODO:''' Add a diagram showing the connections here.}}

==== Accessing The Serial Console On Windows ====

{{note|'''TODO:''' Add a guide on how to install, configure and use PuTTY}}

==== Accessing The Serial Console On Linux ====

{{note|'''TODO:''' Validate the serial settings here.}}
{{note|'''Warning:''' Some poorly written software, like <code>gpsd</code> or <code>brltty</code>, will randomly and happily claim and mess with any USB-to-serial adapters on the system, especially when you least want them to. Use <code>sudo lsof /dev/ttyUSB<var>n</var></code> to determine whether this is the case for you if you run into any trouble with the following steps.}}

First, list all the available USB-to-Serial adapters on your system:

ls /dev/ttyUSB*

If you only have one plugged in, this should probably only return <code>/dev/ttyUSB0</code>.

Next, you have some choice of serial terminal to use: <code>screen</code> (likely already installed), <code>minicom</code> and <code>picocom</code>.

For screen, (replacing <var>n</var> with the number of your serial adapter) use:

screen /dev/ttyUSB<var>n</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

For minicom, (replacing <var>n</var> with the number of your serial adapter) use:

minicom -D /dev/ttyUSB<var>n</var> -b 1500000 -8

You can quit minicom by hitting Ctrl+a, then hit q.

For picocom, (replacing <var>n</var> with the number of your serial adapter) use:

picocom /dev/ttyUSB<var>n</var> -b 1500000

You can quit picocom by hitting Ctrl+a, then hit Ctrl+q.

==== Accessing The Serial Console On macOS ====

{{note|'''TODO:''' Validate the serial settings here, and validate the device name.}}

Open up a terminal, then list all the available serial devices on your system:

ls /dev/tty.*

This will likely return something starting with <code>/dev/tty.usbserial-</code>.

Now we can open this serial port with <code>screen</code> as follows, replacing <var>foo</var> with the adapter name from the previous step:

screen /dev/tty.usbserial-<var>foo</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

==== Using The Serial Console ====

If you just hooked it up to a running system, you're unlikely to see any output. You will only be able to see messages from the point on when you've opened up your serial communication program.

If your board is doing the heartbeat pattern (i.e., it booted, but you're unable to log in over the network) you can hit Enter to (hopefully) make it show you a login prompt. If the login prompt is your first time communicating with the board, use username ''pleb'' and password ''pleb''. From then on, the serial terminal should work like any normal shell you'd have on the system, modulo some possible weirdness with special escape sequences making things a little more prone to drawing in broken ways.

If your board is not doing the heartbeat pattern, hit the reset button (small white button on side of board, the one closer towards the antenna mount) and you should be getting serial output from a fresh boot.

If you still don't get any output, make sure that you flashed the microSD card correctly, and make sure the TXD and RXD lines aren't the wrong way around. If you still don't get any output after that, your Quartz64 Model B may have defective level shifting transistors on the serial lines, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

=== Is My Ethernet Broken? ===

Pine Store has sold a number of boards where the ethernet PHY chip was seemingly broken. If your board exhibits the heartbeat LED pattern but never shows up on the network, either hook up a monitor and a keyboard or use your Woodpecker to hook up to serial (see [[#Connecting UART]]) and try to log in.

After logging in, type:

sudo dmesg | grep rk_gmac-dwmac

If the output contains any lines like

rk_gmac-dwmac fe010000.ethernet end0: __stmmac_open: Cannot attach to PHY (error: -22)

then your hardware is defective, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-14T16:09:26Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}
{{hint|'''For prospective editors:''' This guide was authored by [[User:CounterPillow]]. Please read the lengthy comment at the top of the article in the edit window before trying to contribute to it in any way.}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

{{note|'''Note:''' If you see a heartbeat pattern but the board never gets a DHCP lease, please follow the steps in [[#Is My Ethernet Broken?]].}}

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

=== Permissions ===

{{note|'''TODO:''' Write a section explaining file ownership and permissions.}}

== Setting Up The Network ==

=== Configuring A Fixed LAN IP Address ===

By default, the Plebian images use NetworkManager to automatically configure the ethernet interface in such a way that it asks your router to assign it an IP address inside your local network with a protocol called DHCP. What happens is that the Quartz64 asks the router for an IP address, and the router hands it one from a pool of addresses for a limited span of time, a so-called "lease". Dynamically configuring the IP address like this is great for quickly getting started, especially when in combination with mDNS, as everything just works automatically out of the box.

However, a bit later on in this guide, we'll want the router to know exactly what IP address our Quartz64 Model B is going to respond to even across power cycles of either device. That's why at this point, we'll set it up to have a fixed local network address, with '''one''' of two methods.

==== Method A: Using Reserved DHCP Leases ====

With this method, we'll simply configure your router to always hand the same IP address out over DHCP for the hardware address (MAC) of your Quartz64 Model B.

Many routers will have a web interface through which you can configure them. To find your router's IP address, type <code>ip route</code> into your SSH session with the Quartz64 Model B and hit enter to run the command. It should output something like:

default via 192.168.0.1 dev end0 proto dhcp src 192.168.0.58 metric 100
192.168.0.0/24 dev end0 proto kernel scope link src 192.168.0.58 metric 100

In this case, we can see that our router is <code>192.168.0.1</code>, as the ''default via'' route goes through it. Yours may be different.

You can now type this router IP address into your web browser, and with any luck, you'll be greeted with a web login prompt. If you've never set a password on your router's management interface, check the bottom or sides of your device for a sticker that lists a default password.

The precise management interface differs from router to router, so this guide can't give precise instructions. However, once logged in, there is usually a section labelled "DHCP". In it, you may be able to configure reserved IP addresses for a specific MAC address. To find the MAC address of your Quartz64 Model B, run "ip link" on it, which will give you output like this:

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: end0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 76:36:c7:c4:57:e2 brd ff:ff:ff:ff:ff:ff

What we want here is the first colon separated address in the second link (end0), in this case <code>76:36:c7:c4:57:e2</code>. Your router should let you enter this MAC address somewhere to reserve a specific address from the DHCP pool for it.

==== Method B: Using A Fixed IP ====

If Method A isn't available to you, this method should always work.

Instead of using DHCP to request a lease for an IP address, our Quartz64 Model B can also simply assume it can communicate using a fixed IP address.

'''Important:''' Our fixed IP address should be ''outside'' the range of IP addresses our router hands out through DHCP, as otherwise collisions may occur! In the router web interface, look for a DHCP start address field and DHCP pool size field. An IP address either smaller than the start address (though above 0 and not colliding with the router's address) or larger than the start address plus the pool size (though below 255) will work; you may have to reduce the size of the DHCP pool if it's all maxed out though.

For example, with a DHCP pool that starts at 192.168.0.40 and has a size of 215, we could use a fixed IP address like 192.168.0.10 without accidentally colliding with one the router hands out.

Run the command

sudo nmtui

which should open up an interactive connection editor. Use your cursor keys to highlight the entry "Wired connection 1", and hit the right arrow key to navigate towards the "Edit" option, and hit enter.

Navigate to "IPv4 CONFIGURATION" and hit enter on "<Automatic>", then select "<Manual>". Navigate to the right over the "<Show>", and hit enter again. You should now be greeted by a whole host of options:

# In "Addresses:", hit "<Add...>" and enter your chosen fixed IPv4 address followed by <code>/32</code>, for example <code>192.168.0.21/32</code>.
# In "Gateway", enter your router's IPv4 address.
# In DNS Servers, enter on "<Add...>" and add <code>1.1.1.1</code>. Repeat the same process, but with <code>1.0.0.1</code>. This will add Cloudflare's DNS servers, as we'll no longer be receiving the router's DNS servers with manual configuration.
# Check the box next to "Ignore automatically obtained DNS parameters" by navigating over it and hitting the space bar. This makes sure that if our router tries to give us some DNS servers anyway, we don't use them.
# Check "Require IPv4 addressing for this connection" in the same way.
# Just to be consistent, go to "IPv6 CONFIGURATION", but this time leave it on Automatic. Hit "<Show...>" to expand it.
# Add the following two Cloudflare DNS servers: <code>2606:4700:4700::1111</code> and <code>2606:4700:4700::1001</code>.
# Check "Ignore automatically obtained DNS parameters".
# Navigate down to "<OK>" and hit enter
# Hit escape twice to quit nmtui

The easiest way to make sure your new network connection settings are used is to reboot your board with

sudo reboot

After logging back in, the command

ip addr

should show your chosen IP under end0 after "inet".

=== Configuring A Firewall ===

{{note|'''TODO:''' Explain how to set up a persistent firewall that allows ports 22/tcp from LAN and 25565/tcp from anywhere.}}

== Formatting The NVMe Drive ==

{{note|'''TODO:''' Explain how to wipefs + fdisk + format the NVMe drive, make a mount point and put it in fstab.}}

== Setting Up The Minecraft Java Edition Server ==

{{note|'''TODO:'''
# Add a minecraft system user with a minecraft group that has write permissions to the minecraft directory on NVMe, add minecraft to supplemental groups for user.
# Install Java, download PaperMC to the Minecraft directory, symlink it to paper.jar, run it once, accept the EULA.
# Edit server.properties, enable rcon with a password, enable whitelist, edit motd and set difficulty.
# Add the systemd unit to /etc/systemd/system/, set it to auto-start, then start it.
# Add player to whitelist and ops through rcon.
# Connect to the server for the first time!}}

=== Getting An RCon Client ===

Minecraft's server has a control protocol called "rcon". We'll need this protocol to gracefully shut down the Minecraft server, and add ourselves to ops later on. For this, we'll need a Minecraft RCon client. [https://github.com/Tiiffi/mcrcon Tiiffi/mcrcon] is a good one, but we need to compile and install it first.

To start off, let's install some required tools to compile it. In your Quartz64 Model B's SSH session, type:

sudo apt update
sudo apt install build-essential

Next we'll download the source code for mcrcon:

wget --content-disposition https://github.com/Tiiffi/mcrcon/archive/refs/tags/v0.7.2.tar.gz

This should have downloaded us an ''mcrcon-0.7.2.tar.gz'' archive file. Let's verify that what we've downloaded matches what this guide expects:

sha256sum mcrcon-0.7.2.tar.gz

This should output the following; compare the first string of letter and numbers to yours, they must match:

1743b25a2d031b774e805f4011cb7d92010cb866e3b892f5dfc5b42080973270 mcrcon-0.7.2.tar.gz

Now let's unpack the ''.tar.gz'' archive and change into the directory it contains:

tar -xf mcrcon-0.7.2.tar.gz
cd mcrcon-0.7.2/

{{hint|'''Explanation:''' <code>tar</code> is the standard utility for creating, modifying, inspecting and unpacking tar archives, commonly referred to as "tarballs". The <code>-x</code> argument states that we want to e'''x'''tract, and the <code>-f</code> argument specifies that the next argument is the filename of the tarball we wish to operate on. <code>tar</code> will automatically infer the compression of the tarball, in this case gzip, and decompress it as it is unpacking.}}

In this directory (check with <code>ls -l</code>!) there should be some files, including a ''Makefile''. This allows us to now compile the source code and install the resulting binary:

make
sudo make install

{{hint|'''Explanation:''' A Makefile instructs the <code>make</code> command on how to build a project that uses it. In this case, it also contains a ''install'' target, which copies the resulting binary into ''/usr/local/bin'' and its manual page into the local prefix for manual pages. Since only the superuser can write to these directories, we need to run the install target with <code>sudo</code>.}}

If everything went well, we should now have the <code>mcrcon</code> command available, as well as its manual page with <code>man mcrcon</code>.

{{hint|'''For The Future:''' If you ever need to recompile <code>mcrcon</code>, for example, after a major version distribution upgrade years down the line that gets rid of ''libc.so.6'', you can run:

sudo make uninstall
make clean
make
sudo make install

}}

== Making The Server Accessible From Outside Your Home Network ==

{{note|'''TODO:'''
# Explain what a dynamic IP is, set up ddclient with DuckDNS, have a systemd timer for that.
# Explain what port forwarding is, why it's needed, and why this depends on your router. Warn not to forward port 22/tcp, only port 25565/tcp.}}

== Maintaining Your Server ==

{{note|'''TODO:'''
# Explain how to start, stop, restart the Minecraft server with systemctl.
# Explain how to access server logs with journalctl.
# Explain how to keep PaperMC updated (including changing the symlink).
# Explain apt update and apt upgrade. Recommend unattended-upgrades.
# Explain Debian major releases and to keep an eye out for them.
# Recommend htop to see how CPU and RAM usage is looking.
# Recommend some backup solutions; rsync to flash drive, short mention of borg/borgmatic over the network.
# Explain how to transfer files to/from server: sftp, rsync, winscp, etc.}}

== Security Advice ==

This section will give some general security advice on running your own server, and elaborates on some decisions this guide makes.

=== SSH Public Key Authentication ===

If you absolutely insist on opening up the SSH port to the public internet, you should use public key authentication and disable password authentication for SSH altogether.

This way, public key cryptography is used to authenticate, which is computationally extremely hard to break in this case. The password you encrypt your private key with never travels over the network.

To generate an SSH public/private key pair, run

ssh-keygen

on '''your client machine''', i.e. not the Quartz64 Model B.

Then copy the newly generated SSH public key over to the Quartz64 Model B with

ssh-copy-id <var>youruser</var>@<var>yourhost</var>.local

Try logging in with ssh now. It should prompt you for your key's password, rather than the user account's password.

If it works, you should then finally disable password authentication by editing ''/etc/ssh/sshd_config'' as the superuser and setting:

PasswordAuthentication no

Then, restart the ''sshd.service'' with <code>sudo systemctl restart sshd.service</code>.

Note that from this point on, if you want to log in from a different machine, you'll need to either copy your public/private keypair over or generate a new one there and edit ''~/.ssh/authorized_keys'' manually, or run <code>ssh-copy-id</code> with the <code>-i</code> argument pointing to that public key.

=== On Minecraft Server Modifications And Plugins ===

Please note that Minecraft server modifications or plugins run with the same access as your Minecraft server. While we tried our best in this guide to restrict the Minecraft server's access to the rest of the system, it can obviously still do bad things to our Minecraft world, our computational resources and our network. That's why, whenever you install a server-side modification or plugin, you should ask yourself these questions:

# Do you trust the website/service you are downloading the mod/plugin from to not be malicious?
# Do you trust the website/service you are downloading the mod/plugin from to have the latest version uploaded by the mod/plugin's author rather than an untrustworthy third party?
# Do you trust the mod/plugin author to not be malicious?
# Do you trust the mod/plugin author to have good security practices, as to not get their account compromised or development computer infected with malware?
# Do you trust the mod/plugin to not open up security vulnerabilities in your server?

Chances are the answers to some of these questions will be "no". In that case you have some leg work to do: research the site and users, double-check you're on the right domain, read the code for anything fishy, and if you're ever unsure, ask for a second opinion from somebody knowledgeable on the topics.

This is not unwarranted paranoia: Minecraft server modifications [https://github.com/dogboy21/serializationisbad have introduced security vulnerabilities before]. Well trusted people's accounts [https://github.com/fractureiser-investigation/fractureiser have been hijacked before, or their uploads unknowingly infected with malware]. And the way this happened? They themselves were downloading modifications from malicious users.

Please do note that all these issues generally do not apply to Minecraft Data Packs. While they are more limited than modifications or plugins that hook into the actual code, these limitations are good in the context of security.

=== Do Not Engage In Security By Obscurity ===

You may be tempted to not enable a whitelist because you think nobody is going to find your Minecraft server anyway. This is false. People and bots are constantly scanning the entire internet for open services. This includes Minecraft servers. If you do not have a whitelist, you will sooner or later get uninvited visitors.

Similarly, if you expose any service other than the Minecraft server to the internet through your router, expect that to be instantly discovered as well. Automated exploit scanners will then likely be hitting it regularly.

This sounds scary, but it's really not: if your system is up-to-date and follows best security practices, you generally won't have much to fear. It just means that you can't expose any insecurely configured service to the internet and expect nobody to find it.

=== Can't Be Bothered To Maintain It? Turn It Off ===

One of the biggest possible dangers to your home network's security is unwillingness to take responsibility. If you no longer want to maintain the server, turn the board off, unplug it, and delete the port forwarding rule in your router's web interface.

The majority of security breaches don't happen because somebody tries very hard to breach one target, but because a lot of people try very little to breach many targets. Chances are they will find a system somewhere that nobody feels responsible for anymore, and which hasn't been updated in 5 years, and runs a service of a version with a known vulnerability. Avoid being that system: if your Quartz64 Model B begins operating as part of a botnet due to your indifference, the rest of the internet will suffer.

=== Why Reboots Are Sometimes Recommended ===

Occasionally, your Linux kernel package (''linux-image-arm64'') will update. This is great! The kernel is the most basic part of the operating system, and responsible for enforcing fundamental privilege separation. Unfortunately, live-patching the running kernel (i.e. updating it in memory without requiring a reboot) is something that only enterprise-grade commercial Linux distributions like RedHat Enterprise Linux or SUSE Linux do. Since we're running Debian here and Debian doesn't have this feature, the only way to run the newly updated kernel is to reboot the system.

You can run <code>cat /var/run/reboot-required</code> to see if your Quartz64 Model B requires a reboot. It's worth noting that the Linux kernel development community does not distinguish regular bugs from security bugs, as many a "regular" bug could be a security bug in the right circumstances. However, Debian itself [https://www.debian.org/security/#DSAS publishes security advisories] when a Linux kernel update they ship fixes known potential security issues.

Whether or not you want to reboot for a specific kernel update is up to you. People run servers with hundreds of days of uptime (check with the command <code>uptime</code>) just fine; just because a potential security issue was fixed in the Linux kernel doesn't mean it'd be part of a realistic attack scenario on a specific system. In our case, the attack scenario we're most worried about is that somebody manages to breach the PaperMC Minecraft server, and then gains arbitrary code execution in its context, from which they will then likely attempt to attack the kernel to gain additional privileges. A second, much less likely attack scenario is that the Linux kernel would have a vulnerability in its network stack that would allow an attacker to remotely exploit it. Such vulnerabilities are exceedingly rare in Linux.

=== Why Not Docker: On Software Supply Chains And Understanding Your Stack ===

For the majority of this guide, self-declared DevOps EpicPoggers Awesomeninjas have probably been foaming at their mouth jumping at the opportunity to exclaim that one should just use Docker. This section serves as a soapbox to talk about the problems with that suggestion.

While a Docker container may be, well, contained, it pulls in an entire stacking doll of other images it is built upon. This means an entire operating system to support the application being run, minus a kernel.

This is great if you are the person writing the image manifests, know what your dependency requirements are, and track the entire software supply chain to ensure you always get the right versions for your stack, with all the latest vulnerabilities patched.

However, this is not how the vast majority of people use Docker. The overwhelming majority of Docker users simply pull some random person's image, run it, and thus make these assumptions:

# That the author of the image is not malicious. Malicious images [https://sysdig.com/blog/analysis-of-supply-chain-attacks-through-public-docker-images/ are widespread on Docker Hub].
# That the author of the image has good security practices in order to avoid publishing malicious images. We know account compromises will happen as Docker Hub seemingly does not require Two-Factor Authentication.
# That the author will update the images when critical security fixes in any of the things they depend on are fixed. A [https://dl.acm.org/doi/10.1145/3029806.3029832 2017 research paper] found that many images are hundreds of days old.
# That any of the things that image depends on, recursively, will also meet these three points.

For a single service/single node scenario, Docker complicates the software supply chain massively. Instead of getting most of our system from a source we already trust (Debian), we're now getting a whole second system from a myriad of sources opaquely compiled into one image.

Additionally, Docker complicates the following things:

* Knowing what version a specific runtime dependency is, and that all copies of this dependency on the entire system are patched against the latest vulnerability.
* Updating the container image and spinning up a new container based on it; this is not handled through your system's package manager.
* Persistent data; it's stored in Docker volumes, which may or may not be attached to containers, and you need to actively try to have them stored somewhere other than the default location.
* Service management; Docker reinvents service management in its own, arguably worse way.
* Networking; things are on a virtual network with Docker, which complicates firewall rules and other network configurations.
* Logging; Docker reinvents this too.

By not using a Docker container, but rather a locked down systemd service, we get the following benefits:

* All system software updates, including the Java Runtime, are handled by Debian, irrespective of the version of the Minecraft server we run.
* All of our services use the same system dependencies, and we can answer the question of "has <var>xyz</var> been patched?" by just looking at <code>apt</code>.
* We still get reasonably strong process isolation thanks to the various security sandboxing options our systemd service uses, despite not using Linux namespaces (containers).
* Our persistent data is where we expect it to be, owned by the user and group we expect it to be owned by.
* Our network is not burdened with virtual interfaces and forwarding rules.
* Our Minecraft server is tracked and dependency ordered by systemd's service management. It's automatically started on boot, and gracefully stopped on shutdown.
* Our Minecraft server's logs will show up in the system journal, and we can filter through them or correlate them with other sources just as with any other service reporting to the journal.

Container images built from manifests start to make sense when you are running complex sets of services scaled horizontally across a massive homogeneous cluster, where you want to rescale as needed and deploy new versions of your entire stack as immutable images that you can roll back easily. They also make some amount of sense in a case where you only have access to a very old userland (e.g. a stable enterprise Linux release) but need to run software requiring a myriad of dependencies that are either not packaged or not of a recent enough version in your distribution.

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

To hook up UART serial debug, connect your Woodpecker, ideally with a decent USB extension cord, to your computer's USB port. Make sure the yellow jumper is set to 3.3V.

Connect the GND pin of the Woodpecker to a GND pin of your Quartz64 Model B, which are coloured as black pins. A good one to use is pin number 6 (the one after the red pin 2 and pin 4), as it's right next to the other UART pins we'll need.

Next, hook up the Woodpecker's RXD pin to the Quartz64 Model B's pin number 8, which is next to (lengthwise down the row of pins) the aforementioned pin number 6, coloured in green.

Finally, hook up the Woodpecker's TXD pin to the QUartz64 Model B's pin number 10, which is down yet another pin in the same direction, also coloured in green.

{{note|'''TODO:''' Add a diagram showing the connections here.}}

==== Accessing The Serial Console On Windows ====

{{note|'''TODO:''' Add a guide on how to install, configure and use PuTTY}}

==== Accessing The Serial Console On Linux ====

{{note|'''TODO:''' Validate the serial settings here.}}
{{note|'''Warning:''' Some poorly written software, like <code>gpsd</code> or <code>brltty</code>, will randomly and happily claim and mess with any USB-to-serial adapters on the system, especially when you least want them to. Use <code>sudo lsof /dev/ttyUSB<var>n</var></code> to determine whether this is the case for you if you run into any trouble with the following steps.}}

First, list all the available USB-to-Serial adapters on your system:

ls /dev/ttyUSB*

If you only have one plugged in, this should probably only return <code>/dev/ttyUSB0</code>.

Next, you have some choice of serial terminal to use: <code>screen</code> (likely already installed), <code>minicom</code> and <code>picocom</code>.

For screen, (replacing <var>n</var> with the number of your serial adapter) use:

screen /dev/ttyUSB<var>n</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

For minicom, (replacing <var>n</var> with the number of your serial adapter) use:

minicom -D /dev/ttyUSB<var>n</var> -b 1500000 -8

You can quit minicom by hitting Ctrl+a, then hit q.

For picocom, (replacing <var>n</var> with the number of your serial adapter) use:

picocom /dev/ttyUSB<var>n</var> -b 1500000

You can quit picocom by hitting Ctrl+a, then hit Ctrl+q.

==== Accessing The Serial Console On macOS ====

{{note|'''TODO:''' Validate the serial settings here, and validate the device name.}}

Open up a terminal, then list all the available serial devices on your system:

ls /dev/tty.*

This will likely return something starting with <code>/dev/tty.usbserial-</code>.

Now we can open this serial port with <code>screen</code> as follows, replacing <var>foo</var> with the adapter name from the previous step:

screen /dev/tty.usbserial-<var>foo</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

==== Using The Serial Console ====

If you just hooked it up to a running system, you're unlikely to see any output. You will only be able to see messages from the point on when you've opened up your serial communication program.

If your board is doing the heartbeat pattern (i.e., it booted, but you're unable to log in over the network) you can hit Enter to (hopefully) make it show you a login prompt. If the login prompt is your first time communicating with the board, use username ''pleb'' and password ''pleb''. From then on, the serial terminal should work like any normal shell you'd have on the system, modulo some possible weirdness with special escape sequences making things a little more prone to drawing in broken ways.

If your board is not doing the heartbeat pattern, hit the reset button (small white button on side of board, the one closer towards the antenna mount) and you should be getting serial output from a fresh boot.

If you still don't get any output, make sure that you flashed the microSD card correctly, and make sure the TXD and RXD lines aren't the wrong way around. If you still don't get any output after that, your Quartz64 Model B may have defective level shifting transistors on the serial lines, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

=== Is My Ethernet Broken? ===

Pine Store has sold a number of boards where the ethernet PHY chip was seemingly broken. If your board exhibits the heartbeat LED pattern but never shows up on the network, either hook up a monitor and a keyboard or use your Woodpecker to hook up to serial (see [[#Connecting UART]]) and try to log in.

After logging in, type:

sudo dmesg | grep rk_gmac-dwmac

If the output contains any lines like

rk_gmac-dwmac fe010000.ethernet end0: __stmmac_open: Cannot attach to PHY (error: -22)

then your hardware is defective, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-14T10:20:07Z

CounterPillow:

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-11T18:05:41Z

CounterPillow:

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-11T14:49:53Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

{{note|'''Note:''' If you see a heartbeat pattern but the board never gets a DHCP lease, please follow the steps in [[#Is My Ethernet Broken?]].}}

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

== Setting Up The Network ==

{{note|'''TODO:''' Explain how to either use reserved DHCP leases or configure a static IP with NetworkManager, and how to set up a persistent firewall that allows ports 22/tcp and 25565/tcp.}}

== Formatting The NVMe Drive ==

{{note|'''TODO:''' Explain how to wipefs + fdisk + format the NVMe drive, make a mountpoint and put it in fstab.}}

== Setting Up The Minecraft Java Edition Server ==

{{note|'''TODO:'''
# Install build-essential and git, download https://github.com/Tiiffi/mcrcon and build and install it.
# Add a minecraft system user with a minecraft group that has write permissions to the minecraft directory on NVMe, add minecraft to supplemental groups for user.
# Install Java, download PaperMC to the Minecraft directory, symlink it to paper.jar, run it once, accept the EULA.
# Edit server.properties, enable rcon with a password, enable whitelist, edit motd and set difficulty.
# Add the systemd unit to /etc/systemd/system/, set it to auto-start, then start it.
# Add player to whitelist and ops through rcon.
# Connect to the server for the first time!}}

== Making The Server Accessible From Outside Your Home Network ==

{{note|'''TODO:'''
# Explain what a dynamic IP is, set up ddclient with DuckDNS, have a systemd timer for that.
# Explain what port forwarding is, why it's needed, and why this depends on your router. Warn not to forward port 22/tcp, only port 25565/tcp.}}

== Maintaining Your Server ==

{{note|'''TODO:'''
# Explain how to start, stop, restart the Minecraft server with systemctl.
# Explain how to access server logs with journalctl.
# Explain how to keep PaperMC updated (including changing the symlink).
# Explain apt update and apt upgrade. Recommend unattended-upgrades.
# Explain Debian major releases and to keep an eye out for them.
# Recommend htop to see how CPU and RAM usage is looking.
# Recommend some backup solutions; rsync to flash drive, short mention of borg/borgmatic over the network.
# Explain how to transfer files to/from server: sftp, rsync, winscp, etc.}}

== Security Advice ==

{{note|'''TODO:'''
* Using SSH pubkey auth and disabling password login.
* On the dangers of Minecraft server mods/plugins.
* Do not rely on obscurity in the age of whole IPv4 scanning.
* Not using it anymore and can't be bothered to maintain it? Turn it off.
* On kernel updates and why they need a reboot here.
* Why not Docker: on software supply chains and understanding how to maintain your setup.
}}

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

To hook up UART serial debug, connect your Woodpecker, ideally with a decent USB extension cord, to your computer's USB port. Make sure the yellow jumper is set to 3.3V.

Connect the GND pin of the Woodpecker to a GND pin of your Quartz64 Model B, which are coloured as black pins. A good one to use is pin number 6 (the one after the red pin 2 and pin 4), as it's right next to the other UART pins we'll need.

Next, hook up the Woodpecker's RXD pin to the Quartz64 Model B's pin number 8, which is next to (lengthwise down the row of pins) the aforementioned pin number 6, coloured in green.

Finally, hook up the Woodpecker's TXD pin to the QUartz64 Model B's pin number 10, which is down yet another pin in the same direction, also coloured in green.

{{note|'''TODO:''' Add a diagram showing the connections here.}}

==== Accessing The Serial Console On Windows ====

{{note|'''TODO:''' Add a guide on how to install, configure and use PuTTY}}

==== Accessing The Serial Console On Linux ====

{{note|'''TODO:''' Validate the serial settings here.}}
{{note|'''Warning:''' Some poorly written software, like <code>gpsd</code> or <code>brltty</code>, will randomly and happily claim and mess with any USB-to-serial adapters on the system, especially when you least want them to. Use <code>sudo lsof /dev/ttyUSB<var>n</var></code> to determine whether this is the case for you if you run into any trouble with the following steps.}}

First, list all the available USB-to-Serial adapters on your system:

ls /dev/ttyUSB*

If you only have one plugged in, this should probably only return <code>/dev/ttyUSB0</code>.

Next, you have some choice of serial terminal to use: <code>screen</code> (likely already installed), <code>minicom</code> and <code>picocom</code>.

For screen, (replacing <var>n</var> with the number of your serial adapter) use:

screen /dev/ttyUSB<var>n</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

For minicom, (replacing <var>n</var> with the number of your serial adapter) use:

minicom -D /dev/ttyUSB<var>n</var> -b 1500000 -8

You can quit minicom by hitting Ctrl+a, then hit q.

For picocom, (replacing <var>n</var> with the number of your serial adapter) use:

picocom /dev/ttyUSB<var>n</var> -b 1500000

You can quit picocom by hitting Ctrl+a, then hit Ctrl+q.

==== Accessing The Serial Console On macOS ====

{{note|'''TODO:''' Validate the serial settings here, and validate the device name.}}

Open up a terminal, then list all the available serial devices on your system:

ls /dev/tty.*

This will likely return something starting with <code>/dev/tty.usbserial-</code>.

Now we can open this serial port with <code>screen</code> as follows, replacing <var>foo</var> with the adapter name from the previous step:

screen /dev/tty.usbserial-<var>foo</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

==== Using The Serial Console ====

If you just hooked it up to a running system, you're unlikely to see any output. You will only be able to see messages from the point on when you've opened up your serial communication program.

If your board is doing the heartbeat pattern (i.e., it booted, but you're unable to log in over the network) you can hit Enter to (hopefully) make it show you a login prompt. If the login prompt is your first time communicating with the board, use username ''pleb'' and password ''pleb''. From then on, the serial terminal should work like any normal shell you'd have on the system, modulo some possible weirdness with special escape sequences making things a little more prone to drawing in broken ways.

If your board is not doing the heartbeat pattern, hit the reset button (small white button on side of board, the one closer towards the antenna mount) and you should be getting serial output from a fresh boot.

If you still don't get any output, make sure that you flashed the microSD card correctly, and make sure the TXD and RXD lines aren't the wrong way around. If you still don't get any output after that, your Quartz64 Model B may have defective level shifting transistors on the serial lines, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

=== Is My Ethernet Broken? ===

Pine Store has sold a number of boards where the ethernet PHY chip was seemingly broken. If your board exhibits the heartbeat LED pattern but never shows up on the network, either hook up a monitor and a keyboard or use your Woodpecker to hook up to serial (see [[#Connecting UART]]) and try to log in.

After logging in, type:

sudo dmesg | grep rk_gmac-dwmac

If the output contains any lines like

rk_gmac-dwmac fe010000.ethernet end0: __stmmac_open: Cannot attach to PHY (error: -22)

then your hardware is defective, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-11T13:04:27Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

{{note|'''Note:''' If you see a heartbeat pattern but the board never gets a DHCP lease, please follow the steps in [[#Is My Ethernet Broken?]].}}

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

To hook up UART serial debug, connect your Woodpecker, ideally with a decent USB extension cord, to your computer's USB port. Make sure the yellow jumper is set to 3.3V.

Connect the GND pin of the Woodpecker to a GND pin of your Quartz64 Model B, which are coloured as black pins. A good one to use is pin number 6 (the one after the red pin 2 and pin 4), as it's right next to the other UART pins we'll need.

Next, hook up the Woodpecker's RXD pin to the Quartz64 Model B's pin number 8, which is next to (lengthwise down the row of pins) the aforementioned pin number 6, coloured in green.

Finally, hook up the Woodpecker's TXD pin to the QUartz64 Model B's pin number 10, which is down yet another pin in the same direction, also coloured in green.

{{note|'''TODO:''' Add a diagram showing the connections here.}}

==== Accessing The Serial Console On Windows ====

{{note|'''TODO:''' Add a guide on how to install, configure and use PuTTY}}

==== Accessing The Serial Console On Linux ====

{{note|'''TODO:''' Validate the serial settings here.}}
{{note|'''Warning:''' Some poorly written software, like <code>gpsd</code> or <code>brltty</code>, will randomly and happily claim and mess with any USB-to-serial adapters on the system, especially when you least want them to. Use <code>sudo lsof /dev/ttyUSB<var>n</var></code> to determine whether this is the case for you if you run into any trouble with the following steps.}}

First, list all the available USB-to-Serial adapters on your system:

ls /dev/ttyUSB*

If you only have one plugged in, this should probably only return <code>/dev/ttyUSB0</code>.

Next, you have some choice of serial terminal to use: <code>screen</code> (likely already installed), <code>minicom</code> and <code>picocom</code>.

For screen, (replacing <var>n</var> with the number of your serial adapter) use:

screen /dev/ttyUSB<var>n</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

For minicom, (replacing <var>n</var> with the number of your serial adapter) use:

minicom -D /dev/ttyUSB<var>n</var> -b 1500000 -8

You can quit minicom by hitting Ctrl+a, then hit q.

For picocom, (replacing <var>n</var> with the number of your serial adapter) use:

picocom /dev/ttyUSB<var>n</var> -b 1500000

You can quit picocom by hitting Ctrl+a, then hit Ctrl+q.

==== Accessing The Serial Console On macOS ====

{{note|'''TODO:''' Validate the serial settings here, and validate the device name.}}

Open up a terminal, then list all the available serial devices on your system:

ls /dev/tty.*

This will likely return something starting with <code>/dev/tty.usbserial-</code>.

Now we can open this serial port with <code>screen</code> as follows, replacing <var>foo</var> with the adapter name from the previous step:

screen /dev/tty.usbserial-<var>foo</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backslash (<code>\</code>) and confirm with y.

==== Using The Serial Console ====

If you just hooked it up to a running system, you're unlikely to see any output. You will only be able to see messages from the point on when you've opened up your serial communication program.

If your board is doing the heartbeat pattern (i.e., it booted, but you're unable to log in over the network) you can hit Enter to (hopefully) make it show you a login prompt. If the login prompt is your first time communicating with the board, use username ''pleb'' and password ''pleb''. From then on, the serial terminal should work like any normal shell you'd have on the system, modulo some possible weirdness with special escape sequences making things a little more prone to drawing in broken ways.

If your board is not doing the heartbeat pattern, hit the reset button (small white button on side of board, the one closer towards the antenna mount) and you should be getting serial output from a fresh boot.

If you still don't get any output, make sure that you flashed the microSD card correctly, and make sure the TXD and RXD lines aren't the wrong way around. If you still don't get any output after that, your Quartz64 Model B may have defective level shifting transistors on the serial lines, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

=== Is My Ethernet Broken? ===

Pine Store has sold a number of boards where the ethernet PHY chip was seemingly broken. If your board exhibits the heartbeat LED pattern but never shows up on the network, either hook up a monitor and a keyboard or use your Woodpecker to hook up to serial (see [[#Connecting UART]]) and try to log in.

After logging in, type:

sudo dmesg | grep rk_gmac-dwmac

If the output contains any lines like

rk_gmac-dwmac fe010000.ethernet end0: __stmmac_open: Cannot attach to PHY (error: -22)

then your hardware is defective, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-11T12:54:57Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

{{note|'''Note:''' If you see a heartbeat pattern but the board never gets a DHCP lease, please follow the steps in [[#Is My Ethernet Broken?]].}}

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

To hook up UART serial debug, connect your Woodpecker, ideally with a decent USB extension cord, to your computer's USB port. Make sure the yellow jumper is set to 3.3V.

Connect the GND pin of the Woodpecker to a GND pin of your Quartz64 Model B, which are coloured as black pins. A good one to use is pin number 6 (the one after the red pin 2 and pin 4), as it's right next to the other UART pins we'll need.

Next, hook up the Woodpecker's RXD pin to the Quartz64 Model B's pin number 8, which is next to (lengthwise down the row of pins) the aforementioned pin number 6, coloured in green.

Finally, hook up the Woodpecker's TXD pin to the QUartz64 Model B's pin number 10, which is down yet another pin in the same direction, also coloured in green.

{{note|'''TODO:''' Add a diagram showing the connections here.}}

==== Accessing The Serial Console On Windows ====

{{note|'''TODO:''' Add a guide on how to install, configure and use PuTTY}}

==== Accessing The Serial Console On Linux ====

{{note|'''TODO:''' Validate the serial settings here.}}
{{note|'''Warning:''' Some poorly written software, like <code>gpsd</code> or <code>brltty</code>, will randomly and happily claim and mess with any USB-to-serial adapters on the system, especially when you least want them to. Use <code>sudo lsof /dev/ttyUSB<var>n</var></code> to determine whether this is the case for you if you run into any trouble with the following steps.}}

First, list all the available USB-to-Serial adapters on your system:

ls /dev/ttyUSB*

If you only have one plugged in, this should probably only return <code>/dev/ttyUSB0</code>.

Next, you have some choice of serial terminal to use: <code>screen</code> (likely already installed), <code>minicom</code> and <code>picocom</code>.

For screen, (replacing <var>n</var> with the number of your serial adapter) use:

screen /dev/ttyUSB<var>n</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backspace (<code>\</code>) and confirm with y.

For minicom, (replacing <var>n</var> with the number of your serial adapter) use:

minicom -D /dev/ttyUSB<var>n</var> -b 1500000 -8

You can quit minicom by hitting Ctrl+a, then hit q.

For picocom, (replacing <var>n</var> with the number of your serial adapter) use:

picocom /dev/ttyUSB<var>n</var> -b 1500000

You can quit picocom by hitting Ctrl+a, then hit Ctrl+q.

==== Accessing The Serial Console On macOS ====

{{note|'''TODO:''' Validate the serial settings here, and validate the device name.}}

Open up a terminal, then list all the available serial devices on your system:

ls /dev/tty.*

This will likely return something starting with <code>/dev/tty.usbserial-</code>.

Now we can open this serial port with <code>screen</code> as follows, replacing <var>foo</var> with the adapter name from the previous step:

screen /dev/tty.usbserial-<var>foo</var> 1500000 cs8 -cstop

You can quit screen by hitting Ctrl+a, then hit backspace (<code>\</code>) and confirm with y.

==== Using The Serial Console ====

If you just hooked it up to a running system, you're unlikely to see any output. You will only be able to see messages from the point on when you've opened up your serial communication program.

If your board is doing the heartbeat pattern (i.e., it booted, but you're unable to log in over the network) you can hit Enter to (hopefully) make it show you a login prompt. If the login prompt is your first time communicating with the board, use username ''pleb'' and password ''pleb''. From then on, the serial terminal should work like any normal shell you'd have on the system, modulo some possible weirdness with special escape sequences making things a little more prone to drawing in broken ways.

If your board is not doing the heartbeat pattern, hit the reset button (small white button on side of board, the one closer towards the antenna mount) and you should be getting serial output from a fresh boot.

If you still don't get any output, make sure that you flashed the microSD card correctly, and make sure the TXD and RXD lines aren't the wrong way around. If you still don't get any output after that, your Quartz64 Model B may have defective level shifting transistors on the serial lines, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

=== Is My Ethernet Broken? ===

Pine Store has sold a number of boards where the ethernet PHY chip was seemingly broken. If your board exhibits the heartbeat LED pattern but never shows up on the network, either hook up a monitor and a keyboard or use your Woodpecker to hook up to serial (see [[#Connecting UART]]) and try to log in.

After logging in, type:

sudo dmesg | grep rk_gmac-dwmac

If the output contains any lines like

rk_gmac-dwmac fe010000.ethernet end0: __stmmac_open: Cannot attach to PHY (error: -22)

then your hardware is defective, and you should open [https://support.pine64.org/ a ticket with Pine Store] immediately and ask for a replacement or refund.

Quartz64

2023-09-10T06:38:55Z

CounterPillow: /* No GPU Acceleration with Debian "Bullseye" Userland */ Bookworm is no longer Testing

[[File:Quartz64modelb.png|400px|thumb|right|The Quartz64 Model B]]

The '''Quartz64''' is the most recent Single Board Computer offering from PINE64, with Model A initially released in June of 2021 and Model B in May of 2022. It is powered by a Rockchip RK3566 Quad-Core ARM Cortex A55 64-Bit Processor with a MALI G-52 GPU.

Key features include a PCIe x4 open ended slot (model A) or m.2 (model B) using one Gen2 lane electrically, and the use of LPDDR4 RAM.

The Quartz64 has three LPDDR4 system memory options: 2GB, 4GB or 8GB. For booting, there is an eMMC module socket (supporting up to 128GB) and microSD slot, as well as a footprint to solder on an SPI flash chip. The board is equipped with HDMI, 1x USB 3.0 type A Host, 3x USB 2.0 Host, Gigabit Ethernet, SATA (model A), GPIO Bus, MiPi DSI interface, e-ink interface (model A), eDP interface (model A), touch Panel interface (model A), MiPi CSI interface, as well as many other device interfaces such as UART, SPI, I2C, for makers to integrate with sensors and other peripherals. Many different Operating Systems (OS) are freely available from the open source community, such as Linux (Ubuntu, Debian, Arch), BSD, and Android.

== Software releases ==

Under [[Quartz64 Software Releases]] you will find a complete list of currently supported operating system images, which work with the Quartz64, as well as other related software.

== Getting started ==

=== Flashing the device ===

Natively the board only supports booting the platform firmware from SPI, the eMMC or a microSD card, see [[#Boot order|boot order]]. The platform firmware loaded from there (U-Boot, EDK2, ...) may then allow loading kernels from additional storage mediums or even the network, and they will have their own boot order.

The board can be booted by flashing your chosen operating system to a microSD card using another device and inserting the microSD card into the Quartz64, see the article [[Getting started]]. Flashing the eMMC is possible by booting an operating system from the microSD card and overwriting the eMMC from within the booted operating system, or by using [https://pine64.com/product/usb-adapter-for-emmc-module/ the USB eMMC adapter].

=== Boot order ===

The hardware boot order of the Quartz64 is:

# SPI NOR flash
# SPI NAND flash
# eMMC
# microSD card

== SoC and Memory Specifications ==

[[File:RK3566_icon.png|right]]

* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]

=== CPU Architecture ===

* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache
* [https://developer.arm.com/ip-products/security-ip/trustzone TrustZone] technology support
* [https://www.cnx-software.com/2020/12/01/rockchip-rk3568-processor-to-power-edge-computing-and-nvr-applications 22nm process, believed to be FD-SOI]

=== GPU (Graphics Processing Unit) Capabilities ===

* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== NPU (Neural Processing Unit) Capabilities ===

* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===

* RAM Memory Variants: 2GB (SOQuartz only), 4GB, 8GB LPDDR4.

=== Network ===

* 10/100/1000Mbps Ethernet
** Easily sustains >910 Mbit/s in a <code>--bidir</code> (i.e. sending and receiving at the same time) iperf3 TCP test.
* Wi-Fi 802.11 b/g/n/ac with Bluetooth 5.0 (optional on model A, built in on model B)

=== Storage ===

* microSD - bootable, supports SDHC and SDXC, storage up to 2TB
* USB
** Model A: 2 USB 2.0 host ports, 1 USB 2.0 OTG port, 1 USB 3.0 host port
** Model B: 1 USB 2.0 host port, 1 USB 2.0 OTG port, 1 USB 3.0 host port
* one native SATA 3.0 6Gb/s Port (only on model A, shared with USB 3.0 host port) (removed in newer revisions due to electrical signalling issues it caused)
* optional eMMC module from 8GB up to 128GB
* 64 Mbit (8 MByte) SPI flash (Model B only), part number '''25Q64DWZPIG''' in the schematic

==== eMMC Speeds ====

On a 64 GB eMMC module:

$ sudo hdparm -tT /dev/mmcblk1

/dev/mmcblk1:
Timing cached reads: 2368 MB in 2.00 seconds = 1184.46 MB/sec
Timing buffered disk reads: 452 MB in 3.01 seconds = 149.98 MB/sec

=== Expansion Ports ===
* HDMI
* eDP - 4 lanes of 2.7Gbps, up to 2560x1600@60Hz (only on model A)
* DSI - Display Serial Interface, 4 lanes MiPi, up to 1440P on model A, 2 lanes MiPi, up to 1080p on model B
* CSI - CMOS Camera Interface, 4 lanes MiPi up to 8 mega pixel on model A, 2 lanes MiPi up to 5 mega pixel on model B
* TP - Touch Panel Port, SPI with interrupt on model A
* RTC - Real Time Clock Battery Connector
* VBAT - Lithium Battery Connector with temperature sensor input on model A
* Wi-Fi/BT Module Header - SDIO 3.0 and UART on model A, built-in Wi-Fi/BT Module on model B
* 2x20 pins "Pi2" GPIO Header on model B, 2x10 pins GPO header on model A
* PCIe x4 open ended slot on model A, m.2 slot on model B, one Gen2 lane due to SoC constraints
** On Model A, the slot provides 10W of power for the 3.3V supply and however much power your 12V input power supply provides on the 12V supply

The PCIe implementation on the RK3566 is much more compatible with a wide range of devices compared to the one on the RK3399 used on the ROCKPro64. This means a lot more devices should work (excluding dGPUs due to a lack of cache snooping ability).

==== Combo PHYs ====

[[File:rk3566 phy.png|400px]]

Several of the I/O options on the RK3566 used in the Quartz64 are using the same I/O lines, meaning that they cannot be used at the same time. The above diagram illustrates how they are connected.

In particular, USB 3.0 and the SATA connector on the board are mutually exclusive, and the PCI-e 2.0 lane can be reconfigured into a second SATA port, though an adapter cable needs to be fashioned for this to be useful.

=== GPIO Pins (Quartz64 Model A) ===

Attention! GPIOs are 3.3V!

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SDA_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SCL_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| CPU_REFCLK_OUT
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX_M0_DEBUG
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX_M0_DEBUG
|-
| style="text-align:right;"| SPI1_MOSI_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| UART0_TX a
|-
| style="text-align:right;"| SPI1_MISO_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| UART0_RX a
|-
| style="text-align:right;"| SPI1_CLK_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GND
|-
| style="text-align:right;"| SPI1_CS0_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 17
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| SPDIF_OUT c
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| 3.3V
|}

==== Notes ====
<ol style="list-style-type:lower-alpha">

<li>can be a PWM pin</li>

<li>pulled high to 3.3V through 2.2kOhm resistor</li>

<li>low-pass filtered with cutoff of 220 MHz</li>

</ol>

Source: Page 28 of [[File:Quartz64_model-A_schematic_v1.0_20201215.pdf|the board schematics]].

=== GPIO Pins (Quartz64 Model B) ===

Attention! GPIOs are 3.3V!

Interesting alternate pin configurations are listed in [brackets].

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 1
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SDA_M0]'' GPIO1_A0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SCL_M0]'' GPIO1_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_C4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX
|-
| style="text-align:right;"| ''[SPI1_CS0_M1]'' GPIO3_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| GPIO3_A3_3V3 ''[I2S3_SCLK_M0]''
|-
| style="text-align:right;"| ''[I2S3_MCLK_M0]'' GPIO3_A2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GPIO3_B1_3V3
|-
| style="text-align:right;"| 3.3V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 17
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| GPIO3_B2_3V3
|-
| style="text-align:right;"| GPIO4_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO4_C5_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 21
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 22
| style="text-align:left;"| GPIO3_C1_3V3 ''[SPI1_MOSI_M1]''
|-
| style="text-align:right;"| GPIO4_C2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 23
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 24
| style="text-align:left;"| GPIO4_C6_3V3
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 25
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 26
| style="text-align:left;"| GPIO4_D1_3V3
|-
| style="text-align:right;"| I2C4_SDA_M0
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 27
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 28
| style="text-align:left;"| I2C4_SCL_M0
|-
| style="text-align:right;"| GPIO3_B3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 29
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 30
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 31
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 32
| style="text-align:left;"| GPIO3_C2_3V3 ''[SPI1_MISO_M1]''
|-
| style="text-align:right;"| ''[SPI1_CLK_M1]'' GPIO3_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 33
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 34
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[I2S3_LRCK_M0]'' GPIO3_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 35
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 36
| style="text-align:left;"| GPIO3_A7_3V3
|-
| style="text-align:right;"| ''[SPDIF_TX_M0]'' GPIO1_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 37
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 38
| style="text-align:left;"| GPIO3_A6_3V3 ''[I2S3_SDI_M0]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 39
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 40
| style="text-align:left;"| GPIO3_A5_3V3 ''[I2S3_SDO_M0]''
|}

Source: Page 24 of [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf the board schematics].

== Quartz64 Board Information, Schematics, and Certifications ==

=== Model "A" ===

Model "A" Baseboard Dimensions: 133mm x 80mm x 19mm

Input Power: DC 12V @ 3A 5.5mmOD/2.1mmID center-positive Barrel DC Jack connector

Quartz64 Model "A" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_schematic_v2.0_20210427.pdf Quartz64 Model "A" SBC Schematic ver 2.0 20210427 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_V2.0_connector_placement.pdf Quartz64 Model "A" SBC PCB Connector placement PDF file]

Certifications:

* Disclaimer: Please note that PINE64 SBC is not a "final" product and in general certification is not necessary. However, PINE64 still submit the SBC for FCC and CE certification and obtain the certificates to proof that SBC board is capable on passing the testing. Please note a final commercial product needs to performs its owns testing and obtains its owns certificates.
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20CE%20certification-S21051101701001.pdf Quartz64 model-A CE Certificate]
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20FCC%20certification-S21051101702001.pdf Quartz64 model-A FCC Certificate]

=== Model "B" ===

Model "B" Baseboard Dimensions: 85mm x 56mm x 18.8mm

Input Power: DC 5V @ 3A 3.5mmOD/1.35mmID center-positive Barrel DC Jack connector

Quartz64 Model "B" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf Quartz64 Model "B" SBC Schematic ver 1.3 20220124 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_PCB_Components_Placement-V1.2_20211014.pdf Quartz64 Model "B" SBC PCB Connector placement PDF file]
* Please note that v1.2 and V1.3 schematic and component placement are identical, just some component value changed.
* Note: Model B uses a Molex PicoBlade compatible connector for the RTC battery. The Pine64 Backup Battery Holders come with a JST PH type connector. To use the Pine64 RTC Backup Battery Holder, the connector on the battery holder will need to be modified with a PicoBlade type connector.

== Datasheets for Components and Peripherals ==

Rockchip RK3566 SoC information:
* [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, already got release permission from Rockchip]
* [https://opensource.rock-chips.com/images/2/26/Rockchip_RK3568_TRM_Part1_V1.3-20220930P.PDF Rockchip RK3566 and RK3568 TRM (Technical Reference Manual)]

Rockchip PMU (Power Management Unit) Information:
* [https://www.rockchip.fr/RK817%20datasheet%20V1.01.pdf Rockchip RK817 ver 1.01 datasheet for Quartz64 model A]
* [https://www.rockchip.fr/RK809%20datasheet%20V1.01.pdf Rockchip RK809 ver 1.01 datasheet for Quartz64 model B and SOQuartz]

LPDDR4 (200 Balls) SDRAM:
* [https://files.pine64.org/doc/datasheet/rockpro64/SM512M32Z01MD2BNP(200BALL).pdf Micron LPDDR4 Mobile LPDDR4 Datasheet]

eMMC information:
* [https://files.pine64.org/doc/rock64/PINE64_eMMC_Module_20170719.pdf PINE64 eMMC module schematic]
* [https://files.pine64.org/doc/rock64/usb%20emmc%20module%20adapter%20v2.pdf PINE64 USB adapter for eMMC module V2 schematic]
* [https://files.pine64.org/doc/rock64/USB%20adapter%20for%20eMMC%20module%20PCB.tar PINE64 USB adapter for eMMC module PCB in JPEG]
* [https://files.pine64.org/doc/datasheet/pine64/E-00517%20FORESEE_eMMC_NCEMAM8B-16G%20SPEC.pdf 16GB Foresee eMMC Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/SDINADF4-16-128GB-H%20data%20sheet%20v1.13.pdf 32GB/64GB/128GB SanDisk eMMC Datasheet]

SPI NOR Flash information:
* [https://files.pine64.org/doc/datasheet/pine64/w25q128jv%20spi%20revc%2011162016.pdf WinBond 128Mb SPI Flash Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/GD25Q128C-Rev2.5.pdf GigaDevice 128Mb SPI Flash Datasheet]

E-ink Panel information:
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-754-V3_ES103TC1%20Specification%20V3.0(Signed)-20190702.pdf Eink 10.3" 1872x1404 ES103TC1 Flex Panel Specification]
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-828-V1_ED103TC2%20Formal%20Spec%20V1.0_20190514.pdf Eink 10.3" 1872x1404 ES103TC1 Glass Panel Specification]
* [https://files.pine64.org/doc/datasheet/PineNote/TI%20PMU-TPS651851.pdf TPS65185x PMIC for E-Ink Enabled Electronic Paper Display Datasheet]

LCD Touch Screen Panel information:
* [https://files.pine64.org/doc/datasheet/pine64/FY07024DI26A30-D_feiyang_LCD_panel.pdf 7.0" 1024x600 TFT-LCD Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/HK70DR2459-PG-V01.pdf Touch Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/GT911%20Capacitive%20Touch%20Controller%20Datasheet.pdf GOODiX GT911 5-Point Capacitive Touch Controller Datasheet]

Ethernet PHY information:
* [https://files.pine64.org/doc/datasheet/pine64/rtl8211e(g)-vb(vl)-cg_datasheet_1.6.pdf Realtek RTL8211 10/100/1000M Ethernet Transceiver]

Wi-Fi/BT module info:
* [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC Wi-Fi + Bluetooth5.0 Datasheet]

IR LED:
* [https://media.digikey.com/pdf/Data%20Sheets/Everlight%20PDFs/IRM-36xx_Series.pdf IRM-3638 Datasheet]

Enclosure information:
* [https://files.pine64.org/doc/datasheet/case/playbox_enclosure_20160426.stp Playbox Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/ABS_enclosure_20160426.stp ABS Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/pine64%20Die%20Cast%20casing-final.jpg Outdoor Aluminum Cast Dust-proof IP67 Enclosure Drawing]
* [https://www.printables.com/model/269572-pine-quartz-64-a-full-case 3D Printable Enclosure for Model A]
* [https://www.printables.com/model/269575-pine-quartz-64-a-open-frame Open Frame for Model A]

Connector information:
* [https://files.pine64.org/doc/datasheet/pine64/ePH.pdf 2.0mm PH Type connector specification use in Lithium Battery (VBAT) port (Model A)]
* [https://www.molex.com/pdm_docs/sd/533980271_sd.pdf 1.25mm Picoblade Type connector specification used in RTC Battery port (Model B)]
* [https://files.pine64.org/doc/datasheet/pine64/0.5FPC%20Front%20Open%20Connector%20H=1.5.pdf 0.5mm Pitch cover type FPC connector specification use in DSI port, TP port and CSI port]

== Development efforts ==

{{SeeMainArticle|Quartz64 Development}}

Information and resources of the ongoing development effort for the Quartz64 can be found on the [[Quartz64 Development]] page, where the current status of various board functions can be found, and whether they have landed in upstream.

* [https://gitlab.com/pine64-org/quartz-bsp Quartz64 BSP Gitlab Page]

== Enclosures ==

Note: Please expand this section with more cases known to work.

=== Model "A" ===

All enclosures that fit the ROCKPro64 should fit the Quartz64 Model "A", as the I/O has been laid out the same on purpose.

* [[Model A Acrylic Open Enclosure]] - but see the troubleshooting section below.
* [[Quartz64 Premium Aluminium Case|RockPro64 Premium Aluminium Case]]
* [[ROCKPro64#3D printable ITX mounting brackets]] (Not an enclosure but allows to mount the board in an ATX/ITX case)

=== Model "B" ===

* [[Model B Acrylic Open Enclosure]]
* the ROCK64 aluminium enclosure '''does not''' work, as the DC input jack is placed differently

== Troubleshooting ==

=== Stability/Boot Issues With Missing Battery Shunt ===

If there is no battery plugged into the board, the jumper labelled "ON/OFF_BATT" must be in place. If this is set wrong, stability issues such as failures to boot will occur. '''This affects model A only'''

=== No Ethernet Connectivity ===

Make sure the kernel is built with <code>CONFIG_MOTORCOMM_PHY</code> set to <code>y</code>. Building it as a module (<code>m</code>) and then relying on module auto-loading is unlikely to work, because if the generic PHY driver is built in it will bind to the PHY first, unless you include the motorcomm module in your initramfs.

Note: Starting with [https://salsa.debian.org/kernel-team/linux/-/merge_requests/551 Debian's <code>6.1~rc3-1~exp1</code> kernel] the module is included, but set to <code>m</code> and I (Diederik) have verified that it gets included in the initramfs and '''works''' on Model-A and Model-B with the [[Quartz64#Plebian]] images.

=== "Model A" Acrylic Case Doesn't Fit ===

The Quartz64 does not really fit onto the bottom plate of the [[Model A Acrylic Open Enclosure]]. This is because the "Mic" connector at the bottom of the board interferes with one of the posts. A workaround is to find out which post that is (you have a 50% chance of guessing it right, accounting for rotating the board) and then filing away the corner of the post pointing inwards by a few millimeters.

[[File:Quartz64-audio-jack-spacer-issue.jpg|400px]]

An alternate solution may be to place plastic spacers with a smaller outer diameter in between the acrylic bottom plate posts and the SBC board.

=== No GPU Acceleration with Debian "Bullseye" Userland ===

Debian Bullseye ships a Mesa version that is too old to contain the required patches for the RK356x SoC's GPU. Upgrade to Bookworm.

=== Wireless Connectivity Doesn't Work ===

ROCKPro64 wireless module may have CYW43455 or CYW43456 chips on board (not sure if this is the same for Quartz64 model B). Both chips are supported by <code>brcmfmac</code> Wi-Fi driver and <code>btbcm</code> Bluetooth driver.

For CYW43455 drivers attempt to load <code>/lib/firmware/brcm/brcmfmac43455-sdio.bin</code> for Wi-Fi and <code>/lib/firmware/brcm/BCM4345C0.hcd</code> for Bluetooth. Corresponding firmware files for CYW43456 are <code>/lib/firmware/brcm/brcmfmac43456-sdio.bin</code> and <code>/lib/firmware/brcm/BCM4345C5.hcd</code>.

On Manjaro firmware files for both Bluetooth and Wi-Fi on CYW43456 on are provided by <code>ap6256-firmware</code> package (<code>pacman -S ap6256-firmware</code>).

However for CYW43455 wi-fi firmware is in the <code>linux-firmware</code> package and bluetooth is in the <code>firmware-raspberrypi</code> (<code>pacman -S linux-firmware firmware-raspberrypi</code>). <code>linux-firmware</code> package is missing device specific symlinks for quartz64-a. To create them execute:

# ln -s brcmfmac43455-sdio.bin /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.bin
# ln -s brcmfmac43455-sdio.AW-CM256SM.txt /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.txt

As of 2022-10-19 device tree in mainline kernel for Quartz64 model A has wrong configuration for the Bluetooth driver. [https://patchwork.kernel.org/project/linux-rockchip/patch/20220926125350.64783-1-leo@nabam.net/ Patch] is submitted to the LKML and accepted and included upstream in 6.1-rc7. It's possible to modify dtb file provided by the current kernel using device tree compiler to enable Bluetooth or perform <code>make dtbs</code> in the patched kernel tree to get updated dtb file (<code>arch/arm64/boot/dts/rockchip/rk3566-quartz64-a.dtb</code>). Issue manifests itself with following errors in `dmesg`:

command 0x0c03 tx timeout
Bluetooth: hci0: BCM: Reset failed (-110)

== How-To ==

=== Connect Debug UART ===

The easiest way to get debug output is to connect a 3.3V 1.5mbaud capable UART adapter to the board.

To connect it, connect the ground lead to pin 6, and the RX/TX leads to pins 8 and 10 (consider swapping them if you get no output, things are often mislabeled). These pins are "UART2" in the above GPIO table.

Open a serial terminal at 1500000 bauds, e.g.

$ picocom -b 1500000 /dev/ttyUSB0

=== Disable Heartbeat LED (Linux) ===

The flashing LED is called the "heartbeat LED", it blinks in a heart rhythm like fashion once the kernel is running. To disable it, you can run

# echo none > /sys/class/leds/user-led/trigger

On model A LED device is called "diy-led", not "user-led".

On a system with systemd, you can do this as soon as the system is ready to be logged in with a systemd unit like this:

[Unit]
Description=Turn off heartbeat LED
Wants=multi-user.target
After=multi-user.target

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
ExecStart=sh -c 'echo none > /sys/class/leds/user-led/trigger'

Place it in ''/etc/systemd/system/user-led.service'', and run

# systemctl daemon-reload
# systemctl enable user-led.service

Upon rebooting, you will now notice that the heartbeat LED will blink during boot-up, but stops blinking as soon as the multi-user target is reached (i.e. the user can log in).

=== SATA on model A ===

On model A USB 3.0 and SATA ports are using the same I/O line and can't be used simultaneously. By default USB 3.0 is enabled in Linux device tree and SATA is disabled. FDT modifications are required to turn SATA on.

Following script is tested on Manjaro but should work on the other distributions with minimal changes. Device tree compiler package usually provides fdtput command (on Manjaro run: <code>pacman -S dtc</code>)

# cp /boot/dtbs/rockchip/rk3566-quartz64-a.dtb /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /usb@fd000000 status disabled
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /sata@fc400000 status okay
# sed -i 's#^FDT /dtbs/rockchip/rk3566-quartz64-a.dtb$#FDT /dtbs/rockchip/rk3566-quartz64-a-sata.dtb#' /boot/extlinux/extlinux.conf
# systemctl reboot

=== Using a PCF8574 on Model A ===

See [[Quartz64 Model A using a PCF8574]].

=== Using a battery on Model A ===

See [[Quartz64 Model A Using a battery]].

=== Connecting a MIPI-DSI display ===

See [[Quartz64 connecting a MIPI-DSI display]].

=== Building Mainline U-Boot ===

See [[Quartz64 Building U-Boot]].

== Frequently Asked Questions ==

=== Do I Need A Fan/What Heatsink Do I Need? ===

You don't need a fan. The [https://pine64.com/product/rockpro64-20mm-mid-profile-heatsink/ 20mm medium heatsink for Model A is plenty enough]. For Model B, the [https://pine64.com/product/small-fan-type-heatsink/ fan type heatsink] will do fine.

=== Can This Run A Minecraft Server? ===

Yes! Sort of. Testing on an 8GB Model A with PaperMC, [[User:CounterPillow]] was able to out-row world generation in a boat with just one player online, but aside from the slow world gen (which can be pre-generated) the server handled things like TNT explosions and mobs fine. It'll probably do okay with 1-3 players.

=== Do I Need The 5A Power Supply For Model A? ===

You only need the 5A power supply for Model A if you plan on connecting hard disk drives to the 12V header on the board.

=== How Much Power Does It Consume? ===

For Model B, it's <2W in idle (powertop tunables not set), and <5W under full CPU load (<code>stress-ng -c4</code>). Model A will be similar as it's the same SoC.

[[Category:Quartz64]] [[Category:Rockchip RK3566]]

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-10T05:40:33Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.
* <code>wget</code>: Download a file from the internet
** '''Example:''' <code>wget https://plebian.org/img/plebian-logo-white.svg</code> downloads Plebian's logo from its website.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

=== Editing Text Files ===

For the rest of the guide, we'll be spending significant amounts of time editing text files. That's why it's good to familiarise yourself with a terminal text editor. The simplest to use of these is <code>nano</code>.

nano <var>foo</var>.txt

opens up nano, writing to the file <var>foo</var>.txt. We can save to the file with Ctrl+o, and quit nano with Ctrl+x.

A more advanced option is <code>vim</code>. You can run a lengthy interactive guide to using vim with the command <code>vimtutor</code>. Learning vim is a whole can of worms in of itself, so it's best to stick to nano if you're unsure.

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

{{note|'''TODO:''' Write this.}}

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-10T05:26:02Z

CounterPillow:

{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}}

This guide details how to build and set up a small Minecraft (Java Edition) server on a [[Quartz64]] Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it.

{{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide to work through with them.}}

== Introduction ==

=== Motivation ===

You may ask yourself why one would want to host a Minecraft server themselves instead of renting one. That is a valid question, and one big consideration is running cost. Buying the hardware and running the software yourself from your own internet access means that you're only paying a one-time cost (ignoring the minuscule power draw), whereas renting a server would usually incur a monthly fee. Since it's your server, you also have complete control over the software you run. Lastly, it's a great and fun way to learn about Linux system administration.

As for disadvantages, the server will only be as available as your home internet connection and electricity supply, and you yourself are responsible for keeping your system safe and up-to-date. The server is also not very high performance. It's best for a small group of friends, and not suitable for a public server that is likely to come under DDoS attacks.

In the below table, you can see a comparison between paying Microsoft for a
realms server and self-hosting it according to this guide.

{| class="wikitable" style="text-align:center" border="1"
! scope="col" |
! scope="col" | Minecraft Realms
! scope="col" | Self-Hosted
|-
! Setup Cost
| USD 0 || USD ~130
|-
! Monthly Cost
| USD 7.99 || USD 0
|-
! Modifications
| No || Yes
|-
! Players
| 10 || Uncapped
|-
! Availability
| Always || Depends on you
|-
! Security
| Provided by Microsoft || Your responsibility
|-
! Performance
| High || Low
|-
! Full Shell Access
| No || Yes
|-
! Teaches You Linux
| No || Yes
|}

Ignoring all points other than cost and assuming a USD 0.30/kWh rate for power with an average power draw of 3W for the board, the Quartz64 Model B as it is set up in this guide will have paid for itself in less than 18 months.

=== Game Plan ===

Let's get a high-level overview of what will be set up in this guide.

The goal is to have the base operating system (Debian Bookworm, using the Plebian images) installed on the microSD card. The Minecraft server itself will read and write its data from an NVMe M.2 SSD. The Minecraft server we'll use is PaperMC. We'll run it as a locked down systemd service. To make the server available to others on the internet, we'll use ddclient with DuckDNS to get ourselves a domain name for our (likely) dynamic IP, and forward the ports on the router.

== Shopping List ==

Total cost: Around USD 130 excluding shipping.

=== From Pine Store ===

{{note|'''Note:''' When choosing "Courier Shipping" on Pine Store, you may unfortunately be charged additional import duties once the package arrives. How high these are depends on your jurisdiction, the order value and the courier Pine Store chooses.}}

* [https://pine64.com/product/quartz64-model-b-4gb-single-board-computer/ Quartz64 Model B 4GB] — USD 59.99
** Pine Store has been known to have sold Model B's with defective ethernet or defective debug serial. If either of those things don't work, file a ticket for a return as soon as possible as to not miss the 30 day warranty window.
* [https://pine64.com/product/small-fan-type-heatsink/ Small Fan Type Heatsink] — USD 0.50
* [https://pine64.com/product/serial-console-woodpecker-edition/ Serial Console "Woodpecker" Edition] — USD 1.99
** For debugging any boot problems that might occur.
* [https://pine64.com/product/model-b-acrylic-open-enclosure/ "Model B" Acrylic Open Enclosure] — USD 7.99
* [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-international-power-supply-with-au-eu-uk-us-plug/ 5V3A International Switching Power Supply] — USD 8.99
** Feel free to choose the [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-us-version/ US-only] or [https://pine64.com/product/rock64-pinebook-pro-pine-h64-5v-3a-switching-power-supply-eu-version/ EU-only] variant instead to save two bucks.

=== From Elsewhere ===

* A good 32GB microSD card for the operating system — USD ~15
** SanDisk Max Endurance is a decent brand, Samsung EVO is fine too.
** Even if the brand looks correct, buy from a reputable marketplace and seller: fakes are common! Double-check who's selling it to you on e.g. Amazon.
** Avoid no-name cards, like the ones from Pine Store, or cards that aren't intended for longevity but maximum speed.
* A TLC flash 500GB or higher capacity NVMe M.2 drive — USD ~35
** Look at [https://docs.google.com/spreadsheets/d/1B27_j9NDPU3cNlj2HKcrfpJKHkOf-Oi1DbuuQva2gT4/edit#gid=0 the SSD spreadsheet] and pick a cheap one with TLC, and either DRAM or HMB
** PCIe 3/4 doesn't matter, it'll run at one lane of PCIe 2 anyway
** Decent usually cheap options: Kioxia Exceria, Patriot P300, Lexar NM620, WD Blue SN570
** Avoid: Kingston NV1/NV2 (no cache, meaningfully slow here), anything with QLC flash (could be meaningfully slow here), anything SATA/AHCI (won't work), anything Aliexpress (fraud).
** Shop around for deals and used drives! Just look up the manufacturer and model in the spreadsheet to verify that it's both TLC and has either DRAM or HMB cache. Bandwidth will be severely limited by the Quartz64's one lane of PCIe 2 here so paying a lot is not worth it.

=== Things You Hopefully Already Have ===

* A microSD card reader (your laptop may have one built-in already), USB3 microSD card readers are cheap and useful.
* An ethernet Cat5e or Cat6 or Cat6a cable (though technically you could run it on Wi-Fi)

== Getting Started ==

Unbox your Quartz64 Model B. Carefully attach the U.2 wireless antenna (the little grey wire with the sticker on the end) to the antenna connector that can be found near the Wi-Fi chipset (the shiny metal square). If you do not need Wi-Fi, you can skip attaching the antenna. Now is a good time to stick on the tiny aluminium heatsink; remove the protective film on its bottom and stick it onto the black chip in the centre labelled "Rockchip".

Take the baseplate from your Acrylic Open Enclosure, the small screws, and the brass nuts. Insert the screws from below the base plate (top side is the one with the acrylic standoffs) through the standoffs. Place your Quartz64 Model B board on the standoffs such that the screw threads poke through its mounting holes, oriented such that the board ends up in the middle of the base plate; the standoffs are not centred on purpose, so orientation matters. Now, secure the board by fastening the four brass nuts onto the exposed screw threads.

Next, get the large screws and metal posts, as well as the top acrylic plate. Insert the large screws through the bigger outside holes of the base plate, and fasten the metal posts on the other side. Lay the top plate on the four metal posts, and fasten it down with the remaining four large screws.

Connect the board with an ethernet cable to your network, but do not hook up power yet.

Stick your microSD card into your SD card reader, then [https://plebian.org/flashing/q64b/ follow Plebian's official flashing instructions].

Once it's flashed successfully, stick the microSD with the black bottom facing upwards into the underside of the board, below the metallic Wi-Fi chipset. This can be fiddly to get in with the board mounted to the acrylic base plate. If you're unsure of where exactly the microSD connector on the Quartz64 Model B is, peer through the transparent bottom of the acrylic base plate.

Next, unbox the M.2 NVMe SSD, flip it around and stick it in right below where you mounted the SD card; it will awkwardly protrude from the side of the case, and the spring loading mechanism of the connector will push it against the acrylic bottom plate. As sketchy as this is, it should work, so long as you don't violently bump the protruding SSD.

== First Contact ==

After you hook up the power supply to the barrel connector (important: not the audio jack, that would be bad), your board's LEDs should light up. After a couple dozen seconds, one of the LEDs should begin rhythmically blinking in a "heartbeat" like fashion. If the heartbeat pattern does not appear even after a minute or so, try hitting the little white switch closest to the antenna mount to reset the board. If it still doesn't appear after another minute, go to [[#Connecting UART]].

Once you see the heartbeat pattern, you may now connect to the board over the network, using SSH.

=== Using SSH on Windows ===

Recent versions of Windows 10 and 11 have SSH as well as mDNS support built-in. Click on the start menu, search for the Command Prompt and open it.

Into the command prompt, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use. If the Command Prompt says ssh is not a recognised command, look at [[#Installing OpenSSH On Windows]].

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on Linux or BSD ===

Make sure the OpenSSH client is installed; how depends on your distribution. If your system is set up with an mDNS resolver such as Avahi or systemd-resolved with mDNS resolution enabled, you can open a terminal and type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

=== Using SSH on macOS ===

Open a terminal by clicking on the Launchpad icon in the Dock, typing Terminal in the search field and then clicking on Terminal.

Into the newly opened terminal, type:

ssh pleb@plebian-quartz64b.local

if everything went well, it should prompt you with a host key question. Type "yes" to accept and remember the host key for future use.

ssh will now ask you for a password for the user "pleb". Type in "pleb" as the password. You will then be prompted to change your password; change it to [https://xkcd.com/936/ something secure], then log back in (with the same ssh command again, hit the up arrow to get the previous command from your history) with your new password.

Congratulations, you are now logged into your Quartz64 Model B.

== First Steps ==

{{note|'''TODO:''' Validate this.}}

=== Changing The Hostname ===

First up, you may want to change the hostname the board uses. We can do this quite easily; in your ssh session with the board, type

sudo hostnamectl hostname <var>yourhost</var>

to change the hostname to <var>yourhost</var>. You will be prompted for your password.

{{hint|'''Explanation:''' What we just did was run the <code>hostnamectl</code> command as the superuser with <code>sudo</code>. The superuser, or sometimes called the root user, is the ultimate administrator account on Unix-like systems such as Linux: it has access to everything, and should therefore be used with appropriate caution. By prefixing a command with <code>sudo</code> like this, we ask for it to be run as the superuser. The user "pleb" is allowed to use sudo in this way because it is in the necessary supplementary group.}}

After changing our hostname, a reboot is usually a good idea; type

sudo reboot

to reboot the board. To connect to it after doing this, you'll have to use the new hostname with the <code>.local</code> top-level domain, for example

ssh pleb@mcserver.local

if you set your hostname to "mcserver". You will be prompted to accept the host key again, only this time, it should tell you that it already knows the host by a different name.

=== Changing The Username ===

Being called a pleb isn't very nice, so we'll change this as well. In your ssh session, type:

sudo usermod -l <var>yourname</var> -md /home/<var>yourname</var> pleb

to update your username and home folder to <var>yourname</var>. Don't try to use spaces in your name and don't start your new username with a number. For example, if we wanted to rename the user ''pleb'' to ''greg'', we would type:

sudo usermod -l greg -md /home/greg pleb

{{hint|'''Explanation:''' The command <code>usermod</code> here is run with several arguments, each separated by space. The first argument, <code>-l</code>, signals that the next argument will be the new user name. What follows next in our example is "greg", which is the new username we chose.

Next is the argument <code>-md</code>. This is actually two arguments in one, and could be written instead as <code>-m -d</code> in <code>usermod</code>'s case, though this depends on the command. <code>-m</code> tells the command to move our old home to our new home, and <code>-d</code> tells it that the next argument is the path of the new home directory. In this case, we chose "/home/greg/". This is the usual expected location for a home directory for a user called "greg", though it's not a strict requirement.

Finally, the last argument is a positional argument, which <code>usermod</code> expects to be the current username you wish to operate on.}}

Then, we should also rename the user group:

sudo groupmod -n <var>yourname</var> pleb

{{hint|'''Explanation:''' Each user also has a "login group" they belong to, usually named the same as their username (though not necessarily so). To keep it consistent with your new username, we're renaming it with the <code>groupmod</code> command.}}

Finally, log out (by either typing <code>logout</code> or hitting Ctrl+d, and start a new ssh session with:

ssh <var>yourname</var>@<var>yourhost</var>.local

Your prompt should now show you your new name, and the command <code>id -gn</code> (no sudo!) should show you that your group has been renamed as well.

== Getting Our Feet Wet ==

If you are already familiar with basic Linux/Unix usage from the command line, you can skip this section. However, to ensure nobody is left behind, this will be a quick crash course into how to do very basic things.

=== Where Are We? ===

There is a concept of a "current working directory". Any command we run assumes relative paths are relative to this working directory. We can show the current working directory with:

pwd

This should currently show your home directory.

=== Creating Directories ===

Using the <code>mkdir</code> command, we can create a new directory.

mkdir <var>foo</var>

would create a new directory called <var>foo</var> in our current working directory. That's because the argument we gave it is interpreted as a path relative to the current working directory, as it does not begin with a forward slash (<code>/</code>).

=== Changing The Current Working Directory ===

With the <code>cd</code> command, we can change our current working directory:

cd <var>foo</var>

we should now be in the directory <var>foo</var>; we can verify this by running <code>pwd</code> again:

pwd

This should output <code>/home/<var>yourname</var>/<var>foo</var></code>.

If we want to ascend the directory hierarchy by one level, we can change to the path ".." to do so; ".." has a special meaning to be the parent directory:

cd ..

If you are ever in a hurry, you can run <code>cd</code> without any arguments to return to your home directory.

{{hint|'''Further Explanation:''' Another special directory name is <code>.</code>: this refers to the current directory. For example, <code>cd .</code> would do nothing.

<code>cd foo/./bar</code> would be equivalent to <code>cd foo/bar</code>, and <code>cd foo/../bar</code> would be equivalent to <code>cd bar</code> (into foo, up one level, into bar).

Another path component with special meaning is <code>~</code>. Our shell expands this to our user's home folder. <code>cd ~</code> would be equivalent to <code>cd</code> with no arguments.
}}

We can also give <code>cd</code> an absolute path. Absolute paths start with a forward slash, and the highest level directory is simply <code>/</code>, the root level directory. We can change your working directory to <code>/</code> with <code>cd /</code>, but be aware that we're not allowed to write any files or make any directories here.

=== Listing Directories ===

If we want to find out what's in our current directory, we can use the <code>ls</code> command:

ls

We can also give it a path as an argument to list the contents of that path instead:

ls /usr

This would list the contents of the system ''usr'' directory.

To get a more detailed list, including who owns the files and what their access rights are, we can use the <code>-l</code> argument to <code>ls</code>:

ls -l

By default, <code>ls</code> does not list files or directories starting with a dot (<code>.</code>). We can give it the <code>-a</code> argument to list those as well, including the special <code>.</code> (the folder itself being listed) and <code>..</code> (its parent folder) directories:

ls -al

{{hint|'''Further Explanation:''' Note that we once again were able to combine the two single-letter short options into one argument. <code>ls -al</code> is equivalent to <code>ls -a -l</code> or <code>ls -l -a</code>.}}

=== Creating (Empty) Files ===

To create empty files, we can use the <code>touch</code> command:

touch <var>foo</var>

would create a new empty file named <var>foo</var> in our current working directory.

{{hint|'''Further Explanation:''' What <code>touch</code> actually does is update a file's last-modified time, and create the file if it doesn't already exist. Running <code>touch</code> on an already existing time would only update its last-modified time, and not alter the file contents in any way.}}

=== Deleting Things ===

To delete an empty directory, we can use the <code>rmdir</code> command:

rmdir <var>foo</var>

would remove the <var>foo</var> directory, but only if it's empty.

To remove a file, we can use the <code>rm</code> command:

touch <var>foo</var>
ls
rm <var>foo</var>
ls

This would create a file called <var>foo</var>, list the current working directory to show you that it's there, then remove the file, and then list the current working directory again.

<code>rm</code> can also remove things recursively, in this case it's able to remove directories. Be aware though that there is '''no undo''', if you <code>rm</code> something near and dear to you, you better have had backups. In the following example, we'll create a directory, then create a file in it, then delete the directory recursively by passing <code>rm</code> the <code>-r</code> argument:

mkdir <var>foo</var>
touch <var>foo</var>/<var>bar</var>
ls <var>foo</var>
rm -r <var>foo</var>
ls

=== More Useful Commands ===

A short list of handy commands to know:

* <code>cp</code>: Copy a file (or, when recursive, a whole directory)
** '''Example:''' <code>cp foo bar</code> copies file "foo" to "bar".
** '''Example:''' <code>cp -R foo bar</code> recursively copies the directory "foo" and its contents to "bar".
* <code>mv</code>: Move/Rename a file or directory
** '''Example:''' <code>mv foo bar</code> moves a file or directory "foo" to its new name "bar".
* <code>man</code>: Show manual page for a command.
** '''Example:''' <code>man ls</code> shows the manual page for the <code>ls</code> command.
** Use this whenever you're not sure about a command's invocation. It'll be more accurate to your situation than what an internet search will tell you, and a lot less annoying to use.

{{hint|'''Useful Reminder:''' You can tab-complete a lot of things! For example, if you don't want to type out a whole directory name, hit tab once to complete it as far as possible, and hit tab twice to show the remaining options with how far you've completed it so far. Try typing <code>ls /u</code> and hitting tab, and you should have it complete to <code>ls /usr/</code>.}}

== Troubleshooting ==

This section contains various subsections for helping you troubleshoot problems you may have while following this guide.

=== Connecting UART ===

{{note|'''TODO:''' Write this.}}

=== Installing OpenSSH On Windows ===

On Windows 11, open the start menu, go to Settings > Apps > Optional features. If "OpenSSH Client" doesn't show up in your installed features, click on "View features" in "Add an optional feature" and search for "OpenSSH Client" and check it, then hit "Next" and "Install".

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-10T05:01:13Z

CounterPillow:

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-10T04:30:32Z

CounterPillow:

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-10T04:02:44Z

CounterPillow:

User:CounterPillow/Quartz64 Minecraft Server Guide

2023-09-10T01:54:42Z

CounterPillow: Created page with "{{warning|'''This article is a work-in-progress and incomplete, if you came here from a search engine, turn back.'''}} This guide details how to build and set up a small Minecraft (Java Edition) server on a Quartz64 Model B single board computer. The guide is intended to cover the basics in detail so that inexperienced users can follow it. {{Info|If you have a 12+ year old child interested in computers and have some experience yourself, this could be a great guide..."

Mainline Hardware Decoding

2023-09-05T08:49:54Z

CounterPillow: Add gst-launch examples

{{hint|This page is incomplete, you're welcome to improve it.}}

'''Mainline Hardware Decoding''' refers to video decoding done using hardware accelerators on the mainline Linux kernel (i.e. what sits in Linus' tree).

On most consumer-oriented SoCs, there is what is referred to as a VPU (Video Processing Unit). The VPU is responsible for power-efficient encoding and decoding of videos. Hardware-accelerated video decoding can be useful to get smoother video playback on your devices, lower power consumption, and lower CPU utilisation. Below is information regarding various hardware PINE64 uses and software that works with it.

== Hardware ==

Here's a table of the current support for different hardware. "In review" means the patch series to enable support has been posted to the mailing lists but is undergoing review, "linux-next" means it has been accepted and staged for the next Linux merge window.

=== Supported Codecs By SoC ===

{| class="wikitable plainrowheaders" border="1"
! scope="col" {{Diagonal split header|Codec|SoC}}
! scope="col" style="width:6em" | A64
! scope="col" style="width:6em" | RK3328
! scope="col" style="width:6em" | RK3399
! scope="col" style="width:6em" | RK3566
! scope="col" style="width:6em" | RK3588
|-
! scope="row" | JPEG
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-2
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-4 Part 2/H.263
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP8
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.264/AVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes a
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.265/HEVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:LightYellow; text-align:center;"| In review
| style="background:LightYellow; text-align:center;"| In review
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP9
| style="text-align:center;"| N/A
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AVS2
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AV1
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|}

==== Notes ====

<ol style="list-style-type:lower-alpha">
<li>only Hantro, not rkvdec2, so with a maximum resolution of 1080p for now</li>
</ol>

=== Used SoC By Device ===

This table provides a quick reference to check which SoC is used in what Pine devices, for ease of navigating the previous table.

{| class="wikitable plainrowheaders" border="1"
! SoC
! Device(s)
|-
! Allwinner A64
| PinePhone, PineTab1, Pinebook, PINE A64, PINE A64-LTS, SOPINE
|-
! Rockchip RK3328
| ROCK64
|-
! Rockchip RK3399
| PinePhone Pro, Pinebook Pro, ROCKPro64
|-
! Rockchip RK3566
| Quartz64 Model A and B, SOQuartz, PineTab2
|-
! Rockchip RK3588
| QuartzPro64
|}

=== Cedrus ===

In 2018, Bootlin launched a crowdfunding campaign to bring a open source Allwinner VPU driver to mainline Linux, which came to be called Cedrus. The Cedrus media driver (For Allwinner SOCs such as A64) supported by mainline Linux supports H.264 and H.265 video decoding as of Linux 5.10, and with 5.11 came VP8 decoding support and a H.264 stateless video decoder interface. For more information refer to the [https://linux-sunxi.org/Sunxi-Cedrus#Codec_Support Sunxi wiki].

=== Hantro ===

The Hantro media driver supports Rockchip and NXP SoCs including the RK3399 used in the Pinebook Pro and RockPro64. In November 2020 it [https://www.cnx-software.com/2020/11/24/hantro-h1-hardware-accelerated-video-encoding-support-in-mainline-linux/ was announced] that Bootlin was working on encoding support for the driver.

=== rkvdec ===

rkvdec is the video decoding hardware that's developed by Rockchip presumably in house. It's what Rockchip uses for decoding 4K H.264/AVC, VP9 and H.265/HEVC content. The driver in mainline linux for the first generation rkvdec (used in RK3328 and RK3399) supports VP9 and H.264, [https://patchwork.kernel.org/project/linux-rockchip/list/?series=659401 patches for HEVC support] are also in the process of review.

RK3566, RK3568 and likely RK3588 use a second generation of rkvdec called rkvdec2. No mainline driver for this exists yet. The rkvdec instance on RK3588 additionally supports the [https://en.wikipedia.org/wiki/Audio_Video_Standard AVS2 video codec].

=== rkdjpeg ===

rkdjpeg is Rockchip's in-house hardware accelerated JPEG decoder. It can be found on the RK3566 and RK3568 as well as the RK3588.

No mainline driver exists for it so far.

== Software ==

=== GStreamer ===

H.264, H.265, MPEG-2, VP8, VP9 and AV1 video decoding is possible when using GStreamer's command line tools, or an application utilizing it such as [https://github.com/Rafostar/clapper Clapper] or [https://flathub.org/apps/details/org.sigxcpu.Livi µPlayer]. µPlayer includes a indicator of when hardware acceleration is properly working and in use.

==== Using gst-launch ====

To test out hardware decoding from the command line, <code>gst-launch-1.0</code> may be used. An example pipeline to demux, hardware decode and display H.264 video in an MP4 container would be as follows:

gst-launch-1.0 filesrc location=yourfilehere.mp4 ! qtdemux ! v4l2slh264dec ! videoconvert ! autovideosink

To do the same for a VP8 WebM file, one may use:

gst-launch-1.0 filesrc location=yourfilehere.webm ! matroskademux ! v4l2slvp8dec ! videoconvert ! autovideosink

Depending on your GStreamer version and your GStreamer's build configuration, the following may be available as well: <code>v4l2slmpeg2dec</code>, <code>v4l2slav1dec</code>, <code>v4l2slvp9dec</code> and <code>v4l2slh265dec</code>.

On platforms with a 2D accelerator (such as Rockchip's RGA) that is supported by v4l2, one may use <code>v4l2convert</code> instead of <code>videoconvert</code> to also hardware accelerate the pixel format conversion.

=== FFmpeg ===

Mainline FFmpeg currently lacks the necessary patches to use the v4l2-requests based API, but [https://github.com/jernejsk/FFmpeg a fork that can utilise it exists]. Fedora users can install precompiled binaries from a [https://dl.kwizart.net/pub/ffmpeg-v4l2-request/ dedicated repository] by one of the Fedora maintainers.

To build it, use something like

git clone -b v4l2-request-n6.0 https://github.com/jernejsk/FFmpeg.git
cd FFmpeg
./configure --enable-v4l2-request --enable-libudev --enable-libdrm --enable-gnutls --prefix=/some/install/prefix/here
make -j$(nproc)

After compiling, you can install it into your specified prefix with

make install

And then modify your PATH to include the prefix's bin directory.

With the patched ffmpeg, you can utilise hardware decoding using the <code>-hwaccel drm</code> parameter, e.g.:

ffmpeg -hwaccel drm -i input.mp4 -f null - -benchmark

to measure how fast it decodes.

=== mpv ===

mpv v0.35 or later, built against the aforementioned FFmpeg fork, can be used to play back videos with hardware accelerated decoding. The hardware decoder path features interop with the GPU output, saving an expensive copyback operation. You can utilise the hardware decoding with e.g.:

mpv --hwdec=drm ''video''

In mpv versions prior to 0.35, you can use the copyback hwdec with:

mpv --hwdec=drm-copy ''video''

To build an mpv against the FFmpeg in your prefix, you can run

PKG_CONFIG_PATH="/path/to/your/ffmpeg/prefix/lib/pkgconfig:$PKG_CONFIG_PATH" meson setup build
ninja -C build

== More Resources ==

* [https://xnux.eu/devices/feature/cedrus-pp.html Megi's Cedrus Information]
* [https://briandaniels.me/2021/06/27/hardware-accelerated-video-playback-on-the-pinephone.html HW accelerated GStreamer playback on the PinePhone]
* [https://briandaniels.me/2021/07/06/hardware-accelerated-video-playback-on-the-pinephone-with-clapper.html HW accelerated Clapper video player on the PinePhone]

== See Also ==

* [[Mainline Hardware Encoding]]

[[Category:Quartz64]] [[Category:ROCKPro64]] [[Category:Rockchip RK3566]] [[Category:Rockchip RK3399]] [[Category:Pinebook Pro]] [[Category:PinePhone Pro]] [[Category:PineNote]] [[Category:Rockchip RK3588]] [[Category:Rockchip RK3328]] [[Category:ROCK64]] [[Category:Allwinner A64]] [[Category:PinePhone]] [[Category:PINE A64-LTS]] [[Category:SOPINE]]

Mainline Hardware Decoding

2023-09-05T05:37:48Z

CounterPillow: Add a SoC-to-devices table for ease of reference

{{hint|This page is incomplete, you're welcome to improve it.}}

'''Mainline Hardware Decoding''' refers to video decoding done using hardware accelerators on the mainline Linux kernel (i.e. what sits in Linus' tree).

On most consumer-oriented SoCs, there is what is referred to as a VPU (Video Processing Unit). The VPU is responsible for power-efficient encoding and decoding of videos. Hardware-accelerated video decoding can be useful to get smoother video playback on your devices, lower power consumption, and lower CPU utilisation. Below is information regarding various hardware PINE64 uses and software that works with it.

== Hardware ==

Here's a table of the current support for different hardware. "In review" means the patch series to enable support has been posted to the mailing lists but is undergoing review, "linux-next" means it has been accepted and staged for the next Linux merge window.

=== Supported Codecs By SoC ===

{| class="wikitable plainrowheaders" border="1"
! scope="col" {{Diagonal split header|Codec|SoC}}
! scope="col" style="width:6em" | A64
! scope="col" style="width:6em" | RK3328
! scope="col" style="width:6em" | RK3399
! scope="col" style="width:6em" | RK3566
! scope="col" style="width:6em" | RK3588
|-
! scope="row" | JPEG
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-2
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-4 Part 2/H.263
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP8
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.264/AVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes a
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.265/HEVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:LightYellow; text-align:center;"| In review
| style="background:LightYellow; text-align:center;"| In review
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP9
| style="text-align:center;"| N/A
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AVS2
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AV1
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|}

==== Notes ====

<ol style="list-style-type:lower-alpha">
<li>only Hantro, not rkvdec2, so with a maximum resolution of 1080p for now</li>
</ol>

=== Used SoC By Device ===

This table provides a quick reference to check which SoC is used in what Pine devices, for ease of navigating the previous table.

{| class="wikitable plainrowheaders" border="1"
! SoC
! Device(s)
|-
! Allwinner A64
| PinePhone, PineTab1, Pinebook, PINE A64, PINE A64-LTS, SOPINE
|-
! Rockchip RK3328
| ROCK64
|-
! Rockchip RK3399
| PinePhone Pro, Pinebook Pro, ROCKPro64
|-
! Rockchip RK3566
| Quartz64 Model A and B, SOQuartz, PineTab2
|-
! Rockchip RK3588
| QuartzPro64
|}

=== Cedrus ===

In 2018, Bootlin launched a crowdfunding campaign to bring a open source Allwinner VPU driver to mainline Linux, which came to be called Cedrus. The Cedrus media driver (For Allwinner SOCs such as A64) supported by mainline Linux supports H.264 and H.265 video decoding as of Linux 5.10, and with 5.11 came VP8 decoding support and a H.264 stateless video decoder interface. For more information refer to the [https://linux-sunxi.org/Sunxi-Cedrus#Codec_Support Sunxi wiki].

=== Hantro ===

The Hantro media driver supports Rockchip and NXP SoCs including the RK3399 used in the Pinebook Pro and RockPro64. In November 2020 it [https://www.cnx-software.com/2020/11/24/hantro-h1-hardware-accelerated-video-encoding-support-in-mainline-linux/ was announced] that Bootlin was working on encoding support for the driver.

=== rkvdec ===

rkvdec is the video decoding hardware that's developed by Rockchip presumably in house. It's what Rockchip uses for decoding 4K H.264/AVC, VP9 and H.265/HEVC content. The driver in mainline linux for the first generation rkvdec (used in RK3328 and RK3399) supports VP9 and H.264, [https://patchwork.kernel.org/project/linux-rockchip/list/?series=659401 patches for HEVC support] are also in the process of review.

RK3566, RK3568 and likely RK3588 use a second generation of rkvdec called rkvdec2. No mainline driver for this exists yet. The rkvdec instance on RK3588 additionally supports the [https://en.wikipedia.org/wiki/Audio_Video_Standard AVS2 video codec].

=== rkdjpeg ===

rkdjpeg is Rockchip's in-house hardware accelerated JPEG decoder. It can be found on the RK3566 and RK3568 as well as the RK3588.

No mainline driver exists for it so far.

== Software ==

=== GStreamer ===
H.264 video decoding is possible when using GStreamer built from source, or an application utilizing it such as [https://github.com/Rafostar/clapper Clapper] or [https://flathub.org/apps/details/org.sigxcpu.Livi µPlayer]. µPlayer includes a indicator of when hardware acceleration is properly working and in use.

=== FFmpeg ===

Mainline FFmpeg currently lacks the necessary patches to use the v4l2-requests based API, but [https://github.com/jernejsk/FFmpeg a fork that can utilise it exists]. Fedora users can install precompiled binaries from a [https://dl.kwizart.net/pub/ffmpeg-v4l2-request/ dedicated repository] by one of the Fedora maintainers.

To build it, use something like

git clone -b v4l2-request-n6.0 https://github.com/jernejsk/FFmpeg.git
cd FFmpeg
./configure --enable-v4l2-request --enable-libudev --enable-libdrm --enable-gnutls --prefix=/some/install/prefix/here
make -j$(nproc)

After compiling, you can install it into your specified prefix with

make install

And then modify your PATH to include the prefix's bin directory.

With the patched ffmpeg, you can utilise hardware decoding using the <code>-hwaccel drm</code> parameter, e.g.:

ffmpeg -hwaccel drm -i input.mp4 -f null - -benchmark

to measure how fast it decodes.

=== mpv ===

mpv v0.35 or later, built against the aforementioned FFmpeg fork, can be used to play back videos with hardware accelerated decoding. The hardware decoder path features interop with the GPU output, saving an expensive copyback operation. You can utilise the hardware decoding with e.g.:

mpv --hwdec=drm ''video''

In mpv versions prior to 0.35, you can use the copyback hwdec with:

mpv --hwdec=drm-copy ''video''

To build an mpv against the FFmpeg in your prefix, you can run

PKG_CONFIG_PATH="/path/to/your/ffmpeg/prefix/lib/pkgconfig:$PKG_CONFIG_PATH" meson setup build
ninja -C build

== More Resources ==

* [https://xnux.eu/devices/feature/cedrus-pp.html Megi's Cedrus Information]
* [https://briandaniels.me/2021/06/27/hardware-accelerated-video-playback-on-the-pinephone.html HW accelerated GStreamer playback on the PinePhone]
* [https://briandaniels.me/2021/07/06/hardware-accelerated-video-playback-on-the-pinephone-with-clapper.html HW accelerated Clapper video player on the PinePhone]

== See Also ==

* [[Mainline Hardware Encoding]]

[[Category:Quartz64]] [[Category:ROCKPro64]] [[Category:Rockchip RK3566]] [[Category:Rockchip RK3399]] [[Category:Pinebook Pro]] [[Category:PinePhone Pro]] [[Category:PineNote]] [[Category:Rockchip RK3588]] [[Category:Rockchip RK3328]] [[Category:ROCK64]] [[Category:Allwinner A64]] [[Category:PinePhone]] [[Category:PINE A64-LTS]] [[Category:SOPINE]]

Mainline Hardware Decoding

2023-09-05T05:13:09Z

CounterPillow: /* Hardware */ Make column widths consistent

{{hint|This page is incomplete, you're welcome to improve it.}}

'''Mainline Hardware Decoding''' refers to video decoding done using hardware accelerators on the mainline Linux kernel (i.e. what sits in Linus' tree).

On most consumer-oriented SoCs, there is what is referred to as a VPU (Video Processing Unit). The VPU is responsible for power-efficient encoding and decoding of videos. Hardware-accelerated video decoding can be useful to get smoother video playback on your devices, lower power consumption, and lower CPU utilisation. Below is information regarding various hardware PINE64 uses and software that works with it.

== Hardware ==

Here's a table of the current support for different hardware. "In review" means the patch series to enable support has been posted to the mailing lists but is undergoing review, "linux-next" means it has been accepted and staged for the next Linux merge window.

{| class="wikitable plainrowheaders" border="1"
! scope="col" {{Diagonal split header|Codec|SoC}}
! scope="col" style="width:6em" | A64
! scope="col" style="width:6em" | RK3328
! scope="col" style="width:6em" | RK3399
! scope="col" style="width:6em" | RK3566
! scope="col" style="width:6em" | RK3588
|-
! scope="row" | JPEG
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-2
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-4 Part 2/H.263
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP8
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.264/AVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes a
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.265/HEVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:LightYellow; text-align:center;"| In review
| style="background:LightYellow; text-align:center;"| In review
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP9
| style="text-align:center;"| N/A
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AVS2
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AV1
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|}

=== Notes ===

<ol style="list-style-type:lower-alpha">
<li>only Hantro, not rkvdec2, so with a maximum resolution of 1080p for now</li>
</ol>

=== Cedrus ===

In 2018, Bootlin launched a crowdfunding campaign to bring a open source Allwinner VPU driver to mainline Linux, which came to be called Cedrus. The Cedrus media driver (For Allwinner SOCs such as A64) supported by mainline Linux supports H.264 and H.265 video decoding as of Linux 5.10, and with 5.11 came VP8 decoding support and a H.264 stateless video decoder interface. For more information refer to the [https://linux-sunxi.org/Sunxi-Cedrus#Codec_Support Sunxi wiki].

=== Hantro ===

The Hantro media driver supports Rockchip and NXP SoCs including the RK3399 used in the Pinebook Pro and RockPro64. In November 2020 it [https://www.cnx-software.com/2020/11/24/hantro-h1-hardware-accelerated-video-encoding-support-in-mainline-linux/ was announced] that Bootlin was working on encoding support for the driver.

=== rkvdec ===

rkvdec is the video decoding hardware that's developed by Rockchip presumably in house. It's what Rockchip uses for decoding 4K H.264/AVC, VP9 and H.265/HEVC content. The driver in mainline linux for the first generation rkvdec (used in RK3328 and RK3399) supports VP9 and H.264, [https://patchwork.kernel.org/project/linux-rockchip/list/?series=659401 patches for HEVC support] are also in the process of review.

RK3566, RK3568 and likely RK3588 use a second generation of rkvdec called rkvdec2. No mainline driver for this exists yet. The rkvdec instance on RK3588 additionally supports the [https://en.wikipedia.org/wiki/Audio_Video_Standard AVS2 video codec].

=== rkdjpeg ===

rkdjpeg is Rockchip's in-house hardware accelerated JPEG decoder. It can be found on the RK3566 and RK3568 as well as the RK3588.

No mainline driver exists for it so far.

== Software ==

=== GStreamer ===
H.264 video decoding is possible when using GStreamer built from source, or an application utilizing it such as [https://github.com/Rafostar/clapper Clapper] or [https://flathub.org/apps/details/org.sigxcpu.Livi µPlayer]. µPlayer includes a indicator of when hardware acceleration is properly working and in use.

=== FFmpeg ===

Mainline FFmpeg currently lacks the necessary patches to use the v4l2-requests based API, but [https://github.com/jernejsk/FFmpeg a fork that can utilise it exists]. Fedora users can install precompiled binaries from a [https://dl.kwizart.net/pub/ffmpeg-v4l2-request/ dedicated repository] by one of the Fedora maintainers.

To build it, use something like

git clone -b v4l2-request-n6.0 https://github.com/jernejsk/FFmpeg.git
cd FFmpeg
./configure --enable-v4l2-request --enable-libudev --enable-libdrm --enable-gnutls --prefix=/some/install/prefix/here
make -j$(nproc)

After compiling, you can install it into your specified prefix with

make install

And then modify your PATH to include the prefix's bin directory.

With the patched ffmpeg, you can utilise hardware decoding using the <code>-hwaccel drm</code> parameter, e.g.:

ffmpeg -hwaccel drm -i input.mp4 -f null - -benchmark

to measure how fast it decodes.

=== mpv ===

mpv v0.35 or later, built against the aforementioned FFmpeg fork, can be used to play back videos with hardware accelerated decoding. The hardware decoder path features interop with the GPU output, saving an expensive copyback operation. You can utilise the hardware decoding with e.g.:

mpv --hwdec=drm ''video''

In mpv versions prior to 0.35, you can use the copyback hwdec with:

mpv --hwdec=drm-copy ''video''

To build an mpv against the FFmpeg in your prefix, you can run

PKG_CONFIG_PATH="/path/to/your/ffmpeg/prefix/lib/pkgconfig:$PKG_CONFIG_PATH" meson setup build
ninja -C build

== More Resources ==

* [https://xnux.eu/devices/feature/cedrus-pp.html Megi's Cedrus Information]
* [https://briandaniels.me/2021/06/27/hardware-accelerated-video-playback-on-the-pinephone.html HW accelerated GStreamer playback on the PinePhone]
* [https://briandaniels.me/2021/07/06/hardware-accelerated-video-playback-on-the-pinephone-with-clapper.html HW accelerated Clapper video player on the PinePhone]

== See Also ==

* [[Mainline Hardware Encoding]]

[[Category:Quartz64]] [[Category:ROCKPro64]] [[Category:Rockchip RK3566]] [[Category:Rockchip RK3399]] [[Category:Pinebook Pro]] [[Category:PinePhone Pro]] [[Category:PineNote]] [[Category:Rockchip RK3588]] [[Category:Rockchip RK3328]] [[Category:ROCK64]] [[Category:Allwinner A64]] [[Category:PinePhone]] [[Category:PINE A64-LTS]] [[Category:SOPINE]]

Mainline Hardware Decoding

2023-09-05T04:06:45Z

CounterPillow: /* mpv */ used->built

{{hint|This page is incomplete, you're welcome to improve it.}}

'''Mainline Hardware Decoding''' refers to video decoding done using hardware accelerators on the mainline Linux kernel (i.e. what sits in Linus' tree).

On most consumer-oriented SoCs, there is what is referred to as a VPU (Video Processing Unit). The VPU is responsible for power-efficient encoding and decoding of videos. Hardware-accelerated video decoding can be useful to get smoother video playback on your devices, lower power consumption, and lower CPU utilisation. Below is information regarding various hardware PINE64 uses and software that works with it.

== Hardware ==

Here's a table of the current support for different hardware. "In review" means the patch series to enable support has been posted to the mailing lists but is undergoing review, "linux-next" means it has been accepted and staged for the next Linux merge window.

{| class="wikitable plainrowheaders" border="1"
! scope="col" {{Diagonal split header|Codec|SoC}}
! scope="col" | A64
! scope="col" | RK3328
! scope="col" | RK3399
! scope="col" | RK3566
! scope="col" | RK3588
|-
! scope="row" | JPEG
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-2
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-4 Part 2/H.263
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP8
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.264/AVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes a
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.265/HEVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:LightYellow; text-align:center;"| In review
| style="background:LightYellow; text-align:center;"| In review
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP9
| style="text-align:center;"| N/A
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AVS2
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AV1
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|}

=== Notes ===

<ol style="list-style-type:lower-alpha">
<li>only Hantro, not rkvdec2, so with a maximum resolution of 1080p for now</li>
</ol>

=== Cedrus ===

In 2018, Bootlin launched a crowdfunding campaign to bring a open source Allwinner VPU driver to mainline Linux, which came to be called Cedrus. The Cedrus media driver (For Allwinner SOCs such as A64) supported by mainline Linux supports H.264 and H.265 video decoding as of Linux 5.10, and with 5.11 came VP8 decoding support and a H.264 stateless video decoder interface. For more information refer to the [https://linux-sunxi.org/Sunxi-Cedrus#Codec_Support Sunxi wiki].

=== Hantro ===

The Hantro media driver supports Rockchip and NXP SoCs including the RK3399 used in the Pinebook Pro and RockPro64. In November 2020 it [https://www.cnx-software.com/2020/11/24/hantro-h1-hardware-accelerated-video-encoding-support-in-mainline-linux/ was announced] that Bootlin was working on encoding support for the driver.

=== rkvdec ===

rkvdec is the video decoding hardware that's developed by Rockchip presumably in house. It's what Rockchip uses for decoding 4K H.264/AVC, VP9 and H.265/HEVC content. The driver in mainline linux for the first generation rkvdec (used in RK3328 and RK3399) supports VP9 and H.264, [https://patchwork.kernel.org/project/linux-rockchip/list/?series=659401 patches for HEVC support] are also in the process of review.

RK3566, RK3568 and likely RK3588 use a second generation of rkvdec called rkvdec2. No mainline driver for this exists yet. The rkvdec instance on RK3588 additionally supports the [https://en.wikipedia.org/wiki/Audio_Video_Standard AVS2 video codec].

=== rkdjpeg ===

rkdjpeg is Rockchip's in-house hardware accelerated JPEG decoder. It can be found on the RK3566 and RK3568 as well as the RK3588.

No mainline driver exists for it so far.

== Software ==

=== GStreamer ===
H.264 video decoding is possible when using GStreamer built from source, or an application utilizing it such as [https://github.com/Rafostar/clapper Clapper] or [https://flathub.org/apps/details/org.sigxcpu.Livi µPlayer]. µPlayer includes a indicator of when hardware acceleration is properly working and in use.

=== FFmpeg ===

Mainline FFmpeg currently lacks the necessary patches to use the v4l2-requests based API, but [https://github.com/jernejsk/FFmpeg a fork that can utilise it exists]. Fedora users can install precompiled binaries from a [https://dl.kwizart.net/pub/ffmpeg-v4l2-request/ dedicated repository] by one of the Fedora maintainers.

To build it, use something like

git clone -b v4l2-request-n6.0 https://github.com/jernejsk/FFmpeg.git
cd FFmpeg
./configure --enable-v4l2-request --enable-libudev --enable-libdrm --enable-gnutls --prefix=/some/install/prefix/here
make -j$(nproc)

After compiling, you can install it into your specified prefix with

make install

And then modify your PATH to include the prefix's bin directory.

With the patched ffmpeg, you can utilise hardware decoding using the <code>-hwaccel drm</code> parameter, e.g.:

ffmpeg -hwaccel drm -i input.mp4 -f null - -benchmark

to measure how fast it decodes.

=== mpv ===

mpv v0.35 or later, built against the aforementioned FFmpeg fork, can be used to play back videos with hardware accelerated decoding. The hardware decoder path features interop with the GPU output, saving an expensive copyback operation. You can utilise the hardware decoding with e.g.:

mpv --hwdec=drm ''video''

In mpv versions prior to 0.35, you can use the copyback hwdec with:

mpv --hwdec=drm-copy ''video''

To build an mpv against the FFmpeg in your prefix, you can run

PKG_CONFIG_PATH="/path/to/your/ffmpeg/prefix/lib/pkgconfig:$PKG_CONFIG_PATH" meson setup build
ninja -C build

== More Resources ==

* [https://xnux.eu/devices/feature/cedrus-pp.html Megi's Cedrus Information]
* [https://briandaniels.me/2021/06/27/hardware-accelerated-video-playback-on-the-pinephone.html HW accelerated GStreamer playback on the PinePhone]
* [https://briandaniels.me/2021/07/06/hardware-accelerated-video-playback-on-the-pinephone-with-clapper.html HW accelerated Clapper video player on the PinePhone]

== See Also ==

* [[Mainline Hardware Encoding]]

[[Category:Quartz64]] [[Category:ROCKPro64]] [[Category:Rockchip RK3566]] [[Category:Rockchip RK3399]] [[Category:Pinebook Pro]] [[Category:PinePhone Pro]] [[Category:PineNote]] [[Category:Rockchip RK3588]] [[Category:Rockchip RK3328]] [[Category:ROCK64]] [[Category:Allwinner A64]] [[Category:PinePhone]] [[Category:PINE A64-LTS]] [[Category:SOPINE]]

Mainline Hardware Decoding

2023-09-05T04:04:28Z

CounterPillow: /* mpv */ This isn't generally true, only when the ABI doesn't change, which isn't guaranteed, and mpv strongly recommends only running against the FFmpeg it was built with.

{{hint|This page is incomplete, you're welcome to improve it.}}

'''Mainline Hardware Decoding''' refers to video decoding done using hardware accelerators on the mainline Linux kernel (i.e. what sits in Linus' tree).

On most consumer-oriented SoCs, there is what is referred to as a VPU (Video Processing Unit). The VPU is responsible for power-efficient encoding and decoding of videos. Hardware-accelerated video decoding can be useful to get smoother video playback on your devices, lower power consumption, and lower CPU utilisation. Below is information regarding various hardware PINE64 uses and software that works with it.

== Hardware ==

Here's a table of the current support for different hardware. "In review" means the patch series to enable support has been posted to the mailing lists but is undergoing review, "linux-next" means it has been accepted and staged for the next Linux merge window.

{| class="wikitable plainrowheaders" border="1"
! scope="col" {{Diagonal split header|Codec|SoC}}
! scope="col" | A64
! scope="col" | RK3328
! scope="col" | RK3399
! scope="col" | RK3566
! scope="col" | RK3588
|-
! scope="row" | JPEG
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-2
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | MPEG-4 Part 2/H.263
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP8
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.264/AVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes a
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.265/HEVC
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:LightYellow; text-align:center;"| In review
| style="background:LightYellow; text-align:center;"| In review
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP9
| style="text-align:center;"| N/A
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AVS2
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | AV1
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
|}

=== Notes ===

<ol style="list-style-type:lower-alpha">
<li>only Hantro, not rkvdec2, so with a maximum resolution of 1080p for now</li>
</ol>

=== Cedrus ===

In 2018, Bootlin launched a crowdfunding campaign to bring a open source Allwinner VPU driver to mainline Linux, which came to be called Cedrus. The Cedrus media driver (For Allwinner SOCs such as A64) supported by mainline Linux supports H.264 and H.265 video decoding as of Linux 5.10, and with 5.11 came VP8 decoding support and a H.264 stateless video decoder interface. For more information refer to the [https://linux-sunxi.org/Sunxi-Cedrus#Codec_Support Sunxi wiki].

=== Hantro ===

The Hantro media driver supports Rockchip and NXP SoCs including the RK3399 used in the Pinebook Pro and RockPro64. In November 2020 it [https://www.cnx-software.com/2020/11/24/hantro-h1-hardware-accelerated-video-encoding-support-in-mainline-linux/ was announced] that Bootlin was working on encoding support for the driver.

=== rkvdec ===

rkvdec is the video decoding hardware that's developed by Rockchip presumably in house. It's what Rockchip uses for decoding 4K H.264/AVC, VP9 and H.265/HEVC content. The driver in mainline linux for the first generation rkvdec (used in RK3328 and RK3399) supports VP9 and H.264, [https://patchwork.kernel.org/project/linux-rockchip/list/?series=659401 patches for HEVC support] are also in the process of review.

RK3566, RK3568 and likely RK3588 use a second generation of rkvdec called rkvdec2. No mainline driver for this exists yet. The rkvdec instance on RK3588 additionally supports the [https://en.wikipedia.org/wiki/Audio_Video_Standard AVS2 video codec].

=== rkdjpeg ===

rkdjpeg is Rockchip's in-house hardware accelerated JPEG decoder. It can be found on the RK3566 and RK3568 as well as the RK3588.

No mainline driver exists for it so far.

== Software ==

=== GStreamer ===
H.264 video decoding is possible when using GStreamer built from source, or an application utilizing it such as [https://github.com/Rafostar/clapper Clapper] or [https://flathub.org/apps/details/org.sigxcpu.Livi µPlayer]. µPlayer includes a indicator of when hardware acceleration is properly working and in use.

=== FFmpeg ===

Mainline FFmpeg currently lacks the necessary patches to use the v4l2-requests based API, but [https://github.com/jernejsk/FFmpeg a fork that can utilise it exists]. Fedora users can install precompiled binaries from a [https://dl.kwizart.net/pub/ffmpeg-v4l2-request/ dedicated repository] by one of the Fedora maintainers.

To build it, use something like

git clone -b v4l2-request-n6.0 https://github.com/jernejsk/FFmpeg.git
cd FFmpeg
./configure --enable-v4l2-request --enable-libudev --enable-libdrm --enable-gnutls --prefix=/some/install/prefix/here
make -j$(nproc)

After compiling, you can install it into your specified prefix with

make install

And then modify your PATH to include the prefix's bin directory.

With the patched ffmpeg, you can utilise hardware decoding using the <code>-hwaccel drm</code> parameter, e.g.:

ffmpeg -hwaccel drm -i input.mp4 -f null - -benchmark

to measure how fast it decodes.

=== mpv ===

mpv v0.35 or later, used against the aforementioned FFmpeg fork, can be used to play back videos with hardware accelerated decoding. The hardware decoder path features interop with the GPU output, saving an expensive copyback operation. You can utilise the hardware decoding with e.g.:

mpv --hwdec=drm ''video''

In mpv versions prior to 0.35, you can use the copyback hwdec with:

mpv --hwdec=drm-copy ''video''

To build an mpv against the FFmpeg in your prefix, you can run

PKG_CONFIG_PATH="/path/to/your/ffmpeg/prefix/lib/pkgconfig:$PKG_CONFIG_PATH" meson setup build
ninja -C build

== More Resources ==

* [https://xnux.eu/devices/feature/cedrus-pp.html Megi's Cedrus Information]
* [https://briandaniels.me/2021/06/27/hardware-accelerated-video-playback-on-the-pinephone.html HW accelerated GStreamer playback on the PinePhone]
* [https://briandaniels.me/2021/07/06/hardware-accelerated-video-playback-on-the-pinephone-with-clapper.html HW accelerated Clapper video player on the PinePhone]

== See Also ==

* [[Mainline Hardware Encoding]]

[[Category:Quartz64]] [[Category:ROCKPro64]] [[Category:Rockchip RK3566]] [[Category:Rockchip RK3399]] [[Category:Pinebook Pro]] [[Category:PinePhone Pro]] [[Category:PineNote]] [[Category:Rockchip RK3588]] [[Category:Rockchip RK3328]] [[Category:ROCK64]] [[Category:Allwinner A64]] [[Category:PinePhone]] [[Category:PINE A64-LTS]] [[Category:SOPINE]]

Mainline Hardware Encoding

2023-09-05T04:01:20Z

CounterPillow: Update, add notes

'''Mainline Hardware Encoding''' of video can be achieved through the V4L2 user-space API, for which currently only GStreamer implements the required code.

== SoC Support ==

The following table shows the current supported codecs for encoding for each SoC. Support for decoding is separate.

{| class="wikitable plainrowheaders" border="1"
! scope="col" {{Diagonal split header|Codec|SoC}}
! scope="col" | RK3328
! scope="col" | RK3399
! scope="col" | RK3566
! scope="col" | RK3588
|-
! scope="row" | JPEG
| style="text-align:center;"| N/A
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:PaleGreen; text-align:center;"| Yes
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | VP8
| style="text-align:center;"| N/A
| style="background:LightYellow; text-align:center;"| RFC[https://lore.kernel.org/linux-rockchip/20230309125651.23911-1-andrzej.p@collabora.com/T/]a
| style="background:LightYellow; text-align:center;"| RFC[https://lore.kernel.org/linux-rockchip/20230309125651.23911-1-andrzej.p@collabora.com/T/]a
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.264/AVC
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| Noa
| style="background:#F99; text-align:center;"| No
|-
! scope="row" | H.265/HEVC
| style="background:#F99; text-align:center;"| No
| style="text-align:center;"| N/A
| style="background:#F99; text-align:center;"| No
| style="background:#F99; text-align:center;"| No
|}

=== Notes ===
<ol style="list-style-type:lower-alpha">
<li>Userspace API [https://lore.kernel.org/linux-media/ZK2NiQd1KnraAr20@aptenodytes/ under discussion] as part of the V4L2 stateless encoder uAPI development, with experimental implementations being worked on.</li>
</ol>

== Encoding With GStreamer ==

With GStreamer, in general, any V4L2 control can be set using the <code>extra-controls=foo,name=value</code> syntax after the encode pipeline stage identifier, where <code>foo</code> is any name you wish which GStreamer will promptly ignore, <code>name</code> is the name of the V4L2 control as shown by <code>v4l2-ctl --list-ctrls</code> (make sure to pick the right device with <code>-d</code>), and <code>value</code> is whatever value you want to set it to.

=== JPEG Encoding ===

This example converts an input MP4 file to an output MJPEG-inside-MKV file at JPEG quality 95, without any audio.

gst-launch-1.0 filesrc location=input.mp4 ! qtdemux name=demux demux.video_0 ! decodebin ! videoconvert ! v4l2jpegenc extra-controls=s,compression_quality=95 ! matroskamux ! filesink location=output.mkv

=== VP8 Encoding ===

{{hint|'''Note:''' This requires a draft [https://gitlab.freedesktop.org/gstreamer/gstreamer/-/merge_requests/3736 GStreamer merge request] and the RFC kernel patchset applied.}}
{{note|'''Note:''' Patchset no longer applies cleanly, as AV1 decode controls were introduced and conflict.}}

This example converts an input MP4 file to an output VP8-inside-MKV file with a quantiser between 12 and 28, without any audio. The quantiser value goes from 0 (best quality, biggest filesize) to 63 (worst quality, smallest filesize).

gst-launch-1.0 filesrc location=input.mp4 ! qtdemux name=demux demux.video_0 ! decodebin ! videoconvert ! v4l2slvp8enc min-quality=12 max-quality=28 ! queue ! matroskamux ! filesink location=output.mkv

Alternatively, you can encode in variable bitrate mode with a target bitrate given in bits per second. Do note that Hantro doesn't seem to do target bitrates below 2 mbit/s. In this example, the file is transcoded at a target bitrate of 3 megabits per second.

gst-launch-1.0 filesrc location=input.mp4 ! qtdemux name=demux demux.video_0 ! decodebin ! videoconvert ! v4l2slvp8enc bitrate=3000000 ! queue ! matroskamux ! filesink location=output.mkv

== See Also ==

* [[Mainline Hardware Decoding]]

[[Category:Quartz64]] [[Category:ROCKPro64]] [[Category:Rockchip RK3566]] [[Category:Rockchip RK3399]] [[Category:Pinebook Pro]] [[Category:PinePhone Pro]] [[Category:PineNote]] [[Category:Rockchip RK3588]] [[Category:Rockchip RK3328]] [[Category:ROCK64]]

Quartz64 Development

2023-08-31T12:45:36Z

CounterPillow: /* Current Status */ DSI->Confirmed working

This page documents the current status of software support for the [[Quartz64]] single-board computer, and provides links to resources to help prospective contributors get started. Information is kept current on a best-effort basis as various patches get accepted into the kernel.

== Overview ==

=== Upstreaming Status ===

{| class="wikitable plainrowheaders" border="1"
! scope="col" | Function
! scope="col" colspan="2" | Status
! scope="col" | Component
! scope="col" | Notes
! scope="col" | Applies To
|-
! scope="row" rowspan="3" | Video Output
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchipdrm/VOP2</code>
|
As of 5.19-rc1[https://git.kernel.org/linus/604be85547ce4d61b89292d2f9a78c721b778c16], Also featured in Phoronix Article[https://www.phoronix.com/scan.php?page=news_item&px=Rockchip-VOP2-Linux-5.19], 4k@30 support and other improvements in 6.4-rc1[https://git.kernel.org/linus/83b61f817f43ed67572d1e241c9f552e0a8bfff4]
|-
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rockchip-edpphy-naneng</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/blob/quartz64/drivers/phy/rockchip/phy-rockchip-naneng-edp.c] and [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/commit/d7ad116fb30d11d110aeb880754cf27f34c45c40#7e8e2ef87e479c54539dc519c0b92d6b31727f8d_671_681] Coordinate any porting with Rockchip first
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>dw-mipi-dsi-rockchip</code>
| As of 6.1[https://git.kernel.org/linus/e18d9b093006d8abd53e1ce13c0d5a8d0fcd5f64]
|
|-
! scope="row" | 3D Acceleration
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:PaleGreen; text-align:center;"|Upstream Mesa
| <code>panfrost</code>
| As of 5.18[https://git.kernel.org/linus/810028668c6d9da25664195d6b906c98a8169f72]
|-
! scope="row" rowspan="3" | Video Decode
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:LightYellow; text-align:center;" rowspan="3"|GStreamer only, no ffmpeg[https://patchwork.ffmpeg.org/project/ffmpeg/list/?series=2898]
| <code>hantro</code> using <code>v4l2-requests</code>
| VDPU121 handling 1080p MPEG-2, VP8 and H.264. Mainline as of 5.19[https://git.kernel.org/linus/5f6bfab6da6531238e899fdf29efd6d0185adc3e]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkvdec2</code> using <code>v4l2-requests</code>
| VDPU346 handling 4K H.265, H.264 and VP9
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkdjpeg</code> using <code>v4l2-requests</code>
| VDPU720 handling JPEG, [[User:CounterPillow]] is working on this
|-
! scope="row" rowspan="5" | [[Mainline Hardware Encoding|Video Encode]]
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="text-align:center; background:LightYellow;"|GStreamer only
| JPEG on VEPU121
| Hantro-based. Mainline as of 6.1[https://git.kernel.org/linus/6f1ae821a6c4aa9d5b8f437b27ec86fb569219fd]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| VP8 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU540
| rkvenc-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.265 on VEPU540
| rkvenc-based
|
|-
! scope="row" rowspan="3" | Audio
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-i2s-tdm</code>
| As of 5.16[https://git.kernel.org/linus/43b058698f723e3c2087af7069c0da082a3ecbe1]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-spdif</code>
| As of 5.15[https://git.kernel.org/linus/dac825b6a6bdca41347e25f07354ad94fdc97445]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-codec</code>
| As of 5.14[https://git.kernel.org/linus/0d6a04da9b25b9a7cf2cac5f5079e3296d3bee0f].
| Quartz64 Model A/B
|-
! scope="row" rowspan="3" | Bootloader
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/16952]
| <code>TF-A</code>
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|Merged
| <code>U-Boot</code>
| [[#Mainline_U-Boot_Work|See below]]. Quartz64 and SOQuartz as of v2023.10-rc2[https://source.denx.de/u-boot/u-boot/-/commit/4e619e8d4fd68095bc665a78f2651d8e478a4534]
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|In progress[https://github.com/jaredmcneill/quartz64_uefi]
| <code>Tianocore EDK II</code>
|
|-
! scope="row" rowspan="4" | Device Tree
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model A
| As of 5.16[https://git.kernel.org/linus/b33a22a1e7c4248608e533fc4fa524258b3fae84]
| Quartz64 Model A
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model B
| As of 5.19[https://git.kernel.org/linus/c37415f55bdadffe5b4c0e7981e9fc7e8b96beea]
| Quartz64 Model B
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| SOQuartz
| As of 5.19[https://git.kernel.org/linus/c466828fb3ba8cb7f5c3bf28766da9b70bf9745e]
| SOQuartz
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| PineNote
| As of 5.18[https://git.kernel.org/linus/d449121e5e8addcee654250cec298c887ecafb32]
| PineNote
|-
! scope="row" rowspan="2"| Gigabit Ethernet
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3566-gmac</code>
| As of 5.14[https://git.kernel.org/linus/3bb3d6b1c1957e88bfc5e77a4557f7e6ba761fe3]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>yt8511-phy</code>
| As of 5.14[https://git.kernel.org/linus/48e8c6f1612b3d2dccaea2285231def830cc5b8e]
|-
! scope="row" | IOMMU
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-iommu</code>
| As of 5.14[https://git.kernel.org/linus/c55356c534aa651ccc3053ef2d5d8d810adacf5f]
|-
! scope="row" | GPIO
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>gpio-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/936ee2675eee1faca0dcdfa79165c7990422e0fc]
|-
! scope="row" | pinctrl
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
|
|
|-
! scope="row" | Thermal Regulation
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-thermal</code>
| As of 5.14[https://git.kernel.org/linus/4b14c055a6f644cbeb1156ba24647e92fe51ec69]
|-
! scope="row" | PCIe
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>pcie-dw-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/0e898eb8df4e34c7b129452444eb7cef68a11f43]
|-
! scope="row" | Power Management
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-pm-domains</code>
| As of 5.14[https://git.kernel.org/linus/1782c87b44a0b1a527f01a6a184677c58ccbf9c7]
|-
! scope="row" | Voltage Control
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3568-pmu-io-voltage-domain</code>
| As of 5.15[https://git.kernel.org/linus/28b05a64e47cbceebb8a5f3f643033148d5c06c3]
|-
! scope="row" | SPI
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>spi-rockchip</code>
| As of 5.14[https://git.kernel.org/linus/d74d99229f4d48f42d674f7a8a1137179efd67ac]. Necessary device tree changes [https://patchwork.kernel.org/project/linux-rockchip/list/?series=586691 in review].
|-
! scope="row" | Battery
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-charger</code>
| As of 6.1[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/power/supply/rk817_charger.c?id=11cb8da0189b417392e2334ae967b0ba1f0d1be8]
| Quartz64 Model A, Pinenote
|-
! scope="row" | Microphone
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-saradc</code>
| As of 5.15[https://git.kernel.org/linus/7786da3b5ae167c17f35e22ba35e06006338c2f6]. Headphone jack mic seems to connect to <code>SARADC_VIN2_HP_HOOK</code>, so I'm pretty sure that the dtsi and driver changes are needed for that mic to work
|-
! scope="row" | USB 2.0
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-usb2phy</code>
| As of 5.17[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/phy/rockchip?h=v5.17-rc1&id=42b559727a45d79c811f493515eb9b7e56016421]
|-
! scope="row" | e-Ink
| colspan="2" style="background:LightYellow; text-align:center;"|In review (RFC)[https://lore.kernel.org/linux-rockchip/20220413221916.50995-1-samuel@sholland.org/T/]
| <code>rockchip-ebc</code>
| A DRM driver is available [https://github.com/smaeul/linux/commits/rk35/ebc-drm-v5 here]; also see [[RK3566 EBC Reverse-Engineering]]
|-
! scope="row" | Combo PHY
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>naneng-combphy</code>
| As of 5.18[https://git.kernel.org/linus/7160820d742a16313f7802e33c2956c19548e488]. Still requires DTS changes
|-
! scope="row" | RGA
| colspan="2" style="background:LightYellow; text-align:center;"|Linux Mainline; Could be improved
| <code>rockchip-rga</code>
| As of 6.5[https://git.kernel.org/linus/0c3391f8bb06b744df521651534cd99e3d77e0a8]. Note that there's still a '4GB' problem and it's implementations has room for improvements (to put it midly [https://lore.kernel.org/all/20230522102953.GB23678@pengutronix.de/] and [https://lore.kernel.org/all/b404dc20-c460-ac3f-6659-8be7a7d32bfe@arm.com/])
|-
! scope="row" | Fan Controller
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
| <code>gp7101</code>
| Someone should write a pwm driver for it so we can then use pwm-fan
| SOQuartz Blade
|-
! scope="row" rowspan="2" | CSI Camera
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rkisp</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/media/platform/rockchip/isp]
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-inno-csidphy</code>
| As of 6.1[https://git.kernel.org/linus/29c99fb085ad53e6d5504d1f8d32e6673b9b3a2c]
|
|-
! scope="row" | NPU
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
|
| Downstream version is a closed source SDK and [https://github.com/dieselnutjob/kernel-rk3566/tree/linux-4.19.210/drivers/rknpu open source kernel module rknpu]. Major undertaking to reimplement this as Linux does not (yet) appear to have a generic architecture for neural accelerators.
|
|-
! scope="row" | Crypto
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rk-crypto</code> v2
| Downstream driver [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/crypto/rockchip] doesn't include a rk3568 compatible either, but the TRM shows that it seemingly matches.
|
|-
! scope="row" | TRNG
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://patchwork.kernel.org/project/linux-rockchip/list/?series=699813&archive=both]
| <code>rockchip-rng</code>
|
|
|-
! scope="row" rowspan="2" | Wi-Fi
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>bes2600</code>
| A downstream driver is available but it makes use of some custom Rockchip interfaces and is designed for older kernels, plans are being made to port it to DKMS.
| PineTab 2
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>brcmfmac</code>
|
| Quartz64 Model B
|}

== Current Status ==

The following sections give an overview over the current status of different parts of the board. Some parts are waiting on a driver to be written or ported, others only need various adjustments.

According to pgwipeout, I/O device performance is within expected ranges now.

=== Working ===

* eMMC
* SDMMC0 (SD cards)
* GMAC (Gigabit Ethernet)
* USB 2.0
* SATA 2
* SATA 3
* UART
** UART 0 (Pi-bus)
** UART 1 (Bluetooth)
** UART 2 (Pi-bus, debug)
* Video Decode
** VP8
** H.264
* Video Encode
** JPEG (it's pretty bad)
* Battery
* GPU
* Video Output
** HDMI
** DSI
* Audio
** Analog audio works
** SPDIF works
** HDMI works
* SPI — works, user needs to modify device tree to add devices
* I2C — works, user needs to modify device tree to add devices

=== Partially Working ===

* PCI-Express Controller — everything but devices that need cache coherency (e.g. dGPUs) should work
** [[User:CounterPillow]] noticed some weirdness with NVMe devices disconnecting during heavy write operations, likely down due to power draw on one of the rails as the same sustained bandwidth could be achieved with a different PCIe device with no issue.
* SDMMC1 (Wi-Fi) — AP6256 working, BL602 needs some work to make it flash firmware
* [https://developer.arm.com/architectures/system-architectures/system-components/arm-generic-interrupt-controller GIC] — needs errata published by Rockchip to get upstream to add device-specific workarounds[https://lore.kernel.org/linux-rockchip/CAMdYzYrQ5f-mv_VmTq_CRf9tR=j3mwRpKHNLmPFgCF9whsGFRw@mail.gmail.com/]

=== Confirmed Broken ===

* <s>USB 3.0 (applies to Model A only) — only works with very short cables and depends on the device. This is due to a hardware design issue relating to the coupling capacitors needed for SATA, which shares the same lines as USB 3.0.
** Hardware design changes have been suggested to engineers, it's in their hands now.</s>
** Fixed in newer revisions by leaving SATA unpopulated
* RGA — only works with memory ≤ 4 GiB, because Rockchip didn't make the address registers larger. Oopsie.

=== Needs Testing ===

* E-Paper
* Microphone Input
* CSI — needs CIF driver
* eDP — needs PHY driver and controller driver

== TODO ==

=== ebc-dev Reverse Engineering and Development ===

The [https://gitlab.com/pine64-org/quartz-bsp/linux-next/-/tree/rk356x-ebc-dev driver for the eInk panel] needs to both be reverse engineered and then rewritten as C. In its current form, it is mostly an assembly dump produced by gcc with debug symbols. See [[RK3566 EBC Reverse-Engineering]] for details.

=== Investigate MCU ===

The RK3566 comes with an integrated RISC-V microcontroller (MCU). It communicates with the A55 host through the Mailbox system driven by the rockchip-mailbox driver. Since this MCU would be quite useful for things such as low power standby mode, investigating how it can be turned on and have firmware flashed to it should greatly enhance the power saving features of the PineNote.

I (liamur) [https://github.com/liamhays/rk3566-mcu did some investigation] into the MCU and found that it is disabled by TF-A on suspend, and doesn't reside in a low-power part of the RK3566 anyway. It does however have access to most of the chip and could be used as (for example) a real-time coprocessor.

=== Mainline U-Boot Work ===

We currently use the "downstream" Rockchip U-Boot, which is based on an old version of U-Boot and contains vendor specific patches that have not undergone the same level of code review as they'd have done had they been submitted upstream.

While the lack of ATF sources means that using mainline U-Boot would still require the use of Rockchip provided binaries for the firmware, even with Rockchip blobs, a more modern version of U-Boot will be much nicer to use.

Mainline U-Boot contains good enough support for the RK3566 SoC used on the Quartz64 as of v2023.07 and have support for Quartz64 and SOQuartz as of v2023.10-rc2. Drivers for [https://patchwork.ozlabs.org/cover/1817577/ ethernet GMAC] and [https://patchwork.ozlabs.org/patch/1817295/ Motorcomm PHY] have been submitted for review.

==== Things that could be done ====

This list is non-exhaustive as we don't exactly know how much is missing

* Port a basic VOP2 driver to get a framebuffer from u-boot

==== List of Useful Resources for this Task ====
* Downstream Rockchip U-Boot repository with Quartz64 specific patches: https://gitlab.com/pgwipeout/u-boot-rockchip/-/tree/quartz64
* Mainline Rockchip custodian U-Boot repository: https://source.denx.de/u-boot/custodians/u-boot-rockchip
* U-Boot Mailing List: https://lists.denx.de/listinfo/u-boot

=== eDP Driver Porting ===

The eDP PHY driver and controller driver needs to be ported, brought into shape and submitted with proper commit attribution to the Rockchip authors.

[[User:CounterPillow]] has experimentally ported stuff, but it's currently not working.

== Linux Kernel Config Options ==

* <code>CONFIG_SND_SOC_ROCKCHIP_I2S_TDM</code>
** for Analog and HDMI audio
* <code>CONFIG_SND_SOC_RK817</code>
** for Analog audio on the Model A
* <code>CONFIG_STMMAC_ETH</code>
** Ethernet
* <code>CONFIG_DWMAC_ROCKCHIP</code>
** Ethernet
* <code>CONFIG_MOTORCOMM_PHY</code>
** Ethernet PHY for Model A, set this one to Y, m won't work out of the box if the generic PHY driver is y and binds first. Alternatively tell users in board-specific setup instructions to force including the <code>motorcomm</code> module in initramfs if you set it to m.
* <code>CONFIG_REALTEK_PHY</code>
** Ethernet PHY for Model B
* <code>CONFIG_MMC_DW</code>
** MMC/SD
* <code>CONFIG_MMC_DW_ROCKCHIP</code>
** MMC/SD
* <code>CONFIG_MMC_SDHCI_OF_DWCMSHC</code>
** MMC/SD
* <code>CONFIG_PCIE_ROCKCHIP_DW_HOST</code>
** PCIe
* <code>CONFIG_PHY_ROCKCHIP_NANENG_COMBO_PHY</code>
** PHY for PCIe/SATA/USB3
* <code>CONFIG_DRM_PANFROST</code>
** GPU
* <code>CONFIG_SND_SOC_ROCKCHIP_SPDIF</code>
** SPDIF audio
* <code>CONFIG_ROCKCHIP_DW_HDMI</code>
** HDMI PHY
* <code>CONFIG_PHY_ROCKCHIP_INNO_DSIDPHY</code>
** MIPI DSI DPHY
* <code>CONFIG_ROCKCHIP_VOP2</code>
** Video output
* <code>CONFIG_ARCH_ROCKCHIP</code>
** General SoC support
* <code>CONFIG_ROCKCHIP_PHY</code>
** General SoC support
* <code>CONFIG_PHY_ROCKCHIP_INNO_USB2</code>
** USB 2
* <code>CONFIG_RTC_DRV_RK808</code>
** Real-time Clock
* <code>CONFIG_COMMON_CLK_RK808</code>
** Real-time Clock
* <code>CONFIG_MFD_RK808</code>
** Various things relating to the RK817 chip
* <code>CONFIG_CHARGER_RK817</code>
** RK817 charger
* <code>CONFIG_REGULATOR_RK808</code>
** Voltage regulators
* <code>CONFIG_ROCKCHIP_PM_DOMAINS</code>
** Power management domains
* <code>CONFIG_GPIO_ROCKCHIP</code>
** GPIO support
* <code>CONFIG_PINCTRL_ROCKCHIP</code>
** GPIO and general SoC support
* <code>CONFIG_PWM_ROCKCHIP</code>
** PWM support
* <code>CONFIG_ROCKCHIP_IOMMU</code>
** IOMMU support
* <code>CONFIG_ROCKCHIP_MBOX</code>
** Mailbox support (for communication with MCU)
* <code>CONFIG_ROCKCHIP_SARADC</code>
** Analog-to-digital conversion support, for e.g. microphones
* <code>CONFIG_ROCKCHIP_THERMAL</code>
** Temperature sensor and thermal throttling support
* <code>CONFIG_SPI_ROCKCHIP</code>
** SPI support
* <code>CONFIG_VIDEO_HANTRO_ROCKCHIP</code>
** Hardware video decoder support
* <code>CONFIG_ROCKCHIP_IODOMAIN</code>
** General SoC support so your I/O pins have the right voltage
* <code>CONFIG_COMMON_CLK_ROCKCHIP</code>
** Common clock support
* <code>CONFIG_PHY_ROCKCHIP_INNO_CSIDPHY</code>
** MIPI CSI DPHY
* <code>CONFIG_I2C_RK3X</code>
** I2C support

== Resources ==
=== Repositories ===

* pgwipeout's kernel tree
** https://gitlab.com/pgwipeout/linux-next/-/tree/quartz64-v5.15-rc1
* BSP based development effort for SPL/U-Boot and Linux
** https://gitlab.com/pine64-org/quartz-bsp
* Image CI pipeline aimed at developers
** https://gitlab.com/pgwipeout/quartz64_ci/
* Rockchip U-Boot
** https://github.com/rockchip-linux/u-boot
* Downstream rockchip-linux kernel tree
** https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux
* Tianocore EDK II port for UEFI on Quartz64
** https://github.com/jaredmcneill/quartz64_uefi
* Mainline U-Boot Port by pgwipeout
** https://gitlab.com/pgwipeout/u-boot-quartz64

=== Other ===

* Rockchip-SoC Patchwork Page
** https://patchwork.kernel.org/project/linux-rockchip/list/
* Rockchip Kernel Mailing List Archive
** https://lore.kernel.org/linux-rockchip/

== Board/SoC Documentation ==
=== Booting ===
==== Boot Order ====
The RK3566 boot ROM will search for a valid ID BLOCK in the following order on the support boot media:

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

... if this fails, the boot ROM will initialize the USB0 port and wait for a connection from the Rockchip
flash/boot tools.

==== Bootloader Flashing ====

As per pgwipeout's [https://gitlab.com/pine64-org/quartz-bsp/u-boot/-/commit/12d102b86813378af08b086f3b9c13ed8010754c commit message]:
* Make a partition named <code>uboot</code> as partition number 1 at 8 MiB to 16 MiB
* <code>dd if=idblock.bin of=/dev/''<mmc/sd>'' seek=64</code>
* <code>dd if=uboot.img of=/dev/''<mmc/sd>''1</code>

==== BSP Image Layout ====

[[Category:Quartz64]][[Category:Rockchip RK3566]]

Quartz64 Development

2023-08-31T12:44:06Z

CounterPillow: /* Confirmed Broken */ USB 3 update

This page documents the current status of software support for the [[Quartz64]] single-board computer, and provides links to resources to help prospective contributors get started. Information is kept current on a best-effort basis as various patches get accepted into the kernel.

== Overview ==

=== Upstreaming Status ===

{| class="wikitable plainrowheaders" border="1"
! scope="col" | Function
! scope="col" colspan="2" | Status
! scope="col" | Component
! scope="col" | Notes
! scope="col" | Applies To
|-
! scope="row" rowspan="3" | Video Output
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchipdrm/VOP2</code>
|
As of 5.19-rc1[https://git.kernel.org/linus/604be85547ce4d61b89292d2f9a78c721b778c16], Also featured in Phoronix Article[https://www.phoronix.com/scan.php?page=news_item&px=Rockchip-VOP2-Linux-5.19], 4k@30 support and other improvements in 6.4-rc1[https://git.kernel.org/linus/83b61f817f43ed67572d1e241c9f552e0a8bfff4]
|-
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rockchip-edpphy-naneng</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/blob/quartz64/drivers/phy/rockchip/phy-rockchip-naneng-edp.c] and [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/commit/d7ad116fb30d11d110aeb880754cf27f34c45c40#7e8e2ef87e479c54539dc519c0b92d6b31727f8d_671_681] Coordinate any porting with Rockchip first
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>dw-mipi-dsi-rockchip</code>
| As of 6.1[https://git.kernel.org/linus/e18d9b093006d8abd53e1ce13c0d5a8d0fcd5f64]
|
|-
! scope="row" | 3D Acceleration
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:PaleGreen; text-align:center;"|Upstream Mesa
| <code>panfrost</code>
| As of 5.18[https://git.kernel.org/linus/810028668c6d9da25664195d6b906c98a8169f72]
|-
! scope="row" rowspan="3" | Video Decode
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:LightYellow; text-align:center;" rowspan="3"|GStreamer only, no ffmpeg[https://patchwork.ffmpeg.org/project/ffmpeg/list/?series=2898]
| <code>hantro</code> using <code>v4l2-requests</code>
| VDPU121 handling 1080p MPEG-2, VP8 and H.264. Mainline as of 5.19[https://git.kernel.org/linus/5f6bfab6da6531238e899fdf29efd6d0185adc3e]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkvdec2</code> using <code>v4l2-requests</code>
| VDPU346 handling 4K H.265, H.264 and VP9
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkdjpeg</code> using <code>v4l2-requests</code>
| VDPU720 handling JPEG, [[User:CounterPillow]] is working on this
|-
! scope="row" rowspan="5" | [[Mainline Hardware Encoding|Video Encode]]
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="text-align:center; background:LightYellow;"|GStreamer only
| JPEG on VEPU121
| Hantro-based. Mainline as of 6.1[https://git.kernel.org/linus/6f1ae821a6c4aa9d5b8f437b27ec86fb569219fd]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| VP8 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU540
| rkvenc-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.265 on VEPU540
| rkvenc-based
|
|-
! scope="row" rowspan="3" | Audio
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-i2s-tdm</code>
| As of 5.16[https://git.kernel.org/linus/43b058698f723e3c2087af7069c0da082a3ecbe1]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-spdif</code>
| As of 5.15[https://git.kernel.org/linus/dac825b6a6bdca41347e25f07354ad94fdc97445]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-codec</code>
| As of 5.14[https://git.kernel.org/linus/0d6a04da9b25b9a7cf2cac5f5079e3296d3bee0f].
| Quartz64 Model A/B
|-
! scope="row" rowspan="3" | Bootloader
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/16952]
| <code>TF-A</code>
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|Merged
| <code>U-Boot</code>
| [[#Mainline_U-Boot_Work|See below]]. Quartz64 and SOQuartz as of v2023.10-rc2[https://source.denx.de/u-boot/u-boot/-/commit/4e619e8d4fd68095bc665a78f2651d8e478a4534]
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|In progress[https://github.com/jaredmcneill/quartz64_uefi]
| <code>Tianocore EDK II</code>
|
|-
! scope="row" rowspan="4" | Device Tree
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model A
| As of 5.16[https://git.kernel.org/linus/b33a22a1e7c4248608e533fc4fa524258b3fae84]
| Quartz64 Model A
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model B
| As of 5.19[https://git.kernel.org/linus/c37415f55bdadffe5b4c0e7981e9fc7e8b96beea]
| Quartz64 Model B
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| SOQuartz
| As of 5.19[https://git.kernel.org/linus/c466828fb3ba8cb7f5c3bf28766da9b70bf9745e]
| SOQuartz
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| PineNote
| As of 5.18[https://git.kernel.org/linus/d449121e5e8addcee654250cec298c887ecafb32]
| PineNote
|-
! scope="row" rowspan="2"| Gigabit Ethernet
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3566-gmac</code>
| As of 5.14[https://git.kernel.org/linus/3bb3d6b1c1957e88bfc5e77a4557f7e6ba761fe3]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>yt8511-phy</code>
| As of 5.14[https://git.kernel.org/linus/48e8c6f1612b3d2dccaea2285231def830cc5b8e]
|-
! scope="row" | IOMMU
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-iommu</code>
| As of 5.14[https://git.kernel.org/linus/c55356c534aa651ccc3053ef2d5d8d810adacf5f]
|-
! scope="row" | GPIO
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>gpio-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/936ee2675eee1faca0dcdfa79165c7990422e0fc]
|-
! scope="row" | pinctrl
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
|
|
|-
! scope="row" | Thermal Regulation
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-thermal</code>
| As of 5.14[https://git.kernel.org/linus/4b14c055a6f644cbeb1156ba24647e92fe51ec69]
|-
! scope="row" | PCIe
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>pcie-dw-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/0e898eb8df4e34c7b129452444eb7cef68a11f43]
|-
! scope="row" | Power Management
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-pm-domains</code>
| As of 5.14[https://git.kernel.org/linus/1782c87b44a0b1a527f01a6a184677c58ccbf9c7]
|-
! scope="row" | Voltage Control
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3568-pmu-io-voltage-domain</code>
| As of 5.15[https://git.kernel.org/linus/28b05a64e47cbceebb8a5f3f643033148d5c06c3]
|-
! scope="row" | SPI
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>spi-rockchip</code>
| As of 5.14[https://git.kernel.org/linus/d74d99229f4d48f42d674f7a8a1137179efd67ac]. Necessary device tree changes [https://patchwork.kernel.org/project/linux-rockchip/list/?series=586691 in review].
|-
! scope="row" | Battery
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-charger</code>
| As of 6.1[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/power/supply/rk817_charger.c?id=11cb8da0189b417392e2334ae967b0ba1f0d1be8]
| Quartz64 Model A, Pinenote
|-
! scope="row" | Microphone
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-saradc</code>
| As of 5.15[https://git.kernel.org/linus/7786da3b5ae167c17f35e22ba35e06006338c2f6]. Headphone jack mic seems to connect to <code>SARADC_VIN2_HP_HOOK</code>, so I'm pretty sure that the dtsi and driver changes are needed for that mic to work
|-
! scope="row" | USB 2.0
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-usb2phy</code>
| As of 5.17[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/phy/rockchip?h=v5.17-rc1&id=42b559727a45d79c811f493515eb9b7e56016421]
|-
! scope="row" | e-Ink
| colspan="2" style="background:LightYellow; text-align:center;"|In review (RFC)[https://lore.kernel.org/linux-rockchip/20220413221916.50995-1-samuel@sholland.org/T/]
| <code>rockchip-ebc</code>
| A DRM driver is available [https://github.com/smaeul/linux/commits/rk35/ebc-drm-v5 here]; also see [[RK3566 EBC Reverse-Engineering]]
|-
! scope="row" | Combo PHY
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>naneng-combphy</code>
| As of 5.18[https://git.kernel.org/linus/7160820d742a16313f7802e33c2956c19548e488]. Still requires DTS changes
|-
! scope="row" | RGA
| colspan="2" style="background:LightYellow; text-align:center;"|Linux Mainline; Could be improved
| <code>rockchip-rga</code>
| As of 6.5[https://git.kernel.org/linus/0c3391f8bb06b744df521651534cd99e3d77e0a8]. Note that there's still a '4GB' problem and it's implementations has room for improvements (to put it midly [https://lore.kernel.org/all/20230522102953.GB23678@pengutronix.de/] and [https://lore.kernel.org/all/b404dc20-c460-ac3f-6659-8be7a7d32bfe@arm.com/])
|-
! scope="row" | Fan Controller
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
| <code>gp7101</code>
| Someone should write a pwm driver for it so we can then use pwm-fan
| SOQuartz Blade
|-
! scope="row" rowspan="2" | CSI Camera
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rkisp</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/media/platform/rockchip/isp]
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-inno-csidphy</code>
| As of 6.1[https://git.kernel.org/linus/29c99fb085ad53e6d5504d1f8d32e6673b9b3a2c]
|
|-
! scope="row" | NPU
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
|
| Downstream version is a closed source SDK and [https://github.com/dieselnutjob/kernel-rk3566/tree/linux-4.19.210/drivers/rknpu open source kernel module rknpu]. Major undertaking to reimplement this as Linux does not (yet) appear to have a generic architecture for neural accelerators.
|
|-
! scope="row" | Crypto
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rk-crypto</code> v2
| Downstream driver [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/crypto/rockchip] doesn't include a rk3568 compatible either, but the TRM shows that it seemingly matches.
|
|-
! scope="row" | TRNG
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://patchwork.kernel.org/project/linux-rockchip/list/?series=699813&archive=both]
| <code>rockchip-rng</code>
|
|
|-
! scope="row" rowspan="2" | Wi-Fi
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>bes2600</code>
| A downstream driver is available but it makes use of some custom Rockchip interfaces and is designed for older kernels, plans are being made to port it to DKMS.
| PineTab 2
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>brcmfmac</code>
|
| Quartz64 Model B
|}

== Current Status ==

The following sections give an overview over the current status of different parts of the board. Some parts are waiting on a driver to be written or ported, others only need various adjustments.

According to pgwipeout, I/O device performance is within expected ranges now.

=== Working ===

* eMMC
* SDMMC0 (SD cards)
* GMAC (Gigabit Ethernet)
* USB 2.0
* SATA 2
* SATA 3
* UART
** UART 0 (Pi-bus)
** UART 1 (Bluetooth)
** UART 2 (Pi-bus, debug)
* Video Decode
** VP8
** H.264
* Video Encode
** JPEG (it's pretty bad)
* Battery
* GPU
* Audio
** Analog audio works
** SPDIF works
** HDMI works
* SPI — works, user needs to modify device tree to add devices
* I2C — works, user needs to modify device tree to add devices

=== Partially Working ===

* PCI-Express Controller — everything but devices that need cache coherency (e.g. dGPUs) should work
** [[User:CounterPillow]] noticed some weirdness with NVMe devices disconnecting during heavy write operations, likely down due to power draw on one of the rails as the same sustained bandwidth could be achieved with a different PCIe device with no issue.
* SDMMC1 (Wi-Fi) — AP6256 working, BL602 needs some work to make it flash firmware
* [https://developer.arm.com/architectures/system-architectures/system-components/arm-generic-interrupt-controller GIC] — needs errata published by Rockchip to get upstream to add device-specific workarounds[https://lore.kernel.org/linux-rockchip/CAMdYzYrQ5f-mv_VmTq_CRf9tR=j3mwRpKHNLmPFgCF9whsGFRw@mail.gmail.com/]

=== Confirmed Broken ===

* <s>USB 3.0 (applies to Model A only) — only works with very short cables and depends on the device. This is due to a hardware design issue relating to the coupling capacitors needed for SATA, which shares the same lines as USB 3.0.
** Hardware design changes have been suggested to engineers, it's in their hands now.</s>
** Fixed in newer revisions by leaving SATA unpopulated
* RGA — only works with memory ≤ 4 GiB, because Rockchip didn't make the address registers larger. Oopsie.

=== Needs Testing ===

* E-Paper
* Microphone Input
* CSI — needs CIF driver
* eDP — needs PHY driver and controller driver
* DSI

== TODO ==

=== ebc-dev Reverse Engineering and Development ===

The [https://gitlab.com/pine64-org/quartz-bsp/linux-next/-/tree/rk356x-ebc-dev driver for the eInk panel] needs to both be reverse engineered and then rewritten as C. In its current form, it is mostly an assembly dump produced by gcc with debug symbols. See [[RK3566 EBC Reverse-Engineering]] for details.

=== Investigate MCU ===

The RK3566 comes with an integrated RISC-V microcontroller (MCU). It communicates with the A55 host through the Mailbox system driven by the rockchip-mailbox driver. Since this MCU would be quite useful for things such as low power standby mode, investigating how it can be turned on and have firmware flashed to it should greatly enhance the power saving features of the PineNote.

I (liamur) [https://github.com/liamhays/rk3566-mcu did some investigation] into the MCU and found that it is disabled by TF-A on suspend, and doesn't reside in a low-power part of the RK3566 anyway. It does however have access to most of the chip and could be used as (for example) a real-time coprocessor.

=== Mainline U-Boot Work ===

We currently use the "downstream" Rockchip U-Boot, which is based on an old version of U-Boot and contains vendor specific patches that have not undergone the same level of code review as they'd have done had they been submitted upstream.

While the lack of ATF sources means that using mainline U-Boot would still require the use of Rockchip provided binaries for the firmware, even with Rockchip blobs, a more modern version of U-Boot will be much nicer to use.

Mainline U-Boot contains good enough support for the RK3566 SoC used on the Quartz64 as of v2023.07 and have support for Quartz64 and SOQuartz as of v2023.10-rc2. Drivers for [https://patchwork.ozlabs.org/cover/1817577/ ethernet GMAC] and [https://patchwork.ozlabs.org/patch/1817295/ Motorcomm PHY] have been submitted for review.

==== Things that could be done ====

This list is non-exhaustive as we don't exactly know how much is missing

* Port a basic VOP2 driver to get a framebuffer from u-boot

==== List of Useful Resources for this Task ====
* Downstream Rockchip U-Boot repository with Quartz64 specific patches: https://gitlab.com/pgwipeout/u-boot-rockchip/-/tree/quartz64
* Mainline Rockchip custodian U-Boot repository: https://source.denx.de/u-boot/custodians/u-boot-rockchip
* U-Boot Mailing List: https://lists.denx.de/listinfo/u-boot

=== eDP Driver Porting ===

The eDP PHY driver and controller driver needs to be ported, brought into shape and submitted with proper commit attribution to the Rockchip authors.

[[User:CounterPillow]] has experimentally ported stuff, but it's currently not working.

== Linux Kernel Config Options ==

* <code>CONFIG_SND_SOC_ROCKCHIP_I2S_TDM</code>
** for Analog and HDMI audio
* <code>CONFIG_SND_SOC_RK817</code>
** for Analog audio on the Model A
* <code>CONFIG_STMMAC_ETH</code>
** Ethernet
* <code>CONFIG_DWMAC_ROCKCHIP</code>
** Ethernet
* <code>CONFIG_MOTORCOMM_PHY</code>
** Ethernet PHY for Model A, set this one to Y, m won't work out of the box if the generic PHY driver is y and binds first. Alternatively tell users in board-specific setup instructions to force including the <code>motorcomm</code> module in initramfs if you set it to m.
* <code>CONFIG_REALTEK_PHY</code>
** Ethernet PHY for Model B
* <code>CONFIG_MMC_DW</code>
** MMC/SD
* <code>CONFIG_MMC_DW_ROCKCHIP</code>
** MMC/SD
* <code>CONFIG_MMC_SDHCI_OF_DWCMSHC</code>
** MMC/SD
* <code>CONFIG_PCIE_ROCKCHIP_DW_HOST</code>
** PCIe
* <code>CONFIG_PHY_ROCKCHIP_NANENG_COMBO_PHY</code>
** PHY for PCIe/SATA/USB3
* <code>CONFIG_DRM_PANFROST</code>
** GPU
* <code>CONFIG_SND_SOC_ROCKCHIP_SPDIF</code>
** SPDIF audio
* <code>CONFIG_ROCKCHIP_DW_HDMI</code>
** HDMI PHY
* <code>CONFIG_PHY_ROCKCHIP_INNO_DSIDPHY</code>
** MIPI DSI DPHY
* <code>CONFIG_ROCKCHIP_VOP2</code>
** Video output
* <code>CONFIG_ARCH_ROCKCHIP</code>
** General SoC support
* <code>CONFIG_ROCKCHIP_PHY</code>
** General SoC support
* <code>CONFIG_PHY_ROCKCHIP_INNO_USB2</code>
** USB 2
* <code>CONFIG_RTC_DRV_RK808</code>
** Real-time Clock
* <code>CONFIG_COMMON_CLK_RK808</code>
** Real-time Clock
* <code>CONFIG_MFD_RK808</code>
** Various things relating to the RK817 chip
* <code>CONFIG_CHARGER_RK817</code>
** RK817 charger
* <code>CONFIG_REGULATOR_RK808</code>
** Voltage regulators
* <code>CONFIG_ROCKCHIP_PM_DOMAINS</code>
** Power management domains
* <code>CONFIG_GPIO_ROCKCHIP</code>
** GPIO support
* <code>CONFIG_PINCTRL_ROCKCHIP</code>
** GPIO and general SoC support
* <code>CONFIG_PWM_ROCKCHIP</code>
** PWM support
* <code>CONFIG_ROCKCHIP_IOMMU</code>
** IOMMU support
* <code>CONFIG_ROCKCHIP_MBOX</code>
** Mailbox support (for communication with MCU)
* <code>CONFIG_ROCKCHIP_SARADC</code>
** Analog-to-digital conversion support, for e.g. microphones
* <code>CONFIG_ROCKCHIP_THERMAL</code>
** Temperature sensor and thermal throttling support
* <code>CONFIG_SPI_ROCKCHIP</code>
** SPI support
* <code>CONFIG_VIDEO_HANTRO_ROCKCHIP</code>
** Hardware video decoder support
* <code>CONFIG_ROCKCHIP_IODOMAIN</code>
** General SoC support so your I/O pins have the right voltage
* <code>CONFIG_COMMON_CLK_ROCKCHIP</code>
** Common clock support
* <code>CONFIG_PHY_ROCKCHIP_INNO_CSIDPHY</code>
** MIPI CSI DPHY
* <code>CONFIG_I2C_RK3X</code>
** I2C support

== Resources ==
=== Repositories ===

* pgwipeout's kernel tree
** https://gitlab.com/pgwipeout/linux-next/-/tree/quartz64-v5.15-rc1
* BSP based development effort for SPL/U-Boot and Linux
** https://gitlab.com/pine64-org/quartz-bsp
* Image CI pipeline aimed at developers
** https://gitlab.com/pgwipeout/quartz64_ci/
* Rockchip U-Boot
** https://github.com/rockchip-linux/u-boot
* Downstream rockchip-linux kernel tree
** https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux
* Tianocore EDK II port for UEFI on Quartz64
** https://github.com/jaredmcneill/quartz64_uefi
* Mainline U-Boot Port by pgwipeout
** https://gitlab.com/pgwipeout/u-boot-quartz64

=== Other ===

* Rockchip-SoC Patchwork Page
** https://patchwork.kernel.org/project/linux-rockchip/list/
* Rockchip Kernel Mailing List Archive
** https://lore.kernel.org/linux-rockchip/

== Board/SoC Documentation ==
=== Booting ===
==== Boot Order ====
The RK3566 boot ROM will search for a valid ID BLOCK in the following order on the support boot media:

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

... if this fails, the boot ROM will initialize the USB0 port and wait for a connection from the Rockchip
flash/boot tools.

==== Bootloader Flashing ====

As per pgwipeout's [https://gitlab.com/pine64-org/quartz-bsp/u-boot/-/commit/12d102b86813378af08b086f3b9c13ed8010754c commit message]:
* Make a partition named <code>uboot</code> as partition number 1 at 8 MiB to 16 MiB
* <code>dd if=idblock.bin of=/dev/''<mmc/sd>'' seek=64</code>
* <code>dd if=uboot.img of=/dev/''<mmc/sd>''1</code>

==== BSP Image Layout ====

[[Category:Quartz64]][[Category:Rockchip RK3566]]

Quartz64

2023-08-31T11:56:33Z

CounterPillow: /* Network */ Add information on performance

[[File:Quartz64modelb.png|400px|thumb|right|The Quartz64 Model B]]

The '''Quartz64''' is the most recent Single Board Computer offering from PINE64, with Model A initially released in June of 2021 and Model B in May of 2022. It is powered by a Rockchip RK3566 Quad-Core ARM Cortex A55 64-Bit Processor with a MALI G-52 GPU.

Key features include a PCIe x4 open ended slot (model A) or m.2 (model B) using one Gen2 lane electrically, and the use of LPDDR4 RAM.

The Quartz64 has three LPDDR4 system memory options: 2GB, 4GB or 8GB. For booting, there is an eMMC module socket (supporting up to 128GB) and microSD slot, as well as a footprint to solder on an SPI flash chip. The board is equipped with HDMI, 1x USB 3.0 type A Host, 3x USB 2.0 Host, Gigabit Ethernet, SATA (model A), GPIO Bus, MiPi DSI interface, e-ink interface (model A), eDP interface (model A), touch Panel interface (model A), MiPi CSI interface, as well as many other device interfaces such as UART, SPI, I2C, for makers to integrate with sensors and other peripherals. Many different Operating Systems (OS) are freely available from the open source community, such as Linux (Ubuntu, Debian, Arch), BSD, and Android.

== Software releases ==

Under [[Quartz64 Software Releases]] you will find a complete list of currently supported operating system images, which work with the Quartz64, as well as other related software.

== Getting started ==

=== Flashing the device ===

Natively the board only supports booting the platform firmware from SPI, the eMMC or a microSD card, see [[#Boot order|boot order]]. The platform firmware loaded from there (U-Boot, EDK2, ...) may then allow loading kernels from additional storage mediums or even the network, and they will have their own boot order.

The board can be booted by flashing your chosen operating system to a microSD card using another device and inserting the microSD card into the Quartz64, see the article [[Getting started]]. Flashing the eMMC is possible by booting an operating system from the microSD card and overwriting the eMMC from within the booted operating system, or by using [https://pine64.com/product/usb-adapter-for-emmc-module/ the USB eMMC adapter].

=== Boot order ===

The hardware boot order of the Quartz64 is:

# SPI NOR flash
# SPI NAND flash
# eMMC
# microSD card

== SoC and Memory Specifications ==

[[File:RK3566_icon.png|right]]

* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]

=== CPU Architecture ===

* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache
* [https://developer.arm.com/ip-products/security-ip/trustzone TrustZone] technology support
* [https://www.cnx-software.com/2020/12/01/rockchip-rk3568-processor-to-power-edge-computing-and-nvr-applications 22nm process, believed to be FD-SOI]

=== GPU (Graphics Processing Unit) Capabilities ===

* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== NPU (Neural Processing Unit) Capabilities ===

* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===

* RAM Memory Variants: 2GB (SOQuartz only), 4GB, 8GB LPDDR4.

=== Network ===

* 10/100/1000Mbps Ethernet
** Easily sustains >910 Mbit/s in a <code>--bidir</code> (i.e. sending and receiving at the same time) iperf3 TCP test.
* Wi-Fi 802.11 b/g/n/ac with Bluetooth 5.0 (optional on model A, built in on model B)

=== Storage ===

* microSD - bootable, supports SDHC and SDXC, storage up to 2TB
* USB
** Model A: 2 USB 2.0 host ports, 1 USB 2.0 OTG port, 1 USB 3.0 host port
** Model B: 1 USB 2.0 host port, 1 USB 2.0 OTG port, 1 USB 3.0 host port
* one native SATA 3.0 6Gb/s Port (only on model A, shared with USB 3.0 host port) (removed in newer revisions due to electrical signalling issues it caused)
* optional eMMC module from 8GB up to 128GB
* 64 Mbit (8 MByte) SPI flash (Model B only), part number '''25Q64DWZPIG''' in the schematic

==== eMMC Speeds ====

On a 64 GB eMMC module:

$ sudo hdparm -tT /dev/mmcblk1

/dev/mmcblk1:
Timing cached reads: 2368 MB in 2.00 seconds = 1184.46 MB/sec
Timing buffered disk reads: 452 MB in 3.01 seconds = 149.98 MB/sec

=== Expansion Ports ===
* HDMI
* eDP - 4 lanes of 2.7Gbps, up to 2560x1600@60Hz (only on model A)
* DSI - Display Serial Interface, 4 lanes MiPi, up to 1440P on model A, 2 lanes MiPi, up to 1080p on model B
* CSI - CMOS Camera Interface, 4 lanes MiPi up to 8 mega pixel on model A, 2 lanes MiPi up to 5 mega pixel on model B
* TP - Touch Panel Port, SPI with interrupt on model A
* RTC - Real Time Clock Battery Connector
* VBAT - Lithium Battery Connector with temperature sensor input on model A
* Wi-Fi/BT Module Header - SDIO 3.0 and UART on model A, built-in Wi-Fi/BT Module on model B
* 2x20 pins "Pi2" GPIO Header on model B, 2x10 pins GPO header on model A
* PCIe x4 open ended slot on model A, m.2 slot on model B, one Gen2 lane due to SoC constraints
** On Model A, the slot provides 10W of power for the 3.3V supply and however much power your 12V input power supply provides on the 12V supply

The PCIe implementation on the RK3566 is much more compatible with a wide range of devices compared to the one on the RK3399 used on the ROCKPro64. This means a lot more devices should work (excluding dGPUs due to a lack of cache snooping ability).

==== Combo PHYs ====

[[File:rk3566 phy.png|400px]]

Several of the I/O options on the RK3566 used in the Quartz64 are using the same I/O lines, meaning that they cannot be used at the same time. The above diagram illustrates how they are connected.

In particular, USB 3.0 and the SATA connector on the board are mutually exclusive, and the PCI-e 2.0 lane can be reconfigured into a second SATA port, though an adapter cable needs to be fashioned for this to be useful.

=== GPIO Pins (Quartz64 Model A) ===

Attention! GPIOs are 3.3V!

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SDA_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SCL_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| CPU_REFCLK_OUT
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX_M0_DEBUG
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX_M0_DEBUG
|-
| style="text-align:right;"| SPI1_MOSI_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| UART0_TX a
|-
| style="text-align:right;"| SPI1_MISO_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| UART0_RX a
|-
| style="text-align:right;"| SPI1_CLK_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GND
|-
| style="text-align:right;"| SPI1_CS0_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 17
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| SPDIF_OUT c
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| 3.3V
|}

==== Notes ====
<ol style="list-style-type:lower-alpha">

<li>can be a PWM pin</li>

<li>pulled high to 3.3V through 2.2kOhm resistor</li>

<li>low-pass filtered with cutoff of 220 MHz</li>

</ol>

Source: Page 28 of [[File:Quartz64_model-A_schematic_v1.0_20201215.pdf|the board schematics]].

=== GPIO Pins (Quartz64 Model B) ===

Attention! GPIOs are 3.3V!

Interesting alternate pin configurations are listed in [brackets].

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 1
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SDA_M0]'' GPIO1_A0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SCL_M0]'' GPIO1_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_C4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX
|-
| style="text-align:right;"| ''[SPI1_CS0_M1]'' GPIO3_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| GPIO3_A3_3V3 ''[I2S3_SCLK_M0]''
|-
| style="text-align:right;"| ''[I2S3_MCLK_M0]'' GPIO3_A2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GPIO3_B1_3V3
|-
| style="text-align:right;"| 3.3V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 17
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| GPIO3_B2_3V3
|-
| style="text-align:right;"| GPIO4_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO4_C5_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 21
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 22
| style="text-align:left;"| GPIO3_C1_3V3 ''[SPI1_MOSI_M1]''
|-
| style="text-align:right;"| GPIO4_C2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 23
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 24
| style="text-align:left;"| GPIO4_C6_3V3
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 25
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 26
| style="text-align:left;"| GPIO4_D1_3V3
|-
| style="text-align:right;"| I2C4_SDA_M0
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 27
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 28
| style="text-align:left;"| I2C4_SCL_M0
|-
| style="text-align:right;"| GPIO3_B3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 29
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 30
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 31
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 32
| style="text-align:left;"| GPIO3_C2_3V3 ''[SPI1_MISO_M1]''
|-
| style="text-align:right;"| ''[SPI1_CLK_M1]'' GPIO3_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 33
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 34
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[I2S3_LRCK_M0]'' GPIO3_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 35
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 36
| style="text-align:left;"| GPIO3_A7_3V3
|-
| style="text-align:right;"| ''[SPDIF_TX_M0]'' GPIO1_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 37
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 38
| style="text-align:left;"| GPIO3_A6_3V3 ''[I2S3_SDI_M0]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 39
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 40
| style="text-align:left;"| GPIO3_A5_3V3 ''[I2S3_SDO_M0]''
|}

Source: Page 24 of [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf the board schematics].

== Quartz64 Board Information, Schematics, and Certifications ==

=== Model "A" ===

Model "A" Baseboard Dimensions: 133mm x 80mm x 19mm

Input Power: DC 12V @ 3A 5.5mmOD/2.1mmID center-positive Barrel DC Jack connector

Quartz64 Model "A" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_schematic_v2.0_20210427.pdf Quartz64 Model "A" SBC Schematic ver 2.0 20210427 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_V2.0_connector_placement.pdf Quartz64 Model "A" SBC PCB Connector placement PDF file]

Certifications:

* Disclaimer: Please note that PINE64 SBC is not a "final" product and in general certification is not necessary. However, PINE64 still submit the SBC for FCC and CE certification and obtain the certificates to proof that SBC board is capable on passing the testing. Please note a final commercial product needs to performs its owns testing and obtains its owns certificates.
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20CE%20certification-S21051101701001.pdf Quartz64 model-A CE Certificate]
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20FCC%20certification-S21051101702001.pdf Quartz64 model-A FCC Certificate]

=== Model "B" ===

Model "B" Baseboard Dimensions: 85mm x 56mm x 18.8mm

Input Power: DC 5V @ 3A 3.5mmOD/1.35mmID center-positive Barrel DC Jack connector

Quartz64 Model "B" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf Quartz64 Model "B" SBC Schematic ver 1.3 20220124 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_PCB_Components_Placement-V1.2_20211014.pdf Quartz64 Model "B" SBC PCB Connector placement PDF file]
* Please note that v1.2 and V1.3 schematic and component placement are identical, just some component value changed.
* Note: Model B uses a Molex PicoBlade compatible connector for the RTC battery. The Pine64 Backup Battery Holders come with a JST PH type connector. To use the Pine64 RTC Backup Battery Holder, the connector on the battery holder will need to be modified with a PicoBlade type connector.

== Datasheets for Components and Peripherals ==

Rockchip RK3566 SoC information:
* [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, already got release permission from Rockchip]
* [https://opensource.rock-chips.com/images/2/26/Rockchip_RK3568_TRM_Part1_V1.3-20220930P.PDF Rockchip RK3566 and RK3568 TRM (Technical Reference Manual)]

Rockchip PMU (Power Management Unit) Information:
* [https://www.rockchip.fr/RK817%20datasheet%20V1.01.pdf Rockchip RK817 ver 1.01 datasheet for Quartz64 model A]
* [https://www.rockchip.fr/RK809%20datasheet%20V1.01.pdf Rockchip RK809 ver 1.01 datasheet for Quartz64 model B and SOQuartz]

LPDDR4 (200 Balls) SDRAM:
* [https://files.pine64.org/doc/datasheet/rockpro64/SM512M32Z01MD2BNP(200BALL).pdf Micron LPDDR4 Mobile LPDDR4 Datasheet]

eMMC information:
* [https://files.pine64.org/doc/rock64/PINE64_eMMC_Module_20170719.pdf PINE64 eMMC module schematic]
* [https://files.pine64.org/doc/rock64/usb%20emmc%20module%20adapter%20v2.pdf PINE64 USB adapter for eMMC module V2 schematic]
* [https://files.pine64.org/doc/rock64/USB%20adapter%20for%20eMMC%20module%20PCB.tar PINE64 USB adapter for eMMC module PCB in JPEG]
* [https://files.pine64.org/doc/datasheet/pine64/E-00517%20FORESEE_eMMC_NCEMAM8B-16G%20SPEC.pdf 16GB Foresee eMMC Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/SDINADF4-16-128GB-H%20data%20sheet%20v1.13.pdf 32GB/64GB/128GB SanDisk eMMC Datasheet]

SPI NOR Flash information:
* [https://files.pine64.org/doc/datasheet/pine64/w25q128jv%20spi%20revc%2011162016.pdf WinBond 128Mb SPI Flash Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/GD25Q128C-Rev2.5.pdf GigaDevice 128Mb SPI Flash Datasheet]

E-ink Panel information:
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-754-V3_ES103TC1%20Specification%20V3.0(Signed)-20190702.pdf Eink 10.3" 1872x1404 ES103TC1 Flex Panel Specification]
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-828-V1_ED103TC2%20Formal%20Spec%20V1.0_20190514.pdf Eink 10.3" 1872x1404 ES103TC1 Glass Panel Specification]
* [https://files.pine64.org/doc/datasheet/PineNote/TI%20PMU-TPS651851.pdf TPS65185x PMIC for E-Ink Enabled Electronic Paper Display Datasheet]

LCD Touch Screen Panel information:
* [https://files.pine64.org/doc/datasheet/pine64/FY07024DI26A30-D_feiyang_LCD_panel.pdf 7.0" 1024x600 TFT-LCD Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/HK70DR2459-PG-V01.pdf Touch Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/GT911%20Capacitive%20Touch%20Controller%20Datasheet.pdf GOODiX GT911 5-Point Capacitive Touch Controller Datasheet]

Ethernet PHY information:
* [https://files.pine64.org/doc/datasheet/pine64/rtl8211e(g)-vb(vl)-cg_datasheet_1.6.pdf Realtek RTL8211 10/100/1000M Ethernet Transceiver]

Wi-Fi/BT module info:
* [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC Wi-Fi + Bluetooth5.0 Datasheet]

IR LED:
* [https://media.digikey.com/pdf/Data%20Sheets/Everlight%20PDFs/IRM-36xx_Series.pdf IRM-3638 Datasheet]

Enclosure information:
* [https://files.pine64.org/doc/datasheet/case/playbox_enclosure_20160426.stp Playbox Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/ABS_enclosure_20160426.stp ABS Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/pine64%20Die%20Cast%20casing-final.jpg Outdoor Aluminum Cast Dust-proof IP67 Enclosure Drawing]
* [https://www.printables.com/model/269572-pine-quartz-64-a-full-case 3D Printable Enclosure for Model A]
* [https://www.printables.com/model/269575-pine-quartz-64-a-open-frame Open Frame for Model A]

Connector information:
* [https://files.pine64.org/doc/datasheet/pine64/ePH.pdf 2.0mm PH Type connector specification use in Lithium Battery (VBAT) port (Model A)]
* [https://www.molex.com/pdm_docs/sd/533980271_sd.pdf 1.25mm Picoblade Type connector specification used in RTC Battery port (Model B)]
* [https://files.pine64.org/doc/datasheet/pine64/0.5FPC%20Front%20Open%20Connector%20H=1.5.pdf 0.5mm Pitch cover type FPC connector specification use in DSI port, TP port and CSI port]

== Development efforts ==

{{SeeMainArticle|Quartz64 Development}}

Information and resources of the ongoing development effort for the Quartz64 can be found on the [[Quartz64 Development]] page, where the current status of various board functions can be found, and whether they have landed in upstream.

* [https://gitlab.com/pine64-org/quartz-bsp Quartz64 BSP Gitlab Page]

== Enclosures ==

Note: Please expand this section with more cases known to work.

=== Model "A" ===

All enclosures that fit the ROCKPro64 should fit the Quartz64 Model "A", as the I/O has been laid out the same on purpose.

* [[Model A Acrylic Open Enclosure]] - but see the troubleshooting section below.
* [[Quartz64 Premium Aluminium Case|RockPro64 Premium Aluminium Case]]
* [[ROCKPro64#3D printable ITX mounting brackets]] (Not an enclosure but allows to mount the board in an ATX/ITX case)

=== Model "B" ===

* [[Model B Acrylic Open Enclosure]]
* the ROCK64 aluminium enclosure '''does not''' work, as the DC input jack is placed differently

== Troubleshooting ==

=== Stability/Boot Issues With Missing Battery Shunt ===

If there is no battery plugged into the board, the jumper labelled "ON/OFF_BATT" must be in place. If this is set wrong, stability issues such as failures to boot will occur. '''This affects model A only'''

=== No Ethernet Connectivity ===

Make sure the kernel is built with <code>CONFIG_MOTORCOMM_PHY</code> set to <code>y</code>. Building it as a module (<code>m</code>) and then relying on module auto-loading is unlikely to work, because if the generic PHY driver is built in it will bind to the PHY first, unless you include the motorcomm module in your initramfs.

Note: Starting with [https://salsa.debian.org/kernel-team/linux/-/merge_requests/551 Debian's <code>6.1~rc3-1~exp1</code> kernel] the module is included, but set to <code>m</code> and I (Diederik) have verified that it gets included in the initramfs and '''works''' on Model-A and Model-B with the [[Quartz64#Plebian]] images.

=== "Model A" Acrylic Case Doesn't Fit ===

The Quartz64 does not really fit onto the bottom plate of the [[Model A Acrylic Open Enclosure]]. This is because the "Mic" connector at the bottom of the board interferes with one of the posts. A workaround is to find out which post that is (you have a 50% chance of guessing it right, accounting for rotating the board) and then filing away the corner of the post pointing inwards by a few millimeters.

[[File:Quartz64-audio-jack-spacer-issue.jpg|400px]]

An alternate solution may be to place plastic spacers with a smaller outer diameter in between the acrylic bottom plate posts and the SBC board.

=== No GPU Acceleration with Debian "Bullseye" Userland ===

Debian Bullseye ships a Mesa version that is too old to contain the required patches for the RK356x SoC's GPU. You can (at your own risk) [https://wiki.debian.org/DebianTesting use the current Debian Testing version ], called "Bookworm".

=== Wireless Connectivity Doesn't Work ===

ROCKPro64 wireless module may have CYW43455 or CYW43456 chips on board (not sure if this is the same for Quartz64 model B). Both chips are supported by <code>brcmfmac</code> Wi-Fi driver and <code>btbcm</code> Bluetooth driver.

For CYW43455 drivers attempt to load <code>/lib/firmware/brcm/brcmfmac43455-sdio.bin</code> for Wi-Fi and <code>/lib/firmware/brcm/BCM4345C0.hcd</code> for Bluetooth. Corresponding firmware files for CYW43456 are <code>/lib/firmware/brcm/brcmfmac43456-sdio.bin</code> and <code>/lib/firmware/brcm/BCM4345C5.hcd</code>.

On Manjaro firmware files for both Bluetooth and Wi-Fi on CYW43456 on are provided by <code>ap6256-firmware</code> package (<code>pacman -S ap6256-firmware</code>).

However for CYW43455 wi-fi firmware is in the <code>linux-firmware</code> package and bluetooth is in the <code>firmware-raspberrypi</code> (<code>pacman -S linux-firmware firmware-raspberrypi</code>). <code>linux-firmware</code> package is missing device specific symlinks for quartz64-a. To create them execute:

# ln -s brcmfmac43455-sdio.bin /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.bin
# ln -s brcmfmac43455-sdio.AW-CM256SM.txt /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.txt

As of 2022-10-19 device tree in mainline kernel for Quartz64 model A has wrong configuration for the Bluetooth driver. [https://patchwork.kernel.org/project/linux-rockchip/patch/20220926125350.64783-1-leo@nabam.net/ Patch] is submitted to the LKML and accepted and included upstream in 6.1-rc7. It's possible to modify dtb file provided by the current kernel using device tree compiler to enable Bluetooth or perform <code>make dtbs</code> in the patched kernel tree to get updated dtb file (<code>arch/arm64/boot/dts/rockchip/rk3566-quartz64-a.dtb</code>). Issue manifests itself with following errors in `dmesg`:

command 0x0c03 tx timeout
Bluetooth: hci0: BCM: Reset failed (-110)

== How-To ==

=== Connect Debug UART ===

The easiest way to get debug output is to connect a 3.3V 1.5mbaud capable UART adapter to the board.

To connect it, connect the ground lead to pin 6, and the RX/TX leads to pins 8 and 10 (consider swapping them if you get no output, things are often mislabeled). These pins are "UART2" in the above GPIO table.

Open a serial terminal at 1500000 bauds, e.g.

$ picocom -b 1500000 /dev/ttyUSB0

=== Disable Heartbeat LED (Linux) ===

The flashing LED is called the "heartbeat LED", it blinks in a heart rhythm like fashion once the kernel is running. To disable it, you can run

# echo none > /sys/class/leds/user-led/trigger

On model A LED device is called "diy-led", not "user-led".

On a system with systemd, you can do this as soon as the system is ready to be logged in with a systemd unit like this:

[Unit]
Description=Turn off heartbeat LED
Wants=multi-user.target
After=multi-user.target

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
ExecStart=sh -c 'echo none > /sys/class/leds/user-led/trigger'

Place it in ''/etc/systemd/system/user-led.service'', and run

# systemctl daemon-reload
# systemctl enable user-led.service

Upon rebooting, you will now notice that the heartbeat LED will blink during boot-up, but stops blinking as soon as the multi-user target is reached (i.e. the user can log in).

=== SATA on model A ===

On model A USB 3.0 and SATA ports are using the same I/O line and can't be used simultaneously. By default USB 3.0 is enabled in Linux device tree and SATA is disabled. FDT modifications are required to turn SATA on.

Following script is tested on Manjaro but should work on the other distributions with minimal changes. Device tree compiler package usually provides fdtput command (on Manjaro run: <code>pacman -S dtc</code>)

# cp /boot/dtbs/rockchip/rk3566-quartz64-a.dtb /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /usb@fd000000 status disabled
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /sata@fc400000 status okay
# sed -i 's#^FDT /dtbs/rockchip/rk3566-quartz64-a.dtb$#FDT /dtbs/rockchip/rk3566-quartz64-a-sata.dtb#' /boot/extlinux/extlinux.conf
# systemctl reboot

=== Using a PCF8574 on Model A ===

See [[Quartz64 Model A using a PCF8574]].

=== Using a battery on Model A ===

See [[Quartz64 Model A Using a battery]].

=== Connecting a MIPI-DSI display ===

See [[Quartz64 connecting a MIPI-DSI display]].

=== Building Mainline U-Boot ===

See [[Quartz64 Building U-Boot]].

== Frequently Asked Questions ==

=== Do I Need A Fan/What Heatsink Do I Need? ===

You don't need a fan. The [https://pine64.com/product/rockpro64-20mm-mid-profile-heatsink/ 20mm medium heatsink for Model A is plenty enough]. For Model B, the [https://pine64.com/product/small-fan-type-heatsink/ fan type heatsink] will do fine.

=== Can This Run A Minecraft Server? ===

Yes! Sort of. Testing on an 8GB Model A with PaperMC, [[User:CounterPillow]] was able to out-row world generation in a boat with just one player online, but aside from the slow world gen (which can be pre-generated) the server handled things like TNT explosions and mobs fine. It'll probably do okay with 1-3 players.

=== Do I Need The 5A Power Supply For Model A? ===

You only need the 5A power supply for Model A if you plan on connecting hard disk drives to the 12V header on the board.

=== How Much Power Does It Consume? ===

For Model B, it's <2W in idle (powertop tunables not set), and <5W under full CPU load (<code>stress-ng -c4</code>). Model A will be similar as it's the same SoC.

[[Category:Quartz64]] [[Category:Rockchip RK3566]]

Quartz64

2023-08-31T11:36:26Z

CounterPillow: /* Getting started */ reword, more info

[[File:Quartz64modelb.png|400px|thumb|right|The Quartz64 Model B]]

The '''Quartz64''' is the most recent Single Board Computer offering from PINE64, with Model A initially released in June of 2021 and Model B in May of 2022. It is powered by a Rockchip RK3566 Quad-Core ARM Cortex A55 64-Bit Processor with a MALI G-52 GPU.

Key features include a PCIe x4 open ended slot (model A) or m.2 (model B) using one Gen2 lane electrically, and the use of LPDDR4 RAM.

The Quartz64 has three LPDDR4 system memory options: 2GB, 4GB or 8GB. For booting, there is an eMMC module socket (supporting up to 128GB) and microSD slot, as well as a footprint to solder on an SPI flash chip. The board is equipped with HDMI, 1x USB 3.0 type A Host, 3x USB 2.0 Host, Gigabit Ethernet, SATA (model A), GPIO Bus, MiPi DSI interface, e-ink interface (model A), eDP interface (model A), touch Panel interface (model A), MiPi CSI interface, as well as many other device interfaces such as UART, SPI, I2C, for makers to integrate with sensors and other peripherals. Many different Operating Systems (OS) are freely available from the open source community, such as Linux (Ubuntu, Debian, Arch), BSD, and Android.

== Software releases ==

Under [[Quartz64 Software Releases]] you will find a complete list of currently supported operating system images, which work with the Quartz64, as well as other related software.

== Getting started ==

=== Flashing the device ===

Natively the board only supports booting the platform firmware from SPI, the eMMC or a microSD card, see [[#Boot order|boot order]]. The platform firmware loaded from there (U-Boot, EDK2, ...) may then allow loading kernels from additional storage mediums or even the network, and they will have their own boot order.

The board can be booted by flashing your chosen operating system to a microSD card using another device and inserting the microSD card into the Quartz64, see the article [[Getting started]]. Flashing the eMMC is possible by booting an operating system from the microSD card and overwriting the eMMC from within the booted operating system, or by using [https://pine64.com/product/usb-adapter-for-emmc-module/ the USB eMMC adapter].

=== Boot order ===

The hardware boot order of the Quartz64 is:

# SPI NOR flash
# SPI NAND flash
# eMMC
# microSD card

== SoC and Memory Specifications ==

[[File:RK3566_icon.png|right]]

* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]

=== CPU Architecture ===

* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache
* [https://developer.arm.com/ip-products/security-ip/trustzone TrustZone] technology support
* [https://www.cnx-software.com/2020/12/01/rockchip-rk3568-processor-to-power-edge-computing-and-nvr-applications 22nm process, believed to be FD-SOI]

=== GPU (Graphics Processing Unit) Capabilities ===

* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== NPU (Neural Processing Unit) Capabilities ===

* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===

* RAM Memory Variants: 2GB (SOQuartz only), 4GB, 8GB LPDDR4.

=== Network ===

* 10/100/1000Mbps Ethernet
* Wi-Fi 802.11 b/g/n/ac with Bluetooth 5.0 (optional on model A, built in on model B)

=== Storage ===

* microSD - bootable, supports SDHC and SDXC, storage up to 2TB
* USB
** Model A: 2 USB 2.0 host ports, 1 USB 2.0 OTG port, 1 USB 3.0 host port
** Model B: 1 USB 2.0 host port, 1 USB 2.0 OTG port, 1 USB 3.0 host port
* one native SATA 3.0 6Gb/s Port (only on model A, shared with USB 3.0 host port) (removed in newer revisions due to electrical signalling issues it caused)
* optional eMMC module from 8GB up to 128GB
* 64 Mbit (8 MByte) SPI flash (Model B only), part number '''25Q64DWZPIG''' in the schematic

==== eMMC Speeds ====

On a 64 GB eMMC module:

$ sudo hdparm -tT /dev/mmcblk1

/dev/mmcblk1:
Timing cached reads: 2368 MB in 2.00 seconds = 1184.46 MB/sec
Timing buffered disk reads: 452 MB in 3.01 seconds = 149.98 MB/sec

=== Expansion Ports ===
* HDMI
* eDP - 4 lanes of 2.7Gbps, up to 2560x1600@60Hz (only on model A)
* DSI - Display Serial Interface, 4 lanes MiPi, up to 1440P on model A, 2 lanes MiPi, up to 1080p on model B
* CSI - CMOS Camera Interface, 4 lanes MiPi up to 8 mega pixel on model A, 2 lanes MiPi up to 5 mega pixel on model B
* TP - Touch Panel Port, SPI with interrupt on model A
* RTC - Real Time Clock Battery Connector
* VBAT - Lithium Battery Connector with temperature sensor input on model A
* Wi-Fi/BT Module Header - SDIO 3.0 and UART on model A, built-in Wi-Fi/BT Module on model B
* 2x20 pins "Pi2" GPIO Header on model B, 2x10 pins GPO header on model A
* PCIe x4 open ended slot on model A, m.2 slot on model B, one Gen2 lane due to SoC constraints
** On Model A, the slot provides 10W of power for the 3.3V supply and however much power your 12V input power supply provides on the 12V supply

The PCIe implementation on the RK3566 is much more compatible with a wide range of devices compared to the one on the RK3399 used on the ROCKPro64. This means a lot more devices should work (excluding dGPUs due to a lack of cache snooping ability).

==== Combo PHYs ====

[[File:rk3566 phy.png|400px]]

Several of the I/O options on the RK3566 used in the Quartz64 are using the same I/O lines, meaning that they cannot be used at the same time. The above diagram illustrates how they are connected.

In particular, USB 3.0 and the SATA connector on the board are mutually exclusive, and the PCI-e 2.0 lane can be reconfigured into a second SATA port, though an adapter cable needs to be fashioned for this to be useful.

=== GPIO Pins (Quartz64 Model A) ===

Attention! GPIOs are 3.3V!

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SDA_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SCL_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| CPU_REFCLK_OUT
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX_M0_DEBUG
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX_M0_DEBUG
|-
| style="text-align:right;"| SPI1_MOSI_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| UART0_TX a
|-
| style="text-align:right;"| SPI1_MISO_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| UART0_RX a
|-
| style="text-align:right;"| SPI1_CLK_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GND
|-
| style="text-align:right;"| SPI1_CS0_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 17
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| SPDIF_OUT c
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| 3.3V
|}

==== Notes ====
<ol style="list-style-type:lower-alpha">

<li>can be a PWM pin</li>

<li>pulled high to 3.3V through 2.2kOhm resistor</li>

<li>low-pass filtered with cutoff of 220 MHz</li>

</ol>

Source: Page 28 of [[File:Quartz64_model-A_schematic_v1.0_20201215.pdf|the board schematics]].

=== GPIO Pins (Quartz64 Model B) ===

Attention! GPIOs are 3.3V!

Interesting alternate pin configurations are listed in [brackets].

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 1
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SDA_M0]'' GPIO1_A0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SCL_M0]'' GPIO1_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_C4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX
|-
| style="text-align:right;"| ''[SPI1_CS0_M1]'' GPIO3_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| GPIO3_A3_3V3 ''[I2S3_SCLK_M0]''
|-
| style="text-align:right;"| ''[I2S3_MCLK_M0]'' GPIO3_A2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GPIO3_B1_3V3
|-
| style="text-align:right;"| 3.3V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 17
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| GPIO3_B2_3V3
|-
| style="text-align:right;"| GPIO4_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO4_C5_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 21
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 22
| style="text-align:left;"| GPIO3_C1_3V3 ''[SPI1_MOSI_M1]''
|-
| style="text-align:right;"| GPIO4_C2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 23
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 24
| style="text-align:left;"| GPIO4_C6_3V3
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 25
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 26
| style="text-align:left;"| GPIO4_D1_3V3
|-
| style="text-align:right;"| I2C4_SDA_M0
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 27
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 28
| style="text-align:left;"| I2C4_SCL_M0
|-
| style="text-align:right;"| GPIO3_B3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 29
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 30
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 31
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 32
| style="text-align:left;"| GPIO3_C2_3V3 ''[SPI1_MISO_M1]''
|-
| style="text-align:right;"| ''[SPI1_CLK_M1]'' GPIO3_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 33
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 34
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[I2S3_LRCK_M0]'' GPIO3_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 35
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 36
| style="text-align:left;"| GPIO3_A7_3V3
|-
| style="text-align:right;"| ''[SPDIF_TX_M0]'' GPIO1_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 37
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 38
| style="text-align:left;"| GPIO3_A6_3V3 ''[I2S3_SDI_M0]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 39
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 40
| style="text-align:left;"| GPIO3_A5_3V3 ''[I2S3_SDO_M0]''
|}

Source: Page 24 of [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf the board schematics].

== Quartz64 Board Information, Schematics, and Certifications ==

=== Model "A" ===

Model "A" Baseboard Dimensions: 133mm x 80mm x 19mm

Input Power: DC 12V @ 3A 5.5mmOD/2.1mmID center-positive Barrel DC Jack connector

Quartz64 Model "A" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_schematic_v2.0_20210427.pdf Quartz64 Model "A" SBC Schematic ver 2.0 20210427 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_V2.0_connector_placement.pdf Quartz64 Model "A" SBC PCB Connector placement PDF file]

Certifications:

* Disclaimer: Please note that PINE64 SBC is not a "final" product and in general certification is not necessary. However, PINE64 still submit the SBC for FCC and CE certification and obtain the certificates to proof that SBC board is capable on passing the testing. Please note a final commercial product needs to performs its owns testing and obtains its owns certificates.
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20CE%20certification-S21051101701001.pdf Quartz64 model-A CE Certificate]
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20FCC%20certification-S21051101702001.pdf Quartz64 model-A FCC Certificate]

=== Model "B" ===

Model "B" Baseboard Dimensions: 85mm x 56mm x 18.8mm

Input Power: DC 5V @ 3A 3.5mmOD/1.35mmID center-positive Barrel DC Jack connector

Quartz64 Model "B" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf Quartz64 Model "B" SBC Schematic ver 1.3 20220124 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_PCB_Components_Placement-V1.2_20211014.pdf Quartz64 Model "B" SBC PCB Connector placement PDF file]
* Please note that v1.2 and V1.3 schematic and component placement are identical, just some component value changed.
* Note: Model B uses a Molex PicoBlade compatible connector for the RTC battery. The Pine64 Backup Battery Holders come with a JST PH type connector. To use the Pine64 RTC Backup Battery Holder, the connector on the battery holder will need to be modified with a PicoBlade type connector.

== Datasheets for Components and Peripherals ==

Rockchip RK3566 SoC information:
* [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, already got release permission from Rockchip]
* [https://opensource.rock-chips.com/images/2/26/Rockchip_RK3568_TRM_Part1_V1.3-20220930P.PDF Rockchip RK3566 and RK3568 TRM (Technical Reference Manual)]

Rockchip PMU (Power Management Unit) Information:
* [https://www.rockchip.fr/RK817%20datasheet%20V1.01.pdf Rockchip RK817 ver 1.01 datasheet for Quartz64 model A]
* [https://www.rockchip.fr/RK809%20datasheet%20V1.01.pdf Rockchip RK809 ver 1.01 datasheet for Quartz64 model B and SOQuartz]

LPDDR4 (200 Balls) SDRAM:
* [https://files.pine64.org/doc/datasheet/rockpro64/SM512M32Z01MD2BNP(200BALL).pdf Micron LPDDR4 Mobile LPDDR4 Datasheet]

eMMC information:
* [https://files.pine64.org/doc/rock64/PINE64_eMMC_Module_20170719.pdf PINE64 eMMC module schematic]
* [https://files.pine64.org/doc/rock64/usb%20emmc%20module%20adapter%20v2.pdf PINE64 USB adapter for eMMC module V2 schematic]
* [https://files.pine64.org/doc/rock64/USB%20adapter%20for%20eMMC%20module%20PCB.tar PINE64 USB adapter for eMMC module PCB in JPEG]
* [https://files.pine64.org/doc/datasheet/pine64/E-00517%20FORESEE_eMMC_NCEMAM8B-16G%20SPEC.pdf 16GB Foresee eMMC Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/SDINADF4-16-128GB-H%20data%20sheet%20v1.13.pdf 32GB/64GB/128GB SanDisk eMMC Datasheet]

SPI NOR Flash information:
* [https://files.pine64.org/doc/datasheet/pine64/w25q128jv%20spi%20revc%2011162016.pdf WinBond 128Mb SPI Flash Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/GD25Q128C-Rev2.5.pdf GigaDevice 128Mb SPI Flash Datasheet]

E-ink Panel information:
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-754-V3_ES103TC1%20Specification%20V3.0(Signed)-20190702.pdf Eink 10.3" 1872x1404 ES103TC1 Flex Panel Specification]
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-828-V1_ED103TC2%20Formal%20Spec%20V1.0_20190514.pdf Eink 10.3" 1872x1404 ES103TC1 Glass Panel Specification]
* [https://files.pine64.org/doc/datasheet/PineNote/TI%20PMU-TPS651851.pdf TPS65185x PMIC for E-Ink Enabled Electronic Paper Display Datasheet]

LCD Touch Screen Panel information:
* [https://files.pine64.org/doc/datasheet/pine64/FY07024DI26A30-D_feiyang_LCD_panel.pdf 7.0" 1024x600 TFT-LCD Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/HK70DR2459-PG-V01.pdf Touch Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/GT911%20Capacitive%20Touch%20Controller%20Datasheet.pdf GOODiX GT911 5-Point Capacitive Touch Controller Datasheet]

Ethernet PHY information:
* [https://files.pine64.org/doc/datasheet/pine64/rtl8211e(g)-vb(vl)-cg_datasheet_1.6.pdf Realtek RTL8211 10/100/1000M Ethernet Transceiver]

Wi-Fi/BT module info:
* [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC Wi-Fi + Bluetooth5.0 Datasheet]

IR LED:
* [https://media.digikey.com/pdf/Data%20Sheets/Everlight%20PDFs/IRM-36xx_Series.pdf IRM-3638 Datasheet]

Enclosure information:
* [https://files.pine64.org/doc/datasheet/case/playbox_enclosure_20160426.stp Playbox Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/ABS_enclosure_20160426.stp ABS Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/pine64%20Die%20Cast%20casing-final.jpg Outdoor Aluminum Cast Dust-proof IP67 Enclosure Drawing]
* [https://www.printables.com/model/269572-pine-quartz-64-a-full-case 3D Printable Enclosure for Model A]
* [https://www.printables.com/model/269575-pine-quartz-64-a-open-frame Open Frame for Model A]

Connector information:
* [https://files.pine64.org/doc/datasheet/pine64/ePH.pdf 2.0mm PH Type connector specification use in Lithium Battery (VBAT) port (Model A)]
* [https://www.molex.com/pdm_docs/sd/533980271_sd.pdf 1.25mm Picoblade Type connector specification used in RTC Battery port (Model B)]
* [https://files.pine64.org/doc/datasheet/pine64/0.5FPC%20Front%20Open%20Connector%20H=1.5.pdf 0.5mm Pitch cover type FPC connector specification use in DSI port, TP port and CSI port]

== Development efforts ==

{{SeeMainArticle|Quartz64 Development}}

Information and resources of the ongoing development effort for the Quartz64 can be found on the [[Quartz64 Development]] page, where the current status of various board functions can be found, and whether they have landed in upstream.

* [https://gitlab.com/pine64-org/quartz-bsp Quartz64 BSP Gitlab Page]

== Enclosures ==

Note: Please expand this section with more cases known to work.

=== Model "A" ===

All enclosures that fit the ROCKPro64 should fit the Quartz64 Model "A", as the I/O has been laid out the same on purpose.

* [[Model A Acrylic Open Enclosure]] - but see the troubleshooting section below.
* [[Quartz64 Premium Aluminium Case|RockPro64 Premium Aluminium Case]]
* [[ROCKPro64#3D printable ITX mounting brackets]] (Not an enclosure but allows to mount the board in an ATX/ITX case)

=== Model "B" ===

* [[Model B Acrylic Open Enclosure]]
* the ROCK64 aluminium enclosure '''does not''' work, as the DC input jack is placed differently

== Troubleshooting ==

=== Stability/Boot Issues With Missing Battery Shunt ===

If there is no battery plugged into the board, the jumper labelled "ON/OFF_BATT" must be in place. If this is set wrong, stability issues such as failures to boot will occur. '''This affects model A only'''

=== No Ethernet Connectivity ===

Make sure the kernel is built with <code>CONFIG_MOTORCOMM_PHY</code> set to <code>y</code>. Building it as a module (<code>m</code>) and then relying on module auto-loading is unlikely to work, because if the generic PHY driver is built in it will bind to the PHY first, unless you include the motorcomm module in your initramfs.

Note: Starting with [https://salsa.debian.org/kernel-team/linux/-/merge_requests/551 Debian's <code>6.1~rc3-1~exp1</code> kernel] the module is included, but set to <code>m</code> and I (Diederik) have verified that it gets included in the initramfs and '''works''' on Model-A and Model-B with the [[Quartz64#Plebian]] images.

=== "Model A" Acrylic Case Doesn't Fit ===

The Quartz64 does not really fit onto the bottom plate of the [[Model A Acrylic Open Enclosure]]. This is because the "Mic" connector at the bottom of the board interferes with one of the posts. A workaround is to find out which post that is (you have a 50% chance of guessing it right, accounting for rotating the board) and then filing away the corner of the post pointing inwards by a few millimeters.

[[File:Quartz64-audio-jack-spacer-issue.jpg|400px]]

An alternate solution may be to place plastic spacers with a smaller outer diameter in between the acrylic bottom plate posts and the SBC board.

=== No GPU Acceleration with Debian "Bullseye" Userland ===

Debian Bullseye ships a Mesa version that is too old to contain the required patches for the RK356x SoC's GPU. You can (at your own risk) [https://wiki.debian.org/DebianTesting use the current Debian Testing version ], called "Bookworm".

=== Wireless Connectivity Doesn't Work ===

ROCKPro64 wireless module may have CYW43455 or CYW43456 chips on board (not sure if this is the same for Quartz64 model B). Both chips are supported by <code>brcmfmac</code> Wi-Fi driver and <code>btbcm</code> Bluetooth driver.

For CYW43455 drivers attempt to load <code>/lib/firmware/brcm/brcmfmac43455-sdio.bin</code> for Wi-Fi and <code>/lib/firmware/brcm/BCM4345C0.hcd</code> for Bluetooth. Corresponding firmware files for CYW43456 are <code>/lib/firmware/brcm/brcmfmac43456-sdio.bin</code> and <code>/lib/firmware/brcm/BCM4345C5.hcd</code>.

On Manjaro firmware files for both Bluetooth and Wi-Fi on CYW43456 on are provided by <code>ap6256-firmware</code> package (<code>pacman -S ap6256-firmware</code>).

However for CYW43455 wi-fi firmware is in the <code>linux-firmware</code> package and bluetooth is in the <code>firmware-raspberrypi</code> (<code>pacman -S linux-firmware firmware-raspberrypi</code>). <code>linux-firmware</code> package is missing device specific symlinks for quartz64-a. To create them execute:

# ln -s brcmfmac43455-sdio.bin /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.bin
# ln -s brcmfmac43455-sdio.AW-CM256SM.txt /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.txt

As of 2022-10-19 device tree in mainline kernel for Quartz64 model A has wrong configuration for the Bluetooth driver. [https://patchwork.kernel.org/project/linux-rockchip/patch/20220926125350.64783-1-leo@nabam.net/ Patch] is submitted to the LKML and accepted and included upstream in 6.1-rc7. It's possible to modify dtb file provided by the current kernel using device tree compiler to enable Bluetooth or perform <code>make dtbs</code> in the patched kernel tree to get updated dtb file (<code>arch/arm64/boot/dts/rockchip/rk3566-quartz64-a.dtb</code>). Issue manifests itself with following errors in `dmesg`:

command 0x0c03 tx timeout
Bluetooth: hci0: BCM: Reset failed (-110)

== How-To ==

=== Connect Debug UART ===

The easiest way to get debug output is to connect a 3.3V 1.5mbaud capable UART adapter to the board.

To connect it, connect the ground lead to pin 6, and the RX/TX leads to pins 8 and 10 (consider swapping them if you get no output, things are often mislabeled). These pins are "UART2" in the above GPIO table.

Open a serial terminal at 1500000 bauds, e.g.

$ picocom -b 1500000 /dev/ttyUSB0

=== Disable Heartbeat LED (Linux) ===

The flashing LED is called the "heartbeat LED", it blinks in a heart rhythm like fashion once the kernel is running. To disable it, you can run

# echo none > /sys/class/leds/user-led/trigger

On model A LED device is called "diy-led", not "user-led".

On a system with systemd, you can do this as soon as the system is ready to be logged in with a systemd unit like this:

[Unit]
Description=Turn off heartbeat LED
Wants=multi-user.target
After=multi-user.target

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
ExecStart=sh -c 'echo none > /sys/class/leds/user-led/trigger'

Place it in ''/etc/systemd/system/user-led.service'', and run

# systemctl daemon-reload
# systemctl enable user-led.service

Upon rebooting, you will now notice that the heartbeat LED will blink during boot-up, but stops blinking as soon as the multi-user target is reached (i.e. the user can log in).

=== SATA on model A ===

On model A USB 3.0 and SATA ports are using the same I/O line and can't be used simultaneously. By default USB 3.0 is enabled in Linux device tree and SATA is disabled. FDT modifications are required to turn SATA on.

Following script is tested on Manjaro but should work on the other distributions with minimal changes. Device tree compiler package usually provides fdtput command (on Manjaro run: <code>pacman -S dtc</code>)

# cp /boot/dtbs/rockchip/rk3566-quartz64-a.dtb /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /usb@fd000000 status disabled
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /sata@fc400000 status okay
# sed -i 's#^FDT /dtbs/rockchip/rk3566-quartz64-a.dtb$#FDT /dtbs/rockchip/rk3566-quartz64-a-sata.dtb#' /boot/extlinux/extlinux.conf
# systemctl reboot

=== Using a PCF8574 on Model A ===

See [[Quartz64 Model A using a PCF8574]].

=== Using a battery on Model A ===

See [[Quartz64 Model A Using a battery]].

=== Connecting a MIPI-DSI display ===

See [[Quartz64 connecting a MIPI-DSI display]].

=== Building Mainline U-Boot ===

See [[Quartz64 Building U-Boot]].

== Frequently Asked Questions ==

=== Do I Need A Fan/What Heatsink Do I Need? ===

You don't need a fan. The [https://pine64.com/product/rockpro64-20mm-mid-profile-heatsink/ 20mm medium heatsink for Model A is plenty enough]. For Model B, the [https://pine64.com/product/small-fan-type-heatsink/ fan type heatsink] will do fine.

=== Can This Run A Minecraft Server? ===

Yes! Sort of. Testing on an 8GB Model A with PaperMC, [[User:CounterPillow]] was able to out-row world generation in a boat with just one player online, but aside from the slow world gen (which can be pre-generated) the server handled things like TNT explosions and mobs fine. It'll probably do okay with 1-3 players.

=== Do I Need The 5A Power Supply For Model A? ===

You only need the 5A power supply for Model A if you plan on connecting hard disk drives to the 12V header on the board.

=== How Much Power Does It Consume? ===

For Model B, it's <2W in idle (powertop tunables not set), and <5W under full CPU load (<code>stress-ng -c4</code>). Model A will be similar as it's the same SoC.

[[Category:Quartz64]] [[Category:Rockchip RK3566]]

SOQuartz Software Releases

2023-08-31T11:27:56Z

CounterPillow: Restructure heading levels, add notice

This page contains a list of all available operating systems for the [[SOQuartz]].

== Making Your Own ==

Making your own image/installation of Linux for SOQuartz is relatively easy, as all major components are mainlined. You will need:

* A build of mainline U-Boot ≥ v2023.10, see [[Quartz64 Building U-Boot]]. Flash this to sector 64 (sector size 512, so byte 32768) of your image for SD or eMMC. It's prudent to "protect" it by making a small (~16MiB) partition at this offset.
* A [https://www.kernel.org/ mainline Linux kernel] ≥ v6.2. See [[Quartz64 Development#Linux Kernel Config Options]] for the device specific kernel configuration options.
* The root filesystem of the distribution of your choice. This can be on the same filesystem as your kernel and device tree if using ''extlinux.conf''.

You can either boot the kernel through U-Boot's EFI booting, in which case it gets its device tree from U-Boot, or mark the partition containing your kernel and device tree with the legacy bootable flag and [https://u-boot.readthedocs.io/en/latest/develop/distro.html#boot-configuration-files write an ''extlinux/extlinux.conf''].

== Software Releases ==
{{note|'''Note:''' The images are provided by the PINE64 community, not by Pine Store Ltd. Most community projects currently aim at getting mainline Linux running on the board, not some vendor provided kernel that will never be receiving updates. A mainline-first approach allows for the boards to continue receiving important updates, such as security updates, for years to come, as well as have higher quality code in the kernel as it underwent independent review, but does mean that not all aspects of the hardware work right out of the gate.}}

=== DietPi support with Debian/Bullseye ===

Info and downloads: https://dietpi.com/docs/hardware/#pine64

=== Manjaro ARM ===
[[File:Manjaro-logo.svg|right|100px]]

Manjaro ARM is a user friendly rolling release distribution, based on Arch Linux ARM.

* [https://github.com/manjaro-arm/soquartz-cm4-images/releases Images for SOQuartz on GitHub]

WiFI, Bluetooth, Ethernet, HDMI USB etc. works, others are not tested.

Currently the image is built for Raspberry Pi CM4 - IO board, so to get it working with other base board like pine64 Soquartz model A base board then follow this steps
*Flash the image to a SD card/ EMMC.
*Go to Boot partition.
*Then change the DTB listed in /boot/extlinux/extlinux.conf to -model-a.dtb instead of -cm4.dtb.
*Now put the SD card/ EMMC to the preferred base board and boot.
*First boot will take time as the user partition will resize to take whole storage size.

For headless installation, simply enter "root" at the login: prompt and complete setup.

=== Plebian ===
[[File:Plebian-logo.svg|right|100px]]

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm. It supports both of PINE64's officially released SOQuartz base boards.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace <tt>/dev/sdX</tt> with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Check [https://plebian.org/flashing/ Plebian's flashing instructions] for instructions on how to flash from e.g. Windows.

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys
* '''Please flash the correct image for your SOQuartz baseboard!'''

[[Category:SOQuartz]] [[Category:Quartz64]]

Quartz64 Software Releases

2023-08-31T11:25:44Z

CounterPillow: /* Software releases */ wording of note

This page contains a list of all available operating systems for the [[Quartz64]] in alphabetical order, as well as links to other resources.

== Software releases ==

{{warning|You are strongly encouraged to procure a 3.3V UART serial adapter capable of running at 1.5 mbauds, such as [https://pine64.com/product/serial-console-woodpecker-edition/ the Woodpecker] if you want to use a Quartz64, as some images' U-Boot may have no video output on this chip.}}

{{note|'''Note:''' The images are provided by the PINE64 community, not by Pine Store Ltd. Most community projects currently aim at getting mainline Linux running on the board, not some vendor provided kernel that will never be receiving updates. A mainline-first approach allows for the boards to continue receiving important updates, such as security updates, for years to come, as well as have higher quality code in the kernel as it underwent independent review, but does mean that not all aspects of the hardware work right out of the gate.}}

=== Armbian ===
[[File:armbian.png|right|100px]]

'''Armbian''' is a base operating system platform for single board computers

* Lightweight Debian or Ubuntu based Linux distribution specialized for ARM development boards
* Each system is compiled, assembled and optimized by [https://github.com/armbian/build Armbian Build Tools]
* It has powerful build and software development tools to make custom builds

Download:
{{Info|This image appears to have issues detecting more than 2GB of RAM.It is strongly recommended to use a different distribution.}}

* [https://github.com/armbian/build/releases/ latest, as fresh as possible, upon code change, images]

Notes:

* Support on Armbian forums https://forum.armbian.com/forum/96-upcoming-hardware-wip/

=== DietPi ===
[[File:dietpi.png|right|100px]]

'''DietPi''' is a lightweight, yet easy to setup and feature-rich Linux distribution, based on ''Debian''. To find out more about DietPi, please visit the [https://dietpi.com/docs/ official documentation]. Discuss the Quartz64 build(s) on the [https://forum.pine64.org/showthread.php?tid=17601 PINE64 forum thread].

Download:
* Quartz64 Model A: [https://dietpi.com/downloads/images/DietPi_Quartz64A-ARMv8-Bullseye.7z Direct download from dietpi.com]
* Quartz64 Model B: [https://dietpi.com/downloads/images/DietPi_Quartz64B-ARMv8-Bullseye.7z Direct download from dietpi.com]
* SOQuartz: [https://dietpi.com/downloads/images/DietPi_SOQuartz-ARMv8-Bullseye.7z Direct download from dietpi.com]

{| class="wikitable"
!colspan="2" style="background: #a7d7f9;"| Default credentials
|-
! Root user
| <code>root/dietpi</code>
|}

=== Manjaro ARM ===
[[File:Manjaro-logo.svg|right|100px]]

'''Manjaro ARM''' is a user friendly rolling release distribution, based on Arch Linux ARM.

Download:

* Quartz64 Model A: [https://github.com/manjaro-arm/quartz64-a-images/releases Image on GitHub]
* Quartz64 Model B: [https://github.com/manjaro-arm/quartz64-b-images/releases Image on GitHub]

{| class="wikitable"
!colspan="2" style="background: #a7d7f9;"| Default credentials
|-
! SSH
| <code>oem/oem</code>
|}

Notes:

Most of the hardware support is already available in the mainline kernel. If some devices doesn't work it is possible to swap to the linux-quartz64 kernel <code>pacman -S linux-quartz64</code>.

Following desktop options available:
* Gnome
* KDE Plasma
* Mate
* Sway
* XFCE
as well as minimal image without desktop.

=== NetBSD ===

'''NetBSD''' is a free, fast, secure, and highly portable Unix-like Open Source operating system. It relies upon the UEFI support in Tianocore. Before NetBSD 10 is released, the latest version of NetBSD-current should be used.

Download:
* [http://nycdn.netbsd.org/pub/NetBSD-daily/HEAD/ NetBSD daily builds top level] from inside here, navigate to a date, and inside the images/ subdirectory are installable images. Use the one called "NetBSD-<version>-evbarm-aarch64-install.img.gz".

Notes:
* This image can be written to a supported device, such as the eMMC interface, any USB storage device, NVMe, and PCIe AHCI SATA are all supported with builds after 2022-01-15.
* Currently this can not be shared with the EDK2 port, ie, microSD for EDK2 and some other media for NetBSD.

=== Plebian ===
[[File:Plebian-logo.svg|right|100px]]

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace ''/dev/sdX'' with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys

=== Tianocore EDK II port by jmcneill ===

This (as of 2021-12-30) is a work in progress to enable UEFI enabled systems, and is able to bring up SD, eMMC, USB, PCIe with SATA and NVMe, HDMI, thermal sensors, TRNG, as well as general Cortex A-55 features. Known to work with NetBSD -current, and the ESXi Arm fling version 1.8.

Download:
* [https://github.com/jaredmcneill/quartz64_uefi jmcneill's Quartz64 UEFI Github]

Notes:
* The microSD card image should be written to an microSD card and installed. Currently, using the same card for the operating system as well may be problematic.

== BSP Linux SDK ==

The '''BSP Linux SDK ver 4.19'' for the Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_BSP%20Linux.tar.gz Direct download] from ''pine64.org'' (32.67GB, MD5 of the TAR-GZip file ''24554419aec29700add97167a3a4c9ed'')

== Android SDK ==

=== Android 11 SDK ===

The '''Android 11 SDK''' for the Quartz64 Model A SBC.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64_SDK_android11.tar.gz Direct download] from ''pine64.org'' (79.00GB, MD5 of the TAR-GZip file ''77c2ff57ea3372fb04da7fb49e17d12b'')
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

=== Android 11 Production Test Builds ===

==== Android 11 Stock ====
The '''Android 11 Stock''' images for eMMC boot for the Quartz64 Model A. This is test build that was used during product testing.

Download:
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-8GB.img.gz Stock image for the 8GB eMMC module] from ''pine64.org'' (819MB, MD5 of the Gzip file ''e4365753e584d9fce1b8f10f095eede6'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-16GB.img.gz Stock image for the 16GB eMMC module] from ''pine64.org'' (1.10GB, MD5 of the Gzip file ''491c5f7744b0ca0b74ae76e607051836'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-32GB.img.gz Stock image for the 32GB eMMC module] from ''pine64.org'' (846MB, MD5 of the Gzip file ''47a6f0cdac8bad06cb920743849a8894'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-64GB.img.gz Stock image for the 64GB eMMC module] from ''pine64.org'' (884MB, MD5 of the Gzip file ''4e2fed6f5db0d55afdc8a142fc0c4fe1'', build 20210604)

Notes:
* Write the disk images to the eMMC modules using the USB adapter, for example using <code>dd</code>.
* Please allow 3-5 minutes boot up time on first time for initialization.

==== Android 11 Production Test Build ====
The '''Android 11 Production Test Build''' for the Quartz64 model A for eMMC boot using ROCKChip tools method. This is a test build that was used during product testing.

Download:
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_20210604_stock_android11_emmcboot.img.gz Direct download] from ''pine64.org'' (812MB, MD5 of the Gzip file ''800f867fdd0d1b2bd7822c156b6067e3'', build 20210604)

Notes:
* Please unzip first and then using [https://files.pine64.org/os/Quartz64/android/RKDevTool_Release_v2.84.zip Rockchip Android tool ver 2.84] to flash in
* For Windows OS environment please install the [https://files.pine64.org/os/Quartz64/android/DriverAssitant_v5.1.1.zip DriverAssistant v5.11] driver first
* The OTG port located at top USB 2.0 port on top of USB 3.0 port, needs USB type A to type A cable.
* Please allow 3-5 minutes boot up time on first time for initialization

==== Android 11 eink SDK ====
This the '''Android 11 eink SDK''' build for 10.3" e-ink panels on the Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_eink.android11_SDK.tar.gz Direct download] from ''pine64.org'' (72.88GB, MD5 of the TAR-GZip file ''293a550584298de4fb95ceae18103672'', build 20210604)
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

[[Category:Quartz64]]

Quartz64 Building U-Boot

2023-08-31T11:09:30Z

CounterPillow: Add Debian dependencies

This article guides you through compiling U-Boot for a [[Quartz64]] or [[SOQuartz]] device.

== Prerequisites ==

You will need either an x86 machine with an aarch64 cross-compiler installed, or an existing aarch64 system. You will also need the device tree compiler dtc, python3 (including setuptools and pyelftools), swig, GNU make and git.

=== Arch Linux ===

On an x86_64 Arch Linux system, you can install the required dependencies with:

pacman -S --needed base-devel aarch64-linux-gnu-gcc aarch64-linux-gnu-binutils git dtc python-setuptools swig python-pyelftools

=== Debian (or Derivates like Ubuntu) ===

On an x86_64 Debian system, you can install the required dependencies with:

apt install device-tree-compiler build-essential gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu make python3 python3-dev libssl-dev python3-pyelftools python3-setuptools swig git

== Fetching The Repositories ==

Use git to clone the mainline U-Boot repository into the directory ''u-boot'':

git clone https://source.denx.de/u-boot/u-boot.git

You can use <code>git checkout <var>tagname</var></code> inside the ''u-boot'' directory to check out a specific git tag (release), you can list all of them with <code>git tag -l</code> (but do keep in mind we only have device support since v2023.10).

Then, also use git to clone the rockchip firmware binaries repository into the directory ''rkbin'':

git clone https://github.com/rockchip-linux/rkbin.git

== Setting Up Your Environment ==

Next, we need to set two environment variables: <code>ROCKCHIP_TPL</code> for the DRAM init binary, and <code>BL31</code> for the ARM Trusted Firmware binary.

cd u-boot
export ROCKCHIP_TPL="$(ls ../rkbin/bin/rk35/rk3566_ddr_1056MHz_v*.bin | sort | tail -n1)"
export BL31="$(ls ../rkbin/bin/rk35/rk3568_bl31_v*.elf | sort | tail -n1)"

== Configuring U-Boot ==

First, we need to use the right default config for our device. Please choose <var>defconfig</var> from the following table depending on your device:

{| class="wikitable" border="1"
! scope="col" | Board
! scope="col" | defconfig
|-
| Quartz64 Model A || <code>quartz64-a-rk3566_defconfig</code>
|-
| Quartz64 Model B || <code>quartz64-b-rk3566_defconfig</code>
|-
| SOQuartz on Model A || <code>soquartz-model-a-rk3566_defconfig</code>
|-
| SOQuartz on Blade || <code>soquartz-blade-rk3566_defconfig</code>
|-
| SOQuartz on CM4 I/O Board || <code>soquartz-cm4-rk3566_defconfig</code>
|}

In the ''u-boot'' directory with your environment variables set, run:

make CROSS_COMPILE=aarch64-linux-gnu- <var>defconfig</var>

with <var>defconfig</var> being the value from the previous table.

== Building U-Boot ==

In the ''u-boot'' directory, after configuring, and with your environment variables set, run:

make CROSS_COMPILE=aarch64-linux-gnu- -j$(nproc)

This will output a ''u-boot-rockchip.bin'', which is your freshly built SPL+U-Boot combined image.

[[Category:Quartz64]] [[Category:SOQuartz]] [[Category:Guide]] [[Category:Quartz64 Guides]]

Quartz64 Software Releases

2023-08-31T10:45:20Z

CounterPillow: Add Plebian logo

This page contains a list of all available operating systems for the [[Quartz64]] in alphabetical order, as well as links to other resources.

== Software releases ==

{{warning|You are strongly encouraged to procure a 3.3V UART serial adapter capable of running at 1.5 mbauds, such as [https://pine64.com/product/serial-console-woodpecker-edition/ the Woodpecker] if you want to use a Quartz64, as some images' U-Boot may have no video output on this chip.}}

{{note|'''Note:''' The images are provided by the community, not by PINE64. Most community projects currently aim at getting mainline Linux running on the board, not some vendor provided kernel that will never be receiving updates. A mainline-first approach allows for the boards to continue receiving important updates, such as security updates, for years to come, as well as have higher quality code in the kernel as it underwent independent review, but does mean that not all aspects of the hardware work right out of the gate.}}

=== Armbian ===
[[File:armbian.png|right|100px]]

'''Armbian''' is a base operating system platform for single board computers

* Lightweight Debian or Ubuntu based Linux distribution specialized for ARM development boards
* Each system is compiled, assembled and optimized by [https://github.com/armbian/build Armbian Build Tools]
* It has powerful build and software development tools to make custom builds

Download:
{{Info|This image appears to have issues detecting more than 2GB of RAM.It is strongly recommended to use a different distribution.}}

* [https://github.com/armbian/build/releases/ latest, as fresh as possible, upon code change, images]

Notes:

* Support on Armbian forums https://forum.armbian.com/forum/96-upcoming-hardware-wip/

=== DietPi ===
[[File:dietpi.png|right|100px]]

'''DietPi''' is a lightweight, yet easy to setup and feature-rich Linux distribution, based on ''Debian''. To find out more about DietPi, please visit the [https://dietpi.com/docs/ official documentation]. Discuss the Quartz64 build(s) on the [https://forum.pine64.org/showthread.php?tid=17601 PINE64 forum thread].

Download:
* Quartz64 Model A: [https://dietpi.com/downloads/images/DietPi_Quartz64A-ARMv8-Bullseye.7z Direct download from dietpi.com]
* Quartz64 Model B: [https://dietpi.com/downloads/images/DietPi_Quartz64B-ARMv8-Bullseye.7z Direct download from dietpi.com]
* SOQuartz: [https://dietpi.com/downloads/images/DietPi_SOQuartz-ARMv8-Bullseye.7z Direct download from dietpi.com]

{| class="wikitable"
!colspan="2" style="background: #a7d7f9;"| Default credentials
|-
! Root user
| <code>root/dietpi</code>
|}

=== Manjaro ARM ===
[[File:Manjaro-logo.svg|right|100px]]

'''Manjaro ARM''' is a user friendly rolling release distribution, based on Arch Linux ARM.

Download:

* Quartz64 Model A: [https://github.com/manjaro-arm/quartz64-a-images/releases Image on GitHub]
* Quartz64 Model B: [https://github.com/manjaro-arm/quartz64-b-images/releases Image on GitHub]

{| class="wikitable"
!colspan="2" style="background: #a7d7f9;"| Default credentials
|-
! SSH
| <code>oem/oem</code>
|}

Notes:

Most of the hardware support is already available in the mainline kernel. If some devices doesn't work it is possible to swap to the linux-quartz64 kernel <code>pacman -S linux-quartz64</code>.

Following desktop options available:
* Gnome
* KDE Plasma
* Mate
* Sway
* XFCE
as well as minimal image without desktop.

=== NetBSD ===

'''NetBSD''' is a free, fast, secure, and highly portable Unix-like Open Source operating system. It relies upon the UEFI support in Tianocore. Before NetBSD 10 is released, the latest version of NetBSD-current should be used.

Download:
* [http://nycdn.netbsd.org/pub/NetBSD-daily/HEAD/ NetBSD daily builds top level] from inside here, navigate to a date, and inside the images/ subdirectory are installable images. Use the one called "NetBSD-<version>-evbarm-aarch64-install.img.gz".

Notes:
* This image can be written to a supported device, such as the eMMC interface, any USB storage device, NVMe, and PCIe AHCI SATA are all supported with builds after 2022-01-15.
* Currently this can not be shared with the EDK2 port, ie, microSD for EDK2 and some other media for NetBSD.

=== Plebian ===
[[File:Plebian-logo.svg|right|100px]]

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace ''/dev/sdX'' with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys

=== Tianocore EDK II port by jmcneill ===

This (as of 2021-12-30) is a work in progress to enable UEFI enabled systems, and is able to bring up SD, eMMC, USB, PCIe with SATA and NVMe, HDMI, thermal sensors, TRNG, as well as general Cortex A-55 features. Known to work with NetBSD -current, and the ESXi Arm fling version 1.8.

Download:
* [https://github.com/jaredmcneill/quartz64_uefi jmcneill's Quartz64 UEFI Github]

Notes:
* The microSD card image should be written to an microSD card and installed. Currently, using the same card for the operating system as well may be problematic.

== BSP Linux SDK ==

The '''BSP Linux SDK ver 4.19'' for the Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_BSP%20Linux.tar.gz Direct download] from ''pine64.org'' (32.67GB, MD5 of the TAR-GZip file ''24554419aec29700add97167a3a4c9ed'')

== Android SDK ==

=== Android 11 SDK ===

The '''Android 11 SDK''' for the Quartz64 Model A SBC.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64_SDK_android11.tar.gz Direct download] from ''pine64.org'' (79.00GB, MD5 of the TAR-GZip file ''77c2ff57ea3372fb04da7fb49e17d12b'')
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

=== Android 11 Production Test Builds ===

==== Android 11 Stock ====
The '''Android 11 Stock''' images for eMMC boot for the Quartz64 Model A. This is test build that was used during product testing.

Download:
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-8GB.img.gz Stock image for the 8GB eMMC module] from ''pine64.org'' (819MB, MD5 of the Gzip file ''e4365753e584d9fce1b8f10f095eede6'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-16GB.img.gz Stock image for the 16GB eMMC module] from ''pine64.org'' (1.10GB, MD5 of the Gzip file ''491c5f7744b0ca0b74ae76e607051836'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-32GB.img.gz Stock image for the 32GB eMMC module] from ''pine64.org'' (846MB, MD5 of the Gzip file ''47a6f0cdac8bad06cb920743849a8894'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-64GB.img.gz Stock image for the 64GB eMMC module] from ''pine64.org'' (884MB, MD5 of the Gzip file ''4e2fed6f5db0d55afdc8a142fc0c4fe1'', build 20210604)

Notes:
* Write the disk images to the eMMC modules using the USB adapter, for example using <code>dd</code>.
* Please allow 3-5 minutes boot up time on first time for initialization.

==== Android 11 Production Test Build ====
The '''Android 11 Production Test Build''' for the Quartz64 model A for eMMC boot using ROCKChip tools method. This is a test build that was used during product testing.

Download:
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_20210604_stock_android11_emmcboot.img.gz Direct download] from ''pine64.org'' (812MB, MD5 of the Gzip file ''800f867fdd0d1b2bd7822c156b6067e3'', build 20210604)

Notes:
* Please unzip first and then using [https://files.pine64.org/os/Quartz64/android/RKDevTool_Release_v2.84.zip Rockchip Android tool ver 2.84] to flash in
* For Windows OS environment please install the [https://files.pine64.org/os/Quartz64/android/DriverAssitant_v5.1.1.zip DriverAssistant v5.11] driver first
* The OTG port located at top USB 2.0 port on top of USB 3.0 port, needs USB type A to type A cable.
* Please allow 3-5 minutes boot up time on first time for initialization

==== Android 11 eink SDK ====
This the '''Android 11 eink SDK''' build for 10.3" e-ink panels on the Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_eink.android11_SDK.tar.gz Direct download] from ''pine64.org'' (72.88GB, MD5 of the TAR-GZip file ''293a550584298de4fb95ceae18103672'', build 20210604)
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

[[Category:Quartz64]]

Quartz64 Software Releases

2023-08-31T10:30:13Z

CounterPillow: Remove pgwipeout's CI as it's no longer being updated and hasn't been in a while

This page contains a list of all available operating systems for the [[Quartz64]] in alphabetical order, as well as links to other resources.

== Software releases ==

{{warning|You are strongly encouraged to procure a 3.3V UART serial adapter capable of running at 1.5 mbauds, such as [https://pine64.com/product/serial-console-woodpecker-edition/ the Woodpecker] if you want to use a Quartz64, as some images' U-Boot may have no video output on this chip.}}

{{note|'''Note:''' The images are provided by the community, not by PINE64. Most community projects currently aim at getting mainline Linux running on the board, not some vendor provided kernel that will never be receiving updates. A mainline-first approach allows for the boards to continue receiving important updates, such as security updates, for years to come, as well as have higher quality code in the kernel as it underwent independent review, but does mean that not all aspects of the hardware work right out of the gate.}}

=== Armbian ===
[[File:armbian.png|right|100px]]

'''Armbian''' is a base operating system platform for single board computers

* Lightweight Debian or Ubuntu based Linux distribution specialized for ARM development boards
* Each system is compiled, assembled and optimized by [https://github.com/armbian/build Armbian Build Tools]
* It has powerful build and software development tools to make custom builds

Download:
{{Info|This image appears to have issues detecting more than 2GB of RAM.It is strongly recommended to use a different distribution.}}

* [https://github.com/armbian/build/releases/ latest, as fresh as possible, upon code change, images]

Notes:

* Support on Armbian forums https://forum.armbian.com/forum/96-upcoming-hardware-wip/

=== DietPi ===
[[File:dietpi.png|right|100px]]

'''DietPi''' is a lightweight, yet easy to setup and feature-rich Linux distribution, based on ''Debian''. To find out more about DietPi, please visit the [https://dietpi.com/docs/ official documentation]. Discuss the Quartz64 build(s) on the [https://forum.pine64.org/showthread.php?tid=17601 PINE64 forum thread].

Download:
* Quartz64 Model A: [https://dietpi.com/downloads/images/DietPi_Quartz64A-ARMv8-Bullseye.7z Direct download from dietpi.com]
* Quartz64 Model B: [https://dietpi.com/downloads/images/DietPi_Quartz64B-ARMv8-Bullseye.7z Direct download from dietpi.com]
* SOQuartz: [https://dietpi.com/downloads/images/DietPi_SOQuartz-ARMv8-Bullseye.7z Direct download from dietpi.com]

{| class="wikitable"
!colspan="2" style="background: #a7d7f9;"| Default credentials
|-
! Root user
| <code>root/dietpi</code>
|}

=== Manjaro ARM ===
[[File:Manjaro-logo.svg|right|100px]]

'''Manjaro ARM''' is a user friendly rolling release distribution, based on Arch Linux ARM.

Download:

* Quartz64 Model A: [https://github.com/manjaro-arm/quartz64-a-images/releases Image on GitHub]
* Quartz64 Model B: [https://github.com/manjaro-arm/quartz64-b-images/releases Image on GitHub]

{| class="wikitable"
!colspan="2" style="background: #a7d7f9;"| Default credentials
|-
! SSH
| <code>oem/oem</code>
|}

Notes:

Most of the hardware support is already available in the mainline kernel. If some devices doesn't work it is possible to swap to the linux-quartz64 kernel <code>pacman -S linux-quartz64</code>.

Following desktop options available:
* Gnome
* KDE Plasma
* Mate
* Sway
* XFCE
as well as minimal image without desktop.

=== NetBSD ===

'''NetBSD''' is a free, fast, secure, and highly portable Unix-like Open Source operating system. It relies upon the UEFI support in Tianocore. Before NetBSD 10 is released, the latest version of NetBSD-current should be used.

Download:
* [http://nycdn.netbsd.org/pub/NetBSD-daily/HEAD/ NetBSD daily builds top level] from inside here, navigate to a date, and inside the images/ subdirectory are installable images. Use the one called "NetBSD-<version>-evbarm-aarch64-install.img.gz".

Notes:
* This image can be written to a supported device, such as the eMMC interface, any USB storage device, NVMe, and PCIe AHCI SATA are all supported with builds after 2022-01-15.
* Currently this can not be shared with the EDK2 port, ie, microSD for EDK2 and some other media for NetBSD.

=== Plebian ===

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace ''/dev/sdX'' with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys

=== Tianocore EDK II port by jmcneill ===

This (as of 2021-12-30) is a work in progress to enable UEFI enabled systems, and is able to bring up SD, eMMC, USB, PCIe with SATA and NVMe, HDMI, thermal sensors, TRNG, as well as general Cortex A-55 features. Known to work with NetBSD -current, and the ESXi Arm fling version 1.8.

Download:
* [https://github.com/jaredmcneill/quartz64_uefi jmcneill's Quartz64 UEFI Github]

Notes:
* The microSD card image should be written to an microSD card and installed. Currently, using the same card for the operating system as well may be problematic.

== BSP Linux SDK ==

The '''BSP Linux SDK ver 4.19'' for the Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_BSP%20Linux.tar.gz Direct download] from ''pine64.org'' (32.67GB, MD5 of the TAR-GZip file ''24554419aec29700add97167a3a4c9ed'')

== Android SDK ==

=== Android 11 SDK ===

The '''Android 11 SDK''' for the Quartz64 Model A SBC.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64_SDK_android11.tar.gz Direct download] from ''pine64.org'' (79.00GB, MD5 of the TAR-GZip file ''77c2ff57ea3372fb04da7fb49e17d12b'')
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

=== Android 11 Production Test Builds ===

==== Android 11 Stock ====
The '''Android 11 Stock''' images for eMMC boot for the Quartz64 Model A. This is test build that was used during product testing.

Download:
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-8GB.img.gz Stock image for the 8GB eMMC module] from ''pine64.org'' (819MB, MD5 of the Gzip file ''e4365753e584d9fce1b8f10f095eede6'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-16GB.img.gz Stock image for the 16GB eMMC module] from ''pine64.org'' (1.10GB, MD5 of the Gzip file ''491c5f7744b0ca0b74ae76e607051836'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-32GB.img.gz Stock image for the 32GB eMMC module] from ''pine64.org'' (846MB, MD5 of the Gzip file ''47a6f0cdac8bad06cb920743849a8894'', build 20210604)
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_dd_20210604_stock_android11_emmcboot-64GB.img.gz Stock image for the 64GB eMMC module] from ''pine64.org'' (884MB, MD5 of the Gzip file ''4e2fed6f5db0d55afdc8a142fc0c4fe1'', build 20210604)

Notes:
* Write the disk images to the eMMC modules using the USB adapter, for example using <code>dd</code>.
* Please allow 3-5 minutes boot up time on first time for initialization.

==== Android 11 Production Test Build ====
The '''Android 11 Production Test Build''' for the Quartz64 model A for eMMC boot using ROCKChip tools method. This is a test build that was used during product testing.

Download:
* [https://files.pine64.org/os/Quartz64/android/Quartz64_model-A_20210604_stock_android11_emmcboot.img.gz Direct download] from ''pine64.org'' (812MB, MD5 of the Gzip file ''800f867fdd0d1b2bd7822c156b6067e3'', build 20210604)

Notes:
* Please unzip first and then using [https://files.pine64.org/os/Quartz64/android/RKDevTool_Release_v2.84.zip Rockchip Android tool ver 2.84] to flash in
* For Windows OS environment please install the [https://files.pine64.org/os/Quartz64/android/DriverAssitant_v5.1.1.zip DriverAssistant v5.11] driver first
* The OTG port located at top USB 2.0 port on top of USB 3.0 port, needs USB type A to type A cable.
* Please allow 3-5 minutes boot up time on first time for initialization

==== Android 11 eink SDK ====
This the '''Android 11 eink SDK''' build for 10.3" e-ink panels on the Quartz64 Model A.

Download:
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_eink.android11_SDK.tar.gz Direct download] from ''pine64.org'' (72.88GB, MD5 of the TAR-GZip file ''293a550584298de4fb95ceae18103672'', build 20210604)
* Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

[[Category:Quartz64]]

SOQuartz Software Releases

2023-08-31T10:18:09Z

CounterPillow: Add note about making your own images, remove irrelevant blogspam

This page contains a list of all available operating systems for the [[SOQuartz]].

== Making Your Own ==

Making your own image/installation of Linux for SOQuartz is relatively easy, as all major components are mainlined. You will need:

* A build of mainline U-Boot ≥ v2023.10, see [[Quartz64 Building U-Boot]]. Flash this to sector 64 (sector size 512, so byte 32768) of your image for SD or eMMC. It's prudent to "protect" it by making a small (~16MiB) partition at this offset.
* A [https://www.kernel.org/ mainline Linux kernel] ≥ v6.2. See [[Quartz64 Development#Linux Kernel Config Options]] for the device specific kernel configuration options.
* The root filesystem of the distribution of your choice. This can be on the same filesystem as your kernel and device tree if using ''extlinux.conf''.

You can either boot the kernel through U-Boot's EFI booting, in which case it gets its device tree from U-Boot, or mark the partition containing your kernel and device tree with the legacy bootable flag and [https://u-boot.readthedocs.io/en/latest/develop/distro.html#boot-configuration-files write an ''extlinux/extlinux.conf''].


== DietPi support with Debian/Bullseye ==

Info and downloads: https://dietpi.com/docs/hardware/#pine64

== Manjaro ARM ==
[[File:Manjaro-logo.svg|right|100px]]

Manjaro ARM is a user friendly rolling release distribution, based on Arch Linux ARM.

* [https://github.com/manjaro-arm/soquartz-cm4-images/releases Images for SOQuartz on GitHub]

WiFI, Bluetooth, Ethernet, HDMI USB etc. works, others are not tested.

Currently the image is built for Raspberry Pi CM4 - IO board, so to get it working with other base board like pine64 Soquartz model A base board then follow this steps
*Flash the image to a SD card/ EMMC.
*Go to Boot partition.
*Then change the DTB listed in /boot/extlinux/extlinux.conf to -model-a.dtb instead of -cm4.dtb.
*Now put the SD card/ EMMC to the preferred base board and boot.
*First boot will take time as the user partition will resize to take whole storage size.

For headless installation, simply enter "root" at the login: prompt and complete setup.

== Plebian ==
[[File:Plebian-logo.svg|right|100px]]

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm. It supports both of PINE64's officially released SOQuartz base boards.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace <tt>/dev/sdX</tt> with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Check [https://plebian.org/flashing/ Plebian's flashing instructions] for instructions on how to flash from e.g. Windows.

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys
* '''Please flash the correct image for your SOQuartz baseboard!'''

[[Category:SOQuartz]] [[Category:Quartz64]]

SOQuartz Software Releases

2023-08-31T09:52:23Z

CounterPillow: /* Plebian */

This page contains a list of all available operating systems for the [[SOQuartz]].

== DietPi support with Debian/Bullseye ==

Info and downloads: https://dietpi.com/docs/hardware/#pine64

James Chambers did a soquartz review, and recommends the Armbian build from above.

* https://jamesachambers.com/pine64-soquartz-cm4-alternative-review/

== Manjaro ARM ==
[[File:Manjaro-logo.svg|right|100px]]

Manjaro ARM is a user friendly rolling release distribution, based on Arch Linux ARM.

* [https://github.com/manjaro-arm/soquartz-cm4-images/releases Images for SOQuartz on GitHub]

WiFI, Bluetooth, Ethernet, HDMI USB etc. works, others are not tested.

Currently the image is built for Raspberry Pi CM4 - IO board, so to get it working with other base board like pine64 Soquartz model A base board then follow this steps
*Flash the image to a SD card/ EMMC.
*Go to Boot partition.
*Then change the DTB listed in /boot/extlinux/extlinux.conf to -model-a.dtb instead of -cm4.dtb.
*Now put the SD card/ EMMC to the preferred base board and boot.
*First boot will take time as the user partition will resize to take whole storage size.

For headless installation, simply enter "root" at the login: prompt and complete setup.

== Plebian ==
[[File:Plebian-logo.svg|right|100px]]

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm. It supports both of PINE64's officially released SOQuartz base boards.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace <tt>/dev/sdX</tt> with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Check [https://plebian.org/flashing/ Plebian's flashing instructions] for instructions on how to flash from e.g. Windows.

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys
* '''Please flash the correct image for your SOQuartz baseboard!'''

[[Category:SOQuartz]] [[Category:Quartz64]]

SOQuartz Software Releases

2023-08-31T09:50:25Z

CounterPillow: Add logo to Plebian listing

This page contains a list of all available operating systems for the [[SOQuartz]].

== DietPi support with Debian/Bullseye ==

Info and downloads: https://dietpi.com/docs/hardware/#pine64

James Chambers did a soquartz review, and recommends the Armbian build from above.

* https://jamesachambers.com/pine64-soquartz-cm4-alternative-review/

== Manjaro ARM ==
[[File:Manjaro-logo.svg|right|100px]]

Manjaro ARM is a user friendly rolling release distribution, based on Arch Linux ARM.

* [https://github.com/manjaro-arm/soquartz-cm4-images/releases Images for SOQuartz on GitHub]

WiFI, Bluetooth, Ethernet, HDMI USB etc. works, others are not tested.

Currently the image is built for Raspberry Pi CM4 - IO board, so to get it working with other base board like pine64 Soquartz model A base board then follow this steps
*Flash the image to a SD card/ EMMC.
*Go to Boot partition.
*Then change the DTB listed in /boot/extlinux/extlinux.conf to -model-a.dtb instead of -cm4.dtb.
*Now put the SD card/ EMMC to the preferred base board and boot.
*First boot will take time as the user partition will resize to take whole storage size.

For headless installation, simply enter "root" at the login: prompt and complete setup.

== Plebian ==
[[File:Plebian-logo.svg|right|100px]]

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm. It supports both of PINE64's officially released SOQuartz base boards.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace <tt>/dev/sdX</tt> with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys
* '''Please flash the correct image for your SOQuartz baseboard!'''

[[Category:SOQuartz]] [[Category:Quartz64]]

File:Plebian-logo.svg

2023-08-31T09:49:33Z

CounterPillow: Plebian logo

== Summary ==
Plebian logo
== Licensing ==
{{cc-by-sa-4.0}}

SOQuartz Software Releases

2023-08-31T09:46:18Z

CounterPillow: Remove broken stuff, no longer updated stuff, reorder alphabetically

This page contains a list of all available operating systems for the [[SOQuartz]].

== DietPi support with Debian/Bullseye ==

Info and downloads: https://dietpi.com/docs/hardware/#pine64

James Chambers did a soquartz review, and recommends the Armbian build from above.

* https://jamesachambers.com/pine64-soquartz-cm4-alternative-review/

== Manjaro ARM ==
[[File:Manjaro-logo.svg|right|100px]]

Manjaro ARM is a user friendly rolling release distribution, based on Arch Linux ARM.

* [https://github.com/manjaro-arm/soquartz-cm4-images/releases Images for SOQuartz on GitHub]

WiFI, Bluetooth, Ethernet, HDMI USB etc. works, others are not tested.

Currently the image is built for Raspberry Pi CM4 - IO board, so to get it working with other base board like pine64 Soquartz model A base board then follow this steps
*Flash the image to a SD card/ EMMC.
*Go to Boot partition.
*Then change the DTB listed in /boot/extlinux/extlinux.conf to -model-a.dtb instead of -cm4.dtb.
*Now put the SD card/ EMMC to the preferred base board and boot.
*First boot will take time as the user partition will resize to take whole storage size.

For headless installation, simply enter "root" at the login: prompt and complete setup.

== Plebian ==

Plebian stands for '''P'''INE64 '''L'''ive D'''ebian''' and aims to be a fairly vanilla live Debian image for Quartz64 and SOQuartz devices, based on Debian Bookworm. It supports both of PINE64's officially released SOQuartz base boards.

* [https://github.com/Plebian-Linux/quartz64-images/releases Download Release Images]
* [https://github.com/Plebian-Linux/quartz64-images/blob/main/RUNNING.md Read The Instructions]
* [https://plebian.org/ Visit plebian.org to learn more]

To flash, run (replace <tt>/dev/sdX</tt> with your target block device):

$ xzcat imagename.img.xz | sudo dd of=/dev/sdX bs=4M oflag=dsync status=progress

Some quick notes:

* You will be asked to change your password on first login (for what the default login is, read the instructions!)
* Root file system is grown to take up the entire space of your boot device
* NetworkManager is used instead of Debian's interfaces config to be more flexible with what adapters are plugged in and working
* An sshd is started on port 22 with freshly generated keys
* '''Please flash the correct image for your SOQuartz baseboard!'''

[[Category:SOQuartz]] [[Category:Quartz64]]

SOQuartz

2023-08-31T09:33:27Z

CounterPillow: Add troubleshooting section

[[File:SOQuartz module-1s.jpg|400px|thumb|right|The SOQuartz]]

The '''SOQuartz''' is a RK3566 based compute module and parts of Quartz64 series.

== Software releases ==

The SOQuartz software releases can be found in the article [[SOQuartz Software Releases]].

== SoC and Memory Specification ==
* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]
[[File:RK3566_icon.png|right]]

=== CPU Architecture ===
* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache

=== GPU (Graphics Processing Unit) Capabilities ===
* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== Neural Process Unit NPU Capability ===
* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===
* RAM Memory Variants: 2GB, 4GB, 8GB LPDDR4.
* Storage Memory: optional 128Mb SPI Flash and optional eMMC module from 8GB up to 128GB

=== Network ===
* 10/100/1000Mbps Ethernet
* WiFi 802.11 b/g/n/ac with Bluetooth 5.0

== SOQuartz exposed peripherals ==

=== Displays / Cameras ===

* 1x HDMI
* 2x DSI
* 1x eDP (Instead of HDMI1)
* 1x LVDS (not available when dual-mode DSI)
* 1x CSI 4-line

=== Connectivity ===

* 1x Ethernet (1Gbit)
* 1x USB 2.0 OTG
* 1x SD Card (SD)
* 1x PCIe 1-Line
* 28x GPIO (TBD)

== Connector Pins Definition ==

* [https://files.pine64.org/doc/quartz64/SOQuartz%20Connector%20Pin%20Assignments%20ver%201.0.ods SOQuartz Module Connector Pins Definition ver 1.0]

== SOQuartz Model-A Baseboard Features ==

[[File:SOQuartz_model-A_baseboard.jpg |400px|thumb|SOQuartz Model-A Baseboard]]
* Model "A" Baseboard Dimensions: 133mm x 80mm x 19mm
* Input Power: DC 12V @ 3A 5.5OD/2.1ID (IEC 60130-10 Type A) Barrel DC Jack connector

=== Storage ===
* microSD - bootable, support SDHC and SDXC, storage up to 2TB
* USB - 2 USB2.0 Host port

=== Expansion Ports ===
* MiPi-CSI - 1x 2 lanes, 1x 4 lanes
* MiPi-DSI - 1x 2 lanes, 1x 4 lanes
* 2x20 pins "Pi2" GPIO Header
* PCIe 1x open ended slot
* 1x5 pin USB Expansion Header (J15)

=== GPIO Pins ===

Attention! GPIOs are 3.3V!

Interesting alternate pin configurations are listed in [brackets].

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 1
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C2_SDA_M1]'' GPIO4_B4_3V3 a
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C2_SCL_M1]'' GPIO4_B5_3V3 a
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[GPCLK0]'' GPIO4_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| GPIO0_D1_3V3 ''[UART2_TX_M0]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| GPIO0_D0_3V3 ''[UART2_RX_M0]''
|-
| style="text-align:right;"| ''[I2S1_MCLK_M1]'' GPIO3_C6_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| GPIO3_C7_3V3 ''[I2S1_SCLK_M1]''
|-
| style="text-align:right;"| GPIO4_A0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO4_A2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GPIO4_A3_3V3
|-
| style="text-align:right;"| 3.3V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 17
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| GPIO4_A1_3V3
|-
| style="text-align:right;"| ''[SPI3_MOSI_M0]'' GPIO4_B2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[SPI3_MISO_M0]'' GPIO4_B0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 21
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 22
| style="text-align:left;"| GPIO4_B1_3V3
|-
| style="text-align:right;"| ''[SPI3_CLK_M0]'' GPIO4_B3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 23
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 24
| style="text-align:left;"| GPIO4_A6_3V3 ''[SPI3_CS0_M0]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 25
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 26
| style="text-align:left;"| GPIO4_A7_3V3 ''[SPI3_CS1_M0]''
|-
| style="text-align:right;"| ''[I2C3_SDA_M0]'' GPIO1_A0_3V3 a
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 27
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 28
| style="text-align:left;"| GPIO1_A1_3V3 ''[I2C3_SCL_M0]'' a
|-
| style="text-align:right;"| GPIO3_A5_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 29
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 30
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_D4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 31
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 32
| style="text-align:left;"| GPIO3_D6_3V3
|-
| style="text-align:right;"| GPIO3_D7_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 33
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 34
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[I2S1_LRCK_M1]'' GPIO3_D0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 35
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 36
| style="text-align:left;"| GPIO3_D5_3V3
|-
| style="text-align:right;"| GPIO3_D3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 37
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 38
| style="text-align:left;"| GPIO3_D2_3V3 ''[I2S1_SDI_M1]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 39
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 40
| style="text-align:left;"| GPIO3_D1_3V3 ''[I2S1_SDO_M1]''
|}

====Notes====
<ol style="list-style-type:lower-alpha">
<li>pulled high to 3.3V through 2.2kOhm resistor</li>
</ol>

Source: Page 11 of [https://files.pine64.org/doc/quartz64/SOQuartz-Model-A-Baseboard-Schematic-20220522.pdf the board schematics].
=== USB Expansion Header ===
{| class="wikitable plainrowheaders" border="1"
! scope="col" | Pin no
! scope="col" | Assigned To
|-
| style="text-align:left;"| 1
| style="text-align:center; | USB2_HOST_5V
|-
| style="text-align:left;"| 2
| style="text-align:center; | HOST_DM3
|-
| style="text-align:left;"| 3
| style="text-align:center; | HOST_DP3
|-
| style="text-align:left;"| 4
| style="text-align:center; | GND
|-
| style="text-align:left;"| 5
| style="text-align:center; | GND
|}

Source: Page 10 of [https://files.pine64.org/doc/quartz64/SOQuartz-Model-A-Baseboard-Schematic-20220522.pdf the board schematics].

== SOQuartz BLADE Baseboard Features ==

[[File:SOQuartz_BLADE_Dimension.jpg |400px|thumb|SOQuartz BLADE Baseboard]]
* SOQuartz BLADE Baseboard Dimensions: 200mm x 40mm x 15mm
* Input Power:
** DC 5V @ 3A 3.5OD/1.35ID (IEC 60130-10 Type H) Barrel DC Jack connector
** PoE

=== Storage ===
* microSD - bootable, support SDHC and SDXC, storage up to 2TB
* USB - USB2.0 Host port (with header for setting OTG ID pin)

=== Expansion Ports ===
* 2x20 pins "Pi2" GPIO Header
* M.2 slot
* PWM fan header

=== Jumpers ===
* OTG ID jumper
* GPIO voltage, select 3.3V or 1.8V
* PoE Enable

== SOQuartz Module and Baseboard Information, Schematics, and Certifications ==

* SOQuartz Module Schematic:
** [https://files.pine64.org/doc/quartz64/SOQuartz_SOM_schematic_v1.1_20210816.pdf SOQuartz Module ver 1.1 20210816 Schematic]
** [https://files.pine64.org/doc/quartz64/SOQuartz-PCB-placement-v1.1.pdf SOQuartz Module ver 1.1 20210816 PCB Component Placement]

* SOQuartz Model "A" Baseboard Schematic and PCB Board Resource:
** [https://files.pine64.org/doc/quartz64/SOQuartz-Model-A-Baseboard-Schematic-20220522.pdf SOQuartz Model-A baseboard 20220522 Schematic PDF file]
** [https://files.pine64.org/doc/quartz64/SOQuartz-Model-A-Baseboard-Schematic-20220522.DSN SOQuartz Model-A baseboard 20220522 Schematic DSN source file]
** [https://files.pine64.org/doc/quartz64/SOQuartz-Model-A-Baseboard-Component-Placement_top-20220522.pdf SOQuartz SOQuartz Model-A baseboard 20220522 PCB Top Component Placement]
** [https://files.pine64.org/doc/quartz64/SOQuartz_Model_A_Baseboard_Component_Placement_bottom_20220522.pdf SOQuartz SOQuartz Model-A baseboard 20220522 PCB Bottom Component Placement]
** [https://files.pine64.org/doc/quartz64/SOQuartz-Model-A-Baseboard-PCB-20220522.dsn SOQuartz Model-A baseboard 20220522 PCB DSN file]
** [https://files.pine64.org/doc/quartz64/SOQuartz-Model-A-Baseboard-PCB-20220522.rar SOQuartz Model-A baseboard 20220522 PCB Gerber file]

[[File:BLADE_1U_half_width_server_rack.jpg |400px|thumb|SOQuartz BLADE 3D Print 1U half width server rack]]
[[File:BLADE_1U_full_width_server_rack.jpg |400px|thumb|SOQuartz BLADE 3D Print 1U full width server rack]]
* SOQuartz Blade Baseboard Schematic and PCB Board Resource:
** [https://files.pine64.org/doc/quartz64/SOQuartz-BLADE-Baseboard-Schematic-20220522.pdf SOQuartz BLADE 20220522 Schematic]
** [https://files.pine64.org/doc/quartz64/SOQuartz-BLADE-PCB-Placement-20220522.pdf SOQuartz BLADE 20220522 PCB component Placement]
** [https://files.pine64.org/doc/quartz64/BLADE%201U%20Rack_3D.stp SOQuartz BLADE 1U Rack STP file]
[[File:BLADE_1U_rack_3D.jpg |400px]]

SOQuartz module certifications:
* [https://files.pine64.org/doc/cert/SOQuartz%20FCC%20Certificate-S21101902401001.pdf SOQuartz module FCC Certificate]
* [https://files.pine64.org/doc/cert/SOQuartz%20CE%20Certificate-S21101902402001.pdf SOQuartz module CE EMC Certificate]

== Datasheets for Components and Peripherals ==
* Rockchip RK3566 SoC information:
** [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, already got release permission from Rockchip]
* Rockchip PMU (Power Management Unit) Information:
** [https://www.rockchip.fr/RK809%20datasheet%20V1.01.pdf Rockchip RK809 ver 1.01 datasheet for SOQuartz PMU]
* DDR4 information:
** [https://files.pine64.org/doc/datasheet/rockpro64/SM512M32Z01MD2BNP(200BALL).pdf Micron LPDDR4 Mobile LPDDR4 Datasheet]
* eMMC information:
** [https://files.pine64.org/doc/rock64/PINE64_eMMC_Module_20170719.pdf PINE64 eMMC module schematic]
** [https://files.pine64.org/doc/rock64/usb%20emmc%20module%20adapter%20v2.pdf PINE64 USB adapter for eMMC module V2 schematic]
** [https://files.pine64.org/doc/rock64/USB%20adapter%20for%20eMMC%20module%20PCB.tar PINE64 USB adapter for eMMC module PCB in JPEG]
** [https://files.pine64.org/doc/datasheet/pine64/E-00517%20FORESEE_eMMC_NCEMAM8B-16G%20SPEC.pdf 16GB Foresee eMMC Datasheet]
** [https://files.pine64.org/doc/datasheet/pine64/SDINADF4-16-128GB-H%20data%20sheet%20v1.13.pdf 32GB/64GB/128GB SanDisk eMMC Datasheet]
* SPI NOR Flash information:
* Ethernet PHY information:
** [https://files.pine64.org/doc/datasheet/pine64/rtl8211e(g)-vb(vl)-cg_datasheet_1.6.pdf Realtek RTL8211 10/100/1000M Ethernet Transceiver]
* WiFi/BT module info:
** [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC WiFi + Bluetooth5.0 Datasheet]
* i2C to PWM Controller user in BLADE info:
** [https://files.pine64.org/doc/datasheet/quartz64/GP7101_cn_V1_qsxn.pdf GP7101 i2c to PWM Controller Datasheet in Chinese]
** GP7101 i2c to PWM Controller Datasheet translated to English by neggles [[File:GP7101 cn V1 qsxn en.pdf]]
** I2C address is 0x58 despite what datasheet says
* PoE DC/DC Controller user in BLADE info:
** [https://files.pine64.org/doc/datasheet/quartz64/SD4954B%20Datasheet.pdf Silan SD4954B PD and DC/DC Controller compatible with IEEE 802.3AF standard Datasheet]

== SOQuartz Module with various CM4 carrier boards ==

* For CM4 carrier board comprehensive list, please visit [https://pipci.jeffgeerling.com/boards_cm Jeff Geerling collection]

[[File:SOQuartz_with_DF_Robot_carrier_board.jpg|400px|thumb|SOQuartz with DF Robot CM4 Carrier Board]]

[[File:SOQuartz_with_Waveshare_carrier_board.jpg|400px|thumb|SOQuartz with Waveshare CM4 Carrier Board]]

[[File:SOQuartz_with_Waveshare_PoE_carrier_board.jpg|400px|thumb|SOQuartz with Waveshare CM4 PoE Board]]

== BSP Linux SDK ==

=== BSP Linux SDK ver 4.19 for Quartz64 model A SBC ===
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64-model-A_BSP%20Linux.tar.gz Direct Download from pine64.org]
** MD5 (TAR-GZip file): 24554419aec29700add97167a3a4c9ed
** File Size: 32.67.00GB

== Android SDK ==

=== Android 11 SDK for Quartz64 model A SBC ===
* [http://files.pine64.org/SDK/Quartz64/QUARTZ64_SDK_android11.tar.gz Direct Download from pine64.org]
** MD5 (TAR-GZip file): 77c2ff57ea3372fb04da7fb49e17d12b
** File Size: 79.00GB
** Just the boot blobs (<1MB): [[File:Rk35-blobs.tar.gz]]

== How-To ==

=== Building Mainline U-Boot ===

See [[Quartz64 Building U-Boot]].

== Troubleshooting ==

This section provides information on troubleshooting various common issues you may encounter using the SOQuartz.

=== Thermal Issues ===

The SOQuartz SoM does not have a lot of copper to sink heat into. Therefore, it's recommended you use a heatsink such as the [https://www.waveshare.com/product/accessories/power-heat-sinks/heat-sinks/cm4-heatsink.htm Waveshare CM4 Heatsink], the [https://www.waveshare.com/product/accessories/power-heat-sinks/heat-sinks/cm4-heatsink-b.htm other Waveshare CM4 Heatsink], or the [https://pine64.com/product/small-fan-type-heatsink/ PINE64 Small Fan Type Heatsink]. Please be aware that the Waveshare heatsinks may interfere with any eMMC module, unless you use very thick (2-3mm?) thermal pads. (Note: a lot of local resellers will sell CM4 heatsinks or small stick-on heatsinks, no need to order them from abroad unless it's cheaper!)

Alternatively, or in addition to this, a rectangle of 1mm thick thermal pad can be sandwiched between the SoM and the carrier board. This allows the SoM to more efficiently sink heat into the larger mass of the base board.

[[Category:SOQuartz]] [[Category:Quartz64]]

Quartz64

2023-08-31T09:20:59Z

CounterPillow: /* Storage */ note about SATA port

[[File:Quartz64modelb.png|400px|thumb|right|The Quartz64 Model B]]

The '''Quartz64''' is the most recent Single Board Computer offering from PINE64, with Model A initially released in June of 2021 and Model B in May of 2022. It is powered by a Rockchip RK3566 Quad-Core ARM Cortex A55 64-Bit Processor with a MALI G-52 GPU.

Key features include a PCIe x4 open ended slot (model A) or m.2 (model B) using one Gen2 lane electrically, and the use of LPDDR4 RAM.

The Quartz64 has three LPDDR4 system memory options: 2GB, 4GB or 8GB. For booting, there is an eMMC module socket (supporting up to 128GB) and microSD slot, as well as a footprint to solder on an SPI flash chip. The board is equipped with HDMI, 1x USB 3.0 type A Host, 3x USB 2.0 Host, Gigabit Ethernet, SATA (model A), GPIO Bus, MiPi DSI interface, e-ink interface (model A), eDP interface (model A), touch Panel interface (model A), MiPi CSI interface, as well as many other device interfaces such as UART, SPI, I2C, for makers to integrate with sensors and other peripherals. Many different Operating Systems (OS) are freely available from the open source community, such as Linux (Ubuntu, Debian, Arch), BSD, and Android.

== Software releases ==

Under [[Quartz64 Software Releases]] you will find a complete list of currently supported operating system images, which work with the Quartz64, as well as other related software.

== Getting started ==

=== Flashing the device ===

Natively the board only supports booting from the eMMC or microSD card, see [[#Boot order|boot order]]. There doesn't seem to be a way to boot from USB devices or SATA yet.

The board can be booted by flashing your favorite operating system to a microSD card using another device and to insert the microSD card into the Quartz64, see the article [[Getting started]]. Flashing the eMMC is possible by booting an operating system from the microSD card and to overwrite the eMMC from within the booted operating system.

=== Boot order ===

The hardware boot order of the Quartz64 is:

# SPI NOR flash
# SPI NAND flash
# eMMC
# microSD card

== SoC and Memory Specifications ==

[[File:RK3566_icon.png|right]]

* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]

=== CPU Architecture ===

* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache
* [https://developer.arm.com/ip-products/security-ip/trustzone TrustZone] technology support
* [https://www.cnx-software.com/2020/12/01/rockchip-rk3568-processor-to-power-edge-computing-and-nvr-applications 22nm process, believed to be FD-SOI]

=== GPU (Graphics Processing Unit) Capabilities ===

* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== NPU (Neural Processing Unit) Capabilities ===

* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===

* RAM Memory Variants: 2GB (SOQuartz only), 4GB, 8GB LPDDR4.

=== Network ===

* 10/100/1000Mbps Ethernet
* Wi-Fi 802.11 b/g/n/ac with Bluetooth 5.0 (optional on model A, built in on model B)

=== Storage ===

* microSD - bootable, supports SDHC and SDXC, storage up to 2TB
* USB
** Model A: 2 USB 2.0 host ports, 1 USB 2.0 OTG port, 1 USB 3.0 host port
** Model B: 1 USB 2.0 host port, 1 USB 2.0 OTG port, 1 USB 3.0 host port
* one native SATA 3.0 6Gb/s Port (only on model A, shared with USB 3.0 host port) (removed in newer revisions due to electrical signalling issues it caused)
* optional eMMC module from 8GB up to 128GB
* 64 Mbit (8 MByte) SPI flash (Model B only), part number '''25Q64DWZPIG''' in the schematic

==== eMMC Speeds ====

On a 64 GB eMMC module:

$ sudo hdparm -tT /dev/mmcblk1

/dev/mmcblk1:
Timing cached reads: 2368 MB in 2.00 seconds = 1184.46 MB/sec
Timing buffered disk reads: 452 MB in 3.01 seconds = 149.98 MB/sec

=== Expansion Ports ===
* HDMI
* eDP - 4 lanes of 2.7Gbps, up to 2560x1600@60Hz (only on model A)
* DSI - Display Serial Interface, 4 lanes MiPi, up to 1440P on model A, 2 lanes MiPi, up to 1080p on model B
* CSI - CMOS Camera Interface, 4 lanes MiPi up to 8 mega pixel on model A, 2 lanes MiPi up to 5 mega pixel on model B
* TP - Touch Panel Port, SPI with interrupt on model A
* RTC - Real Time Clock Battery Connector
* VBAT - Lithium Battery Connector with temperature sensor input on model A
* Wi-Fi/BT Module Header - SDIO 3.0 and UART on model A, built-in Wi-Fi/BT Module on model B
* 2x20 pins "Pi2" GPIO Header on model B, 2x10 pins GPO header on model A
* PCIe x4 open ended slot on model A, m.2 slot on model B, one Gen2 lane due to SoC constraints
** On Model A, the slot provides 10W of power for the 3.3V supply and however much power your 12V input power supply provides on the 12V supply

The PCIe implementation on the RK3566 is much more compatible with a wide range of devices compared to the one on the RK3399 used on the ROCKPro64. This means a lot more devices should work (excluding dGPUs due to a lack of cache snooping ability).

==== Combo PHYs ====

[[File:rk3566 phy.png|400px]]

Several of the I/O options on the RK3566 used in the Quartz64 are using the same I/O lines, meaning that they cannot be used at the same time. The above diagram illustrates how they are connected.

In particular, USB 3.0 and the SATA connector on the board are mutually exclusive, and the PCI-e 2.0 lane can be reconfigured into a second SATA port, though an adapter cable needs to be fashioned for this to be useful.

=== GPIO Pins (Quartz64 Model A) ===

Attention! GPIOs are 3.3V!

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SDA_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SCL_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| CPU_REFCLK_OUT
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX_M0_DEBUG
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX_M0_DEBUG
|-
| style="text-align:right;"| SPI1_MOSI_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| UART0_TX a
|-
| style="text-align:right;"| SPI1_MISO_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| UART0_RX a
|-
| style="text-align:right;"| SPI1_CLK_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GND
|-
| style="text-align:right;"| SPI1_CS0_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 17
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| SPDIF_OUT c
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| 3.3V
|}

==== Notes ====
<ol style="list-style-type:lower-alpha">

<li>can be a PWM pin</li>

<li>pulled high to 3.3V through 2.2kOhm resistor</li>

<li>low-pass filtered with cutoff of 220 MHz</li>

</ol>

Source: Page 28 of [[File:Quartz64_model-A_schematic_v1.0_20201215.pdf|the board schematics]].

=== GPIO Pins (Quartz64 Model B) ===

Attention! GPIOs are 3.3V!

Interesting alternate pin configurations are listed in [brackets].

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 1
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SDA_M0]'' GPIO1_A0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SCL_M0]'' GPIO1_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_C4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX
|-
| style="text-align:right;"| ''[SPI1_CS0_M1]'' GPIO3_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| GPIO3_A3_3V3 ''[I2S3_SCLK_M0]''
|-
| style="text-align:right;"| ''[I2S3_MCLK_M0]'' GPIO3_A2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GPIO3_B1_3V3
|-
| style="text-align:right;"| 3.3V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 17
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| GPIO3_B2_3V3
|-
| style="text-align:right;"| GPIO4_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO4_C5_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 21
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 22
| style="text-align:left;"| GPIO3_C1_3V3 ''[SPI1_MOSI_M1]''
|-
| style="text-align:right;"| GPIO4_C2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 23
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 24
| style="text-align:left;"| GPIO4_C6_3V3
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 25
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 26
| style="text-align:left;"| GPIO4_D1_3V3
|-
| style="text-align:right;"| I2C4_SDA_M0
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 27
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 28
| style="text-align:left;"| I2C4_SCL_M0
|-
| style="text-align:right;"| GPIO3_B3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 29
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 30
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 31
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 32
| style="text-align:left;"| GPIO3_C2_3V3 ''[SPI1_MISO_M1]''
|-
| style="text-align:right;"| ''[SPI1_CLK_M1]'' GPIO3_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 33
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 34
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[I2S3_LRCK_M0]'' GPIO3_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 35
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 36
| style="text-align:left;"| GPIO3_A7_3V3
|-
| style="text-align:right;"| ''[SPDIF_TX_M0]'' GPIO1_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 37
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 38
| style="text-align:left;"| GPIO3_A6_3V3 ''[I2S3_SDI_M0]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 39
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 40
| style="text-align:left;"| GPIO3_A5_3V3 ''[I2S3_SDO_M0]''
|}

Source: Page 24 of [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf the board schematics].

== Quartz64 Board Information, Schematics, and Certifications ==

=== Model "A" ===

Model "A" Baseboard Dimensions: 133mm x 80mm x 19mm

Input Power: DC 12V @ 3A 5.5mmOD/2.1mmID center-positive Barrel DC Jack connector

Quartz64 Model "A" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_schematic_v2.0_20210427.pdf Quartz64 Model "A" SBC Schematic ver 2.0 20210427 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_V2.0_connector_placement.pdf Quartz64 Model "A" SBC PCB Connector placement PDF file]

Certifications:

* Disclaimer: Please note that PINE64 SBC is not a "final" product and in general certification is not necessary. However, PINE64 still submit the SBC for FCC and CE certification and obtain the certificates to proof that SBC board is capable on passing the testing. Please note a final commercial product needs to performs its owns testing and obtains its owns certificates.
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20CE%20certification-S21051101701001.pdf Quartz64 model-A CE Certificate]
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20FCC%20certification-S21051101702001.pdf Quartz64 model-A FCC Certificate]

=== Model "B" ===

Model "B" Baseboard Dimensions: 85mm x 56mm x 18.8mm

Input Power: DC 5V @ 3A 3.5mmOD/1.35mmID center-positive Barrel DC Jack connector

Quartz64 Model "B" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf Quartz64 Model "B" SBC Schematic ver 1.3 20220124 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_PCB_Components_Placement-V1.2_20211014.pdf Quartz64 Model "B" SBC PCB Connector placement PDF file]
* Please note that v1.2 and V1.3 schematic and component placement are identical, just some component value changed.
* Note: Model B uses a Molex PicoBlade compatible connector for the RTC battery. The Pine64 Backup Battery Holders come with a JST PH type connector. To use the Pine64 RTC Backup Battery Holder, the connector on the battery holder will need to be modified with a PicoBlade type connector.

== Datasheets for Components and Peripherals ==

Rockchip RK3566 SoC information:
* [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, already got release permission from Rockchip]
* [https://opensource.rock-chips.com/images/2/26/Rockchip_RK3568_TRM_Part1_V1.3-20220930P.PDF Rockchip RK3566 and RK3568 TRM (Technical Reference Manual)]

Rockchip PMU (Power Management Unit) Information:
* [https://www.rockchip.fr/RK817%20datasheet%20V1.01.pdf Rockchip RK817 ver 1.01 datasheet for Quartz64 model A]
* [https://www.rockchip.fr/RK809%20datasheet%20V1.01.pdf Rockchip RK809 ver 1.01 datasheet for Quartz64 model B and SOQuartz]

LPDDR4 (200 Balls) SDRAM:
* [https://files.pine64.org/doc/datasheet/rockpro64/SM512M32Z01MD2BNP(200BALL).pdf Micron LPDDR4 Mobile LPDDR4 Datasheet]

eMMC information:
* [https://files.pine64.org/doc/rock64/PINE64_eMMC_Module_20170719.pdf PINE64 eMMC module schematic]
* [https://files.pine64.org/doc/rock64/usb%20emmc%20module%20adapter%20v2.pdf PINE64 USB adapter for eMMC module V2 schematic]
* [https://files.pine64.org/doc/rock64/USB%20adapter%20for%20eMMC%20module%20PCB.tar PINE64 USB adapter for eMMC module PCB in JPEG]
* [https://files.pine64.org/doc/datasheet/pine64/E-00517%20FORESEE_eMMC_NCEMAM8B-16G%20SPEC.pdf 16GB Foresee eMMC Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/SDINADF4-16-128GB-H%20data%20sheet%20v1.13.pdf 32GB/64GB/128GB SanDisk eMMC Datasheet]

SPI NOR Flash information:
* [https://files.pine64.org/doc/datasheet/pine64/w25q128jv%20spi%20revc%2011162016.pdf WinBond 128Mb SPI Flash Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/GD25Q128C-Rev2.5.pdf GigaDevice 128Mb SPI Flash Datasheet]

E-ink Panel information:
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-754-V3_ES103TC1%20Specification%20V3.0(Signed)-20190702.pdf Eink 10.3" 1872x1404 ES103TC1 Flex Panel Specification]
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-828-V1_ED103TC2%20Formal%20Spec%20V1.0_20190514.pdf Eink 10.3" 1872x1404 ES103TC1 Glass Panel Specification]
* [https://files.pine64.org/doc/datasheet/PineNote/TI%20PMU-TPS651851.pdf TPS65185x PMIC for E-Ink Enabled Electronic Paper Display Datasheet]

LCD Touch Screen Panel information:
* [https://files.pine64.org/doc/datasheet/pine64/FY07024DI26A30-D_feiyang_LCD_panel.pdf 7.0" 1024x600 TFT-LCD Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/HK70DR2459-PG-V01.pdf Touch Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/GT911%20Capacitive%20Touch%20Controller%20Datasheet.pdf GOODiX GT911 5-Point Capacitive Touch Controller Datasheet]

Ethernet PHY information:
* [https://files.pine64.org/doc/datasheet/pine64/rtl8211e(g)-vb(vl)-cg_datasheet_1.6.pdf Realtek RTL8211 10/100/1000M Ethernet Transceiver]

Wi-Fi/BT module info:
* [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC Wi-Fi + Bluetooth5.0 Datasheet]

IR LED:
* [https://media.digikey.com/pdf/Data%20Sheets/Everlight%20PDFs/IRM-36xx_Series.pdf IRM-3638 Datasheet]

Enclosure information:
* [https://files.pine64.org/doc/datasheet/case/playbox_enclosure_20160426.stp Playbox Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/ABS_enclosure_20160426.stp ABS Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/pine64%20Die%20Cast%20casing-final.jpg Outdoor Aluminum Cast Dust-proof IP67 Enclosure Drawing]
* [https://www.printables.com/model/269572-pine-quartz-64-a-full-case 3D Printable Enclosure for Model A]
* [https://www.printables.com/model/269575-pine-quartz-64-a-open-frame Open Frame for Model A]

Connector information:
* [https://files.pine64.org/doc/datasheet/pine64/ePH.pdf 2.0mm PH Type connector specification use in Lithium Battery (VBAT) port (Model A)]
* [https://www.molex.com/pdm_docs/sd/533980271_sd.pdf 1.25mm Picoblade Type connector specification used in RTC Battery port (Model B)]
* [https://files.pine64.org/doc/datasheet/pine64/0.5FPC%20Front%20Open%20Connector%20H=1.5.pdf 0.5mm Pitch cover type FPC connector specification use in DSI port, TP port and CSI port]

== Development efforts ==

{{SeeMainArticle|Quartz64 Development}}

Information and resources of the ongoing development effort for the Quartz64 can be found on the [[Quartz64 Development]] page, where the current status of various board functions can be found, and whether they have landed in upstream.

* [https://gitlab.com/pine64-org/quartz-bsp Quartz64 BSP Gitlab Page]

== Enclosures ==

Note: Please expand this section with more cases known to work.

=== Model "A" ===

All enclosures that fit the ROCKPro64 should fit the Quartz64 Model "A", as the I/O has been laid out the same on purpose.

* [[Model A Acrylic Open Enclosure]] - but see the troubleshooting section below.
* [[Quartz64 Premium Aluminium Case|RockPro64 Premium Aluminium Case]]
* [[ROCKPro64#3D printable ITX mounting brackets]] (Not an enclosure but allows to mount the board in an ATX/ITX case)

=== Model "B" ===

* [[Model B Acrylic Open Enclosure]]
* the ROCK64 aluminium enclosure '''does not''' work, as the DC input jack is placed differently

== Troubleshooting ==

=== Stability/Boot Issues With Missing Battery Shunt ===

If there is no battery plugged into the board, the jumper labelled "ON/OFF_BATT" must be in place. If this is set wrong, stability issues such as failures to boot will occur. '''This affects model A only'''

=== No Ethernet Connectivity ===

Make sure the kernel is built with <code>CONFIG_MOTORCOMM_PHY</code> set to <code>y</code>. Building it as a module (<code>m</code>) and then relying on module auto-loading is unlikely to work, because if the generic PHY driver is built in it will bind to the PHY first, unless you include the motorcomm module in your initramfs.

Note: Starting with [https://salsa.debian.org/kernel-team/linux/-/merge_requests/551 Debian's <code>6.1~rc3-1~exp1</code> kernel] the module is included, but set to <code>m</code> and I (Diederik) have verified that it gets included in the initramfs and '''works''' on Model-A and Model-B with the [[Quartz64#Plebian]] images.

=== "Model A" Acrylic Case Doesn't Fit ===

The Quartz64 does not really fit onto the bottom plate of the [[Model A Acrylic Open Enclosure]]. This is because the "Mic" connector at the bottom of the board interferes with one of the posts. A workaround is to find out which post that is (you have a 50% chance of guessing it right, accounting for rotating the board) and then filing away the corner of the post pointing inwards by a few millimeters.

[[File:Quartz64-audio-jack-spacer-issue.jpg|400px]]

An alternate solution may be to place plastic spacers with a smaller outer diameter in between the acrylic bottom plate posts and the SBC board.

=== No GPU Acceleration with Debian "Bullseye" Userland ===

Debian Bullseye ships a Mesa version that is too old to contain the required patches for the RK356x SoC's GPU. You can (at your own risk) [https://wiki.debian.org/DebianTesting use the current Debian Testing version ], called "Bookworm".

=== Wireless Connectivity Doesn't Work ===

ROCKPro64 wireless module may have CYW43455 or CYW43456 chips on board (not sure if this is the same for Quartz64 model B). Both chips are supported by <code>brcmfmac</code> Wi-Fi driver and <code>btbcm</code> Bluetooth driver.

For CYW43455 drivers attempt to load <code>/lib/firmware/brcm/brcmfmac43455-sdio.bin</code> for Wi-Fi and <code>/lib/firmware/brcm/BCM4345C0.hcd</code> for Bluetooth. Corresponding firmware files for CYW43456 are <code>/lib/firmware/brcm/brcmfmac43456-sdio.bin</code> and <code>/lib/firmware/brcm/BCM4345C5.hcd</code>.

On Manjaro firmware files for both Bluetooth and Wi-Fi on CYW43456 on are provided by <code>ap6256-firmware</code> package (<code>pacman -S ap6256-firmware</code>).

However for CYW43455 wi-fi firmware is in the <code>linux-firmware</code> package and bluetooth is in the <code>firmware-raspberrypi</code> (<code>pacman -S linux-firmware firmware-raspberrypi</code>). <code>linux-firmware</code> package is missing device specific symlinks for quartz64-a. To create them execute:

# ln -s brcmfmac43455-sdio.bin /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.bin
# ln -s brcmfmac43455-sdio.AW-CM256SM.txt /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.txt

As of 2022-10-19 device tree in mainline kernel for Quartz64 model A has wrong configuration for the Bluetooth driver. [https://patchwork.kernel.org/project/linux-rockchip/patch/20220926125350.64783-1-leo@nabam.net/ Patch] is submitted to the LKML and accepted and included upstream in 6.1-rc7. It's possible to modify dtb file provided by the current kernel using device tree compiler to enable Bluetooth or perform <code>make dtbs</code> in the patched kernel tree to get updated dtb file (<code>arch/arm64/boot/dts/rockchip/rk3566-quartz64-a.dtb</code>). Issue manifests itself with following errors in `dmesg`:

command 0x0c03 tx timeout
Bluetooth: hci0: BCM: Reset failed (-110)

== How-To ==

=== Connect Debug UART ===

The easiest way to get debug output is to connect a 3.3V 1.5mbaud capable UART adapter to the board.

To connect it, connect the ground lead to pin 6, and the RX/TX leads to pins 8 and 10 (consider swapping them if you get no output, things are often mislabeled). These pins are "UART2" in the above GPIO table.

Open a serial terminal at 1500000 bauds, e.g.

$ picocom -b 1500000 /dev/ttyUSB0

=== Disable Heartbeat LED (Linux) ===

The flashing LED is called the "heartbeat LED", it blinks in a heart rhythm like fashion once the kernel is running. To disable it, you can run

# echo none > /sys/class/leds/user-led/trigger

On model A LED device is called "diy-led", not "user-led".

On a system with systemd, you can do this as soon as the system is ready to be logged in with a systemd unit like this:

[Unit]
Description=Turn off heartbeat LED
Wants=multi-user.target
After=multi-user.target

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
ExecStart=sh -c 'echo none > /sys/class/leds/user-led/trigger'

Place it in ''/etc/systemd/system/user-led.service'', and run

# systemctl daemon-reload
# systemctl enable user-led.service

Upon rebooting, you will now notice that the heartbeat LED will blink during boot-up, but stops blinking as soon as the multi-user target is reached (i.e. the user can log in).

=== SATA on model A ===

On model A USB 3.0 and SATA ports are using the same I/O line and can't be used simultaneously. By default USB 3.0 is enabled in Linux device tree and SATA is disabled. FDT modifications are required to turn SATA on.

Following script is tested on Manjaro but should work on the other distributions with minimal changes. Device tree compiler package usually provides fdtput command (on Manjaro run: <code>pacman -S dtc</code>)

# cp /boot/dtbs/rockchip/rk3566-quartz64-a.dtb /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /usb@fd000000 status disabled
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /sata@fc400000 status okay
# sed -i 's#^FDT /dtbs/rockchip/rk3566-quartz64-a.dtb$#FDT /dtbs/rockchip/rk3566-quartz64-a-sata.dtb#' /boot/extlinux/extlinux.conf
# systemctl reboot

=== Using a PCF8574 on Model A ===

See [[Quartz64 Model A using a PCF8574]].

=== Using a battery on Model A ===

See [[Quartz64 Model A Using a battery]].

=== Connecting a MIPI-DSI display ===

See [[Quartz64 connecting a MIPI-DSI display]].

=== Building Mainline U-Boot ===

See [[Quartz64 Building U-Boot]].

== Frequently Asked Questions ==

=== Do I Need A Fan/What Heatsink Do I Need? ===

You don't need a fan. The [https://pine64.com/product/rockpro64-20mm-mid-profile-heatsink/ 20mm medium heatsink for Model A is plenty enough]. For Model B, the [https://pine64.com/product/small-fan-type-heatsink/ fan type heatsink] will do fine.

=== Can This Run A Minecraft Server? ===

Yes! Sort of. Testing on an 8GB Model A with PaperMC, [[User:CounterPillow]] was able to out-row world generation in a boat with just one player online, but aside from the slow world gen (which can be pre-generated) the server handled things like TNT explosions and mobs fine. It'll probably do okay with 1-3 players.

=== Do I Need The 5A Power Supply For Model A? ===

You only need the 5A power supply for Model A if you plan on connecting hard disk drives to the 12V header on the board.

=== How Much Power Does It Consume? ===

For Model B, it's <2W in idle (powertop tunables not set), and <5W under full CPU load (<code>stress-ng -c4</code>). Model A will be similar as it's the same SoC.

[[Category:Quartz64]] [[Category:Rockchip RK3566]]

Quartz64 Building U-Boot

2023-08-31T09:08:50Z

CounterPillow: clarify cwd

This article guides you through compiling U-Boot for a [[Quartz64]] or [[SOQuartz]] device.

== Prerequisites ==

You will need either an x86 machine with an aarch64 cross-compiler installed, or an existing aarch64 system. You will also need the device tree compiler dtc, python3 (including setuptools and pyelftools), swig, GNU make and git.

On an x86_64 Arch Linux system, you can install the required dependencies with:

pacman -S --needed base-devel aarch64-linux-gnu-gcc aarch64-linux-gnu-binutils git dtc python-setuptools swig python-pyelftools

== Fetching The Repositories ==

Use git to clone the mainline U-Boot repository into the directory ''u-boot'':

git clone https://source.denx.de/u-boot/u-boot.git

You can use <code>git checkout <var>tagname</var></code> inside the ''u-boot'' directory to check out a specific git tag (release), you can list all of them with <code>git tag -l</code> (but do keep in mind we only have device support since v2023.10).

Then, also use git to clone the rockchip firmware binaries repository into the directory ''rkbin'':

git clone https://github.com/rockchip-linux/rkbin.git

== Setting Up Your Environment ==

Next, we need to set two environment variables: <code>ROCKCHIP_TPL</code> for the DRAM init binary, and <code>BL31</code> for the ARM Trusted Firmware binary.

cd u-boot
export ROCKCHIP_TPL="$(ls ../rkbin/bin/rk35/rk3566_ddr_1056MHz_v*.bin | sort | tail -n1)"
export BL31="$(ls ../rkbin/bin/rk35/rk3568_bl31_v*.elf | sort | tail -n1)"

== Configuring U-Boot ==

First, we need to use the right default config for our device. Please choose <var>defconfig</var> from the following table depending on your device:

{| class="wikitable" border="1"
! scope="col" | Board
! scope="col" | defconfig
|-
| Quartz64 Model A || <code>quartz64-a-rk3566_defconfig</code>
|-
| Quartz64 Model B || <code>quartz64-b-rk3566_defconfig</code>
|-
| SOQuartz on Model A || <code>soquartz-model-a-rk3566_defconfig</code>
|-
| SOQuartz on Blade || <code>soquartz-blade-rk3566_defconfig</code>
|-
| SOQuartz on CM4 I/O Board || <code>soquartz-cm4-rk3566_defconfig</code>
|}

In the ''u-boot'' directory with your environment variables set, run:

make CROSS_COMPILE=aarch64-linux-gnu- <var>defconfig</var>

with <var>defconfig</var> being the value from the previous table.

== Building U-Boot ==

In the ''u-boot'' directory, after configuring, and with your environment variables set, run:

make CROSS_COMPILE=aarch64-linux-gnu- -j$(nproc)

This will output a ''u-boot-rockchip.bin'', which is your freshly built SPL+U-Boot combined image.

[[Category:Quartz64]] [[Category:SOQuartz]] [[Category:Guide]] [[Category:Quartz64 Guides]]

SOQuartz

2023-08-31T09:02:30Z

CounterPillow: Add How-To section with U-Boot building article linked

Quartz64

2023-08-31T09:00:11Z

CounterPillow: /* How-To */ Add U-Boot building guide

[[File:Quartz64modelb.png|400px|thumb|right|The Quartz64 Model B]]

The '''Quartz64''' is the most recent Single Board Computer offering from PINE64, with Model A initially released in June of 2021 and Model B in May of 2022. It is powered by a Rockchip RK3566 Quad-Core ARM Cortex A55 64-Bit Processor with a MALI G-52 GPU.

Key features include a PCIe x4 open ended slot (model A) or m.2 (model B) using one Gen2 lane electrically, and the use of LPDDR4 RAM.

The Quartz64 has three LPDDR4 system memory options: 2GB, 4GB or 8GB. For booting, there is an eMMC module socket (supporting up to 128GB) and microSD slot, as well as a footprint to solder on an SPI flash chip. The board is equipped with HDMI, 1x USB 3.0 type A Host, 3x USB 2.0 Host, Gigabit Ethernet, SATA (model A), GPIO Bus, MiPi DSI interface, e-ink interface (model A), eDP interface (model A), touch Panel interface (model A), MiPi CSI interface, as well as many other device interfaces such as UART, SPI, I2C, for makers to integrate with sensors and other peripherals. Many different Operating Systems (OS) are freely available from the open source community, such as Linux (Ubuntu, Debian, Arch), BSD, and Android.

== Software releases ==

Under [[Quartz64 Software Releases]] you will find a complete list of currently supported operating system images, which work with the Quartz64, as well as other related software.

== Getting started ==

=== Flashing the device ===

Natively the board only supports booting from the eMMC or microSD card, see [[#Boot order|boot order]]. There doesn't seem to be a way to boot from USB devices or SATA yet.

The board can be booted by flashing your favorite operating system to a microSD card using another device and to insert the microSD card into the Quartz64, see the article [[Getting started]]. Flashing the eMMC is possible by booting an operating system from the microSD card and to overwrite the eMMC from within the booted operating system.

=== Boot order ===

The hardware boot order of the Quartz64 is:

# SPI NOR flash
# SPI NAND flash
# eMMC
# microSD card

== SoC and Memory Specifications ==

[[File:RK3566_icon.png|right]]

* Based on [https://www.rock-chips.com/a/en/products/RK35_Series/2021/0113/1274.html Rockchip RK3566]

=== CPU Architecture ===

* [https://developer.arm.com/ip-products/processors/cortex-a/cortex-a55 Quad-core ARM Cortex-A55@1.8GHz]
* AArch32 for full backwards compatibility with ARMv7
* ARM Neon Advanced SIMD (single instruction, multiple data) support for accelerated media and signal processing computation
* Includes VFP hardware to support single and double-precision operations
* ARMv8 Cryptography Extensions
* Integrated 32KB L1 instruction cache and 32KB L1 data cache per core
* 512KB unified system L3 cache
* [https://developer.arm.com/ip-products/security-ip/trustzone TrustZone] technology support
* [https://www.cnx-software.com/2020/12/01/rockchip-rk3568-processor-to-power-edge-computing-and-nvr-applications 22nm process, believed to be FD-SOI]

=== GPU (Graphics Processing Unit) Capabilities ===

* [https://developer.arm.com/ip-products/graphics-and-multimedia/mali-gpus/mali-g52-gpu Mali-G52 2EE Bifrost GPU@800MHz]
* 4x Multi-Sampling Anti-Aliasing (MSAA) with minimal performance drop
* 128KB L2 Cache configurations
* Supports OpenGL ES 1.1, 2.0, and 3.2
* Supports Vulkan 1.0 and 1.1
* Supports OpenCL 2.0 Full Profile
* Supports 1600 Mpix/s fill rate when at 800MHz clock frequency
* Supports 38.4 GLOP/s when at 800MHz clock frequency

=== NPU (Neural Processing Unit) Capabilities ===

* Neural network acceleration engine with processing performance of up to 0.8 TOPS
* Supports integer 8 and integer 16 convolution operations
* Supports the following deep learning frameworks: TensorFlow, TF-lite, Pytorch, Caffe, ONNX, MXNet, Keras, Darknet

=== System Memory ===

* RAM Memory Variants: 2GB (SOQuartz only), 4GB, 8GB LPDDR4.

=== Network ===

* 10/100/1000Mbps Ethernet
* Wi-Fi 802.11 b/g/n/ac with Bluetooth 5.0 (optional on model A, built in on model B)

=== Storage ===

* microSD - bootable, supports SDHC and SDXC, storage up to 2TB
* USB
** Model A: 2 USB 2.0 host ports, 1 USB 2.0 OTG port, 1 USB 3.0 host port
** Model B: 1 USB 2.0 host port, 1 USB 2.0 OTG port, 1 USB 3.0 host port
* one native SATA 3.0 6Gb/s Port (only on model A, shared with USB 3.0 host port)
* optional eMMC module from 8GB up to 128GB
* 64 Mbit (8 MByte) SPI flash (Model B only), part number '''25Q64DWZPIG''' in the schematic

==== eMMC Speeds ====

On a 64 GB eMMC module:

$ sudo hdparm -tT /dev/mmcblk1

/dev/mmcblk1:
Timing cached reads: 2368 MB in 2.00 seconds = 1184.46 MB/sec
Timing buffered disk reads: 452 MB in 3.01 seconds = 149.98 MB/sec

=== Expansion Ports ===
* HDMI
* eDP - 4 lanes of 2.7Gbps, up to 2560x1600@60Hz (only on model A)
* DSI - Display Serial Interface, 4 lanes MiPi, up to 1440P on model A, 2 lanes MiPi, up to 1080p on model B
* CSI - CMOS Camera Interface, 4 lanes MiPi up to 8 mega pixel on model A, 2 lanes MiPi up to 5 mega pixel on model B
* TP - Touch Panel Port, SPI with interrupt on model A
* RTC - Real Time Clock Battery Connector
* VBAT - Lithium Battery Connector with temperature sensor input on model A
* Wi-Fi/BT Module Header - SDIO 3.0 and UART on model A, built-in Wi-Fi/BT Module on model B
* 2x20 pins "Pi2" GPIO Header on model B, 2x10 pins GPO header on model A
* PCIe x4 open ended slot on model A, m.2 slot on model B, one Gen2 lane due to SoC constraints
** On Model A, the slot provides 10W of power for the 3.3V supply and however much power your 12V input power supply provides on the 12V supply

The PCIe implementation on the RK3566 is much more compatible with a wide range of devices compared to the one on the RK3399 used on the ROCKPro64. This means a lot more devices should work (excluding dGPUs due to a lack of cache snooping ability).

==== Combo PHYs ====

[[File:rk3566 phy.png|400px]]

Several of the I/O options on the RK3566 used in the Quartz64 are using the same I/O lines, meaning that they cannot be used at the same time. The above diagram illustrates how they are connected.

In particular, USB 3.0 and the SATA connector on the board are mutually exclusive, and the PCI-e 2.0 lane can be reconfigured into a second SATA port, though an adapter cable needs to be fashioned for this to be useful.

=== GPIO Pins (Quartz64 Model A) ===

Attention! GPIOs are 3.3V!

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SDA_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| I2C3_SCL_M0 a,b
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| CPU_REFCLK_OUT
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX_M0_DEBUG
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX_M0_DEBUG
|-
| style="text-align:right;"| SPI1_MOSI_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| UART0_TX a
|-
| style="text-align:right;"| SPI1_MISO_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| UART0_RX a
|-
| style="text-align:right;"| SPI1_CLK_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GND
|-
| style="text-align:right;"| SPI1_CS0_M1
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 17
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| SPDIF_OUT c
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| 3.3V
|}

==== Notes ====
<ol style="list-style-type:lower-alpha">

<li>can be a PWM pin</li>

<li>pulled high to 3.3V through 2.2kOhm resistor</li>

<li>low-pass filtered with cutoff of 220 MHz</li>

</ol>

Source: Page 28 of [[File:Quartz64_model-A_schematic_v1.0_20201215.pdf|the board schematics]].

=== GPIO Pins (Quartz64 Model B) ===

Attention! GPIOs are 3.3V!

Interesting alternate pin configurations are listed in [brackets].

{| class="wikitable plainrowheaders" border="1"
! scope="col" style="width:20em;" | Assigned To
! scope="col" | Pin no.
! scope="col" | Pin no.
! scope="col" style="width:20em;" | Assigned To
|-
| style="text-align:right;"| 3.3 V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 1
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 2
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SDA_M0]'' GPIO1_A0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 3
| style="text-align:center; background-color:red; color:gold; font-weight:bold;"| 4
| style="text-align:left;"| 5 V
|-
| style="text-align:right;"| ''[I2C3_SCL_M0]'' GPIO1_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 5
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 6
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_C4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 7
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 8
| style="text-align:left;"| UART2_TX
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 9
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 10
| style="text-align:left;"| UART2_RX
|-
| style="text-align:right;"| ''[SPI1_CS0_M1]'' GPIO3_A1_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 11
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 12
| style="text-align:left;"| GPIO3_A3_3V3 ''[I2S3_SCLK_M0]''
|-
| style="text-align:right;"| ''[I2S3_MCLK_M0]'' GPIO3_A2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 13
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 14
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B0_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 15
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 16
| style="text-align:left;"| GPIO3_B1_3V3
|-
| style="text-align:right;"| 3.3V
| style="text-align:center; background-color:yellow; color:black; font-weight:bold;"| 17
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 18
| style="text-align:left;"| GPIO3_B2_3V3
|-
| style="text-align:right;"| GPIO4_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 19
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 20
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO4_C5_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 21
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 22
| style="text-align:left;"| GPIO3_C1_3V3 ''[SPI1_MOSI_M1]''
|-
| style="text-align:right;"| GPIO4_C2_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 23
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 24
| style="text-align:left;"| GPIO4_C6_3V3
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 25
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 26
| style="text-align:left;"| GPIO4_D1_3V3
|-
| style="text-align:right;"| I2C4_SDA_M0
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 27
| style="text-align:center; background-color:blue; color:gold; font-weight:bold;"| 28
| style="text-align:left;"| I2C4_SCL_M0
|-
| style="text-align:right;"| GPIO3_B3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 29
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 30
| style="text-align:left;"| GND
|-
| style="text-align:right;"| GPIO3_B4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 31
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 32
| style="text-align:left;"| GPIO3_C2_3V3 ''[SPI1_MISO_M1]''
|-
| style="text-align:right;"| ''[SPI1_CLK_M1]'' GPIO3_C3_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 33
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 34
| style="text-align:left;"| GND
|-
| style="text-align:right;"| ''[I2S3_LRCK_M0]'' GPIO3_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 35
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 36
| style="text-align:left;"| GPIO3_A7_3V3
|-
| style="text-align:right;"| ''[SPDIF_TX_M0]'' GPIO1_A4_3V3
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 37
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 38
| style="text-align:left;"| GPIO3_A6_3V3 ''[I2S3_SDI_M0]''
|-
| style="text-align:right;"| GND
| style="text-align:center; background-color:black; color:gold; font-weight:bold;"| 39
| style="text-align:center; background-color:green; color:gold; font-weight:bold;"| 40
| style="text-align:left;"| GPIO3_A5_3V3 ''[I2S3_SDO_M0]''
|}

Source: Page 24 of [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf the board schematics].

== Quartz64 Board Information, Schematics, and Certifications ==

=== Model "A" ===

Model "A" Baseboard Dimensions: 133mm x 80mm x 19mm

Input Power: DC 12V @ 3A 5.5mmOD/2.1mmID center-positive Barrel DC Jack connector

Quartz64 Model "A" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_schematic_v2.0_20210427.pdf Quartz64 Model "A" SBC Schematic ver 2.0 20210427 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-A_V2.0_connector_placement.pdf Quartz64 Model "A" SBC PCB Connector placement PDF file]

Certifications:

* Disclaimer: Please note that PINE64 SBC is not a "final" product and in general certification is not necessary. However, PINE64 still submit the SBC for FCC and CE certification and obtain the certificates to proof that SBC board is capable on passing the testing. Please note a final commercial product needs to performs its owns testing and obtains its owns certificates.
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20CE%20certification-S21051101701001.pdf Quartz64 model-A CE Certificate]
* [https://files.pine64.org/doc/cert/Quartz64%20Model-A%20FCC%20certification-S21051101702001.pdf Quartz64 model-A FCC Certificate]

=== Model "B" ===

Model "B" Baseboard Dimensions: 85mm x 56mm x 18.8mm

Input Power: DC 5V @ 3A 3.5mmOD/1.35mmID center-positive Barrel DC Jack connector

Quartz64 Model "B" SBC Schematic and PCB Board Resource:

* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_Schematic-V1.3_20220124.pdf Quartz64 Model "B" SBC Schematic ver 1.3 20220124 PDF file]
* [https://files.pine64.org/doc/quartz64/Quartz64_model-B_PCB_Components_Placement-V1.2_20211014.pdf Quartz64 Model "B" SBC PCB Connector placement PDF file]
* Please note that v1.2 and V1.3 schematic and component placement are identical, just some component value changed.
* Note: Model B uses a Molex PicoBlade compatible connector for the RTC battery. The Pine64 Backup Battery Holders come with a JST PH type connector. To use the Pine64 RTC Backup Battery Holder, the connector on the battery holder will need to be modified with a PicoBlade type connector.

== Datasheets for Components and Peripherals ==

Rockchip RK3566 SoC information:
* [https://files.pine64.org/doc/quartz64/Rockchip%20RK3566%20Datasheet%20V1.0-20201210.pdf Rockchip RK3566 ver 1.0 datasheet, already got release permission from Rockchip]
* [https://opensource.rock-chips.com/images/2/26/Rockchip_RK3568_TRM_Part1_V1.3-20220930P.PDF Rockchip RK3566 and RK3568 TRM (Technical Reference Manual)]

Rockchip PMU (Power Management Unit) Information:
* [https://www.rockchip.fr/RK817%20datasheet%20V1.01.pdf Rockchip RK817 ver 1.01 datasheet for Quartz64 model A]
* [https://www.rockchip.fr/RK809%20datasheet%20V1.01.pdf Rockchip RK809 ver 1.01 datasheet for Quartz64 model B and SOQuartz]

LPDDR4 (200 Balls) SDRAM:
* [https://files.pine64.org/doc/datasheet/rockpro64/SM512M32Z01MD2BNP(200BALL).pdf Micron LPDDR4 Mobile LPDDR4 Datasheet]

eMMC information:
* [https://files.pine64.org/doc/rock64/PINE64_eMMC_Module_20170719.pdf PINE64 eMMC module schematic]
* [https://files.pine64.org/doc/rock64/usb%20emmc%20module%20adapter%20v2.pdf PINE64 USB adapter for eMMC module V2 schematic]
* [https://files.pine64.org/doc/rock64/USB%20adapter%20for%20eMMC%20module%20PCB.tar PINE64 USB adapter for eMMC module PCB in JPEG]
* [https://files.pine64.org/doc/datasheet/pine64/E-00517%20FORESEE_eMMC_NCEMAM8B-16G%20SPEC.pdf 16GB Foresee eMMC Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/SDINADF4-16-128GB-H%20data%20sheet%20v1.13.pdf 32GB/64GB/128GB SanDisk eMMC Datasheet]

SPI NOR Flash information:
* [https://files.pine64.org/doc/datasheet/pine64/w25q128jv%20spi%20revc%2011162016.pdf WinBond 128Mb SPI Flash Datasheet]
* [https://files.pine64.org/doc/datasheet/pine64/GD25Q128C-Rev2.5.pdf GigaDevice 128Mb SPI Flash Datasheet]

E-ink Panel information:
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-754-V3_ES103TC1%20Specification%20V3.0(Signed)-20190702.pdf Eink 10.3" 1872x1404 ES103TC1 Flex Panel Specification]
* [https://files.pine64.org/doc/quartz64/Eink%20P-511-828-V1_ED103TC2%20Formal%20Spec%20V1.0_20190514.pdf Eink 10.3" 1872x1404 ES103TC1 Glass Panel Specification]
* [https://files.pine64.org/doc/datasheet/PineNote/TI%20PMU-TPS651851.pdf TPS65185x PMIC for E-Ink Enabled Electronic Paper Display Datasheet]

LCD Touch Screen Panel information:
* [https://files.pine64.org/doc/datasheet/pine64/FY07024DI26A30-D_feiyang_LCD_panel.pdf 7.0" 1024x600 TFT-LCD Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/HK70DR2459-PG-V01.pdf Touch Panel Specification]
* [https://files.pine64.org/doc/datasheet/pine64/GT911%20Capacitive%20Touch%20Controller%20Datasheet.pdf GOODiX GT911 5-Point Capacitive Touch Controller Datasheet]

Ethernet PHY information:
* [https://files.pine64.org/doc/datasheet/pine64/rtl8211e(g)-vb(vl)-cg_datasheet_1.6.pdf Realtek RTL8211 10/100/1000M Ethernet Transceiver]

Wi-Fi/BT module info:
* [https://files.pine64.org/doc/datasheet/rockpro64/AW-CM256SM_DS_DF_V1.9_STD.pdf Azurewave CM256SM 11AC Wi-Fi + Bluetooth5.0 Datasheet]

IR LED:
* [https://media.digikey.com/pdf/Data%20Sheets/Everlight%20PDFs/IRM-36xx_Series.pdf IRM-3638 Datasheet]

Enclosure information:
* [https://files.pine64.org/doc/datasheet/case/playbox_enclosure_20160426.stp Playbox Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/ABS_enclosure_20160426.stp ABS Enclosure 3D file]
* [https://files.pine64.org/doc/datasheet/case/pine64%20Die%20Cast%20casing-final.jpg Outdoor Aluminum Cast Dust-proof IP67 Enclosure Drawing]
* [https://www.printables.com/model/269572-pine-quartz-64-a-full-case 3D Printable Enclosure for Model A]
* [https://www.printables.com/model/269575-pine-quartz-64-a-open-frame Open Frame for Model A]

Connector information:
* [https://files.pine64.org/doc/datasheet/pine64/ePH.pdf 2.0mm PH Type connector specification use in Lithium Battery (VBAT) port (Model A)]
* [https://www.molex.com/pdm_docs/sd/533980271_sd.pdf 1.25mm Picoblade Type connector specification used in RTC Battery port (Model B)]
* [https://files.pine64.org/doc/datasheet/pine64/0.5FPC%20Front%20Open%20Connector%20H=1.5.pdf 0.5mm Pitch cover type FPC connector specification use in DSI port, TP port and CSI port]

== Development efforts ==

{{SeeMainArticle|Quartz64 Development}}

Information and resources of the ongoing development effort for the Quartz64 can be found on the [[Quartz64 Development]] page, where the current status of various board functions can be found, and whether they have landed in upstream.

* [https://gitlab.com/pine64-org/quartz-bsp Quartz64 BSP Gitlab Page]

== Enclosures ==

Note: Please expand this section with more cases known to work.

=== Model "A" ===

All enclosures that fit the ROCKPro64 should fit the Quartz64 Model "A", as the I/O has been laid out the same on purpose.

* [[Model A Acrylic Open Enclosure]] - but see the troubleshooting section below.
* [[Quartz64 Premium Aluminium Case|RockPro64 Premium Aluminium Case]]
* [[ROCKPro64#3D printable ITX mounting brackets]] (Not an enclosure but allows to mount the board in an ATX/ITX case)

=== Model "B" ===

* [[Model B Acrylic Open Enclosure]]
* the ROCK64 aluminium enclosure '''does not''' work, as the DC input jack is placed differently

== Troubleshooting ==

=== Stability/Boot Issues With Missing Battery Shunt ===

If there is no battery plugged into the board, the jumper labelled "ON/OFF_BATT" must be in place. If this is set wrong, stability issues such as failures to boot will occur. '''This affects model A only'''

=== No Ethernet Connectivity ===

Make sure the kernel is built with <code>CONFIG_MOTORCOMM_PHY</code> set to <code>y</code>. Building it as a module (<code>m</code>) and then relying on module auto-loading is unlikely to work, because if the generic PHY driver is built in it will bind to the PHY first, unless you include the motorcomm module in your initramfs.

Note: Starting with [https://salsa.debian.org/kernel-team/linux/-/merge_requests/551 Debian's <code>6.1~rc3-1~exp1</code> kernel] the module is included, but set to <code>m</code> and I (Diederik) have verified that it gets included in the initramfs and '''works''' on Model-A and Model-B with the [[Quartz64#Plebian]] images.

=== "Model A" Acrylic Case Doesn't Fit ===

The Quartz64 does not really fit onto the bottom plate of the [[Model A Acrylic Open Enclosure]]. This is because the "Mic" connector at the bottom of the board interferes with one of the posts. A workaround is to find out which post that is (you have a 50% chance of guessing it right, accounting for rotating the board) and then filing away the corner of the post pointing inwards by a few millimeters.

[[File:Quartz64-audio-jack-spacer-issue.jpg|400px]]

An alternate solution may be to place plastic spacers with a smaller outer diameter in between the acrylic bottom plate posts and the SBC board.

=== No GPU Acceleration with Debian "Bullseye" Userland ===

Debian Bullseye ships a Mesa version that is too old to contain the required patches for the RK356x SoC's GPU. You can (at your own risk) [https://wiki.debian.org/DebianTesting use the current Debian Testing version ], called "Bookworm".

=== Wireless Connectivity Doesn't Work ===

ROCKPro64 wireless module may have CYW43455 or CYW43456 chips on board (not sure if this is the same for Quartz64 model B). Both chips are supported by <code>brcmfmac</code> Wi-Fi driver and <code>btbcm</code> Bluetooth driver.

For CYW43455 drivers attempt to load <code>/lib/firmware/brcm/brcmfmac43455-sdio.bin</code> for Wi-Fi and <code>/lib/firmware/brcm/BCM4345C0.hcd</code> for Bluetooth. Corresponding firmware files for CYW43456 are <code>/lib/firmware/brcm/brcmfmac43456-sdio.bin</code> and <code>/lib/firmware/brcm/BCM4345C5.hcd</code>.

On Manjaro firmware files for both Bluetooth and Wi-Fi on CYW43456 on are provided by <code>ap6256-firmware</code> package (<code>pacman -S ap6256-firmware</code>).

However for CYW43455 wi-fi firmware is in the <code>linux-firmware</code> package and bluetooth is in the <code>firmware-raspberrypi</code> (<code>pacman -S linux-firmware firmware-raspberrypi</code>). <code>linux-firmware</code> package is missing device specific symlinks for quartz64-a. To create them execute:

# ln -s brcmfmac43455-sdio.bin /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.bin
# ln -s brcmfmac43455-sdio.AW-CM256SM.txt /lib/firmware/brcm/brcmfmac43455-sdio.pine64,quartz64-a.txt

As of 2022-10-19 device tree in mainline kernel for Quartz64 model A has wrong configuration for the Bluetooth driver. [https://patchwork.kernel.org/project/linux-rockchip/patch/20220926125350.64783-1-leo@nabam.net/ Patch] is submitted to the LKML and accepted and included upstream in 6.1-rc7. It's possible to modify dtb file provided by the current kernel using device tree compiler to enable Bluetooth or perform <code>make dtbs</code> in the patched kernel tree to get updated dtb file (<code>arch/arm64/boot/dts/rockchip/rk3566-quartz64-a.dtb</code>). Issue manifests itself with following errors in `dmesg`:

command 0x0c03 tx timeout
Bluetooth: hci0: BCM: Reset failed (-110)

== How-To ==

=== Connect Debug UART ===

The easiest way to get debug output is to connect a 3.3V 1.5mbaud capable UART adapter to the board.

To connect it, connect the ground lead to pin 6, and the RX/TX leads to pins 8 and 10 (consider swapping them if you get no output, things are often mislabeled). These pins are "UART2" in the above GPIO table.

Open a serial terminal at 1500000 bauds, e.g.

$ picocom -b 1500000 /dev/ttyUSB0

=== Disable Heartbeat LED (Linux) ===

The flashing LED is called the "heartbeat LED", it blinks in a heart rhythm like fashion once the kernel is running. To disable it, you can run

# echo none > /sys/class/leds/user-led/trigger

On model A LED device is called "diy-led", not "user-led".

On a system with systemd, you can do this as soon as the system is ready to be logged in with a systemd unit like this:

[Unit]
Description=Turn off heartbeat LED
Wants=multi-user.target
After=multi-user.target

[Install]
WantedBy=multi-user.target

[Service]
Type=simple
ExecStart=sh -c 'echo none > /sys/class/leds/user-led/trigger'

Place it in ''/etc/systemd/system/user-led.service'', and run

# systemctl daemon-reload
# systemctl enable user-led.service

Upon rebooting, you will now notice that the heartbeat LED will blink during boot-up, but stops blinking as soon as the multi-user target is reached (i.e. the user can log in).

=== SATA on model A ===

On model A USB 3.0 and SATA ports are using the same I/O line and can't be used simultaneously. By default USB 3.0 is enabled in Linux device tree and SATA is disabled. FDT modifications are required to turn SATA on.

Following script is tested on Manjaro but should work on the other distributions with minimal changes. Device tree compiler package usually provides fdtput command (on Manjaro run: <code>pacman -S dtc</code>)

# cp /boot/dtbs/rockchip/rk3566-quartz64-a.dtb /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /usb@fd000000 status disabled
# fdtput -t s -v /boot/dtbs/rockchip/rk3566-quartz64-a-sata.dtb /sata@fc400000 status okay
# sed -i 's#^FDT /dtbs/rockchip/rk3566-quartz64-a.dtb$#FDT /dtbs/rockchip/rk3566-quartz64-a-sata.dtb#' /boot/extlinux/extlinux.conf
# systemctl reboot

=== Using a PCF8574 on Model A ===

See [[Quartz64 Model A using a PCF8574]].

=== Using a battery on Model A ===

See [[Quartz64 Model A Using a battery]].

=== Connecting a MIPI-DSI display ===

See [[Quartz64 connecting a MIPI-DSI display]].

=== Building Mainline U-Boot ===

See [[Quartz64 Building U-Boot]].

== Frequently Asked Questions ==

=== Do I Need A Fan/What Heatsink Do I Need? ===

You don't need a fan. The [https://pine64.com/product/rockpro64-20mm-mid-profile-heatsink/ 20mm medium heatsink for Model A is plenty enough]. For Model B, the [https://pine64.com/product/small-fan-type-heatsink/ fan type heatsink] will do fine.

=== Can This Run A Minecraft Server? ===

Yes! Sort of. Testing on an 8GB Model A with PaperMC, [[User:CounterPillow]] was able to out-row world generation in a boat with just one player online, but aside from the slow world gen (which can be pre-generated) the server handled things like TNT explosions and mobs fine. It'll probably do okay with 1-3 players.

=== Do I Need The 5A Power Supply For Model A? ===

You only need the 5A power supply for Model A if you plan on connecting hard disk drives to the 12V header on the board.

=== How Much Power Does It Consume? ===

For Model B, it's <2W in idle (powertop tunables not set), and <5W under full CPU load (<code>stress-ng -c4</code>). Model A will be similar as it's the same SoC.

[[Category:Quartz64]] [[Category:Rockchip RK3566]]

Quartz64 Building U-Boot

2023-08-31T08:58:33Z

CounterPillow: Create a guide on how to compile mainline U-Boot for Quartz64/SOQuartz

This article guides you through compiling U-Boot for a [[Quartz64]] or [[SOQuartz]] device.

== Prerequisites ==

You will need either an x86 machine with an aarch64 cross-compiler installed, or an existing aarch64 system. You will also need the device tree compiler dtc, python3 (including setuptools and pyelftools), swig, GNU make and git.

On an x86_64 Arch Linux system, you can install the required dependencies with:

pacman -S --needed base-devel aarch64-linux-gnu-gcc aarch64-linux-gnu-binutils git dtc python-setuptools swig python-pyelftools

== Fetching The Repositories ==

Use git to clone the mainline U-Boot repository into the directory ''u-boot'':

git clone https://source.denx.de/u-boot/u-boot.git

You can use <code>git checkout <var>tagname</var></code> to check out a specific git tag (release), you can list all of them with <code>git tag -l</code> (but do keep in mind we only have device support since v2023.10).

Then, also use git to clone the rockchip firmware binaries repository into the directory ''rkbin'':

git clone https://github.com/rockchip-linux/rkbin.git

== Setting Up Your Environment ==

Next, we need to set two environment variables: <code>ROCKCHIP_TPL</code> for the DRAM init binary, and <code>BL31</code> for the ARM Trusted Firmware binary.

cd u-boot
export ROCKCHIP_TPL="$(ls ../rkbin/bin/rk35/rk3566_ddr_1056MHz_v*.bin | sort | tail -n1)"
export BL31="$(ls ../rkbin/bin/rk35/rk3568_bl31_v*.elf | sort | tail -n1)"

== Configuring U-Boot ==

First, we need to use the right default config for our device. Please choose <var>defconfig</var> from the following table depending on your device:

{| class="wikitable" border="1"
! scope="col" | Board
! scope="col" | defconfig
|-
| Quartz64 Model A || <code>quartz64-a-rk3566_defconfig</code>
|-
| Quartz64 Model B || <code>quartz64-b-rk3566_defconfig</code>
|-
| SOQuartz on Model A || <code>soquartz-model-a-rk3566_defconfig</code>
|-
| SOQuartz on Blade || <code>soquartz-blade-rk3566_defconfig</code>
|-
| SOQuartz on CM4 I/O Board || <code>soquartz-cm4-rk3566_defconfig</code>
|}

In the ''u-boot'' directory with your environment variables set, run:

make CROSS_COMPILE=aarch64-linux-gnu- <var>defconfig</var>

with <var>defconfig</var> being the value from the previous table.

== Building U-Boot ==

In the ''u-boot'' directory, after configuring, and with your environment variables set, run:

make CROSS_COMPILE=aarch64-linux-gnu- -j$(nproc)

This will output a ''u-boot-rockchip.bin'', which is your freshly built SPL+U-Boot combined image.

[[Category:Quartz64]] [[Category:SOQuartz]] [[Category:Guide]] [[Category:Quartz64 Guides]]

Quartz64 UEFI with U-Boot

2023-08-05T11:39:08Z

CounterPillow: /* Performing the Installation */ nvm this was correct

{{note|'''Note:''' This article is a work-in-progress}}

This article is a guide to installing an [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] capable of booting generic aarch64 EFI images on a [[Quartz64]] or [[SOQuartz]] board.

== Prerequisites ==

{{note|'''Note:''' U-Boot on Quartz64 Model A currently doesn't appear to be able to always load things from USB mass storage devices depending on the device, you'll have to get creative with your installer medium.}}

We need two to three storage mediums:

* an SD card or eMMC module for U-Boot (advanced users may use the SPI flash on Model B)
* an SD card, eMMC module, USB thumb drive or NVMe drive for our installed system
* an SD card, eMMC module, USB thumb drive or NVMe drive for the installer

In practice, you can usually combine some of these into one, e.g. if you start your partitions at 16MiB you can have u-boot and your installed system reside on the same storage medium.

A good way to go about things is to put U-Boot on an SD card, and install the system on eMMC or NVMe, and boot the installer from an USB thumb drive.

== Flashing U-Boot ==

The first step is to flash U-Boot to our first device, either an SD card or an eMMC module. U-Boot here is the system's firmware, similar to the BIOS in an x86 PC.

You'll need a Linux, *BSD or macOS computer (any CPU architecture is fine), and a GitHub account to download Kwiboo's u-boot-build pipeline outputs with.

Download the U-Boot build for your specific device from the latest RK356x Actions run of [https://github.com/Kwiboo/u-boot-build/actions Kwiboo's u-boot-build workflow repository]. Make sure you are downloading the correct build for your device, e.g. '''don't''' use <code>rk3566-quartz64-a</code> on a SOQuartz!

Extract the <code>u-boot-rockchip.bin</code> from the zip archive.

Next, insert the microSD card into your microSD reader, or attach the eMMC module to your eMMC to USB adapter and plug it in. Identify which <code>/dev/</code> device node it showed up at, and ideally wipe any filesystems and partitions on the device. From now on, we'll refer to it as <var>/dev/sdX</var>.

To flash U-Boot, write <code>u-boot-rockchip.bin</code> to byte 32768 of <var>/dev/sdX</var>. You can do this with <code>dd</code> as follows:

sudo dd if=u-boot-rockchip.bin of=<var>/dev/sdX</var> bs=32k seek=1 conv=fsync

{{note|'''Note:''' Double-check you have the right device before doing this! You don't want to flash this to one of your computer's actual disks.}}

== Flashing a Distro Installer ==

Assuming you want to boot an installer rather than some image, you'll want to flash a distribution's aarch64 EFI installation ISO to e.g. an USB thumb drive.

Some examples for installers that fit this criteria:

* '''Fedora Server:''' https://fedoraproject.org/server/download/ (Choose ''For ARM® aarch64 systems, DVD ISO'')
* '''Fedora Workstation:''' https://fedoraproject.org/workstation/download/ (Choose ''For ARM® aarch64 systems, Live ISO'')
* '''openSUSE Tumbleweed:''' https://get.opensuse.org/tumbleweed/ (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
** Tested on 2023-07-28 by [[User:CounterPillow]] on a Quartz64 Model B, installer booted from USB3 thumb drive. Installer has about 1 minute of showing a black screen until things appear on HDMI.
** Note: Installer overwrites U-Boot if installing on the U-Boot medium even with offset! Flashing U-Boot again after installation works.
** Note: Some concerning panfrost clk errors in dmesg and KDE Plasma Desktop defaults to X11 for now, not a good user experience
* '''openSUSE MicroOS:''' https://get.opensuse.org/microos/#download (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
* '''Ubuntu Server:''' https://ubuntu.com/download/server/arm (Choose either the latest LTS or the latest non-LTS)
** Tested on 2023-07-29 by [[User:CounterPillow]] on a Quartz64 Model B, Ubuntu 22.04.2 LTS, installer booted from USB3 thumb drive. Only installer boot tested, no installation performed.
** Note: You '''need''' to choose the HWE kernel in GRUB over Serial Console for 22.04 LTS, otherwise the installer won't boot
** Note: Does not allow setting an offset for partitions, so can't use the same medium for both u-boot and root
** Note: Some concerning panfrost clk errors in dmesg while installer boots, unsure if GPU will be happy

If you're going to use something else, then please make sure the distribution image you're going to use has a not too ancient kernel; check [[Quartz64 Development]] for which kernel versions bring which drivers. Also make sure the distribution's kernel has the right drivers enabled in its kernel configuration.

To prepare the installation medium, simply use your preferred image flashing utility to write the ISO to e.g. a USB thumb drive. You can also use <code>dd</code> for this.

== Performing the Installation ==

Attach your two to three storage mediums (U-Boot medium, installer medium and target drive) and attach power. If everything went well, you should be booted into the distribution's guided installer. If everything did not go well, use a serial adapter like the PINE64 Woodpecker to get serial output from U-Boot at 1500000 bauds.

Complete the installation. If you want to use your U-Boot medium as your target drive here, make sure to manually partition and leave 16MiB or more space at the start of the drive (block 32768), so that U-Boot is not overwritten.

After the installation completes, power off the board, remove the installer medium, and power it back on. You should now be booted into your freshly installed system.

[[Category:Guide]] [[Category:Quartz64]] [[Category:Quartz64 Guides]]

Quartz64 UEFI with U-Boot

2023-08-05T11:38:47Z

CounterPillow: /* Performing the Installation */

{{note|'''Note:''' This article is a work-in-progress}}

This article is a guide to installing an [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] capable of booting generic aarch64 EFI images on a [[Quartz64]] or [[SOQuartz]] board.

== Prerequisites ==

{{note|'''Note:''' U-Boot on Quartz64 Model A currently doesn't appear to be able to always load things from USB mass storage devices depending on the device, you'll have to get creative with your installer medium.}}

We need two to three storage mediums:

* an SD card or eMMC module for U-Boot (advanced users may use the SPI flash on Model B)
* an SD card, eMMC module, USB thumb drive or NVMe drive for our installed system
* an SD card, eMMC module, USB thumb drive or NVMe drive for the installer

In practice, you can usually combine some of these into one, e.g. if you start your partitions at 16MiB you can have u-boot and your installed system reside on the same storage medium.

A good way to go about things is to put U-Boot on an SD card, and install the system on eMMC or NVMe, and boot the installer from an USB thumb drive.

== Flashing U-Boot ==

The first step is to flash U-Boot to our first device, either an SD card or an eMMC module. U-Boot here is the system's firmware, similar to the BIOS in an x86 PC.

You'll need a Linux, *BSD or macOS computer (any CPU architecture is fine), and a GitHub account to download Kwiboo's u-boot-build pipeline outputs with.

Download the U-Boot build for your specific device from the latest RK356x Actions run of [https://github.com/Kwiboo/u-boot-build/actions Kwiboo's u-boot-build workflow repository]. Make sure you are downloading the correct build for your device, e.g. '''don't''' use <code>rk3566-quartz64-a</code> on a SOQuartz!

Extract the <code>u-boot-rockchip.bin</code> from the zip archive.

Next, insert the microSD card into your microSD reader, or attach the eMMC module to your eMMC to USB adapter and plug it in. Identify which <code>/dev/</code> device node it showed up at, and ideally wipe any filesystems and partitions on the device. From now on, we'll refer to it as <var>/dev/sdX</var>.

To flash U-Boot, write <code>u-boot-rockchip.bin</code> to byte 32768 of <var>/dev/sdX</var>. You can do this with <code>dd</code> as follows:

sudo dd if=u-boot-rockchip.bin of=<var>/dev/sdX</var> bs=32k seek=1 conv=fsync

{{note|'''Note:''' Double-check you have the right device before doing this! You don't want to flash this to one of your computer's actual disks.}}

== Flashing a Distro Installer ==

Assuming you want to boot an installer rather than some image, you'll want to flash a distribution's aarch64 EFI installation ISO to e.g. an USB thumb drive.

Some examples for installers that fit this criteria:

* '''Fedora Server:''' https://fedoraproject.org/server/download/ (Choose ''For ARM® aarch64 systems, DVD ISO'')
* '''Fedora Workstation:''' https://fedoraproject.org/workstation/download/ (Choose ''For ARM® aarch64 systems, Live ISO'')
* '''openSUSE Tumbleweed:''' https://get.opensuse.org/tumbleweed/ (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
** Tested on 2023-07-28 by [[User:CounterPillow]] on a Quartz64 Model B, installer booted from USB3 thumb drive. Installer has about 1 minute of showing a black screen until things appear on HDMI.
** Note: Installer overwrites U-Boot if installing on the U-Boot medium even with offset! Flashing U-Boot again after installation works.
** Note: Some concerning panfrost clk errors in dmesg and KDE Plasma Desktop defaults to X11 for now, not a good user experience
* '''openSUSE MicroOS:''' https://get.opensuse.org/microos/#download (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
* '''Ubuntu Server:''' https://ubuntu.com/download/server/arm (Choose either the latest LTS or the latest non-LTS)
** Tested on 2023-07-29 by [[User:CounterPillow]] on a Quartz64 Model B, Ubuntu 22.04.2 LTS, installer booted from USB3 thumb drive. Only installer boot tested, no installation performed.
** Note: You '''need''' to choose the HWE kernel in GRUB over Serial Console for 22.04 LTS, otherwise the installer won't boot
** Note: Does not allow setting an offset for partitions, so can't use the same medium for both u-boot and root
** Note: Some concerning panfrost clk errors in dmesg while installer boots, unsure if GPU will be happy

If you're going to use something else, then please make sure the distribution image you're going to use has a not too ancient kernel; check [[Quartz64 Development]] for which kernel versions bring which drivers. Also make sure the distribution's kernel has the right drivers enabled in its kernel configuration.

To prepare the installation medium, simply use your preferred image flashing utility to write the ISO to e.g. a USB thumb drive. You can also use <code>dd</code> for this.

== Performing the Installation ==

Attach your two to three storage mediums (U-Boot medium, installer medium and target drive) and attach power. If everything went well, you should be booted into the distribution's guided installer. If everything did not go well, use a serial adapter like the PINE64 Woodpecker to get serial output from U-Boot at 1500000 bauds.

Complete the installation. If you want to use your U-Boot medium as your target drive here, make sure to manually partition and leave 16MiB or more space at the start of the drive (byte 32768), so that U-Boot is not overwritten.

After the installation completes, power off the board, remove the installer medium, and power it back on. You should now be booted into your freshly installed system.

[[Category:Guide]] [[Category:Quartz64]] [[Category:Quartz64 Guides]]

Quartz64 Development

2023-07-31T10:21:37Z

CounterPillow: /* Linux Kernel Config Options */ oops, was already on there

This page documents the current status of software support for the [[Quartz64]] single-board computer, and provides links to resources to help prospective contributors get started. Information is kept current on a best-effort basis as various patches get accepted into the kernel.

== Overview ==

=== Upstreaming Status ===

{| class="wikitable plainrowheaders" border="1"
! scope="col" | Function
! scope="col" colspan="2" | Status
! scope="col" | Component
! scope="col" | Notes
! scope="col" | Applies To
|-
! scope="row" rowspan="3" | Video Output
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchipdrm/VOP2</code>
|
As of 5.19-rc1[https://git.kernel.org/linus/604be85547ce4d61b89292d2f9a78c721b778c16], Also featured in Phoronix Article[https://www.phoronix.com/scan.php?page=news_item&px=Rockchip-VOP2-Linux-5.19]
|-
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rockchip-edpphy-naneng</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/blob/quartz64/drivers/phy/rockchip/phy-rockchip-naneng-edp.c] and [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/commit/d7ad116fb30d11d110aeb880754cf27f34c45c40#7e8e2ef87e479c54539dc519c0b92d6b31727f8d_671_681] Coordinate any porting with Rockchip first
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>dw-mipi-dsi-rockchip</code>
| As of 6.1[https://git.kernel.org/linus/e18d9b093006d8abd53e1ce13c0d5a8d0fcd5f64]
|
|-
! scope="row" | 3D Acceleration
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:PaleGreen; text-align:center;"|Upstream Mesa
| <code>panfrost</code>
| As of 5.18[https://git.kernel.org/linus/810028668c6d9da25664195d6b906c98a8169f72]
|-
! scope="row" rowspan="3" | Video Decode
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:LightYellow; text-align:center;" rowspan="3"|GStreamer only, no ffmpeg[https://patchwork.ffmpeg.org/project/ffmpeg/list/?series=2898]
| <code>hantro</code> using <code>v4l2-requests</code>
| VDPU121 handling 1080p MPEG-2, VP8 and H.264. Mainline as of 5.19[https://git.kernel.org/linus/5f6bfab6da6531238e899fdf29efd6d0185adc3e]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkvdec2</code> using <code>v4l2-requests</code>
| VDPU346 handling 4K H.265, H.264 and VP9
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkdjpeg</code> using <code>v4l2-requests</code>
| VDPU720 handling JPEG, [[User:CounterPillow]] is working on this
|-
! scope="row" rowspan="5" | [[Mainline Hardware Encoding|Video Encode]]
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="text-align:center; background:LightYellow;"|GStreamer only
| JPEG on VEPU121
| Hantro-based. Mainline as of 6.1[https://git.kernel.org/linus/6f1ae821a6c4aa9d5b8f437b27ec86fb569219fd]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| VP8 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU540
| rkvenc-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.265 on VEPU540
| rkvenc-based
|
|-
! scope="row" rowspan="3" | Audio
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-i2s-tdm</code>
| As of 5.16[https://git.kernel.org/linus/43b058698f723e3c2087af7069c0da082a3ecbe1]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-spdif</code>
| As of 5.15[https://git.kernel.org/linus/dac825b6a6bdca41347e25f07354ad94fdc97445]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-codec</code>
| As of 5.14[https://git.kernel.org/linus/0d6a04da9b25b9a7cf2cac5f5079e3296d3bee0f].
| Quartz64 Model A/B
|-
! scope="row" rowspan="3" | Bootloader
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/16952]
| <code>TF-A</code>
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://patchwork.ozlabs.org/project/uboot/list/?series=365266&state=*]
| <code>U-Boot</code>
| [[Quartz64_Development#Mainline_U-Boot_Work|See below]]
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|In progress[https://github.com/jaredmcneill/quartz64_uefi]
| <code>Tianocore EDK II</code>
|
|-
! scope="row" rowspan="4" | Device Tree
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model A
| As of 5.16[https://git.kernel.org/linus/b33a22a1e7c4248608e533fc4fa524258b3fae84]
| Quartz64 Model A
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model B
| As of 5.19[https://git.kernel.org/linus/c37415f55bdadffe5b4c0e7981e9fc7e8b96beea]
| Quartz64 Model B
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| SOQuartz
| As of 5.19[https://git.kernel.org/linus/c466828fb3ba8cb7f5c3bf28766da9b70bf9745e]
| SOQuartz
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| PineNote
| As of 5.18[https://git.kernel.org/linus/d449121e5e8addcee654250cec298c887ecafb32]
| PineNote
|-
! scope="row" rowspan="2"| Gigabit Ethernet
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3566-gmac</code>
| As of 5.14[https://git.kernel.org/linus/3bb3d6b1c1957e88bfc5e77a4557f7e6ba761fe3]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>yt8511-phy</code>
| As of 5.14[https://git.kernel.org/linus/48e8c6f1612b3d2dccaea2285231def830cc5b8e]
|-
! scope="row" | IOMMU
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-iommu</code>
| As of 5.14[https://git.kernel.org/linus/c55356c534aa651ccc3053ef2d5d8d810adacf5f]
|-
! scope="row" | GPIO
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>gpio-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/936ee2675eee1faca0dcdfa79165c7990422e0fc]
|-
! scope="row" | pinctrl
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
|
|
|-
! scope="row" | Thermal Regulation
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-thermal</code>
| As of 5.14[https://git.kernel.org/linus/4b14c055a6f644cbeb1156ba24647e92fe51ec69]
|-
! scope="row" | PCIe
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>pcie-dw-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/0e898eb8df4e34c7b129452444eb7cef68a11f43]
|-
! scope="row" | Power Management
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-pm-domains</code>
| As of 5.14[https://git.kernel.org/linus/1782c87b44a0b1a527f01a6a184677c58ccbf9c7]
|-
! scope="row" | Voltage Control
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3568-pmu-io-voltage-domain</code>
| As of 5.15[https://git.kernel.org/linus/28b05a64e47cbceebb8a5f3f643033148d5c06c3]
|-
! scope="row" | SPI
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>spi-rockchip</code>
| As of 5.14[https://git.kernel.org/linus/d74d99229f4d48f42d674f7a8a1137179efd67ac]. Necessary device tree changes [https://patchwork.kernel.org/project/linux-rockchip/list/?series=586691 in review].
|-
! scope="row" | Battery
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-charger</code>
| As of 6.1[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/power/supply/rk817_charger.c?id=11cb8da0189b417392e2334ae967b0ba1f0d1be8]
| Quartz64 Model A, Pinenote
|-
! scope="row" | Microphone
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-saradc</code>
| As of 5.15[https://git.kernel.org/linus/7786da3b5ae167c17f35e22ba35e06006338c2f6]. Headphone jack mic seems to connect to <code>SARADC_VIN2_HP_HOOK</code>, so I'm pretty sure that the dtsi and driver changes are needed for that mic to work
|-
! scope="row" | USB 2.0
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-usb2phy</code>
| As of 5.17[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/phy/rockchip?h=v5.17-rc1&id=42b559727a45d79c811f493515eb9b7e56016421]
|-
! scope="row" | e-Ink
| colspan="2" style="background:LightYellow; text-align:center;"|In review (RFC)[https://lore.kernel.org/linux-rockchip/20220413221916.50995-1-samuel@sholland.org/T/]
| <code>rockchip-ebc</code>
| A DRM driver is available [https://github.com/smaeul/linux/commits/rk35/ebc-drm-v5 here]; also see [[RK3566 EBC Reverse-Engineering]]
|-
! scope="row" | Combo PHY
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>naneng-combphy</code>
| As of 5.18[https://git.kernel.org/linus/7160820d742a16313f7802e33c2956c19548e488]. Still requires DTS changes
|-
! scope="row" | RGA
| colspan="2" style="background:#F99; text-align:center;"|Needs fixing
| <code>rockchip-rga</code>
| [[User:CounterPillow]] experimentally enabled it[https://gist.github.com/CounterPillow/6bea809f15ada7ddd3a3d7a4994fdc4e] in the device tree and ran gstreamer's v4l2convert through it to test, resulting in a completely garbled output.
|-
! scope="row" | Fan Controller
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
| <code>gp7101</code>
| Someone should write a pwm driver for it so we can then use pwm-fan
| SOQuartz Blade
|-
! scope="row" rowspan="2" | CSI Camera
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rkisp</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/media/platform/rockchip/isp]
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-inno-csidphy</code>
| As of 6.1[https://git.kernel.org/linus/29c99fb085ad53e6d5504d1f8d32e6673b9b3a2c]
|
|-
! scope="row" | NPU
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
|
| Downstream version is a closed source SDK and [https://github.com/dieselnutjob/kernel-rk3566/tree/linux-4.19.210/drivers/rknpu open source kernel module rknpu]. Major undertaking to reimplement this as Linux does not (yet) appear to have a generic architecture for neural accelerators.
|
|-
! scope="row" | Crypto
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rk-crypto</code> v2
| Downstream driver [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/crypto/rockchip] doesn't include a rk3568 compatible either, but the TRM shows that it seemingly matches.
|
|-
! scope="row" | TRNG
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://patchwork.kernel.org/project/linux-rockchip/list/?series=699813]
| <code>rockchip-rng</code>
|
|
|-
! scope="row" rowspan="2" | Wi-Fi
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>bes2600</code>
| A downstream driver is available but it makes use of some custom Rockchip interfaces and is designed for older kernels, plans are being made to port it to DKMS.
| PineTab 2
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>brcmfmac</code>
|
| Quartz64 Model B
|}

== Current Status ==

The following sections give an overview over the current status of different parts of the board. Some parts are waiting on a driver to be written or ported, others only need various adjustments.

According to pgwipeout, I/O device performance is within expected ranges now.

=== Working ===

* eMMC
* SDMMC0 (SD cards)
* GMAC (Gigabit Ethernet)
* USB 2.0
* SATA 2
* SATA 3
* UART
** UART 0 (Pi-bus)
** UART 1 (Bluetooth)
** UART 2 (Pi-bus, debug)
* Video Decode
** VP8
** H.264
* Video Encode
** JPEG (it's pretty bad)
* Battery
* GPU
* Audio
** Analog audio works
** SPDIF works
** HDMI works
* SPI — works, user needs to modify device tree to add devices
* I2C — works, user needs to modify device tree to add devices

=== Partially Working ===

* PCI-Express Controller — everything but devices that need cache coherency (e.g. dGPUs) should work
** [[User:CounterPillow]] noticed some weirdness with NVMe devices disconnecting during heavy write operations, likely down due to power draw on one of the rails as the same sustained bandwidth could be achieved with a different PCIe device with no issue.
* SDMMC1 (Wi-Fi) — AP6256 working, BL602 needs some work to make it flash firmware
* [https://developer.arm.com/architectures/system-architectures/system-components/arm-generic-interrupt-controller GIC] — needs errata published by Rockchip to get upstream to add device-specific workarounds[https://lore.kernel.org/linux-rockchip/CAMdYzYrQ5f-mv_VmTq_CRf9tR=j3mwRpKHNLmPFgCF9whsGFRw@mail.gmail.com/]
* Video Output — only at 1920x1080p60 and nothing else, very buggy and rough around more than just the edges

=== Confirmed Broken ===

* USB 3.0 (applies to Model A only) — only works with very short cables and depends on the device. This is due to a hardware design issue relating to the coupling capacitors needed for SATA, which shares the same lines as USB 3.0.
** Hardware design changes have been suggested to engineers, it's in their hands now.
* RGA — only works with memory ≤ 4 GiB, because Rockchip didn't make the address registers larger. Oopsie.

=== Needs Testing ===

* E-Paper
* Microphone Input
* CSI — needs CIF driver
* eDP — needs PHY driver and controller driver
* DSI

== TODO ==

=== ebc-dev Reverse Engineering and Development ===

The [https://gitlab.com/pine64-org/quartz-bsp/linux-next/-/tree/rk356x-ebc-dev driver for the eInk panel] needs to both be reverse engineered and then rewritten as C. In its current form, it is mostly an assembly dump produced by gcc with debug symbols. See [[RK3566 EBC Reverse-Engineering]] for details.

=== Investigate MCU ===

The RK3566 comes with an integrated RISC-V microcontroller (MCU). It communicates with the A55 host through the Mailbox system driven by the rockchip-mailbox driver. Since this MCU would be quite useful for things such as low power standby mode, investigating how it can be turned on and have firmware flashed to it should greatly enhance the power saving features of the PineNote.

=== Mainline U-Boot Work ===

We currently use the "downstream" Rockchip U-Boot, which is based on an old version of U-Boot and contains vendor specific patches that have not undergone the same level of code review as they'd have done had they been submitted upstream.

While the lack of ATF sources means that using mainline U-Boot would still require the use of Rockchip provided binaries for the firmware, even with Rockchip blobs, a more modern version of U-Boot will be much nicer to use.

Mainline U-Boot contains good enough support for the RK3566 SoC used on the Quartz64 as of v2023.07, patches are still in review for e.g. PCIe/NVMe/AHCI support.

Patches for adding Quartz64 and SOQuartz have been submitted and are now [https://patchwork.ozlabs.org/project/uboot/list/?series=365266&state=* in review]

==== Things that could be done ====

This list is non-exhaustive as we don't exactly know how much is missing

* Port the DesignWare Ethernet QoS rockchip driver to u-boot for networking
* Port the Motorcomm PHY driver to u-boot for networking
** Only needed for Model A, RTL8211 on Model B is already supported in mainline u-boot
* Port a basic VOP2 driver to get a framebuffer from u-boot

==== List of Useful Resources for this Task ====
* Downstream Rockchip U-Boot repository with Quartz64 specific patches: https://gitlab.com/pgwipeout/u-boot-rockchip/-/tree/quartz64
* Mainline Rockchip custodian U-Boot repository: https://source.denx.de/u-boot/custodians/u-boot-rockchip
* U-Boot Mailing List: https://lists.denx.de/listinfo/u-boot

=== eDP Driver Porting ===

The eDP PHY driver and controller driver needs to be ported, brought into shape and submitted with proper commit attribution to the Rockchip authors.

[[User:CounterPillow]] has experimentally ported stuff, but it's currently not working.

== Linux Kernel Config Options ==

* <code>CONFIG_SND_SOC_ROCKCHIP_I2S_TDM</code>
** for Analog and HDMI audio
* <code>CONFIG_SND_SOC_RK817</code>
** for Analog audio on the Model A
* <code>CONFIG_STMMAC_ETH</code>
** Ethernet
* <code>CONFIG_DWMAC_ROCKCHIP</code>
** Ethernet
* <code>CONFIG_MOTORCOMM_PHY</code>
** Ethernet PHY for Model A, set this one to Y, m won't work out of the box if the generic PHY driver is y and binds first. Alternatively tell users in board-specific setup instructions to force including the <code>motorcomm</code> module in initramfs if you set it to m.
* <code>CONFIG_REALTEK_PHY</code>
** Ethernet PHY for Model B
* <code>CONFIG_MMC_DW</code>
** MMC/SD
* <code>CONFIG_MMC_DW_ROCKCHIP</code>
** MMC/SD
* <code>CONFIG_MMC_SDHCI_OF_DWCMSHC</code>
** MMC/SD
* <code>CONFIG_PCIE_ROCKCHIP_DW_HOST</code>
** PCIe
* <code>CONFIG_PHY_ROCKCHIP_NANENG_COMBO_PHY</code>
** PHY for PCIe/SATA/USB3
* <code>CONFIG_DRM_PANFROST</code>
** GPU
* <code>CONFIG_SND_SOC_ROCKCHIP_SPDIF</code>
** SPDIF audio
* <code>CONFIG_ROCKCHIP_DW_HDMI</code>
** HDMI PHY
* <code>CONFIG_PHY_ROCKCHIP_INNO_DSIDPHY</code>
** MIPI DSI DPHY
* <code>CONFIG_ROCKCHIP_VOP2</code>
** Video output
* <code>CONFIG_ARCH_ROCKCHIP</code>
** General SoC support
* <code>CONFIG_ROCKCHIP_PHY</code>
** General SoC support
* <code>CONFIG_PHY_ROCKCHIP_INNO_USB2</code>
** USB 2
* <code>CONFIG_RTC_DRV_RK808</code>
** Real-time Clock
* <code>CONFIG_COMMON_CLK_RK808</code>
** Real-time Clock
* <code>CONFIG_MFD_RK808</code>
** Various things relating to the RK817 chip
* <code>CONFIG_CHARGER_RK817</code>
** RK817 charger
* <code>CONFIG_REGULATOR_RK808</code>
** Voltage regulators
* <code>CONFIG_ROCKCHIP_PM_DOMAINS</code>
** Power management domains
* <code>CONFIG_GPIO_ROCKCHIP</code>
** GPIO support
* <code>CONFIG_PINCTRL_ROCKCHIP</code>
** GPIO and general SoC support
* <code>CONFIG_PWM_ROCKCHIP</code>
** PWM support
* <code>CONFIG_ROCKCHIP_IOMMU</code>
** IOMMU support
* <code>CONFIG_ROCKCHIP_MBOX</code>
** Mailbox support (for communication with MCU)
* <code>CONFIG_ROCKCHIP_SARADC</code>
** Analog-to-digital conversion support, for e.g. microphones
* <code>CONFIG_ROCKCHIP_THERMAL</code>
** Temperature sensor and thermal throttling support
* <code>CONFIG_SPI_ROCKCHIP</code>
** SPI support
* <code>CONFIG_VIDEO_HANTRO_ROCKCHIP</code>
** Hardware video decoder support
* <code>CONFIG_ROCKCHIP_IODOMAIN</code>
** General SoC support so your I/O pins have the right voltage
* <code>CONFIG_COMMON_CLK_ROCKCHIP</code>
** Common clock support
* <code>CONFIG_PHY_ROCKCHIP_INNO_CSIDPHY</code>
** MIPI CSI DPHY
* <code>CONFIG_I2C_RK3X</code>
** I2C support

== Resources ==
=== Repositories ===

* pgwipeout's kernel tree
** https://gitlab.com/pgwipeout/linux-next/-/tree/quartz64-v5.15-rc1
* BSP based development effort for SPL/U-Boot and Linux
** https://gitlab.com/pine64-org/quartz-bsp
* Image CI pipeline aimed at developers
** https://gitlab.com/pgwipeout/quartz64_ci/
* Rockchip U-Boot
** https://github.com/rockchip-linux/u-boot
* Downstream rockchip-linux kernel tree
** https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux
* Tianocore EDK II port for UEFI on Quartz64
** https://github.com/jaredmcneill/quartz64_uefi
* Mainline U-Boot Port by pgwipeout
** https://gitlab.com/pgwipeout/u-boot-quartz64

=== Other ===

* Rockchip-SoC Patchwork Page
** https://patchwork.kernel.org/project/linux-rockchip/list/
* Rockchip Kernel Mailing List Archive
** https://lore.kernel.org/linux-rockchip/

== Board/SoC Documentation ==
=== Booting ===
==== Boot Order ====
The RK3566 boot ROM will search for a valid ID BLOCK in the following order on the support boot media:

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

... if this fails, the boot ROM will initialize the USB0 port and wait for a connection from the Rockchip
flash/boot tools.

==== Bootloader Flashing ====

As per pgwipeout's [https://gitlab.com/pine64-org/quartz-bsp/u-boot/-/commit/12d102b86813378af08b086f3b9c13ed8010754c commit message]:
* Make a partition named <code>uboot</code> as partition number 1 at 8 MiB to 16 MiB
* <code>dd if=idblock.bin of=/dev/''<mmc/sd>'' seek=64</code>
* <code>dd if=uboot.img of=/dev/''<mmc/sd>''1</code>

==== BSP Image Layout ====

[[Category:Quartz64]][[Category:Rockchip RK3566]]

Quartz64 Development

2023-07-31T10:21:04Z

CounterPillow: /* Linux Kernel Config Options */ Add Panfrost to kernel config options

This page documents the current status of software support for the [[Quartz64]] single-board computer, and provides links to resources to help prospective contributors get started. Information is kept current on a best-effort basis as various patches get accepted into the kernel.

== Overview ==

=== Upstreaming Status ===

{| class="wikitable plainrowheaders" border="1"
! scope="col" | Function
! scope="col" colspan="2" | Status
! scope="col" | Component
! scope="col" | Notes
! scope="col" | Applies To
|-
! scope="row" rowspan="3" | Video Output
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchipdrm/VOP2</code>
|
As of 5.19-rc1[https://git.kernel.org/linus/604be85547ce4d61b89292d2f9a78c721b778c16], Also featured in Phoronix Article[https://www.phoronix.com/scan.php?page=news_item&px=Rockchip-VOP2-Linux-5.19]
|-
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rockchip-edpphy-naneng</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/blob/quartz64/drivers/phy/rockchip/phy-rockchip-naneng-edp.c] and [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/commit/d7ad116fb30d11d110aeb880754cf27f34c45c40#7e8e2ef87e479c54539dc519c0b92d6b31727f8d_671_681] Coordinate any porting with Rockchip first
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>dw-mipi-dsi-rockchip</code>
| As of 6.1[https://git.kernel.org/linus/e18d9b093006d8abd53e1ce13c0d5a8d0fcd5f64]
|
|-
! scope="row" | 3D Acceleration
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:PaleGreen; text-align:center;"|Upstream Mesa
| <code>panfrost</code>
| As of 5.18[https://git.kernel.org/linus/810028668c6d9da25664195d6b906c98a8169f72]
|-
! scope="row" rowspan="3" | Video Decode
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="background:LightYellow; text-align:center;" rowspan="3"|GStreamer only, no ffmpeg[https://patchwork.ffmpeg.org/project/ffmpeg/list/?series=2898]
| <code>hantro</code> using <code>v4l2-requests</code>
| VDPU121 handling 1080p MPEG-2, VP8 and H.264. Mainline as of 5.19[https://git.kernel.org/linus/5f6bfab6da6531238e899fdf29efd6d0185adc3e]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkvdec2</code> using <code>v4l2-requests</code>
| VDPU346 handling 4K H.265, H.264 and VP9
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| <code>rkdjpeg</code> using <code>v4l2-requests</code>
| VDPU720 handling JPEG, [[User:CounterPillow]] is working on this
|-
! scope="row" rowspan="5" | [[Mainline Hardware Encoding|Video Encode]]
| style="background:PaleGreen; text-align:center;"|Linux Mainline
| style="text-align:center; background:LightYellow;"|GStreamer only
| JPEG on VEPU121
| Hantro-based. Mainline as of 6.1[https://git.kernel.org/linus/6f1ae821a6c4aa9d5b8f437b27ec86fb569219fd]
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| VP8 on VEPU121
| Hantro-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.264 on VEPU540
| rkvenc-based
|
|-
| style="background:#F99; text-align:center;"|Needs writing
| style="text-align:center;"|?
| H.265 on VEPU540
| rkvenc-based
|
|-
! scope="row" rowspan="3" | Audio
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-i2s-tdm</code>
| As of 5.16[https://git.kernel.org/linus/43b058698f723e3c2087af7069c0da082a3ecbe1]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-spdif</code>
| As of 5.15[https://git.kernel.org/linus/dac825b6a6bdca41347e25f07354ad94fdc97445]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-codec</code>
| As of 5.14[https://git.kernel.org/linus/0d6a04da9b25b9a7cf2cac5f5079e3296d3bee0f].
| Quartz64 Model A/B
|-
! scope="row" rowspan="3" | Bootloader
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://review.trustedfirmware.org/c/TF-A/trusted-firmware-a/+/16952]
| <code>TF-A</code>
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://patchwork.ozlabs.org/project/uboot/list/?series=365266&state=*]
| <code>U-Boot</code>
| [[Quartz64_Development#Mainline_U-Boot_Work|See below]]
|
|-
| colspan="2" style="background:LightYellow; text-align:center;"|In progress[https://github.com/jaredmcneill/quartz64_uefi]
| <code>Tianocore EDK II</code>
|
|-
! scope="row" rowspan="4" | Device Tree
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model A
| As of 5.16[https://git.kernel.org/linus/b33a22a1e7c4248608e533fc4fa524258b3fae84]
| Quartz64 Model A
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| Quartz64 Model B
| As of 5.19[https://git.kernel.org/linus/c37415f55bdadffe5b4c0e7981e9fc7e8b96beea]
| Quartz64 Model B
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| SOQuartz
| As of 5.19[https://git.kernel.org/linus/c466828fb3ba8cb7f5c3bf28766da9b70bf9745e]
| SOQuartz
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| PineNote
| As of 5.18[https://git.kernel.org/linus/d449121e5e8addcee654250cec298c887ecafb32]
| PineNote
|-
! scope="row" rowspan="2"| Gigabit Ethernet
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3566-gmac</code>
| As of 5.14[https://git.kernel.org/linus/3bb3d6b1c1957e88bfc5e77a4557f7e6ba761fe3]
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>yt8511-phy</code>
| As of 5.14[https://git.kernel.org/linus/48e8c6f1612b3d2dccaea2285231def830cc5b8e]
|-
! scope="row" | IOMMU
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-iommu</code>
| As of 5.14[https://git.kernel.org/linus/c55356c534aa651ccc3053ef2d5d8d810adacf5f]
|-
! scope="row" | GPIO
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>gpio-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/936ee2675eee1faca0dcdfa79165c7990422e0fc]
|-
! scope="row" | pinctrl
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
|
|
|-
! scope="row" | Thermal Regulation
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-thermal</code>
| As of 5.14[https://git.kernel.org/linus/4b14c055a6f644cbeb1156ba24647e92fe51ec69]
|-
! scope="row" | PCIe
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>pcie-dw-rockchip</code>
| As of 5.15[https://git.kernel.org/linus/0e898eb8df4e34c7b129452444eb7cef68a11f43]
|-
! scope="row" | Power Management
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-pm-domains</code>
| As of 5.14[https://git.kernel.org/linus/1782c87b44a0b1a527f01a6a184677c58ccbf9c7]
|-
! scope="row" | Voltage Control
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk3568-pmu-io-voltage-domain</code>
| As of 5.15[https://git.kernel.org/linus/28b05a64e47cbceebb8a5f3f643033148d5c06c3]
|-
! scope="row" | SPI
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>spi-rockchip</code>
| As of 5.14[https://git.kernel.org/linus/d74d99229f4d48f42d674f7a8a1137179efd67ac]. Necessary device tree changes [https://patchwork.kernel.org/project/linux-rockchip/list/?series=586691 in review].
|-
! scope="row" | Battery
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rk817-charger</code>
| As of 6.1[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/power/supply/rk817_charger.c?id=11cb8da0189b417392e2334ae967b0ba1f0d1be8]
| Quartz64 Model A, Pinenote
|-
! scope="row" | Microphone
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-saradc</code>
| As of 5.15[https://git.kernel.org/linus/7786da3b5ae167c17f35e22ba35e06006338c2f6]. Headphone jack mic seems to connect to <code>SARADC_VIN2_HP_HOOK</code>, so I'm pretty sure that the dtsi and driver changes are needed for that mic to work
|-
! scope="row" | USB 2.0
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-usb2phy</code>
| As of 5.17[https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/drivers/phy/rockchip?h=v5.17-rc1&id=42b559727a45d79c811f493515eb9b7e56016421]
|-
! scope="row" | e-Ink
| colspan="2" style="background:LightYellow; text-align:center;"|In review (RFC)[https://lore.kernel.org/linux-rockchip/20220413221916.50995-1-samuel@sholland.org/T/]
| <code>rockchip-ebc</code>
| A DRM driver is available [https://github.com/smaeul/linux/commits/rk35/ebc-drm-v5 here]; also see [[RK3566 EBC Reverse-Engineering]]
|-
! scope="row" | Combo PHY
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>naneng-combphy</code>
| As of 5.18[https://git.kernel.org/linus/7160820d742a16313f7802e33c2956c19548e488]. Still requires DTS changes
|-
! scope="row" | RGA
| colspan="2" style="background:#F99; text-align:center;"|Needs fixing
| <code>rockchip-rga</code>
| [[User:CounterPillow]] experimentally enabled it[https://gist.github.com/CounterPillow/6bea809f15ada7ddd3a3d7a4994fdc4e] in the device tree and ran gstreamer's v4l2convert through it to test, resulting in a completely garbled output.
|-
! scope="row" | Fan Controller
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
| <code>gp7101</code>
| Someone should write a pwm driver for it so we can then use pwm-fan
| SOQuartz Blade
|-
! scope="row" rowspan="2" | CSI Camera
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rkisp</code>
| Downstream: [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/media/platform/rockchip/isp]
|
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>rockchip-inno-csidphy</code>
| As of 6.1[https://git.kernel.org/linus/29c99fb085ad53e6d5504d1f8d32e6673b9b3a2c]
|
|-
! scope="row" | NPU
| colspan="2" style="background:#F99; text-align:center;"|Needs writing
|
| Downstream version is a closed source SDK and [https://github.com/dieselnutjob/kernel-rk3566/tree/linux-4.19.210/drivers/rknpu open source kernel module rknpu]. Major undertaking to reimplement this as Linux does not (yet) appear to have a generic architecture for neural accelerators.
|
|-
! scope="row" | Crypto
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>rk-crypto</code> v2
| Downstream driver [https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux/-/tree/quartz64/drivers/crypto/rockchip] doesn't include a rk3568 compatible either, but the TRM shows that it seemingly matches.
|
|-
! scope="row" | TRNG
| colspan="2" style="background:LightYellow; text-align:center;"|In review[https://patchwork.kernel.org/project/linux-rockchip/list/?series=699813]
| <code>rockchip-rng</code>
|
|
|-
! scope="row" rowspan="2" | Wi-Fi
| colspan="2" style="background:#F99; text-align:center;"|Needs porting
| <code>bes2600</code>
| A downstream driver is available but it makes use of some custom Rockchip interfaces and is designed for older kernels, plans are being made to port it to DKMS.
| PineTab 2
|-
| colspan="2" style="background:PaleGreen; text-align:center;"|Linux Mainline
| <code>brcmfmac</code>
|
| Quartz64 Model B
|}

== Current Status ==

The following sections give an overview over the current status of different parts of the board. Some parts are waiting on a driver to be written or ported, others only need various adjustments.

According to pgwipeout, I/O device performance is within expected ranges now.

=== Working ===

* eMMC
* SDMMC0 (SD cards)
* GMAC (Gigabit Ethernet)
* USB 2.0
* SATA 2
* SATA 3
* UART
** UART 0 (Pi-bus)
** UART 1 (Bluetooth)
** UART 2 (Pi-bus, debug)
* Video Decode
** VP8
** H.264
* Video Encode
** JPEG (it's pretty bad)
* Battery
* GPU
* Audio
** Analog audio works
** SPDIF works
** HDMI works
* SPI — works, user needs to modify device tree to add devices
* I2C — works, user needs to modify device tree to add devices

=== Partially Working ===

* PCI-Express Controller — everything but devices that need cache coherency (e.g. dGPUs) should work
** [[User:CounterPillow]] noticed some weirdness with NVMe devices disconnecting during heavy write operations, likely down due to power draw on one of the rails as the same sustained bandwidth could be achieved with a different PCIe device with no issue.
* SDMMC1 (Wi-Fi) — AP6256 working, BL602 needs some work to make it flash firmware
* [https://developer.arm.com/architectures/system-architectures/system-components/arm-generic-interrupt-controller GIC] — needs errata published by Rockchip to get upstream to add device-specific workarounds[https://lore.kernel.org/linux-rockchip/CAMdYzYrQ5f-mv_VmTq_CRf9tR=j3mwRpKHNLmPFgCF9whsGFRw@mail.gmail.com/]
* Video Output — only at 1920x1080p60 and nothing else, very buggy and rough around more than just the edges

=== Confirmed Broken ===

* USB 3.0 (applies to Model A only) — only works with very short cables and depends on the device. This is due to a hardware design issue relating to the coupling capacitors needed for SATA, which shares the same lines as USB 3.0.
** Hardware design changes have been suggested to engineers, it's in their hands now.
* RGA — only works with memory ≤ 4 GiB, because Rockchip didn't make the address registers larger. Oopsie.

=== Needs Testing ===

* E-Paper
* Microphone Input
* CSI — needs CIF driver
* eDP — needs PHY driver and controller driver
* DSI

== TODO ==

=== ebc-dev Reverse Engineering and Development ===

The [https://gitlab.com/pine64-org/quartz-bsp/linux-next/-/tree/rk356x-ebc-dev driver for the eInk panel] needs to both be reverse engineered and then rewritten as C. In its current form, it is mostly an assembly dump produced by gcc with debug symbols. See [[RK3566 EBC Reverse-Engineering]] for details.

=== Investigate MCU ===

The RK3566 comes with an integrated RISC-V microcontroller (MCU). It communicates with the A55 host through the Mailbox system driven by the rockchip-mailbox driver. Since this MCU would be quite useful for things such as low power standby mode, investigating how it can be turned on and have firmware flashed to it should greatly enhance the power saving features of the PineNote.

=== Mainline U-Boot Work ===

We currently use the "downstream" Rockchip U-Boot, which is based on an old version of U-Boot and contains vendor specific patches that have not undergone the same level of code review as they'd have done had they been submitted upstream.

While the lack of ATF sources means that using mainline U-Boot would still require the use of Rockchip provided binaries for the firmware, even with Rockchip blobs, a more modern version of U-Boot will be much nicer to use.

Mainline U-Boot contains good enough support for the RK3566 SoC used on the Quartz64 as of v2023.07, patches are still in review for e.g. PCIe/NVMe/AHCI support.

Patches for adding Quartz64 and SOQuartz have been submitted and are now [https://patchwork.ozlabs.org/project/uboot/list/?series=365266&state=* in review]

==== Things that could be done ====

This list is non-exhaustive as we don't exactly know how much is missing

* Port the DesignWare Ethernet QoS rockchip driver to u-boot for networking
* Port the Motorcomm PHY driver to u-boot for networking
** Only needed for Model A, RTL8211 on Model B is already supported in mainline u-boot
* Port a basic VOP2 driver to get a framebuffer from u-boot

==== List of Useful Resources for this Task ====
* Downstream Rockchip U-Boot repository with Quartz64 specific patches: https://gitlab.com/pgwipeout/u-boot-rockchip/-/tree/quartz64
* Mainline Rockchip custodian U-Boot repository: https://source.denx.de/u-boot/custodians/u-boot-rockchip
* U-Boot Mailing List: https://lists.denx.de/listinfo/u-boot

=== eDP Driver Porting ===

The eDP PHY driver and controller driver needs to be ported, brought into shape and submitted with proper commit attribution to the Rockchip authors.

[[User:CounterPillow]] has experimentally ported stuff, but it's currently not working.

== Linux Kernel Config Options ==

* <code>CONFIG_SND_SOC_ROCKCHIP_I2S_TDM</code>
** for Analog and HDMI audio
* <code>CONFIG_SND_SOC_RK817</code>
** for Analog audio on the Model A
* <code>CONFIG_STMMAC_ETH</code>
** Ethernet
* <code>CONFIG_DWMAC_ROCKCHIP</code>
** Ethernet
* <code>CONFIG_MOTORCOMM_PHY</code>
** Ethernet PHY for Model A, set this one to Y, m won't work out of the box if the generic PHY driver is y and binds first. Alternatively tell users in board-specific setup instructions to force including the <code>motorcomm</code> module in initramfs if you set it to m.
* <code>CONFIG_REALTEK_PHY</code>
** Ethernet PHY for Model B
* <code>CONFIG_MMC_DW</code>
** MMC/SD
* <code>CONFIG_MMC_DW_ROCKCHIP</code>
** MMC/SD
* <code>CONFIG_MMC_SDHCI_OF_DWCMSHC</code>
** MMC/SD
* <code>CONFIG_PCIE_ROCKCHIP_DW_HOST</code>
** PCIe
* <code>CONFIG_PHY_ROCKCHIP_NANENG_COMBO_PHY</code>
** PHY for PCIe/SATA/USB3
* <code>CONFIG_DRM_PANFROST</code>
** GPU
* <code>CONFIG_SND_SOC_ROCKCHIP_SPDIF</code>
** SPDIF audio
* <code>CONFIG_ROCKCHIP_DW_HDMI</code>
** HDMI PHY
* <code>CONFIG_PHY_ROCKCHIP_INNO_DSIDPHY</code>
** MIPI DSI DPHY
* <code>CONFIG_ROCKCHIP_VOP2</code>
** Video output
* <code>CONFIG_ARCH_ROCKCHIP</code>
** General SoC support
* <code>CONFIG_ROCKCHIP_PHY</code>
** General SoC support
* <code>CONFIG_PHY_ROCKCHIP_INNO_USB2</code>
** USB 2
* <code>CONFIG_RTC_DRV_RK808</code>
** Real-time Clock
* <code>CONFIG_COMMON_CLK_RK808</code>
** Real-time Clock
* <code>CONFIG_MFD_RK808</code>
** Various things relating to the RK817 chip
* <code>CONFIG_CHARGER_RK817</code>
** RK817 charger
* <code>CONFIG_REGULATOR_RK808</code>
** Voltage regulators
* <code>CONFIG_ROCKCHIP_PM_DOMAINS</code>
** Power management domains
* <code>CONFIG_GPIO_ROCKCHIP</code>
** GPIO support
* <code>CONFIG_PINCTRL_ROCKCHIP</code>
** GPIO and general SoC support
* <code>CONFIG_PWM_ROCKCHIP</code>
** PWM support
* <code>CONFIG_ROCKCHIP_IOMMU</code>
** IOMMU support
* <code>CONFIG_ROCKCHIP_MBOX</code>
** Mailbox support (for communication with MCU)
* <code>CONFIG_ROCKCHIP_SARADC</code>
** Analog-to-digital conversion support, for e.g. microphones
* <code>CONFIG_ROCKCHIP_THERMAL</code>
** Temperature sensor and thermal throttling support
* <code>CONFIG_SPI_ROCKCHIP</code>
** SPI support
* <code>CONFIG_VIDEO_HANTRO_ROCKCHIP</code>
** Hardware video decoder support
* <code>CONFIG_ROCKCHIP_IODOMAIN</code>
** General SoC support so your I/O pins have the right voltage
* <code>CONFIG_COMMON_CLK_ROCKCHIP</code>
** Common clock support
* <code>CONFIG_PHY_ROCKCHIP_INNO_CSIDPHY</code>
** MIPI CSI DPHY
* <code>CONFIG_I2C_RK3X</code>
** I2C support
* <code>CONFIG_DRM_PANFROST</code>
** GPU

== Resources ==
=== Repositories ===

* pgwipeout's kernel tree
** https://gitlab.com/pgwipeout/linux-next/-/tree/quartz64-v5.15-rc1
* BSP based development effort for SPL/U-Boot and Linux
** https://gitlab.com/pine64-org/quartz-bsp
* Image CI pipeline aimed at developers
** https://gitlab.com/pgwipeout/quartz64_ci/
* Rockchip U-Boot
** https://github.com/rockchip-linux/u-boot
* Downstream rockchip-linux kernel tree
** https://gitlab.com/pine64-org/quartz-bsp/rockchip-linux
* Tianocore EDK II port for UEFI on Quartz64
** https://github.com/jaredmcneill/quartz64_uefi
* Mainline U-Boot Port by pgwipeout
** https://gitlab.com/pgwipeout/u-boot-quartz64

=== Other ===

* Rockchip-SoC Patchwork Page
** https://patchwork.kernel.org/project/linux-rockchip/list/
* Rockchip Kernel Mailing List Archive
** https://lore.kernel.org/linux-rockchip/

== Board/SoC Documentation ==
=== Booting ===
==== Boot Order ====
The RK3566 boot ROM will search for a valid ID BLOCK in the following order on the support boot media:

* SPI NOR flash
* SPI NAND flash
* eMMC
* SD-Card

... if this fails, the boot ROM will initialize the USB0 port and wait for a connection from the Rockchip
flash/boot tools.

==== Bootloader Flashing ====

As per pgwipeout's [https://gitlab.com/pine64-org/quartz-bsp/u-boot/-/commit/12d102b86813378af08b086f3b9c13ed8010754c commit message]:
* Make a partition named <code>uboot</code> as partition number 1 at 8 MiB to 16 MiB
* <code>dd if=idblock.bin of=/dev/''<mmc/sd>'' seek=64</code>
* <code>dd if=uboot.img of=/dev/''<mmc/sd>''1</code>

==== BSP Image Layout ====

[[Category:Quartz64]][[Category:Rockchip RK3566]]

Quartz64 UEFI with U-Boot

2023-07-28T23:32:54Z

CounterPillow: /* Flashing a Distro Installer */ Add notes about Ubuntu-Server

Quartz64 UEFI with U-Boot

2023-07-28T23:08:11Z

CounterPillow: /* Flashing a Distro Installer */ Add some openSUSE notes

{{note|'''Note:''' This article is a work-in-progress}}

This article is a guide to installing an [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] capable of booting generic aarch64 EFI images on a [[Quartz64]] or [[SOQuartz]] board.

== Prerequisites ==

{{note|'''Note:''' U-Boot on Quartz64 Model A currently doesn't appear to be able to always load things from USB mass storage devices depending on the device, you'll have to get creative with your installer medium.}}

We need two to three storage mediums:

* an SD card or eMMC module for U-Boot (advanced users may use the SPI flash on Model B)
* an SD card, eMMC module, USB thumb drive or NVMe drive for our installed system
* an SD card, eMMC module, USB thumb drive or NVMe drive for the installer

In practice, you can usually combine some of these into one, e.g. if you start your partitions at 16MiB you can have u-boot and your installed system reside on the same storage medium.

A good way to go about things is to put U-Boot on an SD card, and install the system on eMMC or NVMe, and boot the installer from an USB thumb drive.

== Flashing U-Boot ==

The first step is to flash U-Boot to our first device, either an SD card or an eMMC module. U-Boot here is the system's firmware, similar to the BIOS in an x86 PC.

You'll need a Linux, *BSD or macOS computer (any CPU architecture is fine), and a GitHub account to download Kwiboo's u-boot-build pipeline outputs with.

Download the U-Boot build for your specific device from the latest RK356x Actions run of [https://github.com/Kwiboo/u-boot-build/actions Kwiboo's u-boot-build workflow repository]. Make sure you are downloading the correct build for your device, e.g. '''don't''' use <code>rk3566-quartz64-a</code> on a SOQuartz!

Extract the <code>u-boot-rockchip.bin</code> from the zip archive.

Next, insert the microSD card into your microSD reader, or attach the eMMC module to your eMMC to USB adapter and plug it in. Identify which <code>/dev/</code> device node it showed up at, and ideally wipe any filesystems and partitions on the device. From now on, we'll refer to it as <var>/dev/sdX</var>.

To flash U-Boot, write <code>u-boot-rockchip.bin</code> to byte 32768 of <var>/dev/sdX</var>. You can do this with <code>dd</code> as follows:

sudo dd if=u-boot-rockchip.bin of=<var>/dev/sdX</var> bs=32k seek=1 conv=fsync

{{note|'''Note:''' Double-check you have the right device before doing this! You don't want to flash this to one of your computer's actual disks.}}

== Flashing a Distro Installer ==

Assuming you want to boot an installer rather than some image, you'll want to flash a distribution's aarch64 EFI installation ISO to e.g. an USB thumb drive.

Some examples for installers that fit this criteria:

* '''Fedora Server:''' https://fedoraproject.org/server/download/ (Choose ''For ARM® aarch64 systems, DVD ISO'')
* '''Fedora Workstation:''' https://fedoraproject.org/workstation/download/ (Choose ''For ARM® aarch64 systems, Live ISO'')
* '''openSUSE Tumbleweed:''' https://get.opensuse.org/tumbleweed/ (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
** Tested on 2023-07-28 by [[User:CounterPillow]] on a Quartz64 Model B, installer booted from USB3 thumb drive. Installer has about 1 minute of showing a black screen until things appear on HDMI.
** Note: Installer overwrites U-Boot if installing on the U-Boot medium even with offset! Flashing U-Boot again after installation works.
** Note: Some concerning panfrost clk errors in dmesg and KDE Plasma Desktop defaults to X11 for now, not a good user experience
* '''openSUSE MicroOS:''' https://get.opensuse.org/microos/#download (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
* '''Ubuntu Server:''' https://ubuntu.com/download/server/arm (Choose either the latest LTS or the latest non-LTS)

If you're going to use something else, then please make sure the distribution image you're going to use has a not too ancient kernel; check [[Quartz64 Development]] for which kernel versions bring which drivers. Also make sure the distribution's kernel has the right drivers enabled in its kernel configuration.

To prepare the installation medium, simply use your preferred image flashing utility to write the ISO to e.g. a USB thumb drive. You can also use <code>dd</code> for this.

== Performing the Installation ==

Attach your two to three storage mediums (U-Boot medium, installer medium and target drive) and attach power. If everything went well, you should be booted into the distribution's guided installer. If everything did not go well, use a serial adapter like the PINE64 Woodpecker to get serial output from U-Boot at 1500000 bauds.

Complete the installation. If you want to use your U-Boot medium as your target drive here, make sure to manually partition and leave 16MiB or more space at the start of the drive (block 32768), so that U-Boot is not overwritten.

After the installation completes, power off the board, remove the installer medium, and power it back on. You should now be booted into your freshly installed system.

[[Category:Guide]] [[Category:Quartz64]] [[Category:Quartz64 Guides]]

Quartz64 UEFI with U-Boot

2023-07-28T22:42:36Z

CounterPillow: /* Flashing a Distro Installer */ Add which installer I've tested so far and how

{{note|'''Note:''' This article is a work-in-progress}}

This article is a guide to installing an [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] capable of booting generic aarch64 EFI images on a [[Quartz64]] or [[SOQuartz]] board.

== Prerequisites ==

{{note|'''Note:''' U-Boot on Quartz64 Model A currently doesn't appear to be able to always load things from USB mass storage devices depending on the device, you'll have to get creative with your installer medium.}}

We need two to three storage mediums:

* an SD card or eMMC module for U-Boot (advanced users may use the SPI flash on Model B)
* an SD card, eMMC module, USB thumb drive or NVMe drive for our installed system
* an SD card, eMMC module, USB thumb drive or NVMe drive for the installer

In practice, you can usually combine some of these into one, e.g. if you start your partitions at 16MiB you can have u-boot and your installed system reside on the same storage medium.

A good way to go about things is to put U-Boot on an SD card, and install the system on eMMC or NVMe, and boot the installer from an USB thumb drive.

== Flashing U-Boot ==

The first step is to flash U-Boot to our first device, either an SD card or an eMMC module. U-Boot here is the system's firmware, similar to the BIOS in an x86 PC.

You'll need a Linux, *BSD or macOS computer (any CPU architecture is fine), and a GitHub account to download Kwiboo's u-boot-build pipeline outputs with.

Download the U-Boot build for your specific device from the latest RK356x Actions run of [https://github.com/Kwiboo/u-boot-build/actions Kwiboo's u-boot-build workflow repository]. Make sure you are downloading the correct build for your device, e.g. '''don't''' use <code>rk3566-quartz64-a</code> on a SOQuartz!

Extract the <code>u-boot-rockchip.bin</code> from the zip archive.

Next, insert the microSD card into your microSD reader, or attach the eMMC module to your eMMC to USB adapter and plug it in. Identify which <code>/dev/</code> device node it showed up at, and ideally wipe any filesystems and partitions on the device. From now on, we'll refer to it as <var>/dev/sdX</var>.

To flash U-Boot, write <code>u-boot-rockchip.bin</code> to byte 32768 of <var>/dev/sdX</var>. You can do this with <code>dd</code> as follows:

sudo dd if=u-boot-rockchip.bin of=<var>/dev/sdX</var> bs=32k seek=1 conv=fsync

{{note|'''Note:''' Double-check you have the right device before doing this! You don't want to flash this to one of your computer's actual disks.}}

== Flashing a Distro Installer ==

Assuming you want to boot an installer rather than some image, you'll want to flash a distribution's aarch64 EFI installation ISO to e.g. an USB thumb drive.

Some examples for installers that fit this criteria:

* '''Fedora Server:''' https://fedoraproject.org/server/download/ (Choose ''For ARM® aarch64 systems, DVD ISO'')
* '''Fedora Workstation:''' https://fedoraproject.org/workstation/download/ (Choose ''For ARM® aarch64 systems, Live ISO'')
* '''openSUSE Tumbleweed:''' https://get.opensuse.org/tumbleweed/ (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
** Tested on 2023-07-28 by [[User:CounterPillow]] on a Quartz64 Model B, installer booted from USB3 thumb drive. Installer has about 1 minute of showing a black screen until things appear on HDMI.
* '''openSUSE MicroOS:''' https://get.opensuse.org/microos/#download (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
* '''Ubuntu Server:''' https://ubuntu.com/download/server/arm (Choose either the latest LTS or the latest non-LTS)

If you're going to use something else, then please make sure the distribution image you're going to use has a not too ancient kernel; check [[Quartz64 Development]] for which kernel versions bring which drivers. Also make sure the distribution's kernel has the right drivers enabled in its kernel configuration.

To prepare the installation medium, simply use your preferred image flashing utility to write the ISO to e.g. a USB thumb drive. You can also use <code>dd</code> for this.

== Performing the Installation ==

Attach your two to three storage mediums (U-Boot medium, installer medium and target drive) and attach power. If everything went well, you should be booted into the distribution's guided installer. If everything did not go well, use a serial adapter like the PINE64 Woodpecker to get serial output from U-Boot at 1500000 bauds.

Complete the installation. If you want to use your U-Boot medium as your target drive here, make sure to manually partition and leave 16MiB or more space at the start of the drive (block 32768), so that U-Boot is not overwritten.

After the installation completes, power off the board, remove the installer medium, and power it back on. You should now be booted into your freshly installed system.

[[Category:Guide]] [[Category:Quartz64]] [[Category:Quartz64 Guides]]

Quartz64 UEFI with U-Boot

2023-07-28T22:37:43Z

CounterPillow:

{{note|'''Note:''' This article is a work-in-progress}}

This article is a guide to installing an [https://en.wikipedia.org/wiki/Das_U-Boot U-Boot] capable of booting generic aarch64 EFI images on a [[Quartz64]] or [[SOQuartz]] board.

== Prerequisites ==

{{note|'''Note:''' U-Boot on Quartz64 Model A currently doesn't appear to be able to always load things from USB mass storage devices depending on the device, you'll have to get creative with your installer medium.}}

We need two to three storage mediums:

* an SD card or eMMC module for U-Boot (advanced users may use the SPI flash on Model B)
* an SD card, eMMC module, USB thumb drive or NVMe drive for our installed system
* an SD card, eMMC module, USB thumb drive or NVMe drive for the installer

In practice, you can usually combine some of these into one, e.g. if you start your partitions at 16MiB you can have u-boot and your installed system reside on the same storage medium.

A good way to go about things is to put U-Boot on an SD card, and install the system on eMMC or NVMe, and boot the installer from an USB thumb drive.

== Flashing U-Boot ==

The first step is to flash U-Boot to our first device, either an SD card or an eMMC module. U-Boot here is the system's firmware, similar to the BIOS in an x86 PC.

You'll need a Linux, *BSD or macOS computer (any CPU architecture is fine), and a GitHub account to download Kwiboo's u-boot-build pipeline outputs with.

Download the U-Boot build for your specific device from the latest RK356x Actions run of [https://github.com/Kwiboo/u-boot-build/actions Kwiboo's u-boot-build workflow repository]. Make sure you are downloading the correct build for your device, e.g. '''don't''' use <code>rk3566-quartz64-a</code> on a SOQuartz!

Extract the <code>u-boot-rockchip.bin</code> from the zip archive.

Next, insert the microSD card into your microSD reader, or attach the eMMC module to your eMMC to USB adapter and plug it in. Identify which <code>/dev/</code> device node it showed up at, and ideally wipe any filesystems and partitions on the device. From now on, we'll refer to it as <var>/dev/sdX</var>.

To flash U-Boot, write <code>u-boot-rockchip.bin</code> to byte 32768 of <var>/dev/sdX</var>. You can do this with <code>dd</code> as follows:

sudo dd if=u-boot-rockchip.bin of=<var>/dev/sdX</var> bs=32k seek=1 conv=fsync

{{note|'''Note:''' Double-check you have the right device before doing this! You don't want to flash this to one of your computer's actual disks.}}

== Flashing a Distro Installer ==

Assuming you want to boot an installer rather than some image, you'll want to flash a distribution's aarch64 EFI installation ISO to e.g. an USB thumb drive.

Some examples for installers that fit this criteria:

* '''Fedora Server:''' https://fedoraproject.org/server/download/ (Choose ''For ARM® aarch64 systems, DVD ISO'')
* '''Fedora Workstation:''' https://fedoraproject.org/workstation/download/ (Choose ''For ARM® aarch64 systems, Live ISO'')
* '''openSUSE Tumbleweed:''' https://get.opensuse.org/tumbleweed/ (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
* '''openSUSE MicroOS:''' https://get.opensuse.org/microos/#download (Choose ''UEFI Arm 64-bit servers, desktops, laptops and boards (aarch64)'')
* '''Ubuntu Server:''' https://ubuntu.com/download/server/arm (Choose either the latest LTS or the latest non-LTS)

If you're going to use something else, then please make sure the distribution image you're going to use has a not too ancient kernel; check [[Quartz64 Development]] for which kernel versions bring which drivers. Also make sure the distribution's kernel has the right drivers enabled in its kernel configuration.

To prepare the installation medium, simply use your preferred image flashing utility to write the ISO to e.g. a USB thumb drive. You can also use <code>dd</code> for this.

== Performing the Installation ==

Attach your two to three storage mediums (U-Boot medium, installer medium and target drive) and attach power. If everything went well, you should be booted into the distribution's guided installer. If everything did not go well, use a serial adapter like the PINE64 Woodpecker to get serial output from U-Boot at 1500000 bauds.

Complete the installation. If you want to use your U-Boot medium as your target drive here, make sure to manually partition and leave 16MiB or more space at the start of the drive (block 32768), so that U-Boot is not overwritten.

After the installation completes, power off the board, remove the installer medium, and power it back on. You should now be booted into your freshly installed system.

[[Category:Guide]] [[Category:Quartz64]] [[Category:Quartz64 Guides]]