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:
[C:\Users\xxx\AppData\Local\Temp]dir 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.