Assignment 1: Getting Started with Tock, Teensy, and LEDs

Overview

In this first assignment, there are two objectives:

  1. Set up the development environment that we'll be using for the rest of the quarter, and
  2. Get some lights blinking!

We hope that you'll use the second goal as a chance to express your inner artistic creativity.

You will need to complete the following tasks, in order:

  • Install the virtual machine
  • Program an application onto your Teensy
  • Hook up your LED strip
  • Program your Teensy to animate the LEDs
  • Write your own animation

Installing the Virtual Machine

To simplify the process of installing dependencies, we have a virtual machine with the prerequisite software installed.

First, download and install VirtualBox.

Once VirtualBox is installed, download the Linux image from here. Save the file on your computer, and then in VirtualBox, import the image by going to File->Import Appliance. For help with this step, you can refer to this documentation.

Make sure you can log into the VM: the username is user and the password is user.

If you have issues accessing the internet from within the VM, you should pause or stop the VM, and go to Settings->Network. Check Enable Network Adapter and choose Attached to: NAT from the dropdown. Under Advanced, make sure you check Cable Connected.

What's on the VM

NOTE: Reading this section is purely optional, it's just here for the people curious about what they just installed.

The virtual machine we provide contains all of the necessary prerequisites for compiling the Tock embedded operating system and programming firmware onto the Teensy.

Tock is the operating system that will be running on your Teensy, and we will be talking about it in more detail during the quarter. The Tock homepage is a great way to learn more about this open source operating system and its design philosophy.

To compile Tock, the following prerequisites are needed, which are all provided on the virtual machine:

To get Tock working on the Teensy, there is additional software needed:

  • The tock-teensy repository, which is a port of the Tock OS to the Teensy 3.6 hardware
  • teensy-loader-cli, a command line tool which can upload firmware to the Teensy

Program your first application

To verify that your development environment is set up correctly, you are going to compile, upload, and run a simple blink application on your Teensy.

First, open your Virtual Machine. Then, plug your Teensy into your laptop with the micro-USB cable. The VM is configured to automatically detect the Teensy when it is plugged into your computer--there should be no need to select it from the Devices menu.

In the VM, open Terminal, navigate to your tock-teensy directory, and run

make app APP=examples/blink.

You should see a bunch of compilation output, and then a prompt telling you to push the reset button on your Teensy. When you see this prompt, press the button on your Teensy, and the terminal should indicate that the board has programmed and booted.

If everything worked, you should see the orange LED on your Teensy blinking. Do not go on to the next step until this works! If you run into trouble, contact the teaching staff, and we'll help fix any installation issues.

Setting up the LED strip

If you made it this far, it means you have successfully installed everything, and you're ready to start messing with your LED strip!

[TODO: explanation and pictures of LED hookup]

Program an animation

Once you have your LEDs hooked up correctly, you can test to make sure they work by running

make app APP=examples/dotstar/colorwheel.

This will reprogram your Teensy, and you should see your full LED strip running a simple animation.

Take some time to look over the code in apps/examples/dotstar/colorwheel/main.c. The important functions are set_pixel, which prepares the given pixel to display a particular color, and update_strip, which actually sends the new data to the strip.

Write your own animation!

For next class, we expect you to write a new animation for your LED strip, by using the colorwheel application as a starting point. We encourage you to get as interesting and creative with this as you can, because you'll get a chance to show off your animations in class!

An Aside: Writing New Tock Apps

As an embedded operating system, Tock itself has a fairly complicated build system. However, luckily, to write userspace applications, there is very little that needs to be done. Every Tock app has a few requirements in order to build and run successfully:

  1. The app must be in a subdirectory of the apps folder
  2. The app must have a Makefile; for most situations, you can just copy apps/examples/blink/Makefile.
  3. The app must define a main function.

In order to compile and upload your app, you run

make app APP=path/to/your/app

from the top level of the tock-teensy repository. The path/to/your/app is relative to the apps directory, and must not have a trailing or leading slash. Thus, to build apps/examples/blink, the command is

make app APP=examples/blink.

As the quarter goes on, you will likely want to keep your apps under version control. The best way to do this is by keeping all of your apps in a subdirectory of the apps folder, where the subdirectory is your name or SUID. This subdirectory can be its own repository, allowing you to keep your apps under version control.

For example, if my SUID is bobjones and I have written three different animations for this week's assignment, the apps directory would look like:

apps/
    bobjones/
            animation1/
                        Makefile
                        main.c
            animation2/
                        Makefile
                        main.c
            animation3/
                        Makefile
                        main.c
    examples/
            ...

In this example, bobjones is my repository, hosted privately on GitHub or BitBucket.