Upgrading Teensy Code in the Field

I’ve got a few Teensy projects in ‘production’ now and I know I’m going to have to update the software onsite. In fact, I need to be prepared to allow an end-user to upgrade the software as one Teensy that is located 1000’s of miles away now.

In the back of my head I figured this must not be too hard since the Teensy has a nice windows based programmer. Sure enough, it is slam dunk. Well, pretty close.

This procedure assumes that the necessary files will be gathered together, sent to a remote site, and a reasonably technical user there will be responsible for doing the install (not necessarily someone familiar with programming arduinos, but one able to do normal PC maintenance).

Put Together the Files

To update a Teensy in the field, you are going to need the Windows serial installer, the Teensy programmer application, and the binary code for your own program which consists of a .HEX file and a .ELF file.

On the Teensy download website, https://www.pjrc.com/teensy/td_download.html, you will find the Windows Serial Installer, get a copy of it to install on the PC that will handle the update.

The programmer is called teensy.exe and can be found in <ardinuoDir>\hardware\tools. Here is its location on one of my development systems:

[C:\]dir \arduino-sj\hardware\tools

 Volume in drive C is c140527        Serial number is D467:78F2
 Directory of  C:\arduino-sj\hardware\tools\*

 5/03/2016  14:50         <DIR>    .
 5/03/2016  14:50         <DIR>    ..
 5/03/2016  14:50         <DIR>    arm
 5/03/2016  14:51         <DIR>    avr
 2/06/2016  17:25               0  .keep
 2/06/2016  17:25          45,608  listComPorts.exe
 3/10/2016  22:09          33,448  mktinyfat.exe
 3/10/2016  22:09       2,486,456  teensy.exe
 3/10/2016  22:09          24,744  teensy_gateway.exe
 3/10/2016  22:09          26,280  teensy_post_compile.exe
 3/10/2016  22:09          28,328  teensy_reboot.exe
 3/10/2016  22:09          21,672  teensy_restart.exe

Now you need the binary code for your own program.

  • Start the arduino IDE (which has Teensy support).
  • Do a Verify/Compile (ctl-R) to create the hex file of your code.
  • The hex file is created in the temp directory for your user. For windows 7 (at least for my installation), this is in c:\users\<username>\appdata\local\temp.
  • In the temp directory you should find a directory starting with the word build:

 Volume in drive C is c140527        Serial number is D467:78F2
 Directory of  C:\Users\xxx\AppData\Local\Temp\*

 6/06/2016  15:28         <DIR>    .
 6/06/2016  15:28         <DIR>    ..
 6/06/2016  15:24         <DIR>    build1e37ea4638dee8a2fbba645dea41b283.tmp
 6/06/2016  15:23         <DIR>    hsperfdata
 6/06/2016  15:23         <DIR>    jna-3075831
 5/27/2014  21:40               0  FXSAPIDebugLogFile.txt
              0 bytes in 1 file and 5 dirs    0 bytes allocated
153,325,252,608 bytes free

  • Go into this directory and you will find the hex file (if there is more than one build directory, the one with the most recent date is probably the correct one):
 6/06/2016  15:24         <DIR>    .
 6/06/2016  15:24         <DIR>    ..
 6/06/2016  15:24         <DIR>    core
 6/06/2016  15:23         <DIR>    libraries
 6/06/2016  15:23         <DIR>    preproc
 6/06/2016  15:23         <DIR>    sketch
 6/06/2016  15:23             661  build.options.json
 6/06/2016  15:24              13  test.ino.eep
 6/06/2016  15:24         790,716  test.ino.elf
 6/06/2016  15:24         226,676  test.ino.hex
  • If you cannot find the file search for <project>.ino.hex. I prefer to do this in the cmd box as windows 7 search only finds files I KNOW exist about 1/2 the time:
dir \users\xxx\appdata\Local\*.hex /s
  • Once you have located the .HEX file, the .ELF file will be in the same directory. You will need it as well.
  • Now I have all the files ready to take to the Teensy to be updated:
 6/06/2016  16:09         117,936  serial_install.exe
 6/06/2016  15:54       2,486,456  teensy.exe
 6/06/2016  15:24         790,716  test.ino.elf
 6/06/2016  15:53         226,676  test.ino.hex

Install Serial Driver

Once ready to update, Install the Serial Driver First!

Assuming the PC used to to the upgrade doesn’t already have the Arduino/Teensy software installed, we are going to install just the files necessary to perform the update.

