Elastic Sheep

Because elasticdog was already taken

Elastic Sheep header image 2

Installing the LUFA TeensyHID bootloader

January 5th, 2010 · 48 Comments · Uncategorized

The LUFA project contains the TeensyHID bootloader that can be used as a replacement of the original HalfKay bootloader preloaded on the Teensy boards.

It can be useful if like me you have completely erased the original flash with an external programmer. Because the HalfKay bootloader is proprietary code and is protected by lock bits, you can not read it from another board. In this case the TeensyHID is the only alternative to restore a bootloader compatible with the Teensy loader tools.

Compiling the bootloader

I am using the LUFA 091223.zip release. The TeensyHID project can be found in the Bootloaders/TeensyHID subdirectory.

To compile it for a Teensy 1.0 based on the AT90USB162 I make the following changes in the provided Makefile:

MCU = at90usb162 #atmega32u4
BOOT_START = 0x3800 #0x7000
AVRDUDE_PROGRAMMER = avrispmkii #jtagmkII

The value of BOOT_START is the starting address for a 2048 bytes bootloader (cf AT90USB162 datasheet, 23.7.14, p. 239).

I can check in the build output that the binary can fit in the 2048 bytes limit:

# make
Program:    2002 bytes (12.2% Full)
(.text + .data + .bootloader)

Data:         84 bytes (16.4% Full)
(.data + .bss + .noinit)

Setting the boot size fuse bits

Two BOOTSZ fuse bits in the Fuse High Byte tell the MCU where the start address of the bootloader is (cf AT90USB162 datasheet, 25.2 Fuse bits, p. 245).

To read the hfuse:

# avrdude -p at90usb162 -P usb -c avrispmkii -U hfuse:r:-:h -v
avrdude: writing output file ""

avrdude: safemode: lfuse reads as DF
avrdude: safemode: hfuse reads as DF
avrdude: safemode: efuse reads as F0
avrdude: safemode: Fuses OK

The Teensy factory hfuse value is 0xDF. It tells us that HalfKay is a 512 bytes bootloader that starts at address 0x1E00.

The hfuse value for the TeensyHID bootloader will be 0xDB (BOOTSZ1 = 0, BOOTSZ0 = 1).

To write the hfuse:

# avrdude -p at90usb162 -P usb -c avrispmkii -U hfuse:w:0xdb:m -v
avrdude: verifying ...
avrdude: 1 bytes of hfuse verified

avrdude: safemode: lfuse reads as DF
avrdude: safemode: hfuse reads as DB
avrdude: safemode: efuse reads as F0
avrdude: safemode: Fuses OK

Now I can program the bootloader and test it:

# make program

Testing the bootloader

The Teensy loader application is available on the Teensy home page with two blinking-led test binaries, blink_slow.hex and blink_fast.hex.

Teensy mac loader - Push the button to activate

To execute the bootloader, you have to press and release the pushbutton on the Teensy. The bootloader starts and is enumerated as a USB device and the loader application display changes:

Teensy mac loader - ready for HEX download

You can now load an HEX file and transfer it on the Teensy target. You may need to unplug the Teensy to reboot it. The reboot feature of the loader does not seem to be implemented.

Compiled binary [added 2010-09-04]

I patched the TeensyHID source code with the Teensy 1.0 HID. The board is now correctly recognized as a Teensy 1.0/AT90USB162 one by the Teensy Loader 1.05.
TeensyHID.hex [AT90USB162 / Patched LUFA091223 HID]

Compiled binary [added 2011-01-06]

Here is the patched TeensyHID binary compiled for an 8MHz AT90USB162 board. Not tested since I don’t own corresponding hardware.
TeensyHID_8MHz.hex [AT90USB162 8MHz / Patched LUFA091223 HID]

Tags: ····

