This article is also existing in a german translation here. Diesen Artikel gibt es auch in einer deutschen Übersetzung hier.
Future updates will cover further basic functions bluetooth connections, backup/restore of playlist and radio stations and quite some more to get the basics going on this awesome music player app 🙂
There are two ways how to install moOde on a Raspberry Pi which are described here.
MoOde not offer a “ready to use” image like other distributions. Instead it is using an image of the operating system (Raspbian) as basis and then a script for automatic installation.
This is out of legal reasons (which come together with an own image) that would consume a lot of time (see here and here).
For BOTH alternatives you will need:

• PC (Windows/Mac/Linux) with microSD card reader/writer
• Software for writing image to microSD card
• Ethernet cable with connection to internet (cable is needed during installation, when moOde is running you may switch to WIFI)

“Local” alternative uses hardware directly attached to the Pi

• USB keyboard
• Display connected via HDMI cable OR Raspberry Pi 7″ Touch Display

If you are using a keyboard other than english layout you have to find out the correct keys. In this guide I am telling you the right keys for german keyboards.
“Remote” alternative uses a remote terminal session from your PC

• Software for remote terminal session
• Software for finding out the IP address of your Pi OR display connected via HDMI (which will show the IP address)

The remote alternative gives you the possibility to show the progress of the installation script process.
Usually the installation script should work without problems – all you have to do is to wait (see chapter 6 for how long you have to wait on the different Pi models).
Here are some advices for the most common errors:

• Use the right (corresponding) version of Raspian image (operating system)! Further information on step 1.
• Defective/incompatible microSD card. Simply try a different microSD card if installation does not work!
• Insufficient power (especially on power peaks during installation). (If the lightning bold is already being displayed (sometimes) during regular usage I do not recommend to try an installation.) Possible Solutions:
  • During installation unplug everything that is not needed for installation like USB devices others than keyboard (and perhaps even DAC Hat)
  • Try a different power supply (especially when you are using 7″ touch display) with 2500mA or 3000mA on 5V (like the official Pi power supply)
  • Try different cables if you have a power supply that does not have a fixed cable (yes, by far not all USB-cables are designed for power consumption higher than 1000mA or match with any power supply)
