‘How-To’ Guide

1.0.0 - Introduction

The Raspberry Pi is a very capable Single Board Computer (SBC). This How-To documents the process for installing Ubuntu-MATE on it.

1.0.1 - About This How-To

This How-To will walk you through the process of creating an Ubuntu-MATE installation that will run on a Raspberry Pi 2B, Raspberry Pi 3B, or Raspberry Pi 3B+ while overcoming certain issues and limitations.

Unexpected power loss can result in a corrupted MicroSD card. This How-To also walks you through the process of creating a Rescue System (optional, but recommended) to get your system back up and running should this happen.

Although it will be helpful if you already have a little basic experience with Linux or another Unix variant, it is not necessary. The instructions contained in this How-To have been written in a manner that does not require such knowledge.

These directions are split into sections, each with multiple steps. The entire process they describe will take several hours to complete. You will want/need to take breaks as you go along. The best places to do so are at the end of each section, but there are a few safe stopping places between steps; these are identified as such.

1.0.2 - Ubuntu-MATE Caveats

The stock Ubuntu-MATE distribution for the Raspberry Pi has several issues:

• The Ubuntu-MATE download page specifies a 6 GB or larger card is required. However, the image expands to just over 8 GB, meaning the card capacity must be at least 16 GB!
• Ubuntu-MATE's updater fails because the fat16 partition size, mounted as /boot in Linux, is 64 MB. This is not enough for the updater. Although some manipulation can make it work, the process can take just as long, and should only be undertaken by those with advanced Linux experience.
• Ubuntu-MATE Project Leaders have been experiencing issues creating a downloadable images of Ubuntu-MATE for the Raspberry Pi. The latest working image is for release 16.04, but the current release (as of October, 2018) is 18.04.
• Support for Ubuntu-MATE 16.04 release ends in April, 2019.
• Although Ubuntu-MATE 18.04 can be installed on a Raspberry Pi without an ISO image, the process requires a stable, running Ubuntu-MATE system; in this case, release 16.04. This How-To does exactly that.
• The Raspberry Pi port of Ubuntu-MATE is compiled with the ARMv7 instruction set, not ARMv8. This means that it runs as a 32-bit system instead of 64-bit. Hopefully the project leaders will be able to address this in due course.
• The Raspberry Pi Foundation released the Pi 3B+ in March, 2018. While it can and will run Ubuntu-MATE, the hardware differences between the Pi 3B+ and its predecessors prevent the stock Ubuntu-MATE image from booting. It is unknown at this time if the next functioning image will incorporate the changes required for it to boot on the Pi 3B+. A Raspberry Pi 2B or Pi 3B is required for the preparatory steps.

Top
2.0.0 - Getting Started

The Raspberry Pi is a powerful computer that is also different in some respects when compared to other computers you may be familiar with. Therefore, there are a few topics that should be addressed from the very beginning.

2.1.0 - The Basics

2.1.1 - Things My Raspberry Pi Says...

When the Raspberry Pi is powered up, the first thing it displays is a large color gradient square. Referred to as the Rainbow Square, it quickly goes away once the Pi starts booting from the MicroSD card. If it doesn't go away, the Pi is not able to boot it may be because there is no MicroSD card in the Pi, the card is blank, or the card got clobbered somehow. The on-board LEDs may also flash a in a pattern under these conditions.

The Raspberry Pi can also display one of three icons in the upper right corner of the screen:

• A yellow lightning bolt, indicating that the Pi is not getting enough power.
• A partially red thermometer, indicating a CPU temperature between 80°C and 85°C.
• A fully red thermometer, indicating a CPU temperature above 85°C.

2.1.2 - Things My Raspberry Pi Does...

It is extremely important that you never shut off your Raspberry Pi by simply turning off its power supply! Doing so will likely corrupt the data on all connected storage media.

• In a best case scenario the next boot will take an extremely long time.
• In a worst case scenario the system may not boot at all, requiring a media recovery system.

Always do a proper (orderly) shutdown and wait for the green LED to stop blinking (or another visual indication) that the shutdown completed before unplugging it. This is the golden rule.

If you do not wish to unplug the power supply once your Raspberry Pi has shut down, you have several options at your disposal:

• Purchase a USB-to-MicroUSB cable with an in-line power switch rated for the Raspberry Pi. You will still need to follow the golden rule and do an orderly shutdown first!
• Research and obtain third party add-on hardware that will initiate an orderly shutdown by pressing a button. You will need to research this to ensure the add-on actually does this!

