[How to do instruction] Easy installation / setup / configuration guide for absolute beginners

[deztiny]

Moderator note added 2018-11-23: This post contains valuable information for beginners and even for more experienced computerists unfamiliar with the Raspberry Pi ecosystem.

At the time of its writing, it described the only method available to obtain moOde---using the moOde OS Builder to build up moOde from its constituent parts.  Beginning with the release of moOde 4.3 in September, a second method is available---one can directly download a ready-to-use ISO image. See the homepage http://moodeaudio.org

Either method works. Many will choose the second for convenience. Even so, it is worthwhile reading this post with the awareness that some of steps 0-2 and all of steps 3-6 concern only the moOde OS Builder method.

The first method remains available for advanced users and experimenters who have their own reasons for building or who wish simply to understand the build process.
 
end of note
                                                                                                                                                       

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

Code:

raspberrypi login:

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

Code:

pi@raspberrypi:~$

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

Code:

cd /home/pi

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)

Code:

sudo wget -q http://moodeaudio.org/downloads/mos/mosbuild.sh -O /home/pi/mosbuild.sh

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

Code:

sudo chmod +x /home/pi/mosbuild.sh

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.

Code:

sudo ./mosbuild.sh

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
Plug in power cable and 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

Code:

moslog

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

Code:

http://moode.local

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

[Koda59]

Very nice guide, maybe you could add a small sentence if people want to use ssh (no keyboard) and link to the how-to ssh guide below in this section.

[rikardo1979]

Nicely done. Thank you for this
Any chance you upload your screenshots to some picture host service instead of adding it here as attachments?
Also I have edited your post as you used 'Quote' tags instead of 'Code'

[Martin-Andersen]

Thanks great guide, everything works.

I just forgot to add the ssh file in the root before starting the moode installation. Can I get access to the terminal again?
After boot I get a blank screen as you wrote. Can I hold down some keys to stop that behavior?

Thanks

[Tim Curtis]

Hi,

You will have to add the ssh file to the /boot directory, then ssh will be enabled after next reboot.

-Tim

[Martin-Andersen]

Hi,

You will have to add the ssh file to the /boot directory, then ssh will be enabled after next reboot.

-Tim

Thanks I know, but I can't access the terminal.
The screen goes blank/black after reboot, forgot to add the shh file before running the moOde bash file

[Tim Curtis]

Plug the SD Card into your PC or Mac. The /boot directory is a VFAT formatted partition and so will be accessible in File Manager or Finder as "boot".

[deztiny]

Thanks great guide, everything works.

I just forgot to add the ssh file in the root before starting the moode installation. Can I get access to the terminal again?
After boot I get a blank screen as you wrote. Can I hold down some keys to stop that behavior?

Thanks

Thank you for your feedback. I updated the howto for those who forgot the SSH file in the first place.
Regarding the question why HDMI output is black after moOde installation i did a post in support section, see here.
Hope to get some answer from a Linux/Raspbian Pro 

Tim found a workaround using Alt+F2 keys !

[nmstewart]

Ran into a slight hiccup..
After going through the wizard and rebooting I was unable to SSH into my pi. I added the "ssh" file to /boot and /root and rebooted. Still could not SSH to the pi.
logged in directly and ran the "moslog" command and it showed a download failure and said to reboot. I did and had the same results.
I ran "ifconfig" and did not have an IP address for my wireless.

ran "sudo nano /etc/wpa_supplicant/wpa_supplicant.conf" and noticed the "psk" line had truncated at the "$" in my password. Corrected and it worked flawlessly.
was psk="L3"
changed to psk="L3$*****"

Thanks for the excellent guide

[DRONE7]

Yes, reconnect and it will restart by rebooting and then will build MoOde player. The build may take a while depending on model of Pi , network etc....


(I've often wondered why the replug,restart,reboot is not mentioned in the guide ....??)