documentation

documentation/index.html

@@ -88,9 +88,9 @@ h2, h3 {
 	<div id="content" class="container">
 		<p class="timestamp">2017-01-14</p>
 		<h1>AudioSphere</h1>
-		<p id="subtitle">An MP3 player for children based on the Raspberry Pi Zero and the JBL On Stage IIIp</p>
+		<p id="subtitle">An easy-to-use music player for children based on the Raspberry Pi Zero and the JBL On Stage IIIp</p>
 
-		<p style="font-weight: 700;">In spring 2016 I finalized the <a href="http://tilman.de/projekte/musikrakete/">Musikrakete</a>, an MP3 player that our boys could use without assistance. This is the second version: Not a rocket anymore, but with many improvements.</p>
+		<p style="font-weight: 700;">In spring 2016 I finalized the <a href="http://tilman.de/projekte/musikrakete/">Musikrakete</a>, an MP3 player that our boys could use without assistance. This is the second version: Not a rocket anymore, but with many improvements. <!-- Music is played by simply placing QR code cards on the window on top. --></p>
 
 		<p class="gallery" style="float:right;">
 			<a href="photos/02.jpg" class="fancybox"><img src="images/audiosphere-02.jpg"
@@ -109,29 +109,29 @@ h2, h3 {
 
 		<h2 id="idea">The Idea</h2>
 		<p>
-		This project started about a year ago, when Anica asked me if buying a <a href="https://de-de.hoerbert.com/">hörbert</a> mp3 player would be a good idea. After all our boys wasted two to three CDs every week, trying to get some music out of the small player in their room. And the CD player in the living room also seemed to reach its end of life pretty soon. Nevertheless, I wasn't too sure about the device. In order to get new files on the SD card of the player, the case had to be opened, the navigation with 11 buttons also seemed a little confusing and a single speaker operated with four batteries also did not seem promising to me.
+		This project started about a year ago, when Anica asked me if buying a <a href="https://de-de.hoerbert.com/">hörbert</a> MP3 player would be a good idea. After all our boys wasted two to three CDs every week, trying to get some music out of the small player in their room. And the player in the living room also seemed to reach its end of life pretty soon due to their enthusiasm. Still I wasn't too sure about the device. In order to get new files on the SD card of the player, the case had to be opened, the navigation with 11 buttons also seemed a little confusing and a single speaker operated with four batteries also did not seem promising to me.
 		</p>
 
 		<p>
-		I had seen a <a href="http://www.die-schembergs.de/index.php?page=qr-music">project description of an mp3 player for small children</a> shortly before: A Raspberry Pi, connected to a webcam and speakers reads QR codes and plays the respective track or playlist. So this was what I suggested and to my surprise it was considered a better solution right away. And I had a project.
+		I had seen a <a href="http://www.die-schembergs.de/index.php?page=qr-music">project description of an MP3 player for small children</a> shortly before: A Raspberry Pi, connected to a webcam and speakers reads QR codes and plays the respective track or playlist. So this was what I suggested and to my surprise it was considered a better solution right away. And I had a project.
 		</p>
 
 		<p>
-		As good as the description seemed to be, I wanted to make some improvements on the original design: The player should detect the QR cards on its own, all components should be put together in a single case and, most important, the mp3 should be delivered directly from our home server. No SD card replacement needed.
+		As good as the description seemed to be, I wanted to make some improvements on the original design: The player should detect the QR cards on its own, all components should be put together in a single case and, most important, the MP3 should be delivered directly from our home server. No SD card replacement needed.
 		</p>
 
 		<p>
-		Since we had an old <a href="https://www.amazon.com/JBL-OnStage-30-Pin-iPhone-Speaker/dp/B0017XMN7C">JBL OnStage IIIp</a> speaker lying around that wasn't used anymore due to its outdated 30 pin iPhone dock connector, I decided to use this as a base. After playing around with <a href="https://www.onshape.com/">Onshape</a>, soldering and programming for three months, I had the <a href="http://tilman.de/projekte/musikrakete/">Musikrakete</a> ready by end of March 2016. It's been a huge success with the boys and has been in heavy use ever since.
+		Since we had an old <a href="https://www.amazon.com/JBL-OnStage-30-Pin-iPhone-Speaker/dp/B0017XMN7C">JBL OnStage IIIp</a> speaker lying around that wasn't used anymore due to its outdated iPhone dock connector, I decided to use this as a base. After playing around with <a href="https://www.onshape.com/">Onshape</a>, soldering and programming for three months, I had the <a href="http://tilman.de/projekte/musikrakete/">Musikrakete</a> ready by end of March 2016. It's been a huge success with the boys and has been in heavy use ever since.
 		</p>
 
 		<p>
-		But there were still some open ends on the technical side and I knew that we might need a second player, once the boys have both a room of their own. So when Anica was searching for a good gift to her best friend's son we decided that an updated version would be a good idea.
+		But there were still some open ends on the technical side and I knew that we might need a second player, once the boys both have a room of their own. So when Anica was searching for a good gift to her best friend's son we decided that an updated version would be a good idea.
 		</p>
 
-		<h2 id="piplayer2">PiPlayer, version 2.0:  AudioSphere</h2>
+		<h2 id="piplayer2">PiPlayer 2.0: AudioSphere</h2>
 
 		<p>
-		The major improvement in handling was switching from a QR card slot to a window on top where the QR cards are placed on. I had seen that especially the smaller one had problems getting the cards into the narrow slot. Unfortunately, this also meant that a rocket shape was not an option anymore. At first I tried to put only a hemisphere on top of the JBL speaker which would make it look like a UFO. But the webcam needed at least 10 cm distance to the card in order have the entire QR code covered. Technically, it would be possible to further reduce the size of the ball but fitting all the components in there is hard enough as it is. Also, I wanted to be able to use the cards from the first player in the new one as well.
+		The major improvement in handling was switching from a QR card slot to a window on top where the QR cards are placed on. I had seen that especially the smaller one had problems getting the cards into the narrow slot. Unfortunately, this also meant that a rocket shape was not an option anymore. At first I tried to put only a hemisphere on top of the JBL speaker which would make it look like a UFO. But the webcam needed at least 10&nbsp;cm distance to the card in order have the entire QR code covered. Technically, it would be possible to further reduce the size of the ball but fitting all the components in there is hard enough as it is. Also, I wanted to be able to use the cards from the first player in the new one as well.
 		</p>
 
 		<p>
@@ -139,7 +139,7 @@ h2, h3 {
 		</p>
 
 		<p>
-		On the software side there's two major improvements: The SD card is now mounted read-only by default. This makes unplugging the AudioSphere (by accident or for reboot) unproblematic. And the Python script that operates the player now uses interrupts instead of polling for checking the input sources - no more busy waiting! This removes unnecessary overhead from the CPU and also reduces power-consumption.
+		On the software side there's two major improvements: The SD card is now mounted read-only by default. This makes unplugging the AudioSphere (by accident or for reboot) unproblematic. And the Python script that operates the player now uses interrupts instead of polling for checking the input sources - no more busy waiting!
 		</p>
 
 		<p>
@@ -149,7 +149,7 @@ h2, h3 {
 		<h2 id="case">3D Printed Case</h2>
 
 		<p>
-		First step was the design of the new case. Like the first <a href="https://cad.onshape.com/documents/56f3cf83e4b02f6312a93771/w/785ccf8684baed006305bb0d/e/c68592f13fbf9a2c69b8dd05">rocket case</a> it's public, you can find it <a href="https://cad.onshape.com/documents/584e7d080f617710a60fc5d3/w/28f44a0afe402320fa3f3faa/e/765c3d5ab7a1032836866ac8">here on Onshape</a>. (You will need to create an account to open the document.) Or you can <a href="misc/audiosphere-stl.zip">directly download the STL files for printing if you are using the very same components</a>. (Please note that you will need to rotate the top of the sphere 180° for printing.)
+		First step was the design of the new case. Like the first <a href="https://cad.onshape.com/documents/56f3cf83e4b02f6312a93771/w/785ccf8684baed006305bb0d/e/c68592f13fbf9a2c69b8dd05">rocket case</a> it's public, you can find it <a href="https://cad.onshape.com/documents/584e7d080f617710a60fc5d3/w/28f44a0afe402320fa3f3faa/e/765c3d5ab7a1032836866ac8">here on Onshape</a>. (You will need to create an account to open the document.) Or you can download the <a href="https://github.com/tliero/audiosphere/tree/master/case">STL files</a> for printing if you are using the very same components. (Please note that you will need to rotate the top of the sphere 180° for printing.)
 		</p>
 
 	 <p class="gallery">
@@ -170,7 +170,7 @@ h2, h3 {
 			<li>The sphere case, printed via <a href="https://www.3dhubs.com/">3dhubs.com</a></li>
 			<li>JBL On Stage IIIP (used via ebay for less than 20 €)</li>
 			<li>3 &times; M3 screws with nuts and washers for mounting the case on the speaker</li>
-			<li>Raspberry Pi Zero</li>
+			<li>Raspberry Pi Zero with an SD card</li>
 			<li>Pimoroni PHAT DAC</li>
 			<li>cheap USB Wi-Fi adapter</li>
 			<li>ultra-cheap <a href="images/micro-usb-hub.jpg">Micro USB HUB with ethernet port</a></li>
@@ -188,7 +188,7 @@ h2, h3 {
 					<li>White LED for illumination of the QR cards</li>
 					<li>Infrared LED (904 nm) for remote controlling the speaker</li>
 					<li>Jumper wires</li>
-					<li>0.5 mm copper wire</li>
+					<li>copper wire, circuit board, solder</li>
 				</ul>
 			<li>
 				Tools:
@@ -205,7 +205,7 @@ h2, h3 {
 
 		<h3 id="jblpreparation">Preparing the JBL IIIp Speaker</h3>
 		<p>
-		In order to drill the holes for the screws, the JBL On Stage IIIp has to be disassembled. The procedure is described <a href="https://de.ifixit.com/Guide/JBL+On+Stage+II+Speakers+Replacement/22462">here at ifixit.com for the predecessor</a> which works basically the same way: Remove the rubber pads, then remove all screws from the case. Once the speaker case is opened, the circuit board is unscrewed and removed.
+		In order to drill the holes for the screws, the JBL On Stage IIIp has to be disassembled. The procedure is described <a href="https://de.ifixit.com/Guide/JBL+On+Stage+II+Speakers+Replacement/22462">here at ifixit.com for the predecessor</a> which works basically the same way: Remove the rubber pads, then remove all screws from the case. (Don't forget the center screw in the battery case.) Once the speaker case is opened, the circuit board is unscrewed and removed.
 		</p>
 
 		<p>
@@ -213,7 +213,7 @@ h2, h3 {
 		</p>
 
 		<p>
-		After drilling, washers and screws are added together with the infrared LED that is glued directly in front of the speaker's IR sensor in order to send it commands. The PINs of the IR led are soldered to cables, that are long enough to connect it to the circuit board through one of the additional holes.
+		After drilling, washers and screws are added and the infrared LED is glued directly in front of the speaker's IR sensor in order to send it commands. Before that the PINs of the IR LED are soldered to cables, that are long enough to connect it to the circuit board through one of the additional holes. Also, all the electronics should be tested together before anything is hot-glued into the case.
 		</p>
 
 		<p class="gallery">
@@ -224,25 +224,215 @@ h2, h3 {
 
 		<h3 id="electronics">Electronics</h3>
 		<p>
-		After <a href="http://www.instructables.com/id/Multiroom-Client-With-Raspberry-Pi-ZERO-and-PHAT-D/?ALLSTEPS">soldering the PHAT DAC onto the Raspberri Pi</a>, the used GPIO PINs (9, 10, 11, 17, 22 and 27 together with physical PIN 1 and 9) are connected with jumper cables. (The easiest way is to <a href="https://www.youtube.com/watch?v=MSGIrtGMYRM">solder all PINs at once with a GPIO header</a>.)
+		There are four electronic parts: The reflective optical sensor that triggers the QR recognition process, the LED that illuminates the QR card from within the case, the infrared LED that passes commands to the speaker and the 3 momentary push buttions that are used to pause/unpause playback and move within the current playlist. While the buttons and the LEDs are put directly in the case, all other elements are brought together on a circuit board from where they are connected to the RasPi via jumper cables. (Below is a diagram of the electronics and <a href="https://github.com/tliero/audiosphere/blob/master/misc/electronics-final.fzz">here's the source file</a> for <a href="http://fritzing.org">fritzing</a>.)
 		</p>
 		
 		<p>
-		The electronic components are brought together on a circuit board. There's four different elements: The reflective optical sensor that triggeres the QR recognition process, the LED that illuminates the QR card from within the case, the infrared LED that passes commands to the speaker and the 3 momentary push buttions that are used to pause/unpause playback and move within the current playlist.
+		After <a href="http://www.instructables.com/id/Multiroom-Client-With-Raspberry-Pi-ZERO-and-PHAT-D/?ALLSTEPS">soldering the PHAT DAC onto the Raspberri Pi</a> (preferably using a <a href="images/gpio-header.jpg">GPIO header</a> that directly routes through all the GPIOs), the used PINs are connected with the jumper cables. Where these were not soldered to the contact, I used hot glue to fix the connection which worked pretty well.
-		</p>
-
-		<p>
-		From that circuit board the signals are passed on to the GPIO PINs through jumper cables. Where these jumper cables were not soldered to the contact, I used hot glue to fix the connection which worked pretty well.
 		</p>
 
 		<p class="gallery">
-			<a href="images/audiosphere-electronics.png" class="fancybox" rel="collection03"><img src="images/audiosphere-electronics.png" width="320" alt="The electronics in a single diagram with the optical sensor on the left, the LED, the infrared LED for remote controlling the speaker and the four buttons." /></a>
+			<a href="images/audiosphere-electronics.png" class="fancybox" rel="collection03"><img src="images/audiosphere-electronics.png" width="320" alt="The electronics in a single diagram with the optical sensor on the left, the LED, the infrared LED for remote controlling the speaker and the three buttons." /></a>
 			<a href="images/circuit_board.jpg" class="fancybox" rel="collection03"><img src="images/circuit_board.jpg" width="320" alt="The circuit board after soldering with all resistors and the LED for illumination. Buttons, optical sensor and infrared LED are installed directly in the case." /></a>
 			<a href="images/piplayer-opened.jpg" class="fancybox" rel="collection03"><img src="images/piplayer-opened.jpg" width="320" alt="" /></a>
 		</p>
 
 		<h2 id="software">Software</h2>
+		
 		<h3 id="system">System Installation</h3>
+		<p>
+		Before installing anything additionally, <a href="https://www.raspberrypi.org/downloads/raspbian/">Raspbian Lite</a> has to be <a href="https://www.raspberrypi.org/documentation/installation/installing-images/README.md">installed on the SD card</a>. From there on, it's all on the command line.
+		</p>
+		
+		<p>
+		Basic setup:
+		</p>
+		
+<pre class="pre-scrollable">
+# Make sure that the latest versions are installed
+sudo apt update
+sudo apt upgrade
+
+# Basic setup: password, keyboard layout, wi-fi channels, hostname, ssh
+sudo raspi-config
+
+# Check kernel messages for errors
+dmesg
+
+# Check for connected USB devices
+lsusb
+
+# Install wi-fi client (https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md)
+sudo apt install iw
+
+# Scan networks and add wi-fi network to configuration (https://www.raspberrypi.org/documentation/configuration/wireless/wireless-cli.md)
+sudo iwlist wlan0 scan
+sudo nano /etc/wpa_supplicant/wpa_supplicant.conf
+#	network={
+#		ssid="The_ESSID_from_earlier"
+#		psk="Your_wifi_password"
+#	}
+
+sudo ifdown wlan0
+sudo ifup wlan0
+
+sudo reboot
+
+# disable HDMI (http://www.jeffgeerling.com/blogs/jeff-geerling/raspberry-pi-zero-conserve-energy)
+sudo nano /etc/rc.local
+#	/usr/bin/tvservice -o
+
+# Disable the ACT LED
+sudo nano /boot/config.txt
+#	dtparam=act_led_trigger=none
+#	dtparam=act_led_activelow=off
+
+# Configure NTP
+sudo apt install ntp
+sudo nano /etc/ntp.conf
+# add time server to /etc/ntp.conf
+#	server de.pool.ntp.org
+sudo /etc/init.d/ntp restart
+date
+</pre>
+		
+		<p>
+		Now configure the additional hardware and software that's needed for the player. Before doing that, copy the Python scripts and some MP3 files for testing to <code>/home/pi</code> (either directly or via SCP). Have also one of the QR test cards from the template ready for testing. <b>TODO ADD LINK TO TEMPLATE</b>
+		</p>
+		
+<pre class="pre-scrollable">
+# Install additional software
+sudo apt install lirc zbar-tools mc moc fswebcam python3 python-rpi.gpio python3-rpi.gpio
+
+# Configure PHAT DAC (https://learn.pimoroni.com/tutorial/phat/raspberry-pi-phat-dac-install)
+curl -sS get.pimoroni.com/phatdac | bash
+
+# Check for errors
+dmesg
+
+# Start mocp and test the PHAT DAC
+??????????????? TESTEN
+??????????????? NÖTIG? sudo nano /etc/modprobe.d/alsa-base.conf
+mocp -S
+mocp -l ~/piplayer2/sounds/scanning.mp3
+mocp -p
+mocp -x
+
+# Determine the webcams USB ID and the available resolutions (http://askubuntu.com/questions/214977/how-can-i-find-out-the-supported-webcam-resolutions)
+lsusb
+lsusb -s 001:006 -v | egrep "Width|Height"
+
+# Webcam test: turn on the LED, take a photo and turn the LED off
+# (The focus of the webcam should be adjusted before on another computer with a live picture)
+python3 ~/piplayer2/test/lighton.py
+sudo fswebcam -r 320x240 -d /dev/video0 -v ~/webcam-test.jpg
+python3 ~/piplayer2/test/lightoff.py
+
+# Copy ~/webcam-test.jpg to another computer and have a look at it
+# If needed, adjust the webcam and repeat the procedure until the QR code can be recognized
+
+# QR-Test
+python3 ~/piplayer2/test/lighton.py
+zbarcam --quiet --nodisplay --raw -Sdisable -Sqrcode.enable --prescale=320x240 /dev/video0
+python3 ~/piplayer2/test/lightoff.py
+
+# Enable lirc in /boot/config.txt and add parameters
+sudo nano /boot/config.txt
+#	# Uncomment this to enable the lirc-rpi module
+#	dtoverlay=lirc-rpi,gpio_in_pin=23,gpio_out_pin=22
+
+# add lirc configuration to /etc/lirc/hardware.conf
+sudo nano /etc/lirc/hardware.conf
+#	LIRCD_ARGS="--uinput"
+#	LOAD_MODULES=true
+#	DRIVER="default"
+#	DEVICE="/dev/lirc0"
+#	MODULES="lirc_rpi"
+#	LIRCD_CONF=""
+#	LIRCMD_CONF=""
+
+sudo reboot
+
+# Copy the contents of the JBL remote configuration from ~/misc/lirc_jbl_iiip.conf to /etc/lirc/lircd.conf
+# then restart lircd
+sudo /etc/init.d/lirc restart
+
+# Turn on music, list available commands and test remote control
+mocp -S && mocp -l ~/adele.mp3
+sudo lircd -d /dev/lirc0
+irsend LIST JBLIIIP ""
+## Der Befehl muss 2x schnell hintereinander gesendet werden. Offensichtlich muss die Konfiguration noch verbessert werden.
+irsend SEND_ONCE JBLIIIP KEY_MUTE
+
+# autostart for piplayer with log output redirection
+# (siehe http://raspberrypi.stackexchange.com/questions/8169/run-startup-application-as-a-specific-user)
+sudo nano /etc/rc.local
+#	...
+#	su pi -c 'python3 /home/pi/piplayer2/piplayer2.py >> /home/pi/piplayer2/piplayer2.log 2>&1 &'
+#	exit 0
+
+sudo reboot
+
+# check if running after restart
+ps -ef | grep python
+
+# Tests mit QR-Code-Karten
+tail -f /home/pi/piplayer2/piplayer2.log
+
+
+# SD-Karte read-only nach https://www.heise.de/ct/ausgabe/2016-21-Den-Raspi-als-Bluetooth-Empfaenger-einsetzen-3330683.html
+
+sudo nano /etc/fstab
+#	proc            /proc            proc    defaults                      0       0
+#	/dev/mmcblk0p1  /boot            vfat    defaults,ro                   0       2
+#	/dev/mmcblk0p2  /                ext4    defaults,noatime,ro           0       1
+#	tmpfs           /var/log         tmpfs   nodev,nosuid                  0       0
+#	tmpfs           /var/tmp         tmpfs   nodev,nosuid,mode=1777        0       0
+#	tmpfs           /tmp             tmpfs   nodev,nosuid,mode=1777        0       0
+#	tmpfs           /home/pi/.config tmpfs   nodev,nosuid,mode=1777,uid=pi 0       0
+#	tmpfs           /home/pi/.moc    tmpfs   nodev,nosuid,mode=1777,uid=pi 0       0
+#	# a swapfile is not a swap partition, no line here
+#	#   use  dphys-swapfile swap[on|off]  for that
+
+sudo rm -rf /var/lib/dhcp/ /var/spool /var/lock /etc/resolv.conf
+sudo ln -s /tmp /var/lib/dhcp
+sudo ln -s /tmp /var/spool
+sudo ln -s /tmp /var/lock
+sudo ln -s /tmp/resolv.conf /etc/resolv.conf
+
+sudo nano /etc/rc.local (hier nochmal mit allen Ergänzungen aus den vorherigen Schritten)
+#	...
+#	
+#	# make /tmp on RAM disk writable
+#	chmod 777 /tmp
+#	
+#	# disable hdmi
+#	/usr/bin/tvservice -o
+#	
+#	# start piplayer
+#	su pi -c 'python3 /home/pi/piplayer2/piplayer2.py >> /tmp/piplayer2.log 2>&1 &'
+#	
+#	exit 0
+
+sudo reboot
+
+
+# Dateisystem temporär beschreibbar machen
+sudo mount -o rw,remount /
+sudo mount -o rw,remount /boot
+
+
+# Share einbinden
+sudo nano /etc/rc.local
+#	sudo mount -t cifs -o user=guest,password= //192.168.1.125/media /home/pi/share
+
+# via /etc/fstab HAT NICHT FUNKTIONIERT
+sudo nano /etc/fstab
+#	tmpfs           /media/share     tmpfs   defaults,size=10%             0       0
+#	//192.168.1.125/hidrive/Media /media/share cifs guest,ro
+		</pre>
+		
+		
 		<h3 id="python">Python Script</h3>
 
 		<h2 id="manual">User Manual</h2>