diff --git a/raspberry-pi.md b/raspberry-pi.md
new file mode 100644
index 0000000..2d725e1
--- /dev/null
+++ b/raspberry-pi.md
@@ -0,0 +1,124 @@
+musikbox runs great on a raspberry pi when properly configured. it can be plugged directly into your home stereo system and controlled remotely, both via ssh and a companion android app called `musikdroid`.
+
+# operating system setup
+musikbox on a raspberry pi requires [raspbian jessie](https://www.raspberrypi.org/downloads/raspbian/).
+
+if you already have a functioning system you can skip ahead to the installation section. these first few steps document how to get a freshly installed pi ready for musikbox.
+
+## reconfigure your keyboard
+by default the raspberry pi comes configured with a GB keyboard layout. depending on where you live, this can cause problems. the first order of business is to reconfigure your keyboard.
+
+- `sudo vi /etc/default/keyboard`
+- set: `XKBLAYOUT="us"` (or other country code, as appropriate)
+- `sudo reboot`
+
+## setup wifi
+let's get wifi up and running by connecting to the access point.
+
+- `sudo vi /etc/wpa_supplicant/wpa_supplicant.conf`
+
+  adjust your `country` as necessary, then add access point info to the bottom of the file. the entire file should look something like this:
+
+  ```
+  country=US
+  ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
+  update_config=1
+
+  network={
+    ssid="ACCESS_POINT_NAME"
+    psk="WIFI_PASSWORD"
+  }
+  ```
+- `sudo reboot` (or you can try playing with ifconfig to bring the interface down, then up; i ended up rebooting)
+
+## update your system
+this will update all software on the system to the latest available versions. 
+
+- `sudo apt-get update`
+- `sudo apt-get dist-upgrade`
+- `sudo reboot` (maybe not necessary)
+
+## automatically mount USB drives
+you can configure the operating system automatically mount USB disk drives to a known location so musikbox can scan them during startup for new music. this is as easy as installing the `usbmount` package and configuring musikbox to index the `/media/` directory on the filesystem.
+
+- `sudo apt-get install usbmount`
+
+# using musikbox
+
+## install musikbox binaries
+- download .deb
+- `sudo dpkg -i ./musikbox.deb` (this will likely fail due to missing packages...)
+- `sudo apt-get install -f` (this will install the missing packages, and finish the installation)
+- `musikbox` (start it up to make sure it works)
+
+## configure music paths
+with musikbox running you can configure paths on your system you want to be automatically scanned for music. if you installed `usbmount` above, you should have musikbox index `/media/usb0` through `/media/usb7`. 
+- **important**: do not add `/media/usb`! usbmount appears to set this up as a symlink to `/media/usb0`; doing so will result in duplicate music in your library.
+
+## run musikbox on startup
+it's useful to have musikbox start whenever the pi boots so it's always running.
+
+- `sudo vim /etc/rc.local`
+- add the following line: `su - pi -c "screen -dmS musikbox musikbox"`
+    
+note that the above will start musikbox in a screen session as the `pi` user. that means you can always shell in and do a `screen -r musikbox` to reattach to it to control playback from a computer.
+
+# troubleshooting / optional configuration
+
+you probably shouldn't do any of this unless you are having problems!
+
+## disable wifi power saving
+
+i had an older raspberry pi that seemed to put the wifi card into powersave mode very frequently, making connecting to the device annoying. if you have this problem you can try to disable power saving mode by adding `wireless-poweroff` to each wifi adapter's configuration.
+
+- `sudo vi /etc/network/interfaces`
+  ```
+  ...
+  allow-hotplug wlan0
+  iface wlan0 inet manual
+    wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
+    wireless-power off
+
+  allow-hotplug wlan1
+  iface wlan1 inet manual
+    wpa-conf /etc/wpa_supplicant/wpa_supplicant.conf
+    wireless-power off
+  ...
+  ```
+
+## make wifi reconnection more aggressive
+
+my old wifi router was pretty unstable, and the Pi wasn't good about reconnecting automatically. you can setup a cron job to test the connection and automatically reconnect every couple minutes.
+
+first, create a script to test the connection and bring the interface down, then back up if there are problems:
+
+- `sudo touch /usr/local/bin/wifi_rebooter.sh`
+- `sudo chmod +x /usr/local/bin/wifirebooter.sh`
+- `sudo vi /usr/local/bin/wifi_rebooter.sh`
+    ```
+    #!/bin/bash
+    # http://alexba.in/blog/2015/01/14/automatically-reconnecting-wifi-on-a-raspberrypi/
+
+    # The IP for the server you wish to ping (8.8.8.8 is a public Google DNS server)
+    SERVER=8.8.8.8
+
+    # Only send two pings, sending output to /dev/null
+    ping -c2 ${SERVER} > /dev/null
+
+    # If the return code from ping ($?) is not 0 (meaning there was an error)
+    if [ $? != 0 ]
+    then
+        # Restart the wireless interface
+        ifdown --force wlan0
+        ifup wlan0
+    fi
+    ```
+
+second, add a cron job to run every minute (or whatever) that invokes the script from above:
+
+- `sudo vi /etc/crontab`
+    ```
+    */1 * * * *     root    /usr/local/bin/wifi_rebooter.sh
+    ```
+
+(note: replace "1" above with the desired interval, in minutes.)
\ No newline at end of file