Professional Documents
Culture Documents
All brand new Teensy boards come with the LED blink program pre-loaded. You should
see the Orange LED blink slowly, 1 second on, 1 second off.
If your Teensy is not brand new, it will run whatever program the previous owner
loaded, perhaps causing your computer to recognize new hardware and require drivers.
Just cancel any driver setup. In the next step you will load the LED blink program.
If your Teensy should blink but does not, please check the USB cable to make sure it is
properly connected. Your computer must be on so it provides power to the USB port. If
you still experience problems, try a different USB port or different computer.
HalfKay Bootloader Mode
Your Teensy contains 2 programs, the LED blink (user program) and the HalfKay
bootloader. HalfKay, together with the Teensy Loader software, allows you to easily
load new programs. Normally, the user program will run. To run HalfKay, press and
release the tiny pushbutton.
The LED blinking will stop, because HalfKay never lights the LED.
Your computer may briefly display a message or beep to indicate new hardware.
Windows, MacOS-X and Linux have built-in drivers that are automatically used, so you
never need to install drivers for HalfKay!
Revision History
The Teensy Loader version is shown in the About window, available from the Help
menu, or "Teensy" menu on Mac OS X.
1.15
Version number is now synchronized to Teensyduino
Improve .elf chip detection for Teensy 3.0
1.07
Support for Teensy 3.0
1.06
Fix off-screen issues with Windows multiple monitor desktops
Support for Teensyduino 0.9
1.05
Support Teensy 2.0 board
Improve .elf chip detection
Program EEPROM, if found in .elf file
1.04
Do not program when .elf file is clearly compiled for the wrong chip
Display Teensy++ image when communicating with a Teensy++ board
More careful program close, hopefully fixes crash-on-quit on Mac OS X
1.03
Wait for reboot, (hopefully) solves incorrect auto mode disable, especially on
Windows
More status reported to Teensyduino (to be used by version 0.4)
Fix memory leaks on Mac OS X
1.02
More remote control features (for Teensyduino 0.2)
Never show "stale lock" message at startup on Mac OS X and Linux
Add support for AT90USB646 chip
1.01
Add remote control support (for Teensyduino)
Add universal binary for Mac OS X
Fix drag and drop on Mac OS X
Fix filename disappearing on Linux and Windows
USB HID messages now appear in verbose info window
1.00
Initial Release
Files to download:
Teensy Loader Disk Image (3.5 megabytes, Mac OS X 10.5 and later)
LED Blink, Both Slow & Fast
When you open the disk image, it contains 1 item, the Teensy Loader application.
You may copy the Teensy Loader to your hard drive, perhaps even add it to your dock.
But it will run perfectly directly from the disk image, so just double click it.
The Teensy Loader should appear as a small window. If the Teensy board is running
the LED blink, or not connected, you should see this window.
If HalfKay is running, you should see this. If not, simply make sure your Teensy board
is connected, and press the pushbutton to run HalfKay. The Teensy Loader will quickly
recognize it.
From the File name, choose "Open HEX File" and open blink_fast.hex, which you
downloaded using the link at the top of this page. You can also open the file using the
toolbar button, or using drag-and-drop onto the upper portion of the window. When the
file is opened, the filename and percentage usage of the Teensy's memory are shown.
Select "Program" from the "Operations" menu, or click the Program button on the tool
bar. The download should be very quick, perhaps too fast to see a tiny progress bar
appear, but you should see the "Download Complete" message.
Choose "Reboot" from the "Operations" menu, or click the Reboot button on the tool
bar. Your Teensy board should immediately begin running the fast LED blink program!
To try Automatic mode, simply click the "Auto" button, or choose "Automatic Mode"
from the Operations menu. The Auto button should illuminate bright green. Then, open
the slow LED blink HEX file.
When you press the button on your Teensy board, Automatic Mode will quickly program
and reboot your board. Normally, while working on a project, you can leave the Teensy
Loader in Automatic Mode. Teensy Loader always reads the latest version of your HEX
file, so you can just compile your code, then press the pushbutton to program and run
your code.
Apple's earlier API does not seem to have any functions that can write to HID reports.
All functions only read. If you know of any way to set HID reports in Tiger's HID API,
please email paul@pjrc.com
Files to download:
Ubuntu and other modern Linux distibutions use udev to manage device files when
USB devices are added and removed. By default, udev will create a device with read-
only permission which will not allow to you download code. You must place the udev
rules file at /etc/udev/rules.d/49-teensy.rules
The file is gzip compressed, so you must extract it and then give it execute permission,
and then you may run it. Here are sample commands. Please adjust as necessary, for
example the download directory.
cd Desktop
sudo cp 49-teensy.rules /etc/udev/rules.d/
gzip -d teensy.gz
chmod 755 teensy
./teensy &
The Teensy Loader should appear as a small window. If the Teensy board is running
the LED blink, or not connected, you should see this window.
If HalfKay is running, you should see this. If not, simply make sure your Teensy board
is connected, and press the pushbutton to run HalfKay. The Teensy Loader will quickly
recognize it.
From the File name, choose "Open HEX File" and open blink_fast.hex, which you
downloaded using the link at the top of this page. You can also open the file using the
toolbar button, or using drag-and-drop onto the upper portion of the window. When the
file is opened, the filename and percentage usage of the Teensy's memory are shown.
Select "Program" from the "Operations" menu, or click the Program button on the tool
bar. The download should be very quick, perhaps too fast to see a tiny progress bar
appear, but you should see the "Download Complete" message.
Choose "Reboot" from the "Operations" menu, or click the Reboot button on the tool
bar. Your Teensy board should immediately begin running the fast LED blink program!
To try Automatic mode, simply click the "Auto" button, or choose "Automatic Mode"
from the Operations menu. The Auto button should illuminate bright green. Then, open
the slow LED blink HEX file.
When you press the button on your Teensy board, Automatic Mode will quickly program
and reboot your board. Normally, while working on a project, you can leave the Teensy
Loader in Automatic Mode. Teensy Loader always reads the latest version of your HEX
file, so you can just compile your code, then press the pushbutton to program and run
your code.
Files to download:
TEENSY.EXE is a single file application, so there is no installer required. You may copy
it anywhere on your computer.
Simply double click the application to run it. The first time it runs, Microsoft will ask you
to confirm. This window should show "PJRC.COM, LLC" as the publisher.
The Teensy Loader should appear as a small window. If the Teensy board is running
the LED blink, or not connected, you should see this window.
If HalfKay is running, you should see this. If not, simply make sure your Teensy board
is connected, and press the pushbutton to run HalfKay. The Teensy Loader will quickly
recognize it.
From the File name, choose "Open HEX File" and open blink_fast.hex, which you
downloaded using the link at the top of this page. You can also open the file using the
toolbar button, or using drag-and-drop onto the upper portion of the window. When the
file is opened, the filename and percentage usage of the Teensy's memory are shown.
Select "Program" from the "Operations" menu, or click the Program button on the tool
bar. The download should be very quick, perhaps too fast to see a tiny progress bar
appear, but you should see the "Download Complete" message.
Choose "Reboot" from the "Operations" menu, or click the Reboot button on the tool
bar. Your Teensy board should immediately begin running the fast LED blink program!
To try Automatic mode, simply click the "Auto" button, or choose "Automatic Mode"
from the Operations menu. The Auto button should illuminate bright green. Then, open
the slow LED blink HEX file.
When you press the button on your Teensy board, Automatic Mode will quickly program
and reboot your board. Normally, while working on a project, you can leave the Teensy
Loader in Automatic Mode. Teensy Loader always reads the latest version of your HEX
file, so you can just compile your code, then press the pushbutton to program and run
your code.
Files to download:
TEENSY.EXE is a single file application, so there is no installer required. You may copy
it anywhere on your computer.
Simply double click the application to run it. The first time it runs, Microsoft will ask you
to confirm. This window should show "PJRC.COM, LLC" as the publisher.
The Teensy Loader should appear as a small window. If the Teensy board is running
the LED blink, or not connected, you should see this window.
If HalfKay is running, you should see this. If not, simply make sure your Teensy board
is connected, and press the pushbutton to run HalfKay. The Teensy Loader will quickly
recognize it.
From the File name, choose "Open HEX File" and open blink_fast.hex, which you
downloaded using the link at the top of this page. You can also open the file using the
toolbar button, or using drag-and-drop onto the upper portion of the window. When the
file is opened, the filename and percentage usage of the Teensy's memory are shown.
Select "Program" from the "Operations" menu, or click the Program button on the tool
bar. The download should be very quick, perhaps too fast to see a tiny progress bar
appear, but you should see the "Download Complete" message.
Choose "Reboot" from the "Operations" menu, or click the Reboot button on the tool
bar. Your Teensy board should immediately begin running the fast LED blink program!
To try Automatic mode, simply click the "Auto" button, or choose "Automatic Mode"
from the Operations menu. The Auto button should illuminate bright green. Then, open
the slow LED blink HEX file.
When you press the button on your Teensy board, Automatic Mode will quickly program
and reboot your board. Normally, while working on a project, you can leave the Teensy
Loader in Automatic Mode. Teensy Loader always reads the latest version of your HEX
file, so you can just compile your code, then press the pushbutton to program and run
your code.
Files to download:
Version 2.0 has been tested on Ubuntu 9.04, Mac OS-X 10.5, Windows XP, FreeBSD
8.0, OpenBSD (20-Jan-2010 snapshot), and NetBSD 5.0.1. All versions of NT-based
Windows with USB support (2000 and later) are believed to work.
Caution: HEX files compiled with USB support must be compiled for the correct chip. If you load a
file built for a different chip, often it will hang while trying to initialize the on-chip USB controller
(each chip has a different PLL-based clock generator). On some PCs, this can "confuse" your
USB port and a cold reboot may be required to restore USB functionality. When a Teensy has
been programmed with such incorrect code, the reset button must be held down BEFORE the
USB cable is connected, and then released only after the USB cable is fully connected.
Optional command line parameters:
-w : Wait for device to appear. When the pushbuttons has not been pressed and
HalfKay may not be running yet, this option makes teensy_loader_cli wait. It is safe to
use this when HalfKay is already running. The hex file is read before waiting to verify it
exists, and again immediately after the device is detected.
-r : Use hard reboot if device not online. Perform a hard reset using a second
Teensy running this rebootor code, with pin C7 connected to the reset pin on your main
Teensy. While this requires using a second board, it allows a Makefile to fully automate
reprogramming your Teensy. No manual button press is required!
-s : Use sort reboot if device not online. Perform a sort reset request by searching
for any Teensy running USB Serial code built by Teensyduino. A request to reboot is
transmitted to the first device found.
-n : No reboot after programming. After programming the hex file, do not reboot.
HalfKay remains running. This option may be useful if you wish to program the code but
do not intend for it to run until the Teensy is installed inside a system with its I/O pins
connected.
OpenBSD's make is incompatible with most AVR makefiles. Use "pkg_add -r gmake",
and then compile code with "gmake all" to obtain the .hex file.
I recently had a little trouble getting the teensy cli loader working on Mac OSX 10.8. Apple moved the
location of the SDKs around, so that they now reside inside of the xcode app itself. This is the line in the
makefile that got it working for me:
SDK ?=
/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacO
SX10.8.sdk
Makefile Integration
You can use teensy_loader_cli from your Makefile, to autoamtically program your
freshly compiled code. Here is an example:
# Create final output files (.hex, .eep) from ELF output file.
%.hex: %.elf
@echo
@echo $(MSG_FLASH) $@
$(OBJCOPY) -O $(FORMAT) -R .eeprom -R .fuse -R .lock -R .signature $< $@
teensy_loader_cli -mmcu=$(MCU) -w -v $@
Make requires the white space before any command to be a tab character (not 8
spaces), so please make sure you use tab.
If you connect a second Teensy using the rebootor code, add the "-r" option and your
code will always be programmed automaticallly without having to manually press the
reset button!
Scott Bronson contributed a Makefile patch to allow "make program" to work for the
blinky example.
PlatformIO Integration
http://platformio.org
Errata
Compiling on Mac OS-X 10.6 may require adding "-mmacosx-version-min=10.5" to the
Makefile. Thanks to Morgan Sutherland for reporting this.
To compile C and C++ programs, you will need a collection of programs including avr-
gcc, the avr-libc C library and avr-binutils. Installing all the required pieces separately
can be difficult. Fortunately, there are complete, easy to install packages for all major
platforms.
Macintosh OS X
Download AVR MacPack. The MacPack disk image has an installer that does
everything for you. The following command may need to be entered (in Terminal) to
choose the version of gcc which works with Teensy.
avr-gcc-select 4
Now that you have the compiler installed, a first step is to compile the blinky source into
a .HEX file you can put onto your Teensy using the Teensy Loader. Of course, if you
skipped the previous step, you'll need to install the Teensy Loader to make use of the
.HEX file created here.
Make is a command line program that automatically runs the compiler and other related
programs to perform all the steps necessary to compile your code into the .HEX file.
Fortunately, make is very simple to use. At the command prompt, just type "make".
On Windows XP or Vista, you need to run "Command Prompt" which is in the Start
menu under All Programs -> Accessories. On Mac OS X, run Terminal, which is found
in Applications/Utilities. Linux systems have many ways to access the command line.
On all systems, the command line works in basically the same way.
The command line interface accesses a single directory, which is usually shown in the
prompt. You can type the "cd" command to change this directory. If you find typing
commands cumbersome, just take notice of which directory is used and place the
blinky files in that location. For example, in the screenshot below the directory is
"C:\Documents and Settings\me" and the files from blinky.zip were just copied to that
location.
Just type make and it will do everything and give you detailed information.
That is a lot of information! Really, the most important is what is NOT shown, any errors
that prevent make from completing the job. Normally when you run make, if you see the
size summary at the end, you've got a .HEX file and you just reach over and press the
pushbutton and (if Teensy Loader is in Auto mode) within a few seconds your freshly
compiled code starts running!
Blinky blinks messages in Morse Code on the LED, so you should see patterns of
Morse Code messages when the Blinky starts running.
The size summary is usually worth reading. In this example, "text" is 1926 bytes, "data"
is 0, and "bss" is 3 bytes. The "dec" and "hex" are just the sum of these other numbers.
So what to these names really mean?
Section Meaning
Just add the text and data numbers to get the total flash memory used. The Teensy
Loader also shows the percentage of the chip your HEX file consumes.
RAM usage is more difficult to understand. The data and bss variables are placed at
the beginning of the RAM. Local variables, function call return addresses and
temporary memory used by interrrupt routines are allocated on a stack that starts at the
highest RAM address and grows downward, towards your variables. There is no easy
way to know exactly how much memory the stack will use.
Near the beginning of the file, you will find these definitions. TARGET is the name of
your project. You may want a better name than "blinky".
# Target file name (without extension).
TARGET = blinky
SRC is the list of all your source files. There are generally 3 reasons to structure your
program into different files.
1. Related functions can be grouped into separate files, usually so you do not need
to bother seeing them as you edit other code.
2. Make detects which files have changed and only recompiles those, reducing total
compile time for incremental changes.
3. Code you download from this site and others comes as separate C files. Adding
them to your Makefile is the easiest way to use them. Especially if the C code is
updated, keeping it separate from others makes replacing the old version much
easier than if you copy-and-paste code into one giant file.
Usually each .c file will have a .h header that you use with #include in the other .c files
that will call its functions or access its variables. The "C dependencies are automatically
generated" means you to NOT need to specify the .h files and which .c files include
them. Make will examine your code and learn all those dependencies automatically.
PORTD and DDRD are the actual hardware registers that control the port D pins, and
these definitions provide easy-to-read names for the LED. See the using I/O pins
page for details.
Normally, all variables (even string constants) are placed in RAM. But there isn't much
RAM available and string constants are rather wasteful, because a copy would be in
flash anyway to initialize the RAM at startup! The PSTR macro causes the string to be
placed in flash memory. By convention, functions ending in "_P" do special operations
to read from flash instead of RAM.
Blinky's main loop is very simple. It will just blink "SOS" 6 times, then blink a long
question, and repeat forever. The _delay_ms() function is provided by the C library.
while (1) {
for (i=0; i<6; i++) {
morse("SOS");
_delay_ms(1500);
}
morse("DOES ANYBODY STILL KNOW MORSE CODE?");
_delay_ms(4000);
}
Inside the morse_character() function, which blinks a single character in Morse Code,
there are calls to usb_debug_putchar() and print(), which just calls
usb_debug_putchar().
if (c < 'A' || c > 'Z') {
print("Opps, unsupported character: ");
usb_debug_putchar(c);
print("\n");
return;
}
The HID Listen program is used to receive and display all these characters. If your
Teensy is blinking Morse Code, now is the time to install HID Listen to see these
messages.
In the previous step you compiled and loaded blinky.hex onto your Teensy board. While
it's blinking Morse Code, blinky also sends characters by calling usb_debug_putchar(),
which you can display with the HID Listen program. Other examples use these same
functions, so HID Listen is a valuable tool for "seeing" what your code is doing.
If you didn't compile blinky, you can also find a copy of blinky.hex in the source code
package here.
No driver installation is required. All major operating systems have the USB HID drivers
built in.
Macintosh OS X 10.5
Just run the hid_listen.mac program in Terminal. You may need to give the file execute
permission with the "chmod" command before you can run it.
Linux
On Ubuntu Linux, the /dev/hidraw device files are not readable by default for normal
users. You could create a custom udev rule, or simply run hid_listen with sudo.
Update, Jan 1, 2011: The 32 bit linux binary does not work on 64 bit linux systems
(2.6.32 tested), likely because of missing hidraw 32 bit ioctl support
(HIDIOCGDEVINFO, HIDIOCGVERSION, HIDIOCAPPLICATION). Future kernels may
fix this. Until then, hid_listen must be recompiled from the source to work on 64 bit
linux.
Windows XP & Vista
On Windows, simply double click the hid_listen.exe program. Windows will
automatically launch the command prompt and run hid_listen in it.