skip to Main Content

Tools Needed:

micro SD card
  • A microSD card
    • Either one that you can format or that is already blank and is at least 8 GB in size (example here: more than 32 is overkill), just about any microSD cards will work, Class 10 or Class 4 are the most popular for Pi projects. We’ll install the free software we need in the steps below.
    • or a microSD card purchased with the RaspberryPi NOOBS operating system already installed (example here). Not much of an advantage here – it comes with more than we need and doesn’t save a lot of time.
  • A computer with a slot that can read a microSD card, or (needed for late-model Macs that only have USB-C ports), an external card reader that you can plug into your computer (example here).

Intro:

Prefer video instruction? Use the follow-along YouTube video that covers the steps, below.

Magritte painting with a Raspberry Pi logo instead of an Apple

If you want to set up a Raspberry Pi, but you don’t have a separate keyboard or monitor with ports and cables that plug into the Pi, you’ll want to perform what’s called a “Headless Raspberry Pi” setup. This tutorial outlines the steps needed when using a Mac to configure any Pi with WiFi capabilities (see a Raspberry Pi Models Comparison Table if you’re unsure if your Pi has WiFi). This page written was first written to setup a Pi for follow-along videos for building an iOS-controlled Raspberry Pi robot, but the steps below can be used to set up any Raspberry Pi on a network requiring a single password. See this note if your network requires a UserID and Password.

If you have purchased a microSD card containing NOOBS (New Out Of Box Software) then you can skip to Step 3. NOOBS software contains more than we need for the robotics tutorials, but there’s no harm in using NOOBS, it’ll just contain software we won’t be using in this tutorial, and it’ll take up some more disk space, although not too much to harm our robotics project.

Step 1: Prepare a microSD Card with the Raspbian Operating System

  • Plug the microSD card into the card reader slot on your computer, or if you need to use an external card reader, plug it into the external card reader, then plug the reader into your computer. The card reader (metal-side goes in first. It will only go one way, so if the card isn’t going in, flip it over).
    • If two drive icons show up on your desktop after plugging in your microSD card (likely one will be named RECOVERY), your drive contains an extra partition. You can recover this space and create a single partition by downloading the free SD Card formatter tool at https://www.sdcard.org/ installing and launching this program, then formatting your card. The extra partition doesn’t hurt anything, it just takes up a bit more space and is unnecessary.

Now use the Mac’s Disk Utility program to format the drive to MS-DOS (FAT 32 format).

  • Launch the Mac’s Disk Utility program you can do this by typing Command-Space Bar to launch Spotlight, then typing “Disk Utility” into the search box, and pressing the return key.
  • Click to select your SD card (likely named “BOOT“).
  • Select the Erase button located along the top of the Disk Utility window. A dialog box with “Erase “BOOT”?” will appear.
  • The Name: field should read BOOT, within the Format: field, select “MS-DOS (FAT32)”. Even if this shows grayed out, you’ll need to select it from the pulldown next to Format: to enable the “Erase” button.
  • Press the “Erase” button.
  • Select the “Done” button when the progress box states “Erase process is complete.
  • Quit the Disk Utility prog                                                    ram. The microSD card named “BOOT” should now appear on your desktop.

Step 2: Download and Install the Raspian Operating System (not needed if using a NOOBS card)

Download the .zip file for the Raspbian Lite software.

  • Open a browser and go to https://raspberrypi.org
  • Select “Downloads” from the menu at the top of the page.
  • Select the “Raspbian” icon (you could install NOOBS, but we don’t need all of this software for our Robot project). This will bring you to a page where you can select the Raspbian Operating System and Supporting Software you’d like to install.
  • Select the “Download ZIP” button underneath Raspbian Stretch Lite. This version does not include extra software that we won’t use as part of our Robot project, so selecting Stretch Lite should result in a faster download and install, and take up less room on your SD card.
  • Select a location to install the .zip file (Desktop is a good, easy-to-find choice), then press “Save”. You will NOT need to double-click the .zip file to decompress it. The .zip file will be used directly by the Etcher software, outlined below.

Put the Raspbian .zip file onto your SD card using Etcher Software.

  • Download and Install Etcher by visiting: https://www.balena.io/etcher/
    • Select theDownload for macOSbutton at the bottom of the screen.
    • Select a location to install the .zip file (Desktop is a good, easy-to-find choice), then press “Save”.
    • Once the .dmg file has finished downloading, double-click to launch and run this file. After the .dmg has been installed, you’ll see a dialog box with an arrow pointing to from balenaEtcher to Applications.
    • Drag the balenaEtcher file into the Applications Folder. This will install Etcher in the Mac’s Applications folder.
  • Use Etcher to flash (install) the .zip file onto your SD card:
    • Double click balenaEtcher to run the program. If prompted with a warning that Etcher was downloaded from the Internet, select “Open” to continue to run Etcher.
    • Click the “Select Image” option. A file selection dialog box will appear.
    • Navigate to the location where your .zip file was saved. Select the .zip file and select the “Open” button.
    • If your SD card is plugged in and formatted, and is the only SD card connected to your machine, the middle of the dialog box will show that it has been selected.
      • If the SD card doesn’t show up as selected in the center of the screen, select “Change”, then the check box next to the SD card you’re using for your install (the check box will then turn green), then select the “Continue” button.
    • Select “Flash“. You may need to enter your Mac’s password, then select “OK“. Etcher will show a progress bar for the flash install, then the validation.
    • After “Flash Complete” shows, quit out of Etcher.
    • You won’t need any of the files downloaded for this install (the .zip, the .dmg, and even balenaEtcher, if that installed on your Desktop). You can drag all of these files into the trash
    • Remount the SD card by removing it, then reinserting it into the SD card slot. The name of this card “BOOT” should show on your desktop.