48 Comments so far ↓

  • Dean Camera

    Interesting — are you saying the latest LUFA demo works correctly on the original at90usb162 based Teensy board? I had some issues recently with making the code compatible with the PJRC GUI, due to Paul changing a few of the magic numbers needed for it to recognize it. However, I thought this was done because of the jump to the atmega32u4 based Teensy 2.0.

    This seems to suggest that Paul made the changes to screw with my firmware, rather than for compatibility reasons between versions.

    - Dean

  • Aos.Silver

    Hello ,
    Can i have the .hex file for the bootloader ,because i erase this on my teensy++ and i don’t say how to compile the source .

    thank you

    (sorry for my english , i’m french)

  • Dave

    Is there a pre-compiled hex for teensy with at90usb162 ?
    I got a problem to compile it under winavr.

    Thanks a lot

  • The Chief Sheep


    It seems the last version of the Teensy Loader GUI is not compatible anymore with the TeensyHID application on the AT90USB162.

    I checked yesterday and the Teensy Loader (1.05) tells me my board is a Teensy 2 instead of a Teensy 1.

    I have added the TeensyHID hex binary in my post but it may work only with older version of the Teensy Loader…

  • The Chief Sheep

    I have patched the TeensyHID source code. The Teensy Loader now correctly recognize the board and I am able to program it.

    Not sure the binary I provided you with is working. I don’t have a Teensy++ so I don’t know the correct HID for this model.

  • Dave

    There is no possibility to make it in linux either ….

    make says : No rule to make target ‘teensyhid.elf’ needed by elf Stop !!!!!

  • Dave

    Can you provide older teensy loader or can you compile new patched version for us.

    Thanks a lot

  • Dave

    Sorry, i didn`t notice you already did :) )))

    BIG Thanks !!!!!!!!!!!!!!!!!!!!!!!!!!!

  • Waiman

    Hello, I have a AT90USB162 board, but the MCU work 8Mhz / 3.3V, but you provide TeensyHID HEX can not run on my board, may be different frequencies.

    Will TeensyHID need to be modified to allow Teensy loader correctly identify? I want to change TeensyHID source code and compile it to run in the 8MHz.

  • 3dotter

    Hi, I have the same question. Can this TeensyHID.hex file be used on the at90usb162 running at 3.3 V / 8 Mhz?

  • JC

    Anyone as the Loader in v1.04??
    Please…. :)

  • The Chief Sheep

    @Waiman, @3dotter

    To compile TeensyHID.hex for an 8MHz at90usb162 board, you have to change the F_CPU value in the TeensyHID directory makefile.

    F_CPU = 8000000 # Old value: 16000000

    I will compile a TeensyHID.hex with the modified HID as soon as I have access to my main computer.

    Update: new binary TeensyHID_8MHz added.


  • 3dotter

    Thanks for compiling the new binary with 8MHz! Question 1: Can it be used with internal clock on the at90usb162?
    Question 2. The atmega32u2 appears to be a good replacement for the at90usb162. Which values need to be changed in the makefile or can the present compiled TeensyHID_8MHz.hex be used?

  • The Chief Sheep


    For Q1, considering the figure 6.2 in the at90usb162 datasheet, it looks like the internal RC oscillator could be used as a clock source for the USB PLL. But the RC oscillator is much less precise than a crystal (8MHz +-10% at 25°C) and the USB PLL will amplify the error. I don’t know if this is acceptable for the USB spec (but if Atmel has planned for the use case, why not ?).

    The TeensyHID binary configured for a 8MHz crystal could be used without modification. You just need to configure the fuse bits CLKSEL3..0 to select the RC oscillator as the boot clock source (default value is to use external oscillator)

    For Q2, I don’t think the at90usb162 and the atmega32u2 are binary compatible at the register level. The MCU value should be changed in the TeensyHID makefile.


  • Pablo

    could i use the TeensyHID with my OpenKubus at90usb162 atmega16u4? it seems to be the same as atmega32u4 just a flash of 16kb.

  • SteveC

    Could someone help me load this onto a board please? Flip keeps giving me an address range error.

    Can this be programmed through the Flip tools or does it require a hardware programmer?

    Thanks folks.


  • The Chief Sheep


    The OpenKubus V2 hardware is based on an ATMEGA16U4.
    I think you could directly compile TeensyHID from LUFA 091223 with just a modification of the MCU and of the BOOT_START value in the project makefile.


    I don’t think you can upload a bootloader on a board with the FLIP tools. FLIP is itself a bootloader and I am not sure it can write on itself. Using an AVR programmer may be the only solution…

  • SteveC

    Thanks for the feedback :)

    Sooo, if the HalfKay is running does this mean that you cannot use Flip to program devices? i.e. is it an either/or, or can both be running?

    Do you know if there is/was a reason for HalfKay rather than simply using Flip?

    Looking forward to trying this out. Thanks for your time working on it.


  • The Chief Sheep

    Hi Steve,

    Some clarifications:
    - HalfKay is the bootloader included in the Teensy boards. It works with the Teensy Loader application.
    - With virgin USB AVR chips, Atmel includes a DFU bootloader. This bootloader works with the FLIP tools.
    The FLIP tools are not compatible with the HalfKay protocol. Same for Teensy Loader with the DFU protocol.

    The HalfKay bootloader advantage is its small size. It can fit in 512 bytes as its name implied. On the other hand, the Atmel DFU bootloader requires 2048 bytes of Flash. It is an important point for a small Flash device like the AT90USB82, less so for bigger Flash devices.


  • SteveC

    Excellent. Thanks for the clarification.

    I really appreciate your time helping me better understand this.

    So, If the HalfKay loader is loaded then there will be more user program space available I guess (1.5K more)?

    Do you know if the Atmel DFU loader is available to re-load if one decides to go back to the Flip tools?

    Again, I really appreciate you taking the time to help me.


  • The Chief Sheep

    Yes, the HalfKay bootloader is really useful if you are memory constrained. But it is only available inside new Teensy board and once you have erase it (like I did), you can not get it again unless you buy it in someway from PJRC.

    I though the Atmel DFU would be available to download but it does not seem to be the case either. Only the protocol is published [www.atmel.com/dyn/resources/prod_documents/doc7618.pdf].

    The only remaining solution to use the Flip tools would be to compile the DFU bootloader available in the LUFA project.

  • SteveC

    Thanks for the info. This is a great help :)


  • Lutz


    I used DFU programmer to download the TeensyHID to a virgin AT90USB162 stick:

    sh-3.2# dfu-programmer at90usb162 get
    Bootloader Version: 0×05 (5)
    sh-3.2# dfu-programmer at90usb162 flash TeensyHID.hex
    Bootloader and code overlap.
    Use –suppress-bootloader-mem to ignore
    sh-3.2# dfu-programmer at90usb162 flash TeensyHID.hex –suppress-bootloader-mem
    2002 bytes used (16.29%)
    sh-3.2# dfu-programmer at90usb162 get
    Bootloader Version: 0×05 (5)
    sh-3.2# dfu-programmer at90usb162 start
    sh-3.2# dfu-programmer at90usb162 get
    Bootloader Version: 0×05 (5)
    sh-3.2# dfu-programmer at90usb162 erase
    sh-3.2# dfu-programmer at90usb162 flash blink_slow.hex
    54 bytes used (0.44%)
    sh-3.2# dfu-programmer at90usb162 start

    but the Teensy loader would not do anything and the original Atmel bootloader seems still to be there. Or did I miss anything?


  • The Chief Sheep

    Hi Lutz,
    I don’t think the DFU programmer is able to overwrite the original Atmel Bootloader.
    It returns you the error “Bootloader and code overlap” because the Flash location of the TeensyHID.hex is the same as the original bootloader.

    The option -suppress-bootloader-mem only tells the programmer to ignore Flash writes in the bootloader area. So with this option, nothing is written in the at90usb162 Flash.

    Your only option to flash a bootloader is to use an external AVR ISP programmer.


  • Lutz

    Hi Mathieu,

    makes sense. Thank you!

  • stevey


    Does anyone have teensy.exe v1.05 (XP)
    or where it can be found.


  • SteveC

    Thanks for all your help in the past, and I hate to keep bugging you, but I need your help again please.

    I built a serial programmer based on the Olimex serial programmer and use PonyProg v2.07c to program my AT90USB162 but when I connect the board through USB I now get USB device not recognized.

    Now, when I try to program the device with PonyProg it does give me an alert stating “device missing or unknown device”, but if I ignore then the programming and verification seems to go fine. I can verify the device afterwards and it passes.

    I have done a readback of the program memory and diffed it against the original file from you and the only differences start at line 121 in the hex file, corresponding to address 0x3f80 onwards.

    Any thoughts or ideas?

    Thanks again for your time. I really do appreciate it.

  • SteveC

    Just to add…

    I also tried with an 8MHz crystal and the 8MHz version and get the same result… device not recognized.



  • Humberto Sales

    SteveC, I am same problem.
    I bought the fake Teensy from DealExtreme.com and compiled my code for Teensy 2, however the board of dealextreme is teensy 1.0.
    Now the PC isn’t recognizing the device and I can’t install new Bootloader.

    Please, help!

    thank you

  • Stewie

    Thank you VERY much. Saved my teensy. Like some of the others above me, from dealextreme.com.

  • Mauro Martins

    Stewie, how you saved your Teensy from dealextreme ? Can you explain with more details ?

    Thank you!

  • shell


    i got the newest dfu version (LUFA 111009) The are 3 folders in bootloader (cdc, dfu and and hid). Which one do i need to built?

  • Skvozniak

    @The Chief Sheep
    I loaded hex file you provided with teensy loader 1.05 . But after this the board still recognized as teensy 2.0 buy teensy loader. Do i do something wrong?

  • Skvozniak

    …..*by teensy loader

  • Skvozniak

    @Humberto Sales
    from http://www.pjrc.com/teensy/loader_cli.html

    “…If you load a file built for a different chip, often it will hang while trying to initialize the on-chip USB controller ….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.”

    Compile you code in arduino for teensy 1.0
    and load it with a command line teensy loader

    don’t forget to press the botton before loading

  • Ironaxe


    would it be possible to compile this Teensy compatible Bootloader for a AT90USBKEY ( AT90USB1287 ) to be compatible with the Teensy Loader ? ( Especially to be recognised as Teensy++ 2.0 )
    Would be a great help.
    I tried myself but having problems to compile the BL.


  • Willie

    I need to translate the the Teensy Loader application to run on Android…… in an attempt to assure myself that I am not re-inventing the wheel ( which I often seem to do ) I would ask if anyone has already done this …. if no I will in the next couple months do this….. I will post it on my app market for others to use…. details to come


  • The Chief Sheep

    Interesting idea. It could ease the use of the Teensy as an Android peripheral…

  • Willie

    I think that with the evolution of Android Tablets that have USB ports this might be a useful tool for some….

    Is there any addition data available on the USB commands used by Teensey ? ( obviously with the Lufa Loader code I can figure it out )

    Shouldn’t be hard ,,, just need to find the time… and obviously I will share it when I am done

    Will sargentw@gmail.com

  • The Chief Sheep

    You can find information about the Teensy HalfKay bootloader protocol on this page: http://www.pjrc.com/teensy/halfkay_protocol.html.

    The source code of a command-line C version loader is also available here:


  • Willie

    goodness ! that makes it easy…. thx

  • Konsgn

    I am trying to get the Lufa bootloader working with teensyloader for a Teensy2.0 and I’m stuck. I have been working with the latest LUFA HID Bootloader (LUFA-120219, the HID bootloader matches the Halfkay communication protocol) and modified the vendor and product id to match halfkay. After those modifications nothing happened but then I modified the Vendor page to 0xFF9c and Vendor Usage to 0×19 and was able to get the following results from looking at the Hardware ID’s:


    This (in particular the HID Device Up line) match the image from the teensy website in checking halfkay on vista. After doing this, I was able to get my board recognized as a Teensy 1.0 rather than a Teensy 2.0 by the latest teensy loader.

    Could someone with an unmodified Teensy2.0 let me know what the HID_DEVICE_UP: line reads when they check their teensy hardware id’s? I believe that with the proper Vendor page and usage it will be recognized correctly.

    Hey! The max limit for the bootloader on these chips is 2048 WORDS. Each word in the chips is actually 16bits therefore the byte limit is 4096 not 2048. In fact, I couldn’t get the HID bootloader for the atmega32u4 to a size smaller than 2068 bytes and it still fit in the bootsection of 2048 words.


  • Konsgn

    Edit: Scratch that last part, I misread what the post was saying, keeping the bootloader smaller than 2048 bytes is a good idea so that you won’t have to use the largest size bootloader section. My bad.

  • Prashanth

    Hi Chief,
    I wanted to know is it possible to programme at90usb162 with DFU-Programmer if I flash the micro-controller with teensy bootloader,
    Prashanth. G

  • The Chief Sheep

    Hi Prashanth,
    The Teensy bootloader is only compatible with the Teensy loader application from PJRC. You will not be able to use it with a DFU programmer.
    But the LUFA library also contains a DFU-compatible bootloader that you should be able to use.

  • YBK

    Konstanatin said that latest LUFA (LUFA-120219) worked for him on a Teensy2.0, but I can’t get it to work on Teensy++2.0. Compile and load works fine but I see no USB device when connected. All my own programs worked fine loaded via the same ISP method.

  • konsgn


    Yea sorry about that, There are a few modifications I had to do to the default distribution to get it to work properly. I don’t have it in front of me but I think that I needed to add a section of the code that checks the reset register and makes the code stay in bootloader mode if the reset button was pressed. Also, the latest teensyloader 1.06 somehow requests data from the teensy 2.0 in order to check if its the proprietary bootloader.(although I think the security check is not implemented in the teensy2.0++) I got around the problem by using the teensyloader 1.05 release. But you could also use the teensyloadercli command line program to get the bootloader working properly.

  • Ciro

    Yeah! It works. Wonderful… I made a teensy 1 board and it worked! Teensy loader recognized my board and loaded .hex file. The only difference with the original Halfkey is that, every time you load a .hex file, it replaces the bootloader and next time you connect it to usb the teensy loader wont recognize your board. So the bootloader needs to be burned into MCU with ISP programmer using AVRDUDE again. Thank you for sharing your work.

Leave a Comment