Guide: Install on macOS


These are the instructions for installing the development tools on macOS. We peppered the installation instructions with Check steps that confirm your progress through the steps. Use each to validate a step before moving on. If you hit a snag, stop and reach out (forum, office hours) and we can help you out!

Install Xcode

To ease the installation process, we are using Homebrew. Homebrew is a popular package manager for OS X.

If you already use Homebrew, skip to the next section; otherwise follow these steps.

  1. Homebrew requires the Xcode command line tools. Install these by running the command below.
    $ xcode-select --install
    
  2. Install Homebrew by running the command below.
    $ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    

Check: confirm Homebrew installation

$ brew -v
Homebrew 2.7.1

Fine if your version number is newer.

Install arm-none-eabi toolchain

We use a cross-compiler toolchain to compile programs for the Raspberry Pi.

  1. Install our custom brew formula containing the cross-compile tools.
     $ brew install cs107e/cs107e/arm-none-eabi-test
    

Check: confirm compiler

$ brew info arm-none-eabi-test
cs107e/cs107e/arm-none-eabi-test: stable 9-2019q4-cs107e
ARM embedded toolchain MacOS for cs107e
$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (GNU Tools for Arm Embedded Processors 9-2019-q4-major) 9.2.1 20191025 (release) [ARM/arm-9-branch revision 277599]

Install python3 and packages

The rpi-run.py script will be used to send programs from your computer to the Pi. This script requires installation of python3 and two support modules.

Note: macOs have a version of python pre-installed, but it is an older version (version 2) which is nearing end of life. You need python version 3. If you previously have installed python3, skip step 1 below.

  1. Install python3. Python installers are available from https://www.python.org/downloads/mac-osx/. Choose the latest stable Python 3 release and download its macOS 64-bit installer. Open the downloaded pkg file and follow the instructions to install python3.

  2. Install the pyserial and xmodem packages for python3:

     $ python3 -m pip install pyserial xmodem
    

Check: confirm python3 and packages pyserial and xmodem

$ python3 --version
python 3.8.1
$ python3 -m pip show pyserial xmodem 
Name: pyserial
Version: 3.4
...
---
Name: xmodem
Version: 0.4.5
...

Your versions may be slightly newer (higher numbers). That's fine!

Install CP2012 console driver

The console driver enables the bootloader client to communicate with the Pi over the USB-serial device.

Have Big Sur? If you are running macOS Big Sur 10.16 or later, you should have CP2102 support out of the box. Skip over this section and do not install the Silicon Labs driver.

  1. Download the CP2012 driver. The drivers are available on the Silicon Labs CP210x Downloads page. Select the "Downloads" tab and find the link for the "CP210x VCP Mac OSX Driver" and download the zip file. Open the zip to decompress into the dmg file SiLabsUSBDriverDisk.dmg. Open the dmg file to mount the volume named Silicon Labs VCP Driver Install Disk.

  2. On the mounted volume, find the file named Install CP2010x VCP Driver. Open this file to launch the installer. Follow its instructions to install the driver.

  3. If your system raises a "System Extension Blocked" alert, you must take additional action to enable the driver. Open System Preferences and choose the Security & Privacy option. On the General tab, find the message indicating that "Silicon Laboratories Inc" has been blocked and click Allow to unblock it. Restart your computer for this change to take effect.

Check: confirm CP2102 driver is installed and loadable

$ kextfind -B -si silabs -report -b -loadable
CFBundleIdentifier  Loadable
com.silabs.driver.CP210xVCPDriver   yes

After you have installed the development tools, follow the steps below to configure your user environment.

Create cs107e_home directory

  1. Make a new directory named cs107e_home to store course material within your home directory. The tilde character ~ is shorthand for the user's home directory.

     $ mkdir ~/cs107e_home
    
  2. Change to this directory and clone the courseware repository. The courseware repo is used to distribute code and materials for lectures, labs, and assignments.

     $ cd ~/cs107e_home
     $ git clone https://github.com/cs107e/cs107e.github.io
     Cloning into 'cs107e.github.io'...
    

Check: confirm directory contents

$ ls ~/cs107e_home/cs107e.github.io/cs107e/bin
pinout     rpi-run.py

Note: If you're using WSL, now is a good time to open File Explorer on your cs107e_home directory and "Pin to Quick Access" to add it the sidebar for future use. See accessing WSL files from Windows.

Edit shell configuration file

Next, configure your shell environment to match the location of your cs107e_home directory.

When opening a new shell, the environment is initialized by reading a configuration file in your home directory. Editing the configuration file allows you to set the initial state of your shell.

  1. Determine the name of the configuration file for your shell. The name depends on which shell you are using. Use the command echo $SHELL to see your shell. Your shell is likely bash, although it might be zsh if using a more recent macOS.
     $ echo $SHELL
     /bin/bash
    

    If your shell is bash, the configuration file is named .bashrc. If your shell is zsh, the configuration file is named .zshrc. For any other shell, please contact a CA for help.

  2. Find out if you already have an existing configuration file or create it if needed. Change to your home directory and list the files. Filenames starting with a dot are hidden in a directory listing by default. Use the command ls -a to list all files, including hidden ones:
     $ cd ~
     $ ls -a
     .    .bash_history   .bashrc     cs107e_home     .python_history 
     ..   .bash_logout    .config     .profile        .viminfo
    

    (The filenames listed in your directory may be somewhat different, don't worry!) Look through list to see if there is already a configuration file for your shell. If not listed, use touch to create an empty file with the appropriate name:

     $ touch .bashrc
    
  3. Open the configuration file in a text editor and append the following two lines verbatim:
     export CS107E=~/cs107e_home/cs107e.github.io/cs107e
     export PATH=$PATH:$CS107E/bin
    

    The first line sets the environment variable CS107E to the path to where the class files are stored. The second line adds our bin subdirectory to your executable path.

  4. Use the source command to read the updated configuration file into your current shell:
     $ source ~/.bashrc
    

Check: confirm current shell is properly configured

$ echo $CS107E
/Users/student/cs107e_home/cs107e.github.io/cs107e
$ ls $CS107E/lib/libpi.a
/Users/student/cs107e_home/cs107e.github.io/cs107e/lib/libpi.a
$ which pinout
/Users/student/cs107e_home/cs107e.github.io/cs107e/bin/pinout

The configuration file is persistent and should be automatically read when creating a new shell in the future.

Check: confirm shell configuration is persistent and future shells properly configured

Close your current shell and open a new one. Repeat the check step above in the new shell and confirm the new shell is also properly configured.

If you confirm your configuration is persistent, skip Step 5 below. If it is not persistent and you are using bash and macOS Terminal, use the additional customization in Step 5 to add persistence.

  1. (only if needed) Find the file named .bash_profile in your home directory. If no such file exists, use the touch command to create an empty file with that name. Open that file in a text editor and append the following line verbatim:
     source ~/.bashrc
    

Repeat the previous check step with a new shell to confirm your configuration is now persistent.

Configure git identity

We distribute course materials as git repos and you will use git to access, manage, and submit your work.

  1. The commands below will properly set the identity recorded with your git actions. Be sure to replace My Name and myemail@stanford.edu with your own.

     $ git config --global user.name "My Name"
     $ git config --global user.email myemail@stanford.edu
    

Check: confirm your git identity

$ git config --get-regexp user
user.name My Name
user.email myemail@stanford.edu

Installation complete

Use the Final check steps to confirm your entire environment.