Step 3: Add a blank file named “ssh” to the boot directory on your Pi’s microSD card

The ssh command will allow you to remotely connect to your Pi via a terminal program such as Terminal on the Mac or Putty for Windows, but for security reasons, it’s not setup as part of the base Pi software install. To enable ssh, create a file named “ssh” in your Pi’s boot directory by performing the following:

  • Press Command-Space to launch Spotlight
  • Type Terminal, then press the return key and the Terminal app should launch

  • Copy the line below and paste it into the Terminal program, following the prompt, then press return. This will create a blank ssh file on the Pi,
    touch /Volumes/boot/ssh
    • Side note ONLY for those working on a “campus” – most readers will be using your Pi at home on a personal Wi-Fi network, however, some corporate and campus networks (including my own University) require smart devices to have their MAC address registered for use on the network, and only then allow these approved devices to operate without a userID and password. One challenge you’ll face is finding your Pi’s MAC address before connecting to a network. To do this, you can follow the step-by-step tutorial at: https://gallaugher.com/makersnack-setup-a-raspberry-pi-on-a-campus-network-that-needs-a-mac-address-before-wi-fi-access then return to this page and skip to Step 13, below.

Step 4; Create and configure a wpa_supplicant.conf file in your Pi’s boot directory

  • Copy the line below and paste it into the Terminal program, following the prompt, then press return. This will launch the nano text-editor program by creating a new, blank file named wpa_supplicant.conf in your Pi’s boot directory:
    nano /Volumes/boot/wpa_supplicant.conf
  • Copy the text below and paste into the Terminal program.
    country=US
    ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
    update_config=1

    network={
    ssid="NETWORK-NAME"
    psk="NETWORK-PASSWORD"
    }
  • Using the arrow keys on your keyboard, move the cursor to change the lines as follows:
    • Replace the NETWORK-NAME with the name of your own Wi-Fi network. You must spell your WiFi network exactly (same letter case, space, and punctuation) as it appears in your WiFi menu and in Network Settings in System Preferences. Keep double-quotes around your network’s name.
    • If you are from outside the United States, replace the two letter US country code in the first line with appropriate Alpha-2 two letter code for your country, which you can find in a list of ISO 3166-1 Country Codes
    • Type Control-X to exit nano and when asked, type “Y“, then return to save the new file you’ve just created.
  • Note that you can have more than one “network” block if you regularly switch between networks – just follow the ending curly brace of one network block with another “network={…}” block that includes the ssid, psk, key_mgmt=NONE, or any other necessary configuration text.

Step 5; Quit Terminal and Eject your microSD card

  • Quit out of the Terminal program and return to the Mac Finder.
  • On the Mac you can just right-click on the volume representing the SD card, as it appears on your desktop (it’s likely called boot), then select “Eject ‘boot’“, or you can find it under the “Devices” listing on the left of a Finder window and click the Eject (⏏) icon. Note: If you have a second volume named “Recovery“, and you are given the option to Eject All when ejecting the ‘boot’ volume, you can select “Eject All“.
  • Remove the microSD card from the microSD slot.

Step 6; Insert the microSD card into your Raspberry Pi

  • Slide the card, metal pins first, into the mciroSD card slot on your Raspberry Pi. The card only fits one way, so if it’s not going in, flip the card over.

Step 7; Power your Raspberry Pi

Plug your power source into the Pi’s miroUSB power connector. You should have a cable 5v, 2A power supply plug, or you should be using an appropriate rechargeable power supply (I use a standard cell-phone portable charger like this Jackery Mini 3350mAh for projects where I need mobile power). Your Pi may take as long as 30 seconds to boot.

Step 8: Generate an ssh key for your new Pi

  • If the terminal program isn’t already running, launch it by pressing  Command-Space to launch Spotlight on your Mac, then type Terminal, and press the return key.
  • Copy the line below and paste it into Terminal, then press return. This will allow your Mac to connect to your new Pi. You’ll only perform this step once when setting up a new Pi. You may get warnings or a host-not-found error. You can accept any default values and press enter, and you can ignore any warnings.
    ssh-keygen -R raspberrypi.local

