We’ll start with a fresh install of the latest Raspbian OS release. As we’re using a Model B+, any version from 2014-06-20 or later should work:

Raspberry Pi Downloads Page

If you’re new to Raspberry Pi, we strongly suggest working through the first few guides in the Learn Raspberry Pi tutorial series…know how to “burn” an SD image, perform a first-time setup and get the Raspberry Pi connected to a network. Some familiarity with one of the text editors (such as the simple nano or the more daunting vi or emacs) is also recommended.

Install the Raspbian image on a 4GB or larger microSD card. You’ll need to connect a monitor and USB keyboard for basic system configuration, but this is only temporary…we’ll set it up to run “headless” later. For networking, connect either an Ethernet cable or a USB WiFi adapter.

Basic Setup

On first boot, the raspi-config utility will automatically start:

The following selections are required:

• Expand Filesystem
  

The following are optional, but strongly recommended:

• Change User Password (because everybody knows the default).
  
• Under “Internationalization Options,” select “Change Locale,” “Change Timezone” and “Change Keyboard Layout” to suit your location. If your keyboard isn’t producing the expected symbols, this is why.
  
• Change Hostname (under “Advanced Options”). I named mine “curtain” to distinguish it from other Raspberry Pi systems on the network.
• Enable SSH (also under “Advanced Options”). This allows remote login from another system on the network, for performing administration tasks without a display attached.
• You can disable Overscan (Advanced Options) if you like — we’ll reboot a few times during the setup process, and this provides a little extra screen real estate on HDMI monitors.

You do not need to change the Memory Split or Overclock settings. The Pi can handle Fadecandy just fine with the standard configuration.

Tab over to the “Finish” button, press Return and confirm you’d like to reboot the system when prompted. You’ll need to log in manually now, using the password you established above.

Network Setup

Even if your goal is a standalone system (with all the LED animation being generated on the Raspberry Pi, not streamed over a network), it’s still helpful to get networking up at least temporarily, to install packages and updates, or for remote administration.

If using a wired network, just connect an Ethernet cable and you’re done…skip ahead to the next section below. Wireless networks are a little more involved…

For most WiFi networks — those that broadcast their SSID (network name) — you can type startx and (with a USB mouse connected) click the WiFi Config icon on the desktop to configure your network adapter. Super easy.

For WPA2-protected “hidden” WiFi networks — those that don’t broadcast their SSID — you can try the following steps. This is not guaranteed to work…we strongly recommend just using a broadcast network name (with WPA2 password), since hidden networks are not inherently more secure! But you can give it a shot…

First, edit the WPA Supplicant configuration file:

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Use the following, completely replacing the contents of that file:

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
ap_scan=2
eapol_version=1
network={
	ssid="WIFI_NAME_GOES_HERE"
	scan_ssid=1
	mode=0
	proto=WPA2
	auth_alg=OPEN
	pairwise=CCMP
	group=CCMP
	key_mgmt=WPA-PSK
	psk="WIFI_PASSWORD_GOES_HERE"
}

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1
ap_scan=2
eapol_version=1
network={
	ssid="WIFI_NAME_GOES_HERE"
	scan_ssid=1
	mode=0
	proto=WPA2
	auth_alg=OPEN
	pairwise=CCMP
	group=CCMP
	key_mgmt=WPA-PSK
	psk="WIFI_PASSWORD_GOES_HERE"
}

Edit the ssid and psk strings to match your WiFi network name and password.

Make sure those lines in the network section are indented using tabs, not spaces. It seems to be quite picky about formatting.

If using a WiFi adapter based on the popular Realtek 8192CU chipset, disabling WiFi power management seems to help with reliability:

echo "options 8192cu rtw_power_mgnt=0 rtw_enusbss=0" | sudo tee --append /etc/modprobe.d/8192cu.conf

echo "options 8192cu rtw_power_mgnt=0 rtw_enusbss=0" | sudo tee --append /etc/modprobe.d/8192cu.conf

WiFi should then be active on the next boot:

sudo reboot

Log in again, and you should be able to access the outside world now:

ping adafruit.com

Do not proceed until internet access is working. If WiFi refuses to cooperate, make sure every step above has been followed carefully. If you’re trying to use a hidden network and it just won’t play nice, change the router configuration to broadcast the network name.

A Little More Network Setup

The monitor and keyboard are needed for just a moment more…

Installing netatalk enables Zeroconf (aka Bonjour) networking, so the system appears on the network as “curtain.local” (or whatever hostname you configured) instead of a numeric IP address:

sudo apt-get -y install netatalk

As a bonus for Mac users, this also enables AppleTalk sharing, which can make it easier to transfer files to and from the system if needed.

With netatalk installed, you can easily access the Raspberry Pi remotely using an ssh client from another system on the network. For example, using the Terminal application in Mac OS X, one would type:

ssh [email protected]

You should get a password prompt. Once logged in, you can perform all administration duties remotely (including the steps that follow), and the monitor and keyboard are no longer needed on the Raspberry Pi.

As an optional step, you can make sure your Pi is running the most up-to-date packages:

sudo apt-get -y update
sudo apt-get -y upgrade

This can be really time-consuming, and honestly your Pi is fine running the OS as it arrived on the disk image…some folks are just sticklers for detail.

Remember…

We’re not done yet, but something to keep in mind for the end of the day: so as not to lose all this hard work, make sure the Raspberry Pi is always shut down using the proper procedure. Never just pull the plug on a Linux system, they hate that!

sudo shutdown -h now

Wait about 15 seconds and you can then safely disconnect power. Or, if a monitor is attached, wait for the “Will now halt” message.

Logging in remotely every time you want to turn off the curtain can be a bit of a nuisance. We wrote a small utility that handles this task just by pressing a button connected to the Pi’s GPIO header. The software can be installed with:

git clone https://github.com/adafruit/Adafruit-GPIO-Halt
cd Adafruit-GPIO-Halt
make
sudo make install
sudo nano /etc/rc.local

Insert this one line before the final 'exit 0':

/usr/local/bin/gpio-halt &

/usr/local/bin/gpio-halt &

An alternate pin number can optionally be specified before the “&”. The default — GPIO21 — was chosen because this and a GND are the last two pins on the Model B+ GPIO header, making it very simple to add a momentary button using one of these quick-connects. On a “classic” Pi (original Model A or B), GPIO7 is similarly convenient, with an adjacent GND pin at the end of the header…just be sure to use “gpio-halt 7 &” in that case.

Once installed, gpio-halt will be active on the next reboot.

After pressing the button, you’ll still need to wait about 15 seconds before disconnecting power.