• Sometimes a server for downloading the necessary packages cannot be reached, because it is not available or your connection or download request timed out (can happen if your internet connection is overloaded – happens to me at my home every sunday afternoon 🙁 ). In this case you have to reboot the Pi and it will continue where it stopped. (something like “failed to fetch / unable to fetch some archives”
  • Setup an SSH connection according to chapter “3. Remote alternative: establish SSH connection”. Then login SSH and check out process progress as described in chapter “6. Installation & progress status”

0. Preparation
For a clean start I recommend to format/repartition the microSD card with one click.
Often Rasperry Pi images create multiple partitions on the SD card. With this Windows tool it is very easy to do a “factory reset”.
Download the official SD Card Formatter. Current version is 5 on official download page. This one does not work well for me (program window does not show at all or close on insert of microSD card with Linux partition).
Therefore I went back and recommend last version 4 which is for example available here. Hope they will fix this with next version.
Insert the microSD card, select the drive letter (in case of multiple partitions select one of them, doesn’t matter which one) and hit “Format” button (default “Quick Format” setting is enough).
1. Download image writer and image
In case you do not have a tool for writing images to SD cards yet, then get one and install it.
“Etcher” is easiest to use (decompression of image files not needed) and available for Windows, Mac and Linux, get it here.
“Win32 Disk Image Writer” is a smaller alternative for Windows, download here. It has typical windows user interfac, is smaller but requires images to be extracted from download files.
MoOde uses Raspbian Stretch Lite image as operating system.
To make sure that moOde installation works correctly it is IMPORTANT that you are using the version of the operating system which fits the moOde version.
So on moOde homepage at support section currently it tells you in the first line “Raspbian Stretch Lite release 2018-03-13” for moOde version 4.1 .
Also watch out that there are TWO Raspbian Stretch versions available, we want “Lite” version NOT “with desktop” .
Official download page for Raspbian is here but this is only offering the newest version. (Like right at the moment) It can happen that there is a newer version (“2018-04-18”) than the one we want.
In case an older version is needed go here where all older releases like for example 2018-03-13 for moOde 4.1 are available.
2. Write image
After the download we want to write the image file

• (if you are using Win 32 Disk Image Writer extract the .img-file from the download file using e.g. 7-Zip)
• start Etcher or Win32 Disk Image Writer
• select the image file
• select the correct destination drive letter of microSD card
• hit the write button, writing process will start and show you a progress bar
• when writing was successful on Windows 10 you have to ignore and abort the upcoming messages (they are caused by an additional Linux partition that was created on the microSD card. Windows cannot read it so it is showing those anoying messages and recommendation to format again. Hope MS will change this messy behaviour.)
• only “remote alternative”: you HAVE TO create a file called “ssh” in the root directory of the microSD card (where a lot of other files like “config.txt” are being displayed) to ACTIVATE the necessary SSH functionality. This is a security function – reason read here. On Windows easiest way is to create a new text file, name it ssh and IMPORTANT remove the “.txt” file extension (probably you have to disable the hiding of file extensions in Windows).
• (on windows use eject function and) remove the microSD card from the reader and insert it into your Pi

3. ONLY Local alternative: connect your hardware
You just have to connect the USB keyboard, ethernet cable and power cable into your Pi.
When Display (external via HDMI or official 7″ Touch Display) shows

than the Raspian operating system is running and you are ready to directly type in the user name in the next step.
3. ONLY Remote alternative: establish SSH connection
For establishing a SSH connection

• file called “ssh” is needed in root directory, otherwise you CANNOT establish a connection. If you forgot to create the file, power off, remove the microSD card from the Pi, insert it into your PC and create it as described in chapter “2. Write image”.
• plug in the power cable into your Pi and wait for about 30 seconds
• find out the IP address of your Pi in your network
  • “Hardware” solution: if you are connecting a display (either via HDMI or the touch display) after the first boot of Raspian operating (in the next step), a few lines before the last statement there should be a line that starts with “My IP address is…”. Either it is in a format like 192.168.0.23 (thats IP address version 4) or it is something like 2a02:810d:fc0:2650::9 (that IP address version 6). In the second case, only enter the address until the first blank! Usually there are listed multiple of those IP version 6 adresses but you must only enter ONE of them.
  • “Software” solution: run a network scanner program/app which shows you all IP adresses in your network. On Windows download Advanced IP Scanner (Screenshot) here and start it (it offers “run” without installation). On iOS/Android smartphone/tablet use Fing (Screenshot) from Google Play Store or Apple App Store. For Android there is an open source alternative called Port Authority (Screenshot) on F-Droid or Google Play Store. Of course you need the IP address for “Raspberry Pi” device (red markup on the screenshots).
• use an SSH client to connect to your Pi. On windows for example download Putty either as regular installer here or as portable app here. On iOS (iPad, iPhone) Shelly is small and easy to handle. On Android you may use ConnectBot from Google Play Store or F-Droid.
  Install/extract the application and start it. It will only display a small window with tons of setting, but you only have to fill out ONE field “Host Name (or IP address)” with the network address of your Raspberry Pi and hit the “Open” button.
• IMPORTANT: using SSH you don’t have to worry about foreign keyboard layouts in step 4

4. Login & download installation script
WARNING for local alternative: local USB keyboard settings are on english keyboard layout! So if you are using a keyboard layout of a differnt country you have to find out the correct keys! Therefore the following commands are also listed for german keyboard layout (feel free to let me know other layouts and I will add them).
INFO for remote alternative: when using Putty on Windows you may just copy the command from the browser and paste them into putty by using right mouse button.
Login by typing pi as user and raspberry as password (german keyboard layout type raspberrz !)
If Pi is showing

login was successful.
Now enter the following commands. There is NO feedback if the command was done right, the next promp will simply popup. See here how it should look like.
First command is for changing the directory

german keyboard type: cd -home-pi
The following command downloads the script file from moOde Server. WARNING! This means for this step you have to be connected to the internet!
If you are offline there is no error message, the file will be created anyway but will have no content!
INFO: the O is the o letter, it is NOT a 0 (zero)

german keyboard type: sudo wget ßq httpÖ–moodeaudio.org-downloads-mos-mosbuild.sh ßO -home-pi-mosbuild.sh
The following command changes the file attributes of the script file so that the file can be executed in the next step

german keyboard type: sudo chmod `x -home-pi-mosbuild.sh (` is Shift+button to the right of ß)
The following command executes the script.
If you have not been connected to the internet two commands earlier, than simply NOTHING will happen here.
If you had been online the installation wizard will be started.

german keyboard type: sudo .-mosbuild.sh
5. Installation wizard
Now a wizard will help you to do some setup. Here is a screenshot of the full process.

• Write OS build directly to the boot SDCard? -> y (german usb keyboard: z)
• Do you have a backup of your boot SDCard? -> y (german usb keyboard: z)
• Enter Current Date (YYYY-MM-DD) -> enter date (german usb keyboard ß for -)
• Make corrections -> n
• Use a proxy server for Internet access -> n
• Use a WIFI instead of Ethernet? -> n
  Switching to WIFI should be done later when moOde is running.
• Proceed with build -> y (german usb keyboard: z)
• Power off the Pi -> y (german usb keyboard: z)
• Wait for about 10 seconds until the green LED on Pi stops blinking. Then unplug the power cable AND keyboard (its not needed anymore).

