Teensy 2.0 programming on Gentoo

Getting the cross-compilation toolchain for AVR configured on Gentoo to allow programming the Teensy 2.0 microcontroller..

My longest-running project to date: Make my own keyboard. The hardware involved has been through a couple of iterations, but now I’ve settled on the fairly common Teensy 2.0 as the controller. This document describes how to get the right toolchain configured on Gentoo.

Overview

1. Install the cross-compiler and required packages
2. Install teensy_loader_cli
3. Compile and load fast morse-code blinky program

Tooling on Gentoo

First we need a C compiler. To program the Teensy 2.0 we need a cross-compiler for AVR. The official documentation page only describes setting up this toolchain on Ubuntu.

On Gentoo, we have crossdevhttps://wiki.gentoo.org/wiki/Crossdev to help us out. To get an AVR cross-compiler toolchain, it’s as simple as:

$ crossdev -t avr

It also turns out we need dev-libs/libusb-compat (for <usb.h>).

Teensy loader CLI

There is a graphical utility for flashing the Teensy, but I much prefer a command-line tool, and luckily there is one we can just use: teensy_loader_cli.https://github.com/PaulStoffregen/teensy_loader_cli

Building the tool requires the <usb.h> header,⊕On Gentoo this header is provided by dev-libs/libusb-compat but that should be all that’s needed to run make successfully.

To flash the sample slow blinking program on the Teensy 2.0, plug it in, press the push button so the light stops blinking,https://www.pjrc.com/teensy/first_use.html then run:

$ ./teensy_loader_cli --mcu=TEENSY2 -v -w blink_slow_Teensy2.hex

That should be all there is to it.

Blinky

The blinky program on the pagehttps://www.pjrc.com/teensy/gcc.html (it’s provided as a zip file) provides a larger program that blinks morse code.

With avr-gcc version 13, the blinky sources do not compile out of the box. In usb_debug_only.c there is a collection of static global variables that are meant to go in read-only memory (by the __attribute__((progmem)) attribute). The error looks something like this:

error: variable ‘xyz’ must be const in order to be put into read-only section by means of ‘__attribute__((progmem))’

Adding const to these variables lets the program compile. The default settings in the Makefile target Teensy 2.0 so no further changes are necessary.

To flash blinky.hex onto our Teensy 2.0 do:

$ teensy_loader_cli --mcu=TEENSY2 -w -v blinky.hex

And off we go!

For now, the sources for my Teensy 2.0 powered keyboard live at https://git.sr.ht/~laumann/teensy-keyboard. I went down a rabbit hole ended up implementing my own loader program. It’s not as full-featured as teensy_loader_cli, but at least it does not require libusb-compat, only libusb and is POSIX C99.