VS Code/Platform IO and Lockable Teensy 4.1

milesg

Member
Is there a workflow that works with VSCode to produce/upload the encrypted EHEX file when I use the tools available with Platform IO?

I tried putting the key.pem file in various locations that I thought might work:
C:\Users\*Username*\Documents\PlatformIO\Projects\ - (Similar to sketchbook folder where it lives with the Arduino IDE)
*\Projects\MV_Controller_SureServo2\.pio\build\teensy41\ - (Where the regular hex file gets saved normally)
C:\Users\*Username*\.platformio\packages\tool-teensy - (Where the teensy.exe lives)

But I don't get an EHEX file.

Also what about the Fuse Write Sketch, Verify Sketch, and Lock Security Sketches? I can save all these out from the "Teensy 4 Security" interface, but will they be usable with multiple boards? I see that the lock sketch references a serial number, which may only work with the current board I'm testing (purely conjecture on my part here.) I know of course that I need to keep the fuse write sketch as safe and secure as my key.pem, but will it work to keep using that same sketch with different boards? I only have the one lockable teensy to play with right now, so I haven't done anything to it yet (still fully unlocked.) I just want to make sure I don't do something dumb and cause a problem with my workflow down the line.

Thanks so much!
 
I can't help with PlatformIO. But I can at least answer some of your questions....


But I don't get an EHEX file.

You could just run the "teensy_secure" program manually, with the pathname of your HEX file and your KEY.PEM file. Details on the code security page. Scroll down to "Integration with Non-Arduino Development Tools".

https://www.pjrc.com/teensy/td_code_security.html

To create the EHEX file, teensy_secure only needs your HEX file and KEY.PEM. You can just tell it the exact location of both files, so it doesn't depend on anything Arduino.


Also what about the Fuse Write Sketch, Verify Sketch, and Lock Security Sketches? I can save all these out from the "Teensy 4 Security" interface, but will they be usable with multiple boards?

Yes, that's fine. But do be careful about access to the fuse write sketch. It needs to be kept secret, same as key.pem.

Also be careful that your PlatformIO core library for Teensy is not too old, and ideally is a precise match to the copy of Arduino you have. Out of date libraries seems to be an ongoing problem on PlatformIO.

With Arduino IDE usage for EHEX, the assumption is made that the Teensy4Secure utility in Arduino is delivered by the same installer which put the core library into Arduino's internal hardware folder, so they will always match. But if you run Arduino just to use that utility to generate and save the 3 sketches, and then compile and run them using PlatformIO, you're opening up a potential liability to compile them with a different version of the core library than expected.

Might be safer to make copies of the compiled .ELF and .HEX files. You can open those with Teensy Loader and know you're using the code exactly as Arduino compiled.


I see that the lock sketch references a serial number, which may only work with the current board I'm testing

No worries about the serial number. It's merely an additional safety check, to avoid any attempt to lock boards made before code security was supported. This should be a non-issue with all PJRC manufactured boards, but the check exists just in case people who built their own custom boards with the T4 bootloader chip might accidentally run the lock sketch with hardware made before the bootloader supported code security.


I know of course that I need to keep the fuse write sketch as safe and secure as my key.pem, but will it work to keep using that same sketch with different boards?

Yes, ok to reuse it, assuming you go with the normal (and simpler) approach just 1 key.pem file for all boards you program. See the code security documentation "Firmware Cloning Between Boards" about why you might wish to use either multiple keys or some other way of writing different data to the other non-volatile fuse memory.
 
Hi Paul,
Thank you very much for your detailed answers and words of wisdom/warning about the core libraries. I will be testing all this in the next couple weeks, so I'll be sure to take your advice into consideration. I've actually manually updated the libraries/exes in my Platform IO installation to Teensy 1.57, so I think everything should be matched up nicely now.

Just to be clear: If I were to end up using .hex files which may or may not have slightly older core libraries out of my PlatformIO/VSCode project, would that cause an issue if I'm trying to create ehex files and load them on a Teensy which has been locked with the latest 3 security .hex files out of Arduino? Or is it best to just keep everything matching regardless of which might be newer?

Thanks again and sorry I didn't reply sooner. I always appreciate the expertise.
 
Here's a pull request with a first draft of PlatformIO support:
https://github.com/platformio/platform-teensy/pull/98

Here's the notes I made in the description:
1. I'm not quite sure how to use the .hex file and not the .ehex file name if `teensy_secure` fails to encrypt. While it still works because the `teensy_secure` program, when told to upload a '.ehex' file, will find the '.hex' file, I don't like how it still says `Uploading .pio/build/teensy41/firmware.ehex`.
2. I haven't tested this on Windows or Linux.
 
Hi Shawn,
I'd be happy to give it a go. I've moved on to other tasks recently as I had just been doing as Paul suggested and been running teensy_secure manually. I will try to get to it by the end of the week.

Looks like I just have to update the main.py file to the one in your pull. Just to be sure, am I to place my key.pem file in the **project**/.pio/build/teensy41 folder for this to work?

Thanks for your efforts to improve this functionality!
 