6. Installation & progress status
All you have to do now is to wait. The Pi is downloading and compiling, so how long you have to wait is mostly depending on the CPU speed of your Pi.
My results for moOde 4.1: Pi-Zero W 512MB v1.1 takes about 2h 45m, Pi-1B 512MB nearly 4 hours, Pi-2B 1GB v1.1 nearly 1,5 hours, Pi-3B 1GB v1.2 1 hour, Pi-3B+ 1GB v1.3 55 minutes
Building progress is NOT displayed on local display.
Remote Alternative:
So if you are interested in the progress or if you are running into problems it can be followed using a SSH connection (as described in chapter “3. Remote alternative: establish SSH connection”):
In the builder guide of moOde it is explained that a log file is maintained during the build which will let you know that the process is running.
IMPORTANT: this time you have to use a different password for login! User is still pi but password is moodeaudio
For printing each line in real-time enter

If there is an error displayed power off your Pi and power on again. The Pi should be resuming the process by trying the last step again.
SSH connection should only be terminated when automated reboot took place which is announced in the last stated line “** Reboot X” where X is 1 to 9.
If the process is finished successful the moslog will look like this and show “installation time” and “final reboot”.
7. Setup & Configuration
Directly connected Pi Touch Display will show terminal with “moode login:”, not “raspberrypi login:” anymore.
HDMI will show blank black screen, hitting Alt+F2 and then Alt+F1 will show the terminal and login as well.
(e.g. you can shutdown Pi after login via pi/moodeaudio by typing “shutdown now”)
Try to open the moOde userinterface by opening the following URL in your browser

INFO: this address works on windows (i think 7 or newer), Mac OS and iOS, but NOT on Android (SmartPhone and Tablets). Reason is that browsers on android cannot deal with it, so you have to work with the IP address of your Pi in your network.
Run a network scanner program/app which shows you all IP adresses in your network. On Windows download Advanced IP Scanner (Screenshot) here and start it (it offers “run” without installation). On iOS/Android smartphone/tablet use Fing (Screenshot) from Google App Store or Apple App Store. For Android there is an open source alternative called Port Authority (Screenshot) on F-Droid or Google Play Store. Of course you need the IP address for “Raspberry Pi” device (red markup on the screenshots).
The moOde user interface will be displayed.
System menu is accessed on the upper right corner by clicking on moOde logo.
Shutdown and reboot can be both found under “Restart” entry.
Set Timezone and Keyboard layout at “Configure” and “System”
WIFI activation

• choose “Configure” then “Network”, click “Scan” button next to SSID field.
• choose your Wifi network name in the dropdown list and enter your password in “Password” field. Then hit “Apply” button on the top of the page and reboot moOde.
• To check if your WIFI is working correctly go to “Configure” and “Network” again.
• Open system menu again and it will show the additional entry “System info”, it opens a popup window.
• Next to “WLAN0 IP” there should be a number, if it still shows “unassigned” the WIFI setup did not work.
• If WLAN shows an IP address you are safe to shutdown your Pi and remove the ethernet cable and power on.
• In case the user interface looks broken in your browser on first boot without ethernet cable but WIFI then use “Refresh” button in system menu.

Activation of an official 7″ touch display
In the system menu choose “Configure” than “System”. There you have to activate “Local UI display”, “Touch screen”, and “Rotate screen” by 180 degrees. I am also decreasing brightness from 255 to 128. Push the “Set” button after every single setting.
Activation of a DAC board (like HIFIBerry called HATs)
Go to “Configure” and “Audio” and select the exact correct (!) one in the first dropdown box next to “I2S audio device”, hit “Set” button and reboot.
Adding Music from USB drive
Go to “Configure”, “Sources” and hit “Update” button in section “USB and SD Card Sources”. On the bottom line “Updating” will be displayed instead of “Browse” as long as scan takes place.
Selecting music
There are two ways of adding tracks to the playlist.

• “Library” is showing scanned tracks based on meta file information (“tags”). You have to select an album so that tracks are displayed. You may add single tracks through the three dots button on the very right of every track or add the whole album by clicking on the cover art picture.
• “Browse” and “USB” is showing the file/directory view. Klick on folder names for navigation, klick on icons for adding folders and files to playlist.

Adding options

• “Add” is adding tracks to the end of the playlist but continues playing
• “Play” is adding tracks to the end of the playlist and jumps to the first of the added track
• “Clear/Play” first empties the playlist, is then adding the tracks and starts playing the first of the added tracks.

Feedback for corrections and enhancements are welcome
Update 2018-06-28: Minor updates based on review for german translation of this post
Update 2018-06-14: Times for installer on different Pi models, and Shelly SSH app for iOS
Update 2018-06-09: Complete revision, some screenshots, expanded chapter 7
Update 2018-05-07: Building process in chapter 5, complete text review
Update 2018-05-06: Extended description using SSH instead of USB keyboard, Attachments removed