################################################################################
#
#  Setup Guide for moOde audio player
#
#  Updated: 2024-02-10
#  (C) Tim Curtis 2017 http://moodeaudio.org
#
################################################################################

GENERAL INFORMATION

Access moOde using a Browser and one of the URL's below. After opening moOde
in the Browser use the IOS or Android "Save to Home Screen" option to create a
moOde App on your home screen. There is no need to download anything.
http://moode, http://moode.local or http://IP_ADDRESS

OPERATING ISTRUCTIONS

Instructions for configuring and operating moOde are contained in Quick help
which is located on the "m" menu and at the link below.
https://github.com/moode-player/docs/blob/main/Quickhelp.pdf

MOODE OS IMAGE

For improved security the OS image does not contain a userid, WiFi SSID or
Access Point password, and Secure Shell (SSH) access is disabled.

  1. REQUIRED: The official Raspberry Pi Imager is required to enable SSH,
  create a userid and password and optionally set the host name and WiFi SSID
  and password. If a host name is not set in the Imager then the default
  host name "moode" will be used.

  2. REQUIRED: Userid, password and SSH are required otherwise moOde will not
  function correctly. When enabling SSH, select "Use password authentication"
  which means the password specified for the userid is to be used. 

  3. REQUIRED: An Access Point password is required and is set after first boot
  in the Network Configuration screen. This allows moOde to still be accessable
  if it cannot connect to Ethernet or any configrred WiFi SSID's.

- OS images are listed in the "Media Player OS" category of the Raspberry Pi
  Imager, or if they were downloaded directly from moodeaudio.org they can be
  selected via the "Use custom" category in the Imager.

- Refer to the links below for more information on operating system security
  and how to download and use the Raspberry Pi Imager.
  https://www.raspberrypi.com/software/
  https://www.raspberrypi.com/news/raspberry-pi-bullseye-update-april-2022/

To access the OS command console use SSH. An easy to use WebSSH terminal is
available in the System Config screen.

ACCESS POINT (AP) MODE

To use Access Point (AP) mode which is moOde's private 2.4 GHz WiFi network
refer to the settings below.

- IP address    172.24.1.1
- SSID          Moode
- Password      As set in Network Config screen
- Channel       6

AP mode starts automatically when any of the following are true.

- WiFi SSID is set to "None (activates AP mode)" in Network Config, Router
  mode is Off and there is no active Ethernet connection.

- WiFi SSID is defined in Network Config but no IP address was assigned after
  attempting to connect to the SSID and there is no active Ethernet connection.

- Router mode is On in Network Config and either WiFi SSID is defined but no IP
  address was assigned or SSID is set to "None (activates AP mode)". An active
  Ethernet connection is required for Router mode to function but it does not
  need to be active at the time AP Router mode starts.

FILE SHARING

- SMB File Sharing can be turned on in System Config. SMB (Samba) shares named
  NAS, Playlists, and SDCard are automatically created. Each USB disk will also
  have a Samba share created that is named after its Disk Label.

- NFS File Sharing can be turned on in System Config. Access and options defaults
  are provided but can be manually overridden. Each USB disk will have an NFS
  export created whose path is /media/disk_label.

WIFI ADAPTERS THAT ARE REPORTED TO SUPPORT Access Point (AP) MODE

- Raspberry Pi integrated WiFi adapter
- Comfast CF-912AC dual-band WiFi adapter
- For all other adapters consult the manufacturer

IN-PLACE SOFTWARE UPDATES

- Updates to moOde software are made available periodically and can be downloaded
  and installed by clicking "CHECK for software update" in System Config.
- Click VIEW to see a list of what is contained in the update package.
- Click INSTALL to download and install the update package.

IMAGE WRITING UTILITIES

The official Raspberry Pi Imager can be downloaded via the URL below.
https://www.raspberrypi.org/documentation/installation/installing-images/

PLAYER SETUP AND CONFIGURATON

1. INITIAL SETUP

   a) Insert boot SD card or USB drive
   b) Connect USB or I2S audio device
   c) Connect USB storage devices
   - Ethernet mode
   a) Insert ethernet cable
   b) Power on
   c) http://moode, moode.local or IP_ADDRESS
   - Access Point (AP) mode
   a) Insert WiFi adapter that supports AP mode
   b) Power on
   c) Join network: SSID = Moode, password = Refer to SECURITY section
   d) http://172.24.1.1 or http://moode.local

2. AUDIO DEVICE SETUP

   - USB DEVICE

   a) Menu, Configure, Audio
   b) Set Named I2S device and DT overlay to "None" if needed and then Restart
   c) Menu, Configure, Audio
   d) Set Output device to to the name of the USB audio device
   e) If the audio device supports hardware volume set Volume type to
      Hardware otherwise set it to Software, Fixed or Null
   f) Menu, Power, Restart

   - I2S DEVICE

   a) Menu, Configure, Audio
   b) Set Named I2S device or DT overlay to the correct device or overlay name
   c) Menu, Power, Restart
   d) Menu, Configure, Audio
   e) If the audio device supports hardware volume set Volume type to
      Hardware otherwise set it to Software, Fixed or Null

3. TIME ZONE

   a) Menu, Configure, System
   b) Set the appropriate timezone