Without an argument specifying one (I should probably add that option), teensy_secure just looks in the default location that the key generator puts it. On Mac, it’s ~/Documents/Arduino/key.pem.
 
Hi Shawn,
It looks like it worked perfectly for me on Windows 10 running the latest VSCode/PlatformIO:

Code:
Building in release mode
Linking .pio\build\teensy41\firmware.elf
Checking size .pio\build\teensy41\firmware.elf
Building .pio\build\teensy41\firmware.hex
Encrypting .pio\build\teensy41\firmware.ehex
encrypting 138240 bytes to .pio\build\teensy41\firmware.ehex
Configuring upload protocol...
AVAILABLE: jlink, teensy-cli, teensy-gui
CURRENT: upload_protocol = teensy-gui
Uploading .pio\build\teensy41\firmware.ehex
Opening Teensy Loader...

The ehex code automatically loaded into teensy.exe, uploaded to the locked Teensy and worked as expected. Thanks!

I think it would be nice if it were to allow further separation from the Arduino world when working within VSCode/PlatformIO such that it would check the project dir (or perhaps elsewhere) for the key.pem file. (I guess generating the key and locking sketches is another matter that we've not addressed here.)

In my usage case, I am working with a different encryption key for 2 separate projects because each project uses the Teensy plugged into the same 'motherboard'. By using different keys, I can -for example- make sure that no one will be able to run the project A firmware on a system that was locked down for use as a project B device. I don't know if that's an atypical use or not, but having my unique key.pem files working within their own project folders would make things a lot simpler when switching between projects.

I'm happy to provide any further info/insight if needed. Thanks again for your help!
 
Thank you for trying that, and I'm glad it works!

To-dos, off the top of my head:
1. Add an option to specify a key
2. Test on Linux
3. Fall back to showing "loading .hex" instead of "loading .ehex" when the ehex generation fails —*this is a SCons thing
 
How to use lockable Teensy's with VSCode/PlatformIO

I found this thread helpful but I found no documentation on how to use lockable Teensy’s with VSCode/PlatformIO. This is what I had to do to run it on my install on macOS. I didn’t want to install the Arduino app, I’ve been happily using PlatformIO for a very long time! This first part is only relevant if you also don’t want to install the Arduino app.
  1. Download Teensyduino (The one for Arduino 1.8.x).
  2. Expand the zip, then right click on Teensyduino.app and go to Show Package Contents.
  3. Navigate to Contents > Java > hardware.
  4. Right click on ‘Tools’ and select ‘New Terminal at Folder’.
  5. In the terminal window, use the following to create a key: ./teensy_secure keygen key.pem
  6. Copy that key and put it somewhere proximate to your lockable program. Name it helpfully.
  7. Run ./teensy_secure fuseino key.pem
  8. Copy the output, paste into a new file in your project folder. I called mine fuseWriter.cpp
  9. Run ./teensy_secure lockino key.pem
  10. Copy the output, paste into a new file in your project folder. I called mine lockFuses.cpp
  11. Add #include <Arduino.h> to the top of both files.
  12. In the FuseWriter.cpp file, do the following:
  1. Remove these two lines from near the top:
    Code:
        extern const unsigned char plaintext[1024];  // random bytes
        extern const unsigned char ciphertext[1024]; // test data
  2. Move the setup() and loop() functions to beneath the defines and functions.
  3. Run ./teensy_secure testdataino key.pem
  4. Copy the output into fuseWriter.cpp, between the defines and the first function.

Someone could automate the above into one python script that generates both files, I’m sure. :cool:

You’ll need to know how to switch environments in VSCode/PlatformIO. As I recently transitioned from Atom/PlatformIO, I have to remind myself to change environment using the button at the bottom of the interface, just to the right of the terminal button.

Edit your platformio.ini to add a new environment specifically for encrypted teensy’s. Mine looks like this:

Code:
[env:teensy40]
platform = teensy
board = teensy40
framework = arduino
upload_protocol = teensy-cli

[env:lockable]
platform = https://github.com/ssilverman/platform-teensy.git#add-teensy-secure
board = teensy40
framework = arduino
upload_protocol = teensy-cli
custom_secure_key = ~/Documents/Arduino/projectName/lockable/key.pem
At the time of writing, the teensy-secure method is a pull request that hasn’t yet been merged into the develop stream. Hence the platform git shown above. Obviously change your custom_secure_key path to wherever you store yours. Drop the ~ if it’s a full path and not in your user folder.

Flashing process:
Change to env:teensy40 if it's not already. Move fuseWriter.cpp to your src folder and hit upload. If you have the serial monitor on, it’ll tell you the public and private keys do not match. Ignore this.

Remove fuseWriter.cpp from your src folder and put lockFuses.cpp in instead. Change to env:lockable. Upload. You need the serial monitor to be on for this to actually work; you’ll notice there’s a ‘while (!Serial)’ in the setup function of this program. You need to see:

Code:
Set Lockable Teensy into secure mode
Success: Secure mode set

To know it’s working.

Now you can upload your actual program or distribute it as an ehex. The terminal output will tell you if it’s found the key and the encryption is working.

Backup your key and fuseWriter.cpp files!
 
Back
Top