Nitrokey Storage Firmware

Firmware verification

To verify firmware flashed on device, please use the Nitrokey Storage Firmware Checksum Tool from the tools directory.

Building

Windows

Note: Tested with Windows 7

Install the following tools in this order:

1. avr32-gnu-toolchain-2.4.2-setup.exe
2. avr32studio-ide-installer-2.5.0.35-win32.win32.x86.exe
3. AvrStudio4Setup.exe
4. AVRStudio4.18SP2.exe

Linux

GUI

The compile procedure is as follows (tested on ArchLinux but should work on any other GNU/Linux OS):

1. Clone this git project (git clone https://github.com/Nitrokey/nitrokey-storage-firmware.git)
2. Download and extract AVR32 Studio. Example archive filename: avr32studio-ide-2.6.0.753-linux.gtk.x86_64.zip. At the moment no newer version seems to be available for Linux.
3. Start AVR32 Studio by executing avr32studio in the extracted folder.
4. Import project into AVR32 Studio: File | Import... | General | Existing Projects into Workspace | Choose the folder of downloaded git project.
5. Rename pm_240.h in the git project folder to pm_231.h. Make a backup of as4e-ide/plugins/com.atmel.avr.toolchains.linux.x86_64_3.0.0.201009140852/os/linux/x86_64/avr32/include/avr32/pm_231.h. Replace that pm_231.h with the renamed pm_240.h.
6. In AVR32 Studio select Project | Build All.
7. The builded file is now in the folder Debug of the git project folder.

Command Line

# setup
TOOLCHAIN_PATH=as4e-ide
T_SUBPATH=plugins/com.atmel.avr.toolchains.linux.x86_64_3.0.0.201009140852/os/linux/x86_64/avr32/include/avr32
mv $(TOOLCHAIN_PATH)/$(T_SUBPATH)/pm_231.h{,~} -v
cp pm_240.h $(TOOLCHAIN_PATH)/$(T_SUBPATH)/pm_231.h
# firmware build
cd src && make CC=path/to/avr32-gcc

Converting to .HEX file

Before flashing there may be a need to convert binary file to .hex. If it was not done automatically execute the following in Debug or Release directory:

avr-objcopy -R .eeprom -O ihex USB_MASS.elf firmware.hex

or, while in ./Debug directory:

make firmware.hex

Flashing the Firmware to Device

• Latest firmware releases
• General documentation
• Firmware upgrade instructions:
  • Windows
  • macOS
  • Linux
  • (previous documentation)

Debugging

Note: To connect an external debugger as described here, you will need a development version of the Nitrokey Storage that makes the JTAG pins available (pictured below). This version is currently not for sale. The PCB layout for the developer version can be found in the Nitrokey Storage Hardware repository, inside the dev folders.

Compatible Debuggers

This has been tested with the AVR JTAGICE XPII, however the more recent Atmel ICE and any other AVR UC3 compatible debugger should work as well.

Prepare connections

The JTAG connections on the PCB have a pitch of 1.27mm. To ease connecting and disconnecting, it is easiest to solder a pin header to the PCB and use a pin socket to quickly attach the device to the debugger. It is recommended to use the following parts for that (however any connector with a 1.27mm pitch will work):

Part	Digikey Part Number
7-pin THT Pin header, 1.27mm Pitch	S9014E-07-ND
7-pin THT Pin header, 2.54mm Pitch	S1012EC-07-ND
7-pin Socket, 1.27mm Pitch	S9008E-07-ND
1.27mm Ribbon Cable, ca. 15cm
Heatshrink

• Solder the 1.27mm Pin header to the board
• Solder the 1.27mm socket and 2.54mm header to the cable and isolate individual contacts with heatshrink

Connect Debugger interface to the Nitrokey

Use jumper wires to connect the cable from the Nitrokey to the Debugger interface connector as pictured below:

Nitrokey Side	AVR JTAG Connector Side
RST	nSRST
TCK	TCK
TDI	TDI
TDO	TDO
TMS	TMS
GND	GND
VDD	VTref

The device still needs to be powered via USB during debugging. For an initial function test, you can issue the following commands from the AVR32Studio home directory:

cd /plugins/com.atmel.avr.utilities.linux.x86_64_3.0.0.201009140848/os/linux/x86_64/bin
./avr32program --part UC3A3256S cpuinfo

if the device is connected correctly, this should yield an output similar to this:

Connected to JTAGICE mkII version 6.6, 6.6 at USB.

Device information:
Device Name                                   UC3A3256S 
Device Revision                               H
JTAG ID                                       0x7202003f
SRAM size                                     128 kB
Flash size                                    256 kB

Using the debugger in AVR32Studio

To enable the debugger, follow these steps inside the IDE:

• Enable the "AVR Targets" dialog under Window -> Show View -> AVR Targets
• Right click inside the "AVR Targets" window and select Scan Targets. Your debugger should now be shown as a target.
• Right click on the debugger entry and select Properties
• Select the "Details" tab. Under "Device", select AVR UC3A Series -> AT32UC3A3256S

The debugger should now be available. Configure the debugging environment by following these steps:

• Open Run -> Debug Configurations
• If there is no entry under AVR Application, create one by double clicking on it. Otherwise select the existing entry.
• Under "File", select Debug/USB_MASS.elf
• Under "Target" select JTAGICE mkII (or your correspondig JTAG debugger)
• Under "Erase Options" select Erase sectors
• Under "Run Options" select Reset MCU
• Apply Settings and close the dialog window

Congratulations, your IDE should now be ready for debugging. Set breakpoints as needed and start a JTAG debugging session by pressing F11.

Defaulting to USB DFU

If you accidentally erased the DFU bootloader from the chip or run into any trouble, the stick can always be reprogrammed like this:

• In the "AVR Targets" dialog, right click on your JTAG debugger and select Program Bootloader
• Leave all the entries in their default state and reprogram the bootloader by clicking Finish

The device will now start in DFU mode and can be programmed as described above in the Firmware Upgrade Instructions