4. ADD SOURCE(S) CONTAINING MUSIC FILES

   - USB STORAGE DEVICES

   a) Insert USB storage device
   b) Menu, Update library
   c) Wait for completion (no spinner)

   - BOOT SDCARD STORAGE

   a) Menu, Update library
   b) Wait for completion (no spinner)

   - NAS DEVICE

   a) Menu, Configure, Library
   b) CREATE Music source
   c) After SAVE, return to Playback or Library
   d) Menu, Update library
   e) Wait for completion (no spinner)

   - MUSIC DATABASE UTILITIES

   a) Menu, Configure, Library
   b) Various utilities will be listed in the Music Library section

5. VERIFY AUDIO PLAYBACK

   - Ethernet mode

   a) http://moode, moode.local or IP_ADDRESS
   b) Play one of the radio stations

   - AP mode

   a) http://172.24.1.1 or http://moode.local
   b) Switch to Library Folder view
   c) Navigate to the SDCARD/Stereo Test
   c) Play the "LR Channel And Phase" track

At this point a FULLY OPERATIONAL PLAYER exists.

CUSTOM CONFIGURATIONS

Customize the player by using any of the following procedures.

1. CONFIGURE FOR WIFI CONNECTION

   - Ethernet mode
   a) Leave Ethernet cable connected
   b) Insert WiFi adapter (while Pi running)
   c) http://moode, moode.local or IP_ADDRESS
   d) Menu, Configure, Network
   e) Configure a WiFi connection
   f) Menu, Power, Shutdown
   g) Unplug Ethernet cable
   h) Power on

   - Access Point (AP) mode
   a) Join network SSID = Moode, password = Refer to SECURITY section
   b) http://172.24.1.1 or http://moode.local
   c) Menu, Configure, Network
   d) Configure a WiFi connection
   e) Menu, Power, Restart

2. CHANGE HOST AND RENDERER NAMES

   a) Menu, Configure, System (and Audio)
   b) Click SET after entering an appropriate value in each name field
   c) Restart is required if changing Host name

3. AUTO-CONFIGURE AT BOOT

   a) Copy the file /boot/moodecfg.ini.default from the Pi to a PC or Mac
   b) Rename it to moodecfg.ini
   c) Edit the settings as needed
   d) Insert an SD Card into a reader attached to the PC or Mac
   e) Copy the moodecfg.ini file from the PC or Mac to /boot on the SD Card
   f) Eject the SD Card
   f) Insert the SD Card into the Pi and power up
   g) The Pi will reboot twice to perform the auto-configuration process

AFTER PLAYER SETUP

Follow these instructions for making certain types of changes.

1. Switching from a USB to an I2S audio device
   a) Unplug the USB audio device
   b) Menu, Power, Shutdown
   c) Install the I2S audio device
   d) Power on
   e) Menu, Configure, Audio
   b) Set Named I2S device or DT overlay to the correct device or overlay name
   g) Menu, Power, Restart

2. Switching from an I2S to a USB audio device
   a) Menu, Configure, Audio
   b) Set Named I2S device and DT overlay to "None"
   c) Menu, Power, Shutdown
   d) Remove the I2S audio device
   e) Power on
   f) Menu, Configure, Audio
   g) Set Output device to to the name of the USB audio device
   h) If the audio device supports hardware volume set Volume type to
      Hardware otherwise set it to Software, Fixed or Null
   i) Menu, Power, Restart

3. Switching from WiFi back to Ethernet
   a) Plug in Ethernet cable
   b) Menu, Configure, Network
   c) RESET network configuration to defaults
   d) Menu, Power, Shutdown
   e) Remove WiFi adapter
   f) Power on

COMMAND AND REST API

Commands can be submitted to moOde via SSH or HTTP. If an HTTP command returns
data it is in JSON format following REST guidelines.

REST API COMMANDS

Base URL is http://moode/command/?cmd=

get_currentsong
Returns contents of the file /var/local/www/currentsong.txt.
Turn on the Metadata file option in Audio Config to generate this file.

get_output_format
ALSA output format or 'Not playing' is returned.

get_volume
Returns the Knob volume.

set_volume
Sets the knob volume to value N, up or down N or mute toggle.
Arguments: N | -up N | -dn N | -mute

set_coverview
Turns CoverView screen saver on or off.
Arguments: -on | -off

upd_library
Submits an "Update library" command.

MPD commands
See MPD protocol for list of commands.
https://mpd.readthedocs.io/en/latest/protocol.html

Deprecated REST API (http) commands. The following commands have been replaced
by the equivalent commands above and at some point will not be supported. It is
recommened to update scripts to use the new commands.

- vol.sh
- coverview.php
- libupd-submit.php

SSH COMMANDS

moodeutl
This command can be used for printing logs, status or for manipulating certain
parts of moOde. For a list of options type moodeutl --help

mpc
This command can be used to control MPD. For a list of options type mpc help

vol.sh
This command can be used to get or set MPD volume and update the volume knob.
For a list of options type /var/www/vol.sh --help
To run it type /var/www/vol.sh <options>

libupd-submit.php
This command submits a "Library update".
To run it type /var/www/libupd-submit.php

coverview.php
This command turns the CoverView screen saver on or off.
To run it type /var/www/util/coverview.php -on | -off

################################################################################
#  Post questions regarding this guide to http://moodeaudio.org/forum
################################################################################