Getting Started with Tock, Teensy, and LEDs
In this first assignment, there are two objectives:
- Set up the development environment that we'll be using for
the rest of the quarter, and
- Get some lights blinking!
We hope that you'll use the second goal as a chance to express your inner
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
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
Make sure you can log into the VM: the username is
user and the
If you have issues accessing the internet from within the VM, you should
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
about what they just installed.
The virtual machine we provide contains all of the necessary prerequisites
compiling the Tock embedded operating system and programming firmware onto the
Tock is the operating system that will be running on your Teensy, and we will
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
To compile Tock, the following prerequisites are needed, which are all
on the virtual machine:
To get Tock working on the Teensy, there is additional software needed:
tock-teensy repository, which is a port of the Tock OS
to the Teensy 3.6
teensy-loader-cli, a command line tool which can upload
firmware to the
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
First, open your Virtual Machine. Then, plug your Teensy into your laptop
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
directory, and run
make app APP=examples/blink.
You should see a bunch of compilation
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.
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
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
set_pixel, which prepares the given pixel to display
particular color, and
update_strip, which actually sends the new
data to the
Write your own animation!
For next class, we expect you to write a new animation for your LED strip, by
colorwheel application as a starting point. We encourage you to
interesting and creative with this as you can, because you'll get a chance
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:
- The app must be in a subdirectory of the
- The app must have a Makefile; for most situations, you can just copy
- The app must define a main function.
In order to compile and upload your app, you run
from the top level of the
tock-teensy repository. The
relative to the
apps directory, and must not have a trailing or
Thus, to build
apps/examples/blink, the command is
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
apps folder, where the subdirectory is your name or SUID.
can be its own repository, allowing you to keep your apps under version
For example, if my SUID is
bobjones and I have written three
animations for this week's assignment, the apps directory would look
In this example,
bobjones is my repository, hosted
privately on GitHub or