0-blink

Setup lab: make sure R/pi hardware and its toolchain works.

This is a relatively trivial lab to make sure your r/pi (model 1 A+) and ARM toolchain works.

• Make sure you start with the prelab.

There's a lot of fiddly little details in getting a pi working, and this lab is many people's first time working with hardware, so we break the lab down into many (perhaps too-many) small steps. Our theorem for this class: the smaller the step, the more obvious what the actual (distal) error is and the less time you have to spend debugging.

If you learn one thing from this class, hopefully it's the counter-intuitive realization that:

• when building systems, smaller the step you take the faster you can run ("epsilon sprinting").

We'll use different variations of a blinky light using GPIO pin 20 (second from bottom on the right):

1. You'll turn on an LED manually;
2. then use a pre-compiled program loaded from the SD card (why not skip 1?);
3. then use a bootloader (why not skip 2?);
4. then install the r/pi tool chain, compile a given assembly version and use it (why not skip 3?);
5. then write your own blink program and compile: this is the fun part. It's also the longest (why not skip 4?).

The final sign off for the lab:

1. Show you have a working blink compiled using the tool chain and started using the bootloader.
2. Bonus: write up a short example problem you ran into (or someone you helped ran into) and how you solved them and post to the newsgroup so we can start accumulating examples.

---

Crucial: Life and death rules for pi hardware.

Always:

1. Whenever you make a hardware change --- messing with wires, pulling the SD card in/out --- make sure pi is disconnected from your laptop. It's too easy to short something and fry your hardware. Also, pulling the SD card out while under power sometimes causes corruption when some bytes have been written out by your laptop and others have not.

2. If anything ever gets hot to the touch --- the serial device, the pi --- DISCONNECT! Sometimes devices have manufacturing errors (welcome to hardware), sometimes you've made a mistake. Any of these can lead to frying the device or, in the worst case, your laptop. So don't assume you have a safety net: its up to you to avert disaster.

3. While the pi has its own unique features, it's also like all other computers you've worked with: if it's not responding, "reboot" and retry by unplugging it (to remove power) and reconnect.

---

0. Make sure you have everything.

You should have:

1. one or more R/PI A+;
2. one or more microSD card and adapter;
3. one or more CP2102 USB-TTL adapter;
4. however many led's you want;
5. some female-female jumpers;
6. printout of the pi's pins.

---

1. Make sure hardware is working:

Before we mess with software, we first make sure the hardware works. When doing something for the first time, you always want to isolate into small pieces.

So as our first step, we will use the USB-TTY to power the pi, and use the pi's power to directly turn on an LED. This tests some basic hardware and that you know how to wire.

Mechanically:

1. Connect the USB-to-TTL Serial cable's power (red) and ground (black) wires to a 5v pin (not the 3v pin) and ground pins on the pi that are next to each other (see your printout; upper right corner).

2. Plug the USB-TTY into your laptop's USB port.

3. Using a red (power) and black(ground) female jumper wires, connect your LED to an unused ground pin and the 3v power pin (there are several) to make sure the hardware components work, and you know how get them to.

   If the LED doesn't go on, reverse its connections. You'll note that one leg of the LED is longer than the other. This is used to indicate which one is for power, which is for ground. You can empirically determine which is which.

   If still doesn't go on, plug someone else's working version into your computer. If that doesn't work, ask.

   (Note: the color of the wire does not matter for electricity, but it makes it much easier to keep track of what goes where.)

4. Try another LED and try some of the other ground and power pins.

(EE folks: We don't use a breadboard b/c it's bulky; we don't use resistors for the same reason + the LED is big enough we generally don't fry it.)

What can go wrong:

1. If your USB-to-TTL starts heating up, disconnnect! It appears that 1 in 8 is defective.
2. If your pi starts heating up, now or ever, disconnect! If you have a short, where a pin with power feeds right into ground, you'll fry it.

---

2. Make sure you're able to install firmware, etc:

You'll run a precompiled program (part1/blink-pin20.bin) on the pi and make sure it can blink pin 20.

Note: in the next assignment when you develop your own remote bootloader (see next step), if your code is broken you'll need to use this SD card method to load a new version, so pay attention to how you do it on your computer.

Mechanically:

1. Unplug the USB-TTY.
2. Plug SD card into your computer and figure out where it's mounted.
3. As discussed in the PRELAB, copy all the files from class firmware directory onto the SD card (cp firmware/* /<sdcard path>/)
4. copy part1/blink-pin20.bin to the SD card as kernel.img.
5. type sync and then eject the SD card (don't just pull it out! data may not be written out.)
6. connect the LED to GPIO20 and ground. Use docs/gpio.png to figure out which this is.
7. Plug the SD card into your pi
8. Plug in the USB-TTY to your USB to power the pi. The pi will jump to whatever code is in kernel.img.

The LED should be blinking. If you get this working, please help anyone else that is stuck so we all kind of stay about the same speed.

Troubleshooting: 0. First try to trouble shooting from part 1.

1. If it's not blinking, swap in someone else's card that is working.
2. If that works, compare their SD card to yours.
3. If that doesn't work, try your card in their rpi.

---

3. Send a new pi program from your computer rather than SD card.

As you've noticed, running new programs on the pi using the SD card method is tedious. This step shows makes it so you can send programs directly from your computer to a plugged-in pi.

Method: install a program (which we somewhat inaccurately call a "bootloader"). This program will wait on the pi for a program sent by your computer, copy it into pi memory, and then jump to it. We currently give you a pre-compiled version (firmware/bootloader.bin).

Mac:

• Download and install the drivers for a CP210x USB-to-UART driver as described in the cs107e docs.
• Make sure you reboot after doing so.

Linux:

• You shouldn't need drivers, however you may need to add yourself to the dialout group (or serial) depending on the distribution.

  sudo adduser <your username> dialout
  

  If that still doesn't work, you may have to remove modemmanager:

  sudo apt-get remove modemmanager
  

Mechanically:

0. Unplug your pi. Don't modify your current wiring.
1. Copy firmware/bootloader.bin on your SD card as kernel.img (see a pattern?).
2. Hook the TX and RX wires up to the pi. Do you TX/TX and RX/RX or switch them? (Hint: Think about the semantics of TX (transmit) and RX (receive).)
3. Copy bin/pi-install.linux or bin/pi-install.macos to your local bin/pi-install. Make sure when you type pi-install something happens! If not, make sure your local bin/ directory is in your path, and that you have sourced your shell startup file.
4. Run pi-install part1/blink-pin20.bin

Your LED should be blinking.

---

4. Make sure your r/pi toolchain is working.

For this class you need to compile bare-metal r/pi programs on your computer, which is most likely not a bare-metal r/pi itself. Thus we need to set up the tools needed to cross-compile r/pi programs on your computer and to r/pi binaries.

Install the toolchain:

• For a mac use the cs107e install notes. Note: do not install the python stuff.

• For ubuntu/linux:

   sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa
   sudo apt-get update
   sudo apt-get install gcc-arm-none-eabi
  

  You may also have to add your username to the dialout group.

  If gcc can't find header files, try:

   sudo apt-get install libnewlib-arm-none-eabi
  

Compile part2/blink-pin20.s using the shell script.

1. cd part2. Run sh make.sh. We will use make frequently in the future to compile our code before sending if off to the pi. If you don't know what make does, or how a Makefile works, see the CS107E Guide to Make.
2. reset your pi: unplug the TTY-USB then plug it back in to your laptop.
3. pi-install part2/blink-pin20.bin. Should blink. If not isolate the problem by trying the blink-pin20.bin in part1/, your lab partner's, etc.