2.1.3 - Storage Media: Care and Feeding

To avoid damaging the MicroUSB card and/or the Raspberry Pi, never insert or remove the card while the Raspberry Pi is getting power.

Always unmount (eject) USB flash drives or other storage media before disconnecting it from the Raspberry Pi, as it is almost certain that the data on the card will end up corrupted.

2.1.4 - How to Access the Linux Command Line

At various points in this How-To, you will need to access the Linux Command Line. If this is your first experience with Linux, you can access it by opening a Terminal window. Its icon looks like a computer screen, and you will find it:

• On the Menu Bar in Raspbian, Raspberry Pi's own Linux distribution.
• Under Applications > System Tools in Ubuntu MATE.

Please note that unlike on Windows computers, the default placement of the menu bar in Linux is at the top of the screen.

2.2.0 - Project Requirements

To complete the steps discussed in this How-To you will need:

• A Raspberry Pi 2B, 3B, or 3B+
  NOTE: A Raspberry Pi 2B or 3B may also be required to install on a Raspberry Pi 3B+
• One Class 10 MicroSD card, 16 GB or larger for your Ubuntu MATE system
• One Class 10 MicroSD card, 8 GB or larger, with the latest release of the Raspberry Pi Operating System installed
  NOTE: If you are starting from scratch, follow the setup directions on the Raspberry Pi web site.