If your Pi hangs during this step, you can stop the ssh-keygen step by pressing Control-C, and you can try again.

Step 9: Log into your Pi using the default UserName and Password

  • The default name for your Pi is “raspberrypi” and the default password is “raspberry”. We’ll change these, soon, but first, log into your Pi by typing the following into the Terminal, then pressing return.
    ssh pi@raspberrypi.local
  • When asked for your password, type
    raspberry
    The password will be hidden as you type it.
    There is a chance you may get a “Connection refused.” message that returns you to your Mac’s prompt. If so, just try the ssh command above, again, and it should work.

Step 10: Change your Pi’s Password

  • From the Terminal type the command below to launch the raspi-config tool:
    sudo raspi-config
  • Use the arrow keys to select the option to “Change User Password” (it may already be selected, as it’s likely the first option), then press return and follow the prompts to enter a new password and type it again to confirm it was entered correctly.
  • When the password change has been confirmed, press return to accept the “OK” option and return to the raspi-config main menu.
  • Be sure to save your password. I recommend using a Password Management tool like 1Password, which can give you secure access to your passwords from any browser as well as within mobile apps and browser plugins.

Step 11: Change your Pi’s hostname, then reboot your Pi

The default hostname for your Pi is “raspberrypi”. You used this to ssh into the pi when using the ssh pi@raspberrypi.local command, above. You can rename your Pi within raspi-config as follows.

  • Within raspi-config, use the arrow keys to select the “Network Options” (likely the second option listed), then press the return key.
  • Use the arrow keys to select “Hostname” (likely the first option that is already selected), then press the return key. You can read the general guidelines on acceptable hostnames, then press the return key to confirm <Ok>. You’ll be prompted to enter a hostname.
  • Use the backspace key to delete the existing “raspberrypi” host name, then type in the new name for your Pi, press return, or move the arrows to select <Ok> and press return to return to the raspi-config main menu.
  • Press the right arrow key twice to select <Finish> from within raspi-config, then press return to select the highlighted <Yes> when asked if you’d like to reboot your Pi.

Step 12: Log into your Pi with your new hostname and password

  • VERY IMPORTANT – when logging in using ssh, be sure to use your new hostname in the place of the word ‘hostname’ in the command below:
    ssh pi@hostname.local
    Pro-tip: Pressing the up arrow key will cycle through prior commands typed into the Terminal, so you can press the up arrow until ssh pi@raspberrypi.local shows up, then backspace over raspberry.local and replace it with your new hostname.local. Pressing the up-arrow key within Terminal will cycle back through the commands you typed at the command prompt this session, starting with the most recent one, first. Once you’ve used up-arrow, you can also down-arrow to cycle back to the most recent commands.
  • Type in your new password, when asked, then press the return key. You should be logged in and you should notice that your command prompt after login shows pi@hostname where hostname is your Pi’s new hostname.
    • NOTE: If you receive a scary warning with @ signs stating something like: “WARNING: POSSIBLE DNS SPOOFING DETECTED!”, this occurs because the IP address being used for your Pi was used for another device. You’ll likely not see this, but if you do, simply try to log in, but this time use sudo before the command above, like this, being sure to replace hostname below with the hostname you gave your Pi:
      sudo ssh pi@hostname.local
    • You’ll likely then be asked for your password – this will be your Mac’s password, so enter your Mac’s password (not the Pi’s) and press return.
    • You may get an additional warning mentioning an ECDSA key fingerprint and asking “Are you sure you want to continue connecting (yes/no)?” type yes and press enter.
    • You’ll then be prompted to enter

      pi@hostname.local’s password:

      Enter the password for your Pi (not your Mac), and  press enter. You should now be properly logged in.

Step 13: Update the Software on your Pi

If asked to confirm whether you want to use a certain amount of disk storage during update and upgrade below, always type Y, then return.

  • From the Terminal, copy & paste the line below, then press return.
    sudo apt-get update -y
  • This will schedule files to be updated when you copy the statement below, then press return (so do that now, as well).
    sudo apt-get upgrade -y

 

And remember to sudo halt when shutting down…

When turning off your Pi (removing the power), type the command below to avoid any potential file corruption during shutoff. 

sudo halt

If you’re following this tutorial to build the iOS-controlled PiBot robot, return to the PiBot project start page to find in this series and links to accompanying step-by-step YouTube videos at: https://bit.ly/iOS-Pi-Robot.

If you’re following this tutorial as part of the iOS-controlled “Make It Talk” project (Talking Yoda), return to the MakeItTalk project start page.

❖    ❖    ❖    ❖    ❖

Ready for more? Check out tutorials on Robotics, Wearables, App Development and more at: http://bit.ly/GallaugherYouTube. Please consider subscribing and do share with others who may be interested!

Want to learn to build apps? The same content I use in my semester-long online course (videos and tutorial content) is available for less than $25 via links you’ll find at https://gallaugher.com/swift.

Look for more updates at gallaugher.com as well as on Twitter @gallaugher

 

 

Back To Top