Right click on the serial_install.exe file and run as Admin to let it install the virtual serial driver.

Connect to the Teensy

  • Plug the Teensy into the PC’s USB port.
  • Windows should see the device and start looking for drivers. Skip searching the internet for the update.
  • Once the driver is installed, there is no indication I can find that device manager sees the Teensy (it won’t update the serial port list). But you should still hear the sound effect when you unplug/plug the teensy in.

Update the Code

  • Start the Teensy.exe program
  • Click on Help | Verbose – You will see a screen which will indicate the program is ‘listening for remote control’.
  • In Teensy.exe, do a file | open and open the HEX file. The log indicates the file has been opened.
  • Press the ‘Auto’ button in teensy.exe.
  • Press the reset button on the Teensy.
  • You should see messages in the log indicating the download and reboot were successful:
16:55:40: Board is: Teensy 3.2 (MK20DX256), version 1.03
16:55:40: File "test.ino.hex". 80576 bytes, 31% used
16:55:40: File "test.ino.hex". 80576 bytes, 31% used
16:55:40: elf size appears to be 262144
16:55:40: elf binary data matches hex file
16:55:40: Code size from .elf file = 262144
16:55:40: begin operation
16:55:40: flash, block=0, bs=1024, auto=1
16:55:40: flash, block=1, bs=1024, auto=1
16:55:40: flash, block=2, bs=1024, auto=1
16:55:41: flash, block=76, bs=1024, auto=1
16:55:41: flash, block=77, bs=1024, auto=1
16:55:41: flash, block=78, bs=1024, auto=1
16:55:41: sending reboot
16:55:41: begin wait_until_offline
16:55:41: offline, waited 2
16:55:41: end operation
16:55:41: redraw timer set, image 14 to show for 1200 ms
16:55:41: HID/win32:  vid:05A4 pid:9881 ver:0120
16:55:41: HID/win32:  vid:05A4 pid:9881 ver:0120
16:55:42: redraw, image 9

Maintaining Executable Code

Once I had this process working, it became evident I no longer have to recompile programs every time I want to use them.

This is most helpful on my current project. There are quite a few hardware subsystems involved. After I build a new PCB, I want to make sure all of the hardware is fully functional, so I have a hardware test suite I use.

I can now download and execute the hardware test suite w/o compiling. Once the hardware is tested, I can then download and execute the stable version of the software without having to go back to the source and recompile it.


Nov 2016 Update:

Periodically, I have an issue getting this process to work. When I do a file | open in teensy.exe and specify the HEX file, I will get an error indicating file too large.

It seems teensy.exe defaults to an older model of teensy with less program space. Supposedly if you have both the HEX and ELF files available this isn’t supposed to be an issue, but sometimes it is.

It seems that if I build the HEX file by doing a sketch | upload this problem will not occur. But sometimes I don’t want to upload the version I’m compiling to the teensy that I have connected so I do a sketch | compile. I don’t know why that would make a difference, but so far my observations have been it does.

What to do when this happens? Today I seem to have stumbled across a solution. I have not been able to replicate the failure so I’m not 100% I got the correction sequence right:

  • After doing the file | load, you see the file too large error in Teensy.exe.
  • Double click on teensy_reboot.exe – this will upload the file anyway.
  • Then double click on teensy_restart.exe – this will restart the teensy.


This entry was posted in c-teensy and tagged . Bookmark the permalink.

4 Responses to Upgrading Teensy Code in the Field

  1. Andreas says:

    Great write up. I’ve gone through the same recently.
    There are a couple of notes to add. The hex file can be exported from within the Arduino menus. Saves you hunting down the temp file.
    Another point is the button. My customer can’t access the teensy button so the download needs to work without.

    With these two commands the programming can be automated without the need of the button

    teensy_post_compile.exe -file=my_hex_file -path=c:\mypath_for_hex_file -tools=c:\location_where_teensy is.
    See here too

    • Dan TheMan says:

      Thanks for the comments, Andreas. At the moment I’m using a sandwich case and the button can be pressed albeit clumsily. I’ve been wondering how I would deal with the problem once I start using a fully enclosed case.

  2. Bruce Boyes says:

    Have you considered TyQt? I have been using it for remote code uploads at a customer site. It does several things which the Teensy loader does not: you can send Teensy a serial data file, which we use to load configuration data into a local FRAM on our board. You can find TyQt at https://github.com/Koromix/ty

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s