• One USB flash drive with at least 50 MB of free space
• One USB SD (or MicroSD) Card Reader
• One MicroSD-to-SD adapter (if the card reader does not accept MicroSD cards directly
• The Ubuntu-MATE 16.04 ISO image

In addition, you will need the following on a Windows or Mac computer:

• SD Card Formatter, an SD card formatting utility
• Etcher, a disk image flashing (writing) utility

To create a Rescue System, you will also need:

• One MicroSD card with a minimum capacity of 128 MB
• The Slackware Soft Float Installer for your Raspberry Pi model

Top
3.0.0 - Preparations

Although the system will ultimately be running Ubuntu-MATE 18.04, there are a few preliminary steps that must be completed.

3.1.0 - Raspbian MicroSD Card

On your PC, prepare the Raspbian MicroSD card per the instructions on the Raspberry Pi web site. Insert the Raspbian MicroSD card in the Raspberry Pi and boot it. Look for GParted in the Preferences menu. If it wasn't found, open a Terminal window and type sudo apt-get install gparted -y to install it. Then:

1. Connect the USB flash drive.
2. Open the File Manager.
3. Copy the folder /lib/firmware/brcm (Firmware) to a folder on the USB flash drive.
4. Copy the content of /boot (Boot Folder) to a folder on the USB flash drive.
5. Eject the USB flash drive and set it aside.

3.2.0 - Ubuntu-MATE MicroSD Card

Prepare the Ubuntu-MATE MicroSD card on your PC, first by using SD Card Formatter to format the card, and then to write the Ubuntu-MATE ISO image to it with Etcher. Then:

1. Insert the Ubuntu-MATE card in the reader and connect it to the Raspberry Pi.
2. Start GParted.
3. Select the card; typically /dev/sda.
4. Right-click and unmount /dev/sda1 and /dev/sda2.
5. Select the partition called /dev/sda2.
6. Right-click and select Resize/Move.
7. Set Free Space Preceding to 64 MB.
8. Select the partition called /dev/sda1.
9. Right-click and select Resize/Move.
10. Set Free Space Following to 0. This will increase the partition size to 128 MB.
    This document assumes /dev/sda1 will be increased to 128 MB. For a larger partition, change Free Space Preceding in 16 MB increments to the desired size.
11. Verify the fat16 partition flags are boot and lba; set them if not.
12. Click Apply to commit the changes.
    NOTE: If there is a gap between the fat16 and ext4 partitions, select the fat16 partition and repeat repeat steps 9-10 to enlarge the fat16 partition.
13. Shut down and unplug the Raspberry Pi.
14. Remove the Raspbian card and put it away.
15. Move the Ubuntu-MATE card to the PC.
16. Format the fat16 (DOS) partition; Windows will usually prompt to format the partition because it cannot recognize it.
    WARNING! Do not use SD Formatter for this step as it will wipe the whole card!
17. Mount the USB flash drive on the PC.
18. Copy the Boot Folder to the Ubuntu-MATE card.
19. Eject the Ubuntu-MATE card and the USB flash drive.

Top
4.0.0 - Install Ubuntu-MATE

4.1.0 - Install Ubuntu-MATE 16.04

These instructions must be completed on a Raspberry Pi 2B or 3B. Steps 1 - 7 will not work on a Pi 3B+.

1. Start the Raspberry Pi 2 or Pi 3 using the Ubuntu-MATE card.
2. Go through the system setup.
3. In the Ubuntu-MATE Welcome window:
   • Click Raspberry Pi Information and then Resize Now.
   • Reboot when instructed.
4. If necessary, click on the network icon in the menu bar and configure the network connection.
5. Open a Terminal window and type sudo BRANCH=stable rpi-update. Do not reboot when the update finishes, and leave the window open.
6. Mount the USB flash drive.
7. In the Terminal window, type sudo su -.
8. Copy the Firmware from the flash drive to /lib/firmware/brcm.
9. Depending on the type of Raspberry Pi the system will be installed on:
   • Raspberry Pi 2B or 3B:
     » Reboot.
     
   • Raspberry Pi 3B+:
     » Shut down the Raspberry Pi.
     » Move the Ubuntu-MATE card to the Raspberry Pi 3B+
     » Boot the Raspberry Pi 3B+.
     
10. Enable the updated Wireless drivers:
    • Open a Terminal window.
    • Type sudo su -.
    • Type rfkill unblock wifi.
    • Type rfkill list.
    • If a block is returned for the Wireless or Bluetooth connections, repeat the last two commands.
    • Type apt-get --no-install-recommends install network-manager .
11. Reboot to commit the changes.

If you encounter issues with wi-fi after logging in:

1. Open a Terminal window.
2. Type sudo su -.
3. Type nmcli dev wifi list.
4. Type nmtui-connect.

4.2.0 - Upgrade To Ubuntu-MATE 18.04

Now that Ubuntu-MATE is running on the Raspberry Pi, the upgrade itself can begin.

4.2.1 - Bring The System Up To Date

1. Type sudo apt-get autoclean.
2. Type sudo apt-get update.
3. Type sudo apt-get upgrade -y.
4. Type sudo apt-get autoremove -y.

Depending on various factors, step 3 might take an hour or more to complete; it should not be interrupted! This step may also request permission to replace a configuration file, Because this is a fresh installation, it makes no difference how it is answered.

4.2.2 - Upgrade To Ubuntu-MATE 18.04

The upgrade process will take at least one hour to complete. Once started, the process cannot be interrupted without consequence. The upgrade itself will prompt for input on four separate occasions; accept the defaults where applicable.

1. Type do-release-upgrade.
2. Reboot the system to commit the upgrade.

After the system comes back up:

1. System > Preferences > Look and Feel > MATE Tweak
   • Select Panel in the sidebar.
   • Select Traditional to restore the default panel layout. A glitch causes some objects to disappear during the upgrade. If this layout shows as active, change it to another and then back to force the reset.
2. System > Administration > LightDM GTK+ Greeter Settings
   • On the Appearance tab, select a background image or color to fix an invalid lockscreen background condition.
   • On the Window Position tab, re-center the dialog by changing the horizontal value to 50.
3. Open a Terminal window to install the required applications missing from the online upgrade:
   • Type sudo snap install ubuntu-mate-welcome --classic -y
   • Type sudo snap install software-boutique --classic -y
   • Type sudo snap install pulsemixer -y

This completes the upgrade to Ubuntu-MATE 18.04.

Top
5.0.0 - Next Steps

5.1.0 - Install Useful Applications

These applications are installed from a Terminal window using the command line:

• GParted - A disk partition manager; it was used to prepare the Ubuntu-MATE MicroSD card in Section 3.2.0. To install it, type sudo apt-get install gparted -y
• Glances - A text-based system monitoring tool. To install it, type sudo apt-get install glances -y

5.2.0 - Playing A Sound At Login

If you want to hear a sound when logging into your Ubuntu-MATE system:

• System > Preferences > Personal > Startup Applictions
• Click Add and set:
      Name: MATE Login Sound
      Command: paplay /usr/share/sounds/ubuntu/stereo/desktop-login.ogg
      Comment: Play a sound at login
  

You can replace the path/filename with that of a sound file of your own choosing; there should be no trailing space after the filename.

Top
6.0.0 - Creating And Using A Rescue System

In the unlikely event that your Ubuntu-MATE system shuts down unexpectedly, it might no longer boot due to filesystem errors. Ubuntu-MATE does not have a built-in method to recover from this. However, there are several ways to overcome this. For novices, the best way it to create a rescue system.

As an added bonus, because the Rescue System only occupies 100 MB, the MicroSD containing it can have total capacity of 128 MB and up. It is a distinct possibility that you might have one laying around, unused.

6.1.0 - Requirements

• One MicroSD card with a minimum capacity of 128 MB
the system packages are not required
• One USB SD (or MicroSD) Card Reader
• One MicroSD-to-SD adapter (if the card reader does not accept MicroSD cards directly
• The Slackware Soft Float Installer (img.gz) for your Raspberry Pi model;
• SD Card Formatter, an SD card formatting utility
• Etcher, a disk image flashing (writing) utility

6.2.0 - Creating the Rescue System

• Use SD Card Formatter on a PC to format the MicroSD card.
• Use Etcher on a PC to write the Slackware Installer image to the MicroSD card.
• Eject the MicroSD card if Etcher did not do so automatically.
• Shut down the Raspberry Pi and remove the Ubuntu-MATE card
• Insert the Rescue System card in the Raspberry Pi and turn it on.
• Follow the on-screen instructions to select a keyboard map.
• Log in as root and ignore all instructions.
• Type halt to shut down the system.
• Power off the Raspberry Pi and remove the Rescue System card.
• Reinsert the Ubuntu-MATE card and restart the Raspberry Pi.
• Store the Rescue System card in a safe, accessible place.

6.3.0 - Using the Rescue System

If the Raspberry Pi shut down unexpectedly and refuses to boot:

• With the power off, remove the Ubuntu-MATE card and insert the Rescue System card.
• Insert the Ubuntu-MATE card in the USB SD card reader, and connect it to the Raspberry Pi.
• Start the Raspberry Pi.
• Follow the on-screen instructions to log in as root.
• Type df -h to ensure the Ubuntu-MATE card was mounted.
• Type umount /dev/sda1.
• Type umount /dev/sda2.
• Type fsck /dev/sda1 to repair the DOS partition; allow any requested repairs.
• Type fsck /dev/sda2 to repair the Linux partition; allow any requested repairs.
• Type halt to shut down the system.
• Power off the Raspberry Pi and remove the Rescue System card.
• Reinsert the Ubuntu-MATE card and restart the Raspberry Pi.

Top
7.0.0 - Appendices

7.1.0 - Troubleshooting

7.1.1 - Things Do Not Sound Right

There is a possibility that sound will not work after installing Ubuntu-MATE 16.04. This will definitely resolve once the system is brought up to date (Section 4.2.1). The audio subsystem will be recognized as Analog Stereo.

Audio will continue to work after upgrading to Ubuntu-MATE 18.04, but the subsystem will be recognized as Analog Mono. As of October, 2018, a fix has yet to be identified.

7.1.2 - Failure Messages During Boot

Status messages are displayed on the screen as the Linux boot sequence progresses. After upgrading to Ubuntu-MATE 18.04, you will see that one of these status messages reads:

Along with a description of the error, executing systemctl status systemd-modules-load.service in a Terminal window will list the four modules that could not be activated. The first three of these (lp, ppdev, and parport_pc) are used by Linux to print via a Parallel Port, something the Raspberry Pi does not have. The fourth module, bcm2708_rng is for the random number generator. As of October, 2018, a fix has yet to be identified, but the error should not cause any issues.

7.2.0 - Resources

7.2.1 - Additional Reading

Many of the procedures outlined in this How-To are the result of extensive trial and error. Some of the topics it covers are discussed in the following articles:

• Raspberry Pi Forums: Ubuntu-MATE 18.04???
• Raspberry Pi Forums: Ubuntu image for the new Raspberry Pi 3 B+

7.2.2 - Links Mentioned In This How-To

• Raspberry Pi
• Ubuntu-MATE
• Raspberry Pi 2B
• Raspberry Pi 3B
• Raspberry Pi 3B+
• Raspberry Pi Software Download
• Raspberry Pi Setup
• Ubuntu-MATE 16.04 ISO Image Download
• SD Card Formatter Download
• Etcher Download
• Slackware Soft Float Installer Download

Top